Simulation Workflows

---
name: simulation-workflows
description: "Set up and run practical OpenMM Python application-layer
  simulations from PDB, PDBx/mmCIF, Amber, GROMACS, CHARMM, and Tinker inputs,
  including Simulation setup, integrators, reporters, minimization, stepping,
  checkpoints, portable state restarts, and small validation smokes."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT, GPL, LGPL
---

# Simulation Workflows

Use this sub-skill when the task is to write, adapt, debug, or sanity-check an OpenMM Python application-layer simulation script. It owns the workflow that loads input files, creates or receives a `System`, creates a `Simulation`, initializes the `Context`, attaches reporters, minimizes, runs steps, and saves or resumes progress.

## Route Here For

- Creating short scripts around `Simulation(topology, system, integrator, platform=None, platformProperties=None, state=None)`.
- Loading coordinates/topologies from `PDBFile`, `PDBxFile`, Amber `prmtop`/`inpcrd`, GROMACS `top`/`gro`, CHARMM `psf` plus coordinate and parameter files, or Tinker `xyz`/parameter files.
- Choosing ordinary application-layer integrators such as `LangevinMiddleIntegrator`, `LangevinIntegrator`, or `VerletIntegrator` for simple production or smoke runs.
- Adding `DCDReporter`, `StateDataReporter`, `CheckpointReporter`, `PDBReporter`, or `PDBxReporter` output.
- Using `minimizeEnergy()`, `step()`, `runForClockTime()`, `saveCheckpoint()`, `loadCheckpoint()`, `saveState()`, and `loadState()`.
- Writing quick Reference/CPU smoke checks that avoid long trajectories and verify positions, energy, step count, or reporter output.

## Use Other Sub-skills For

- Force-field XML choice, `Modeller`, solvation, ions, missing atoms, templates, and model editing: `../force-fields-modeling/SKILL.md`.
- Custom expression forces, custom reporters beyond basic app-layer reporting, advanced alchemical systems, or custom integrators: `../custom-forces-integrators/SKILL.md`.
- CUDA/OpenCL/HIP/CPU/Reference platform selection, precision, device properties, performance, and platform-specific errors: `../platforms-performance/SKILL.md`.
- C++ APIs, plugins, serialization internals, or source-level extension work: `../development-extensions/SKILL.md`.

## Working References

- Start with `references/simulation-recipes.md` for PDB, Amber, GROMACS, CHARMM, Tinker, smoke, minimization, stepping, and restart recipes.
- Use `references/file-formats-and-reporters.md` for loader pairing, reporter options, checkpoint/state differences, and validation snippets.
- Use `references/troubleshooting.md` when a script fails to load files, builds a bad `System`, produces NaNs, writes no output, or cannot resume from a checkpoint.
- Run `scripts/minimal_reference_smoke.py` to verify that OpenMM imports, units, `Context`, `Simulation`, minimization, stepping, and serialization work on the Reference platform without external data files.

## Default Safe Pattern

1. Import from `openmm.app`, `openmm`, and `openmm.unit`; use explicit unit-bearing quantities such as `300*kelvin`, `1/picosecond`, and `0.002*picoseconds`.
2. Load topology and positions from matching input files; pass periodic box vectors from the coordinate file when the topology format needs them.
3. Create or receive a `System` before constructing `Simulation`; changes to `System` after `Simulation` creation do not affect the existing `Context`.
4. Create an integrator, then `Simulation(topology, system, integrator, ...)`; set positions and, for dynamics or restart-sensitive tests, set velocities explicitly.
5. Minimize before dynamics unless the workflow is intentionally evaluating unminimized input.
6. Attach reporters before `step()`; use short intervals and small step counts for smoke tests.
7. Prefer `saveState()`/`loadState()` for portable restarts across hardware/platforms; use checkpoints only for same-system, same-platform, same-version continuation.

## Acceptance Checks

- The script imports `openmm`, `openmm.app`, and `openmm.unit` without relying on the OpenMM source checkout.
- Every physical value has units or is intentionally unitless where OpenMM expects a count, boolean, or enum.
- The topology, positions, and system particle count are consistent before the first `step()`.
- Reporters write to intentional paths or file-like objects, and progress reporters specify `totalSteps`.
- Smoke runs are bounded, usually 0-10 steps on `Reference` or `CPU`, and check a concrete invariant such as `currentStep`, finite energy, positions present, or a restart restoring positions.