From ee756633e5cb6108e818c0cf4e76a42f6eaf0031 Mon Sep 17 00:00:00 2001 From: Peter Karalekas Date: Thu, 12 Jan 2017 22:11:05 -0800 Subject: [PATCH] Added pip and more clarity to the Forest instructions, minor misc others --- README.md | 73 ++++++++++++++++----------------- docs/source/getting_started.rst | 25 +++++++---- 2 files changed, 53 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index e16b86294..1b34c3237 100644 --- a/README.md +++ b/README.md @@ -3,40 +3,42 @@ A library for easily generating Quil programs to be executed using the Rigetti Forest platform. pyQuil is licensed under the [Apache 2.0 license](https://github.com/rigetticomputing/pyQuil/blob/master/LICENSE). -[![Build Status] -(https://semaphoreci.com/api/v1/projects/044fb8f4-1f90-4e28-8459-95289d682b70/1124972/badge.svg)] -(https://semaphoreci.com/rigetti/pyquil) -[![Documentation Status](https://readthedocs.org/projects/pyquil/badge/?version=latest)] -(http://pyquil.readthedocs.io/en/latest/?badge=latest) +[![Build Status](https://semaphoreci.com/api/v1/projects/044fb8f4-1f90-4e28-8459-95289d682b70/1124972/badge.svg)](https://semaphoreci.com/rigetti/pyquil) +[![Documentation Status](https://readthedocs.org/projects/pyquil/badge/?version=latest)](http://pyquil.readthedocs.io/en/latest/?badge=latest) ## Documentation -Documentation is hosted at [http://pyquil.readthedocs.io/en/latest/] -(http://pyquil.readthedocs.io/en/latest/) +Documentation is hosted at [http://pyquil.readthedocs.io/en/latest/](http://pyquil.readthedocs.io/en/latest/) ## Installation -You can install directly from the Python pip package manager using +You can install pyQuil directly from the Python package manager `pip` using: ``` pip install pyquil ``` -### Installation from source - -Clone the git repository, `cd` into it, and run - +To instead install pyQuil from source, clone this repository, `cd` into it, and run: ``` pip install -e . ``` -This will install pyQuil's dependencies (requests and numpy) if you do not already have them. -In order to connect to the QVM you need to set up configuration in the file `.pyquil_config` which -by default is looked for in your home directory. (You can change this location by setting the +This will also install pyQuil's dependencies (requests >= 2.4.2 and NumPy >= 1.10) +if you do not already have them. + +## Connecting to the Rigetti Forest + +pyQuil can be used to build and manipulate Quil programs without restriction. However, to run +programs (e.g., to get wavefunctions, get multishot experiment data), you will need an API key +for [Rigetti Forest](http://forest.rigetti.com). This will allow you to run your programs on the +Rigetti Quantum Virtual Machine (QVM) or on a real quantum processor (QPU). + +Once you have your key, you need to set up configuration in the file `.pyquil_config` which +pyQuil will attempt to find in your home directory by default. (You can change this location by setting the environment variable `PYQUIL_CONFIG` to the path of the file.) Loading the `pyquil.forest` module will print a warning if this is not found. The configuration file is in INI format and should -contain relevant information to connect. +contain all the information required to connect to Forest: -``` +```ini [Rigetti Forest] url: key: @@ -45,33 +47,33 @@ key: If `url` is not specified, it will default to `https://api.rigetti.com/qvm`. In addition to the above, the fields `https_cert` and `https_key` are supported for direct HTTPS connections to QVMs. -``` +```ini https_cert: https_key: ``` -## Examples using QVM +## Examples using the Rigetti QVM Here is how to construct a Bell state program and how to compute the amplitudes of its wavefunction: -``` +```python >>> import pyquil.quil as pq >>> import pyquil.forest as forest >>> from pyquil.gates import * ->>> cxn = forest.Connection() +>>> qvm = forest.Connection() >>> p = pq.Program(H(0), CNOT(0,1)) ->>> cxn.wavefunction(p)[0] +>>> qvm.wavefunction(p)[0] [(0.7071067811865475+0j), 0j, 0j, (0.7071067811865475+0j)] ``` How to do a simulated multishot experiment measuring qubits 0 and 1 of a Bell state. (Of course, each measurement pair will be `00` or `11`.) -``` +```python >>> import pyquil.quil as pq >>> import pyquil.forest as forest ->>> cxn = forest.Connection() +>>> qvm = forest.Connection() >>> p = pq.Program() >>> p.inst(H(0), ... CNOT(0, 1), @@ -84,29 +86,24 @@ CNOT 0 1 MEASURE 0 [0] MEASURE 1 [1] ->>> cxn.run(p, [0, 1], 10) +>>> qvm.run(p, [0, 1], 10) [[0, 0], [1, 1], [1, 1], [0, 0], [0, 0], [1, 1], [0, 0], [0, 0], [0, 0], [0, 0]] ``` -## Rigetti Forest - -pyQuil can be used to build and manipulate Quil programs without restriction. However, to run -programs (e.g., to get wavefunctions, get multishot experiment data), you will need an API key -for [Rigetti Forest](http://forest.rigetti.com). - -## Building the docs +## Building the Docs -We use sphinx to build the documentation. This can be done with: +We use sphinx to build the documentation. To do this, navigate into pyQuil's top-level directory and run: ``` sphinx-build -b html docs/source docs/_build ``` -To view the docs navigate to the `docs/_build` directory in the pyQuil root directory and open the `index.html` file a browser. Note that we use the readthedocs theme for our documentation, so this theme may need to be installed using `pip install sphinx_rtd_theme`. +To view the docs navigate to the newly-created `docs/_build` directory and open +the `index.html` file in a browser. Note that we use the Read the Docs theme for +our documentation, so this may need to be installed using `pip install sphinx_rtd_theme`. ## Development and Testing -We use pytest for testing. Tests can be run from the top level directory with - -``` -py.test --cov=pyquil +We use pytest for testing. Tests can be run from the top-level directory using: ``` +pytest --cov=pyquil +``` \ No newline at end of file diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 303d19f9c..385b98f30 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -48,29 +48,40 @@ installation of Python 2.7. If you don't have pip, it can be installed with Installation ~~~~~~~~~~~~ -After obtaining pyQuil from `GitHub `_ -or from a source distribution, navigate into its directory in a terminal and run +You can install pyQuil directly from the Python package manager pip using: + +:: + + pip install pyquil + +To instead install the bleeding-edge version from source, clone the +`pyquil GitHub repository `_, +navigate into its directory in a terminal, and run: :: pip install -e . On Mac/Linux, if this command does not succeed because of permissions -errors, then run with +errors, then instead run: :: sudo pip install -e . -This will install pyQuil's dependencies (requests >= 2.4.2 and numpy >= 1.10) if you do not already +This will also install pyQuil's dependencies (requests >= 2.4.2 and NumPy >= 1.10) if you do not already have them. The library will now be available globally. -Connecting to a Rigetti QVM -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Connecting to the Rigetti Forest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +pyQuil can be used to build and manipulate Quil programs without restriction. However, to run +programs (e.g., to get wavefunctions, get multishot experiment data), you will need an API key +for Rigetti Forest. This will allow you to run your programs on the Rigetti QVM or QPU. -In order to connect to the QVM you need to set up configuration in the file ``.pyquil_config`` +Once you have your key, you need to set up configuration in the file ``.pyquil_config`` which pyQuil will attempt to find in your home directory by default. (You can change this location by setting the environment variable ``PYQUIL_CONFIG`` to the path of the file.) Loading the ``pyquil.forest`` module will print a warning if this is not found. The configuration file is in INI format and