ffsim 0.0.72__tar.gz → 0.0.74__tar.gz

{ffsim-0.0.72 → ffsim-0.0.74}/.github/workflows/test-latest-versions.yml

@@ -33,7 +33,7 @@ jobs:
           pip install tox
       - name: Run tests
         run: |
-          tox run -e py${{ matrix.python-version }}
+          tox run -e test-${{ matrix.python-version }}
   test-linux-arm:
     runs-on: ubuntu-24.04-arm
     strategy:
@@ -54,7 +54,7 @@ jobs:
           pip install tox
       - name: Run tests
         run: |
-          tox run -e py${{ matrix.python-version }}
+          tox run -e test-${{ matrix.python-version }}
   test-macos:
     runs-on: macos-latest
     strategy:
@@ -72,4 +72,4 @@ jobs:
           pip install tox
       - name: Run tests
         run: |
-          tox run -e py${{ matrix.python-version }}
+          tox run -e test-${{ matrix.python-version }}

{ffsim-0.0.72 → ffsim-0.0.74}/.github/workflows/test-minimum-versions.yml

@@ -35,4 +35,4 @@ jobs:
           extremal-python-dependencies pin-dependencies-to-minimum --inplace
       - name: Run tests
         run: |
-          tox run -e py${{ matrix.python-version }}
+          tox run -e test-${{ matrix.python-version }}

{ffsim-0.0.72 → ffsim-0.0.74}/.gitignore

@@ -70,7 +70,6 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/api/generated/
 
 # PyBuilder
 target/
@@ -140,3 +139,6 @@ wheelhouse/
 
 # direnv
 .envrc
+
+# generated API docs
+docs/api/

{ffsim-0.0.72 → ffsim-0.0.74}/CONTRIBUTING.md

@@ -47,11 +47,12 @@ tox run -e <environment name>
 
 substituting `<environment name>` with the name of the tox environment for the check. The following environments are available:
 
-- `py310`, `py311`, `py312`, `py313`, `py314`: Run tests for a specific Python version
+- `test-3.10`, `test-3.11`, `test-3.12`, `test-3.13`, `test-3.14`: Run tests for a specific Python version
 - `coverage`: Code coverage
 - `type`: Type check
 - `lint`: Lint check
 - `format`: Format check
+- `spell`: Spell check
 - `docs`: Build documentation
 
 ## Run code checks directly
@@ -85,9 +86,16 @@ ruff check --fix
 ruff format
 ```
 
+### Run spell check
+
+```bash
+typos
+```
+
 ### Build documentation
 
 ```bash
+python docs/generate_api_docs.py
 sphinx-build -b html -W docs/ docs/_build/html
 ```
 

{ffsim-0.0.72 → ffsim-0.0.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffsim
-Version: 0.0.72
+Version: 0.0.74
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only

ffsim-0.0.74/docs/_templates/autosummary/class.rst

@@ -0,0 +1,44 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+
+   {% block methods %}
+   {%- set is_protocol = '__protocol_attrs__' in members and '__protocol_attrs__' not in inherited_members %}
+   {%- set ns = namespace(protocol_methods=[]) %}
+   {%- if is_protocol %}
+   {%- for item in all_methods %}
+   {%- if item.startswith('_') and not item.startswith('__') and item.endswith('_') and not item.endswith('__') %}
+   {%- set ns.protocol_methods = ns.protocol_methods + [item] %}
+   {%- endif %}
+   {%- endfor %}
+   {%- endif %}
+   {% if methods or ns.protocol_methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods if item not in inherited_members and item != '__init__' %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {%- for item in ns.protocol_methods if item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- for item in ns.protocol_methods %}
+
+   .. automethod:: {{ item }}
+   {%- endfor %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes if item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

{ffsim-0.0.72 → ffsim-0.0.74}/docs/conf.py

@@ -21,6 +21,7 @@ extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
@@ -42,6 +43,18 @@ html_theme_options = {
     "sidebar_qiskit_ecosystem_member": True,
 }
 
+# autosummary options
+autosummary_generate = True
+templates_path = ["_templates"]
+
+# intersphinx options
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "qiskit": ("https://quantum.cloud.ibm.com/docs/api/qiskit", None),
+}
+
 # nbsphinx options (for tutorials)
 nbsphinx_timeout = 300
 nbsphinx_execute = "always"

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/diag-coulomb-hamiltonian.ipynb

@@ -13,12 +13,12 @@
     "A diagonal Coulomb Hamiltonian has the form\n",
     "\n",
     "$$\n",
-    "    H = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "        + \\frac12 \\sum_{\\sigma \\tau, pq} J^{\\sigma \\tau}_{pq} n_{\\sigma, p}\n",
-    "        n_{\\tau, q} + \\text{constant}\n",
+    "    H = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "        + \\frac12 \\sum_{\\substack{pq \\\\ \\sigma \\tau}} J^{\\sigma \\tau}_{pq} n_{p\\sigma}\n",
+    "        n_{q\\tau} + \\text{constant}\n",
     "$$\n",
     "\n",
-    "where $n_{\\sigma, p} = a^\\dagger_{\\sigma, p} a_{\\sigma, p}$ is the number operator on orbital $p$ with spin $\\sigma$.\n",
+    "where $n_{p\\sigma} = a^\\dagger_{p\\sigma} a_{p\\sigma}$ is the number operator on orbital $p$ with spin $\\sigma$.\n",
     "\n",
     "The Hamiltonian is specified by the following data ($N$ is the number of spatial orbitals):\n",
     "\n",
@@ -26,11 +26,11 @@
     "- The diagonal Coulomb matrices $J^{\\sigma \\tau}$, given as a pair of $N \\times N$ real symmetric matrices specifying the independent coefficients for alpha-alpha and alpha-beta interactions. We require that $J^{\\alpha\\alpha} = J^{\\beta\\beta}$ and $J^{\\alpha\\beta} = J^{\\beta\\alpha}$, so only two matrices are needed.\n",
     "- The constant, which is a real number.\n",
     "\n",
-    "Compared to the general [molecular Hamiltonian](hamiltonians.ipynb), the two-body interaction is restricted to density-density form ($n_{\\sigma, p} n_{\\tau, q}$ terms). This restriction means the two-body part is specified by $O(N^2)$ parameters rather than $O(N^4)$, which enables more efficient simulation.\n",
+    "Compared to the general [molecular Hamiltonian](hamiltonians.ipynb), the two-body interaction is restricted to density-density form ($n_{p\\sigma} n_{q\\tau}$ terms). This restriction means the two-body part is specified by $O(N^2)$ parameters rather than $O(N^4)$, which enables more efficient simulation.\n",
     "\n",
     "## Data representation\n",
     "\n",
-    "A diagonal Coulomb Hamiltonian is represented in ffsim using the [DiagonalCoulombHamiltonian](../api/ffsim.rst#ffsim.DiagonalCoulombHamiltonian) class. You can initialize it by passing the one-body tensor, the diagonal Coulomb matrices, and an optional constant."
+    "A diagonal Coulomb Hamiltonian is represented in ffsim using the [DiagonalCoulombHamiltonian](../api/stubs/ffsim.DiagonalCoulombHamiltonian.rst#ffsim.DiagonalCoulombHamiltonian) class. You can initialize it by passing the one-body tensor, the diagonal Coulomb matrices, and an optional constant."
    ]
   },
   {
@@ -90,15 +90,15 @@
     "The [Fermi-Hubbard model](https://en.wikipedia.org/wiki/Hubbard_model) is a widely studied example of a Hamiltonian with diagonal Coulomb form, since its two-body interaction is an onsite density-density interaction. The two-dimensional Fermi-Hubbard Hamiltonian on a square lattice is given by\n",
     "\n",
     "$$\n",
-    "    H = -t \\sum_{\\sigma, \\langle pq \\rangle}\n",
-    "    (a^\\dagger_{\\sigma, p} a_{\\sigma, q} + a^\\dagger_{\\sigma, q} a_{\\sigma, p})\n",
-    "    + U \\sum_p n_{\\alpha, p} n_{\\beta, p}\n",
-    "    - \\mu \\sum_p (n_{\\alpha, p} + n_{\\beta, p})\n",
+    "    H = -t \\sum_{\\substack{\\langle pq \\rangle \\\\ \\sigma}}\n",
+    "    (a^\\dagger_{p\\sigma} a_{q\\sigma} + a^\\dagger_{q\\sigma} a_{p\\sigma})\n",
+    "    + U \\sum_p n_{p\\alpha} n_{p\\beta}\n",
+    "    - \\mu \\sum_p (n_{p\\alpha} + n_{p\\beta})\n",
     "$$\n",
     "\n",
     "where $t$ is the tunneling amplitude, $U$ is the onsite interaction strength, and $\\mu$ is the chemical potential. The index $\\langle pq \\rangle$ runs over pairs of neighboring orbitals on the lattice.\n",
     "\n",
-    "The two-dimensional Fermi-Hubbard Hamiltonian can be constructed as a [FermionOperator](../api/ffsim.rst#ffsim.FermionOperator) using the [fermi_hubbard_2d](../api/ffsim.rst#ffsim.fermi_hubbard_2d) function, and then converted to a `DiagonalCoulombHamiltonian` using the `from_fermion_operator` method."
+    "The two-dimensional Fermi-Hubbard Hamiltonian can be constructed as a [FermionOperator](../api/stubs/ffsim.FermionOperator.rst#ffsim.FermionOperator) using the [fermi_hubbard_2d](../api/stubs/ffsim.fermi_hubbard_2d.rst#ffsim.fermi_hubbard_2d) function, and then converted to a `DiagonalCoulombHamiltonian` using the `from_fermion_operator` method."
    ]
   },
   {
@@ -211,21 +211,21 @@
     "where\n",
     "\n",
     "$$\n",
-    "    H_0 = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
+    "    H_0 = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
     "$$\n",
     "\n",
     "is a quadratic Hamiltonian and\n",
     "\n",
     "$$\n",
-    "    H_1 = \\frac12 \\sum_{\\sigma \\tau, pq} J^{\\sigma \\tau}_{pq} n_{\\sigma, p} n_{\\tau, q}\n",
+    "    H_1 = \\frac12 \\sum_{\\substack{pq \\\\ \\sigma \\tau}} J^{\\sigma \\tau}_{pq} n_{p\\sigma} n_{q\\tau}\n",
     "$$\n",
     "\n",
     "is a diagonal Coulomb operator. Note,\n",
     "\n",
     "- $H_0$ can be simulated exactly using [orbital rotations](orbital-rotation.ipynb#Application-to-time-evolution-by-a-quadratic-Hamiltonian).\n",
-    "- $H_1$ can be simulated exactly using [apply_diag_coulomb_evolution](../api/ffsim.rst#ffsim.apply_diag_coulomb_evolution).\n",
+    "- $H_1$ can be simulated exactly using [apply_diag_coulomb_evolution](../api/stubs/ffsim.apply_diag_coulomb_evolution.rst#ffsim.apply_diag_coulomb_evolution).\n",
     "\n",
-    "This split-operator approach is implemented in ffsim by the function [simulate_trotter_diag_coulomb_split_op](../api/ffsim.rst#ffsim.simulate_trotter_diag_coulomb_split_op). As with other Trotter functions in ffsim, the `order` parameter controls the order of the Trotter-Suzuki formula: `order=0` is the first-order asymmetric formula (the default), `order=1` is the first-order symmetric (second-order) formula, and so on.\n",
+    "This split-operator approach is implemented in ffsim by the function [simulate_trotter_diag_coulomb_split_op](../api/stubs/ffsim.simulate_trotter_diag_coulomb_split_op.rst#ffsim.simulate_trotter_diag_coulomb_split_op). As with other Trotter functions in ffsim, the `order` parameter controls the order of the Trotter-Suzuki formula: `order=0` is the first-order asymmetric formula (the default), `order=1` is the first-order symmetric (second-order) formula, and so on.\n",
     "\n",
     "In the following example, we compare the Trotter-approximated time evolution against the exact time evolution (computed using `expm_multiply`)."
    ]
@@ -299,7 +299,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.11"
+   "version": "3.13.12"
   }
  },
  "nbformat": 4,

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/double-factorized.ipynb

@@ -13,16 +13,16 @@
     "The molecular Hamiltonian is commonly written in the form\n",
     "\n",
     "$$\n",
-    "    H = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "        + \\frac12 \\sum_{\\sigma \\tau, pqrs} h_{pqrs}\n",
-    "        a^\\dagger_{\\sigma, p} a^\\dagger_{\\tau, r} a_{\\tau, s} a_{\\sigma, q}\n",
+    "    H = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "        + \\frac12 \\sum_{\\substack{pqrs \\\\ \\sigma \\tau}} h_{pqrs}\n",
+    "        a^\\dagger_{p\\sigma} a^\\dagger_{r\\tau} a_{s\\tau} a_{q\\sigma}\n",
     "        + \\text{constant}.\n",
     "$$\n",
     "\n",
     "This representation of the Hamiltonian is daunting for quantum simulations because the number of terms in the two-body part scales as $N^4$ where $N$ is the number of spatial orbitals. An alternative representation can be obtained by performing a \"double factorization\" of the two-body tensor $h_{pqrs}$:\n",
     "\n",
     "$$\n",
-    "    H = \\sum_{\\sigma, pq} h'_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
+    "    H = \\sum_{\\substack{pq \\\\ \\sigma}} h'_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
     "    + \\sum_{k=1}^L \\mathcal{U}_k \\mathcal{J}_k \\mathcal{U}_k^\\dagger\n",
     "    + \\text{constant}'.\n",
     "$$\n",
@@ -30,10 +30,10 @@
     "Here each $\\mathcal{U}_k$ is an [orbital rotation](orbital-rotation.ipynb) and each $\\mathcal{J}_k$ is a so-called diagonal Coulomb operator of the form\n",
     "\n",
     "$$\n",
-    "    \\mathcal{J} = \\frac12\\sum_{\\sigma \\tau, ij} \\mathbf{J}_{ij} n_{\\sigma, i} n_{\\tau, j},\n",
+    "    \\mathcal{J} = \\frac12\\sum_{\\substack{ij \\\\ \\sigma \\tau}} \\mathbf{J}_{ij} n_{i\\sigma} n_{j\\tau},\n",
     "$$\n",
     "\n",
-    "where $n_{\\sigma, i} = a^\\dagger_{\\sigma, i} a_{\\sigma, i}$ is the occupation number operator and $\\mathbf{J}_{ij}$ is a real symmetric matrix. The one-body tensor and the constant have been updated to accommodate extra terms that arise from reordering fermionic ladder operators.\n",
+    "where $n_{i\\sigma} = a^\\dagger_{i\\sigma} a_{i\\sigma}$ is the occupation number operator and $\\mathbf{J}_{ij}$ is a real symmetric matrix. The one-body tensor and the constant have been updated to accommodate extra terms that arise from reordering fermionic ladder operators.\n",
     "\n",
     "For an exact factorization, $L$ is proportional to $N^2$. However, the two-body tensor often has low-rank structure, and the decomposition can be truncated while still maintaining an accurate representation. Thus, in practice, $L$ often scales only linearly with $N$, resulting in a much more compact representation that gives rise to more efficient schemes for simulating and measuring the Hamiltonian, which utilize efficient quantum circuits for orbital rotations and time evolution by a diagonal Coulomb operator.\n",
     "\n",
@@ -80,7 +80,7 @@
     "where\n",
     "\n",
     "$$\n",
-    "H_0 = \\sum_{\\sigma, pq} h'_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
+    "H_0 = \\sum_{\\substack{pq \\\\ \\sigma}} h'_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
     "$$\n",
     "\n",
     "and for $k = 1, \\ldots, L$,\n",
@@ -92,9 +92,9 @@
     "We have that\n",
     "\n",
     "- $H_0$ is a quadratic Hamiltonian and can be simulated as described on [this page](orbital-rotation.ipynb#Application-to-time-evolution-by-a-quadratic-Hamiltonian), and\n",
-    "- $H_k$ is a diagonal Coulomb operator (up to an orbital rotation) for $k = 1, \\ldots, L$, and ffsim includes the function [apply_diag_coulomb_evolution](../api/ffsim.rst#ffsim.apply_diag_coulomb_evolution) for simulating time evolution by such an operator.\n",
+    "- $H_k$ is a diagonal Coulomb operator (up to an orbital rotation) for $k = 1, \\ldots, L$, and ffsim includes the function [apply_diag_coulomb_evolution](../api/stubs/ffsim.apply_diag_coulomb_evolution.rst#ffsim.apply_diag_coulomb_evolution) for simulating time evolution by such an operator.\n",
     "\n",
-    "Given the ability to simulate each of the individual terms, we can implement Trotter-Suzuki formulas for time evolution by the entire Hamiltonian. This is implemented in ffsim by the function [simulate_trotter_double_factorized](../api/ffsim.rst#ffsim.simulate_trotter_double_factorized), which implements higher-order Trotter-Suzuki formulas in addition to the first-order asymmetric formula mentioned previously. The first-order asymmetric formula corresponds to setting the argument `order=0`, which is the default. `order=1` corresponds to the first-order symmetric (commonly known as the second-order) formula, `order=2` corresponds to the second-order symmetric (fourth-order) formula, and so on."
+    "Given the ability to simulate each of the individual terms, we can implement Trotter-Suzuki formulas for time evolution by the entire Hamiltonian. This is implemented in ffsim by the function [simulate_trotter_double_factorized](../api/stubs/ffsim.simulate_trotter_double_factorized.rst#ffsim.simulate_trotter_double_factorized), which implements higher-order Trotter-Suzuki formulas in addition to the first-order asymmetric formula mentioned previously. The first-order asymmetric formula corresponds to setting the argument `order=0`, which is the default. `order=1` corresponds to the first-order symmetric (commonly known as the second-order) formula, `order=2` corresponds to the second-order symmetric (fourth-order) formula, and so on."
    ]
   }
  ],

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/fermion-operator.ipynb

@@ -13,8 +13,8 @@
     "The FermionOperator class is used to represent a linear combination of products of fermionic creation and annihilation operators. For example:\n",
     "\n",
     "$$\n",
-    "0.5 a_{\\alpha, 0}^\\dagger a_{\\alpha, 3} - 0.25 a_{\\alpha, 3}^\\dagger a_{\\alpha, 0}\n",
-    "+ (1 + i) a_{\\beta, 1}^\\dagger a_{\\beta, 5} a_{\\alpha, 4}^\\dagger.\n",
+    "0.5 a_{0\\alpha}^\\dagger a_{3\\alpha} - 0.25 a_{3\\alpha}^\\dagger a_{0\\alpha}\n",
+    "+ (1 + i) a_{1\\beta}^\\dagger a_{5\\beta} a_{4\\alpha}^\\dagger.\n",
     "$$\n",
     "\n",
     "Such operators are represented programmatically as a dictionary (hash table) that maps each term to its associated coefficient. An individual term is represented as a tuple of fermionic actions. Each action is described by three pieces of information:\n",

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/hamiltonians.ipynb

@@ -13,9 +13,9 @@
     "ffsim includes [several classes](#hamiltonian-classes) for representing Hamiltonians in different forms. To take a concrete example, we'll use the molecular Hamiltonian of the form\n",
     "\n",
     "$$\n",
-    "H = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "    + \\frac12 \\sum_{\\sigma \\tau, pqrs} h_{pqrs}\n",
-    "    a^\\dagger_{\\sigma, p} a^\\dagger_{\\tau, r} a_{\\tau, s} a_{\\sigma, q}\n",
+    "H = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "    + \\frac12 \\sum_{\\substack{pqrs \\\\ \\sigma \\tau}} h_{pqrs}\n",
+    "    a^\\dagger_{p\\sigma} a^\\dagger_{r\\tau} a_{s\\tau} a_{q\\sigma}\n",
     "    + \\text{constant}.\n",
     "$$\n",
     "\n",
@@ -53,7 +53,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The molecular Hamiltonian is represented in ffsim using the [MolecularHamiltonian](../api/ffsim.rst#ffsim.MolecularHamiltonian) class. You initialize the class by passing the three pieces of information (the constant is optional and defaults to zero if not specified):"
+    "The molecular Hamiltonian is represented in ffsim using the [MolecularHamiltonian](../api/stubs/ffsim.MolecularHamiltonian.rst#ffsim.MolecularHamiltonian) class. You initialize the class by passing the three pieces of information (the constant is optional and defaults to zero if not specified):"
    ]
   },
   {
@@ -199,12 +199,12 @@
     "\n",
     "### MolecularHamiltonian\n",
     "\n",
-    "The [MolecularHamiltonian](../api/ffsim.rst#ffsim.MolecularHamiltonian) class stores the Hamiltonian in the standard second-quantized form with a one-body tensor, two-body tensor, and constant:\n",
+    "The [MolecularHamiltonian](../api/stubs/ffsim.MolecularHamiltonian.rst#ffsim.MolecularHamiltonian) class stores the Hamiltonian in the standard second-quantized form with a one-body tensor, two-body tensor, and constant:\n",
     "\n",
     "$$\n",
-    "H = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "    + \\frac12 \\sum_{\\sigma \\tau, pqrs} h_{pqrs}\n",
-    "    a^\\dagger_{\\sigma, p} a^\\dagger_{\\tau, r} a_{\\tau, s} a_{\\sigma, q}\n",
+    "H = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "    + \\frac12 \\sum_{\\substack{pqrs \\\\ \\sigma \\tau}} h_{pqrs}\n",
+    "    a^\\dagger_{p\\sigma} a^\\dagger_{r\\tau} a_{s\\tau} a_{q\\sigma}\n",
     "    + \\text{constant}.\n",
     "$$\n",
     "\n",
@@ -221,16 +221,16 @@
    "source": [
     "### DoubleFactorizedHamiltonian\n",
     "\n",
-    "The [DoubleFactorizedHamiltonian](../api/ffsim.rst#ffsim.DoubleFactorizedHamiltonian) class stores the Hamiltonian in the double-factorized representation, which decomposes the two-body tensor into a sum of diagonal Coulomb operators acting in rotated orbital bases:\n",
+    "The [DoubleFactorizedHamiltonian](../api/stubs/ffsim.DoubleFactorizedHamiltonian.rst#ffsim.DoubleFactorizedHamiltonian) class stores the Hamiltonian in the double-factorized representation, which decomposes the two-body tensor into a sum of diagonal Coulomb operators acting in rotated orbital bases:\n",
     "\n",
     "$$\n",
-    "H = \\sum_{\\sigma, pq} \\kappa_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "    + \\frac12 \\sum_t \\sum_{\\sigma\\tau, ij}\n",
-    "    J^{(t)}_{ij} n^{(t)}_{\\sigma, i} n^{(t)}_{\\tau, j}\n",
+    "H = \\sum_{\\substack{pq \\\\ \\sigma}} \\kappa_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "    + \\frac12 \\sum_t \\sum_{\\substack{ij \\\\ \\sigma\\tau}}\n",
+    "    J^{(t)}_{ij} n^{(t)}_{i\\sigma} n^{(t)}_{j\\tau}\n",
     "    + \\text{constant}'\n",
     "$$\n",
     "\n",
-    "where $n^{(t)}_{\\sigma, i} = \\sum_{pq} U^{(t)}_{pi} a^\\dagger_{\\sigma, p} a_{\\sigma, q} U^{(t)*}_{qi}$ is the number operator in the rotated basis defined by the unitary matrix $U^{(t)}$.\n",
+    "where $n^{(t)}_{i\\sigma} = \\sum_{pq} U^{(t)}_{pi} a^\\dagger_{p\\sigma} a_{q\\sigma} U^{(t)*}_{qi}$ is the number operator in the rotated basis defined by the unitary matrix $U^{(t)}$.\n",
     "\n",
     "The data stored by this class consists of:\n",
     "\n",
@@ -249,15 +249,15 @@
    "source": [
     "### DiagonalCoulombHamiltonian\n",
     "\n",
-    "The [DiagonalCoulombHamiltonian](../api/ffsim.rst#ffsim.DiagonalCoulombHamiltonian) class stores a Hamiltonian whose two-body interaction is diagonal in the computational basis:\n",
+    "The [DiagonalCoulombHamiltonian](../api/stubs/ffsim.DiagonalCoulombHamiltonian.rst#ffsim.DiagonalCoulombHamiltonian) class stores a Hamiltonian whose two-body interaction is diagonal in the computational basis:\n",
     "\n",
     "$$\n",
-    "H = \\sum_{\\sigma, pq} h_{pq} a^\\dagger_{\\sigma, p} a_{\\sigma, q}\n",
-    "    + \\frac12 \\sum_{\\sigma \\tau, pq} J^{\\sigma \\tau}_{pq} n_{\\sigma, p}\n",
-    "    n_{\\tau, q} + \\text{constant}\n",
+    "H = \\sum_{\\substack{pq \\\\ \\sigma}} h_{pq} a^\\dagger_{p\\sigma} a_{q\\sigma}\n",
+    "    + \\frac12 \\sum_{\\substack{pq \\\\ \\sigma \\tau}} J^{\\sigma \\tau}_{pq} n_{p\\sigma}\n",
+    "    n_{q\\tau} + \\text{constant}\n",
     "$$\n",
     "\n",
-    "where $n_{\\sigma, p} = a_{\\sigma, p}^\\dagger a_{\\sigma, p}$ is the number operator.\n",
+    "where $n_{p\\sigma} = a_{p\\sigma}^\\dagger a_{p\\sigma}$ is the number operator.\n",
     "\n",
     "The data stored by this class consists of:\n",
     "\n",

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/lucj.ipynb

@@ -33,9 +33,9 @@
     "\n",
     "ffsim implements two variants of the UCJ ansatz, a \"spin-balanced\" ansatz, which is appropriate to apply to a closed-shell reference state, and a \"spin-unbalanced\" ansatz, which is appropriate to apply to an open-shell initial reference state.\n",
     "\n",
-    "In the spin-balanced ansatz, $\\mathbf{J}^{\\alpha\\alpha} = \\mathbf{J}^{\\beta\\beta}$ and $\\mathbf{J}^{\\alpha\\beta} = \\mathbf{J}^{\\beta\\alpha}$. As a result, each diagonal Coulomb operator is described by 2 matrices, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\alpha\\beta}$, and both of these matrices are symmetric. The spin-balanced UCJ ansatz is represented by the [UCJOpSpinBalanced](../api/ffsim.rst#ffsim.UCJOpSpinBalanced) class.\n",
+    "In the spin-balanced ansatz, $\\mathbf{J}^{\\alpha\\alpha} = \\mathbf{J}^{\\beta\\beta}$ and $\\mathbf{J}^{\\alpha\\beta} = \\mathbf{J}^{\\beta\\alpha}$. As a result, each diagonal Coulomb operator is described by 2 matrices, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\alpha\\beta}$, and both of these matrices are symmetric. The spin-balanced UCJ ansatz is represented by the [UCJOpSpinBalanced](../api/stubs/ffsim.UCJOpSpinBalanced.rst#ffsim.UCJOpSpinBalanced) class.\n",
     "\n",
-    "In the spin-unbalanced ansatz, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\beta\\beta}$ are allowed to differ, and $\\mathbf{J}^{\\alpha\\beta}$ is no longer required to be symmetric. Since $\\mathbf{J}^{\\alpha\\beta}_{ij} = \\mathbf{J}^{\\beta\\alpha}_{ji}$, we don't need to store $\\mathbf{J}^{\\beta\\alpha}$ separately. Therefore, each diagonal Coulomb operator is described by 3 matrices, $\\mathbf{J}^{\\alpha\\alpha}$, $\\mathbf{J}^{\\alpha\\beta}$, and $\\mathbf{J}^{\\beta\\beta}$, and of these matrices, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\beta\\beta}$ are symmetric. The spin-unbalanced UCJ ansatz is represented by the [UCJOpSpinUnbalanced](../api/ffsim.rst#ffsim.UCJOpSpinUnbalanced) class.\n",
+    "In the spin-unbalanced ansatz, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\beta\\beta}$ are allowed to differ, and $\\mathbf{J}^{\\alpha\\beta}$ is no longer required to be symmetric. Since $\\mathbf{J}^{\\alpha\\beta}_{ij} = \\mathbf{J}^{\\beta\\alpha}_{ji}$, we don't need to store $\\mathbf{J}^{\\beta\\alpha}$ separately. Therefore, each diagonal Coulomb operator is described by 3 matrices, $\\mathbf{J}^{\\alpha\\alpha}$, $\\mathbf{J}^{\\alpha\\beta}$, and $\\mathbf{J}^{\\beta\\beta}$, and of these matrices, $\\mathbf{J}^{\\alpha\\alpha}$ and $\\mathbf{J}^{\\beta\\beta}$ are symmetric. The spin-unbalanced UCJ ansatz is represented by the [UCJOpSpinUnbalanced](../api/stubs/ffsim.UCJOpSpinUnbalanced.rst#ffsim.UCJOpSpinUnbalanced) class.\n",
     "\n",
     "## The local UCJ (LUCJ) ansatz\n",
     "\n",

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/orbital-rotation.ipynb

@@ -10,15 +10,15 @@
     "\n",
     "## Definition of orbital rotation\n",
     "\n",
-    "An orbital rotation is described by an $N \\times N$ unitary matrix $\\mathbf{U}$ (here $N$ is the number spatial orbitals), and we denote the corresponding operator as $\\mathcal{U}$. This operator has the following action on the fermionic creation operators $\\set{a^\\dagger_{\\sigma, i}}$:\n",
+    "An orbital rotation is described by an $N \\times N$ unitary matrix $\\mathbf{U}$ (here $N$ is the number spatial orbitals), and we denote the corresponding operator as $\\mathcal{U}$. This operator has the following action on the fermionic creation operators $\\set{a^\\dagger_{i\\sigma}}$:\n",
     "\n",
     "$$\n",
     "\\begin{align*}\n",
-    "    \\mathcal{U} a^\\dagger_{\\sigma, i} \\mathcal{U}^\\dagger = \\sum_j \\mathbf{U}_{ji} a^\\dagger_{\\sigma, j}.\n",
+    "    \\mathcal{U} a^\\dagger_{i\\sigma} \\mathcal{U}^\\dagger = \\sum_j \\mathbf{U}_{ji} a^\\dagger_{j\\sigma}.\n",
     "\\end{align*}\n",
     "$$\n",
     "\n",
-    "That is, $a^\\dagger_{\\sigma, i}$ is mapped to a new operator $b^\\dagger_{\\sigma, i}$ where $b^\\dagger_{\\sigma, i}$ is a linear combination of the operators $\\set{a^\\dagger_{\\sigma, i}}$ with coefficients given by the $i$-th column of $\\mathbf{U}$. The fact that $\\mathbf{U}$ is unitary can be used, together with the fermionic anticommutation relations, to show that the $\\set{b^\\dagger_{\\sigma, i}}$ also satisfy the fermionic anticommutation relations. Thus, the $b^\\dagger_{\\sigma, i}$ are creation operators in a rotated basis of orbitals.\n",
+    "That is, $a^\\dagger_{i\\sigma}$ is mapped to a new operator $b^\\dagger_{i\\sigma}$ where $b^\\dagger_{i\\sigma}$ is a linear combination of the operators $\\set{a^\\dagger_{i\\sigma}}$ with coefficients given by the $i$-th column of $\\mathbf{U}$. The fact that $\\mathbf{U}$ is unitary can be used, together with the fermionic anticommutation relations, to show that the $\\set{b^\\dagger_{i\\sigma}}$ also satisfy the fermionic anticommutation relations. Thus, the $b^\\dagger_{i\\sigma}$ are creation operators in a rotated basis of orbitals.\n",
     "\n",
     "### Explicit expression\n",
     "\n",
@@ -27,7 +27,7 @@
     "$$\n",
     "\\begin{align*}\n",
     "    \\mathcal{U} = \\prod_{\\sigma}\n",
-    "    \\exp\\left[\\sum_{ij} \\log\\left(\\mathbf{U}\\right)_{ij} a^\\dagger_{\\sigma, i} a_{\\sigma, j}\\right]\n",
+    "    \\exp\\left[\\sum_{ij} \\log\\left(\\mathbf{U}\\right)_{ij} a^\\dagger_{i\\sigma} a_{j\\sigma}\\right]\n",
     "\\end{align*}.\n",
     "$$\n",
     "Sometimes, it is useful to specify the orbital rotation via the antihermitian matrix $\\mathbf{K} = \\log(\\mathbf{U})$ rather than $\\mathbf{U}$ itself. However, ffsim generally represents orbital rotations using the unitary matrix $\\mathbf{U}$.\n",
@@ -51,9 +51,9 @@
     "\n",
     "$$\n",
     "\\begin{align*}\n",
-    "    \\mathcal{U} a^\\dagger_{\\sigma, i} \\mathcal{U}^\\dagger &= \\sum_j \\mathbf{U}^{\\sigma}_{ji} a^\\dagger_{\\sigma, j}, \\\\\n",
+    "    \\mathcal{U} a^\\dagger_{i\\sigma} \\mathcal{U}^\\dagger &= \\sum_j \\mathbf{U}^{\\sigma}_{ji} a^\\dagger_{j\\sigma}, \\\\\n",
     "    \\mathcal{U} &= \\prod_{\\sigma}\n",
-    "    \\exp\\left[\\sum_{ij} \\log\\left(\\mathbf{U}^{\\sigma}\\right)_{ij} a^\\dagger_{\\sigma, i} a_{\\sigma, j}\\right].\n",
+    "    \\exp\\left[\\sum_{ij} \\log\\left(\\mathbf{U}^{\\sigma}\\right)_{ij} a^\\dagger_{i\\sigma} a_{j\\sigma}\\right].\n",
     "\\end{align*}\n",
     "$$\n",
     "\n",
@@ -62,7 +62,7 @@
     "A quadratic Hamiltonian is an operator of the form (here we restrict the definition to Hamiltonians with particle number and spin Z symmetry)\n",
     "\n",
     "$$\n",
-    "    \\mathcal{M} = \\sum_{\\sigma, ij} \\mathbf{M}_{ij} a^\\dagger_{\\sigma, i} a_{\\sigma, j}\n",
+    "    \\mathcal{M} = \\sum_{\\substack{ij \\\\ \\sigma}} \\mathbf{M}_{ij} a^\\dagger_{i\\sigma} a_{j\\sigma}\n",
     "$$\n",
     "\n",
     "where $\\mathbf{M}$ is a Hermitian matrix. Time evolution by this Hamiltonian is given by the operator $e^{-i \\mathcal{M} t}$, where $t$ is the evolution time. Orbital rotations can be used to implement time evolution by a quadratic Hamiltonian using two different methods.\n",
@@ -72,10 +72,10 @@
     "A quadratic Hamiltonian can always be rewritten as\n",
     "\n",
     "$$\n",
-    "    \\mathcal{M} = \\mathcal{U} \\left(\\sum_{\\sigma, i} \\lambda_i n_{\\sigma, i}\\right)\\mathcal{U}^\\dagger\n",
+    "    \\mathcal{M} = \\mathcal{U} \\left(\\sum_{i \\sigma} \\lambda_i n_{i\\sigma}\\right)\\mathcal{U}^\\dagger\n",
     "$$\n",
     "\n",
-    "where the $\\set{\\lambda_i}$ are real numbers called orbital energies, $\\mathcal{U}$ is an orbital rotation, and $n_{\\sigma, i} = a^\\dagger_{\\sigma, i} a_{\\sigma, i}$ is the occupation number operator. The $\\set{\\lambda_i}$ and the unitary matrix $\\mathbf{U}$ describing the orbital rotation are obtained from an eigendecomposition of $\\mathbf{M}$:\n",
+    "where the $\\set{\\lambda_i}$ are real numbers called orbital energies, $\\mathcal{U}$ is an orbital rotation, and $n_{i\\sigma} = a^\\dagger_{i\\sigma} a_{i\\sigma}$ is the occupation number operator. The $\\set{\\lambda_i}$ and the unitary matrix $\\mathbf{U}$ describing the orbital rotation are obtained from an eigendecomposition of $\\mathbf{M}$:\n",
     "\n",
     "$$\n",
     "    \\mathbf{M}_{ij} = \\sum_k \\lambda_k \\mathbf{U}_{ik} \\mathbf{U}_{jk}^*.\n",
@@ -85,7 +85,7 @@
     "\n",
     "- Compute the orbital energies $\\set{\\lambda_i}$ and the orbital rotation matrix $\\mathbf{U}$ by performing an eigendecomposition of $\\mathbf{M}$.\n",
     "- Perform the orbital rotation $\\mathcal{U}^\\dagger$, which corresponds to the matrix $\\mathbf{U}^\\dagger$.\n",
-    "- Perform time evolution by the operator $\\sum_{\\sigma, i} \\lambda_i n_{\\sigma, i}$.\n",
+    "- Perform time evolution by the operator $\\sum_{i \\sigma} \\lambda_i n_{i\\sigma}$.\n",
     "- Perform the orbital rotation $\\mathcal{U}^\\dagger$, which corresponds to the matrix $\\mathbf{U}$.\n",
     "\n",
     "### Method 2: Implement directly as an orbital rotation\n",
@@ -135,7 +135,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The [apply_quad_ham_evolution](../api/ffsim.rst#ffsim.apply_quad_ham_evolution) function implements time evolution by a quadratic Hamiltonian. Internally, it implements the evolution directly as an orbital rotation (Method 2)."
+    "The [apply_quad_ham_evolution](../api/stubs/ffsim.apply_quad_ham_evolution.rst#ffsim.apply_quad_ham_evolution) function implements time evolution by a quadratic Hamiltonian. Internally, it implements the evolution directly as an orbital rotation (Method 2)."
    ]
   },
   {
@@ -155,7 +155,7 @@
    "source": [
     "## Quantum circuit implementation\n",
     "\n",
-    "An orbital rotation can be implemented as a quantum circuit by decomposing it into [Givens rotations](../api/ffsim.rst#ffsim.apply_givens_rotation). Under the [Jordan-Wigner transformation](https://en.wikipedia.org/wiki/Jordan%E2%80%93Wigner_transformation), the circuit can be implemented as a dense brickwork pattern of two-qubit rotations, followed by a single layer of single-qubit phase gates. The following code cell constructs and displays a Qiskit circuit for implementing an orbital rotation. Notice that the circuit consists of two independent sub-circuits acting on each spin sector."
+    "An orbital rotation can be implemented as a quantum circuit by decomposing it into [Givens rotations](../api/stubs/ffsim.apply_givens_rotation.rst#ffsim.apply_givens_rotation). Under the [Jordan-Wigner transformation](https://en.wikipedia.org/wiki/Jordan%E2%80%93Wigner_transformation), the circuit can be implemented as a dense brickwork pattern of two-qubit rotations, followed by a single layer of single-qubit phase gates. The following code cell constructs and displays a Qiskit circuit for implementing an orbital rotation. Notice that the circuit consists of two independent sub-circuits acting on each spin sector."
    ]
   },
   {
@@ -196,7 +196,11 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "When an orbital rotation is applied to a single electronic configuration (in the qubit picture, a computational basis state), the quantum circuit implementation can be optimized to use fewer gates, resulting in a \"diamond\" pattern of gates rather than a dense \"brickwork\" pattern. For additional information, see [Jiang et al. (2018)](https://arxiv.org/abs/1711.05395).\n\nThe following code cell constructs and displays an example of the optimized circuit."
+   "source": [
+    "When an orbital rotation is applied to a single electronic configuration (in the qubit picture, a computational basis state), the quantum circuit implementation can be optimized to use fewer gates, resulting in a \"diamond\" pattern of gates rather than a dense \"brickwork\" pattern. For additional information, see [Jiang et al. (2018)](https://arxiv.org/abs/1711.05395).\n",
+    "\n",
+    "The following code cell constructs and displays an example of the optimized circuit."
+   ]
   },
   {
    "cell_type": "code",
@@ -245,10 +249,10 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.11"
+   "version": "3.13.12"
   },
   "orig_nbformat": 4
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

{ffsim-0.0.72 → ffsim-0.0.74}/docs/explanations/protocols.ipynb

@@ -19,12 +19,12 @@
     "\n",
     "| Protocol | Method | Function | Description |\n",
     "|---|---|---|---|\n",
-    "| [SupportsApplyUnitary](../api/ffsim.rst#ffsim.SupportsApplyUnitary) | `_apply_unitary_` | [ffsim.apply_unitary](../api/ffsim.rst#ffsim.apply_unitary) | Apply a unitary transformation to a state vector. |\n",
-    "| [SupportsLinearOperator](../api/ffsim.rst#ffsim.SupportsLinearOperator) | `_linear_operator_` | [ffsim.linear_operator](../api/ffsim.rst#ffsim.linear_operator) | Convert to a [SciPy LinearOperator](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html). |\n",
-    "| [SupportsFermionOperator](../api/ffsim.rst#ffsim.SupportsFermionOperator) | `_fermion_operator_` | [ffsim.fermion_operator](../api/ffsim.rst#ffsim.fermion_operator) | Convert to a [FermionOperator](../api/ffsim.rst#ffsim.FermionOperator). |\n",
-    "| [SupportsTrace](../api/ffsim.rst#ffsim.SupportsTrace) | `_trace_` | [ffsim.trace](../api/ffsim.rst#ffsim.trace) | Compute the trace of a linear operator. |\n",
-    "| [SupportsDiagonal](../api/ffsim.rst#ffsim.SupportsDiagonal) | `_diag_` | [ffsim.diag](../api/ffsim.rst#ffsim.diag) | Return the diagonal entries of a linear operator.|\n",
-    "| [SupportsApproximateEquality](../api/ffsim.rst#ffsim.SupportsApproximateEquality) | `_approx_eq_` | [ffsim.approx_eq](../api/ffsim.rst#ffsim.approx_eq) | Compare objects with numerical tolerance. |"
+    "| [SupportsApplyUnitary](../api/stubs/ffsim.SupportsApplyUnitary.rst#ffsim.SupportsApplyUnitary) | `_apply_unitary_` | [ffsim.apply_unitary](../api/stubs/ffsim.apply_unitary.rst#ffsim.apply_unitary) | Apply a unitary transformation to a state vector. |\n",
+    "| [SupportsLinearOperator](../api/stubs/ffsim.SupportsLinearOperator.rst#ffsim.SupportsLinearOperator) | `_linear_operator_` | [ffsim.linear_operator](../api/stubs/ffsim.linear_operator.rst#ffsim.linear_operator) | Convert to a [SciPy LinearOperator](https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html). |\n",
+    "| [SupportsFermionOperator](../api/stubs/ffsim.SupportsFermionOperator.rst#ffsim.SupportsFermionOperator) | `_fermion_operator_` | [ffsim.fermion_operator](../api/stubs/ffsim.fermion_operator.rst#ffsim.fermion_operator) | Convert to a [FermionOperator](../api/stubs/ffsim.FermionOperator.rst#ffsim.FermionOperator). |\n",
+    "| [SupportsTrace](../api/stubs/ffsim.SupportsTrace.rst#ffsim.SupportsTrace) | `_trace_` | [ffsim.trace](../api/stubs/ffsim.trace.rst#ffsim.trace) | Compute the trace of a linear operator. |\n",
+    "| [SupportsDiagonal](../api/stubs/ffsim.SupportsDiagonal.rst#ffsim.SupportsDiagonal) | `_diag_` | [ffsim.diag](../api/stubs/ffsim.diag.rst#ffsim.diag) | Return the diagonal entries of a linear operator.|\n",
+    "| [SupportsApproximateEquality](../api/stubs/ffsim.SupportsApproximateEquality.rst#ffsim.SupportsApproximateEquality) | `_approx_eq_` | [ffsim.approx_eq](../api/stubs/ffsim.approx_eq.rst#ffsim.approx_eq) | Compare objects with numerical tolerance. |"
    ]
   },
   {
@@ -63,7 +63,7 @@
     "\n",
     "The function `ffsim.apply_unitary(vec, obj, norb, nelec, copy=True)` dispatches to this method.\n",
     "\n",
-    "Classes that implement this protocol include the variational ansatz operators such as [UCJOpSpinBalanced](../api/ffsim.rst#ffsim.UCJOpSpinBalanced) and the UCCSD operator classes."
+    "Classes that implement this protocol include the variational ansatz operators such as [UCJOpSpinBalanced](../api/stubs/ffsim.UCJOpSpinBalanced.rst#ffsim.UCJOpSpinBalanced) and the UCCSD operator classes."
    ]
   },
   {
@@ -126,9 +126,9 @@
     "    ...\n",
     "```\n",
     "\n",
