Merge 7ca58c8 into a989adf

README.rst

@@ -32,6 +32,114 @@ This allows users to
 -  export quantum programs as circuits (using TikZ)
 -  get resource estimates
 
+Examples
+--------
+
+**First quantum program**
+
+.. code-block:: python
+
+    from projectq import MainEngine  # import the main compiler engine
+    from projectq.ops import H, Measure  # import the operations we want to perform (Hadamard and measurement)
+
+    eng = MainEngine()  # create a default compiler (the back-end is a simulator)
+    qubit = eng.allocate_qubit()  # allocate a quantum register with 1 qubit
+
+    H | qubit  # apply a Hadamard gate
+    Measure | qubit  # measure the qubit
+
+    eng.flush()  # flush all gates (and execute measurements)
+    print("Measured {}".format(int(qubit)))  # converting a qubit to int or bool gives access to the measurement result
+
+
+ProjectQ features a lean syntax which is close to the mathematical notation used in quantum physics. For example, a rotation of a qubit around the x-axis is usually specified as:
+
+.. image:: docs/images/braket_notation.svg
+    :alt: Rx(theta)|qubit>
+    :width: 100px
+
+The same statement in ProjectQ's syntax is:
+
+.. code-block:: python
+
+    Rx(theta) | qubit
+
+The **|**-operator separates the specification of the gate operation (left-hand side) from the quantum bits to which the operation is applied (right-hand side).
+
+**Changing the compiler and using a resource counter as a back-end**
+
+Instead of simulating a quantum program, one can use our resource counter (as a back-end) to determine how many operations it would take on a future quantum computer with a given architecture. Suppose the qubits are arranged on a linear chain and the architecture supports any single-qubit gate as well as the two-qubit CNOT and Swap operations:
+
+.. code-block:: python
+
+    from projectq import MainEngine
+    from projectq.backends import ResourceCounter
+    from projectq.ops import QFT
+    from projectq.setups import linear
+
+    compiler_engines = linear.get_engine_list(num_qubits=16,
+                                              one_qubit_gates='any',
+                                              two_qubit_gates=(CNOT, Swap))
+    resource_counter = ResourceCounter()
+    eng = MainEngine(backend=resource_counter, engine_list=compiler_engines)
+    qureg = eng.allocate_qureg(16)
+    QFT | qureg
+    eng.flush()
+
+    print(resource_counter)
+
+    # This will output, among other information,
+    # how many operations are needed to perform
+    # this quantum fourier transform (QFT), i.e.,
+    #   Gate class counts:
+    #       AllocateQubitGate : 16
+    #       CXGate : 240
+    #       HGate : 16
+    #       R : 120
+    #       Rz : 240
+    #       SwapGate : 262
+
+
+**Running a quantum program on IBM's QE chips**
+
+To run a program on the IBM Quantum Experience chips, all one has to do is choose the `IBMBackend` and the corresponding compiler:
+
+.. code-block:: python
+
+    compiler_engines = projectq.setups.ibm16.get_engine_list()
+    eng = MainEngine(IBMBackend(use_hardware=True, num_runs=1024,
+                                verbose=False, device='ibmqx5'),
+                     engine_list=compiler_engines)
+
+
+**Classically simulate a quantum program**
+
+ProjectQ has a high-performance simulator which allows simulating up to about 30 qubits on a regular laptop. See the `simulator tutorial <https://github.com/ProjectQ-Framework/ProjectQ/blob/feature/update-readme/examples/simulator_tutorial.ipynb>`__ for more information. Using the emulation features of our simulator (fast classical shortcuts), one can easily emulate Shor's algorithm for problem sizes for which a quantum computer would require above 50 qubits, see our `example codes <http://projectq.readthedocs.io/en/latest/examples.html#shor-s-algorithm-for-factoring>`__.
+
+
+The advanced features of the simulator are also particularly useful to investigate algorithms for the simulation of quantum systems. For example, the simulator can evolve a quantum system in time (without Trotter errors) and it gives direct access to expectation values of Hamiltonians leading to extremely fast simulations of VQE type algorithms:
+
+.. code-block:: python
+    
+    from projectq import MainEngine
+    from projectq.ops import All, Measure, QubitOperator, TimeEvolution
+
+    eng = MainEngine()
+    wavefunction = eng.allocate_qureg(2)
+    # Specify a Hamiltonian in terms of Pauli operators:
+    hamiltonian = QubitOperator("X0 X1") + 0.5 * QubitOperator("Y0 Y1")
+    # Apply exp(-i * Hamiltonian * time) (without Trotter error)
+    TimeEvolution(time=1, hamiltonian=hamiltonian) | wavefunction
+    # Measure the expection value using the simulator shortcut:
+    eng.flush()
+    value = eng.backend.get_expectation_value(hamiltonian, wavefunction)
+
+    # Last operation in any program should be measuring all qubits
+    All(Measure) | qureg
+    eng.flush()
+
+
+
 Getting started
 ---------------
 
