Merge branch 'master' into master

README.md

@@ -10,19 +10,15 @@ Use **QISKit** to create quantum computing programs, compile them, and execute t
 
 Links to Sections:
 
-* [Installation and setup](#installation-and-setup)
-* [Getting Started](#getting-started)
-* [Quantum Chips](quantum-hips)
+* [Installation](#installation-and-setup)
+* [Creating your first Quantum Program](#getting-started)
 * [More Information](#more-information)
-* [FAQ](#FAQ)
 * [License](#license)
 
 # Installation and setup
 ## Dependencies
 
-To use QISKit Python version you'll need to have installed [Python 3 or later](https://www.python.org/downloads/) and [Jupyter Notebooks](https://jupyter.readthedocs.io/en/latest/install.html) (recommended to interact with tutorials). 
-
-For this reason we recomend to use [Anaconda 3](https://www.continuum.io/downloads) python distribution for install all of this dependencies.
+To use QISKit Python version you'll need to have installed [Python 3 or later](https://www.python.org/downloads/) and [Jupyter Notebooks](https://jupyter.readthedocs.io/en/latest/install.html) (recommended to interact with tutorials). For this reason we recomend to use [Anaconda 3](https://www.continuum.io/downloads) python distribution, install all of this dependencies for you.
 
 In addition, a basic understanding of quantum information is very helpful when interacting with QISKit. If you're new to quantum, Start with our [User Guides](https://github.com/QISKit/ibmqx-user-guides)!
 
@@ -40,24 +36,24 @@ The fast way to install QISKit is using PIP tool (Python package manager):
 
 ### Source Installation 
 
-Other common option is clone the QISKit SDK repository and navigate to its folder on your local machine:
+And alternative method is clone the QISKit SDK repository and navigate to its folder on your local machine:
 
 #### Download the code 
 
 Select the "Clone or download" button at the top of this webpage (or from URL shown in the git clone command), unzip the file if needed, and navigate to **qiskit-sdk-py folder** in a terminal window.
 
 #### Clone the repository 
 
-Alternatively, if you have Git installed, run the following commands:
+If you have Git installed, run the following commands:
 ```
     git clone https://github.com/QISKit/qiskit-sdk-py
     cd qiskit-sdk-py
 ```
 #### Setup you enviroment
 
-We recomend that you use python Virtual enviroments to improve your experience. You can get more info about it in: [Setup the environment](doc/install.rst#3.1-Setup-the-environment)
+We recomend that you use python virtual enviroments to improve your experience. [Setup the environment](doc/install.rst#3.1-Setup-the-environment)
 
-## Getting Started
+## Creating your first Quantum Program
 
 Now that the SDK is installed, it's time to begin working with QISKit. First, get your API token:
 
@@ -66,9 +62,7 @@ Now that the SDK is installed, it's time to begin working with QISKit. First, ge
 
 This API token allows to you to execute your programs in the IBM Quantum Experience backends.
 
-After, try out some example QASM, which runs via the local simulator or the online simulator or [real Quantum Chips](#quantum-chips).
-
-### Creating your first Quantum Program 
+After, try out some example QASM, which runs via the local simulator.
 
 This is a simple superpesition example.
 
@@ -115,32 +109,18 @@ COMPLETED
 {'00': 509, '11': 515} 
 ```
 
-The basic concept of our quantum program is an array of quantum
-circuits. The program workflow consists of three stages: Build, Compile, and Run. Build allows you to make different quantum circuits that represent the problem you are solving; Compile allows you to rewrite them to run on different backends (simulators/real chips of different quantum volumes, sizes, fidelity, etc); and Run launches the jobs. After the jobs have been run, the data is collected. There are methods for putting this data together, depending on the program. This either gives you the answer you wanted or allows you to make a better program for the
-next instance.
-
-You can get more details in [doc/qiskit.rst](doc/qiskit.rst).
-
-### Quantum Chips
-If you want to execute your Quantum circuit in a real Chip, you can use the IBM Quantum Experience (QX) cloud platform. Currently through QX you can use the following chips:
 
--   ibmqx2: [5-qubit backend](https://ibm.biz/qiskit-ibmqx2)
-
--   ibmqx3: [16-qubit backend](https://ibm.biz/qiskit-ibmqx3)
-
-more information about the [IBM Q experience backend information](https://github.com/QISKit/ibmqx-backend-information)
+You can execute your code in a [real Quantum Chips](https://github.com/QISKit/ibmqx-backend-information).
 
+More details in [the Qiskit documentation](doc/qiskit.rst).
 
 ### Next Steps
 
-You can review the QISKit documentation 
-
-Now you're set up and ready to check out some of our other examples in the [Tutorials](https://github.com/QISKit/qiskit-tutorial) repository! Our tutorials are developed using [Jupyter Notebooks](https://jupyter.org/), but can be accessed as read-only from the github web page. If you want to install it like part of QISKit read the steps [doc/install.rst](doc/install.rst#Install-Jupyter-based-tutorials)
+Now you're set up and ready to check out some of our other examples in the [Tutorials](https://github.com/QISKit/qiskit-tutorial) repository! Our tutorials are developed using [Jupyter Notebooks](https://jupyter.org/), but can be accessed as read-only from the github web page. To install it like part of QISKit read installation details [installation details](doc/install.rst#Install-Jupyter-based-tutorials)
 
 Start with the [index](https://github.com/QISKit/qiskit-tutorial/blob/master/index.ipynb) and the [‘Getting Started’ example](https://github.com/QISKit/qiskit-tutorial/blob/002d054c72fc59fc5009bb9fa0ee393e15a69d07/1_introduction/getting_started.ipynb). If you have [Jupyter Notebooks installed](https://jupyter.readthedocs.io/en/latest/install.html), can copy and modify the notebooks to create experiments of your own.
 
-Additionally, Python example programs can be found in the *examples* directory, and test scripts are located in *test*. The *qiskit* directory is the main module of the SDK. and in the *doc* directory you can find the complete SDK documentation.
-
+The *qiskit* directory is the main module of the SDK. and in the *doc* directory you can find the complete SDK documentation.
 
 ## More Information
 

doc/qiskit.rst

@@ -3,13 +3,15 @@ QISKit Documentation
 ====================
 
 Quantum Information Software Kit (QISKit), SDK Python version for working
-with `OpenQASM <https://github.com/IBM/qiskit-openqasm>`_ and the IBM Q experience (QX).
+with `OpenQASM <https://github.com/QISKit/openqasm>`_ and the IBM Q experience (QX).
 
 Philosophy
 ==========
 
-The basic concept of our quantum program is an array of quantum
-circuits. The program workflow consists of three stages: Build, Compile,
+QISKit is a collection of software for working with short depth quantum
+circuits and building near term applications and experiments on quantum
+computers. In QISKit, a quantum program is an array of quantum circuits.
+The program workflow consists of three stages: Build, Compile,
 and Run. Build allows you to make different quantum circuits that
 represent the problem you are solving; Compile allows you to rewrite
 them to run on different backends (simulators/real chips of different
@@ -102,33 +104,18 @@ extension defining some typical quantum gates.
 Internal modules
 ----------------
 
-The directory also contains internal modules that are still under
-development:
-
--  a *qasm* module for parsing **OpenQASM** circuits
--  an *unroll* module to interpret and "unroll" **OpenQASM** to a target
-   gate basis (expanding gate subroutines and loops as needed)
--  a *circuit* module for working with circuits as graphs
--  a *mapper* module for mapping all-to-all circuits to run on devices
-   with fixed couplings
-
-Quantum circuits flow through the components as follows. The programming
-interface is used to generate **OpenQASM** circuits. **OpenQASM**
-source, as a file or string, is passed into a *Qasm* object, whose
-*parse* method produces an abstract syntax tree (**AST**). The **AST**
-is passed to an *Unroller* that is attached to an *UnrollerBackend*.
-There is a *PrinterBackend* for outputting text, a *SimulatorBackend*
-for outputting simulator input data for the local simulators, and a
-*CircuitBackend* for constructing *Circuit* objects. The *Circuit*
-object represents an "unrolled" **OpenQASM** circuit as a directed
-acyclic graph (**DAG**). The *Circuit* provides methods for
-representing, transforming, and computing properties of a circuit and
-outputting the results again as **OpenQASM**. The whole flow is used by
-the *mapper* module to rewrite a circuit to execute on a device with
-fixed couplings given by a *CouplingGraph*.
-
-The four circuit representations and how they are currently transformed
-into each other are summarized in this figure:
+The directory also contains internal modules that are still under development:
+
+- a *qasm* module for parsing **OpenQASM** circuits
+- an *unroll* module to interpret and “unroll” **OpenQASM** to a target gate basis (expanding gate subroutines and loops as needed)
+- a *dagcircuit* module for working with circuits as graphs
+- a *mapper* module for mapping all-to-all circuits to run on devices with fixed couplings
+- a *simulators* module contains quantum circuit simulators
+- a *tools* directory contains methods for applications, analysis, and visualization
+
+Quantum circuits flow through the components as follows. The programming interface is used to generate **OpenQASM** circuits, as text or *QuantumCircuit* objects. **OpenQASM** source, as a file or string, is passed into a *Qasm* object, whose parse method produces an abstract syntax tree (**AST**). The **AST** is passed to an *Unroller* that is attached to an *UnrollerBackend*. There is a *PrinterBackend* for outputting text, a *JsonBackend* for producing input to simulator and experiment backends, a *DAGBackend* for constructing *DAGCircuit* objects, and a *CircuitBackend* for producing *QuantumCircuit* objects. The *DAGCircuit* object represents an “unrolled” **OpenQASM** circuit as a directed acyclic graph (DAG). The *DAGCircuit* provides methods for representing, transforming, and computing properties of a circuit and outputting the results again as **OpenQASM**. The whole flow is used by the *mapper* module to rewrite a circuit to execute on a device with fixed couplings given by a *CouplingGraph*. The structure of these components is subject to change.
+
+The circuit representations and how they are currently transformed into each other are summarized in this figure: