Merge pull request #39 from simsaidan/aidandocstrings

Add executable API docs and Google-style util docstrings.

Author: simsaidan

.github/workflows/deploy-docs.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Install documentation dependencies
         run: uv sync --locked --group docs --no-dev
       - name: Build site
-        run: uv run mkdocs build
+        run: uv run mkdocs build --strict
       - uses: actions/upload-pages-artifact@v3
         with:
           path: site

docs/index.md

@@ -10,7 +10,7 @@ hide:
 
     ---
 
-    Narrative guides and API reference will land here as the library stabilizes.
+    Start with the [API reference](reference/utils.md) for standalone utilities.
 
 -   :material-github:{ .lg .middle } __Source__
 

docs/javascript/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true,
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex",
+  },
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise();
+});

docs/reference/combined_hamiltonian_matrix.md

@@ -0,0 +1,5 @@
+# Combined Hamiltonian matrix
+
+Build a full-system Hamiltonian matrix from local and global terms.
+
+::: shadowsim.core.combined_hamiltonian_matrix.combined_hamiltonian_matrix

docs/reference/utils.md

@@ -0,0 +1,23 @@
+# Utils
+
+Standalone matrix and helper utilities.
+
+::: shadowsim.utils.hermitian.hermitian
+
+::: shadowsim.utils.unitary.unitary
+
+::: shadowsim.utils.positive_definite.positive_definite
+
+::: shadowsim.utils.positive_semidefinite.positive_semidefinite
+
+::: shadowsim.utils.negative_definite.negative_definite
+
+::: shadowsim.utils.negative_semidefinite.negative_semidefinite
+
+::: shadowsim.utils.indefinite.indefinite
+
+::: shadowsim.utils.tensor.tensor
+
+::: shadowsim.utils.flip_dict.flip_dict
+
+::: shadowsim.utils.next_power_of_two.next_power_of_two

mkdocs.yml

@@ -40,12 +40,16 @@ theme:
 
 markdown_extensions:
   - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - admonition
   - pymdownx.details
   - attr_list
   - md_in_html
+  - pymdownx.arithmatex:
+      generic: true
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
@@ -54,10 +58,36 @@ markdown_extensions:
 
 nav:
   - Home: index.md
+  - API Reference:
+      - Utils: reference/utils.md
+      - Combined Hamiltonian matrix: reference/combined_hamiltonian_matrix.md
 
 plugins:
   - meta
   - search
+  - markdown-exec
+  - mkdocstrings:
+      handlers:
+        python:
+          paths:
+            - .
+          options:
+            show_root_heading: true
+            show_root_full_path: false
+            show_source: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            heading_level: 2
+            signature_crossrefs: true
+            separate_signature: true
+            docstring_style: google
+            docstring_section_style: list
+            show_signature_annotations: true
+            members_order: source
+
+extra_javascript:
+  - javascript/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
 
 extra:
   social:

pyproject.toml

