Merge pull request #97 from zpparks314/master

Editing documentation for new Python decorator API

docs/source/apps.rst

@@ -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

docs/source/plugins.rst

@@ -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>``.
 

docs/source/tutorials.rst

@@ -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.