htmd.builder.openmm module#

OpenMM/OpenFF-based system builder for molecular dynamics.

Provides an alternative to the tleap-based AMBER builder, using OpenMM force fields for parameterization and OpenFF Interchange (or ParmEd) for AMBER prmtop/inpcrd export.

Dependencies (imported lazily at call time):

openmm, openmmforcefields, openff-toolkit, openff-interchange

htmd.builder.openmm.build(mol, ff=None, extra_xml=None, small_molecule_ff=None, molecules=None, prefix='structure', outdir='./build', caps=None, ionize=True, saltconc=0, saltanion=None, saltcation=None, disulfide=None, custombonds=None, solvate=True, padding=10.0, water_model='tip3p', boxsize=None, gbsa=False)#

Build a system using OpenMM force fields and export to AMBER format.

Parameters:

  • mol (Molecule) – The input molecular system.

  • ff (list of str, optional) – OpenMM XML force field file names (see openmm.app.ForceField). Default: defaultFf().

  • extra_xml (str or list of str, optional) – Paths to additional OpenMM XML files for non-standard residues.

  • small_molecule_ff (str, optional) – Small-molecule force field for the template generator, e.g. "gaff-2.2.20" or "openff-2.3.0". Requires molecules.

  • molecules (list, optional) – openff.toolkit.Molecule objects or paths to SDF files describing the small molecules present in the system.

  • prefix (str) – Prefix for output files.

  • outdir (str) – Output directory path.

  • caps (dict, optional) –

    Terminal capping specification. Accepts two formats:

    • {segid: [nterm_cap, cterm_cap]} — e.g. {"P": ["ACE","NME"]}

    • {atomsel: cap} — e.g. {"chain A and resid 5": "ACE"}

    Default: ACE/NME on every protein segment with >= 10 residues.

  • ionize (bool) – Neutralise the system (and add salt if saltconc > 0).

  • saltconc (float) – Salt concentration in molar, added on top of neutralisation.

  • saltanion (str, optional) – Anion type. Accepts "Cl-", "CL", "chloride" etc.

  • saltcation (str, optional) – Cation type. Accepts "Na+", "K+", "Cs+" and divalent "Mg2+", "Ca2+", "Zn2+".

  • disulfide (list of pairs of str, optional) – Manual disulfide bonds as pairs of atom-selection strings. None triggers automatic detection.

  • custombonds (list of pairs of str, optional) – Extra bonds as pairs of atom-selection strings.

  • solvate (bool) – Add explicit water via Modeller.addSolvent().

  • padding (float) – Box padding in Angstroms (used when solvate is True).

  • water_model (str) – Water model name for Modeller.addSolvent().

  • boxsize (float or list of float, optional) – Explicit box dimensions [x, y, z] in Angstroms. Overrides padding.

  • gbsa (bool) – Use GBSA implicit solvent (OBC2 model).

Returns:

  • molbuilt (Molecule) – The fully built system.

  • system (openmm.System) – The parameterised OpenMM System object.

htmd.builder.openmm.defaultFf()#

Returns the default OpenMM XML force field files.

The amber14/ prefix ships with OpenMM itself. If the openmmforcefields package is installed, force fields under the amber/ or amber19/ prefixes are also available.

Returns:

Force field XML file names loadable by openmm.app.ForceField.

Return type:

list of str

htmd.builder.openmm.parameterizeLigandsOpenFF(mol, ligand_ff='openff_unconstrained-2.3.0.offxml', charge_method='nagl', resnames=None)#

Parameterise free ligand residues via OpenFF Interchange.

Slices each ligand residue out of mol, assigns partial charges, applies the chosen SMIRNOFF force field via openff.interchange.Interchange.from_smirnoff(), and returns one Interchange per resname. The returned objects can be combined with other Interchanges via ic.combine(other) and exported to OpenMM via ic.to_openmm().

The default charge model is NAGL, which is the OpenFF-recommended fast surrogate for AM1-BCC (Sage 2.0-2.2) / AshGC (Sage 2.3.0). Using a different charge model logs a warning: Sage’s vdW + torsion parameters were fit alongside a specific charge model, so other charge choices give a thermodynamically inconsistent potential.

Mirrors the OpenFF protein-ligand tutorial pattern:

ligand_ic = Interchange.from_smirnoff(
    force_field=ForceField("openff_unconstrained-2.3.0.offxml"),
    topology=[ligand_offmol],
)
Parameters:

  • mol (moleculekit.molecule.Molecule) – Molecule containing one or more free ligand residues. Each ligand must already have explicit hydrogens and explicit integer bond orders, e.g. via moleculekit.molecule.Molecule.templateResidueFromSmiles().

  • ligand_ff (str, optional) – Name of an OpenFF force field offxml. The default "openff_unconstrained-2.3.0.offxml" is the right choice for openmm.build: the bond / angle / torsion / vdW / charge parameters are byte-identical to the constrained variant "openff-2.3.0.offxml" (per the OpenFF README: “Each mainline force field is currently available in two forms - both with and without bond constraints to hydrogen”), and openmm.build already applies constraints=app.HBonds at createSystem time so the X-H bonds are constrained at the simulator level. Pick the constrained variant only if the emitted XML will be consumed by a downstream tool that runs createSystem without passing constraints.

  • charge_method (str or None, optional) – "nagl" (default, recommended) - AM1-BCC-equivalent partial charges from the OpenFF NAGL graph neural network. Sage was fit alongside this charge model. Needs PyTorch. Other choices log a warning. "gasteiger" - RDKit PEOE. "resp" / "resp-multiconf" - RESP via parameterize + Psi4. None - let SMIRNOFF assign its own charges (e.g. AM1-BCC via ToolkitAM1BCCHandler).

  • resnames (list[str] or None, optional) – Subset of resnames to parameterise. None parameterises every unique resname in mol.

Returns:

One Interchange per resname.

Return type:

dict[str, openff.interchange.Interchange]