Merge pull request #52 from rigetticomputing/pyquillow

Upgrade to v1.0.0

README.md

@@ -42,25 +42,20 @@ contain all the information required to connect to Forest:
 [Rigetti Forest]
 url: <URL to Rigetti Forest or QVM endpoint>
 key: <Rigetti Forest API key>
+user_id: <Rigetti Forest User ID>
 ```
 
-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: <path to signed HTTPS certificate and key>
-https_key: <path to separate key file, if different from the above>
-```
+If `url` is not specified, it will default to `https://api.rigetti.com/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
+>>> import pyquil.api as api
 >>> from pyquil.gates import *
->>> qvm = forest.Connection()
+>>> qvm = api.SyncConnection()
 >>> p = pq.Program(H(0), CNOT(0,1))
 <pyquil.pyquil.Program object at 0x101ebfb50>
 >>> qvm.wavefunction(p)[0]
@@ -72,9 +67,9 @@ each measurement pair will be `00` or `11`.)
 
 ```python
 >>> import pyquil.quil as pq
->>> import pyquil.forest as forest
+>>> import pyquil.api as api
 >>> from pyquil.gates import *
->>> qvm = forest.Connection()
+>>> qvm = api.SyncConnection()
 >>> p = pq.Program()
 >>> p.inst(H(0),
 ...        CNOT(0, 1),

docs/source/conf.py

@@ -44,14 +44,13 @@
 import os
 
 def remove_secrets(app, what, name, obj, options, signature, return_annotation):
-    if what == "class" and name == "pyquil.forest.Connection":
-        import pyquil.forest as pqf
-        print("Replacing endpoint secrets in pyquil.forest.Connection() signature")
+    if what == "class" and name == "pyquil.api.Connection":
+        import pyquil.api as pqf
+        print("Replacing endpoint secrets in pyquil.api.Connection() signature")
         print(signature,)
         signature = signature.replace("'{}'".format(pqf.ENDPOINT), "ENDPOINT")
         signature = signature.replace("'{}'".format(pqf.API_KEY), "API_KEY")
-        signature = signature.replace("'{}'".format(pqf.HTTPS_CERT), "HTTPS_CERT")
-        signature = signature.replace("'{}'".format(pqf.HTTPS_KEY), "HTTPS_KEY")
+        signature = signature.replace("'{}'".format(pqf.USER_ID), "USER_ID")
         print("--> ", signature)
         return signature, return_annotation
 
@@ -86,9 +85,9 @@ def setup(app):
 # built documents.
 #
 # The short X.Y version.
-version = u'0.0.1'
+version = u'1.0.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.0.1'
+release = u'1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/getting_started.rst

@@ -8,9 +8,9 @@ programs.
 .. code:: python
 
     import pyquil.quil as pq
-    import pyquil.forest as forest
+    import pyquil.api as api
     from pyquil.gates import *
-    qvm = forest.Connection()
+    qvm = api.SyncConnection()
     p = pq.Program()
     p.inst(H(0), CNOT(0, 1))
         <pyquil.pyquil.Program object at 0x101ebfb50>
@@ -25,13 +25,16 @@ It comes with a few parts:
    abstract machine, such as the quantum virtual machine (QVM), or on a
    real quantum processing unit (QPU). More details regarding Quil can be
    found in the `whitepaper <https://arxiv.org/abs/1608.03355>`__.
-2. **QVM**: A Quantum Virtual Machine, which is an implementation of the quantum
-   abstract machine on classical hardware. The QVM lets you use a
+2. **QVM**: A `Quantum Virtual Machine <qvm_overview.html>`_, which is an implementation of the
+   quantum abstract machine on classical hardware. The QVM lets you use a
    regular computer to simulate a small quantum computer. You can access
    the Rigetti QVM running in the cloud with your API key.
-   Sign up `here <http://forest.rigetti.com>`_ to get your key.
+   `Sign up here <http://forest.rigetti.com>`_ to get your key.
 3. **pyQuil**: A Python library to help write and run Quil code and
    quantum programs.
+4. **QPUConnection**: pyQuil also includes some a special connection which lets you run experiments
+   on Rigetti's prototype superconducting quantum processors over the cloud.  These experiments are
+   described in more detail `here <qpu.html>`_.
 
 Environment Setup
 -----------------
@@ -102,20 +105,27 @@ and should contain all the information required to connect to Forest:
 Look `here <http://forest.rigetti.com>`_ to learn more about the Forest toolkit.
 
 If ``url`` is not set, pyQuil will default to looking for a
-local endpoint at ``127.0.0.1:5000``. In addition to the above, the fields ``https_cert``
-and ``https_key`` are supported for direct HTTPS connections to Forest.
-
-::
-
-    https_cert: <path to signed HTTPS certificate and key>
-    https_key: <path to separate key file, if different from the above>
+local endpoint at ``127.0.0.1:5000``.
 
 Alternatively, connection information can be provided in environment variables.
 
 ::
 
     export QVM_URL=<URL to Rigetti Forest or QVM endpoint>
     export QVM_API_KEY=<Rigetti Forest API key>
+    export QVM_USER_ID=<Rigetti User ID>
+
+Endpoints
++++++++++
+There are two important endpoints to keep in mind.  You will use different ones for different types
+of jobs.
+
+``https://api.rigetti.com/qvm`` is used for making synchronous calls to the QVM.  You should use
+this for most of the getting started materials unless otherwise instructed.
+
+``https://job.rigetti.com/Beta`` is used for large async `QVM jobs <getting_started.html#jobconnections>`_
+or for running `jobs on a QPU <qpu.html>`_.
+
 
 Running your first quantum program
 ----------------------------------
@@ -147,14 +157,18 @@ gates for pyQuil.
 .. code:: python
 
     import pyquil.quil as pq
-    import pyquil.forest as forest
+    import pyquil.api as api
     from pyquil.gates import *
 
-Next, we want to open a connection to the QVM.
+Next, we want to open a connection to the QVM. Forest supports two types of connections through
+pyQuil.  The first is a synchronous connection that immediately runs requested jobs against the QVM.
+This will time out on longer jobs that run for more than 30 seconds. Synchronous connections are good
+for experimenting interactively as they give quick feedback.
 
 .. code:: python
 
-    qvm = forest.Connection()
+    # open a synchronous connection
+    qvm = api.SyncConnection()
 
 Now we can make a program by adding some Quil instruction using the
 ``inst`` method on a ``Program`` object.
@@ -327,10 +341,10 @@ reproduce measurement results for the purpose of testing:
 
 .. code:: python
 
-    seeded_cxn = forest.Connection(random_seed=17)
+    seeded_cxn = api.SyncConnection(random_seed=17)
     print(seeded_cxn.run(pq.Program(H(0)).measure(0, 0), [0], 20))
 
-    seeded_cxn = forest.Connection(random_seed=17)
+    seeded_cxn = api.SyncConnection(random_seed=17)
     # This will give identical output to the above
     print(seeded_cxn.run(pq.Program(H(0)).measure(0, 0), [0], 20))
 
@@ -789,7 +803,7 @@ probabilities specified.
     # 20% chance of a X gate being applied after gate applications and before measurements.
     gate_noise_probs = [0.2, 0.0, 0.0]
     meas_noise_probs = [0.2, 0.0, 0.0]
-    noisy_qvm = forest.Connection(gate_noise=gate_noise_probs, measurement_noise=meas_noise_probs)
+    noisy_qvm = api.SyncConnection(gate_noise=gate_noise_probs, measurement_noise=meas_noise_probs)
 
 We can test this by applying an :math:`X`-gate and measuring. Nominally,
 we should always measure ``1``.
@@ -922,6 +936,55 @@ alpha.
 This ParametricProgram now acts as a template, caching the result of the ``exponential_map``
 calculation so that it can be used later with new values.
 
+JobConnections
+--------------
+Larger pyQuil programs can take longer than 30 seconds to run.  These jobs can be posted into the
+cloud job queue using a different connection object.  The mode of interactive with the API is
+asynchronous.  This means that there is a seperate query to post a job and to get the result.
+
+::
+
+  from pyquil.quil import Program
+  from pyquil.gates import X, H, I
+  from pyquil.api import JobConnection
+
+  job_qvm = JobConnection()
+  res = job_qvm.run(Program(X(0)).measure(0, 0), [0])
+
+The `res` is an instance of a ``JobResult`` object.  It has an id and allows you to make queries
+to see if the job result is finished.
+
+::
+
+  zz = res.get()
+  print type(zz), zz
+
+.. parsed-literal::
+
+    <class 'pyquil.job_results.JobResult'> {u'status': u'Submitted', u'jobId': u'BLSLJCBGNP'}
+
+Once the job is finished, then the results can be retrieved from the JobResult object:
+
+::
+
+  import time
+
+  while not res.is_done():
+      res.get()
+      time.sleep(1)
+  print res
+  answer = res.decode()
+  print answer
+
+.. parsed-literal::
+
+  {u'result': u'[[1]]', u'jobId': u'BLSLJCBGNP'}
+
+  <type 'list'> [[1]]
+
+This same pattern applies to the ``wavefunction``, ``expectation``, and ``run_and_measure`` calls
+on the JobConnection object.
+
 Exercises
 ---------
 

docs/source/index.rst

@@ -13,6 +13,8 @@ Welcome to the Documentation for Forest and pyQuil!
    intro_to_qc
    getting_started
    next_steps
+   qvm_overview
+   qpu
    examples
    source_docs
 

docs/source/intro_to_qc.rst

@@ -193,16 +193,16 @@ Some Code
 Let us take a look at some code in pyQuil to see how these quantum states
 play out. We will dive deeper into quantum operations and pyQuil in
 the following sections. Note that in order to run these examples you will need
-to `install pyQuil and set up a connection to Forest <getting_started.html#getting-started>`_.
+to `install pyQuil and set up a connection to the Forest API <getting_started.html#getting-started>`_.
 Each of the code snippets below will be immediately followed by its output.
 
 .. code:: python
 
     # Imports for pyQuil (ignore for now)
     import numpy as np
     from pyquil.quil import Program
-    import pyquil.forest as forest
-    quantum_simulator = forest.Connection()
+    import pyquil.api as api
+    quantum_simulator = api.SyncConnection()
 
     # pyQuil is based around operations (or gates) so we will start with the most
     # basic one: the identity operation, called I. I takes one argument, the index

docs/source/job_results.rst

@@ -0,0 +1,7 @@
+pyquil.job_results
+------------------
+
+.. automodule:: pyquil.job_results
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/overview.rst

@@ -5,7 +5,7 @@ Overview
 Welcome to pyQuil!
 
 pyQuil is part of the Rigetti Forest `toolkit <http://forest.rigetti.com>`_ for
-**quantum programming in the cloud**, which is currently in private beta.  If you are interested in
+**quantum programming in the cloud**, which is currently in public beta.  If you are interested in
 obtaining an API key for the beta, please reach out by signing up
 `here <http://forest.rigetti.com>`_.  We look forward to hearing from you.
 
@@ -21,6 +21,17 @@ belief is that in the near term quantum computers will operate as coprocessors,
 concert with traditional CPUs.  This means that Quil is designed to execute on a Quantum Abstract
 Machine that has a shared classical/quantum architecture at its core.
 
+pyQuil currently allows you to do quantum computing in two ways:
+1.  Quil programs can be executed on a local or cloud-based Quantum Virtual Machine.  This is a
+classical simulation of a quantum processor that can simulate up to 36 qubits.  The default access
+key allows you to run simulations of up to 25 qubits.  These simulations can be run through either
+synchronous API calls, or through an asynchronous job queue for larger programs.  More information
+about the QVM can be found at `Overview of the Quantum Virtual Machine <qvm_overview.html>`_.
+2.  pyQuil also runs some select single qubit experiments on Rigetti's superconducting quantum
+processors.  This functionality will be expanded over time, and currently allows for Rabi, Ramsey,
+and T1 experiments to be run on a multi-qubit chip using the QPUConnection object. More information
+about these features are available at `Experimenting with a QPU <qpu.html>`_.
+
 If you are already familiar with quantum computing, then feel free to proceed to
 `Installation and Getting Started <getting_started.html>`_.
 

docs/source/plots.rst

@@ -0,0 +1,7 @@
+pyquil.plots
+------------
+
+.. automodule:: pyquil.plots
+    :members:
+    :undoc-members:
+    :show-inheritance: