Update freezing orbitals documentation

circuit_knitting/forging/entanglement_forging_ground_state_solver.py

@@ -139,7 +139,7 @@ def __init__(
             optimizer: Optimizer to use to optimize the ansatz circuit parameters
             initial_point: Initial values for ansatz parameters
             orbitals_to_reduce: List of orbital indices to remove from the problem before
-                decomposition.
+                decomposition. See :ref:`Freezing orbitals` for more information.
             backend_names: Backend name or list of backend names to use during parallel computation
             options: Options or list of options to be applied to the backends
             mo_coeff: Coefficients for converting an input problem to MO basis

docs/entanglement_forging/explanation/index.rst

@@ -138,28 +138,6 @@ orbital). Furthermore, in the case of water, it turns out that orbital 3
 symmetry to the other orbitals, so excitations to orbital 3 are
 suppressed. For water, we thus freeze orbitals 0 and 3.
 
-
-Example: Water molecule
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The total number of orbitals (core + valence) = 7 orbitals
-
-Frozen orbital approximation = 2 orbitals
-
-Active space orbitals = total number of orbitals – frozen orbitals = 5
-orbitals (bitstring size is set to 5)
-
-Leading excitation analysis = 3 unique bitstrings
-
-.. code:: python
-
-    >>> from circuit_knitting.utils import reduce_bitstrings
-    >>> orbitals_to_reduce = [0,3]
-    >>> bitstrings = [(1,1,1,1,1,0,0), (1,0,1,1,1,0,1), (1,0,1,1,1,1,0)]
-    >>> reduced_bitstrings = reduce_bitstrings(bitstrings, orbitals_to_reduce)
-    >>> print(f'Bitstrings after orbital reduction: {reduced_bitstrings}')
-    Bitstrings after orbital reduction: [[1, 1, 1, 0, 0], [0, 1, 1, 0, 1], [0, 1, 1, 1, 0]]
-
 A complete example is provided in the `guide on freezing orbitals <../how-tos/freeze-orbitals.ipynb>`_.
 
 .. _Picking the bitstrings:

docs/entanglement_forging/how-tos/freeze-orbitals.ipynb

@@ -37,7 +37,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "First, we set up the $\\mathrm{H}_2\\mathrm{O}$ molecule, specify the driver and converter, and instantiate an `ElectronicStructureProblem`."
+    "First, we set up the $\\mathrm{H}_2\\mathrm{O}$ molecule, specify the driver and converter, and instantiate an `ElectronicStructureProblem`. The total number of orbitals (core + valence) is seven."
    ]
   },
   {
@@ -71,13 +71,43 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Create the ansatz with a reduced set of bitstrings."
+    "Since the execution time scales exponentially in the number of orbitals, it’s a good idea to simplify the problem (if possible) by eliminating some of the orbitals. Some knowledge of chemistry is useful when picking orbitals to freeze. One good rule of thumb is to freeze the core orbital. For $H^2O$, this is the core oxygen $1s$ orbital, which corresponds to qubit 0. Furthermore, in the case of $H^2O$, the out-of-plane oxygen $2p$ orbital, corresponding to qubit 3, has different symmetry to the other orbitals, so we freeze it as well. For $H^2O$, we thus freeze orbitals 0 and 3, resulting in length-5 bitstrings."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 3,
    "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[(1, 1, 1, 0, 0), (0, 1, 1, 0, 1), (0, 1, 1, 1, 0)]"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "orbitals_to_reduce = [0, 3]\n",
+    "bitstrings_u = [(1, 1, 1, 1, 1, 0, 0), (1, 0, 1, 1, 1, 0, 1), (1, 0, 1, 1, 1, 1, 0)]\n",
+    "reduced_bitstrings = reduce_bitstrings(bitstrings_u, orbitals_to_reduce)\n",
+    "reduced_bitstrings"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Create the ansatz circuit. Since we have frozen two orbitals, the size of our active space has been decreased from 7 to 5, so we create a 5-qubit ansatz circuit. Finally, we instantiate an ``EntanglementForgingAnsatz``, which contains the ansatz circuit and the reduced bitstrings."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -108,7 +138,7 @@
        "     └───────────────┘└──────────────┘└───────────────┘"
       ]
      },
-     "execution_count": 3,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -139,11 +169,6 @@
     "circuit_u.append(hop_gate.to_gate({theta: theta_3}), [0, 2])\n",
     "circuit_u.append(hop_gate.to_gate({theta: theta_4}), [3, 4])\n",
     "\n",
-    "# Set our bitstrings, and then reduce the chosen orbitals\n",
-    "orbitals_to_reduce = [0, 3]\n",
-    "bitstrings_u = [(1, 1, 1, 1, 1, 0, 0), (1, 0, 1, 1, 1, 0, 1), (1, 0, 1, 1, 1, 1, 0)]\n",
-    "reduced_bitstrings = reduce_bitstrings(bitstrings_u, orbitals_to_reduce)\n",
-    "\n",
     "ansatz = EntanglementForgingAnsatz(circuit_u=circuit_u, bitstrings_u=reduced_bitstrings)\n",
     "\n",
     "ansatz.circuit_u.draw()"
@@ -158,7 +183,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -177,13 +202,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/html": [
-       "<h3>Version Information</h3><table><tr><th>Qiskit Software</th><th>Version</th></tr><tr><td><code>qiskit-terra</code></td><td>0.24.0</td></tr><tr><td><code>qiskit-aer</code></td><td>0.12.0</td></tr><tr><td><code>qiskit-ibmq-provider</code></td><td>0.20.2</td></tr><tr><td><code>qiskit-nature</code></td><td>0.6.0</td></tr><tr><th>System information</th></tr><tr><td>Python version</td><td>3.8.16</td></tr><tr><td>Python compiler</td><td>Clang 14.0.6 </td></tr><tr><td>Python build</td><td>default, Mar  1 2023 21:19:10</td></tr><tr><td>OS</td><td>Darwin</td></tr><tr><td>CPUs</td><td>8</td></tr><tr><td>Memory (Gb)</td><td>32.0</td></tr><tr><td colspan='2'>Sun Jun 18 20:55:50 2023 CDT</td></tr></table>"
+       "<h3>Version Information</h3><table><tr><th>Qiskit Software</th><th>Version</th></tr><tr><td><code>qiskit-terra</code></td><td>0.24.1</td></tr><tr><td><code>qiskit-aer</code></td><td>0.12.1</td></tr><tr><td><code>qiskit-ibmq-provider</code></td><td>0.20.2</td></tr><tr><td><code>qiskit</code></td><td>0.43.2</td></tr><tr><td><code>qiskit-nature</code></td><td>0.6.0</td></tr><tr><th>System information</th></tr><tr><td>Python version</td><td>3.8.16</td></tr><tr><td>Python compiler</td><td>Clang 14.0.6 </td></tr><tr><td>Python build</td><td>default, Mar  1 2023 21:19:10</td></tr><tr><td>OS</td><td>Darwin</td></tr><tr><td>CPUs</td><td>8</td></tr><tr><td>Memory (Gb)</td><td>32.0</td></tr><tr><td colspan='2'>Tue Jul 11 12:13:03 2023 CDT</td></tr></table>"
       ],
       "text/plain": [
        "<IPython.core.display.HTML object>"