Unverified Commit 67456992 authored by Mccaskey, Alex's avatar Mccaskey, Alex Committed by GitHub
Browse files

Merge pull request #97 from zpparks314/master

Editing documentation for new Python decorator API
parents e376b38d 7b1def38
Pipeline #28234 passed with stages
in 8 minutes and 59 seconds
...@@ -263,10 +263,10 @@ xacc quantum kernel written in Quil) ...@@ -263,10 +263,10 @@ xacc quantum kernel written in Quil)
Python JIT VQE Decorator Python JIT VQE Decorator
++++++++++++++++++++++++ ++++++++++++++++++++++++
The easiest way to run the VQE algorithm with XACC-VQE is to leverage the The easiest way to run the VQE algorithm with XACC-VQE is to leverage the
``xacc.qpu.vqe`` decorator. This decorator builds on the ``xacc.qpu`` decorator ``xacc.qpu`` decorator. Using the ``algo`` decorator argument, it is possible to specify that the function
and gives users an opportunity to define the VQE ansatz as a single Python function, will run VQE with the given ansatz ciruit and parameters. This gives users an opportunity
and through this algorithmic decoration, execute the VQE algorithm given some set to define the VQE ansatz as a single Python function, and through this algorithmic decoration,
of decorator arguments. Let's look at an example execute the VQE algorithm according to the other decorator arguments. Let's look at an example
.. code:: .. code::
...@@ -285,7 +285,7 @@ of decorator arguments. Let's look at an example ...@@ -285,7 +285,7 @@ of decorator arguments. Let's look at an example
PauliOperator({0:'Z'}, .21829) + \ PauliOperator({0:'Z'}, .21829) + \
PauliOperator({1:'Z'}, -6.125) PauliOperator({1:'Z'}, -6.125)
@xaccvqe.qpu.vqe(accelerator=tnqvm, observable=ham) @xacc.qpu(algo='vqe', accelerator=tnqvm, observable=ham)
def ansatz(buffer, t0): def ansatz(buffer, t0):
X(0) X(0)
Ry(t0, 1) Ry(t0, 1)
...@@ -299,7 +299,7 @@ of decorator arguments. Let's look at an example ...@@ -299,7 +299,7 @@ of decorator arguments. Let's look at an example
print('Energy = ', buffer.getInformation('vqe-energy')) print('Energy = ', buffer.getInformation('vqe-energy'))
print('Opt Angles = ', buffer.getInformation('vqe-angles')) print('Opt Angles = ', buffer.getInformation('vqe-angles'))
After running the VQE algorithm with the above example script, the ``AcceleratorBuffer`` now stores the information regarding the results of the executions. The XACC Python API enables the user to easily access this information stored in the ``AcceleratorBuffer`` and its children. After running the VQE algorithm with the above example script, the ``AcceleratorBuffer`` now stores the information regarding the results of the executions. The XACC Python API enables the user to easily access this information stored in the ``AcceleratorBuffer`` and its children.
.. code:: .. code::
...@@ -327,8 +327,8 @@ After running the VQE algorithm with the above example script, the ``Accelerator ...@@ -327,8 +327,8 @@ After running the VQE algorithm with the above example script, the ``Accelerator
"parameters": [ "parameters": [
0.5 0.5
] ]
}, },
... ...
{ {
"name": "X0X1", "name": "X0X1",
...@@ -344,8 +344,8 @@ After running the VQE algorithm with the above example script, the ``Accelerator ...@@ -344,8 +344,8 @@ After running the VQE algorithm with the above example script, the ``Accelerator
} }
] ]
} }
... ...
For example, if the user wanted to generate a file consisting of the relevant, unique results of the VQE algorithm executions stored in the ``AcceleratorBuffer`` children as comma-separated values, it can be done as shown below, using the ``getAllUnique``, ``getChildren``, and ``getInformation`` methods. For example, if the user wanted to generate a file consisting of the relevant, unique results of the VQE algorithm executions stored in the ``AcceleratorBuffer`` children as comma-separated values, it can be done as shown below, using the ``getAllUnique``, ``getChildren``, and ``getInformation`` methods.
.. code:: .. code::
...@@ -362,4 +362,3 @@ For example, if the user wanted to generate a file consisting of the relevant, u ...@@ -362,4 +362,3 @@ For example, if the user wanted to generate a file consisting of the relevant, u
f.write(','+str(c.getInformation('exp-val-z'))) f.write(','+str(c.getInformation('exp-val-z')))
f.write(','+str(energy)+'\n') f.write(','+str(energy)+'\n')
f.close() f.close()
\ No newline at end of file
...@@ -296,21 +296,20 @@ These Pythonic functions can then be consumed by a custom ``xacc.qpu`` class dec ...@@ -296,21 +296,20 @@ These Pythonic functions can then be consumed by a custom ``xacc.qpu`` class dec
the source code for these functions can be converted to a string with the ``inspect`` the source code for these functions can be converted to a string with the ``inspect``
module, and compiled with this PyXACCCompiler implementation. module, and compiled with this PyXACCCompiler implementation.
The PyXACC Antlr grammar also defines an ``xacc()`` instruction, which takes as The PyXACC Antlr grammar also defines syntax for generating XACC ``IR`` function instances using any
its first argument the name of the IRGenerator you would like to use to generate of the installed and available XACC ``IRGenerator`` interfaces.
the function. This argument can be followed by any key-value arguments.
Imagine we have an IRGenerator that produces a UCCSD circuit based on the number of Imagine we have an ``IRGenerator`` that produces a UCCSD circuit based on the number of
qubits and electrons in the problem. We could define a Python function like this to qubits and electrons in the problem. We could define a Python function like this to
create this circuit (instead of arduously typing out all the instructions) create this circuit (instead of arduously typing out all the instructions)
.. code:: .. code::
def uccsd(buffer, *args): def uccsd(buffer, *args):
xacc(uccsd, n_qubits=4, n_electrons=2) uccsd(n_qubits=4, n_electrons=2)
Measure(0,0) Measure(0,0)
The above code would generate the a UCCSD circuit on 4 qubits and 2 fermions The above code would generate the UCCSD circuit on 4 qubits and 2 fermions
and measure the first qubit, giving an estimated expectation value with respect to and measure the first qubit, giving an estimated expectation value with respect to
the ``Z`` operator for Hamiltonian term ``<Z0>``. the ``Z`` operator for Hamiltonian term ``<Z0>``.
......
...@@ -60,7 +60,7 @@ on. Execution of this code on the IBM QPU is then affected by simply calling thi ...@@ -60,7 +60,7 @@ on. Execution of this code on the IBM QPU is then affected by simply calling thi
function. The results of the execution are stored on the users allocated ``AcceleratorBuffer``. function. The results of the execution are stored on the users allocated ``AcceleratorBuffer``.
Finally we cleanup the framework with the ``xacc.Finalize()`` call. Finally we cleanup the framework with the ``xacc.Finalize()`` call.
``xacc()`` Instruction and IRGenerators IRGenerator Interfaces
+++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++
XACC exposes an extensible interface for the generation of ``IR`` instances based XACC exposes an extensible interface for the generation of ``IR`` instances based
on simple input parameters (this differentiates it from ``Compilers`` which also on simple input parameters (this differentiates it from ``Compilers`` which also
...@@ -80,17 +80,16 @@ provide ``QFT`` and ``InverseQFT`` ``IRGenerators``). ...@@ -80,17 +80,16 @@ provide ``QFT`` and ``InverseQFT`` ``IRGenerators``).
The XACC Python PyXACCCompiler language provides an instruction that lets users The XACC Python PyXACCCompiler language provides an instruction that lets users
express this ``IRGenerator`` generation step on a single line of quantum code. To do so, express this ``IRGenerator`` generation step on a single line of quantum code. To do so,
in addition to standard gates and ``qmi`` instructions, this language defines an in addition to standard gates and ``qmi`` instructions, this language defines
``xacc()`` instruction that takes as its first input the name of the IRGenerator instructions as the name of any availabe ``IRGenerator`` taking as input any key-value
to be used in building up the quantum kernel, followed by any key-value pair arguments. pair arguments required to generate the ``IR`` instance. Here's an example of generating
Here's an example of generating a hardware-efficient ansatz used in a variational a hardware-efficient ansatz used in a variational quantum eigensolver routine
quantum eigensolver routine
.. code:: .. code::
@xacc.qpu(accelerator=ibm) @xacc.qpu(accelerator=ibm)
def hwe(buffer, *args): def hwe(buffer, *args):
xacc(hwe, layers=2, n_qubits=2, connectivity='[[0,1]]') hwe(layers=2, n_qubits=2, connectivity='[[0,1]]')
This would generate the following circuit This would generate the following circuit
...@@ -124,8 +123,8 @@ This would generate the following circuit ...@@ -124,8 +123,8 @@ This would generate the following circuit
init = np.random.uniform(low=-np.pi,high=np.pi, size=(hwe.nParameters(),)) init = np.random.uniform(low=-np.pi,high=np.pi, size=(hwe.nParameters(),))
hwe(buffer, *init) hwe(buffer, *init)
This ``xacc()`` instruction can be used with any available ``IRGenerator`` present Any available ``IRGenerator`` present in the XACC framework can be used in this way
in the XACC framework. to instantiate an ``IR`` instance for execution on a QPU.
D-Wave Python JIT D-Wave Python JIT
+++++++++++++++++ +++++++++++++++++
...@@ -164,8 +163,8 @@ biases and couplers can be runtime parameters. See below for an example. ...@@ -164,8 +163,8 @@ biases and couplers can be runtime parameters. See below for an example.
xacc.Finalize() xacc.Finalize()
Or, if we have an ``IRGenerator`` for a D-Wave problem, we could use the ``xacc()`` Or, if we have an ``IRGenerator`` for a D-Wave problem, we could use the name of the ``IRGenerator`` as an instruction
instruction. Imagine we have an ``IRGenerator`` implemented that takes an integer ``N`` to create the D-Wave IR instance. Imagine we have an ``IRGenerator`` implemented that takes an integer ``N``
and creates a D-Wave IR instance that factors ``N`` into its constituent primes. and creates a D-Wave IR instance that factors ``N`` into its constituent primes.
Our code would look like this Our code would look like this
...@@ -186,7 +185,7 @@ Our code would look like this ...@@ -186,7 +185,7 @@ Our code would look like this
# IR Generator # IR Generator
@xacc.qpu(accelerator='dwave') @xacc.qpu(accelerator='dwave')
def factor15(buffer): def factor15(buffer):
xacc(dwave-factoring, n=15) dwave-factoring(n=15)
# Factor 15 on the D-Wave # Factor 15 on the D-Wave
factor15(buffer) factor15(buffer)
...@@ -377,36 +376,36 @@ from file. ...@@ -377,36 +376,36 @@ from file.
Extending XACC with Plugins Extending XACC with Plugins
--------------------------- ---------------------------
XACC provides a modular, service-oriented architecture. Plugins can XACC provides a modular, service-oriented architecture. Plugins can
be contributed to the framework providing new Compilers, Accelerators, be contributed to the framework providing new Compilers, Accelerators,
Instructions, IR Transformations, IRGenerators, etc. Instructions, IR Transformations, IRGenerators, etc.
XACC provides a plugin-generator that will create a new plugin project XACC provides a plugin-generator that will create a new plugin project
with all boilerplate code provided. Developers just implement the with all boilerplate code provided. Developers just implement the
pertinent methods for the plugin (like the ``compile()`` method for pertinent methods for the plugin (like the ``compile()`` method for
new Compilers). Contributing the plugins after the pertinent methods have new Compilers). Contributing the plugins after the pertinent methods have
been implemented is as simple as ``make install``. been implemented is as simple as ``make install``.
.. note:: .. note::
Note that to use the XACC plugin-generator you must have XACC installed Note that to use the XACC plugin-generator you must have XACC installed
from source (you cannot use the pip install) and your XACC must be built from source (you cannot use the pip install) and your XACC must be built
with Python support. with Python support.
To generate new plugins, users/developers can run the following command To generate new plugins, users/developers can run the following command
.. code:: .. code::
$ python3 -m xacc generate-plugin -t compiler -n awesome $ python3 -m xacc generate-plugin -t compiler -n awesome
Here we use the XACC python module to generate a new ``Compiler`` plugin with the Here we use the XACC python module to generate a new ``Compiler`` plugin with the
name ``awesome``. You should see a new ``xacc-awesome`` folder that contains ``CMakeLists.txt`` and name ``awesome``. You should see a new ``xacc-awesome`` folder that contains ``CMakeLists.txt`` and
``README.md`` files (the CMake file is a working build file ready for use). You should ``README.md`` files (the CMake file is a working build file ready for use). You should
also see ``compiler`` and ``tests`` folders with stubbed out code ready for implementation. also see ``compiler`` and ``tests`` folders with stubbed out code ready for implementation.
You as the developer can now implement your custom quantum kernel compilation routine and You as the developer can now implement your custom quantum kernel compilation routine and
any unit test you would like (as a Google Test). Then, to build, test, and contribute the plugin any unit test you would like (as a Google Test). Then, to build, test, and contribute the plugin
to your XACC framework instance, run the following from the top-level of the ``xacc-awesome`` to your XACC framework instance, run the following from the top-level of the ``xacc-awesome``
folder: folder:
.. code:: .. code::
...@@ -416,10 +415,10 @@ folder: ...@@ -416,10 +415,10 @@ folder:
$ make install $ make install
$ ctest $ ctest
This will build, install, and run your tests on the Compiler plugin you have just This will build, install, and run your tests on the Compiler plugin you have just
created. created.
The instructions for other plugins are similar. The instructions for other plugins are similar.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment