update intro notebook

docs/tutorials/01-introduction.ipynb

@@ -8,7 +8,7 @@
     "\n",
     "ffsim is a software library for simulating fermionic quantum circuits that conserve particle number and the Z component of spin. By taking advantage of these symmetries, it can simulate these circuits much more efficiently than a generic quantum circuit simulator.\n",
     "\n",
-    "ffsim is a rather \"low-level\" software library. It does not have a class for representing quantum circuits. The primary way of using ffsim is by calling functions that transform statevectors represented directly as NumPy arrays. As an example, the following code shows how to create a Slater determinant and apply an orbital rotation to it."
+    "The primary way of using ffsim is by calling functions that transform statevectors represented directly as NumPy arrays. As an example, the following code shows how to create a vector representing the Hartree-Fock state with 6 spatial orbitals, 3 alpha electrons and 2 beta electrons, and then apply an orbital rotation to it. It also shows an equivalent way to construct the resulting state as a Slater determinant."
    ]
   },
   {
@@ -17,24 +17,30 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import numpy as np\n",
     "import ffsim\n",
     "\n",
     "# Set the number of orbitals and their occupancies\n",
     "norb = 6\n",
     "nelec = (3, 2)\n",
-    "n_alpha, n_beta = nelec\n",
-    "occupied_orbitals = (range(n_alpha), range(n_beta))\n",
     "\n",
-    "# Create a Slater determinant\n",
-    "vec = ffsim.slater_determinant(norb, occupied_orbitals=occupied_orbitals)\n",
+    "# Create the Hartree-Fock state\n",
+    "vec = ffsim.hartree_fock_state(norb, nelec)\n",
     "\n",
     "# Generate a random orbital rotation\n",
     "orbital_rotation = ffsim.random.random_unitary(norb, seed=1234)\n",
     "\n",
     "# Apply the orbital rotation to the statevector\n",
-    "rotated_vec = ffsim.apply_orbital_rotation(\n",
-    "    vec, orbital_rotation, norb=norb, nelec=nelec\n",
-    ")"
+    "vec = ffsim.apply_orbital_rotation(vec, orbital_rotation, norb=norb, nelec=nelec)\n",
+    "\n",
+    "# Equivalent way to create the same state\n",
+    "n_alpha, n_beta = nelec\n",
+    "occupied_orbitals = (range(n_alpha), range(n_beta))\n",
+    "slater_det = ffsim.slater_determinant(\n",
+    "    norb, occupied_orbitals, orbital_rotation=orbital_rotation\n",
+    ")\n",
+    "\n",
+    "np.testing.assert_allclose(slater_det, vec)"
    ]
   },
   {
@@ -47,6 +53,8 @@
     "{N \\choose N_\\alpha} \\times {N \\choose N_\\beta}.\n",
     "$$\n",
     "\n",
+    "In contrast, a generic quantum circuit simulator would represent the statevector in the space spanned by all possible bitstrings of length $2N$, resulting in a dimention of $2^{2N}$.\n",
+    "\n",
     "For convenience, ffsim includes functions to calculate these dimensions."
    ]
   },
@@ -60,6 +68,8 @@
     "\n",
     "dim_a, dim_b = ffsim.dims(norb, nelec)\n",
     "dim = ffsim.dim(norb, nelec)\n",
+    "print(f\"The dimension of the vector space is {dim}.\")\n",
+    "print(f\"On the other hand, 2 ** (2 * norb) = {2 ** (2 * norb)}.\")\n",
     "\n",
     "assert dim_a == comb(norb, n_alpha, exact=True)\n",
     "assert dim_b == comb(norb, n_beta, exact=True)\n",
@@ -80,14 +90,24 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "reshaped_vec = vec.reshape((dim_a, dim_b))"
+    "mat = vec.reshape((dim_a, dim_b))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The statevector representation depends on a choice of ordering for the $\\alpha$- and $\\beta$-strings. ffsim uses the same ordering as pySCF's FCI module, `pyscf.fci`."
+    "The statevector representation depends on a choice of ordering for the $\\alpha$- and $\\beta$-strings. ffsim uses the same ordering as pySCF's FCI module, `pyscf.fci`. You can use the `indices_to_strings` function to convert a list of statevector indices to the corresponding bitstrings. The left half of a bitstring is the $\\alpha$-string, and the right half is the $\\beta$-string."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "strings = ffsim.indices_to_strings(range(20), norb, nelec)\n",
+    "strings"
    ]
   }
  ],
@@ -107,7 +127,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.10.12"
   },
   "orig_nbformat": 4
  },