Engine¶

MD / simulation engine abstractions for LAMMPS, GROMACS, OpenMM and CP2K. Every engine has run. LAMMPS, GROMACS and OpenMM also have one input writer each, with one signature: generate_inputs(frame, forcefield, output_dir, *, ...) returns the written paths by name, "input" always the runnable input run takes. CP2K runs a CP2K input you write; it generates no inputs.

Quick reference¶

Symbol	Summary	Preferred for
`LammpsEngine`	`generate_inputs(frame, ff, out)` → `input` (the input script), `data`, `settings`, `init`; `minimize` / `md` relax a frame through the same deck	LAMMPS decks and relaxations
`GromacsEngine`	`generate_inputs(frame, ff, out)` → `input` (`em.mdp`), `gro`, the whole `top` (`write_top_system`), `nvt` (`nvt.mdp`); `run` grompp's and mdrun's an `.mdp`	GROMACS input sets
`OpenmmEngine`	`generate_inputs(frame, ff, out, simulation=…)` → `input` (the Python script), `pdb`, `forcefield` (XML with residue templates)	Running OpenMM simulations
`OpenmmSimulationConfig`	OpenMM run configuration, validated on construction	Configuring an OpenMM run
`Cp2kEngine`	Runs a CP2K input you write (no `generate_inputs`)	Running CP2K simulations
`Script`	An immutable (name, text, path) value; what `run` takes	Writing or loading an input script

Key behavior¶

An engine's executable, environment (env + env_manager), launcher, env_vars and timeout are its [engine.<name>] settings in molpy's configuration, falling back to [engine] (molpy.config); the constructor takes config, workdir and check_executable; they are resolved by the shared molpy.wrapper.Tool core
run(scripts, *, workdir, capture_output, check) writes the scripts (the first is the input) and runs the engine; it keeps no state and does not change the scripts. check=True is the default. GROMACS's run also takes structure=, the coordinates grompp -c reads: <prefix>.gro by default, the previous stage's output ("em.gro") for a later stage
Every failure is a molpy.wrapper.ToolError carrying tool ("engine.lammps"), returncode and tail — the program's stderr or, when nothing was captured, its log (log.lammps, cp2k.out, GROMACS's <stem>.log)
Every subprocess is logged to molpy.engine.<name> (lammps, gromacs, openmm, cp2k) as mollog records carrying the command, cwd, returncode and elapsed_s (GROMACS adds step: grompp / mdrun); generate_inputs logs inputs written with the files
The decks write the force field's own nonbonded settings (each pair style's cutoff; coul/long/pme long-range, coul/cut cut off); an explicit argument overrides them
A frame without a periodic box is a non-periodic system in every engine: LAMMPS shrink-wraps it, OpenMM uses NoCutoff; a method that needs a periodic cell (Ewald / PME / PPPM, CutoffPeriodic, NPT) is refused for it, and GROMACS, periodic only, refuses it

Guide: Simulation Engines
Guide: Configure and Log a Run
API: Config
Guide: File I/O (the data and force-field files the script reads)

Full API¶

Base¶

Engine ¶

Engine(*, config=None, workdir=None, check_executable=True)

Bases: Tool, ABC

Abstract base class for computational chemistry engines.

Concrete subclasses name their configuration table in :attr:tool ("lammps" reads [engine.lammps], falling back to [engine]) and implement :meth:_execute and :meth:_get_default_extension. The :class:~molpy.wrapper.Tool core resolves the settings, environment, executable, launcher, environment variables, time limit and logger; this class writes the scripts into the run directory.

Parameters:

Name	Type	Description	Default
`config`	`Config \| None`	molpy's configuration (:func:`molpy.config.load_config`); `None` loads it (package defaults, user and project files).	`None`
`workdir`	`str \| Path \| None`	Default working directory. `None` creates a temporary directory on each :meth:`run` call.	`None`
`check_executable`	`bool`	Verify the executable is available at construction time (system `PATH` or the configured env). Set to `False` when only writing inputs, or when the binary is only available on a remote node.	`True`

Raises:

Type	Description
`ToolError`	If check_executable is `True` and the executable is not found.
`ValueError`	If the configured environment is incomplete or its manager unsupported.

Example

from molpy.config import load_config from molpy.engine import LammpsEngine, Script

