diff --git a/docs/tutorials/05-entanglement-forging.ipynb b/docs/how-to-guides/entanglement-forging.ipynb similarity index 96% rename from docs/tutorials/05-entanglement-forging.ipynb rename to docs/how-to-guides/entanglement-forging.ipynb index 3ebe82bbe..03fd8ab65 100644 --- a/docs/tutorials/05-entanglement-forging.ipynb +++ b/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." ] }, { diff --git a/docs/tutorials/06-fermion-operator.ipynb b/docs/how-to-guides/fermion-operator.ipynb similarity index 93% rename from docs/tutorials/06-fermion-operator.ipynb rename to docs/how-to-guides/fermion-operator.ipynb index 8b382de88..bb351b1ab 100644 --- a/docs/tutorials/06-fermion-operator.ipynb +++ b/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." ] }, { diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md new file mode 100644 index 000000000..667cf44d2 --- /dev/null +++ b/docs/how-to-guides/index.md @@ -0,0 +1,9 @@ +# How-to guides + +```{toctree} +:maxdepth: 1 + +lucj +entanglement-forging +fermion-operator +``` diff --git a/docs/tutorials/04-lucj.ipynb b/docs/how-to-guides/lucj.ipynb similarity index 95% rename from docs/tutorials/04-lucj.ipynb rename to docs/how-to-guides/lucj.ipynb index 72e6dd913..07766472a 100644 --- a/docs/tutorials/04-lucj.ipynb +++ b/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", diff --git a/docs/index.md b/docs/index.md index c88e73d7a..90164bc8f 100644 --- a/docs/index.md +++ b/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 ``` diff --git a/docs/tutorials/02-orbital-rotation.ipynb b/docs/tutorials/02-orbital-rotation.ipynb index 3d12a1a44..c0da5f185 100644 --- a/docs/tutorials/02-orbital-rotation.ipynb +++ b/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 }, diff --git a/docs/tutorials/03-double-factorized.ipynb b/docs/tutorials/03-double-factorized.ipynb index e82c19e8b..a7840b12c 100644 --- a/docs/tutorials/03-double-factorized.ipynb +++ b/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 }, diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 73a36c9c3..0ab09d15b 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -6,7 +6,4 @@ 01-introduction 02-orbital-rotation 03-double-factorized -04-lucj -05-entanglement-forging -06-fermion-operator ``` diff --git a/src/fermion_operator.rs b/src/fermion_operator.rs index 5dd4307b6..8078b6e76 100644 --- a/src/fermion_operator.rs +++ b/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: ///