PyQVM

docs/source/apidocs/qam.rst

@@ -9,10 +9,11 @@ quantum/classical quil programs on either a Quantum Virtual Machine (QVM, a clas
 or a Quantum Processor Unit (QPU, a real quantum device).
 
 
-.. currentmodule:: pyquil.api
 .. autosummary::
     :toctree: autogen
+    :template: autosumm.rst
 
-    _qam.QAM
-    QPU
-    QVM
+    ~pyquil.api._qam.QAM
+    ~pyquil.api.QPU
+    ~pyquil.api.QVM
+    ~pyquil.pyqvm.PyQVM

docs/source/apidocs/simulators.rst

@@ -0,0 +1,43 @@
+Simulators
+==========
+
+QVMs promise to behave like a real QPU. However, under-the-hood there is usually a simulation
+that has fewer constraints than a physical device. For example, in a wavefunction (or statevector)
+simulation, you can directly inspect amplitudes and probabilities.
+
+
+.. currentmodule:: pyquil
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    ~pyquil.api.WavefunctionSimulator
+    ~pyquil.reference_simulator.ReferenceWavefunctionSimulator
+    ~pyquil.reference_simulator.ReferenceDensitySimulator
+    ~pyquil.numpy_simulator.NumpyWavefunctionSimulator
+
+
+Reference Utilities
+-------------------
+
+.. currentmodule:: pyquil.unitary_tools
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    lifted_pauli
+    lifted_gate
+    program_unitary
+    all_bitstrings
+
+
+Numpy Utilities
+---------------
+
+.. currentmodule:: pyquil.numpy_simulator
+.. autosummary::
+    :toctree: autogen
+    :template: autosumm.rst
+
+    targeted_einsum
+    targeted_tensordot

docs/source/index.rst

@@ -94,7 +94,7 @@ Contents
    apidocs/compilers
    apidocs/qam
    apidocs/devices
-   apidocs/wavefunction
+   apidocs/simulators
    apidocs/noise
 
 .. toctree::

docs/source/migration.ipynb

@@ -91,7 +91,7 @@
    "source": [
     "#### The new way\n",
     "\n",
-    "`WavefunctionSimulator` encapsulates all functionality that requires peering into a wavefunction. This also opens the door for different types of simulators other than those backed by a wavefunction. For example, you can simulate a quantum circuit with a density matrix simulation or a path integral simulation."
+    "PyQuil has a built-in numpy-based wavefunction simulator that is reasonably performant and easy to interact with."
    ]
   },
   {
@@ -103,14 +103,56 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "(0.7071067812+0j)|00> + (0.7071067812+0j)|11>\n"
+      "as a n_qubit-index tensor:\n",
+      " [[0.70710678+0.j 0.        +0.j]\n",
+      " [0.        +0.j 0.70710678+0.j]]\n",
+      "flattened:\n",
+      " [0.70710678+0.j 0.        +0.j 0.        +0.j 0.70710678+0.j]\n"
+     ]
+    }
+   ],
+   "source": [
+    "from pyquil.numpy_simulator import NumpyWavefunctionSimulator\n",
+    "sim = NumpyWavefunctionSimulator(n_qubits=2)\n",
+    "sim = sim.do_program(program)\n",
+    "print(\"as a n_qubit-index tensor:\\n\", sim.wf)\n",
+    "print(\"flattened:\\n\", sim.wf.reshape(-1))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The wavefunction is persisted across multiple calls to `do_program`. Consider calling `reset`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Without resetting\n",
+      "[[0.70710678+0.j 0.        +0.j]\n",
+      " [0.        +0.j 0.70710678+0.j]]\n",
+      "With resetting\n",
+      "[[1.+0.j 0.+0.j]\n",
+      " [0.+0.j 0.+0.j]]\n"
      ]
     }
    ],
    "source": [
-    "from pyquil.api import WavefunctionSimulator\n",
-    "wfn = WavefunctionSimulator().wavefunction(program)\n",
-    "print(wfn)"
+    "sim.do_gate(I(0))\n",
+    "print(\"Without resetting\")\n",
+    "print(sim.wf)\n",
+    "\n",
+    "print(\"With resetting\")\n",
+    "sim.reset()\n",
+    "sim.do_gate(I(0))\n",
+    "print(sim.wf)"
    ]
   },
   {
@@ -126,7 +168,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
     {
@@ -157,7 +199,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -186,7 +228,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -210,14 +252,14 @@
    "metadata": {},
    "source": [
     "#### The new way\n",
-    "If you want analytical expectation values, the solution is to use `WavefunctionSimulator.expectation`\n",
+    "If you want analytical expectation values, the solution is to use the `expectation` method on `NumpyWavefunctionSimulator`. In lieu of a `prep_program` argument, call `do_program` beforehand and your wavefunction will persist.\n",
     "\n",
-    "Note that the method is not named `pauli_expectation` as we do not support the pyQuil<1.9 way of using `Program`s to represent `PauliSum`s"
+    "This should allow you to prepare a wavefunction once and measure multiple expectation values or measure expectation values in the middle of programs."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {
@@ -231,8 +273,9 @@
     }
    ],
    "source": [
+    "sim = NumpyWavefunctionSimulator(n_qubits=2).do_program(program)\n",
     "for observable in [z0, z1, xor]:\n",
-    "    expectation = WavefunctionSimulator().expectation(prep_prog=program, pauli_terms=observable)\n",
+    "    expectation = sim.expectation(observable)\n",
     "    print(observable, '\\t', expectation)"
    ]
   },
@@ -288,7 +331,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -308,7 +351,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {