Add open-source Amber ff14SB + OpenFF Sage parametrization for protein systems

docs/content/docs/developer-guide/architecture.mdx

@@ -180,8 +180,8 @@ graph TD
 
 - **`config.py`**: Pydantic models for local and SLURM execution. `ExecutorConfig` handles local runs; `SlurmExecutorConfig` adds SLURM-specific fields (account, partition, walltime, gres, per-stage overrides). Both serialize to/from YAML via `from_yaml()` and `model_dump()`.
 - **`session.py`**: `parsl_session()` context manager that owns the Parsl DataFlowKernel lifecycle. On exit it calls `parsl.clear()` and explicitly `scancel`s any lingering SLURM job IDs.
-- **`apps.py`**: Defines `get_build_app()` (python\_app for system building), `get_grompp_app()` and `get_mdrun_app()` (bash\_apps for GROMACS). Nearly all conditional logic (GPU, MPI, thread counts, restart flags) is resolved in Python before generating the bash script — the only permitted runtime branch is a small `if/elif/else/fi` block for binary detection when `gmx_binary` is set to `auto`.
-- **`stages.py`**: `STAGE_REGISTRY` declares the canonical pipeline (EM → NVT → NPT → Production) as `StageSpec` dataclasses. `run_stage()` is the single generic dispatch function for all stages.
+- **`apps.py`**: Defines `get_build_app()` (python\_app for system building), `get_grompp_app()` and `get_mdrun_app()` (bash\_apps for GROMACS). Nearly all conditional logic (GPU, MPI, thread counts, restart flags) is resolved in Python before generating the bash script — the only permitted runtime branches are a small `if/elif/else/fi` block for binary detection when `gmx_binary` is set to `auto`, and, in the grompp script only, a GROMACS version check that is emitted when the topology's force field needs a minimum GROMACS version (e.g. `amber14sb.ff` needs 2026).
+- **`stages.py`**: `STAGE_REGISTRY` declares the canonical pipeline (EM → NVT → NPT → Production) as `StageSpec` dataclasses. `run_stage()` is the single generic dispatch function for all stages; it derives the minimum GROMACS version from the simulation directory's `topology.top` and passes it to grompp.
 - **`build.py`** / **`simulate.py`**: Top-level entry points. `build_systems()` submits parallel build tasks; `run_simulations()` chains stages sequentially per simulation with checkpoint detection and trajectory validation.
 - **`tui.py`**: Interactive SLURM configuration wizard using `questionary`. Auto-discovers cluster hardware via `sinfo`/`sacctmgr` and persists the result as a reusable YAML file.
 

docs/content/docs/installation.mdx

@@ -93,6 +93,14 @@ MDFactory currently supports GROMACS workflows with OpenMM-assisted build steps.
 conda install -c conda-forge gromacs
 ```
 
+<Callout type="info" title="Amber protein route needs GROMACS 2026">
+The open-source `parametrization: amber` route for `proteinbox` and `protein_mixedbox` uses the
+`amber14sb.ff` force field that ships with **GROMACS 2026 or later**. Builds and simulations fail
+early with a clear error when an older `gmx` is found. The pixi workspace provides ready-made
+environments: `pixi run -e gmx ...` (CPU build, all platforms) and `pixi run -e gmx-cuda ...`
+(CUDA build, linux-64).
+</Callout>
+
 ### OpenMM
 
 ```bash

docs/content/docs/user-guide/parametrization.mdx

@@ -3,7 +3,7 @@ title: Parametrization
 description: Force field parametrization methods in MDFactory
 ---
 
-MDFactory supports two force field parametrization methods for generating molecular mechanics parameters from SMILES strings. Both generate GROMACS-compatible ITP files.
+MDFactory supports two force field parametrization methods for generating molecular mechanics parameters from SMILES strings, SMIRNOFF and CGenFF. Both generate GROMACS-compatible ITP files. Protein systems additionally support an open-source Amber ff14SB + OpenFF Sage route.
 
 ## Available parametrization methods
 
@@ -106,6 +106,55 @@ parametrization: cgenff
 
 CGenFF does not require additional configuration options as it uses the global installation settings.
 
