[ci/cd - documentation checker] script that checks the status of the documentaiton

.github/workflows/lint_test.yml

@@ -26,6 +26,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: python ./test_dependency_versions.py
+  check_docs:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - run: pip install -e .
+      - name: Check documentation drift and external links
+        run: python scripts/doc_detector.py --check-signatures --check-external-links
   test:
     needs: check_dependency_versions
     runs-on: ${{ matrix.os }}

.github/workflows/publish.yml

@@ -14,8 +14,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  validate_docs:
+    name: Validate documentation
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: |
+          pip install -e .
+          pip install playwright aiohttp
+          playwright install chromium
+      - name: Run full documentation checks
+        run: python scripts/doc_detector.py --check-all -v
+
   publish_emu_base:
     name: Publish emu-base to PyPI
+    needs: validate_docs
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     permissions:

docs/emu_mps/api.md

@@ -10,6 +10,11 @@ The implementation of the base classes is as follows:
 ## MPSConfig
 ::: emu_mps.mps_config.MPSConfig
 
+## Solver
+::: emu_mps.solver.Solver
+    options:
+        members: false
+
 ## MPS
 ::: emu_mps.mps.MPS
 

docs/emu_mps/index.md

@@ -6,40 +6,71 @@ You have found the documentation for emu-mps. The emulator **emu-mps** is a back
 
 The following features are currently supported:
 
