From f93de0d4c15d1466835cd7fea7ae47d1e2079a91 Mon Sep 17 00:00:00 2001 From: tjkessler Date: Fri, 17 Jul 2026 01:23:40 -0400 Subject: [PATCH] Clean up public documentation wording. Co-authored-by: Cursor --- CONTRIBUTING.md | 25 ++++---------------- docs/source/api.rst | 14 +++++------ docs/source/architecture.rst | 46 +++++++++++++++++------------------- docs/source/quickstart.rst | 2 +- 4 files changed, 35 insertions(+), 52 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 827aa6a..b4a9e86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -237,15 +237,15 @@ handling, read the maintainer architecture guide: - It defines the public façade vs power-user modules vs private (`_`-prefixed) helpers (**thin root `__all__`**: keep core workflow symbols; demote specialized helpers to `metrics` / `analysis` / `data` / `adaptation` / - `observables` — TASK-747–750), device/tensor conventions across `fit`, the - RL env, online adaptation, and classical baselines/datasets, plus - **optional-dependency** (fail-at-call / `[rl]` soft-import) and **frozen - dataclass result-type** conventions. + `observables`), device/tensor conventions across `fit`, the RL env, online + adaptation, and classical baselines/datasets, plus **optional-dependency** + (fail-at-call / `[rl]` soft-import) and **frozen dataclass result-type** + conventions. - **Package layout** (same page): when to nest into one-level capability packages vs stay flat; keep `model.py` at the package root; no deep trees; three-layer API preserved under any folder move; compatibility contract for root `__all__` vs power-user deep imports (same-named packages or in-repo - migration — no long-lived root shim modules after TASK-746). + migration — no long-lived root shim modules). ## Releasing @@ -373,21 +373,6 @@ pip install torch torch-geometric pip install dist/koopman_graph-*.whl ``` -## Agent-assisted development - -This repository maintains a development blueprint for structured, task-oriented -work—particularly useful when using AI coding agents: - -- **[Development Blueprint](docs/BLUEPRINT.md)** — phased task tracker with - acceptance criteria, dependencies, and agent logs. - -Agents working from the blueprint should read one task at a time, present a -plan for user approval, and update the blueprint status upon completion. During -the plan gate, consult -[`docs/source/architecture.rst`](docs/source/architecture.rst) whenever a task -touches exports, internal helpers, or device placement. Human contributors may -use the blueprint as a roadmap but are not required to follow it. - ## License By contributing to KoopmanGraph, you agree that your contributions will be diff --git a/docs/source/api.rst b/docs/source/api.rst index 09d9b48..da30f6d 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -32,7 +32,7 @@ Built-in encoders live in :mod:`koopman_graph.nn` (``encoder``, ``decoder``, ``gnn``). Prefer ``from koopman_graph import GNNEncoder, GATEncoder`` for application code, or ``from koopman_graph.nn import …`` for power-user imports. Former deep imports ``koopman_graph.encoder`` / ``decoder`` / ``gnn`` were -removed in v0.3.0 (TASK-746). +removed in v0.3.0. .. automodule:: koopman_graph.nn.encoder :members: @@ -62,7 +62,7 @@ Physics-Informed Observables ---------------------------- Hybrid physics helpers such as ``graph_laplacian_features`` are imported from -:mod:`koopman_graph.observables` only (TASK-750). Prefer +:mod:`koopman_graph.observables` only. Prefer ``physics_preset="graph_laplacian"`` on :class:`~koopman_graph.model.GraphKoopmanModel` for the built-in Laplacian path; pass a custom ``physics_lifting_fn`` when needed. @@ -78,7 +78,7 @@ Built-in operators live in :mod:`koopman_graph.operators` (``contract``, KoopmanOperator, ContinuousKoopmanOperator`` or ``from koopman_graph.operators import …``. Former deep imports ``koopman_graph.operator`` / ``koopman_graph.continuous`` were removed in -v0.3.0 (TASK-746). +v0.3.0. .. automodule:: koopman_graph.operators :members: @@ -96,7 +96,7 @@ the root façade. Specialized helpers (``compute_generator_spectrum``, ``spectrum_distance``, ``koopman_std``, ``dynamical_similarity``, ``detect_anomaly``, ``calibrate_anomaly_threshold``, ``AnomalyDetectionResult``, ``plot_spectrum``) are imported from -:mod:`koopman_graph.analysis` only (TASK-749 / TASK-751). The helpers live in +:mod:`koopman_graph.analysis` only. The helpers live in the ``spectrum`` / ``similarity`` / ``anomaly`` / ``plotting`` submodules. ``plot_spectrum`` requires Matplotlib (``pip install matplotlib`` or the ``[dev]`` extra). @@ -154,7 +154,7 @@ Data Utilities Containers and split helpers (``GraphSnapshotSequence``, ``MultiTrajectory``, ``TemporalSplit``, ``temporal_split``, ``WindowSampler``) remain on the root façade. ``as_multi_trajectory`` is imported from :mod:`koopman_graph.data` -only (TASK-750). +only. .. automodule:: koopman_graph.data :members: @@ -194,7 +194,7 @@ Metrics Primary forecast evaluation entrypoints (``evaluate_forecast``, ``EvaluationResult``) remain on the root façade. Low-level helpers (``mae``, ``rmse``, ``mape``, ``HorizonMetrics``) are imported from -:mod:`koopman_graph.metrics` only (TASK-748). +:mod:`koopman_graph.metrics` only. .. automodule:: koopman_graph.metrics :members: @@ -205,7 +205,7 @@ Online Adaptation ``RecursiveKoopmanAdapter`` remains on the root façade. ``AdaptationStepResult`` is imported from :mod:`koopman_graph.adaptation` -only (TASK-750). +only. .. automodule:: koopman_graph.adaptation :members: diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 398abf0..6868825 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -63,8 +63,8 @@ Convert a flat module into a capability package when **any** of these hold: * **Room to grow peers** — a new classical method or GNN variant should land as a sibling module, not another flat mega-file. -Phase 8 capability packages (TASK-740–745): ``training/``, ``data/``, -``operators/``, ``nn/``, ``analysis/``, and ``baselines/`` (all landed). +Phase 8 capability packages: ``training/``, ``data/``, ``operators/``, +``nn/``, ``analysis/``, and ``baselines/`` (all landed). ``koopman_graph.training`` package layout: @@ -95,7 +95,7 @@ Phase 8 capability packages (TASK-740–745): ``training/``, ``data/``, Prefer ``from koopman_graph.operators import …`` (or the root façade for public operator classes). Former root modules ``koopman_graph.operator`` and -``koopman_graph.continuous`` were removed in v0.3.0 (TASK-746). +``koopman_graph.continuous`` were removed in v0.3.0. ``koopman_graph.nn`` package layout (peer encoder / decoder / GNN primitives; PyG-style ``nn`` capability package, no ``conv/`` subtree): @@ -109,8 +109,8 @@ PyG-style ``nn`` capability package, no ``conv/`` subtree): Prefer ``from koopman_graph.nn import …`` (or the root façade for public classes). Former root modules ``koopman_graph.encoder``, -``koopman_graph.decoder``, and ``koopman_graph.gnn`` were removed in v0.3.0 -(TASK-746). Encoder and decoder remain peers: both import from ``nn.gnn``; +``koopman_graph.decoder``, and ``koopman_graph.gnn`` were removed in v0.3.0. +Encoder and decoder remain peers: both import from ``nn.gnn``; neither imports the other. ``koopman_graph.analysis`` package layout (spectrum / similarity / anomaly / @@ -189,8 +189,8 @@ Moving files must **not** change the layering contract above: Folders are an organization tool; they do not create a fourth API tier. -Compatibility contract (TASK-740–746) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compatibility contract +~~~~~~~~~~~~~~~~~~~~~~ When splitting or nesting modules: @@ -206,7 +206,7 @@ When splitting or nesting modules: * **Migrate in-repo** — update every docs/tests/notebook deep import to the new path and record the rename here. **Do not** add long-lived root shim modules for renamed paths (``operator`` → ``operators``, ``encoder`` → - ``nn.encoder``, …). v0.3.0 removed the TASK-742/743 shims (TASK-746). + ``nn.encoder``, …). v0.3.0 removed those temporary root shims. Do not leave half-migrated import paths. Serialization type strings and checkpoint reconstruct rules stay intact unless a task explicitly bumps @@ -223,10 +223,10 @@ Public façade Stable, supported entry points re-exported from :mod:`koopman_graph` (see ``__all__``). Prefer these in tutorials, notebooks, and application code. -v0.3.0 uses a **thin** root façade (TASK-747–750): keep the core encode → -evolve → decode / fit / evaluate workflow at the package root; import -specialized helpers from capability modules. Demotions are a **hard cut** -(no root deprecation aliases), consistent with TASK-746 shim removal. +v0.3.0 uses a **thin** root façade: keep the core encode → evolve → decode / +fit / evaluate workflow at the package root; import specialized helpers from +capability modules. Demotions are a **hard cut** (no root deprecation +aliases), consistent with the shim-removal policy above. **Keep in** ``koopman_graph.__all__`` (core workflow): @@ -268,16 +268,15 @@ Dataset generators remain via :mod:`koopman_graph.datasets` (not root ``__all__``): * :mod:`koopman_graph.metrics` — ``mae``, ``rmse``, ``mape``, - ``HorizonMetrics`` (landed in TASK-748) + ``HorizonMetrics`` * :mod:`koopman_graph.analysis` — ``compute_generator_spectrum``, ``discrete_spectrum_at_delta_t``, ``decode_mode_shapes``, ``spectrum_distance``, ``koopman_std``, ``dynamical_similarity``, ``detect_anomaly``, ``calibrate_anomaly_threshold``, - ``AnomalyDetectionResult`` (landed in TASK-749) -* :mod:`koopman_graph.data` — ``as_multi_trajectory`` (landed in TASK-750) -* :mod:`koopman_graph.adaptation` — ``AdaptationStepResult`` (landed in TASK-750) + ``AnomalyDetectionResult`` +* :mod:`koopman_graph.data` — ``as_multi_trajectory`` +* :mod:`koopman_graph.adaptation` — ``AdaptationStepResult`` * :mod:`koopman_graph.observables` — ``graph_laplacian_features`` - (landed in TASK-750) .. code-block:: python @@ -535,7 +534,7 @@ of assembled ``K`` / ``L`` via ``eigvals``. Prefer ``bound_metric`` for ODO factor monitoring and structural certificates. Discrete ODO still satisfies ``ρ(K) ≤ bound_metric`` via the operator 2-norm; continuous ODO does **not** guarantee Hurwitz stability from the factor bound alone. See the quickstart -stability section and TASK-608 docs. +stability section. ``KoopmanPropagator`` in :mod:`koopman_graph.graph_utils` is an alias of the Protocol and is the single typing surface for losses and adaptation. @@ -925,9 +924,9 @@ No ``FORMAT_VERSION`` bump was required: the field was already emitted in v2. v0.3.0 architectural consistency outcomes ----------------------------------------- -Phase 8 (TASK-700–752) standardized style and release quality without bumping -the package beyond ``0.3.0`` or ``FORMAT_VERSION`` 2. Outcomes folded into the -first public v0.3.0 cut: +Phase 8 standardized style and release quality without bumping the package +beyond ``0.3.0`` or ``FORMAT_VERSION`` 2. Outcomes folded into the first public +v0.3.0 cut: **Highest-impact API remediations (second style audit)** @@ -968,9 +967,8 @@ first public v0.3.0 cut: * Layout policy plus ``training/``, ``data/``, ``operators/``, ``nn/``, ``analysis/``, and ``baselines/`` capability packages; deep-import shim - hard cut (TASK-746); thin root ``__all__`` with metrics / analysis / data / - adaptation / observables secondaries demoted to capability imports - (TASK-747–750). + hard cut; thin root ``__all__`` with metrics / analysis / data / + adaptation / observables secondaries demoted to capability imports. **Analysis UX and release quality** diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 8cace48..770d4a2 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -313,7 +313,7 @@ operator is acceptable. Continuous write-back can still degrade for very large Historical note: earlier releases used a first-order controlled approximation ``B̃ ≈ B(Δt) / Δt`` that disagreed with Van Loan integration; that path was -replaced in the Phase 8 fidelity update (TASK-704). +replaced in the Phase 8 fidelity update. Latent-space RL environment ---------------------------