+### Amber ff14SB + OpenFF Sage (protein systems)
+
+The **amber** parametrization is a fully open-source route for the `proteinbox` and
+`protein_mixedbox` system types. It needs no CGenFF or SILCSBIO license:
+
+- **Protein:** Amber ff14SB, using the `amber14sb.ff` force field that ships with GROMACS, through `gmx pdb2gmx`.
+- **Small-molecule solutes** (`protein_mixedbox`): OpenFF Sage through SMIRNOFF.
+- **Water and ions:** TIP3P and Joung–Cheatham Na⁺/Cl⁻ from `amber14sb.ff`.
+
+<Callout type="warn" title="Requires GROMACS 2026 or later">
+`amber14sb.ff` is only shipped with, and only correct for, GROMACS ≥ 2026 (older versions silently
+ignore its LEaP dihedral reordering). MDFactory checks the `gmx` version before `pdb2gmx` at build
+time and again before the first `grompp` of `mdfactory simulate`, on the node that runs the job.
+Use the pixi `gmx` environment (`pixi run -e gmx ...`, or `gmx-cuda` for the CUDA build) or point
+`[gromacs] GMX_PATH` at a GROMACS 2026 binary.
+</Callout>
+
+**Configuration:**
+
+```yaml
+engine: gromacs
+parametrization: amber
+parametrization_config:
+  type: amber
+  forcefield: amber14sb        # only amber14sb is supported
+  water_model: tip3p           # only tip3p is supported
+  ignore_hydrogens: true
+  merge_all: false
+  sage_forcefield: openff-2.2.0.offxml
+  charge_method: openff-gnn-am1bcc-0.1.0-rc.3.pt
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `forcefield` | `amber14sb` | Protein force field passed to `pdb2gmx`. Only `amber14sb` is supported. |
+| `water_model` | `tip3p` | Water model passed to `pdb2gmx`. Only `tip3p` is supported. |
+| `ignore_hydrogens` | `true` | Drop input hydrogens and let `pdb2gmx` rebuild them. |
+| `merge_all` | `false` | Merge all chains into one moleculetype. |
+| `sage_forcefield` | `openff-2.2.0.offxml` | OpenFF force field for small-molecule solutes. Ignored for `proteinbox`. |
+| `charge_method` | `openff-gnn-am1bcc-0.1.0-rc.3.pt` | Partial charge method for solutes (see [Charge methods](#charge-methods)). Ignored for `proteinbox`. |
+
+Amber builds install their own run schedule with Sage-style nonbonded settings
+(`rcoulomb = rvdw = 0.9`, PME, `vdw-modifier = Potential-switch`, `rvdw-switch = 0.8`,
+`DispCorr = EnerPres`). Protonation states use Amber residue names directly (e.g. `HIE`, `HID`, `HIP`).
+
+Sage solute parameters share the regular SMIRNOFF parameter cache (see below). The cache is keyed
+by the OpenFF force field only, so a solute parametrized earlier with a different `charge_method`
+is reused as-is.
+
 ## Choosing a parametrization method
 
 | Use Case | Recommended Method |
@@ -115,6 +164,7 @@ CGenFF does not require additional configuration options as it uses the global i
 | Lipid bilayer simulations | CGenFF (CHARMM36 compatible) |
 | Quick prototyping | SMIRNOFF (faster, no license) |
 | Compatibility with existing CHARMM systems | CGenFF |
+| Protein systems without a CGenFF license | Amber (ff14SB + Sage, GROMACS ≥ 2026) |
 
 ## Parameter caching
 

examples/protein_mixedbox/lysozyme_amber_fixed_box.yaml

@@ -0,0 +1,48 @@
+# Open-source route: Amber ff14SB (amber14sb.ff, GROMACS >= 2026) for the protein,
+# OpenFF Sage for the ethanol solute, and native TIP3P water and ions.
+# No CGenFF/SILCSBIO installation is needed.
+simulation_type: protein_mixedbox
+engine: gromacs
+parametrization: amber
+parametrization_config:
+  type: amber
+  forcefield: amber14sb
+  water_model: tip3p
+  ignore_hydrogens: true
+  sage_forcefield: openff-2.2.0.offxml
+
+system:
+  protein:
+    resname: LYZ
+    count: 1
+    pdb_path: ../proteinbox/1aki.pdb
+    chains: [A]
+    disulfide_bonds:
+      - [CYS6, CYS127]
+      - [CYS30, CYS115]
+      - [CYS64, CYS80]
+      - [CYS76, CYS94]
+    protonation_states:
+      HIS15: HIE
+  species:
+    # ~53 M water leaves room for the 1 M ethanol (about 1.0 g/mL solvent). The
+    # 55 M + 1 M of the CHARMM example over-fills the box for TIP3P + Sage.
+    - smiles: O
+      resname: SOL
+      concentration: 53.0
+    - smiles: CCO
+      resname: ETH
+      concentration: 1.0
+  sizing:
+    type: fixed_box
+    box_size: 72.0
+  padding: 12.0
+  concentration_volume_basis: protein_excluded
+  partial_specific_volume: 0.73
+  relax_steps: 10000
+  ionization:
+    # Salt is added on top of neutralization (and any packed ion species),
+    # resolved against concentration_volume_basis. Set concentration: 0 to add
+    # no salt and set ionic strength via packed ion species instead.
+    neutralize: true
+    concentration: 0.15

examples/protein_mixedbox/lysozyme_amber_water_fixed_box.yaml

@@ -0,0 +1,42 @@
+# Open-source route: Amber ff14SB (amber14sb.ff, GROMACS >= 2026) with native
+# TIP3P water and ions only (no small-molecule solutes).
+simulation_type: protein_mixedbox
+engine: gromacs
+parametrization: amber
+parametrization_config:
+  type: amber
+  forcefield: amber14sb
+  water_model: tip3p
+  ignore_hydrogens: true
+  sage_forcefield: openff-2.2.0.offxml
+
+system:
+  protein:
+    resname: LYZ
+    count: 1
+    pdb_path: ../proteinbox/1aki.pdb
+    chains: [A]
+    disulfide_bonds:
+      - [CYS6, CYS127]
+      - [CYS30, CYS115]
+      - [CYS64, CYS80]
+      - [CYS76, CYS94]
+    protonation_states:
+      HIS15: HIE
+  species:
+    - smiles: O
+      resname: SOL
+      concentration: 55.0
+  sizing:
+    type: fixed_box
+    box_size: 72.0
+  padding: 12.0
+  concentration_volume_basis: protein_excluded
+  partial_specific_volume: 0.73
+  relax_steps: 10000
+  ionization:
+    # Salt is added on top of neutralization (and any packed ion species),
+    # resolved against concentration_volume_basis. Set concentration: 0 to add
+    # no salt and set ionic strength via packed ion species instead.
+    neutralize: true
+    concentration: 0.15

examples/protein_mixedbox/protein_mixedbox_amber.csv

@@ -0,0 +1,2 @@
+simulation_type,engine,parametrization,parametrization_config.type,parametrization_config.forcefield,parametrization_config.water_model,parametrization_config.ignore_hydrogens,system.protein.resname,system.protein.pdb_path,system.protein.chains,system.protein.disulfide_bonds,system.protein.protonation_states.HIS15,system.species.SOL.smiles,system.species.SOL.concentration,system.species.ETH.smiles,system.species.ETH.concentration,system.sizing.type,system.sizing.box_size,system.padding,system.concentration_volume_basis,system.partial_specific_volume,system.relax_steps,system.ionization.neutralize,system.ionization.concentration
+protein_mixedbox,gromacs,amber,amber,amber14sb,tip3p,True,LYZ,../proteinbox/1aki.pdb,A,CYS6-CYS127;CYS30-CYS115;CYS64-CYS80;CYS76-CYS94,HIE,O,53.0,CCO,1.0,fixed_box,72.0,12.0,protein_excluded,0.73,10000,True,0.15

examples/proteinbox/lysozyme_amber14sb.yaml

@@ -0,0 +1,28 @@
+# Open-source route: Amber ff14SB (amber14sb.ff, GROMACS >= 2026) + TIP3P and
+# Joung-Cheatham ions. No CGenFF/SILCSBIO installation is needed.
+simulation_type: proteinbox
+engine: gromacs
+parametrization: amber
+parametrization_config:
+  type: amber
+  forcefield: amber14sb
+  water_model: tip3p
+  ignore_hydrogens: true
+
+system:
+  protein:
+    resname: LYZ
+    count: 1
+    pdb_path: ./1aki.pdb
+    chains: [A]
+    disulfide_bonds:
+      - [CYS6, CYS127]
+      - [CYS30, CYS115]
+      - [CYS64, CYS80]
+      - [CYS76, CYS94]
+    protonation_states:
+      HIS15: HIE
+  padding: 12.0
+  ionization:
+    neutralize: true
+    concentration: 0.15

examples/proteinbox/proteins_amber.csv

@@ -0,0 +1,2 @@
+simulation_type,engine,parametrization,parametrization_config.type,parametrization_config.forcefield,parametrization_config.water_model,parametrization_config.ignore_hydrogens,system.protein.resname,system.protein.pdb_path,system.protein.chains,system.protein.disulfide_bonds,system.protein.protonation_states.HIS15,system.padding,system.ionization.neutralize,system.ionization.concentration,system.relax_steps
+proteinbox,gromacs,amber,amber,amber14sb,tip3p,True,LYZ,1aki.pdb,A,CYS6-CYS127;CYS30-CYS115;CYS64-CYS80;CYS76-CYS94,HIE,12.0,True,0.15,100