@@ -54,10 +162,11 @@ When using ProjectQ for research projects, please cite
 
 -  Damian S. Steiger, Thomas Häner, and Matthias Troyer "ProjectQ: An
    Open Source Software Framework for Quantum Computing"
-   `[arxiv:1612.08091] <https://arxiv.org/abs/1612.08091>`__
+   `Quantum 2, 49 (2018) <https://doi.org/10.22331/q-2018-01-31-49>`__
+   (published on `arXiv <https://arxiv.org/abs/1612.08091>`__ on 23 Dec 2016)
 -  Thomas Häner, Damian S. Steiger, Krysta M. Svore, and Matthias Troyer
-   "A Software Methodology for Compiling Quantum Programs"
-   `[arxiv:1604.01401] <http://arxiv.org/abs/1604.01401>`__
+   "A Software Methodology for Compiling Quantum Programs" `Quantum Sci. Technol. 3 (2018) 020501 <https://doi.org/10.1088/2058-9565/aaa5cc>`__ 
+   (published on `arXiv <http://arxiv.org/abs/1604.01401>`__ on 5 Apr 2016)
 
 Authors
 -------
@@ -70,6 +179,8 @@ in the group of `Prof. Dr. Matthias
 Troyer <http://www.comp.phys.ethz.ch/people/troyer.html>`__ at ETH
 Zurich.
 
+ProjectQ is constantly growing and `many other people <https://github.com/ProjectQ-Framework/ProjectQ/graphs/contributors>`__ have already contributed to it in the meantime.
+
 License
 -------
 

docs/index.rst

@@ -14,8 +14,8 @@ The **four core principles** of this open-source effort are
 
 
 Please cite
-	* Damian S. Steiger, Thomas Häner, and Matthias Troyer "ProjectQ: An Open Source Software Framework for Quantum Computing" [`arxiv:1612.08091 <https://arxiv.org/abs/1612.08091>`_]
-	* Thomas Häner, Damian S. Steiger, Krysta M. Svore, and Matthias Troyer "A Software Methodology for Compiling Quantum Programs" [`arxiv:1604.01401 <http://arxiv.org/abs/1604.01401>`_]
+	* Damian S. Steiger, Thomas Häner, and Matthias Troyer "ProjectQ: An Open Source Software Framework for Quantum Computing" `Quantum 2, 49 (2018) <https://doi.org/10.22331/q-2018-01-31-49>`__ (published on `arXiv <https://arxiv.org/abs/1612.08091>`__ on 23 Dec 2016)
+	* Thomas Häner, Damian S. Steiger, Krysta M. Svore, and Matthias Troyer "A Software Methodology for Compiling Quantum Programs" `Quantum Sci. Technol. 3 (2018) 020501 <https://doi.org/10.1088/2058-9565/aaa5cc>`__ (published on `arXiv <http://arxiv.org/abs/1604.01401>`__ on 5 Apr 2016)
 
 
 Contents