-- All Pulser sequences that use only the rydberg channel
-- MPS and MPO can be constructed using the abstract Pulser format.
-- All noise from the pulser `NoiseModel` except leakage
-    - Effective noise is included using [Monte Carlo quantum jumps](https://pulser.readthedocs.io/en/stable/tutorials/effective_noise.html)
+- All Pulser sequences that use only rydberg (`ground-rydberg` basis) and only microwave (`XY` basis) channel
+- MPS and MPO can be constructed using the abstract Pulser format and following the correspondent basis format
+- All noise from the pulser `NoiseModel`
+  - Effective noise (`eff_noise`) is included using jump or [collapse operators](https://pulser.readthedocs.io/en/stable/noise_model.html#Describing-noise-in-neutral-atom-QPUs-with-a-NoiseModel) and emu-mps uses the quantum jump method or Monte Carlo wave function (MCWF) approach.
 - The following [basis states](https://pulser.readthedocs.io/en/stable/conventions.html) in a sequence:
-    - [ground-rydberg](https://pulser.readthedocs.io/en/stable/review.html#programmable-arrays-of-rydberg-atoms)
-    - [XY](https://pulser.readthedocs.io/en/stable/tutorials/xy_spin_chain.html)
+
+  - [ground-rydberg](./notebooks/getting_started.ipynb)
+
+  - [XY](https://pulser.readthedocs.io/en/stable/tutorials/xy_spin_chain.html)
+
 - The following properties from a Pulser Sequence are also correctly applied:
-    - [hardware modulation](https://pulser.readthedocs.io/en/stable/tutorials/output_mod_eom.html)
-    - [SLM mask](https://pulser.readthedocs.io/en/stable/tutorials/slm_mask.html)
-    - A complex phase for the omega parameter
+
+  - [hardware modulation](https://pulser.readthedocs.io/en/stable/tutorials/output_mod_eom.html)
+
+  - [SLM mask](https://pulser.readthedocs.io/en/stable/tutorials/slm_mask.html)
+
+  - A complex phase for the omega parameter, i.e. the phase $\phi$ in the [driving Hamiltonian](https://pulser.readthedocs.io/en/stable/programming.html#driving-hamiltonian)
+
 - Customizable output, with the folowing inbuilt options:
-    - The quantum state in MPS format
-    - Bitstrings
-    - The fidelity with respect to a given state
-    - The expectation of a given operator
-    - The qubit density (magnetization)
-    - The correlation matrix
-    - The mean, second moment and variance of the energy
-    - Entanglement entropy
-- Specification of
-    - Initial state
-    - Various precision parameters
-    - Whether to run on cpu or gpu(s)
-    - The $U_{ij}$ coefficients from [here](./advanced/hamiltonian.md)
-    - A cutoff below which $U_{ij}$ are set to 0 (this makes the computation more memory efficient)
+
+  - The quantum state in MPS format
+
+  - Bitstrings
+
+  - The fidelity with respect to a given state
+
+  - The expectation of a given operator (as `MPO` or `MPO._from_operator_repr`)
+
+  - The qubit density (magnetization)
+
+  - The correlation matrix
+
+  - The mean, second moment and variance of the energy
+
+  - Entanglement entropy
+
+  - computational statistics: each time step during the simulation will generate the following information:
+
+    - $\chi$ : is the maximum bond dimension of the MPS
+
+    - $|\Psi|$: MPS (the state) memory footprint
+
+    - RSS: max memory allocation
+
+    - $\Delta t$: time that the step took to run (given in seconds)
+
+- Specification of:
+
+  - Initial state ( as `MPS` or `MPS._from_state_amplitudes`)
+
+  - Various precision parameters
+
+  - Whether to run on cpu or gpu(s)
+
+  - The interaction coefficients $U_{ij}$ from [here](./advanced/hamiltonian.md#qpu-hamiltonian)
+
+  - A cutoff below which $U_{ij}$ are set to 0 (this makes the computation more memory efficient)
 
 ## Planned features
 
 - More efficient use of GPU by storing tensors on CPU where possible.
-- Leakage noise.
 - Differentiability.
 
 ## More Info
+
 Please see the API specification for a list of available config options ([see here](api.md)).
 Those configuration options relating to the mathematical functioning of the backend are explained in more detail in the config page ([see here](advanced/config.md)).
 For notebooks with examples for how to do various things, please see the notebooks page ([see here](./notebooks/index.md)).

docs/emu_sv/api.md

@@ -16,3 +16,6 @@ The emu-sv API is based on the specification [here](../base_classes.md). Concret
 
 ## DenseOperator
 ::: emu_sv.dense_operator.DenseOperator
+
+## DensityMatrix
+::: emu_sv.density_matrix_state.DensityMatrix

emu_mps/mpo.py

@@ -21,6 +21,8 @@ class MPO(Operator[complex, torch.Tensor, MPS]):
 
     Args:
         factors: the tensors making up the MPO
+        num_gpus_to_use: distribute the factors over this many GPUs.
+            If None, keeps the existing device assignment.
     """
 
     def __init__(

emu_mps/mps.py

@@ -28,6 +28,17 @@ class MPS(State[complex, torch.Tensor]):
     Each tensor has 3 dimensions ordered as such: (left bond, site, right bond).
 
     Only qubits are supported.
+
+    Args:
+        factors: the tensors for each site. WARNING: for efficiency, this list
+            is NOT deep-copied. The MPS may share ownership with the caller.
+        orthogonality_center: the orthogonality center of the MPS, or None
+            (in which case it will be orthogonalized when needed).
+        precision: the truncation precision threshold for this MPS.
+        max_bond_dim: the maximum bond dimension to allow for this MPS.
+        num_gpus_to_use: distribute the factors over this many GPUs.
+            0=all factors to cpu, None=keep the existing device assignment.
+        eigenstates: the basis eigenstates, e.g. ("r", "g") or ("0", "1").
     """
 
     def __init__(

emu_mps/mps_backend.py

@@ -12,6 +12,11 @@ class MPSBackend(EmulatorBackend):
     """
     A backend for emulating Pulser sequences using Matrix Product States (MPS),
     aka tensor trains.
+
+    Args:
+        sequence: the Pulser sequence to emulate.
+        config: configuration options for the MPS backend (MPSConfig).
+        mimic_qpu: if True, mimics QPU behavior more closely.
     """
 
     default_config = MPSConfig()

emu_mps/solver.py

@@ -2,5 +2,25 @@
 
 
 class Solver(str, Enum):
+    """Solver algorithm for evolving the quantum state.
+
+    The solver parameter selects the algorithm used to evolve the system
+    using a Pulser sequence.
+
+    Attributes:
+        TDVP: Time-Dependent Variational Principle algorithm.
+            Performs real-time evolution of the MPS using the two-site
+            TDVP algorithm. This is the default solver.
+        DMRG: Density Matrix Renormalization Group algorithm.
+            Variationally minimizes the effective Hamiltonian using
+            the two-site DMRG algorithm. Typically used for simulating
+            adiabatic sequences.
+
+    Examples:
+        >>> from emu_mps import MPSConfig, Solver
+        >>> config = MPSConfig(solver=Solver.TDVP)  # default
+        >>> config = MPSConfig(solver=Solver.DMRG)  # for adiabatic sequences
+    """
+
     TDVP = "tdvp"
     DMRG = "dmrg"

emu_sv/dense_operator.py

@@ -20,7 +20,13 @@
 
 
 class DenseOperator(Operator[complex, torch.Tensor, StateVector]):
-    """DenseOperator in EMU-SV use dense matrices"""
+    """
+    DenseOperator in EMU-SV uses dense matrices.
+
+    Args:
+        matrix: the dense matrix representation of the operator.
+        gpu: if True, stores the matrix on GPU when available.
+    """
 
     def __init__(
         self,

emu_sv/density_matrix_state.py

@@ -15,7 +15,13 @@
 
 
 class DensityMatrix(State[complex, torch.Tensor]):
-    """Represents a density matrix in a computational basis."""
+    """
+    Represents a density matrix in a computational basis.
+
+    Args:
+        matrix: 2D tensor representation of the density matrix.
+        gpu: if True, stores the matrix on GPU when available.
+    """
 
     # for the moment no need to check positivity and trace 1
     def __init__(

emu_sv/state_vector.py

@@ -26,9 +26,10 @@ class StateVector(State[complex, torch.Tensor]):
     manipulation, and measurement. The state vector must have a length
     that is a power of 2, representing 2ⁿ basis states for n qubits.
 
-    Attributes:
+    Args:
         vector: 1D tensor representation of a state vector.
-        gpu: store the vector on GPU if True, otherwise on CPU
+        gpu: if True, stores the vector on GPU when available.
+        eigenstates: the basis eigenstates, e.g. ("r", "g") or ("0", "1").
     """
 
     def __init__(

emu_sv/sv_backend.py

@@ -8,7 +8,12 @@ class SVBackend(EmulatorBackend):
     """
     A backend for emulating Pulser sequences using state vectors and sparse matrices.
     Noisy simulation is supported by solving the Lindblad equation and using effective
-    noise channel or jump operators
+    noise channel or jump operators.
+
+    Args:
+        sequence: the Pulser sequence to emulate.
+        config: configuration options for the state vector backend (SVConfig).
+        mimic_qpu: if True, mimics QPU behavior more closely.
     """
 
     default_config = SVConfig()

mkdocs.yml

@@ -121,7 +121,6 @@ extra_css:
 # For mathjax
 extra_javascript:
   - extras/javascripts/mathjax.js
-  - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
 watch: