ambermeta 1.4.0__tar.gz

ambermeta-1.4.0/LICENSE

@@ -0,0 +1,101 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Dr. Michele Bonus
+Licensed Work:        AmberMeta
+                      The Licensed Work is (c) 2026 Dr. Michele Bonus.
+                      All rights reserved.
+Change Date:          2029-03-26
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor directly.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this file, you must purchase a commercial
+license from the Licensor, its affiliated entities, or authorized resellers, or
+you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work, and the Change Date may vary for each
+version of the Licensed Work released by the Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the original or modified Licensed Work
+from a third party, the terms and conditions set forth in this License apply
+to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of the
+Licensor or its affiliates (provided that you may use a trademark or logo of
+the Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. THE LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as
+long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+who receive the Licensed Work under this License, to honor and faithfully
+comply with the following provisions:
+
+1. Licensor will specify as the Change License the GPL Version 2.0 or any
+   later version, or a license that is compatible with GPL Version 2.0 or a
+   later version, where "compatible" means that software provided under the
+   Change License can be included in a program with software provided under
+   GPL Version 2.0 or a later version. Licensor may specify additional Change
+   Licenses without limitation.
+
+2. Licensor will either: (a) specify an additional grant of rights to use
+   that does not impose any additional restriction on the right granted in this
+   License, as the Additional Use Grant; or (b) insert the text "None" in the
+   space of the Additional Use Grant.
+
+3. Licensor will specify a Change Date.
+
+4. Licensor will not modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+For more information on the use of the Business Source License, please visit
+https://mariadb.com/bsl-faq-adopting/

ambermeta-1.4.0/PKG-INFO

@@ -0,0 +1,438 @@
+Metadata-Version: 2.4
+Name: ambermeta
+Version: 1.4.0
+Summary: Simulation provenance extraction utilities for AMBER molecular dynamics runs.
+Author: AmberMeta Contributors
+License-Expression: BUSL-1.1
+Project-URL: Homepage, https://github.com/CPCLab/ambermeta
+Project-URL: Documentation, https://github.com/CPCLab/ambermeta#readme
+Project-URL: Repository, https://github.com/CPCLab/ambermeta.git
+Project-URL: Issues, https://github.com/CPCLab/ambermeta/issues
+Keywords: amber,molecular-dynamics,simulation,provenance,metadata,bioinformatics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: netcdf
+Requires-Dist: netCDF4>=1.6; extra == "netcdf"
+Requires-Dist: scipy>=1.8; extra == "netcdf"
+Requires-Dist: numpy>=1.23; extra == "netcdf"
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.100.0; extra == "gui"
+Requires-Dist: uvicorn>=0.23.0; extra == "gui"
+Requires-Dist: websockets>=11.0; extra == "gui"
+Requires-Dist: python-multipart>=0.0.6; extra == "gui"
+Requires-Dist: pyyaml>=6.0; extra == "gui"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: toml
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "toml"
+Provides-Extra: tests
+Requires-Dist: pytest>=7; extra == "tests"
+Requires-Dist: pytest-cov>=4.0; extra == "tests"
+Requires-Dist: httpx>=0.24; extra == "tests"
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: netCDF4>=1.6; extra == "all"
+Requires-Dist: scipy>=1.8; extra == "all"
+Requires-Dist: numpy>=1.23; extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: uvicorn>=0.23.0; extra == "all"
+Requires-Dist: websockets>=11.0; extra == "all"
+Requires-Dist: python-multipart>=0.0.6; extra == "all"
+Requires-Dist: pyyaml>=6.0; extra == "all"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/CPCLab/ambermeta/main/docs/assets/logo/ambermeta_logo_dark.svg">
+    <img src="https://raw.githubusercontent.com/CPCLab/ambermeta/main/docs/assets/logo/ambermeta_logo.svg" alt="AmberMeta" width="520">
+  </picture>
+</p>
+
+# AmberMeta
+
+**AmberMeta is a provenance engine for AMBER molecular-dynamics workflows. It reads the files a run already produced — `prmtop`, `mdin`, `mdout`, `mdcrd`, `inpcrd` — reconstructs the simulation behind them as a `Simulation → Phase → Step` document, validates that the steps actually connect, and exports a machine-readable record you can drop into a methods section or a downstream pipeline.**
+
+You point it at a directory (or a manifest), and it answers the questions that are tedious to answer by hand: *What was actually run? In what order? Do the restarts line up? Is any topology hydrogen-mass-repartitioned? What were the ensemble, thermostat, barostat, and cutoff? Did the run finish? Is a member of a numbered sequence missing?*
+
+- **Version:** 1.4.0 · **Python:** 3.9+ · **License:** BUSL-1.1
+- **Repository:** <https://github.com/CPCLab/ambermeta>
+
+---
+
+## 1. The model
+
+A **Simulation** is the whole document. It owns a **topology pool** (one or more prmtops, each labeled `normal` or `hmr`) and a single **starting structure**. A **Phase** is a named, role-bearing container — minimization / heating / equilibration / production — that groups related runs. A **Step** is one actual run: it binds one topology from the pool, names its `mdin`/`mdout`/`mdcrd`, and declares where its input coordinates come from (the Simulation's starting structure, a previous step's output restart, or an explicit path).
+
+That last part is what makes continuity checking exact: AmberMeta follows the declared input-coordinate chain from step to step, compares each hand-off's timing against a frame-interval-based tolerance, and flags both broken continuity and holes in numbered sequences (`prod_0001, prod_0002, prod_0004, …` → `0003` is missing) as first-class findings — not as an afterthought bolted onto a flat stage list.
+
+A Step can also carry a **`lineage`** tag naming which member of a parallel set it belongs to — a replica, a branch off a shared restart, a pose. Steps sharing a tag are one member; untagged means the single implicit member, and a document that declares none behaves exactly as it always did. Every chaining and continuity path honours the tag: replicas are chained and measured within themselves, so a set of replicas is no longer reported as one long serial run.
+
+| Capability | What you get |
+|---|---|
+| **Metadata extraction** | Per-file parsers for topology, input, output, trajectory, and restart files. Atom/residue counts, box geometry, density, solvent model, HMR status, ensemble, thermostat/barostat, cutoff, SHAKE, completion status, and streaming thermodynamic statistics (temperature/pressure/density/energy, mean ± σ). |
+| **Simulation discovery** | Scans a directory into a `Simulation` draft: builds the topology pool, detects numbered sequences, infers each step's role (minimization / heating / equilibration / production) from content then path, and resolves the input-coordinate chain — all as explainable, one-click-undoable suggestions. Where the layout names members (`rep1/`, `rep2/`, … running the same runs) each is tagged and chained separately; an ambiguous layout is left untagged rather than guessed at. |
+| **Continuity & sequence validation** | Per-run checks (atom-count agreement across a run's files, mdin against mdout, a time step above 2 fs on a topology with standard hydrogen masses, a run that did not finish, and the input coordinates a step declares against the INPCRD its mdout records) and whole-simulation checks (timing gaps between chained steps against a tolerance, missing members of a numbered run), with configurable per-step tolerances. The whole-simulation checks are scoped per lineage, so a replica that stopped early is named instead of pooled with its siblings, and one member's first run is never measured against another member's last. |
+| **Manifest format v2** | One reader and one writer for the `Simulation → Phase → Step` document, in JSON or YAML. The GUI and CLI share the same document. |
+| **Reproducibility exports** | A full simulation/protocol summary (JSON/YAML); a methods summary, a compact digest of it for writing a Methods section (settings stated once per phase with their source and the runs that differ, the system by residue class, replicas, findings, and what no run file records); and a per-stage statistics CSV. |
+
+Two interfaces sit on one shared core:
+
+| Surface | Use it when | Entry point |
+|---|---|---|
+| **CLI** | Scripting, CI, SSH/cluster, headless batch processing | `ambermeta <command>` |
+| **GUI** | Interactively assembling or auditing a manifest in a browser | `ambermeta gui` |
+
+> The CLI is the complete, headless interface — everything AmberMeta does is reachable without the GUI. The GUI is an optional, offline, localhost-only manifest editor built on the same engine (it imports the core through a single bridge module, `ambermeta.gui.api.core_bridge`; it does not re-implement any logic). There is no separate TUI.
+
+---
+
+## 2. Install
+
+AmberMeta requires **Python 3.9+**. The base install is dependency-light; optional features live behind extras.
+
+```bash
+python -m pip install ambermeta              # from PyPI
+python -m pip install "ambermeta[all]"       # with all runtime features
+```
+
+From a clone of the repository, for development:
+
+```bash
+python -m pip install -e .
+```
+
+| Extra | Pulls in | Enables |
+|---|---|---|
+| _(base)_ | stdlib only | All parsers except NetCDF; JSON manifests; full CLI |
+| `netcdf` | `netCDF4`, `scipy`, `numpy` | NetCDF trajectory (`.nc`) and NetCDF restart (`.ncrst`) parsing |
+| `gui` | `fastapi`, `uvicorn`, `websockets`, `python-multipart`, `pyyaml` | The browser GUI (`ambermeta gui`) |
+| `yaml` | `pyyaml` | YAML manifests |
+| `toml` | `tomli` (only on Python < 3.11) | Nothing any more — AmberMeta neither reads nor writes TOML. Retained so an existing `pip install ambermeta[toml]` keeps resolving |
+| `tests` | `pytest`, `pytest-cov`, `httpx` | Running the test suite |
+| `dev` | `black`, `ruff`, `mypy` | Linting and type checking |
+| `all` | everything runtime (netcdf + gui + yaml + toml) | The full feature set (does **not** include `tests`/`dev`) |
+
+```bash
+python -m pip install -e ".[all]"     # all runtime features
+python -m pip install -e ".[gui]"     # just the GUI
+```
+
+> ⚠️ The GUI ships a **pre-built, offline frontend bundle** under `ambermeta/gui/static/`. No Node.js, no build step, and no CDN at runtime — it works on an air-gapped workstation. The `gui` extra only adds the Python web server.
+
+---
+
+## 3. Sixty-second quickstart (CLI)
+
+Every command below is run against the sample data in `tests/data/amber/md_test_files/` — a real 64,528-atom glycoprotein system with a five-run NPT production sequence (`ntp_prod_0001` … `ntp_prod_0005`).
+
+**Discover the directory into a Simulation draft and save it as a v2 manifest:**
+
+```text
+$ ambermeta discover tests/data/amber/md_test_files --write sim.yaml
+
+Simulation summary
+==================
+Topologies (pool): 1
+  - top_CH3L1_HUMAN_6NAG [normal]  CH3L1_HUMAN_6NAG.top
+Starting structure: ntp_prod_0000.rst
+Phases: 1
+
+Phase: Production [production]
+  - ntp_prod_0001  from the starting structure
+  - ntp_prod_0002  from ntp_prod_0001
+  - ntp_prod_0003  from ntp_prod_0002
+  - ntp_prod_0004  from ntp_prod_0003
+  - ntp_prod_0005  from ntp_prod_0004
+
+Suggestions:
+  - [applied] ntp_prod_0000.rst set as the starting structure
+  - [applied] Phase roles inferred from file content/names
+
+Wrote v2 draft manifest: sim.yaml (yaml)
+NOTE: the manifest is not in /abs/path/tests/data/amber/md_test_files, so its file paths are written relative to its own directory (/abs/path), where `validate --manifest` and `plan -m` read them.
+```
+
+**Inspect a single file in depth:**
+
+```text
+$ ambermeta info tests/data/amber/md_test_files/CH3L1_HUMAN_6NAG.top
+
+File Information: CH3L1_HUMAN_6NAG.top
+============================================================
+  natom: 64528
+  nres: 15102
+  nbond: 64539
+  total_charge: 8.020996347271433e-05
+  is_neutral: True
+  box_dimensions: [98.3405545, 76.0526585, 81.2272985]
+  density: 0.8433970648221194
+  solvent_type: Explicit Solvent
+  simulation_category: Protein / Ligand in Explicit Water
+  num_solvent_molecules: 14659
+  num_solute_residues: 371
+  iptres: 443
+  hmr_active: False
+  hmr_hydrogen_mass_summary: 1.008-1.008 amu across 32188 H
+  hmr_detection_method: atomic_number
+  ... (also: version, title, force_field_features, total_mass, box_angles,
+      box_volume, box_is_topology_time, residue_composition — run it yourself for
+      the full field list)
+```
+
+**Validate the whole Simulation — continuity, sequence holes, per-run checks, and suggestions (exit code `0`/`1` for CI):**
+
+```text
+$ ambermeta validate --manifest sim.yaml
+
+Simulation validation
+
+Simulated time: 100 ns
+
+Findings:
+  - Run check: ntp_prod_0001: Time step of 4 fs, but the topology has standard hydrogen masses (no hydrogen mass repartitioning); a time step above 2 fs needs repartitioned hydrogen masses.
+  - Run check: ntp_prod_0002: Time step of 4 fs, but the topology has standard hydrogen masses (no hydrogen mass repartitioning); a time step above 2 fs needs repartitioned hydrogen masses.
+  - Run check: ntp_prod_0003: Time step of 4 fs, but the topology has standard hydrogen masses (no hydrogen mass repartitioning); a time step above 2 fs needs repartitioned hydrogen masses.
+  - Run check: ntp_prod_0004: Time step of 4 fs, but the topology has standard hydrogen masses (no hydrogen mass repartitioning); a time step above 2 fs needs repartitioned hydrogen masses.
+  - Run check: ntp_prod_0005: Time step of 4 fs, but the topology has standard hydrogen masses (no hydrogen mass repartitioning); a time step above 2 fs needs repartitioned hydrogen masses.
+
+Validation: OK, 5 findings to review
+```
+
+The chain is intact, so the verdict is `OK`, but each run is compared with what AMBER recorded, and the sample as bundled ran at `dt = 0.004` ps with a topology whose 32,188 hydrogens all weigh 1.008 amu. A 4-fs time step needs repartitioned hydrogen masses, so either the runs used a different (HMR) topology than the one bundled, or they were integrated at a step their hydrogens do not support. On your own data with an HMR topology this finding does not appear. Findings leave the exit code at `0` by default; `--strict` makes any finding exit `1`, so `--strict` on the untouched sample exits `1`.
+
+**Write the summary files** (`summary.json`, the methods summary as JSON and as Markdown to read, and per-run statistics) into one folder:
+
+```text
+$ ambermeta plan -m sim.yaml --out results/
+...
+Wrote summary: /abs/path/results/summary.json
+Wrote methods_summary: /abs/path/results/methods_summary.json
+Wrote methods_summary_md: /abs/path/results/methods_summary.md
+Wrote stats_csv: /abs/path/results/stats.csv
+```
+
+That is the whole path: `discover --write`, read and fix the manifest, `validate --manifest`, then `plan -m ... --out`. `ambermeta --help` lists the same four steps. Editing a manifest by hand, converting it between YAML and JSON (`export`), and each summary file in detail are in the [CLI reference](https://github.com/CPCLab/ambermeta/blob/main/docs/cli.md) and the [tutorials](https://github.com/CPCLab/ambermeta/blob/main/docs/tutorials.md).
+
+---
+
+## 4. The manifest
+
+A manifest is the durable, hand-editable description of a simulation: a topology pool, a starting structure, an ordered list of phases, and the steps inside them. This is **manifest format v2** — the canonical, current shape:
+
+```yaml
+version: 2
+simulation:
+  topologies:
+    - id: top_wt
+      path: wt.prmtop
+      kind: normal          # "normal" | "hmr" (detected, overridable)
+    - id: top_wt_hmr
+      path: wt_hmr.prmtop
+      kind: hmr
+  starting_structure: wt.inpcrd
+phases:
+  - { id: ph_min,  name: Minimization, role: minimization, order: 0 }
+  - { id: ph_prod, name: Production,    role: production,   order: 1 }
+steps:
+  - id: st_min
+    name: minimize
+    phase: ph_min
+    order: 0
+    topology: top_wt                              # reference into the pool
+    input_coords: { source: starting_structure }
+    mdin: min.in
+    mdout: min.out
+    rst: min.rst                                  # the restart THIS step writes
+  - id: st_prod_001
+    name: prod_001
+    phase: ph_prod
+    order: 0
+    topology: top_wt_hmr
+    input_coords: { source: step, ref: st_min }   # or { source: path, path: "..." }
+    mdin: prod_001.in
+    mdout: prod_001.out
+    mdcrd: prod_001.nc
+    rst: prod_001.rst
+    gaps: { expected: null, tolerance: null }
+```
+
+Each step's `input_coords.source` is one of `starting_structure`, `step` (with `ref: <step id>`), or `path` (with an explicit `path:`) — that's the continuity anchor the validator walks. A chained step names *only* the step it continues from: the restart file itself is recorded once, as `rst` on the step that wrote it, and `ref` is followed to reach it. `gaps.expected`/`gaps.tolerance` are the per-step expected inter-run gap and tolerance, in ps; both may be `null`.
+
+**v2 is read and written as JSON or YAML** (`load_simulation`/`write_simulation`) — those are the only manifest formats AmberMeta has. A `.toml` or `.csv` manifest is refused with a message saying so, rather than being half-parsed.
+
+```bash
+ambermeta validate --manifest simulation.yaml --format json
+```
+
+A finding you have reviewed (a replica stopped on purpose, a run that was not deposited) can be settled in the manifest with a note, under `acknowledged:`; it is then listed apart with that note, no longer fails `--strict`, and is carried into the summaries. See [manifest §9.3](https://github.com/CPCLab/ambermeta/blob/main/docs/manifest.md#93-settling-a-finding-acknowledged).
+
+The complete schema — every key, all input-coordinate sources, gap configuration, environment-variable expansion, and role tokens — is documented in the [manifest schema reference](https://github.com/CPCLab/ambermeta/blob/main/docs/manifest.md).
+
+### Coming from v1?
+
+**The v1 flat manifest file format has been removed.** A file whose top level is a `stages:` list (with `global_prmtop`/`hmr_prmtop`/`initial_coordinates`) no longer opens anywhere — not in `plan -m`, `validate --manifest`, `export`, or the GUI. Each of them fails cleanly, naming the file:
+
+```text
+$ ambermeta plan tests/data/amber/md_test_files -m old_manifest.yaml
+
+ERROR: old_manifest.yaml is not a v2 manifest (no 'steps' key). Rebuild it with `ambermeta discover <dir> --write <path>`.
+```
+
+There is no migration command and no in-memory migration. Rebuild the document from the run directory it describes:
+
+```bash
+ambermeta discover runs/ --write sim.yaml     # a v2 draft from the files on disk
+ambermeta init runs/ -o sim.yaml              # or start from a blank v2 template
+```
+
+`discover` reads the same files the old manifest pointed at, so the rebuilt document is derived from the runs themselves rather than from the stale paths in the v1 file. Check the inferred phase roles and the topology pool before relying on it.
+
+---
+
+## 5. Python API
+
+The same engine is a library, with two layers. For the new model, work with `ambermeta.simulation` directly — it is not (yet) re-exported at the `ambermeta` top level:
+
+```python
+from ambermeta.simulation import load_simulation
+
+sim = load_simulation("sim.yaml")   # a v2 manifest: JSON or YAML
+print(sim.topologies)
+# -> [Topology(id='top_CH3L1_HUMAN_6NAG', path='CH3L1_HUMAN_6NAG.top', kind='normal')]
+print(sim.starting_structure)
+# -> ntp_prod_0000.rst
+for phase in sim.phases:
+    print(phase.name, phase.role, [s.name for s in phase.steps])
+# -> Production production ['ntp_prod_0001', 'ntp_prod_0002', 'ntp_prod_0003', 'ntp_prod_0004', 'ntp_prod_0005']
+```
+
+`write_simulation(sim, path, fmt)` (`fmt` is `"json"` or `"yaml"`) writes it back out; `simulation_to_payload`/`payload_to_simulation` round-trip a `Simulation` through the same JSON-shaped dict the GUI's HTTP API uses.
+
+The retained parsing engine — file discovery, the flat `SimulationProtocol`/`SimulationStage` model, and the per-file parsers — is still the public top-level `ambermeta.*` surface, and still powers `discover`/`validate --manifest` under the hood via `ambermeta.gui.api.core_bridge`:
+
+```python
+from ambermeta import auto_discover
+
+# Reconstruct a flat protocol from a directory (the path `plan --recursive` uses)
+protocol = auto_discover("runs/", recursive=True, auto_detect_restarts=True)
+print(len(protocol.stages), protocol.totals())
+
+# Per-file parsing — note the .details accessor
+from ambermeta.parsers import PrmtopParser
+result = PrmtopParser("system.prmtop").parse()
+meta = result.details
+print(meta.natom, meta.hmr_active, meta.solvent_type)
+```
+
+The full surface — every `ambermeta.simulation` dataclass, the retained `SimulationProtocol`/`SimulationStage`/`ProtocolBuilder`, the `core_bridge.discover_draft`/`validate_simulation` helpers that back the CLI and GUI, and every parser metadata field — is in the [Python API reference](https://github.com/CPCLab/ambermeta/blob/main/docs/api.md).
+
+---
+
+## 6. GUI
+
+```bash
+ambermeta gui tests/data/amber/md_test_files          # opens http://127.0.0.1:8765
+ambermeta gui runs/ --port 9000 --no-browser
+```
+
+A rebuilt three-pane browser app for assembling and auditing a Simulation:
+
+- **Files** (left) — a searchable file list; drag a file onto the topology pool, the starting-structure slot, a step's topology, or a step's `mdin`/`mdout`/`mdcrd` slot.
+- **Canvas** (center) — a continuous vertical timeline: phases as sections, steps as cards showing their bound topology and input-coordinate source, continuity arrows between chained steps (amber where a real gap exists), and ghost cards for missing members of a numbered sequence. Drag to reorder steps, move a step across phases, or reorder phases.
+- **Inspector** (right) — peek and full-details/raw tabs for whatever's selected, plus assign actions and inline editors for the selected step or phase (name, topology, input-coordinate source and "continues from", restart, gaps, notes; name and role for a phase).
+
+A **Suggestions** tray surfaces every inferred thing (roles, HMR topology, starting structure, sequence holes, continuity gaps) as an explainable, undoable suggestion rather than applying it silently. **Discover** re-runs discover-as-draft on the launch directory; **Open**/**Save** read and write the same v2 manifest the CLI does; **Validate** lists issues.
+
+Run lineages are **proposed, never written**. After a Discover that found a grouping, a **proposal strip** shows the members it inferred, the directories each was built from, an editable name per member, and a segment picker for regrouping by a different part of the path — plus the cross-directory restart handoffs that AMBER's own mdout `File Assignments` records (`equil/01/18_ntp_equi → prod/01/nvt_prod_0001`). Discover already follows a record that identifies one run, in every directory, so the draft chain is what AMBER recorded wherever it recorded something usable. Nothing lands until you press **Accept**. The inference refuses more layouts than it accepts; **Define replicas…** in the top bar opens the same picker on demand and never refuses, so a tree it could not reconcile is still one click from being declared. See [GUI guide §5a](https://github.com/CPCLab/ambermeta/blob/main/docs/gui.md).
+
+The server is server-authoritative (a single document held server-side; every mutation returns the new document; undo/redo call the server), single-user, **localhost-only**, and confines all file access to the launch directory. Full walkthrough, including the HTTP API surface: [GUI guide](https://github.com/CPCLab/ambermeta/blob/main/docs/gui.md).
+
+---
+
+## 7. Command reference
+
+| Command | Purpose |
+|---|---|
+| `ambermeta discover` | Scan a directory into a Simulation draft (topology pool, phases, steps with input-coord sources) and optionally write a v2 manifest |
+| `ambermeta plan` | Build and summarize a Simulation from a v2 manifest, or a flat protocol via recursive discovery / interactive prompts; export summaries and stats |
+| `ambermeta validate` | Validate individual files, or a whole Simulation manifest (`--manifest`) for continuity and sequence holes |
+| `ambermeta export` | Re-emit a v2 manifest as canonical v2, converting between JSON and YAML |
+| `ambermeta init` | Write a starting v2 manifest template (`--force` to overwrite) |
+| `ambermeta info` | Print parsed metadata for a single file (text / JSON / YAML) |
+| `ambermeta gui` | Launch the browser GUI |
+| `ambermeta completion` | Emit a shell-completion script (bash / zsh / fish) |
+
+Global options (`--log-level`, `--log-file`, `-q/--quiet`) and every flag are documented — and kept in sync with the parser by CI — in the [CLI reference](https://github.com/CPCLab/ambermeta/blob/main/docs/cli.md).
+
+---
+
+## 8. Documentation
+
+| Document | What's inside |
+|---|---|
+| [Architecture](https://github.com/CPCLab/ambermeta/blob/main/docs/architecture.md) | How the engine is built: the Simulation → Phase → Step model, the topology pool and input-coordinate sources, continuity/sequence detection, manifest v2 and its reader, the shared role classifier, the parser layer, and the GUI's single-engine bridge |
+| [CLI reference](https://github.com/CPCLab/ambermeta/blob/main/docs/cli.md) | Every command, flag, exit code, and environment variable |
+| [Python API reference](https://github.com/CPCLab/ambermeta/blob/main/docs/api.md) | Classes, functions, parser metadata fields, and worked examples |
+| [Manifest schema](https://github.com/CPCLab/ambermeta/blob/main/docs/manifest.md) | The full v2 schema, environment-variable expansion, and role tokens |
+| [GUI guide](https://github.com/CPCLab/ambermeta/blob/main/docs/gui.md) | The browser app, its API surface, and its security model |
+| [Tutorials](https://github.com/CPCLab/ambermeta/blob/main/docs/tutorials.md) | Task-oriented, step-by-step walkthroughs |
+| [Recipes](https://github.com/CPCLab/ambermeta/blob/main/docs/recipes.md) | Copy-paste CLI one-liners for common jobs |
+| [Depositor SOP](https://github.com/CPCLab/ambermeta/blob/main/docs/sop/ambermeta-sop.pdf) | The procedure for applying AmberMeta to a collected dataset, one system at a time — prerequisites, the layout to use, the GUI walkthrough, and what to do with each finding ([source](https://github.com/CPCLab/ambermeta/blob/main/docs/sop/ambermeta-sop.tex)) |
+| [Replica layouts](https://github.com/CPCLab/ambermeta/blob/main/docs/sop/replica-layouts.pdf) | Which directory conventions the layout inference detects, which it declines and why, and how to declare the rest by hand ([source](https://github.com/CPCLab/ambermeta/blob/main/docs/sop/replica-layouts.tex)) |
+
+A single-page, fully offline HTML version of these docs lives at [`docs/ambermeta.html`](https://github.com/CPCLab/ambermeta/blob/main/docs/ambermeta.html) — open it in any browser (no server, no network).
+
+---
+
+## 9. Compatibility & limitations
+
+- **v1 manifests no longer open.** A bare `stages:` list or a `global_prmtop`/`hmr_prmtop`/`initial_coordinates` manifest is refused with a clean error by every entry point, and there is no migration path. Rebuild from the run directory — see [Coming from v1?](#coming-from-v1) above.
+- **AMBER engines:** parses output from both `pmemd`/`pmemd.cuda` and `sander`. GPU model and ns/day come from the `mdout` footer where present. Completion and wall-time are read per engine: `pmemd` writes a `Final Performance Info` block and a `Total wall time:` line, `sander` writes neither — its completion is taken from its own end-of-run markers (`Run done at`, `wallclock() was called`) and its wall clock from the `Total time` line in `TIMINGS`.
+- **NetCDF:** `.nc` trajectories and `.ncrst` restarts require the `netcdf` extra. Without it, ASCII trajectories/restarts still parse; NetCDF files are reported as unreadable rather than crashing the run, and continuity reads each run's start time from its `mdout` instead. A run that set its own clock (`irest = 0`, new velocities) is then not measured against the run before it: it gets an INFO note that continuity follows the recorded input coordinates.
+- **Incomplete trajectories are not read as complete ones.** NetCDF-3 stores record variables interleaved at the end of the file, so records that were never written back read as fill. A trajectory that is truncated, still being written, or half-copied is detected by its frame times ceasing to increase: AmberMeta reports the frames that are really on disk, warns that the times are not reported, and lets continuity fall through to the `mdout` rather than taking a fill value as the run's end time. Box records that read as empty are dropped from the box and volume statistics with a warning of their own.
+- **One simulation per folder.** A folder whose runs report different atom counts holds several systems, so `discover`, `plan --recursive` and the GUI's Discover refuse it and name each system; run each system's folder on its own, or pass `--as-one-simulation` for a false alarm. See [Several systems in one folder](https://github.com/CPCLab/ambermeta/blob/main/docs/cli.md#several-systems-in-one-folder).
+- **Fault tolerance:** `ambermeta plan` is fault-tolerant by default — an unreadable or malformed file is skipped, the error is recorded against its stage/step, and the run still completes (exit `0`). Pass `--strict` to make the first bad file a hard error.
+- **Role inference is heuristic.** When a phase or stage omits its role, AmberMeta infers it from `imin` in the `mdin`/`mdout`, the file/path name, and other content (restraints, a temperature ramp, run length), via the shared classifier in `ambermeta/roles.py`, and records that it did so. Name cues are matched per path component, directories first: `min`/`em`, `heat`, `equil`/`equi`/`eq`, `prod`, then `nvt`/`npt` (so `nvt_prod_0001` is production), each followed by `_`, `.`, `-`, a digit or the end of the name (`prod1`, `eq0001`); the full table is in the [manifest schema](https://github.com/CPCLab/ambermeta/blob/main/docs/manifest.md#7-canonical-role-tokens). Verify inferred roles before publishing.
+- **Manifest formats:** JSON or YAML, in both directions. TOML and CSV are not manifest formats — a `.toml`/`.csv` manifest path is refused with a message that says so. (`--stats-csv` still writes a per-stage statistics CSV; that is a report, not a manifest.)
+
+### Behavior changes in 1.4.0
+
+- **A finding can be settled with a note.** A manifest may list findings you have reviewed under `acknowledged:`, each with a note that says why it stands. `validate` and `plan` show them apart under "Acknowledged", they no longer count for the verdict or for `--strict`, and an entry that no longer matches a finding is listed as no longer found. The notes are kept in `summary.json` and in the methods summary. In the GUI, a finding offers **Acknowledge…** and an acknowledged one offers **Reopen**. See [Settling a finding](https://github.com/CPCLab/ambermeta/blob/main/docs/manifest.md#93-settling-a-finding-acknowledged).
+- **The methods summary as Markdown.** `plan --methods-summary-md FILE` writes a readable Markdown version beside the JSON, `plan --out DIR` writes it as `methods_summary.md`, and `python -m ambermeta.methods_summary summary.json -o methods_summary.md` converts any existing summary. The GUI's Plan dialog writes it by default.
+- **One simulation per folder.** `discover`, `plan --recursive` and the GUI's Discover refuse a folder whose runs report different atom counts and name each system, where 1.3.0 merged them. `--as-one-simulation` keeps the old behavior.
+- **Plainer output.** The verdict counts what is left to check (`Validation: OK, N findings to review`), findings are worded in plain language, and a gap in a numbered series names the run that is missing. `--help` shows the typical workflow, `plan`'s options are grouped, `plan --out DIR` writes every summary into one folder, and the run listing is compact (`-v` for full lines).
+- **Readable manifests.** Ids are readable: a step's id is its run's name and a phase's id is its name in lower case (`production`). A YAML draft written with `discover --write` starts with a comment that says what to check.
+- **No silent overwrites.** `discover --write` and `export -o` refuse to replace an existing file without the new `--force`, so a script that rewrites a manifest needs the flag. A missing parent directory is created.
+- **Smaller CLI changes:** `ambermeta --version`; `NO_COLOR` is honoured; `export --format yaml` prints YAML; `export` keeps `$VARS` as written; `init` refuses a name that is not `.yaml`/`.yml`; `--help` no longer crashes when piped on Windows.
+- **Fixes that change results:** a stated gap or tolerance of `0` is honoured; an unknown `input_coords.source` is refused when the manifest is loaded; an `.in` file without `&cntrl` (`tleap.in`) gets a warning and a finding instead of passing as an MD run; `validate <files>` reports an empty or cut-off file instead of OK; where two files of a run share a stem (`prod_0001.mdcrd` beside `prod_0001.nc`), the run names the one it read and the one it did not; reordering steps in the GUI keeps the links that AMBER recorded.
+- **Packaging:** `pyproject.toml` is the only packaging file.
+
+### Behavior changes in 1.3.0
+
+- **Replicas are compared per role.** Settings (`dt`, `temp0`, `cut`, `ntt`, `ntp`) are compared between replicas role by role for minimization, heating and equilibration runs, and on all other runs (production, custom roles, unclassified) together, so replicas whose production runs differ in `temp0` are reported even when each replica's equilibration runs use several temperatures (`Members differ in temp0 in their production runs (...)`). `temp0` is compared on those production runs (among the replicas that have them), and on the last equilibration (or heating) role only where no replica has such runs; per-segment or per-replica equilibration temperatures before production are not reported.
+- **`plan --recursive` follows the recorded inputs.** The directory scan orders and links runs by the input coordinates each `mdout` records, as `discover` does, so names that do not sort in run order (`eq_0001 -> prod_0001 -> eq_0002 -> ...`) no longer produce false gaps and overlaps. A run that no record links to a run here (a job script that copies every restart to one fixed name, restarts not deposited) is still measured against the run before it, so real gaps are reported, and continuity problems are now listed under Findings and count for `--strict`. Topology and starting-structure groups are listed but not measured.
+- **Simulated time per role.** Where the runs hold more than one role, `summary.json` totals and each lineage gain `time_ps_<role>` (`time_ps_equilibration`, `time_ps_production`, ...), and `plan`/`validate` print `Simulated time: 63 ns (equilibration 3 ns; production 60 ns)`.
+- **Repeated phases are numbered.** A protocol that alternates roles gets `Equilibration`, `Production`, `Equilibration 2`, `Production 2`, ... from `discover`; the methods summary still describes each phase once.
+- **Smaller fixes:** `stats.csv` has a `lineage` column when lineages exist; `discover --write` outside the scanned directory writes paths relative to the manifest (a manifest in a subdirectory keeps paths relative to the scanned directory, for the GUI); replica directories holding byte-identical copies of the starting restart give one starting structure; NetCDF attributes read through SciPy are decoded (`pmemd`, not `b'pmemd'`); `num_solute_residues` no longer counts ions (371, not 443, on the sample; LEaP's raw value is the new `iptres`); the methods summary of an older `summary.json` keeps the ensemble of NPT runs.
+
+---
+
+## 10. License
+
+AmberMeta is distributed under the **Business Source License 1.1 (BUSL-1.1)**. See [`LICENSE`](https://github.com/CPCLab/ambermeta/blob/main/LICENSE) for the full terms.