ProjectQ v0.3.2

README.rst

@@ -13,7 +13,7 @@ ProjectQ - An open source software framework for quantum computing
 
 ProjectQ is an open source effort for quantum computing.
 
-The first version (v0.1) features a compilation framework capable of
+It features a compilation framework capable of
 targeting various types of hardware, a high-performance quantum computer
 simulator with emulation capabilities, and various compiler plug-ins.
 This allows users to
@@ -29,7 +29,9 @@ This allows users to
 Getting started
 ---------------
 
-To start using ProjectQ, simply follow the installation instructions in the `tutorials <http://projectq.readthedocs.io/en/latest/tutorials.html>`__. There, you will also find OS-specific hints, a small introduction to the ProjectQ syntax, and a few `code examples <http://projectq.readthedocs.io/en/latest/examples.html>`__. Also, make sure to check out the `ProjectQ
+To start using ProjectQ, simply follow the installation instructions in the `tutorials <http://projectq.readthedocs.io/en/latest/tutorials.html>`__. There, you will also find OS-specific hints, a small introduction to the ProjectQ syntax, and a few `code examples <http://projectq.readthedocs.io/en/latest/examples.html>`__. More example codes and tutorials can be found in the examples folder `here <https://github.com/ProjectQ-Framework/ProjectQ/tree/develop/examples>`__ on GitHub.
+
+Also, make sure to check out the `ProjectQ
 website <http://www.projectq.ch>`__ and the detailed `code documentation <http://projectq.readthedocs.io/en/latest/>`__.
 
 How to contribute

docs/tutorials.rst

@@ -22,6 +22,8 @@ or, alternatively, `clone/download <https://github.com/projectq-framework>`_ thi
 	cd /home/projectq
 	python -m pip install --user .
 
+ProjectQ comes with a high-performance quantum simulator written in C++. Please see the detailed OS specific installation instructions below to make sure that you are installing the fastest version.
+
 .. note::
 	The setup will try to build a C++-Simulator, which is much faster than the Python implementation. If it fails, you may use the `--without-cppsimulator` parameter, i.e., 
 
@@ -48,6 +50,7 @@ Detailed instructions and OS-specific hints
 -------------------------------------------
 
 **Ubuntu**:
+
 	After having installed the build tools (for g++):
 
 	.. code-block:: bash
@@ -70,21 +73,47 @@ Detailed instructions and OS-specific hints
 
 
 **Windows**:
+
 	It is easiest to install a pre-compiled version of Python, including numpy and many more useful packages. One way to do so is using, e.g., the Python3.5 installers from `python.org <https://www.python.org/downloads>`_ or `ANACONDA <https://www.continuum.io/downloads>`_. Installing ProjectQ right away will succeed for the (slow) Python simulator (i.e., with the `--without-cppsimulator` flag). For a compiled version of the simulator, install the Visual C++ Build Tools and the Microsoft Windows SDK prior to doing a pip install. The built simulator will not support multi-threading due to the limited OpenMP support of msvc.
 
 	Should you want to run multi-threaded simulations, you can install a compiler which supports newer OpenMP versions, such as MinGW GCC and then manually build the C++ simulator with OpenMP enabled.
 
 
 **macOS**:
+
 	These are the steps to install ProjectQ on a new Mac:
 
-	Install XCode:
+	In order to install the fast C++ simulator, we require that your system has a C++ compiler (see option 3 below on how to only install the slower Python simulator via the `--without-cppsimulator` parameter)
+
+	Below you will find two options to install the fast C++ simulator. The first one is the easiest and requires only the standard compiler which Apple distributes with XCode. The second option uses macports to install the simulator with additional support for multi-threading by using OpenMP, which makes it slightly faster. We show how to install the required C++ compiler (clang) which supports OpenMP and additionally, we show how to install a newer python version.
+
+.. note::
+	Depending on your system you might need to use `sudo` for the installation.
+
+1. Installation using XCode and the default python:
+
+	Install XCode by opening a terminal and running the following command:
 
 	.. code-block:: bash
 
 		xcode-select --install
 
-	Next, you need to install Python and pip. One way of doing so is using macports to install Python 3.5 and the corresponding version of pip. Visit `macports.org <https://www.macports.org/install.php>`_ and install the latest version (afterwards open a new terminal). Then, use macports to install Python 3.5 by
+	Next, you will need to install Python and pip. See option 2 for information on how to install a newer python version with macports. Here, we are using the standard python which is preinstalled with macOS. Pip can be installed by:
+
+	.. code-block:: bash
+
+		sudo easy_install pip
+
+	Now, you can install ProjectQ with the C++ simulator using the standard command:
+
+	.. code-block:: bash
+
+		python -m pip install --user projectq
+
+
+2. Installation using macports:
+
+	Either use the standard python and install pip as shown in option 1 or better use macports to install a newer python version, e.g., Python 3.5 and the corresponding pip. Visit `macports.org <https://www.macports.org/install.php>`_ and install the latest version (afterwards open a new terminal). Then, use macports to install Python 3.5 by
 
 	.. code-block:: bash
 
@@ -102,7 +131,7 @@ Detailed instructions and OS-specific hints
 
 		sudo port install py35-pip
 
-	Next, we can install ProjectQ with the high performance simulator written in C++. Therefore, we first need to install a suitable compiler which supports OpenMP and instrinsics. One option is to install clang 3.9 also using macports (note: gcc installed via macports does not work as the gcc compiler claims to support instrinsics, while the assembler of gcc does not support it)
+	Next, we can install ProjectQ with the high performance simulator written in C++. First, we will need to install a suitable compiler with support for **C++11**, OpenMP, and instrinsics. The best option is to install clang 3.9 also using macports (note: gcc installed via macports does not work)
 
 	.. code-block:: bash
 
@@ -114,27 +143,21 @@ Detailed instructions and OS-specific hints
 
 		env CC=clang-mp-3.9 env CXX=clang++-mp-3.9 python3.5 -m pip install --user projectq
 
-	If you don't want to install clang 3.9, you can try and specify your preferred compiler by changing CC and CXX in the above command (the compiler must support **C++11**). 
+3. Installation with only the slow Python simulator:
+
+	While this simulator works fine for small examples, it is suggested to install the high performance simulator written in C++.
 
-	Should something go wrong when compiling the C++ simulator extension in one of the above installation procedures, 
-	you can turn off this feature using the ``--without-cppsimulator`` 
-	parameter (note: this only works if one of the above installation methods has been tried and hence 
-	all requirements are now installed), i.e.,
+	If you just want to install ProjectQ with the (slow) Python simulator and no compiler, then first try to install ProjectQ with the default compiler 
 
 	.. code-block:: bash
-	
-		python3.5 -m pip install --user --global-option=--without-cppsimulator projectq
 
-	While this simulator works fine for small examples, it is suggested to install the high performance simulator written in C++. 
+		python -m pip install --user projectq
 
-	If you just want to install ProjectQ with the (slow) Python simulator and no compiler, then first try to install ProjectQ with the default compiler 
+	which most likely will fail. Then, try again with the flag ``--without-cppsimulator``:
 
 	.. code-block:: bash
 
-		python3.5 -m pip install --user projectq
-
-	which most likely will fail and then use the command above using the ``--without-cppsimulator`` 
-	parameter.
+		python -m pip install --user --global-option=--without-cppsimulator projectq
 
 
 The ProjectQ syntax

examples/README.rst

@@ -0,0 +1,24 @@
+Examples and Tutorials
+======================
+
+This folder contains a collection of **examples** and **tutorials** for how to use ProjectQ. They offer a great way to get started. While this collection is growing, it will never be possible to cover everything. Therefore, we refer the readers to also have a look at:
+
+* Our complete **code documentation** which can be found online `here <http://projectq.readthedocs.io/en/latest/>`__. Besides the newest version of the documentation it also provides older versions. Moreover, these docs can be downloaded for offline usage.
+
+* Our **unit tests**. More than 99% of all lines of code are covered with various unit tests since the first release. Tests are really important to us. Therefore, if you are wondering how a specific feature can be used, have a look at the **unit tests**, where you can find plenty of examples. Finding the unit tests is very easy: E.g., the tests of the simulator implemented in *ProjectQ/projectq/backends/_sim/_simulator.py* can all be found in the same folder in the file *ProjectQ/projectq/backends/_sim/_simulator_test.py*.
+
+Getting started / background information
+----------------------------------------
+
+It might be a good starting point to have a look at our paper which explains the goals of the ProjectQ framework and also gives a good overview:
+
+* 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>`__
+
+Examples and tutorials in this folder
+-------------------------------------
+
+1. Some of the files in this folder are explained in the `documentation <http://projectq.readthedocs.io/en/latest/examples.html>`__.
+
+2. Take a look at the *simulator_tutorial.ipynb* for a detailed introduction to most of the features of our high performance quantum simulator.
+
+3. Running on the IBM QE chip is explained in more details in *ibm_entangle.ipynb*.