Merge pull request #30 from rigetticomputing/feature/run-quil-script

Feature/run quil script

docs/source/getting_started.rst

@@ -116,8 +116,26 @@ 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>
 
-Basic Usage
------------
+Running your first quantum program
+----------------------------------
+pyQuil is a Python library that helps you write programs in the Quantum Instruction Language (Quil).
+It also ships with a simple script ``examples/run_quil.py`` that runs Quil code directly. You can
+test your connection to Forest using this script by executing the following on your command line
+
+::
+
+    cd examples/
+    run_quil.py hello_world.quil
+
+You should see the following output array ``[[1, 0, 0, 0, 0, 0, 0, 0]]``. This indicates that you have
+a good connection to our API.
+
+You can continue to write more Quil code in files and run them using the ``run_quil.py`` script. The
+following sections describe how to use the pyQuil library directly to build quantum programs in
+Python.
+
+Basic pyQuil Usage
+------------------
 
 To ensure that your installation is working correctly, try running the
 following Python commands interactively. First, import the ``quil``

examples/hello_world.quil

@@ -0,0 +1,2 @@
+X 0
+MEASURE 0 [0]

examples/run_quil.py

@@ -0,0 +1,33 @@
+"""
+This module run basic Quil text files agains the Forest QVM API. Usage
+"""
+import sys
+
+from pyquil.quil import Program
+import pyquil.forest as forest
+
+qvm = forest.Connection()
+
+help_string = "Script takes two arguments. Quil program filename is required as the first " \
+              "argument and number of classical registers to return is the optional second " \
+              "argument (defaults to 8)."
+
+if __name__ == '__main__':
+    assert len(sys.argv) == 2 or len(sys.argv) == 3, help_string
+    if sys.argv[1] == '-h' or sys.argv[1] == '--help':
+        print help_string
+        sys.exit()
+    filepath = str(sys.argv[1])
+    if len(sys.argv) == 3:
+        classical_register_num = int(sys.argv[2])
+    else:
+        classical_register_num = 8
+
+    with open(filepath) as file:
+        quil_prog = file.read()
+        p = Program(quil_prog)
+
+    print "Running Quil Program from: ", filepath
+    print "---------------------------"
+    print "Output: "
+    print qvm.run(p, range(classical_register_num))