script = Script.from_text("input", "units real\natom_style full\n") config = load_config({"engine": {"lammps": {"executable": "lmp"}}}) engine = LammpsEngine(config=config, check_executable=False) result = engine.run(script, workdir="./calc") print(result.returncode) 0

run ¶

run(
    scripts,
    *,
    workdir=None,
    capture_output=False,
    check=True,
)

Write scripts into the run directory and execute the engine.

Accepts a :class:~molpy.engine.Script, a raw string (named input), a :class:~pathlib.Path to a script file, or a list of scripts and paths. The first script is the engine's input; the rest are written beside it. A script with a path is written under its file name, any other as <name><extension>. Neither the scripts nor the engine are changed: every call names what it runs.

Parameters:

Name	Type	Description	Default
`scripts`	`Script \| str \| Path \| Sequence[Script \| Path]`	The script(s) to run; the first is the input.	required
`workdir`	`str \| Path \| None`	Working directory for this run; `None` is :attr:`workdir`, or a new temporary directory when that is `None` too.	`None`
`capture_output`	`bool`	Capture stdout/stderr.	`False`
`check`	`bool`	Raise :class:`~molpy.wrapper.ToolError` on a non-zero exit.	`True`

Returns:

Type	Description
`CompletedProcess[str]`	class:`subprocess.CompletedProcess` with execution results.

Raises:

Type	Description
`ValueError`	If scripts is an empty list.
`ToolError`	The engine could not start, timed out, or (with check) exited non-zero.

CP2K¶

Cp2kEngine ¶

Cp2kEngine(
    *, config=None, workdir=None, check_executable=True
)

Bases: Engine

CP2K quantum chemistry / molecular dynamics engine.

Runs CP2K input scripts. The executable is engine.cp2k.executable: cp2k.psmp (MPI + OpenMP build) by default, or e.g. cp2k.popt (MPI only). Settings: [engine.cp2k]; logger: molpy.engine.cp2k.

A minimal CP2K input must contain at least &GLOBAL, &FORCE_EVAL, and &MOTION (or &ENERGY) sections.

Example

from molpy.engine import Script from molpy.engine import Cp2kEngine

inp = ( ... "&GLOBAL\n" ... " PROJECT water\n" ... " RUN_TYPE ENERGY\n" ... "&END GLOBAL\n" ... "&FORCE_EVAL\n" ... " METHOD Quickstep\n" ... "&END FORCE_EVAL\n" ... ) script = Script.from_text("input", inp) engine = Cp2kEngine(check_executable=False) result = engine.run(script, workdir="./calc") print(result.returncode) 0

LAMMPS¶

LammpsEngine ¶

LammpsEngine(
    *, config=None, workdir=None, check_executable=True
)

Bases: Engine

LAMMPS molecular dynamics engine.

Runs LAMMPS input scripts. The engine binary is typically named lmp, lmp_serial, or lmp_mpi depending on the build; with no engine.lammps.executable configured, the first of those found in the engine's environment is used, so LammpsEngine() works out of the box on a typical install. Settings: [engine.lammps]; logger: molpy.engine.lammps.

Example

from molpy.config import load_config from molpy.engine import LammpsEngine, Script

script = Script.from_text("input", "units real\natom_style full\nrun 0\n") engine = LammpsEngine(check_executable=False) result = engine.run(script, workdir="./calc") print(result.returncode) 0

MPI execution, as a run override::

config = load_config(
    {"engine": {"lammps": {"launcher": ["mpirun", "-np", "16"]}}}
)
result = LammpsEngine(config=config).run(script, workdir="./calc")

generate_inputs ¶

generate_inputs(
    frame,
    forcefield,
    output_dir,
    *,
    prefix="system",
    atom_style=None,
    units="real",
    pair_style=None,
    body=None,
)

Write a complete LAMMPS deck for frame under forcefield.

Files written (given prefix="system"):

