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)
Python JIT VQE Decorator
++++++++++++++++++++++++
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
and gives users an opportunity to define the VQE ansatz as a single Python function,
and through this algorithmic decoration, execute the VQE algorithm given some set
of decorator arguments. Let's look at an example
``xacc.qpu`` decorator. Using the ``algo`` decorator argument, it is possible to specify that the function
will run VQE with the given ansatz ciruit and parameters. This gives users an opportunity
to define the VQE ansatz as a single Python function, and through this algorithmic decoration,
execute the VQE algorithm according to the other decorator arguments. Let's look at an example
.. code::
......@@ -285,7 +285,7 @@ of decorator arguments. Let's look at an example
PauliOperator({0:'Z'}, .21829) + \
PauliOperator({1:'Z'}, -6.125)
@xaccvqe.qpu.vqe(accelerator=tnqvm, observable=ham)
@xacc.qpu(algo='vqe', accelerator=tnqvm, observable=ham)
def ansatz(buffer, t0):
X(0)
Ry(t0, 1)
......@@ -299,7 +299,7 @@ of decorator arguments. Let's look at an example
print('Energy = ', buffer.getInformation('vqe-energy'))
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::
......@@ -327,8 +327,8 @@ After running the VQE algorithm with the above example script, the ``Accelerator
"parameters": [
0.5
]
},
},
...
{
"name": "X0X1",
......@@ -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.
.. code::
......@@ -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(energy)+'\n')
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
the source code for these functions can be converted to a string with the ``inspect``
module, and compiled with this PyXACCCompiler implementation.
The PyXACC Antlr grammar also defines an ``xacc()`` instruction, which takes as
its first argument the name of the IRGenerator you would like to use to generate
the function. This argument can be followed by any key-value arguments.
The PyXACC Antlr grammar also defines syntax for generating XACC ``IR`` function instances using any
of the installed and available XACC ``IRGenerator`` interfaces.
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
create this circuit (instead of arduously typing out all the instructions)
.. code::
def uccsd(buffer, *args):
xacc(uccsd, n_qubits=4, n_electrons=2)
uccsd(n_qubits=4, n_electrons=2)
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
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
function. The results of the execution are stored on the users allocated ``AcceleratorBuffer``.
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
on simple input parameters (this differentiates it from ``Compilers`` which also
......@@ -80,17 +80,16 @@ provide ``QFT`` and ``InverseQFT`` ``IRGenerators``).
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,
in addition to standard gates and ``qmi`` instructions, this language defines an
``xacc()`` instruction that takes as its first input the name of the IRGenerator
to be used in building up the quantum kernel, followed by any key-value pair arguments.
Here's an example of generating a hardware-efficient ansatz used in a variational
quantum eigensolver routine
in addition to standard gates and ``qmi`` instructions, this language defines
instructions as the name of any availabe ``IRGenerator`` taking as input any key-value
pair arguments required to generate the ``IR`` instance. Here's an example of generating
a hardware-efficient ansatz used in a variational quantum eigensolver routine
.. code::
@xacc.qpu(accelerator=ibm)
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
......@@ -124,8 +123,8 @@ This would generate the following circuit
init = np.random.uniform(low=-np.pi,high=np.pi, size=(hwe.nParameters(),))
hwe(buffer, *init)
This ``xacc()`` instruction can be used with any available ``IRGenerator`` present
in the XACC framework.
Any available ``IRGenerator`` present in the XACC framework can be used in this way
to instantiate an ``IR`` instance for execution on a QPU.
D-Wave Python JIT
+++++++++++++++++
......@@ -164,8 +163,8 @@ biases and couplers can be runtime parameters. See below for an example.
xacc.Finalize()
Or, if we have an ``IRGenerator`` for a D-Wave problem, we could use the ``xacc()``
instruction. Imagine we have an ``IRGenerator`` implemented that takes an integer ``N``
Or, if we have an ``IRGenerator`` for a D-Wave problem, we could use the name of the ``IRGenerator`` as an instruction
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.
Our code would look like this
......@@ -186,7 +185,7 @@ Our code would look like this
# IR Generator
@xacc.qpu(accelerator='dwave')
def factor15(buffer):
xacc(dwave-factoring, n=15)
dwave-factoring(n=15)
# Factor 15 on the D-Wave
factor15(buffer)
......@@ -377,36 +376,36 @@ from file.
Extending XACC with Plugins
---------------------------
XACC provides a modular, service-oriented architecture. Plugins can
be contributed to the framework providing new Compilers, Accelerators,
Instructions, IR Transformations, IRGenerators, etc.
XACC provides a plugin-generator that will create a new plugin project
with all boilerplate code provided. Developers just implement the
pertinent methods for the plugin (like the ``compile()`` method for
new Compilers). Contributing the plugins after the pertinent methods have
XACC provides a modular, service-oriented architecture. Plugins can
be contributed to the framework providing new Compilers, Accelerators,
Instructions, IR Transformations, IRGenerators, etc.
XACC provides a plugin-generator that will create a new plugin project
with all boilerplate code provided. Developers just implement the
pertinent methods for the plugin (like the ``compile()`` method for
new Compilers). Contributing the plugins after the pertinent methods have
been implemented is as simple as ``make install``.
.. note::
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
with Python support.
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
with Python support.
To generate new plugins, users/developers can run the following command
.. code::
$ python3 -m xacc generate-plugin -t compiler -n awesome
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
``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.
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
``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.
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
to your XACC framework instance, run the following from the top-level of the ``xacc-awesome``
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
to your XACC framework instance, run the following from the top-level of the ``xacc-awesome``
folder:
.. code::
......@@ -416,10 +415,10 @@ folder:
$ make install
$ ctest
This will build, install, and run your tests on the Compiler plugin you have just
created.
This will build, install, and run your tests on the Compiler plugin you have just
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