-    "The function `ffsim.linear_operator(obj, norb, nelec)` dispatches to this method. It also has special handling for [FermionOperator](../api/ffsim.rst#ffsim.FermionOperator) instances, which are converted to a `LinearOperator` directly.\n",
+    "The function `ffsim.linear_operator(obj, norb, nelec)` dispatches to this method. It also has special handling for [FermionOperator](../api/stubs/ffsim.FermionOperator.rst#ffsim.FermionOperator) instances, which are converted to a `LinearOperator` directly.\n",
     "\n",
-    "The `LinearOperator` representation enables matrix-vector multiplication, eigenvalue computation, and time evolution. The Hamiltonian classes ([MolecularHamiltonian](../api/ffsim.rst#ffsim.MolecularHamiltonian), [DiagonalCoulombHamiltonian](../api/ffsim.rst#ffsim.DiagonalCoulombHamiltonian), [DoubleFactorizedHamiltonian](../api/ffsim.rst#ffsim.DoubleFactorizedHamiltonian), [SingleFactorizedHamiltonian](../api/ffsim.rst#ffsim.SingleFactorizedHamiltonian)) all implement this protocol."
+    "The `LinearOperator` representation enables matrix-vector multiplication, eigenvalue computation, and time evolution. The Hamiltonian classes ([MolecularHamiltonian](../api/stubs/ffsim.MolecularHamiltonian.rst#ffsim.MolecularHamiltonian), [DiagonalCoulombHamiltonian](../api/stubs/ffsim.DiagonalCoulombHamiltonian.rst#ffsim.DiagonalCoulombHamiltonian), [DoubleFactorizedHamiltonian](../api/stubs/ffsim.DoubleFactorizedHamiltonian.rst#ffsim.DoubleFactorizedHamiltonian), [SingleFactorizedHamiltonian](../api/stubs/ffsim.SingleFactorizedHamiltonian.rst#ffsim.SingleFactorizedHamiltonian)) all implement this protocol."
    ]
   },
   {
@@ -167,7 +167,7 @@
    "source": [
     "## SupportsFermionOperator\n",
     "\n",
-    "The `SupportsFermionOperator` protocol is for objects that can be converted to a [FermionOperator](../api/ffsim.rst#ffsim.FermionOperator), which is ffsim's symbolic representation of a [fermionic operator](../explanations/fermion-operator.ipynb) as a linear combination of products of creation and annihilation operators. A class implements this protocol by defining the `_fermion_operator_` method, which has the signature\n",
+    "The `SupportsFermionOperator` protocol is for objects that can be converted to a [FermionOperator](../api/stubs/ffsim.FermionOperator.rst#ffsim.FermionOperator), which is ffsim's symbolic representation of a [fermionic operator](../explanations/fermion-operator.ipynb) as a linear combination of products of creation and annihilation operators. A class implements this protocol by defining the `_fermion_operator_` method, which has the signature\n",
     "\n",
     "```python\n",
     "def _fermion_operator_(self) -> FermionOperator:\n",
@@ -217,7 +217,7 @@
     "\n",
     "The function `ffsim.diag(obj, norb, nelec)` dispatches to this method.\n",
     "\n",
-    "The diagonal is useful for constructing preconditioners in iterative eigensolvers like Davidson's method. The Hamiltonian classes ([MolecularHamiltonian](../api/ffsim.rst#ffsim.MolecularHamiltonian), [DiagonalCoulombHamiltonian](../api/ffsim.rst#ffsim.DiagonalCoulombHamiltonian), [DoubleFactorizedHamiltonian](../api/ffsim.rst#ffsim.DoubleFactorizedHamiltonian)) implement this protocol."
+    "The diagonal is useful for constructing preconditioners in iterative eigensolvers like Davidson's method. The Hamiltonian classes ([MolecularHamiltonian](../api/stubs/ffsim.MolecularHamiltonian.rst#ffsim.MolecularHamiltonian), [DiagonalCoulombHamiltonian](../api/stubs/ffsim.DiagonalCoulombHamiltonian.rst#ffsim.DiagonalCoulombHamiltonian), [DoubleFactorizedHamiltonian](../api/stubs/ffsim.DoubleFactorizedHamiltonian.rst#ffsim.DoubleFactorizedHamiltonian)) implement this protocol."
    ]
   },
   {
@@ -263,7 +263,7 @@
     "    ...\n",
     "```\n",
     "\n",
-    "The function `ffsim.trace(obj, norb, nelec)` dispatches to this method. This function first checks for the `_trace_` method and uses that if it exists. If the `_trace_` method does not exist, it then checks for a `_diag_` method, since the trace can be computed by summing the diagonal. Thus, classes that implement the [SupportsDiagonal](../api/ffsim.rst#ffsim.SupportsDiagonal) protocol automatically implement [SupportsTrace](../api/ffsim.rst#ffsim.SupportsTrace) as well.\n",
+    "The function `ffsim.trace(obj, norb, nelec)` dispatches to this method. This function first checks for the `_trace_` method and uses that if it exists. If the `_trace_` method does not exist, it then checks for a `_diag_` method, since the trace can be computed by summing the diagonal. Thus, classes that implement the [SupportsDiagonal](../api/stubs/ffsim.SupportsDiagonal.rst#ffsim.SupportsDiagonal) protocol automatically implement [SupportsTrace](../api/stubs/ffsim.SupportsTrace.rst#ffsim.SupportsTrace) as well.\n",
     "\n",
     "One practical use of the trace is to pass it to `scipy.sparse.linalg.expm_multiply` for Hamiltonian time evolution, which uses the trace to improve its performance. Without it, SciPy issues a warning."
    ]
@@ -345,7 +345,7 @@
     "\n",
     "The function `ffsim.approx_eq(obj, other, rtol=1e-5, atol=1e-8)` dispatches to this method. It tries `obj._approx_eq_(other)` first, then `other._approx_eq_(obj)`, and falls back to `obj == other`. The tolerance parameters `rtol` and `atol` follow the same convention as `numpy.allclose`.\n",
     "\n",
-    "This protocol is widely implemented across ffsim: Hamiltonians, ansatz operators, and [FermionOperator](../api/ffsim.rst#ffsim.FermionOperator) all support it."
+    "This protocol is widely implemented across ffsim: Hamiltonians, ansatz operators, and [FermionOperator](../api/stubs/ffsim.FermionOperator.rst#ffsim.FermionOperator) all support it."
    ]
   },
   {