system.data — the structure (molrs's LAMMPS data writer), in atom_style and units.
system.in.settings — molrs's LAMMPS force-field include: the *_style line of every category the frame uses (built-in or a registered force-field IR style; hybrid when a category spans several styles), its coefficients, special_bonds and pair_modify. It is included after read_data, where LAMMPS rejects units, so units is the init's.
system.in.init — units and atom_style (the data file's own), boundary, neighbor and, when pair_style is given, that pair_style line (the include then leaves its own out).
system.in — the input script: init, read_data, settings, kspace_style pppm 1.0e-4 when the force field's Coulomb style is long-range (coul/long/pme) and its pair style is in force, then body (a starter minimise + NVT run by default).

The nonbonded settings are the force field's own: its pair style, cutoffs and mixing are written as it states them, and only an explicit pair_style replaces them.

A frame with a periodic box gets boundary p p p and binned neighbour lists. A frame without one (Atomistic.to_frame() carries no box) is a non-periodic system and gets a non-periodic deck: molrs's data writer puts the atoms inside the bounds of their coordinates widened by 1 length unit on every side, boundary s s s shrink-wraps that box to the atoms, and neighbor 2.0 nsq searches all pairs, since binning needs a box wider than the pair cutoff. A long-range Coulomb style, whose PPPM solver needs a periodic cell, is refused for it (the policy every engine follows: :mod:molpy.engine).

molpy names no style itself: a style molrs can write is emitted and one it cannot is refused by molrs, by name, before any file is written.

Parameters:

Name	Type	Description	Default
`frame`	`Frame`	Typed structure (`type` columns keyed to forcefield).	required
`forcefield`	`ForceField`	The force field the settings are written from.	required
`output_dir`	`str \| Path`	Directory for the deck (created if absent).	required
`prefix`	`str`	Stem of the four file names.	`'system'`
`atom_style`	`str \| None`	LAMMPS `atom_style` of the data file and the init; `None` is the style the frame's atom columns hold (:func:`molpy.io.lammps.infer_lammps_atom_style`: `full` with `mol_id` and `charge`, `atomic` with neither, …).	`None`
`units`	`str`	LAMMPS `units` style — `"real"`, `"metal"` or `"lj"` — of the init, the data file and the coefficients, each converted to it by molrs.	`'real'`
`pair_style`	`str \| None`	A `pair_style` line (without the command) that replaces the force field's own; `None` (the default) keeps the force field's. A replacement needing a long-range solver sets its `kspace_style` in body.	`None`
`body`	`str \| None`	Commands after the settings include; `None` writes the starter minimise + NVT run.	`None`

Returns:

Type	Description
`dict[str, Path]`	`{"data", "settings", "init", "input"}` mapped to the written
`dict[str, Path]`	paths.

Raises:

Type	Description
`ValueError`	If units is not one molrs writes, or the frame has no periodic box and the force field's Coulomb style is long-range; before any file is written.

md ¶

md(
    frame,
    ff,
    *,
    ensemble="nve",
    steps=1000,
    temperature=300.0,
    timestep=1.0,
    seed=12345,
    limit=0.1,
    pair_style=None,
    atom_style=None,
    units="real",
    workdir=None,
    capture_output=False,
)

Run short MD on frame under ff and return a new frame.

A thin sibling of :meth:minimize for settling a packed box. Note that a freshly packed box carries residual clashes; run :meth:minimize first, or use ensemble="nve/limit", to avoid a blow-up under plain nve.

Parameters:

Name	Type	Description	Default
`frame`	`Frame`	Input structure: periodic when it carries a periodic box (`frame.box`), else a non-periodic, shrink-wrapped system.	required
`ff`	`ForceField`	Typified force field.	required
`ensemble`	`str`	One of `"nve"`, `"nve/limit"`, `"nvt"`.	`'nve'`
`steps`	`int`	Number of MD steps.	`1000`
`temperature`	`float`	Initial / target temperature (K).	`300.0`
`timestep`	`float`	Timestep in units time (fs for `real`).	`1.0`
`seed`	`int`	RNG seed for the initial velocity distribution.	`12345`
`limit`	`float`	Per-step displacement cap (Å) for `ensemble="nve/limit"`.	`0.1`
`pair_style`	`str \| None`	A `pair_style` line replacing the force field's own; `None` keeps the force field's.	`None`
`atom_style`	`str \| None`	LAMMPS `atom_style`; `None` is the frame's.	`None`
`units`	`str`	LAMMPS `units`: `real`, `metal` or `lj`.	`'real'`
`workdir`	`str \| Path \| None`	Working directory; temporary when `None`.	`None`
`capture_output`	`bool`	Capture LAMMPS stdout/stderr.	`False`

Returns:

Type	Description
`Frame`	A new :class:`~molpy.Frame` with the post-MD coordinates.

Raises:

Type	Description
`ValueError`	If ensemble is unknown, or as :meth:`generate_inputs`.

minimize ¶

minimize(
    frame,
    ff,
    *,
    etol=0.0001,
    ftol=1e-06,
    max_iter=1000,
    max_eval=10000,
    pair_style=None,
    atom_style=None,
    units="real",
    workdir=None,
    capture_output=False,
)

Energy-minimise frame under force field ff and return a new frame.

Writes a LAMMPS data file and coefficient settings from frame / ff, runs minimize, then splices the relaxed coordinates back onto a copy of frame (topology, types, and box preserved). frame is not mutated.

Typical use is removing residual overlaps after packing::

eng = LammpsEngine()
relaxed = eng.minimize(pack_result.frame, ff)

Parameters:

Name	Type	Description	Default
`frame`	`Frame`	Input structure: periodic when it carries a periodic box (`frame.box`), else a non-periodic, shrink-wrapped system.	required
`ff`	`ForceField`	Typified force field providing pair/bond/angle/... coefficients.	required
`etol`	`float`	Energy stopping tolerance (unitless).	`0.0001`
`ftol`	`float`	Force stopping tolerance (force units).	`1e-06`
`max_iter`	`int`	Maximum minimiser iterations.	`1000`
`max_eval`	`int`	Maximum force/energy evaluations.	`10000`
`pair_style`	`str \| None`	A LAMMPS `pair_style` line replacing the force field's own; `None` (the default) minimises under the force field's pair style, cutoffs and long-range solver (see :meth:`generate_inputs`).	`None`
`atom_style`	`str \| None`	LAMMPS `atom_style`; `None` is the frame's (see :meth:`generate_inputs`).	`None`
`units`	`str`	LAMMPS `units`: `real` (default), `metal` or `lj`.	`'real'`
`workdir`	`str \| Path \| None`	Directory for input/output files; a temporary directory is created when `None`.	`None`
`capture_output`	`bool`	Capture LAMMPS stdout/stderr.	`False`

Returns:

Type	Description
`Frame`	A new :class:`~molpy.Frame` with relaxed coordinates.

Raises:

Type	Description
`ValueError`	As :meth:`generate_inputs` does.
`ToolError`	If LAMMPS fails or writes no output structure; the error carries the tail of `log.lammps`.

GROMACS¶

GromacsEngine ¶

GromacsEngine(
    *,
    prefix="system",
    config=None,
    workdir=None,
    check_executable=True,
)

Bases: Engine

GROMACS molecular dynamics engine.

The executable is the gmx driver, engine.gromacs.executable (gmx by default; gmx_mpi, …). An input script is an .mdp file; :meth:generate_inputs writes the structure and topology it is run against.

Example::

engine = GromacsEngine(check_executable=False)
paths = engine.generate_inputs(frame, ff, "./md")
engine.run(Script.from_path(paths["input"]), workdir="./md")
# NVT from the minimised structure EM wrote:
engine.run(Script.from_path(paths["nvt"]), workdir="./md", structure="em.gro")

Initialise the GROMACS engine.

Parameters:

Name	Type	Description	Default
`prefix`	`str`	Stem of the `.top` :meth:`run` passes to `grompp`, and of the `.gro` it starts a first stage from (what :meth:`generate_inputs` writes).	`'system'`
`config`	`Config \| None`	molpy's configuration; `None` loads it (see :class:`~molpy.engine.Engine`).	`None`
`workdir`	`str \| Path \| None`	Default working directory.	`None`
`check_executable`	`bool`	Verify the executable is available.	`True`

generate_inputs ¶

generate_inputs(
    frame,
    forcefield,
    output_dir,
    *,
    temperature=300.0,
    coulombtype=None,
    rcoulomb=None,
    rvdw=None,
)

Write a ready-to-run GROMACS input set.

Files written (with the engine's prefix, "system" by default): system.gro (initial structure), system.top (the whole topology: the force field's directives, one [ moleculetype ] per molecule with each row's parameters, [ system ] and [ molecules ] — what grompp -p reads), em.mdp (steepest-descent minimisation) and nvt.mdp (V-rescale NVT at temperature K).

The .mdp nonbonded settings are the force field's own: coulombtype is PME for a long-range Coulomb style (coul/long/pme) and Cut-off for a truncated one, rcoulomb is its Coulomb style's cutoff and rvdw its other pair styles' (each defaulting to the other when only one is stated), and rlist the larger. Only what the force field leaves unstated falls back to PME and 1.2 nm; the keyword arguments override.

Parameters:

Name	Type	Description	Default
`frame`	`Frame`	The typed structure (`Atomistic.to_frame()` for a graph) with its angles and dihedrals (`generate_topology`): GROMACS excludes every pair within three bonds, and those rows are how the pair list knows them. Its atoms' `mol_id` splits it into molecules, and its periodic box is the `.gro` box.	required
`forcefield`	`ForceField`	The force field the frame's types name.	required
`output_dir`	`str \| Path`	Directory for the files (created if absent).	required
`temperature`	`float`	Reference and initial-velocity temperature (K).	`300.0`
`coulombtype`	`str \| None`	The `.mdp` `coulombtype`; `None` is the force field's.	`None`
`rcoulomb`	`float \| None`	Coulomb cutoff (nm); `None` is the force field's.	`None`
`rvdw`	`float \| None`	Van der Waals cutoff (nm); `None` is the force field's.	`None`

Returns:

Type	Description
`dict[str, Path]`	`{"input", "gro", "top", "nvt"}` mapped to the written paths:
`dict[str, Path]`	`"input"` is `em.mdp`, the first stage :meth:`run` takes, and
`dict[str, Path]`	`"nvt"` the stage after it.

Raises:

Type	Description
`ValueError`	If the frame has no periodic box, before any file is written: GROMACS's Verlet cutoff scheme (its only one since 2020) simulates periodic systems only, so a vacuum system needs a box larger than the molecule plus twice the cutoff.

run ¶

run(
    scripts,
    *,
    workdir=None,
    structure=None,
    capture_output=False,
    check=True,
)

grompp then mdrun the .mdp scripts starts with.

As :meth:Engine.run <molpy.engine.Engine.run>, plus the structure the stage starts from.

Parameters:

Name	Type	Description	Default
`scripts`	`Script \| str \| Path \| Sequence[Script \| Path]`	The `.mdp` (first) and any files written beside it.	required
`workdir`	`str \| Path \| None`	Working directory for this run (see :meth:`Engine.run <molpy.engine.Engine.run>`).	`None`
`structure`	`str \| Path \| None`	The coordinates `grompp -c` reads, relative to the run directory: `None` is `<prefix>.gro` (a first stage); a later stage names the previous stage's output, e.g. `"em.gro"` after `em.mdp`.	`None`
`capture_output`	`bool`	Capture stdout/stderr.	`False`
`check`	`bool`	Raise :class:`~molpy.wrapper.ToolError` on a non-zero exit.	`True`

Raises:

Type	Description
`ValueError`	If scripts is an empty list.
`ToolError`	A step could not start, timed out, or (with check) exited non-zero.

Script¶

Script `dataclass` ¶

Script(name, text, path=None)

An input script: a name, its text and the file it came from.

Attributes:

Name	Type	Description
`name`	`str`	Logical name; an engine writes an unpathed script to `<name><extension>`.
`text`	`str`	The full text, written as is.
`path`	`Path \| None`	The file it was read from, or `None`; an engine writes it under this file name.

from_path `classmethod` ¶

from_path(path)

The script in the file at path, named after its stem.

The text is the file's, unchanged.

Raises:

Type	Description
`FileNotFoundError`	If the file does not exist.

from_text `classmethod` ¶

from_text(name, text, *, path=None)

A script from a string literal.

The block is dedented and ends in exactly one newline, so an indented triple-quoted string in code becomes a flush-left file.

Parameters:

Name	Type	Description	Default
`name`	`str`	Logical name of the script.	required
`text`	`str`	The script text.	required
`path`	`str \| Path \| None`	The file name an engine writes it under.	`None`

preview ¶

preview(max_lines=20)

The first max_lines lines, numbered, and how many more there are.

save ¶

save(path=None)

Write the text to path (default: :attr:path); return where.

Parent directories are created. The script itself is unchanged.

Raises:

Type	Description
`ValueError`	If no path is given and the script has none.

OpenMM¶

OpenmmEngine ¶

OpenmmEngine(
    *, config=None, workdir=None, check_executable=True
)

Bases: Engine

OpenMM molecular dynamics engine.

Generates a complete set of OpenMM input files from MolPy :class:~molpy.Frame and :class:~molpy.ff.forcefield.ForceField objects. OpenMM itself is not required for input generation; it is only needed to run the generated script.

The generated Python script can be executed directly::

python simulate.py

or via the engine::

result = engine.run(paths["input"], workdir="./output")

which runs engine.openmm.executable (the Python interpreter, python by default) in the configured environment. Settings: [engine.openmm]; logger: molpy.engine.openmm.

Example

from molpy.engine import OpenmmEngine, OpenmmSimulationConfig

simulation = OpenmmSimulationConfig(ensemble="NVT", n_steps=10_000) engine = OpenmmEngine(check_executable=False) paths = engine.generate_inputs(frame, ff, "./output", simulation=simulation)

paths["input"] (simulate.py), paths["pdb"], paths["forcefield"]¶

generate_inputs ¶

generate_inputs(
    frame,
    forcefield,
    output_dir,
    *,
    simulation=None,
    pdb_filename="system.pdb",
    ff_filename="forcefield.xml",
    script_filename="simulate.py",
)

Generate PDB, XML force field, and Python simulation script.

Does not require OpenMM to be installed. The PDB is molrs's :func:~molpy.io.write_pdb; the force-field XML is :func:~molpy.io.write_openmm_system: the force field plus a <Residue> template for every residue of that PDB (its atom names, types, charges and bonds), what ForceField.createSystem matches the PDB topology against.

Parameters:

Name	Type	Description	Default
`frame`	`Frame`	Typed :class:`~molpy.Frame` (string `type` and `element` atom columns, `bonds`) with atom positions.	required
`forcefield`	`ForceField`	A :class:`~molpy.ff.forcefield.ForceField` holding an atom type for every `type` the frame names.	required
`output_dir`	`PathLike`	Directory where files are written (created if absent).	required
`simulation`	`OpenmmSimulationConfig \| None`	Simulation parameters (`None`: the defaults); an unset `nonbonded_method` or `nonbonded_cutoff_nm` is the force field's (`NoCutoff` for a frame without a periodic box).	`None`
`pdb_filename`	`str`	Name for the PDB coordinate file.	`'system.pdb'`
`ff_filename`	`str`	Name for the XML force field file.	`'forcefield.xml'`
`script_filename`	`str`	Name for the Python simulation script.	`'simulate.py'`

Returns:

Type	Description
`dict[str, Path]`	`{"input", "pdb", "forcefield"}` mapped to the written paths;
`dict[str, Path]`	`"input"` is the simulation script :meth:`run` takes.

Raises:

Type	Description
`ValueError`	If the frame has no periodic box and simulation asks for a periodic method (`CutoffPeriodic`, `PME`, `Ewald`) or `NPT`; before any file is written.

OpenmmSimulationConfig `dataclass` ¶

OpenmmSimulationConfig(
    ensemble="NVT",
    temperature=300.0,
    pressure=1.0,
    timestep_fs=2.0,
    n_steps=500000,
    nonbonded_method=None,
    nonbonded_cutoff_nm=None,
    constraints="HBonds",
    friction_per_ps=1.0,
    dcd_reporter_interval=1000,
    state_reporter_interval=1000,
    checkpoint_interval=10000,
    output_dcd="trajectory.dcd",
    output_log="simulation.log",
    output_chk="checkpoint.chk",
    output_pdb="minimized.pdb",
    minimize_tolerance=10.0,
    minimize_max_iterations=1000,
    barostat_frequency=25,
    platform="CUDA",
)

Configuration for an OpenMM simulation.

All fields have physical units encoded in their names. The object round-trips through JSON via :meth:to_json / :meth:from_json.

Attributes:

Name	Type	Description
`ensemble`	`Ensemble`	Simulation ensemble (case-sensitive). `"NVT"` and `"NPT"` use a `LangevinMiddleIntegrator` (NPT adds a `MonteCarloBarostat`); `"NVE"` uses a `VerletIntegrator` and starts from velocities drawn at temperature; `"minimize"` only minimises the energy and writes the minimised coordinates to output_pdb.
`temperature`	`float`	Temperature in Kelvin (the thermostat's, or NVE's initial velocities').
`pressure`	`float`	Pressure in bar (NPT only; a periodic frame only).
`timestep_fs`	`float`	Integration timestep in femtoseconds.
`n_steps`	`int`	Number of MD steps.
`nonbonded_method`	`NonbondedMethod \| None`	Nonbonded treatment, by its `openmm.app` name: `"NoCutoff"`, `"CutoffNonPeriodic"`, `"CutoffPeriodic"`, `"PME"` or `"Ewald"`. `None` (the default) is the force field's for a periodic frame: `PME` for a long-range Coulomb style (`coul/long/pme`), `CutoffPeriodic` for a truncated one (OpenMM's cutoff methods add a reaction field), `PME` when it states none; and `NoCutoff` for a frame without a periodic box, for which the periodic methods are refused.
`nonbonded_cutoff_nm`	`float \| None`	Nonbonded cutoff radius in nanometres. `None` (the default) is the force field's: its Coulomb style's `cutoff`, else its other pair styles', else 1.0 nm.
`constraints`	`Constraints`	Constraint scheme — `"HBonds"`, `"AllBonds"`, `"HAngles"`, or the string `"None"` for no constraints.
`friction_per_ps`	`float`	Langevin friction coefficient in ps⁻¹ (NVT, NPT).
`dcd_reporter_interval`	`int`	Steps between DCD trajectory frames.
`state_reporter_interval`	`int`	Steps between log lines.
`checkpoint_interval`	`int`	Steps between checkpoint saves.
`output_dcd`	`str`	Filename for the DCD trajectory.
`output_log`	`str`	Filename for the state-data log.
`output_chk`	`str`	Filename for checkpoint files.
`output_pdb`	`str`	Filename for the minimised coordinates (`"minimize"`).
`minimize_tolerance`	`float`	Energy minimisation tolerance in kJ mol⁻¹ nm⁻¹.
`minimize_max_iterations`	`int`	Maximum minimisation iterations.
`barostat_frequency`	`int`	MC barostat move frequency in steps (NPT only).
`platform`	`str`	OpenMM platform name (`"CUDA"`, `"OpenCL"`, `"CPU"`).

Raises:

Type	Description
`ValueError`	If ensemble, nonbonded_method or constraints is not one of the values listed above (also from :meth:`from_dict` and :meth:`from_json`).

from_dict `classmethod` ¶

from_dict(data)

Construct a config from a plain dictionary.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	Dict as returned by :meth:`to_dict`.	required

Returns:

Name	Type	Description
`New`	`'OpenmmSimulationConfig'`	class:`OpenmmSimulationConfig` instance.

Raises:

Type	Description
`ValueError`	If a choice field holds an unknown value.

from_json `classmethod` ¶

from_json(path)

Load a configuration from a JSON file.

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	Path to a JSON file previously written by :meth:`to_json`.	required

Returns:

Name	Type	Description
`New`	`'OpenmmSimulationConfig'`	class:`OpenmmSimulationConfig` instance.

Raises:

Type	Description
`FileNotFoundError`	If path does not exist.
`ValueError`	If a choice field holds an unknown value.

to_dict ¶

to_dict()

Return a JSON-serialisable dictionary of all fields.

Returns:

Type	Description
`dict[str, Any]`	Plain dict with field names as keys and Python scalars as values.

to_json ¶

to_json(path)

Write the configuration to a JSON file.

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	Destination file path (created or overwritten).	required

Raises:

Type	Description
`OSError`	If the file cannot be written.

Engine¶

Quick reference¶

Key behavior¶

Related¶

Full API¶

Base¶

Engine ¶

run ¶

CP2K¶

Cp2kEngine ¶

LAMMPS¶

LammpsEngine ¶

generate_inputs ¶

md ¶

minimize ¶

GROMACS¶

GromacsEngine ¶

generate_inputs ¶

run ¶

Script¶

Script dataclass ¶

from_path classmethod ¶

from_text classmethod ¶

preview ¶

save ¶

OpenMM¶

OpenmmEngine ¶

paths["input"] (simulate.py), paths["pdb"], paths["forcefield"]¶

generate_inputs ¶

OpenmmSimulationConfig dataclass ¶

from_dict classmethod ¶

from_json classmethod ¶

to_dict ¶

to_json ¶

Script `dataclass` ¶

from_path `classmethod` ¶

from_text `classmethod` ¶

OpenmmSimulationConfig `dataclass` ¶

from_dict `classmethod` ¶

from_json `classmethod` ¶