reorganize docs

docs/tutorials/05-entanglement-forging.ipynb → docs/how-to-guides/entanglement-forging.ipynb

@@ -4,9 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Entanglement forging\n",
+    "# How to simulate entanglement forging\n",
     "\n",
-    "In this tutorial, we show how to simulate entanglement forging for a water molecule at equilibrium."
+    "In this guide, we show how to simulate entanglement forging for a water molecule at equilibrium."
    ]
   },
   {

docs/tutorials/06-fermion-operator.ipynb → docs/how-to-guides/fermion-operator.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# The FermionOperator class\n",
+    "# How to use the FermionOperator class\n",
     "\n",
     "The FermionOperator class is used to represent a linear combination of products of fermionic creation and annihilation operators. For example:\n",
     "\n",
@@ -19,7 +19,7 @@
     "2. The spin of the orbital being acted upon (alpha or beta).\n",
     "3. The numerical index of the orbital.\n",
     "\n",
-    "Internally, the action is itself represented as a tuple containing these three pieces of information, but it is recommended to use the helper functions `cre_a`, `cre_b`, `des_a`, and `des_b` to construct these tuples.\n",
+    "Internally, the action is itself represented as a tuple containing these three pieces of information, but we recommend using the helper functions `cre_a`, `cre_b`, `des_a`, and `des_b` to construct these tuples.\n",
     "\n",
     "The following code example shows how to construct the operator shown above."
    ]
@@ -137,6 +137,7 @@
    "metadata": {},
    "source": [
     "It is good to be aware that some in-place operations are especially efficient because they avoid copying data into a new FermionOperator object. These operations are:\n",
+    "\n",
     "- In-place addition and subtraction\n",
     "- In-place multiplication and division by a scalar\n",
     "\n",
@@ -183,7 +184,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Operators can be normal-ordered by calling the `normal_ordered` function, which returns a new FermionOperator. In the normal-ordered form of a FermionOperator, the operators comprising each term appear from left to right in descending lexicographic order by `(action, spin, orb)`. That is, all creation operators appear before all annihilation operators; within creation/annihilation operators, spin beta operators appear before spin alpha operators, and larger orbital indices appear before smaller orbital indices."
+    "Operators can be normal-ordered by calling the `normal_ordered` method, which returns a new FermionOperator. In the normal-ordered form of a FermionOperator, the operators comprising each term appear from left to right in descending lexicographic order by `(action, spin, orb)`. That is, all creation operators appear before all annihilation operators; within creation/annihilation operators, spin beta operators appear before spin alpha operators, and larger orbital indices appear before smaller orbital indices."
    ]
   },
   {

docs/how-to-guides/index.md

@@ -0,0 +1,9 @@
+# How-to guides
+
+```{toctree}
+:maxdepth: 1
+
+lucj
+entanglement-forging
+fermion-operator
+```

docs/tutorials/04-lucj.ipynb → docs/how-to-guides/lucj.ipynb

@@ -4,9 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# The local unitary cluster Jastrow (LUCJ) ansatz\n",
+    "# How to simulate the local unitary cluster Jastrow (LUCJ) ansatz\n",
     "\n",
-    "In this tutorial, we show how to use ffsim to simulate the local unitary cluster Jastrow (LUCJ) ansatz. We'll use it to calculate the ground state energy of an ethene molecule at a stretched bond length."
+    "In this guide, we show how to use ffsim to simulate the local unitary cluster Jastrow (LUCJ) ansatz. We'll use it to calculate the ground state energy of an ethene molecule at a stretched bond length."
    ]
   },
   {
@@ -76,13 +76,13 @@
     "  \\lvert \\Psi \\rangle = \\prod_{k = 1}^L \\mathcal{W}_k e^{i \\mathcal{J}_k} \\mathcal{W}_k^\\dagger \\lvert \\Phi_0 \\rangle\n",
     "$$\n",
     "\n",
-    "where $\\lvert \\Phi_0 \\rangle$ is a reference state, often taken as the Hartree-Fock state, each $\\mathcal{W_k}$ is an [orbital rotation](./02-orbital-rotation.ipynb), and each $\\mathcal{J}_k$ is a diagonal Coulomb operator of the form\n",
+    "where $\\lvert \\Phi_0 \\rangle$ is a reference state, often taken as the Hartree-Fock state, each $\\mathcal{W_k}$ is an [orbital rotation](../tutorials/02-orbital-rotation.ipynb), and each $\\mathcal{J}_k$ is a diagonal Coulomb operator of the form\n",
     "\n",
     "$$\n",
     "    \\mathcal{J} = \\frac12\\sum_{ij,\\sigma \\tau} \\mathbf{J}^{\\sigma \\tau}_{ij} n_{i,\\sigma} n_{j,\\tau}.\n",
     "$$\n",
     "\n",
-    "Note that this expression for the diagonal Coulomb operator is more general than the one introduced in [the previous tutorial](./03-double-factorized.ipynb) because the matrices $\\mathbf{J}^{\\sigma \\tau}$ are indexed by the spins $\\sigma$ and $\\tau$. In order that the operator commutes with the total spin Z operator, we enforce that $\\mathbf{J}^{\\alpha\\alpha} = \\mathbf{J}^{\\beta\\beta}$ and $\\mathbf{J}^{\\alpha\\beta} = \\mathbf{J}^{\\beta\\alpha}$. As a result, we have two sets of matrices for describing the diagonal Coulomb operators: \"alpha-alpha\" matrices containing coefficients for terms involving the same spin, and \"alpha-beta\" matrices containing coefficients for terms involving different spins.\n",
+    "In order that the operator commutes with the total spin Z operator, we enforce that $\\mathbf{J}^{\\alpha\\alpha} = \\mathbf{J}^{\\beta\\beta}$ and $\\mathbf{J}^{\\alpha\\beta} = \\mathbf{J}^{\\beta\\alpha}$. As a result, we have two sets of matrices for describing the diagonal Coulomb operators: \"alpha-alpha\" matrices containing coefficients for terms involving the same spin, and \"alpha-beta\" matrices containing coefficients for terms involving different spins.\n",
     "\n",
     "In ffsim, the UCJ ansatz operator $\\prod_{k = 1}^L \\mathcal{W_k} e^{i \\mathcal{J}_k} \\mathcal{W_k^\\dagger}$ is represented by the `UCJOperator` class, which is just a dataclass that stores the diagonal Coulomb matrices and orbital rotations. A constructor method is provided to initialize the operator from a truncated double factorization of t2 amplitudes (e.g. from CCSD or MP2).\n",
     "\n",

docs/index.md

@@ -14,7 +14,10 @@
 
 ## Next steps
 
-Check out the [tutorials](tutorials/index.md).
+Check out the following resources:
+
+- [Tutorials](tutorials/index.md)
+- [How-to guides](how-to-guides/index.md)
 
 ## Developer guide
 
@@ -32,5 +35,6 @@ See the [developer guide](https://github.com/qiskit-community/ffsim/blob/main/CO
 
 install
 tutorials/index
+how-to-guides/index
 api/index
 ```

docs/tutorials/02-orbital-rotation.ipynb

@@ -201,7 +201,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.11.8"
   },
   "orig_nbformat": 4
  },

docs/tutorials/03-double-factorized.ipynb

@@ -497,7 +497,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.11.8"
   },
   "orig_nbformat": 4
  },

docs/tutorials/index.md

@@ -6,7 +6,4 @@
 01-introduction
 02-orbital-rotation
 03-double-factorized
-04-lucj
-05-entanglement-forging
-06-fermion-operator
 ```

src/fermion_operator.rs

@@ -46,7 +46,7 @@ impl KeysIterator {
 /// by scalars. When multiplying by a scalar, the scalar should go on the left side of the
 /// multiplication operator, e.g. ``scalar * op``, not ``op * scalar``.
 ///
-/// See :doc:`/tutorials/06-fermion-operator` for a demonstration of how to use this class.
+/// See :doc:`/how-to-guides/fermion-operator` for an explanation of how to use this class.
 ///
 /// Example:
 ///