@@ -39,6 +39,10 @@ dev = [
 docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+    "markdown-exec[ansi]>=1.7",
+    # Needed so mkdocstrings can format signatures during the docs build.
+    "ruff==0.16.0",
 ]
 lint = [
     "ruff==0.16.0",
@@ -101,6 +105,9 @@ ignore = ["D407", "D203", "D213", "D416", "PLR0912", "PLR0911", "PLR0915", "PLR2
 # E203 -- Whitespace before ':'. This rule conflicts with Black's formatting style.
 # It was removing definitions with the same name creating conflicts in test_is_stochastic.py
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.ruff.lint.pylint]
 # Simulator constructors take many positional model parameters (default limit is 5).
 max-positional-args = 15

shadowsim/core/combined_hamiltonian_matrix.py

@@ -10,18 +10,40 @@ def combined_hamiltonian_matrix(
     hamiltonians: list[Hamiltonian],
     num_qubits: int,
 ) -> np.ndarray:
-    """Sum Hamiltonian terms on the full ``num_qubits``-site tensor space.
+    r"""Sum Hamiltonian terms on the full ``num_qubits``-site tensor space.
 
     ``LocalHamiltonian`` terms are embedded with identities on the remaining
     sites; full-domain ``Hamiltonian`` matrices are added as-is. All terms must
     match a common Hilbert-space dimension (``local_dim ** num_qubits`` for
     locals, or the matrix size of bare terms).
 
-    Parameter hamiltonians: The list of Hamiltonians to sum.
-    Precondition: hamiltonians is a list of Hamiltonian objects.
+    Args:
+        hamiltonians: Non-empty list of ``Hamiltonian`` objects to sum.
+        num_qubits: Positive number of sites in the full system.
+
+    Returns:
+        Complex matrix of shape ``(d, d)`` equal to the sum of the (embedded)
+        terms, where ``d`` is the shared Hilbert-space dimension.
+
+    Raises:
+        ValueError: If ``LocalHamiltonian`` terms use mixed ``local_dim`` values,
+            or if term dimensions disagree for the requested ``num_qubits``.
+        AssertionError: If ``hamiltonians`` / ``num_qubits`` fail basic type and
+            positivity checks.
+
+    Examples:
+        Embed a single-site \(Z\) into a three-qubit chain and inspect the shape:
+
+        ```python exec="1" source="above" result="text"
+        import numpy as np
+        from shadowsim.core import LocalHamiltonian
+        from shadowsim.core.combined_hamiltonian_matrix import combined_hamiltonian_matrix
+
+        local = LocalHamiltonian(np.diag([1.0, -1.0]), sites=[1], local_dim=2)
+        out = combined_hamiltonian_matrix([local], num_qubits=3)
+        print(out.shape)
+        ```
 
-    Parameter num_qubits: The number of qubits in the full system.
-    Precondition: num_qubits is a positive integer.
     """
     assert isinstance(hamiltonians, list), "hamiltonians must be a list"
     assert all(isinstance(h, Hamiltonian) for h in hamiltonians), "all hamiltonians must be Hamiltonian objects"

shadowsim/utils/flip_dict.py

@@ -1,9 +1,29 @@
 """Helpers for reversing dictionary keys (bitstring endianness)."""
 
+from typing import Any
 
-def flip_dict(d):
+
+def flip_dict(d: dict[str, Any]) -> dict[str, Any]:
     """Return a new dictionary with each string key reversed.
 
-    This is used to switch the endianness of measurement results.
+    Measurement outcomes are often labeled by bitstrings whose endianness
+    differs between frameworks; reversing the keys converts between those
+    conventions.
+
+    Args:
+        d: Mapping whose keys are strings (typically measurement bitstrings).
+
+    Returns:
+        A new dictionary with the same values and each key reversed.
+
+    Examples:
+        Flip Qiskit-style bitstring keys:
+
+        ```python exec="1" source="above" result="text"
+        from shadowsim.utils.flip_dict import flip_dict
+
+        print(flip_dict({"01": 3, "10": 5}))
+        ```
+
     """
     return {k[::-1]: v for k, v in d.items()}

shadowsim/utils/hermitian.py

@@ -3,6 +3,37 @@
 import numpy as np
 
 
-def hermitian(H):
-    """Return whether the NumPy matrix ``H`` is Hermitian."""
+def hermitian(H: np.ndarray) -> bool:
+    r"""Return whether the NumPy matrix ``H`` is Hermitian.
+
+    A square matrix \(H\) is Hermitian when it equals its conjugate transpose,
+    \(H = H^\dagger\).
+
+    Args:
+        H: Square complex matrix.
+
+    Returns:
+        ``True`` if ``H`` is Hermitian up to numerical tolerance, else ``False``.
+
+    Examples:
+        The Pauli \(Y\) matrix is Hermitian:
+
+        ```python exec="1" source="above" result="text"
+        import numpy as np
+        from shadowsim.utils.hermitian import hermitian
+
+        Y = np.array([[0.0, -1j], [1j, 0.0]])
+        print(hermitian(Y))
+        ```
+
+        A non-symmetric complex matrix is not:
+
+        ```python exec="1" source="above" result="text"
+        import numpy as np
+        from shadowsim.utils.hermitian import hermitian
+
+        print(hermitian(np.array([[1.0 + 2j, 0.0], [0.0, 0.0]])))
+        ```
+
+    """
     return np.allclose(H, H.conjugate().T)