Skip to content

AGENTS.md

Latest commit

 

History

History
90 lines (76 loc) · 4.08 KB

AGENTS.md

File metadata and controls

90 lines (76 loc) · 4.08 KB
Raw

src_method agent guide

A pure-Python implementation of Successive Randomized Compression (SRC) for tensor networks. apply contracts and compresses MPO-MPS and MPO-MPO products, compress truncates a single MPO or MPS. Trains are plain lists of per-site NumPy arrays; MPS against MPO is inferred from the rank of the first site tensor, so there is no wrapper type.

Rules

  • Target Python 3.11-3.14. Type hints everywhere, from __future__ import annotations at the top of every module.
  • Google-style docstrings without types (types live in the signature) on every public function, class and module.
  • ruff is the source of truth for style: the formatter wraps at 88 columns (E501 only fires past 120), 4-space indent, the rule set in pyproject.toml. Do not hand-format around it.
  • snake_case for functions and variables, CamelCase for classes. N803 and N806 are off so that matrices can keep their mathematical names (Q, R, A); that licence does not extend to anything else.
  • Comment invariants, contracts and non-obvious numerical choices only. Never narrate the code.
  • Backend-agnostic code: go through src_method.utils._backend instead of importing numpy or cupy directly in the algorithms, so CPU and GPU paths stay in sync.
  • Log with the standard library: logger = logging.getLogger(__name__) per module, lazy %-style arguments, never print. Never add handlers, levels or basicConfig in the package; progress messages go at DEBUG.
  • Run uv run prek run --all-files and the relevant tests before pushing, and fix every finding. lint.yml runs the same hooks in CI, so a skipped lint is a red PR.
  • Changes to the API or to user-facing behavior -- developers included, e.g. workflows or test layout -- belong in the docs and, when relevant, in README.md. docs/content/docs/contributing/ covers versioning, dependencies, tests and the docs site; read it before changing any of those. Python blocks in the docs pages run in CI: keep them self-contained, or mark them python notest.

Git and PRs

  • Commits and PR titles: <type>(<optional scope>): <gitmoji> <description>. Types: feat (minor), fix (patch), docs, style, refactor, test, chore; ! for breaking changes.
  • Agent commits carry Assisted-by: <harness>:<model> and no Co-authored-by.
  • Prefix agent-authored PR descriptions and comments with :robot: _AI text below_ :robot:.

Layout

Package src/src_method/: apply.py and compress.py are the public entry points, _tensor_train.py holds the shared train helpers, utils/_backend.py the NumPy/CuPy dispatch and utils/linalg.py the decompositions. Tests in tests/, benchmarks in benches/ with recorded results in baseline-benchmarks/, the Fumadocs site in docs/ (MDX pages in docs/content/docs/, tutorial notebooks in docs/notebooks/), throwaway scripts in sandbox/.

src/src_method/_version.py is generated by hatch-vcs -- never edit it.

Commands

We use uv for environment management.

uv sync --all-groups --all-extras
uv run prek install --prepare-hooks
uv run pytest -m "not slow"    # fast suite
uv run pytest                  # everything
uv run ruff check src/ tests/
uv run ty check src/

Docs site (Node.js 22+), from docs/: npm ci, then uv run python scripts/gen_api_dump.py src_method -d ., node scripts/generate-api.mjs, uv run python scripts/notebooks_to_mdx.py and npm run dev.

Notes

  • filterwarnings = ["error"] is on: a stray warning fails the suite. Networks with fewer than three sites intentionally warn and fall back to an exact SVD, so those tests must assert the warning.
  • Markers: slow (>=1 minute) and perf (benchmark). Mark anything long, the PR suite runs -m "not slow".
  • GPU tests in tests/test_gpu_backend.py skip without CuPy; the GPU extras are gpu-nvidia (CUDA) and gpu-rocm.
  • Array layouts follow the quimb conventions: MPO bulk tensors are ('l', 'r', 'u', 'd'), MPS bulk tensors ('l', 'r', 'u'), boundary tensors drop the outer bond index.
  • apply and compress are pure; never mutate the input arrays.