Amber Chemist

amber-chemist Skill (v1.0)

This skill is the Amber-native sibling to ase-chemist. It is MD-first: the v1.0 verb is normal (single-replica) MD with configurable stages, restart-and-extend, restraints, barostat options, explicit or implicit solvent, and a verbatim-mdin escape hatch. T-REMD is built on top of that core and ships in v1.0 too — currently the strongest differentiator vs ase-chemist's narrower v1.3 carve-out (which cannot do REMD). Analysis (cpptraj) and endpoint scoring (MMPBSA) are add-ons that consume the MD output, not co-equal verbs.

Always do this first

python scripts/check_env.py

The output ends with a [SUMMARY] line that names exactly which workflows your environment supports right now.

Environment-driven fallback strategy:

1. Parse the [SUMMARY] to determine available engines (pmemd.cuda, pmemd.cuda.MPI, pmemd, sander, etc.).
2. If the user requests REMD but only single-replica engines are available, always recommend single-replica MD as the fallback.
3. If the user requests MMPBSA scoring or cpptraj analysis but MMPBSA.py / cpptraj is not on PATH, report the gap clearly rather than fabricating a workaround.
4. Recommend the strongest path that the environment can run today; do not fabricate workarounds.

MD-core method selection

Deep dive: references/md_core.md for stage rendering, restart vs extend, restraints, barostat options, and implicit-solvent (GB) MD.

Barostat caveat: the default Berendsen barostat produces the wrong NPT distribution — use it for equilibration (the density stage) only. Switch production to --barostat monte_carlo for correct NPT ensemble averages. See references/md_core.md §Barostats.

Add-ons (consume MD output; not part of the MD core)

Framing: references/add_ons.md explains why add-ons consume MD output rather than acting as co-equal verbs, plus the extension-surface convention.

Force-field selection (v1.0)

Today: GAFF2 + AM1-BCC for small organics in TIP3P / OPC / SPCE / TIP4P-Ew water (or vacuum / implicit GB). That's the only path amber_prep.py runs.

--force-field {ff14SB, ff19SB, OL21} is pre-wired but raises NotImplementedError in v1.0. Biopolymer prep (proteins, nucleic acids, complexes) lands in v1.1. When the user asks for protein MD, say so honestly: this skill ships GAFF2-only today; ff19SB+OPC and OL21 are deferred. See references/extension_map.md for where each deferred feature would land.

Deep dive: references/force_fields.md for GAFF2/AM1-BCC details, supported water models (TIP3P / OPC / SPCE / TIP4P-Ew), and the deferred biopolymer set (ff19SB, OL21, LIPID17).

Engine selection

Auto-fail with a clear message if no engine of the right flavor is on PATH. AmberTools25 is fully open-source, including pmemd.cuda; if the user is on a fresh install and missing pmemd.cuda, point them at https://ambermd.org/GetAmber.php.

Verification & clarification

Don't ask what's already named — and frame what you do ask

The two failure modes to avoid: silently picking wrong physics (a wrong --net-charge shifts every AM1-BCC partial charge; a REMD ladder with 50 K gaps lands far below the 15-50% acceptance window; MMPBSA on an implicit-only prmtop is wrong physics), and re-asking the user something the prompt or input file already names.

When the answer is genuinely underdetermined, frame the question with the option you'd pick and the reason — e.g., "8 replicas geometric 300-400 K gives ~13–16 K gaps (widening with T), which should land inside the 15-50% acceptance window; keep that or hand-tune?" — beats a blank "what ladder?".

Ask the user to verify before recommending execution

After choosing parameters, restate them in a short block and ask the user to confirm before suggesting they run anything. What to surface depends on the verb:

Single-replica MD (amber_run.py --mode standard / amber_md.py):

• Force field + water model (GAFF2 + TIP3P, etc.)
• Net charge (silent-shift failure mode if wrong)
• Engine (pmemd.cuda / pmemd / sander)
• Buffer / box shape, salt conc if non-zero
• Stage durations (heat ps, density ps, prod ns) and barostat
• Restraints (mask + weight) if any
• Output directory

T-REMD (amber_remd.py / amber_run.py --mode remd):

• N replicas + T-low / T-high + ladder shape
• Exchange-every (steps) and total time per replica
• MPI engine + launcher (mpirun vs srun)
• Implicit-solvent flag if relevant
• Expected acceptance window — geometric gaps widen with T (~13–16 K for 8 replicas over 300–400 K is normal); flag only if a gap exceeds ~30 K or if N replicas is below 4. The script warns at >50 K.

Add-ons (amber_score.py, amber_analyze.py, amber_sp.py):

• MMPBSA: method (gb / pb / both), igb model, ionic strength, frame range, MPI count
• Analyze: which analyses (rmsd / rmsf / rdf / hbond / radgyr), masks, reference frame
• SP: mode (snapshot / trajectory), frame slice (trajectory mode), engine

Keep it tight — a 4-6 line summary, not a paragraph. If the user has already approved the plan, don't re-ask.

Carve-out relationship with ase-chemist

ase-chemist's v1.3 carve-out does plain GAFF2 NPT MD only; amber-chemist is the deeper sibling (restart/extend, REMD, implicit solvent, cpptraj, MMPBSA). Shared-zone prompts (GAFF2 + AM1-BCC + TIP3P + plain MD) are correct from either. See references/carveout_relationship.md.

Looking up Amber semantics

For mdin keyword behavior, force-field options, and file formats, check references/mdin_keywords.md first (the ~50 most-asked keywords), then references/manual_lookup.md for Reference Manual sections and curated URLs. cpptraj and MMPBSA idioms live in references/cpptraj_idioms.md and references/mmpbsa_idioms.md.

Smell test — don't fabricate. If you are about to write "I think <keyword> defaults to ..." or "the standard value for <flag> is roughly ...", stop and check the manual first. Hallucinated Amber semantics is a high-cost, hard-to-detect failure mode — pmemd often runs with the wrong value and produces plausible-looking output that misleads downstream analysis.

Reporting results

When you finish a task, report:

1. The pipeline used (prep + stages, or REMD config, or scoring deck) and why it was chosen given system size, available engines, and what the user asked for.
2. Final numbers with units: trajectory length (ns), final temperature / density / volume parsed from the last mdout, REMD per-pair exchange acceptance rates (flag any outside [15%, 50%]), MMPBSA delta_total ± std-err if scoring.
3. Where outputs were written: prmtop / rst7 / .nc trajectory / mdout / exchange_rate.txt / <prefix>_summary.json.
4. Any caveats — e.g., "Berendsen for density only; prod ran with Monte Carlo", "REMD acceptance was 18% on the highest pair — borderline; consider one more replica", "MMPBSA GB-only — PB is ~2× slower but more defensible for publication".

Honest deferrals

When the user asks for something this skill does not ship — free energy (TI / FEP / MBAR), enhanced sampling beyond T-REMD (aMD, SMD, umbrella, metadynamics), Hamiltonian REMD, biopolymers (ff19SB / OL21), constant-pH, QM/MM, membrane/LIPID17, multi-GPU, PLUMED — point at references/extension_map.md for the concrete landing spot rather than fabricating a workflow. Do not pretend to support these. For features this skill DOES ship but where the user is hitting trouble, check references/failure_modes.md first (known failure modes + recovery recipes).