From a106a920a62c7549b4c29f57f6bb7f143b861769 Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Tue, 27 Nov 2018 15:33:25 -0800 Subject: [PATCH 01/13] Add information about QuantumComputer --- docs/source/qvm.rst | 274 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 228 insertions(+), 46 deletions(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index ddf4e9ef8..d5217440f 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -3,76 +3,178 @@ The Quantum Computer ==================== -The Quantum Virtual Machine (QVM) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``QuantumComputer`` +~~~~~~~~~~~~~~~~~~~ + +The :py:class:`~pyquil.api.QuantumComputer` abstraction offered by pyQuil provides an easy access point to the most +critical objects used in pyQuil for building and executing your quantum programs. +We will cover the main methods and attributes on this page. +The `QuantumComputer API Reference `_ provides a reference for all of its methods and +options. + +At a high level, the :py:class:`~pyquil.api.QuantumComputer` wraps around our favorite quantum computing tools: + + - **A compiler** ``.compiler`` : this determines how we manipulate the Quil input to something more efficient when possible, + and then into a form which our QAM can accept as input. + - **A device** ``.device`` : this specifies the topology and Instruction Set Architecture (ISA) of + the targeted device by listing the supported 1Q and 2Q gates. + - **A quantum abstract machine** ``.qam`` : this is our general purpose quantum computing device, + which implements the required abstract methods to manipulate classical and quantum state, such as + loading programs, writing to shared classical memory, and executing programs. It is implemented as a :py:class:`~pyquil.api.QVM` + (quantum virtual machine) or + :py:class:`~pyquil.api.QPU` (quantum processing unit) object in pyQuil. + +The :py:class:`~pyquil.api.QuantumComputer` instance makes methods available which are built on the above objects. If +you need more fine grained controls for your work, you might try exploring what is offered by these objects. + +For more information on each of the above, check out the following pages: + + - `Compiler API Reference `_ + - :ref:`Quil Compiler docs ` + - `Device API Reference `_ + - :ref:`new_topology` + - `Quantum abstract machine (QAM) API Reference `_ + - `The Quil Whitepaper `_ which describes the QAM + +Instantiation +------------- -The Rigetti Quantum Virtual Machine is an implementation of the Quantum Abstract Machine from -*A Practical Quantum Instruction Set Architecture*. [1]_ It is implemented in ANSI Common LISP and -executes programs specified in the Quantum Instruction Language (Quil). +A decent amount of information needs to be provided to initialize the ``compiler``, ``device``, and ``qam`` attributes, +much of which is already in your :ref:`config files <_advanced_usage>` (or provided reasonable defaults when running locally). +Typically, you will want a :py:class:`~pyquil.api.QuantumComputer` which either: -Quil is an opinionated quantum instruction language: its basic belief is that in the near term quantum computers will -operate as coprocessors, working in 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. + - pertains to a real, available QPU device + - is a QVM but mimics the topology of a QPU, with or without noise + - is some a generic QVM -The QVM is a wavefunction simulation of unitary evolution with classical control flow -and shared quantum classical memory. +All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. -.. _qvm_use: +.. code:: python -Using the QVM -------------- -After :ref:`downloading the SDK `, the QVM is available on your local machine. You can initialize a local -QVM server by typing ``qvm -S`` into your terminal. You should see the following message. + def get_qc(name: str, *, as_qvm: bool = None, noisy: bool = None, + connection: ForestConnection = None) -> QuantumComputer: .. code:: python - $ qvm -S - ****************************** - * Welcome to the Rigetti QVM * - ****************************** - Copyright (c) 2018 Rigetti Computing. + from pyquil import get_qc - (Configured with 2048 MiB of workspace and 8 workers.) + # Get a QPU + qc = get_qc(QPU_LATTICE_NAME) # This is just a string naming the device - [2018-11-06 18:18:18] Starting server on port 5000. + # Get a QVM with the same topology as the QPU lattice, without noise + qc = get_qc(QPU_LATTICE_NAME, as_qvm=True) + # or, equivalently + qc = get_qc(f"{QPU_LATTICE_NAME}-qvm") -For a detailed description of how to use the ``qvm`` from the command line, see :ref:`The QVM manual page `. + # With noise + qc = get_qc(QPU_LATTICE_NAME, as_qvm=True, noisy=True) + + # A fully connected QVM + number_of_qubits = 10 + qc = get_qc(f"{number_of_qubits}q-qvm") + +For now, you will have to join QCS to get ``QPU_LATTICE_NAME`` by running the +``qcs lattices`` command from your QMI. Access to the QPU is only possible from a QMI, during a booked reservation. +If this sounds unfamiliar, check out our `documentation for QCS `_ +and `join the waitlist `_. + +For more information about creating your own noise models, check out :ref:`noise`. + +.. note:: + When connecting to a QVM locally (such as with ``get_qc(..., as_qvm=True)``) you'll have to set up the QVM + in :ref:`server mode `. + +Methods +------- -Once the QVM is serving requests, we can run the following pyQuil program to get a ``QuantumComputer`` object which -will use the QVM. +Now that you have your ``qc``, there's a lot you can do with it. Most users will want to use ``compile``, ``run`` or +``run_and_measure``, and ``qubits`` very regularly. The general flow of use would look like this: .. code:: python from pyquil import get_qc, Program from pyquil.gates import * - qc = get_qc('9q-square-qvm') + qc = get_qc('9q-square-qvm') # not general to any number of qubits, 9q-square-qvm is special -One executes quantum programs on the QVM using the ``.run(...)`` method, intended to closely mirror how one will -execute programs on a real QPU. We also offer a Wavefunction Simulator (formerly a part of the ``QVM`` object), -which allows users to contruct and inspect wavefunctions of quantum programs. Learn more -about the Wavefunction Simulator :ref:`here `. For information on constructing quantum -programs, please refer back to :ref:`basics`. + qubits = qc.qubits() # this information comes from qc.device + p = Program() + # ... build program, potentially making use of the qubits list + + compiled_program = qc.compile(p) # this makes multiple calls to qc.compiler + + results = qc.run(compiled_program) # this makes multiple calls to qc.qam + +.. note:: + + In addition to a running QVM server, you will need a running ``quilc`` server to compile your program. Setting + up both of these is very easy, as explained :ref:`here `. + + +The ``.run_and_measure(...)`` method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the most high level way to run your program. With this method, you are **not** responsible for compiling your program +before running it, nor do you have to specify any ``MEASURE`` instructions; all qubits will get measured. + +.. code:: python + + from pyquil import Program, get_qc + from pyquil.gates import X + + qc = get_qc("8q-qvm") + + p = Program(X(0)) + + results = qc.run_and_measure(p, trials=5) + print(results) + +Trials specifies how many times to run this program. Let's see our results: + +.. parsed-literal:: + + {0: array([1, 1, 1, 1, 1]), + 1: array([0, 0, 0, 0, 0]), + 2: array([0, 0, 0, 0, 0]), + 3: array([0, 0, 0, 0, 0]), + 4: array([0, 0, 0, 0, 0]), + 5: array([0, 0, 0, 0, 0]), + 6: array([0, 0, 0, 0, 0]), + 7: array([0, 0, 0, 0, 0])} + +The return value is a dictionary from qubit index to results for all trials. +Every qubit in the lattice is measured for you, and as expected, qubit 0 has been flipped to the excited state +for each trial. The ``.run(...)`` method ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ -The ``.run(...)`` method takes in a compiled program. You are responsible for compiling your program before running it. -Remember to also start up a ``quilc`` compiler server, too, with ``quilc -S``. +The lower-level ``.run(...)`` method gives you more control over how you want to build and compile your program than +``.run_and_measure`` does. **You are responsible for compiling your program before running it.** +The above program would be written in this way to execute with ``run``: .. code:: python + from pyquil import Program, get_qc + from pyquil.gates import X + + qc = get_qc("8q-qvm") + p = Program() ro = p.declare('ro', 'BIT', 1) p += X(0) p += MEASURE(0, ro[0]) p += MEASURE(1, ro[1]) p.wrap_in_numshots_loop(5) + executable = qc.compile(p) - results = qc.run(executable) - print(results) + bitstrings = qc.run(executable) # .run takes in a compiled program, unlike .run_and_measure + print(bitstrings) + +By specifying ``MEASURE`` ourselves, we will only get the results that we are interested in. To be completely equivalent +to the previous example, we would have to measure all eight qubits. -The results returned are a *list of lists of integers*. In the above case, that's +The results returned is a *list of lists of integers*. In the above case, that's .. parsed-literal:: @@ -86,23 +188,103 @@ we use as our readout register. We see that the result of this program is that t the state of qubit 0, which should be ``1`` after an :math:`X`-gate. See :ref:`declaring_memory` and :ref:`measurement` for more details about declaring and accessing classical memory regions. -.. [1] https://arxiv.org/abs/1608.03355 +.. tip:: Get the results for qubit 0 with ``numpy.array(bitstrings)[:,0]``. + +.. _new_topology: + +Providing Your Own Device Topology +---------------------------------- + +It is simple to provide your own device topology as long as you can give your qubits each a number, +and specify which edges exist. Here is an example, using the topology of our 16Q chip (two octagons connected by a square): + +.. code:: python + + import networkx as nx + + from pyquil.device import NxDevice, gates_in_isa + from pyquil.noise import decoherence_noise_with_asymmetric_ro + + qubits = [0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, 13, 14, 15, 16, 17] # qubits are numbered by octagon + edges = [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5) (5, 6), (6, 7), (7, 0), # first octagon + (1, 16), (2, 15), # connections across the square + (10, 11), (11, 12), (13, 14), (14, 15), (15, 16), (16, 17), (10, 17)] # second octagon + + # Build the NX graph + topo = nx.from_edgelist(edges) + # You would uncomment the next line if you have disconnected qubits + # topo.add_nodes_from(qubits) + device = NxDevice(topo) + device.noise_model = decoherence_noise_with_asymmetric_ro(gates_in_isa(device.get_isa())) # Optional + +Now that you have your device, you could set ``qc.device`` and ``qc.compiler.device`` to point to your new device, +or use it to make new objects. Simulating the QPU using the QVM -------------------------------- -The QVM is a powerful tool for testing quantum programs before executing them on the QPU. +The :py:class:`~pyquil.api.QAM` methods are intended to be used in the same way, whether a QVM or QPU is being targeted. +Everywhere on this page, +you can swap out the type of the QAM (quantum abstract machine -- remember, a QVM or a QPU) and you will still +get reasonable results back. As long as the topology of the devices are the same, programs compiled and ran on the QVM +will be able to run on the QPU and visa-versa. Since :py:class:`~pyquil.api.QuantumComputer` is built on the ``QAM`` +abstract class, its methods will also work for both QAM implementations. + +This makes the QVM is a powerful tool for testing quantum programs before executing them on the QPU. .. code:: python - qc = get_qc("QuantumComputerName") - qc = get_qc("QuantumComputerName-qvm") + qpu = get_qc(QPU_LATTICE_NAME) + qvm = get_qc(QPU_LATTICE_NAME, as_qvm=True) -By simply providing ``-qvm`` in the device name, all programs executed on this QVM will, have the same topology as -the named QPU. To learn how to add noise models to your virtual ``QuantumComputer`` instance, check out +By simply providing ``as_qvm=True``, we get a QVM which will have the same topology as +the named QPU. It's a good idea to run your programs against the QVM before booking QPU time to iron out +bugs. You can also provide ``noisy=True`` to get a noisy QVM. To learn more about how to add noise models to your virtual ``QuantumComputer`` instance, check out :ref:`noise`. -The Quantum Processing Unit -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _qvm_use: + +The Quantum Virtual Machine (QVM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The pyQuil :py:class:`~pyquil.api.QVM` object, which fills the :py:class:`~pyquil.api.QuantumComputer` ``qam`` attribute, +is essentially a client around a Rigetti QVM endpoint. + +The Rigetti Quantum Virtual Machine is an implementation of the Quantum Abstract Machine from +*A Practical Quantum Instruction Set Architecture*. [1]_ It is implemented in ANSI Common LISP and +executes programs specified in the Quantum Instruction Language (Quil). + +Quil is an opinionated quantum instruction language: its basic belief is that in the near term quantum computers will +operate as coprocessors, working in 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. + +The QVM is a wavefunction simulation of unitary evolution with classical control flow +and shared quantum classical memory. + +The QVM is part of the Forest SDK, and it's available for you to use on your local machine. +After :ref:`downloading the SDK `, you can initialize a local +QVM server by typing ``qvm -S`` into your terminal. You should see the following message. + +.. code:: python + + $ qvm -S + ****************************** + * Welcome to the Rigetti QVM * + ****************************** + Copyright (c) 2018 Rigetti Computing. + + (Configured with 2048 MiB of workspace and 8 workers.) + + [2018-11-06 18:18:18] Starting server on port 5000. + +For a detailed description of how to use the ``qvm`` from the command line, see :ref:`The QVM manual page `. + + +We also offer a Wavefunction Simulator (formerly a part of the :py:class:`~pyquil.api.QVM` object), +which allows users to contruct and inspect wavefunctions of quantum programs. Learn more +about the Wavefunction Simulator :ref:`here `. For information on constructing quantum +programs, please refer back to :ref:`basics`. + + +.. [1] https://arxiv.org/abs/1608.03355 -*Coming soon*: Detailed information about how to use :py:func:`~pyquil.get_qc` to target a QPU. From 74ad1ee58bb41173407495cc56fd02dd9e678272 Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Fri, 30 Nov 2018 14:20:40 -0800 Subject: [PATCH 02/13] Add info about QPU, QVM, and both generally --- docs/source/qvm.rst | 188 ++++++++++++++++++++++++++++++-------------- 1 file changed, 130 insertions(+), 58 deletions(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index d5217440f..203efcf91 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -3,8 +3,122 @@ The Quantum Computer ==================== -``QuantumComputer`` -~~~~~~~~~~~~~~~~~~~ +PyQuil is used to build Quil (Quantum Instruction Language) programs and execute them on simulated or real quantum devices. Quil is an opinionated +quantum instruction language: its basic belief is that in the near term quantum computers will +operate as coprocessors, working in concert with traditional CPUs. This means that Quil is designed to execute on +a Quantum Abstract Machine (QAM) that has a shared classical/quantum architecture at its core. + +A QAM must, therefore, implement certain abstract methods to manipulate classical and quantum state, such as loading +programs, writing to shared classical memory, and executing programs. + +The program execution itself is sent from pyQuil to quantum computer endpoints, which will be one of two options: + + - A Rigetti Quantum Virtual Machine (QVM) + - A Rigetti Quantum Processing Unit (QPU) + +Within pyQuil, there is a :py:class:`~pyquil.api.QVM` object and a :py:class:`~pyquil.api.QPU` object which use +the exposed APIs of the QVM and QPU servers, respectively. + +On this page, we'll learn a bit about the :ref:`QVM ` and :ref:`QPU `, then we will +show you how to use them from pyQuil with a :ref:`quantum_computer`. + +For information on constructing quantum programs, please refer back to :ref:`basics`. + +.. _qvm_use: + +The Quantum Virtual Machine (QVM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Rigetti Quantum Virtual Machine is an implementation of the Quantum Abstract Machine from +*A Practical Quantum Instruction Set Architecture*. [1]_ It is implemented in ANSI Common LISP and +executes programs specified in Quil. + +The QVM is a wavefunction simulation of unitary evolution with classical control flow +and shared quantum classical memory. + +The QVM is part of the Forest SDK, and it's available for you to use on your local machine. +After :ref:`downloading and installing the SDK `, you can initialize a local +QVM server by typing ``qvm -S`` into your terminal. You should see the following message. + +.. code:: python + + $ qvm -S + ****************************** + * Welcome to the Rigetti QVM * + ****************************** + Copyright (c) 2018 Rigetti Computing. + + (Configured with 2048 MiB of workspace and 8 workers.) + + [2018-11-06 18:18:18] Starting server on port 5000. + +As you can see, the server is started by default on port 5000, on your local machine. Consequently, the endpoint which +the pyQuil :py:class:`~pyquil.api.QVM` will default to for the QVM address is ``"http://127.0.0.1:5000"``. When you +run your program, a pyQuil client will send a Quil program to the QVM server and wait for a response back. + +It's also possible to use the QVM from the command line. You can write a Quil program in its own file: + +.. code:: python + + # example.quil + + DECLARE ro BIT[1] + RX(pi/2) 0 + CZ 0 1 + +and then execute it with the QVM directly from the command line: + +.. code:: python + + $ qvm -e < example.quil + + [2018-11-30 11:13:58] Reading program. + [2018-11-30 11:13:58] Allocating memory for QVM of 2 qubits. + [2018-11-30 11:13:58] Allocation completed in 4 ms. + [2018-11-30 11:13:58] Loading quantum program. + [2018-11-30 11:13:58] Executing quantum program. + [2018-11-30 11:13:58] Execution completed in 6 ms. + [2018-11-30 11:13:58] Printing 2-qubit state. + [2018-11-30 11:13:58] Amplitudes: + [2018-11-30 11:13:58] |00>: 0.0, P= 0.0% + [2018-11-30 11:13:58] |01>: 0.0-1.0i, P=100.0% + [2018-11-30 11:13:58] |10>: 0.0, P= 0.0% + [2018-11-30 11:13:58] |11>: 0.0, P= 0.0% + [2018-11-30 11:13:58] Classical memory (low -> high indexes): + [2018-11-30 11:13:58] ro: 1 0 + +For a detailed description of how to use the ``qvm`` from the command line, see :ref:`The QVM manual page ` or +type ``man qvm`` in your terminal. + +We also offer a Wavefunction Simulator (formerly a part of the :py:class:`~pyquil.api.QVM` object), +which allows users to contruct and inspect wavefunctions of quantum programs. Learn more +about the Wavefunction Simulator :ref:`here `. + +.. _qpu: + +The Quantum Processing Unit (QPU) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To access a QPU endpoint, you will have to `sign up `_ for Quantum Cloud Services (QCS). +Documentation for getting started with your Quantum Machine Image (QMI) is found +`here `_. Using QCS, you will ``ssh`` into your QMI, and reserve a +QPU lattice for a particular time block. + +When your reservation begins, you will be authorized to access the QPU. A configuration file will be automatically +populated for you with the proper QPU endpoint for your reservation. Both your QMI and the QPU are located on premises, +giving you low latency access to the QPU server. That server accepts jobs in the form of ``BinaryExecutableRequest``s, +which is precisely what you get back when you compile your program in pyQuil and target the QPU (more on this soon). +This request contains all the information necessary to run your program on the control rack which sends and receives +waveforms from the QPU, so that you can receive classified readout results (``0``s and ``1``s). + +For information on available lattices, you can check out your dashboard at https://qcs.rigetti.com/dashboard after you've +been invited to QCS. + + +.. _quantum_computer: + +The ``QuantumComputer`` +~~~~~~~~~~~~~~~~~~~~~~~ The :py:class:`~pyquil.api.QuantumComputer` abstraction offered by pyQuil provides an easy access point to the most critical objects used in pyQuil for building and executing your quantum programs. @@ -14,15 +128,17 @@ options. At a high level, the :py:class:`~pyquil.api.QuantumComputer` wraps around our favorite quantum computing tools: + - **A quantum abstract machine** ``.qam`` : this is our general purpose quantum computing device, + which implements the required abstract methods described :ref:`above `. It is implemented as a + :py:class:`~pyquil.api.QVM` or :py:class:`~pyquil.api.QPU` object in pyQuil. - **A compiler** ``.compiler`` : this determines how we manipulate the Quil input to something more efficient when possible, and then into a form which our QAM can accept as input. - **A device** ``.device`` : this specifies the topology and Instruction Set Architecture (ISA) of the targeted device by listing the supported 1Q and 2Q gates. - - **A quantum abstract machine** ``.qam`` : this is our general purpose quantum computing device, - which implements the required abstract methods to manipulate classical and quantum state, such as - loading programs, writing to shared classical memory, and executing programs. It is implemented as a :py:class:`~pyquil.api.QVM` - (quantum virtual machine) or - :py:class:`~pyquil.api.QPU` (quantum processing unit) object in pyQuil. + +When you instantiate a :py:class:`~pyquil.api.QuantumComputer` instance, these subcomponents will be compatible with +each other. So, if you get a ``QPU`` implementation for the ``.qam``, you will have a ``QPUCompiler`` for the +``.compiler``, and your ``.device`` will match the device used by the ``.compiler.`` The :py:class:`~pyquil.api.QuantumComputer` instance makes methods available which are built on the above objects. If you need more fine grained controls for your work, you might try exploring what is offered by these objects. @@ -44,7 +160,7 @@ much of which is already in your :ref:`config files <_advanced_usage>` (or provi Typically, you will want a :py:class:`~pyquil.api.QuantumComputer` which either: - pertains to a real, available QPU device - - is a QVM but mimics the topology of a QPU, with or without noise + - is a QVM but mimics the topology of a QPU - is some a generic QVM All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. @@ -61,14 +177,11 @@ All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. # Get a QPU qc = get_qc(QPU_LATTICE_NAME) # This is just a string naming the device - # Get a QVM with the same topology as the QPU lattice, without noise + # Get a QVM with the same topology as the QPU lattice qc = get_qc(QPU_LATTICE_NAME, as_qvm=True) # or, equivalently qc = get_qc(f"{QPU_LATTICE_NAME}-qvm") - # With noise - qc = get_qc(QPU_LATTICE_NAME, as_qvm=True, noisy=True) - # A fully connected QVM number_of_qubits = 10 qc = get_qc(f"{number_of_qubits}q-qvm") @@ -78,7 +191,7 @@ For now, you will have to join QCS to get ``QPU_LATTICE_NAME`` by running the If this sounds unfamiliar, check out our `documentation for QCS `_ and `join the waitlist `_. -For more information about creating your own noise models, check out :ref:`noise`. +For more information about creating and adding your own noise models, check out :ref:`noise`. .. note:: When connecting to a QVM locally (such as with ``get_qc(..., as_qvm=True)``) you'll have to set up the QVM @@ -225,7 +338,7 @@ Simulating the QPU using the QVM The :py:class:`~pyquil.api.QAM` methods are intended to be used in the same way, whether a QVM or QPU is being targeted. Everywhere on this page, -you can swap out the type of the QAM (quantum abstract machine -- remember, a QVM or a QPU) and you will still +you can swap out the type of the QAM (QVM <=> QPU) and you will still get reasonable results back. As long as the topology of the devices are the same, programs compiled and ran on the QVM will be able to run on the QPU and visa-versa. Since :py:class:`~pyquil.api.QuantumComputer` is built on the ``QAM`` abstract class, its methods will also work for both QAM implementations. @@ -239,52 +352,11 @@ This makes the QVM is a powerful tool for testing quantum programs before execut By simply providing ``as_qvm=True``, we get a QVM which will have the same topology as the named QPU. It's a good idea to run your programs against the QVM before booking QPU time to iron out -bugs. You can also provide ``noisy=True`` to get a noisy QVM. To learn more about how to add noise models to your virtual ``QuantumComputer`` instance, check out +bugs. To learn more about how to add noise models to your virtual ``QuantumComputer`` instance, check out :ref:`noise`. -.. _qvm_use: - -The Quantum Virtual Machine (QVM) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The pyQuil :py:class:`~pyquil.api.QVM` object, which fills the :py:class:`~pyquil.api.QuantumComputer` ``qam`` attribute, -is essentially a client around a Rigetti QVM endpoint. - -The Rigetti Quantum Virtual Machine is an implementation of the Quantum Abstract Machine from -*A Practical Quantum Instruction Set Architecture*. [1]_ It is implemented in ANSI Common LISP and -executes programs specified in the Quantum Instruction Language (Quil). - -Quil is an opinionated quantum instruction language: its basic belief is that in the near term quantum computers will -operate as coprocessors, working in 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. - -The QVM is a wavefunction simulation of unitary evolution with classical control flow -and shared quantum classical memory. - -The QVM is part of the Forest SDK, and it's available for you to use on your local machine. -After :ref:`downloading the SDK `, you can initialize a local -QVM server by typing ``qvm -S`` into your terminal. You should see the following message. - -.. code:: python - - $ qvm -S - ****************************** - * Welcome to the Rigetti QVM * - ****************************** - Copyright (c) 2018 Rigetti Computing. - - (Configured with 2048 MiB of workspace and 8 workers.) - - [2018-11-06 18:18:18] Starting server on port 5000. - -For a detailed description of how to use the ``qvm`` from the command line, see :ref:`The QVM manual page `. - - -We also offer a Wavefunction Simulator (formerly a part of the :py:class:`~pyquil.api.QVM` object), -which allows users to contruct and inspect wavefunctions of quantum programs. Learn more -about the Wavefunction Simulator :ref:`here `. For information on constructing quantum -programs, please refer back to :ref:`basics`. - +In the next section, we will see how to use the Wavefunction Simulator aspect of the Rigetti QVM to inspect the full +wavefunction set up by a Quil program. .. [1] https://arxiv.org/abs/1608.03355 From 08fbc8599a87c68800e6ba86848c47b4d047a305 Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Fri, 30 Nov 2018 17:07:23 -0800 Subject: [PATCH 03/13] Update docs/source/qvm.rst add missing gate import --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 203efcf91..c6d66f552 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -269,7 +269,7 @@ The above program would be written in this way to execute with ``run``: .. code:: python from pyquil import Program, get_qc - from pyquil.gates import X + from pyquil.gates import X, MEASURE qc = get_qc("8q-qvm") From a0277dcaae67c2b4a583cd6eeafec66bfaed72e1 Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Fri, 30 Nov 2018 17:07:53 -0800 Subject: [PATCH 04/13] Update docs/source/qvm.rst missing comma --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index c6d66f552..9dee9b524 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -319,7 +319,7 @@ and specify which edges exist. Here is an example, using the topology of our 16Q from pyquil.noise import decoherence_noise_with_asymmetric_ro qubits = [0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, 13, 14, 15, 16, 17] # qubits are numbered by octagon - edges = [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5) (5, 6), (6, 7), (7, 0), # first octagon + edges = [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7), (7, 0), # first octagon (1, 16), (2, 15), # connections across the square (10, 11), (11, 12), (13, 14), (14, 15), (15, 16), (16, 17), (10, 17)] # second octagon From 7b03a414279402eae032cb8ecbebede61df19c55 Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:08:13 -0800 Subject: [PATCH 05/13] Update docs/source/qvm.rst typo Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 9dee9b524..9d6d2c7a2 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -8,7 +8,7 @@ quantum instruction language: its basic belief is that in the near term quantum operate as coprocessors, working in concert with traditional CPUs. This means that Quil is designed to execute on a Quantum Abstract Machine (QAM) that has a shared classical/quantum architecture at its core. -A QAM must, therefore, implement certain abstract methods to manipulate classical and quantum state, such as loading +A QAM must, therefore, implement certain abstract methods to manipulate classical and quantum states, such as loading programs, writing to shared classical memory, and executing programs. The program execution itself is sent from pyQuil to quantum computer endpoints, which will be one of two options: From f7c3b7ac5c1b4d39d5f3602d6faa82455aca9470 Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:08:31 -0800 Subject: [PATCH 06/13] Update docs/source/qvm.rst amy is awesome Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 9d6d2c7a2..c432b1b93 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -19,7 +19,7 @@ The program execution itself is sent from pyQuil to quantum computer endpoints, Within pyQuil, there is a :py:class:`~pyquil.api.QVM` object and a :py:class:`~pyquil.api.QPU` object which use the exposed APIs of the QVM and QPU servers, respectively. -On this page, we'll learn a bit about the :ref:`QVM ` and :ref:`QPU `, then we will +On this page, we'll learn a bit about the :ref:`QVM ` and :ref:`QPU `. Then we will show you how to use them from pyQuil with a :ref:`quantum_computer`. For information on constructing quantum programs, please refer back to :ref:`basics`. From 41dca1eeab92a6c3cfba1ac01191ccb6528de36f Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Fri, 30 Nov 2018 17:09:16 -0800 Subject: [PATCH 07/13] Update docs/source/qvm.rst extra tilde --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index c432b1b93..9d196df28 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -27,7 +27,7 @@ For information on constructing quantum programs, please refer back to :ref:`bas .. _qvm_use: The Quantum Virtual Machine (QVM) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Rigetti Quantum Virtual Machine is an implementation of the Quantum Abstract Machine from *A Practical Quantum Instruction Set Architecture*. [1]_ It is implemented in ANSI Common LISP and From 46c722ec7645aa6b8904f1bed8b711489059c96f Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:10:00 -0800 Subject: [PATCH 08/13] Update docs/source/qvm.rst improved wording Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 9d196df28..0e9df6ae1 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -52,7 +52,7 @@ QVM server by typing ``qvm -S`` into your terminal. You should see the following [2018-11-06 18:18:18] Starting server on port 5000. -As you can see, the server is started by default on port 5000, on your local machine. Consequently, the endpoint which +By default, the server is started on port 5000 on your local machine. Consequently, the endpoint which the pyQuil :py:class:`~pyquil.api.QVM` will default to for the QVM address is ``"http://127.0.0.1:5000"``. When you run your program, a pyQuil client will send a Quil program to the QVM server and wait for a response back. From f8de781bf73ac03ca4dbc2f02d489b2deb7e185f Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:10:12 -0800 Subject: [PATCH 09/13] Update docs/source/qvm.rst Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 0e9df6ae1..1048d56fc 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -242,7 +242,7 @@ before running it, nor do you have to specify any ``MEASURE`` instructions; all results = qc.run_and_measure(p, trials=5) print(results) -Trials specifies how many times to run this program. Let's see our results: +``trials`` specifies how many times to run this program. Let's see our results: .. parsed-literal:: From 96e4056a674cb03bc39d590581a0ec61c037c9b1 Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:10:24 -0800 Subject: [PATCH 10/13] Update docs/source/qvm.rst Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 1048d56fc..a8ea779a4 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -343,7 +343,7 @@ get reasonable results back. As long as the topology of the devices are the same will be able to run on the QPU and visa-versa. Since :py:class:`~pyquil.api.QuantumComputer` is built on the ``QAM`` abstract class, its methods will also work for both QAM implementations. -This makes the QVM is a powerful tool for testing quantum programs before executing them on the QPU. +This makes the QVM a powerful tool for testing quantum programs before executing them on the QPU. .. code:: python From 1c70680f2a697f8fd794c7e113808cd613ac8622 Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:10:34 -0800 Subject: [PATCH 11/13] Update docs/source/qvm.rst Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index a8ea779a4..e37745cad 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -175,7 +175,7 @@ All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. from pyquil import get_qc # Get a QPU - qc = get_qc(QPU_LATTICE_NAME) # This is just a string naming the device + qc = get_qc(QPU_LATTICE_NAME) # The argument is just a string naming the device # Get a QVM with the same topology as the QPU lattice qc = get_qc(QPU_LATTICE_NAME, as_qvm=True) From 0169e609dc399051525d7dbefe4a7ee66cab3f0a Mon Sep 17 00:00:00 2001 From: Amy Brown <44273795+amyfbrown@users.noreply.github.com> Date: Fri, 30 Nov 2018 17:11:22 -0800 Subject: [PATCH 12/13] Update docs/source/qvm.rst Co-Authored-By: lcapelluto --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index e37745cad..13f6a77b2 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -161,7 +161,7 @@ Typically, you will want a :py:class:`~pyquil.api.QuantumComputer` which either: - pertains to a real, available QPU device - is a QVM but mimics the topology of a QPU - - is some a generic QVM + - is some generic QVM All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. From ae98c4ce9f48b3acd0f0edd6977a7ef68ba50558 Mon Sep 17 00:00:00 2001 From: Lauren Capelluto Date: Fri, 30 Nov 2018 19:14:07 -0800 Subject: [PATCH 13/13] Update docs/source/qvm.rst --- docs/source/qvm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/qvm.rst b/docs/source/qvm.rst index 13f6a77b2..ffd697216 100644 --- a/docs/source/qvm.rst +++ b/docs/source/qvm.rst @@ -175,7 +175,7 @@ All of this can be accomplished with :py:func:`~pyquil.api.get_qc`. from pyquil import get_qc # Get a QPU - qc = get_qc(QPU_LATTICE_NAME) # The argument is just a string naming the device + qc = get_qc(QPU_LATTICE_NAME) # QPU_LATTICE_NAME is just a string naming the device # Get a QVM with the same topology as the QPU lattice qc = get_qc(QPU_LATTICE_NAME, as_qvm=True)