mchem

Core

CLI entry point: convert PDB to SQLite DB, solvate PDB, etc.

System of force terms and particles; load/save from SQLite DB.

class mchem.system.Box(a: float, b: float, c: float, alpha: float, beta: float, gamma: float)

Bases: object

Periodic box dimensions from PDB CRYST1: cell lengths a, b, c (Angstroms) and angles alpha, beta, gamma (degrees).

a: float

b: float

c: float

alpha: float

beta: float

gamma: float

__init__(a: float, b: float, c: float, alpha: float, beta: float, gamma: float) → None

mchem.system.register_term_class(cls)

Register a custom term dataclass so it can be deserialized from a database file. Call this before loading a .db that contains the class.

class mchem.system.System(path: PathLike | None = None)

Bases: object

Container for force-field terms and metadata, backed by SQLite.

Terms are stored by table name (e.g. Particle, AmoebaBond). Metadata is stored in a separate meta table. Use register_term_class() to register custom term dataclasses before loading a DB that contains them.

__init__(path: PathLike | None = None)

Create an empty system or load from an existing SQLite DB.

Parameters:

path (os.PathLike, optional) – If given, path to SQLite file to load; otherwise an empty system.

__getitem__(key: str)

Return the term list for the given table name.

property data

Mapping of table name to TermList of terms.

property meta

Mapping of metadata keys to values (e.g. name, units).

fromDatabase()

Load all tables from the connected SQLite database into data and meta.

getTableNames()

Return list of table names in the connected database.

getTermsByName(name: str) → TermList

Return the TermList for the given term table name.

addTerm(term, name: str | None = None)

Append a single term; use its class name as table name if name is not given.

addTerms(terms: TermList, name: str | None = None)

Append all terms from a TermList.

addMeta(key: str, value: Any)

Set a metadata key (hyphens in key are replaced with underscores).

save(path: PathLike, overwrite: bool = False)

Write meta and all term tables to a new SQLite file.

Parameters:

• path (os.PathLike) – Output DB path.

• overwrite (bool, optional) – If True, replace existing file; otherwise raise if file exists.

close()

Close the database connection.

Residue templates (atoms and bonds) loaded from XML; used for topology matching.

class mchem.template.ResidueTemplate(name: str, atoms: Dict[str, Dict[str, Any]], bonds: List[Dict[str, Any]], altNames: List[str] = [])

Bases: object

Template for a residue: atom names (with alternates) and bond list for matching.

__init__(name: str, atoms: Dict[str, Dict[str, Any]], bonds: List[Dict[str, Any]], altNames: List[str] = [])

Parameters:

• name (str) – Residue template name.

• atoms (dict) – Map atom name -> dict with altNames (and optionally atomType).

• bonds (list) – List of dicts with keys atom1, atom2, order.

• altNames (list, optional) – Alternative names for this template.

classmethod fromXMLData(data: Element)

Build a ResidueTemplate from an XML Residue element (name, Atom, Bond children).

setAtomType(atomName: str, atomType: str)

Set force-field atom type for the given atom name.

getAtomType(atomName: str)

Return force-field atom type for the given atom name.

getAtom(atomName: str) → dict

Return force-field atom info

mchem.template.loadTemplateDefinitions(fname: PathLike)

Load residue templates from an XML file and add them to TEMPLATES.

Parameters:

fname (os.PathLike) – Path to XML file containing Residue elements.

mchem.template.loadNamedTemplateDefinitions(ffname: str)

Molecular topology: residues, atoms, bonds, and connectivity.

class mchem.topology.Residue(name: str, number: int, chain: str = 'A', insertionCode: str = '')

Bases: object

A residue (e.g. amino acid) containing atoms and optional link to a Topology.

__init__(name: str, number: int, chain: str = 'A', insertionCode: str = '')

Parameters:

• name (str) – Residue name (e.g. "ALA").

• number (int) – Residue sequence number.

• chain (str, optional) – Chain identifier.

• insertionCode (str, optional) – PDB insertion code.

property name: str

setName(newName: str)

property stdName: str

setStdName(newName: str)

property topology

setTopology(topology)

hasTopology()

property idx: int

setIdx(newIdx: int)

addAtom(atom)

getAtomWithName(name: str)

removeAtom(atom)

property numAtoms

property atoms

matchTemplate(template: ResidueTemplate, stdResidueName: bool = True)

Match this residue to a template: align atom names (including alternates) and add template bonds to topology.

Parameters:

• template (ResidueTemplate) – Template to match (atom names and bonds).

• stdResidueName (bool, optional) – If True, set residue name to template name.

Returns:

True if match succeeded.

Return type:

bool

class mchem.topology.Atom(name: str, element: str)

Bases: object

An atom with element, position, optional residue/topology, bonds, and force-field type/class.

__init__(name: str, element: str)

Parameters:

• name (str) – Atom name (e.g. "CA").

• element (str) – Element symbol (key in ELEMENTS).

setPosition(pos)

property polarizationGroup

setPolarizationGroup(setOfAtoms)

addToPolarizationGroup(other)

property mass: float

property symbol: str

property atomicNum: int

property atomType

property atomClass

setAtomType(atype)

setAtomClass(aclass)

property parametrized

property name: str

setName(newname: str)

property idx: int

setIdx(newIdx: int)

property residue

hasResidue()

setResidue(residue: None | Residue)

property topology

hasTopology()

property bonds

generateNeighbors()

getNeighbors()

getHighOrderNeighbors(order: int)

generateTopologicalInfo(maxConnect: int)

property pathsToBondedAtoms

property bondedAtoms

getTopologicalInfo()

addBond(bond)

pruneBonds()

class mchem.topology.Bond(atom1: Atom, atom2: Atom, order: float)

Bases: object

A bond between two atoms with a bond order.

__init__(atom1: Atom, atom2: Atom, order: float)

Parameters:

• atom1 (Atom) – Bonded atoms.

• atom2 (Atom) – Bonded atoms.

• order (float) – Bond order (e.g. 1.0, 2.0).

hasTopology() → bool

mchem.topology.require_editable(func)

Decorator: raise if topology is not editable.

mchem.topology.require_noneditable(func)

Decorator: raise if topology is editable.

class mchem.topology.BondedAtoms(atoms: List[Atom])

Bases: object

Ordered list of bonded atoms, with hash/equality invariant under reversal (for undirected paths).

__init__(atoms: List[Atom])

Parameters:

atoms (List[Atom]) – Ordered sequence of bonded atoms.

extend(atoms)

class mchem.topology.Topology(name: str, maxConnect: int = 5)

Bases: object

Molecular topology: list of residues, bonds, and connectivity up to _maxConnect bonds.

__init__(name: str, maxConnect: int = 5)

Parameters:

• name (str) – Topology name (e.g. from PDB).

• maxConnect (int, optional) – Maximum bond connectivity distance for generating bonded-atom lists.

property editable

setEditable()

assignIndex()

pruneBonds()

property residues: List[Residue]

property numResidues

getResidueWithIdx(idx: int) → Residue

addResidue(*args, **kwargs)

insertResidue(*args, **kwargs)

removeResidue(*args, **kwargs)

property numAtoms

property numBonds

atoms() → Atom

getAtomWithIdx(idx: int) → Atom

addAtomToResidue(*args, **kwargs)

property bonds

addBond(*args, **kwargs)

property connTable

property bondedAtoms

generateTopologicalInfo()

matchTemplates()

processDisulfideBond()

property coordinates: ndarray

Solvation: add water and ions to a solute in a periodic box.

Uses Packmol as the external placement engine and computes box dimensions following OpenMM’s openmm.app.Modeller.addSolvent() conventions.

mchem.solvate.BoxShape

Allowed periodic box shapes.

alias of Literal[‘cube’, ‘dodecahedron’, ‘octahedron’]

mchem.solvate.solvate(topology: Topology, positions: ndarray, *, box_shape: Literal['cube', 'dodecahedron', 'octahedron'] = 'cube', buffer: float = 10.0, neutralize: bool = True, ionic_strength: float = 0.0, positive_ion: str = 'Na+', negative_ion: str = 'Cl-') → Tuple[Topology, ndarray, Tuple[ndarray, ndarray, ndarray]]

Solvate a solute with water and optional ions in a periodic box.

Parameters:

• topology (Topology) – Solute topology (no solvent).

• positions (np.ndarray) – Atom positions, shape (N, 3), in Angstroms.

• box_shape (BoxShape, optional) – Periodic box shape. Default is "cube".

• buffer (float, optional) – Minimum padding in Angstroms between solute and box edge. Default is 10.0.

• neutralize (bool, optional) – If True, add counterions to neutralize the system. Default is True.

• ionic_strength (float, optional) – Target ionic strength in mol/L. Default is 0.0.

• positive_ion (str, optional) – Positive ion type (e.g. "Na+"). Default is "Na+".

• negative_ion (str, optional) – Negative ion type (e.g. "Cl-"). Default is "Cl-".

Returns:

(topology, positions, box_vectors) where box_vectors is a tuple of three np.ndarray vectors.

Return type:

tuple

Raises:

• ValueError – If an unsupported ion type is given.

• RuntimeError – If Packmol fails.

Trajectory conversion utilities (an M-Chem analogue of gmx trjconv).

This module reads a topology (currently the SQLite .db format) together with an M-Chem HDF5 (QArchive) trajectory and writes selected frames to a molecular structure/trajectory file (currently PDB).

The design is intentionally modular so that additional topology formats (e.g. PDB), trajectory formats, and output formats (e.g. XTC) can be added by implementing the relevant abstract base class and registering it, without changing the trjconv() orchestrator.

Frame indexing

Frames use the trajectory’s native 1-based numbering (matching the HDF5 time_step groups). A frame index of -1 (or None) selects the last frame.

class mchem.trjconv.AtomInfo(idx: int, name: str, element: str, resnum: int, resname: str, chain: str = 'A')

Bases: object

Minimal per-atom metadata required to write a structure record.

Parameters:

• idx (int) – Zero-based atom index (matches the trajectory column order).

• name (str) – Atom name (e.g. "CA").

• element (str) – Element symbol.

• resnum (int) – Residue sequence number.

• resname (str) – Residue name.

• chain (str) – Chain identifier (single character).

idx: int

name: str

element: str

resnum: int

resname: str

chain: str = 'A'

__init__(idx: int, name: str, element: str, resnum: int, resname: str, chain: str = 'A') → None

class mchem.trjconv.Frame(index: int, coordinates: ndarray, box: Tuple[float, float, float] | None = None, time: float | None = None)

Bases: object

A single trajectory frame.

Parameters:

• index (int) – Native (1-based) frame index within the trajectory.

• coordinates (numpy.ndarray) – Cartesian coordinates in Angstroms, shape (natoms, 3).

• box (tuple of float, optional) – Orthorhombic cell lengths (a, b, c) in Angstroms, or None.

• time (float, optional) – Simulation time in picoseconds.

index: int

coordinates: ndarray

box: Tuple[float, float, float] | None = None

time: float | None = None

__init__(index: int, coordinates: ndarray, box: Tuple[float, float, float] | None = None, time: float | None = None) → None

class mchem.trjconv.TopologyProvider

Bases: ABC

Abstract source of per-atom metadata for writing structure records.

Subclasses expose an ordered list of AtomInfo whose order matches the atom/column order of the trajectory being converted.

abstract property atoms: List[AtomInfo]

Return the ordered list of AtomInfo.

property natoms: int

Number of atoms in the topology.

class mchem.trjconv.DBTopologyProvider(path: PathLike)

Bases: TopologyProvider

Topology provider backed by an M-Chem SQLite .db file.

Reads the Particle term table directly (see db_format), which keeps the provider lightweight and robust to auxiliary tables that are not needed to write structure records.

Parameters:

path (os.PathLike) – Path to the .db topology file.

__init__(path: PathLike)

property atoms: List[AtomInfo]

class mchem.trjconv.TrajectoryReader

Bases: ABC

Abstract random-access reader over trajectory frames.

Frames are addressed by native 1-based index. Iterating a reader yields Frame objects in ascending frame order.

abstract property n_frames: int

Total number of frames available.

abstract property frame_indices: List[int]

Sorted list of available (1-based) frame indices.

abstractmethod read_frame(index: int) → Frame

Read one frame.

Parameters:

index (int) – Native 1-based frame index. -1 selects the last frame.

Return type:

Frame

resolve_index(index: int | None) → int

Resolve None/-1 to the last frame; validate other values.

close() → None

Release any underlying resources (no-op by default).

class mchem.trjconv.HDF5TrajectoryReader(path: PathLike, job_id: int | None = None)

Bases: TrajectoryReader

Reader for M-Chem HDF5 (QArchive) trajectories.

The expected layout is:

job/{job_id}/molecular_dynamics/
    natoms
    time_step/{frame}/
        coordinates   [3, natoms]  (Angstrom)
        box            [3]          (Angstrom)
        time           scalar       (ps)

Coordinates are stored column-major as (3, natoms) and are transposed to (natoms, 3) on read.

Parameters:

• path (os.PathLike) – Path to the .h5 trajectory file.

• job_id (int, optional) – Job group to read. If None, the single available job is auto-detected.

__init__(path: PathLike, job_id: int | None = None)

property natoms: int

Number of atoms per frame as recorded in the trajectory.

property n_frames: int

property frame_indices: List[int]

read_frame(index: int) → Frame

close() → None

class mchem.trjconv.TrajectoryWriter

Bases: ABC

Abstract writer for one or more frames to an output file.

Use as a context manager so resources are flushed and closed. Multiple calls to write_frame() append successive models/frames.

abstractmethod write_frame(frame: Frame, atoms: Sequence[AtomInfo]) → None

Write a single Frame given the topology atoms.

close() → None

Finalize and close the output (no-op by default).

class mchem.trjconv.PDBTrajectoryWriter(path: PathLike)

Bases: TrajectoryWriter

Write frames as PDB records.

A single frame is written as a plain ATOM/HETATM block preceded by a CRYST1 record (when box information is available). When more than one frame is written, each is wrapped in MODEL/ENDMDL records, laying the groundwork for future multi-frame output.

Parameters:

path (os.PathLike) – Output PDB path.

__init__(path: PathLike)

write_frame(frame: Frame, atoms: Sequence[AtomInfo]) → None

close() → None

mchem.trjconv.trjconv(topology_path: PathLike, trajectory_path: PathLike, output_path: PathLike, frame: int | None = None) → Frame

Convert an M-Chem trajectory frame to a structure file.

Picks a topology provider, trajectory reader, and output writer based on file extensions, extracts the requested frame, and writes it out.

Parameters:

• topology_path (os.PathLike) – Topology file (currently .db).

• trajectory_path (os.PathLike) – M-Chem HDF5 trajectory (.h5/.hdf5).

• output_path (os.PathLike) – Output structure file (currently .pdb).

• frame (int, optional) – Native 1-based frame index. None or -1 selects the last frame.

Returns:

The frame that was written (with resolved index).

Return type:

Frame

Raises:

• ValueError – If a format is unsupported or the topology and trajectory atom counts do not match.

• IndexError – If the requested frame does not exist.

Physical constants and unit conversion factors for energy and length.

Periodic table data: element symbol, mass, and name.

class mchem.element.Element(atomicNum: int, symbol: str, mass: float, name: str)

Bases: object

Dataclass for a chemical element.

atomicNum

Atomic number.

Type:

int

symbol

Element symbol (e.g. 'C', 'H').

Type:

str

mass

Atomic mass in amu.

Type:

float

name

Full element name.

Type:

str

atomicNum: int

symbol: str

mass: float

name: str

__init__(atomicNum: int, symbol: str, mass: float, name: str) → None

Force field

Force field XML loading and term generation (see ForceField, Generator).

Force field definition from XML: atom types, residues, and force generators.

mchem.forcefield.base.str2float(string)

Convert string to float.

mchem.forcefield.base.str2int(string)

Convert string to int.

mchem.forcefield.base.float2str(number)

Format number for XML (float or scientific).

mchem.forcefield.base.str2bool(string)

Convert string to bool (True/False, case-insensitive).

mchem.forcefield.base.xmlele2str(xmlele: Element)

Serialize XML element to string (unicode, stripped).

class mchem.forcefield.base.AtomType(name: str, atomClass: str)

Bases: object

Force-field atom type with name and class.

name: str

atomClass: str

__init__(name: str, atomClass: str) → None

class mchem.forcefield.base.ForceField(*files)

Bases: object

Load and apply a force field from one or more XML files.

Parses AtomTypes, Residues, and force elements (e.g. AmoebaBondForce); uses Parsers to create generators that produce terms for a Topology.

__init__(*files)

Load force field from one or more XML files.

Parameters:

*files (str or os.PathLike) – XML paths; resolved via processFileNames() if not found.

atomTypes: Dict[str, AtomType]

atomClasses: Dict[str, List[AtomType]]

processFileNames(files)

Resolve file paths; search next to this module if not found. Returns list of paths.

property generators

List of force generators (one per force type from XML).

addGenerator(generator)

Append a force generator.

getGeneratorWithClass(generatorClass)

Return the first generator that is an instance of generatorClass, or None.

addGeneratorWithClass(generatorClass)

Get or create a generator of the given class and return it.

addAtomType(atomTypeElement: Element)

Register an atom type from an XML Type element (name, class).

loadAtomTypes()

Load all AtomTypes from parsed XML trees.

loadAtomTypeDefs()

Map residue atom names to atom types from Residues section (templates must exist).

loadForces()

Parse force elements using Parsers and register generators.

assignAtomTypes(topology: Topology)

Set atom type and class on each atom from residue templates.

findAtomTypes(element: Element, numAtoms: int)

Resolve type/class attributes to list of atom type name tuples (supports wildcards).

createSystem(topology: Topology, **kwargs)

Build a System with particles and all generator terms for the given topology.

getParameters(asJaxNumpy: bool = True)

updateParameters(param: Dict[str, Any])

Update each generator’s parameters from a dict keyed by generator class name.

exportAtomTypes()

Return XML string for AtomTypes section.

exportAtomTypeDefs()

Return XML string for Residues section (atom type defs).

save(path: PathLike)

Write force field XML to file (atom types, residue defs, all force sections).

class mchem.forcefield.base.Generator(ff: ForceField, paramFields: List[str] = [], raiseError: bool = True)

Bases: object

Base class for a force generator: holds parameters keyed by atom type/SMIRKS and creates terms for a topology.

__init__(ff: ForceField, paramFields: List[str] = [], raiseError: bool = True)

getMetadata(key: str)

setMetadata(key: str, value: Any)

property paramFields: List[str]

property numParameters: int

addParameterField(name: str)

checkParameter(paramDict: Dict[str, Any])

addParameterWithAtomTypes(typeOrtypes, paramDict: Dict[str, Any])

addParameterWithSmirks(smirks: str, paramDict: Dict[str, Any])

setParameterWithIdx(paramDict: Dict[str, Any], paramIdx: int)

getParameterIdxWithAtomType(typeQuery)

getParameterWithAtomType(typeQuery)

getParameterIdxWithSmirks(smirksQuery: str)

getParameterWithSmirks(smirksQuery: str)

getParameterWithIdx(idx: int)

getParameters(asJaxNumpy: bool = False)

updateParameters(param: Dict[str, Any])

createTerms(topology: Topology, **kwargs)

Build term list(s) for the given topology. Override in subclasses. Returns TermList or tuple of TermLists.

raise_exception(msg: str, raiseError: bool = True)

exportParameterToStr()

Force generators: create bonded/nonbonded terms from XML and topology.

class mchem.forcefield.generators.HarmonicBondGenerator(ff)

Bases: Generator

Generator for Harmonic Bonds

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addBond(bondElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.HarmonicAngleGenerator(ff)

Bases: Generator

Generator for Harmonic Angles

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addAngle(angleElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaBondGenerator(ff)

Bases: Generator

Generator for AMOEBA bond terms (quartic) from AmoebaBondForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addBond(bondElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaAngleGenerator(ff)

Bases: Generator

Generator for AMOEBA angle and in-plane angle terms from AmoebaAngleForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addAngle(angleElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaUreyBradleyGenerator(ff)

Bases: Generator

Generator for AMOEBA Urey-Bradley terms from AmoebaUreyBradleyForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addUreyBrad(ubElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.MultipoleGenerator(ff)

Bases: Generator

Generator for atomic multipoles from AmoebaMultipoleForce / MBUCBMultipoleForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

static setAxisType(kz: int, kx: int, ky: int)

addMultipole(mpoleElement: Element)

exportParameterToStr()

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.IsotropicPolarizationGenerator(ff)

Bases: Generator

Generator for isotropic polarizability terms from Polarize elements.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addPolarize(polarElement: Element)

setPolarizationGroup(topology: Topology)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmberNonbondedGenerator(ff)

Bases: Generator

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addAtom(nbElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaVdwGenerator(ff)

Bases: Generator

Generator for AMOEBA buffered 14-7 VdW terms from AmoebaVdwForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

exportParameterToStr()

addVdw(vdwElement: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaStretchBendGenerator(ff)

Bases: Generator

Generator for AMOEBA stretch-bend coupling from AmoebaStretchBendForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaOutOfPlaneBendGenerator(ff)

Bases: Generator

Generator for AMOEBA out-of-plane bend terms from AmoebaOutOfPlaneBendForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addOutofPlaneBend(ele: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaPiTorsionGenerator(ff)

Bases: Generator

Generator for AMOEBA pi-torsion terms from AmoebaPiTorsionForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addPiTorsion(ele: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.PeriodicTorsionGenerator(ff)

Bases: Generator

Generator for periodic proper torsions from PeriodicTorsionForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addProperTorsion(ele: Element)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AmoebaTorsionTorsionGenerator(ff)

Bases: Generator

Generator for AMOEBA torsion-torsion (5-atom) terms and grids from AmoebaTorsionTorsionForce XML.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.AnisotropicPolarizationGenerator(ff)

Bases: Generator

Generator for anisotropic polarizability from Polarize elements (MBUCB).

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addPolarize(polarElement: Element)

exportParameterToStr()

setPolarizationGroup(topology: Topology)

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.MBUCBChargePenetrationGenerator(ff)

Bases: Generator

Generator for MBUCB charge-penetration terms from ChargePenetration elements.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addTerm(element: Element)

exportParameterToStr()

createTerms(topology: Topology, **kwargs)

class mchem.forcefield.generators.MBUCBChargeTransferGenerator(ff)

Bases: Generator

Generator for MBUCB charge-transfer terms from ChargeTransfer elements.

__init__(ff)

static parseElement(element: Element, ff: ForceField)

addTerm(element: Element)

exportParameterToStr()

createTerms(topology: Topology, **kwargs)

Terms

Force term dataclasses and TermList (bonded, nonbonded).

Base container for force-term lists keyed by term class.

class mchem.terms.base.TermList(cls)

Bases: list

List of force terms restricted to a single dataclass type.

Used by mchem.system.System to store terms per table (e.g. AmoebaBond).

__init__(cls)

Parameters:

cls (type) – Dataclass type; only instances of this type can be appended.

property cls

Term dataclass type for this list.

append(item)

Append a term; must be an instance of cls.

Bonded force terms: bonds, angles, Urey-Bradley, torsions, CMAP, AMOEBA-specific.

class mchem.terms.bonded.HarmonicBond(p0: int, p1: int, b0: float, kb: float, paramIdx: int = -1)

Bases: object

Class for a bond with normal harmonic potential

p0: int

p1: int

b0: float

kb: float

paramIdx: int = -1

__init__(p0: int, p1: int, b0: float, kb: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaBond(p0: int, p1: int, b0: float, kb: float, cubic: float, quartic: float, paramIdx: int = -1)

Bases: object

Class for a bond in AMOEBA force field, i.e. up to quartic polynomials

p0: int

p1: int

b0: float

kb: float

cubic: float

quartic: float

paramIdx: int = -1

__init__(p0: int, p1: int, b0: float, kb: float, cubic: float, quartic: float, paramIdx: int = -1) → None

class mchem.terms.bonded.HarmonicAngle(p0: int, p1: int, p2: int, th0: float, kth: float, paramIdx: int = -1)

Bases: object

Class for an angle with harmonic potential

p0: int

p1: int

p2: int

th0: float

kth: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, th0: float, kth: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaAngle(p0: int, p1: int, p2: int, th0: float, kth: float, cubic: float, quartic: float, pentic: float, sextic: float, paramIdx: int = -1)

Bases: object

Class for an angle in AMOEBA force field (up to sextic polynomials)

p0: int

p1: int

p2: int

th0: float

kth: float

cubic: float

quartic: float

pentic: float

sextic: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, th0: float, kth: float, cubic: float, quartic: float, pentic: float, sextic: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaAngleInPlane(p0: int, p1: int, p2: int, p3: int, th0: float, kth: float, cubic: float, quartic: float, pentic: float, sextic: float, paramIdx: int = -1)

Bases: object

Class for an in-plane angle in AMOEBA force field (up to sextic polynomials)

p0: int

p1: int

p2: int

p3: int

th0: float

kth: float

cubic: float

quartic: float

pentic: float

sextic: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, p3: int, th0: float, kth: float, cubic: float, quartic: float, pentic: float, sextic: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaStretchBend(p0: int, p1: int, p2: int, th0: float, b01: float, b02: float, kb1: float, kb2: float, paramIdx: int = -1)

Bases: object

Class for stretch-bend coupling term in AMOEBA force field

p0: int

p1: int

p2: int

th0: float

b01: float

b02: float

kb1: float

kb2: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, th0: float, b01: float, b02: float, kb1: float, kb2: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaUreyBradley(p0: int, p1: int, p2: int, r0: float, fc: float, paramIdx: int = -1)

Bases: object

Class for Urey-Bradley term used in AMOEBA force field

p0: int

p1: int

p2: int

r0: float

fc: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, r0: float, fc: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaOutOfPlaneBend(p0: int, p1: int, p2: int, p3: int, fc: float, paramIdx: int = -1)

Bases: object

Class for out-of-plane bending term in AMOEBA force field

p0: int

p1: int

p2: int

p3: int

fc: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, p3: int, fc: float, paramIdx: int = -1) → None

class mchem.terms.bonded.PeriodicTorsion(p0: int, p1: int, p2: int, p3: int, phase1: float, phase2: float, phase3: float, phase4: float, phase5: float, phase6: float, k1: float, k2: float, k3: float, k4: float, k5: float, k6: float, paramIdx: int = -1)

Bases: object

Periodic torsion (dihedral) term with up to six Fourier components.

p0: int

p1: int

p2: int

p3: int

phase1: float

phase2: float

phase3: float

phase4: float

phase5: float

phase6: float

k1: float

k2: float

k3: float

k4: float

k5: float

k6: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, p3: int, phase1: float, phase2: float, phase3: float, phase4: float, phase5: float, phase6: float, k1: float, k2: float, k3: float, k4: float, k5: float, k6: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaStretchTorsion(p0: int, p1: int, p2: int, p3: int, k11: float, k12: float, k13: float, k21: float, k22: float, k23: float, k31: float, k32: float, k33: float, b01: float, b02: float, b03: float, phi01: float, phi02: float, phi03: float)

Bases: object

Class for AMOEBA stretch-torsion coupling term

p0: int

p1: int

p2: int

p3: int

k11: float

k12: float

k13: float

k21: float

k22: float

k23: float

k31: float

k32: float

k33: float

b01: float

b02: float

b03: float

phi01: float

phi02: float

phi03: float

__init__(p0: int, p1: int, p2: int, p3: int, k11: float, k12: float, k13: float, k21: float, k22: float, k23: float, k31: float, k32: float, k33: float, b01: float, b02: float, b03: float, phi01: float, phi02: float, phi03: float) → None

class mchem.terms.bonded.AmoebaAngleTorsion(p0: int, p1: int, p2: int, p3: int, k11: float, k12: float, k13: float, k21: float, k22: float, k23: float, th01: float, th02: float, phi01: float, phi02: float, phi03: float, paramIdx: int = -1)

Bases: object

Class for AMOEBA angle-torsion coupling term

p0: int

p1: int

p2: int

p3: int

k11: float

k12: float

k13: float

k21: float

k22: float

k23: float

th01: float

th02: float

phi01: float

phi02: float

phi03: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, p3: int, k11: float, k12: float, k13: float, k21: float, k22: float, k23: float, th01: float, th02: float, phi01: float, phi02: float, phi03: float, paramIdx: int = -1) → None

class mchem.terms.bonded.AmoebaPiTorsion(p0: int, p1: int, p2: int, p3: int, p4: int, p5: int, k: float, paramIdx: int = -1)

Bases: object

Class for pi-torsion term in Amoeba

p0: int

p1: int

p2: int

p3: int

p4: int

p5: int

k: float

paramIdx: int = -1

__init__(p0: int, p1: int, p2: int, p3: int, p4: int, p5: int, k: float, paramIdx: int = -1) → None

class mchem.terms.bonded.CMAPTable(phi: float, psi: float, ene: float, paramIdx: int = -1)

Bases: object

Class for a CMAP tabulated torsion-torsion coupling term

phi: float

psi: float

ene: float

paramIdx: int = -1

__init__(phi: float, psi: float, ene: float, paramIdx: int = -1) → None

class mchem.terms.bonded.CMAP(cmap: int, p0: int, p1: int, p2: int, p3: int, p4: int, p5: int, p6: int, p7: int)

Bases: object

Class for CMAP torsion-torsion coupling term

cmap: int

p0: int

p1: int

p2: int

p3: int

p4: int

p5: int

p6: int

p7: int

__init__(cmap: int, p0: int, p1: int, p2: int, p3: int, p4: int, p5: int, p6: int, p7: int) → None

class mchem.terms.bonded.AmoebaTorsionTorsionGrid(angle1: float, angle2: float, f: float, gridIdx: int)

Bases: object

Class for an AMOEBA torsion-torsion 2D energy grid point

angle1: float

angle2: float

f: float

gridIdx: int

__init__(angle1: float, angle2: float, f: float, gridIdx: int) → None

class mchem.terms.bonded.AmoebaTorsionTorsion(p0: int, p1: int, p2: int, p3: int, p4: int, gridIdx: int, nx: int, ny: int)

Bases: object

Class for an AMOEBA torsion-torsion coupling term (5-atom chain)

p0: int

p1: int

p2: int

p3: int

p4: int

gridIdx: int

nx: int

ny: int

__init__(p0: int, p1: int, p2: int, p3: int, p4: int, gridIdx: int, nx: int, ny: int) → None

Non-bonded terms: particles, VdW, multipoles, polarization, MBUCB.

class mchem.terms.nonbonded.MultipoleAxisType(value)

Bases: Enum

Axis convention for multipole frame (ZThenX, Bisector, ZOnly, etc.).

ZThenX = 0

Bisector = 1

ZBisect = 2

ThreeFold = 3

ZOnly = 4

NoAxisType = 5

LastAxisTypeIndex = 6

class mchem.terms.nonbonded.Particle(idx: int, name: str, element: str, mass: float, resnum: int, resname: str, xx: float, xy: float, xz: float, vx: float = 0.0, vy: float = 0.0, vz: float = 0.0)

Bases: object

Single particle: index, name, element, mass, residue info, position, optional velocity.

idx: int

name: str

element: str

mass: float

resnum: int

resname: str

xx: float

xy: float

xz: float

vx: float = 0.0

vy: float = 0.0

vz: float = 0.0

__init__(idx: int, name: str, element: str, mass: float, resnum: int, resname: str, xx: float, xy: float, xz: float, vx: float = 0.0, vy: float = 0.0, vz: float = 0.0) → None

class mchem.terms.nonbonded.AmoebaVdw147(idx: int, epsilon: float, sigma: float, parentIdx: int = -1, reduction: float = 1.0, paramIdx: int = -1)

Bases: object

AMOEBA buffered 14-7 VdW parameters (epsilon, sigma, reduction, optional parent).

idx: int

epsilon: float

sigma: float

parentIdx: int = -1

reduction: float = 1.0

paramIdx: int = -1

__init__(idx: int, epsilon: float, sigma: float, parentIdx: int = -1, reduction: float = 1.0, paramIdx: int = -1) → None

class mchem.terms.nonbonded.AmberNonbonded(idx: int, charge: float, epsilon: float, sigma: float, paramIdx: int = -1)

Bases: object

AMBER Nonbonded parameters

idx: int

charge: float

epsilon: float

sigma: float

paramIdx: int = -1

__init__(idx: int, charge: float, epsilon: float, sigma: float, paramIdx: int = -1) → None

class mchem.terms.nonbonded.Multipole(idx: int, c0: float, dx: float, dy: float, dz: float, qxx: float, qxy: float, qxz: float, qyy: float, qyz: float, qzz: float, axistype: int, kz: int = -1, kx: int = -1, ky: int = -1, paramIdx: int = -1)

Bases: object

Atomic multipole (charge, dipole, quadrupole) and axis type / frame indices.

idx: int

c0: float

dx: float

dy: float

dz: float

qxx: float

qxy: float

qxz: float

qyy: float

qyz: float

qzz: float

axistype: int

kz: int = -1

kx: int = -1

ky: int = -1

paramIdx: int = -1

__init__(idx: int, c0: float, dx: float, dy: float, dz: float, qxx: float, qxy: float, qxz: float, qyy: float, qyz: float, qzz: float, axistype: int, kz: int = -1, kx: int = -1, ky: int = -1, paramIdx: int = -1) → None

class mchem.terms.nonbonded.IsotropicPolarization(idx: int, alpha: float, thole: float, grp: list, paramIdx: int = -1)

Bases: object

Isotropic polarizability (alpha, thole) and polarization group indices.

idx: int

alpha: float

thole: float

grp: list

paramIdx: int = -1

__init__(idx: int, alpha: float, thole: float, grp: list, paramIdx: int = -1) → None

class mchem.terms.nonbonded.AnisotropicPolarization(idx: int, alphaxx: float, alphaxy: float, alphaxz: float, alphayy: float, alphayz: float, alphazz: float, thole: float, grp: list = <factory>, paramIdx: int = -1)

Bases: object

Anisotropic polarizability tensor (alpha_xx, alpha_xy, …) and thole/group.

idx: int

alphaxx: float

alphaxy: float

alphaxz: float

alphayy: float

alphayz: float

alphazz: float

thole: float

grp: list

paramIdx: int = -1

__init__(idx: int, alphaxx: float, alphaxy: float, alphaxz: float, alphayy: float, alphayz: float, alphazz: float, thole: float, grp: list = <factory>, paramIdx: int = -1) → None

class mchem.terms.nonbonded.MBUCBChargePenetration(idx: int, z: float, alpha: float, beta: float, paramIdx: int = -1)

Bases: object

MBUCB charge-penetration correction parameters (z, alpha, beta).

idx: int

z: float

alpha: float

beta: float

paramIdx: int = -1

__init__(idx: int, z: float, alpha: float, beta: float, paramIdx: int = -1) → None

class mchem.terms.nonbonded.MBUCBChargeTransfer(idx: int, d: float, b: float, alpha: float, paramIdx: int = -1)

Bases: object

MBUCB charge-transfer parameters (d, b, alpha).

idx: int

d: float

b: float

alpha: float

paramIdx: int = -1

__init__(idx: int, d: float, b: float, alpha: float, paramIdx: int = -1) → None

class mchem.terms.nonbonded.PairList(p0: int, p1: int)

Bases: object

Class for atom pairs that has to specially treated in non-bonded calculations

p0: int

p1: int

energy() → float

__init__(p0: int, p1: int) → None

File formats

File format loaders (e.g. PDB) that produce mchem.topology.Topology.

PDB file I/O: read/write Topology from/to ATOM/HETATM records.

mchem.fileformats.pdb.read_pdb_box(fname: PathLike) → Tuple[float, float, float, float, float, float] | None

Read periodic box dimensions from the first CRYST1 record in a PDB file.

Parameters:

fname (os.PathLike) – Path to the PDB file.

Returns:

Cell lengths a, b, c in Angstroms and angles alpha, beta, gamma in degrees. None if no CRYST1 record is present.

Return type:

tuple of (a, b, c, alpha, beta, gamma) or None

mchem.fileformats.pdb.load_pdb(fname: PathLike) → Topology

Load a topology from a PDB file (ATOM/HETATM), match residue templates, and return editable topology.

Parameters:

fname (os.PathLike) – Path to the PDB file.

Returns:

Topology with residues and atoms; templates are matched so bonds and standard names are set.

Return type:

Topology

mchem.fileformats.pdb.format_cryst1_record(a: float, b: float, c: float, alpha: float, beta: float, gamma: float) → str

Format a PDB CRYST1 record from cell lengths and angles.

Parameters:

• a (float) – Cell lengths in Angstroms.

• b (float) – Cell lengths in Angstroms.

• c (float) – Cell lengths in Angstroms.

• alpha (float) – Cell angles in degrees.

• beta (float) – Cell angles in degrees.

• gamma (float) – Cell angles in degrees.

Returns:

A single CRYST1 line terminated by a newline.

Return type:

str

mchem.fileformats.pdb.format_atom_record(serial: int, name: str, resname: str, chain: str, resnum: int, x: float, y: float, z: float, symbol: str, hetatm: bool | None = None) → str

Format a single PDB ATOM/HETATM record.

Parameters:

• serial (int) – Atom serial number (1-based).

• name (str) – Atom name.

• resname (str) – Residue name.

• chain (str) – Chain identifier (single character).

• resnum (int) – Residue sequence number.

• x (float) – Cartesian coordinates in Angstroms.

• y (float) – Cartesian coordinates in Angstroms.

• z (float) – Cartesian coordinates in Angstroms.

• symbol (str) – Element symbol.

• hetatm (bool, optional) – Force HETATM (True) or ATOM (False). If None, decide from _HETATM_RESIDUES based on resname.

Returns:

A single record line terminated by a newline.

Return type:

str

mchem.fileformats.pdb.write_pdb(fname: PathLike, topology: Topology, positions: ndarray, box_vectors: Tuple[ndarray, ndarray, ndarray] | None = None) → None

Write a PDB file from a topology and positions.

Parameters:

• fname (os.PathLike) – Output PDB file path.

• topology (Topology) – Molecular topology.

• positions (np.ndarray) – Atom positions, shape (N, 3), in Angstroms.

• box_vectors (tuple of np.ndarray, optional) – Three box vectors (v1, v2, v3). If provided, a CRYST1 record is written at the top of the file.