Rename mdforge to MolDynX Tools (moldynx)

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [main, mdforge-framework]
+    branches: [main]
   pull_request:
 
 jobs:
@@ -23,6 +23,6 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -e ".[dev]"
       - name: Lint (ruff, non-blocking)
-        run: ruff check mdforge || true
+        run: ruff check moldynx || true
       - name: Run tests
         run: pytest -q

.gitignore

@@ -10,7 +10,9 @@ venv/
 .pytest_cache/
 .ruff_cache/
 
-# --- mdforge run outputs (regenerated) ------------------------------------
+# --- MolDynX Tools run outputs (regenerated; mdforge_* = pre-rename names) --
+moldynx_results/
+**/moldynx_out/
 mdforge_results/
 **/mdforge_out/
 core.pdb
@@ -33,6 +35,9 @@ step5_production.*
 step4_*.*
 toppar/
 
+# ...except the small, curated test fixtures (real trimmed logs, one small .edr)
+!tests/fixtures/**
+
 # --- OS cruft -------------------------------------------------------------
 .DS_Store
 Thumbs.db

.zenodo.json

@@ -1,6 +1,6 @@
 {
-  "title": "mdforge: a reusable, reproducible analysis framework for GROMACS molecular dynamics simulations",
-  "description": "mdforge turns a GROMACS simulation directory into a complete, publication-quality, fully reproducible analysis. It discovers files, detects the biomolecular system (protein / ligand / DNA / RNA / membrane / ions / multi-chain), auto-selects the appropriate analyses, runs them with streaming-friendly performance, and produces 300-dpi figures, a reproducibility manifest, and Markdown/HTML/PDF reports. Extensible via a plugin architecture and drivable from a single YAML config.",
+  "title": "MolDynX Tools (formerly mdforge): a reusable, reproducible analysis framework for GROMACS molecular dynamics simulations",
+  "description": "MolDynX Tools (formerly mdforge) turns a GROMACS simulation directory into a complete, publication-quality, fully reproducible analysis. It discovers files, detects the biomolecular system (protein / ligand / DNA / RNA / membrane / ions / multi-chain), auto-selects the appropriate analyses, runs them with streaming-friendly performance, and produces 300-dpi figures, a reproducibility manifest, and Markdown/HTML/PDF reports. Extensible via a plugin architecture and drivable from a single YAML config.",
   "upload_type": "software",
   "license": "MIT",
   "access_right": "open",

CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+## 0.3.0 — unreleased
+
+### Renamed: mdforge → **MolDynX Tools**
+
+- Import package `mdforge` → `moldynx`; CLI `mdforge` → `moldynx`; distribution
+  `molecular-dynamics-forge` → `moldynx-tools`.
+- Default output folder `mdforge_results` → `moldynx_results`; manifest key
+  `mdforge_version` → `moldynx_version`; plugin entry-point group `mdforge.plugins` →
+  `moldynx.plugins`.
+- **Compatibility for one minor version (removed in 0.4.0):** `import mdforge` and every
+  `mdforge.<submodule>` import still work (same module objects, one registry) with a
+  `DeprecationWarning`; the `mdforge` console script is kept as an alias; plugins advertised
+  under `mdforge.plugins` are still loaded, with a warning.
+- The Zenodo concept DOI (10.5281/zenodo.21265946) is unchanged; citation metadata now reads
+  "MolDynX Tools (formerly mdforge)".
+
+### Intake: the right files, chosen by evidence
+
+- **Fixed:** discovery picked the *largest* file per role. On real CHARMM-GUI folders that selects
+  an equilibration run input as the topology (equilibration `.tpr` files can be larger than the
+  production one) and a minimisation crash dump (`stepNc.pdb`) as the structure.
+- Files are now classified by simulation **stage** (setup / minimisation / NVT / NPT /
+  production); folders of earlier analysis output, GROMACS backups and caches are ignored; the
+  production trajectory is the longest complete one whose atom count equals the run input's,
+  verified from file headers; ties and mismatches are reported as ambiguities (errors unless
+  `--allow-ambiguous`, `--traj/--top` or `--interactive`).
+- New read-only evidence readers (`moldynx.io.gromacs`): mdrun logs (sessions, parameters,
+  coupling groups, minimisation outcome, warnings), `.mdp`, XTC frame headers (no offset cache is
+  written into the simulation folder), `.tpr` headers, and a GROMACS runner that falls back to WSL.
+- New `moldynx intake` command and `INTAKE_REPORT.md` / `intake_manifest.json` (also written by
+  every `analyze` run): canonical run and why, per-stage summary, temperature changes between
+  stages, a **capability matrix** (what each missing file disables), cluster-clock offset, run
+  extensions, and inputs referenced by job scripts that are absent.
+- `SystemInfo` now carries per-chain records (segid, atom range, residue range, sequence) and ion
+  counts.
+- The run manifest records the evidence chain and fingerprints every file the run depends on.
+- `analyze` output now defaults to `./moldynx_results/<input folder name>` (was
+  `./moldynx_results`), so runs of different simulations do not overwrite each other.
+
+### Periodic boundaries: diagnose, treat, prove — in one pass
+
+- **Fixed:** solute extraction applied `unwrap` inside `try/except: pass`, so a topology without
+  bonds silently produced a trajectory that was never made whole; the cached solute trajectory was
+  reused whenever the files existed, whatever the inputs, frame slice or treatment.
+- New `moldynx.core.pbc`: for every frame the raw coordinates are diagnosed first (molecules split
+  across the boundary, centre-of-mass continuity, PBC-aware minimum distance between partners),
+  then treated (`--pbc auto|none|whole|nojump`; `auto` = nojump for multi-molecule solutes, with
+  first-frame clustering), then **proven** against the raw frame: only whole-box translations,
+  all bonds short, partner distances preserved, and a split molecule shows two translation vectors
+  exactly in the frames where it was split. Nothing is repaired silently.
+- New `pbc_validation` analysis (runs first) with `results/pbc_summary.json`,
+  `results/pbc_per_frame.csv` and a figure.
+- The solute cache (`data/core_meta.json`) is keyed on input fingerprints, PBC mode, frame slice
+  and selection.
+- **Fixed:** `interface` could not resolve the two partners of CHARMM-GUI complexes: the PDB
+  format truncates `seg_0_PROA` / `seg_1_PROB` to `seg_`, so both chains read back from the cached
+  structure as one segment. Chain identity is now persisted as atom-index ranges
+  (`AnalysisContext.chain_groups()`); `interface` returns an explicit `skipped` reason instead of a
+  silent note when partners cannot be resolved.
+- Validated on two 100 ns protein–protein trajectories (1.6 M and 2.0 M atoms): split-frame
+  counts, zero whole-box translations, minimum inter-chain distances and molecular extents
+  reproduce an independent manual audit exactly.
+
+### Preparation and equilibration audit
+
+- New `equilibration` analysis: per-stage parameters from the logs, minimisation outcome (states
+  plainly when the force tolerance was *not* reached) and the chain/residue/atom carrying the
+  largest residual force, crash-dump accounting, energy-file statistics (tail means, residual
+  drift, settling times), position restraints per force constant and molecule type (`gmx dump`,
+  native or WSL; production must have none), protonation states, chain of custody from job
+  scripts (`moldynx.io.jobscripts`), stage timeline, figure. Missing inputs are reported.
+- Reproduces the manual audit of both reference datasets and additionally located the largest
+  residual force of one system on a protonated aspartate.
+
+### Interface and surface area
+
+- `interface` rewritten from the validated legacy suite: residue–residue contacts, interface
+  occupancy with **full** core lists, persistent contacts, residues ever within 6 Å (the set a
+  binding-energy decomposition must cover), buried area, interface Cα RMSD, trends.
+- **Fixed:** `mdtraj.shrake_rupley` (1.11.1) returns wrong values for some frames of a
+  multi-frame call (±0.5 nm² on a real trajectory; negative buried areas in a rigid-body test).
+  `moldynx.core.surface.shrake_rupley` computes frame by frame; `sasa` and `interface` buried
+  area now stride by 10 frames by default (parameters `stride` / `bsa_stride`).
+
+Remaining 0.3 work: `docs/NEXT_STEPS.md`.

CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
-title: "mdforge: a reusable, reproducible analysis framework for GROMACS molecular dynamics simulations"
+title: "MolDynX Tools (formerly mdforge): a reusable, reproducible analysis framework for GROMACS molecular dynamics simulations"
 abstract: >-
-  mdforge analyses GROMACS MD simulations of arbitrary biomolecular systems from
+  MolDynX Tools analyses GROMACS MD simulations of arbitrary biomolecular systems from
   a single simulation directory: it detects the system, auto-selects analyses,
   runs them with streaming performance, and produces publication-quality figures,
   a reproducibility manifest, and reports. Extensible via plugins and YAML config.

Dockerfile

@@ -1,6 +1,6 @@
-# mdforge -- reproducible container image.
-# Build:  docker build -t mdforge .
-# Run:    docker run --rm -v /data/sim:/sim mdforge analyze --input /sim --output /sim/results
+# MolDynX Tools -- reproducible container image.
+# Build:  docker build -t moldynx .
+# Run:    docker run --rm -v /data/sim:/sim moldynx analyze --input /sim --output /sim/results
 FROM mambaorg/micromamba:1.5-jammy
 
 WORKDIR /app
@@ -12,5 +12,5 @@ COPY --chown=$MAMBA_USER:$MAMBA_USER . /app
 ARG MAMBA_DOCKERFILE_ACTIVATE=1
 RUN pip install --no-deps -e .
 
-ENTRYPOINT ["mdforge"]
+ENTRYPOINT ["moldynx"]
 CMD ["--help"]

README.md

@@ -1,11 +1,11 @@
-# mdforge — reusable, reproducible GROMACS MD analysis
+# MolDynX Tools — reusable, reproducible, audited GROMACS MD analysis
 
 [![CI](https://github.com/SamDozer/molecular-dynamics-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/SamDozer/molecular-dynamics-forge/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21265946.svg)](https://doi.org/10.5281/zenodo.21265946)
 
-**mdforge** turns a GROMACS simulation directory into a complete, publication-quality,
+**MolDynX Tools** (`moldynx`; formerly *mdforge*) turns a GROMACS simulation directory into a complete, publication-quality,
 fully reproducible analysis — with minimal input. Point it at a folder; it discovers
 the files, **detects the system** (protein / ligand / DNA / RNA / membrane / ions /
 multi-chain / …), **auto-selects the right analyses**, runs them with streaming-friendly
@@ -24,7 +24,7 @@ performance, and produces figures, tables, a provenance manifest, and a report.
 - **Automatic module selection** — each analysis declares the system types and files
   it supports; the pipeline runs exactly what applies (`--plan` shows *why*).
 - **Extensible via plugins** — drop a `BaseAnalysis` subclass into
-  `mdforge/analysis/plugins/` (or a `--plugin-dir`) and it is auto-discovered.
+  `moldynx/analysis/plugins/` (or a `--plugin-dir`) and it is auto-discovered.
 - **Config-driven** — describe a whole run in `config.yaml` and re-run with one command
   (ideal for HPC/batch).
 - **Reproducible by construction** — every run writes `manifest.json/yaml` with library
@@ -51,19 +51,19 @@ python -m pip install -e ".[all]"      # or ".[dev]" for tests
 ## Usage
 
 ```bash
-mdforge detect  --input /path/to/sim_dir            # what's in my system?
-mdforge analyze --input /path/to/sim_dir --plan     # what would run, and why?
-mdforge analyze --input /path/to/sim_dir -o results # run everything applicable
-mdforge analyze --config examples/alpha_zein_A8HNE1/config.yaml   # reproducible
-mdforge list-analyses                                # registered analyses (incl. plugins)
+moldynx detect  --input /path/to/sim_dir            # what's in my system?
+moldynx analyze --input /path/to/sim_dir --plan     # what would run, and why?
+moldynx analyze --input /path/to/sim_dir -o results # run everything applicable
+moldynx analyze --config examples/alpha_zein_A8HNE1/config.yaml   # reproducible
+moldynx list-analyses                                # registered analyses (incl. plugins)
 ```
 
 See [`docs/QUICKSTART.md`](docs/QUICKSTART.md) for all options and the plugin template.
 
 ## Architecture
 
 ```
-mdforge/
+moldynx/
   core/       system.py (detection) · base.py (BaseAnalysis) · registry.py (+plugins)
               context.py · config.py (YAML+CLI) · provenance.py · pipeline.py
   io/         discovery.py · validation.py
@@ -90,7 +90,7 @@ Every analysis subclasses `BaseAnalysis`, declaring `required_files`,
 | **Protein–DNA/RNA** | protein–nucleic contacts, nucleic RMSD |
 
 Each is a drop-in `BaseAnalysis`; the pipeline runs only those applicable to the
-detected system (`mdforge list-analyses` shows all; `--plan` shows what runs and why).
+detected system (`moldynx list-analyses` shows all; `--plan` shows what runs and why).
 The complex/ligand/nucleic modules are implemented and gate correctly but await
 validation on a matching test trajectory.
 
@@ -103,14 +103,14 @@ cat results/manifest.json     # versions, git commit, seeds, params, input hashe
 ## Container
 
 ```bash
-docker build -t mdforge .
-docker run --rm -v /data/sim:/sim mdforge analyze --input /sim --output /sim/results
+docker build -t moldynx .
+docker run --rm -v /data/sim:/sim moldynx analyze --input /sim --output /sim/results
 ```
 
 ## Roadmap
 
 See **[ROADMAP.md](ROADMAP.md)** for the plan — the flagship being a
-**comparison mode** (`mdforge compare`) that overlays control vs. protein–ligand /
+**comparison mode** (`moldynx compare`) that overlays control vs. protein–ligand /
 protein–protein systems on shared axes (ΔRMSF maps, common-subspace PCA, ensemble
 similarity), plus parallel execution, a functional API, membrane and multi-engine
 support — drawing design influence from
@@ -119,9 +119,9 @@ support — drawing design influence from
 
 ## Citation
 
-If you use mdforge, please cite it (concept DOI — always resolves to the latest version):
+If you use MolDynX Tools, please cite it (concept DOI — always resolves to the latest version):
 
-> Mahmoud, H. *mdforge: a reusable, reproducible analysis framework for GROMACS
+> Mahmoud, H. *MolDynX Tools: a reusable, reproducible analysis framework for GROMACS
 > molecular dynamics simulations.* Zenodo. https://doi.org/10.5281/zenodo.21265946
 
 A machine-readable [`CITATION.cff`](CITATION.cff) is included (GitHub shows a