---

name: system-preparation description: "Prepare, minimize, equilibrate, serialize, and safely continue coronavirus molecular systems with OpenMM." metadata: disco-role: operating disable-model-invocation: true license: CC BY 4.0

System preparation

Use this route when a task needs an OpenMM molecular system prepared from a validated PDB, including solvation, ion placement, minimization, a short equilibration, XML/PDB serialization, or continuation at a longer timestep. The bundled scripts provide bounded, explicit-argument baselines that can be run from any working directory.

Route by intent

• Prepare an apo or straightforward protein system: read workflows.md, validate the input first with the sibling structure-curation route, then use scripts/simulate_openmm_system.py.
• Prepare a protein–ligand system: read ligand-complex.md before choosing OpenFF/SystemGenerator/ParmEd. Route residue naming, bond edits, and coordinate repair to structure-curation.
• Continue a serialized system: confirm that the PDB, system.xml, and state.xml belong to the same preparation, then use scripts/continue_openmm.py and the continuation contract in workflows.md.
• Diagnose installation or platform behavior: run scripts/check_openmm_env.py --cpu-smoke; treat CUDA as an optional probe, not as evidence of required capability.

Operating sequence

1. Establish source-structure identity, chain selection, protonation/capping status, force-field assumptions, and output directory. Do not silently change a structure to make a simulation start.
2. Validate topology/positions using the sibling route. For a complex, confirm ligand chemistry and parameters before calling createSystem.
3. Start with the smallest deterministic CPU run. Use explicit --steps and --iterations; never inherit historical multi-nanosecond defaults into a test run.
4. Inspect atom counts, periodic box vectors, potential energy, and serialized files. Keep the input and output directories distinct unless an intentional, reviewed overwrite is requested.
5. Record parameters and provenance in the project note route. These helpers reproduce preparation mechanics; they do not establish production-quality sampling, biological efficacy, or paper-level validation.

Safety gates

• CPU OpenMM is the required baseline. CUDA can be requested only after a platform probe and may fail because of driver/toolkit/PTX incompatibility; see troubleshooting.md.
• A missing optional ligand package is a reason to stop and report a prerequisite, not to substitute an unparameterized ligand.
• Keep the default run short. The helper refuses excessive work unless --allow-long-run is supplied, and even then a research plan should define an independent budget.
• Do not run Folding@home client workflows, network downloads, or long production trajectories through this route.

Handoff

For coordinate/chain/ligand edits, hand off to ../structure-curation/SKILL.md. For target rationale and publication evidence, hand off to ../project-context/SKILL.md. After a successful run, hand off artifact names, exact parameters, package/platform information, warnings, and unresolved scientific limitations rather than only saying “equilibrated.”