updated docs (#480)

## Description

This PR updates the examples in the docs based on some mistakes that
were noticed.
This type of PR will be done periodicially.

Author: aaronleesander

CHANGELOG.md

@@ -30,6 +30,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- added trapped-ion position-grid guide and `hamiltonians` factory section ([#476]) ([**@linusschulte**])
 - simplified user-facing top-level imports ([#467]) ([**@aaronleesander**])
 - updated documentation structure and content ([#465]) ([**@aaronleesander**])
 - changed analog simulation default mode to 2TDVP ([#458]) ([**@aaronleesander**])

docs/conf.py

@@ -66,6 +66,7 @@
     "examples/strong_circuit_simulation": "examples/circuit_simulation.html",
     "examples/sample_observable_digital_tjm": "examples/circuit_simulation.html#mid-circuit-observables",
     "examples/solver_comparison": "examples/representation_comparison.html",
+    "examples/fermi_hubbard_mpo": "examples/hamiltonians.html#fermi-hubbard-1d",
 }
 
 source_suffix = [".rst", ".md"]
@@ -116,6 +117,18 @@
     ("latex", "image/svg+xml", 15),
 ]
 nb_execution_raise_on_error = True
+# Suppress noisy but harmless warnings during notebook execution (complex casts, etc.).
+nb_prolog = """
+import warnings
+
+warnings.filterwarnings("ignore", message=".*cast.*complex.*")
+warnings.filterwarnings("ignore", message=".*Casting complex values to real.*")
+try:
+    from numpy.exceptions import ComplexWarning
+except ImportError:
+    from numpy import ComplexWarning
+warnings.filterwarnings("ignore", category=ComplexWarning)
+"""
 
 
 class CDAStyle(UnsrtStyle):

docs/examples/analog_simulation.md

@@ -4,7 +4,7 @@ kernelspec:
   name: python3
 mystnb:
   number_source_lines: true
-  execution_timeout: 300
+  execution_timeout: 600
 ---
 
 ```{code-cell} ipython3
@@ -16,66 +16,48 @@ mystnb:
 
 This guide walks through an open-system **analog** simulation with the tensor jump method (TJM): build a Hamiltonian, attach a noise model, configure {class}`~mqt.yaqs.core.data_structures.simulation_parameters.AnalogSimParams`, and visualize time-resolved observables.
 
-For Gaussian (bell-curve) noise strengths and static disorder, see {doc}`realistic_noise_models`. For execution options (parallelism, progress bars), see {doc}`simulator_initialization`.
+For log-normal disorder on strengths and static calibration spread, see {doc}`realistic_noise_models`. For execution options (parallelism, progress bars), see {doc}`simulator_initialization`. To build Ising, Hubbard, Pauli-string, or hardware Hamiltonians, see {doc}`hamiltonians`.
 
 ## 1. Hamiltonian
 
-Three equivalent ways to define the transverse-field Ising model $H = -J \sum_i Z_i Z_{i+1} - g \sum_i X_i$ on an open chain:
-
 ```{code-cell} ipython3
-from mqt.yaqs import Hamiltonian, MPO
-
-L = 3
-J = 1
-g = 0.5
+from mqt.yaqs import Hamiltonian
 
-# Method 1: built-in constructor
+L = 5
+J, g = 1.0, 0.8
 H_0 = Hamiltonian.ising(L, J, g)
-
-# Method 2: generic Pauli interface
-H_0 = Hamiltonian.pauli(
-    length=L,
-    two_body=[(-J, "Z", "Z")],
-    one_body=[(-g, "X")],
-    bc="open",
-)
-
-# Method 3: explicit Pauli-string MPO
-terms = [(-J, f"Z{i} Z{i+1}") for i in range(L - 1)] + [(-g, f"X{i}") for i in range(L)]
-mpo = MPO()
-mpo.from_pauli_sum(terms=terms, length=L)
-H_0 = Hamiltonian.from_mpo(mpo)
 ```
 
+See {doc}`hamiltonians` for Pauli sums, Fermi–Hubbard, Bose–Hubbard, and coupled-transmon factories.
+
 ## 2. Initial state and noise model
 
+We prepare a Néel state $\ket{01010\ldots}$ and track staggered magnetization under a transverse-field Ising model with on-site amplitude damping. The alternating $\langle Z_i \rangle$ pattern at $t=0$ spreads and decays in a site-dependent way.
+
 ```{code-cell} ipython3
 from mqt.yaqs import NoiseModel, State
 
-state = State(L, initial="zeros")
-# Alternative: State(L, initial="haar-random", pad=4)
+state = State(L, initial="Neel")
 
-gamma = 0.1
+gamma = 0.08
 noise_model = NoiseModel([
-    {"name": name, "sites": [i], "strength": gamma}
-    for i in range(L)
-    for name in ["lowering", "pauli_z"]
+    {"name": "lowering", "sites": [i], "strength": gamma} for i in range(L)
 ])
 ```
 
-Pass a float for each `strength` here. For distribution-valued strengths (Gaussian and other distributions), see {doc}`realistic_noise_models`.
+Pass a float for each `strength` here. For distribution-valued strengths (log-normal and other distributions), see {doc}`realistic_noise_models`.
 
 ## 3. Simulation parameters
 
 ```{code-cell} ipython3
 from mqt.yaqs import AnalogSimParams, Observable
 
 sim_params = AnalogSimParams(
-    observables=[Observable("x", site) for site in range(L)],
-    elapsed_time=10,
+    observables=[Observable("z", site) for site in range(L)],
+    elapsed_time=6.0,
     dt=0.1,
-    num_traj=100,
-    max_bond_dim=4,
+    num_traj=20,
+    max_bond_dim=16,
     svd_threshold=1e-6,
     order=2,
     sample_timesteps=True,
@@ -91,17 +73,20 @@ Optional `tdvp_sweeps` (default `1`) runs multiple symmetric TDVP substeps per p
 With `num_traj > 1`, each {meth}`~mqt.yaqs.Simulator.run` call averages independent quantum-jump trajectories. Set {attr}`~mqt.yaqs.core.data_structures.simulation_parameters.AnalogSimParams.random_seed` to fix the pseudorandom stream across trajectories (and for distribution-valued noise strengths):
 
 ```{code-cell} ipython3
+---
+tags: [remove-output]
+---
 import copy
 
 import numpy as np
 
 from mqt.yaqs import AnalogSimParams, Observable, Simulator
 
 repro_params = AnalogSimParams(
-    observables=[Observable("x", site) for site in range(L)],
+    observables=[Observable("z", site) for site in range(L)],
     elapsed_time=1.0,
     dt=0.1,
-    num_traj=50,
+    num_traj=16,
     max_bond_dim=4,
     svd_threshold=1e-6,
     order=2,
@@ -121,8 +106,6 @@ def run_reproducible() -> list[np.ndarray]:
 
 first_run = run_reproducible()
 second_run = run_reproducible()
-assert all(np.allclose(a, b) for a, b in zip(first_run, second_run, strict=True))
-print("Both runs produced identical trajectory-averaged observables.")
 ```
 
 The same `random_seed` field exists on {class}`~mqt.yaqs.core.data_structures.simulation_parameters.StrongSimParams` and {class}`~mqt.yaqs.core.data_structures.simulation_parameters.WeakSimParams`.
@@ -147,22 +130,18 @@ import matplotlib.pyplot as plt
 
 heatmap = result.expectation_values
 
-fig, ax = plt.subplots(figsize=(5, 3))
-im = ax.imshow(heatmap, aspect="auto", extent=(0, 10, L, 0), vmin=0, vmax=0.5)
+fig, ax = plt.subplots(figsize=(7, 4), layout="constrained")
+im = ax.imshow(heatmap, aspect="auto", extent=(0, 6, L, 0), vmin=-1, vmax=1)
 ax.set_xlabel("Time")
 ax.set_yticks([x - 0.5 for x in range(1, L + 1)], [str(x) for x in range(L)])
 ax.set_ylabel("Site")
-
-fig.subplots_adjust(top=0.95, right=0.88)
-cbar_ax = fig.add_axes(rect=(0.9, 0.11, 0.025, 0.8))
-cbar = fig.colorbar(im, cax=cbar_ax)
-cbar.ax.set_title(r"$\langle X \rangle$")
-plt.tight_layout()
+fig.colorbar(im, ax=ax, shrink=0.9, label=r"$\langle Z \rangle$")
 plt.show()
 ```
 
 ## Related topics
 
+- {doc}`hamiltonians` — Pauli, Hubbard, and hardware Hamiltonians
 - {doc}`representation_comparison` — MPS, MCWF, and Lindblad backends
 - {doc}`scheduled_jumps` — deterministic jumps at specified times
 - {doc}`ensemble_evolution` — unitary ensemble correlations