Openmm

---
name: openmm
description: "Use OpenMM for molecular simulation workflows, force-field/model
  preparation, custom forces/integrators, platform/performance diagnostics, and
  maintainer extension work."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT, GPL, LGPL
---

# OpenMM

Use this repo skill when a task involves OpenMM, the molecular simulation toolkit exposed through `openmm`, `openmm.app`, `openmm.unit`, C++ APIs, runtime platforms, plugins, or the OpenMM source tree.

## Quick Start

- Install OpenMM from the public package channel appropriate for the user's environment; for Python workflows, verify `import openmm, openmm.app, openmm.unit` before writing larger scripts.
- Run `scripts/openmm_reference_smoke.py` for a checkout-independent Reference-platform sanity check that constructs a tiny system, evaluates a `Context`, and reports available platforms.
- Read `references/environment-and-platform-facts.md` for package/version caveats, install extras, platform expectations, and safe verification commands.
- Read `references/openmm-capability-map.md` when routing a broad request across sub-skills.
- Read `references/troubleshooting.md` first for cross-cutting install/import, unit, platform, and workflow failures.

## Route by User Task

- Use `sub-skills/simulation-workflows/SKILL.md` for Python application-layer simulations: loading PDB/mmCIF, Amber, GROMACS, CHARMM, or Tinker inputs; creating `Simulation`; attaching reporters; minimizing; stepping; and checkpoint or XML-state restarts.
- Use `sub-skills/force-fields-modeling/SKILL.md` for `ForceField`, `Modeller`, bundled XML files, `createSystem()`, missing hydrogens, solvent/ions, membranes, residue template errors, parameterized file formats, and ffxml authoring.
- Use `sub-skills/custom-forces-integrators/SKILL.md` for `Custom*Force` classes, expression syntax, runtime parameters, tabulated functions, force groups, `CustomIntegrator`, and serialization-aware custom systems.
- Use `sub-skills/platforms-performance/SKILL.md` for `Reference`, `CPU`, `CUDA`, `OpenCL`, or `HIP` platform selection, `platformProperties`, precision/device/thread choices, plugin availability, benchmark interpretation, and performance diagnostics.
- Use `sub-skills/development-extensions/SKILL.md` for changing OpenMM itself: C++ API/implementation work, kernels, plugins, serialization proxies, Python wrapper generation, CMake builds, and focused native tests.

## Core Concepts

- `openmm.System` stores particles, constraints, forces, virtual sites, and periodic box information; most simulation errors trace back to mismatch among `System`, topology, positions, and force parameters.
- `openmm.Context` binds a `System`, an `Integrator`, and a `Platform`; changes to a `System` after `Context` creation usually require updating parameters in context or reinitializing.
- `openmm.app.Simulation(topology, system, integrator, platform=None, platformProperties=None, state=None)` is the high-level Python workflow object for most application scripts.
- `openmm.app.ForceField(*files)` creates `System` objects from topologies and bundled or custom XML; use `Modeller(topology, positions)` before `createSystem()` when the structure needs hydrogens, solvent, ions, membranes, or extra particles.
- Physical quantities should carry `openmm.unit` units, for example `300*kelvin`, `1/picosecond`, `0.004*picoseconds`, and `1*nanometer`.
- The `Reference` platform is slow but excellent for correctness smokes; `CPU`, `CUDA`, `OpenCL`, and `HIP` need environment-specific package/plugin/runtime support.

## Safe Working Pattern

1. Clarify whether the user is running a simulation, preparing a model, defining custom physics, diagnosing hardware/performance, or modifying OpenMM internals.
2. Route to the narrowest sub-skill and use its nearest references/scripts rather than writing a large one-off script from memory.
3. Start with a bounded smoke: import OpenMM, list platforms, build or load a tiny system, run 0-10 steps or one energy evaluation, and assert finite output.
4. Escalate to production settings only after topology, positions, `System`, integrator, reporter paths, and platform choice are validated.
5. For source-tree development, separate build-required/native tests from package-level Python smokes; do not assume a user has a compiled OpenMM build tree.

## Bundled Runtime Assets

- `references/repo-provenance.md` records the source commit, dirty state, package version facts, and evidence paths used to create this skill.
- `references/openmm-capability-map.md` maps natural OpenMM requests to sub-skill owners, evidence, and validation signals.
- `references/environment-and-platform-facts.md` summarizes install/import/platform facts verified during skill creation without exposing private environment paths.
- `references/troubleshooting.md` covers cross-cutting failures and points to sub-skill-specific troubleshooting files.
- `scripts/openmm_reference_smoke.py` is a safe, checkout-independent Reference-platform smoke test.

## Boundaries

- This skill is self-contained runtime guidance. It does not require the original OpenMM checkout to be available.
- Do not link future agents to original repo docs, examples, tests, scripts, or absolute local paths; use the bundled references and scripts here.
- Treat benchmarks, GPU runs, source builds, `ctest`, and wrapper generation as optional, environment-dependent workflows that require explicit user context.