Force field¶

The forcefield section holds the parameters that define the energy model of the record's particles: atom types, bonded and non-bonded styles, their per-type tables, the unit system those numbers are in, and the 1-2 / 1-3 / 1-4 scaling. It is a peer of meta, system and trajectory at the root. How a job used the model (engine, cutoff schedule, thermostat) is method; which particle carries which type is system.

forcefield is frame-shaped: a JSON document stored as the group's attributes, plus one block per style. A reader that knows nothing of force fields reads it with the frame codec and loses nothing.

forcefield
 +-- name: string[]
 +-- units
 |    +-- (preset: string[])
 |    +-- (length | energy | angle | charge | mass | time: string[])
 +-- (source)
 |    +-- format: string[]
 |    +-- (uri: string[])
 |    +-- (sha256: string[])
 +-- (special_bonds)
 |    +-- lj: f64[3]
 |    +-- coul: f64[3]
 +-- styles: [{category, style, (params), (expression), (endpoint_key)}, ...]
 \-- <category>.<style>             one block per entry of styles
      \-- name: string[T]
      \-- (itom | jtom | ktom | ltom | mtom: string[T])
      \-- (<annotation>: string[T])
      \-- (<param>: f64[T] | string[T])
      \-- (grid: f64[T, N, N])          a cmap table only
      \-- (_validity)

A record whose only substantive section is forcefield is valid: it is a force-field package.

The document¶

The group's attribute map is exactly the force-field document. Keys other than those below are preserved by every reader.

name

Required. The force field's name ("OPLS-AA", "GAFF2", "openff-2.1.0").

units

Required. The unit of every number in the section, by quantity. Every parameter in a style table and every style-level parameter is a number in these units, and a reader MUST NOT convert it on read. A writer that translates a file states the file's own units here rather than converting, except where one quantity is mixed inside the source (a degree angle beside a per-radian force constant): it then converts that quantity to one unit and states that unit.

A unit string is parseable by pint. A derived dimension (a bond force constant, energy/length²) is composed from these; it has no key of its own.

preset names a unit system instead of listing it. The presets are:

The names are those of the LAMMPS units command, but the angle is a radian in every preset: a LAMMPS input file's degrees are an input convention, not the unit system. lj is reduced units: no quantity but angle has a unit, and the numbers are in the reduced scale of the producer's choosing.

units MUST carry preset or at least one quantity. When both a preset and a quantity are present they MUST agree (pint-equivalent strings); a reader refuses a document where they do not. A style whose parameters need a quantity that units does not resolve is not refused on read; a validator SHOULD report it.

source

Optional provenance of the parameters: format ("openmm-xml", "offxml", "gromacs-top", "lammps", "amber-frcmod", …), uri, and sha256 (64 lowercase hex digits) of the source file's bytes.

special_bonds

Optional. The scale applied to non-bonded interactions between atoms that are 1-2, 1-3 and 1-4 neighbours through bonds: lj for the van-der-Waals styles, coul for the electrostatic ones, each [w12, w13, w14]. 0 excludes the class, 1 leaves it at full strength. Pairs further apart are at full strength. Absent means the force field declares no weights; a consumer supplies its own default and SHOULD say so. Which weight set a pair style takes is its registry entry's special class (Style registry).

styles

Required (it may be empty). An ordered list; each entry is one style:

A (category, style) pair appears at most once. Order is preserved; it carries no physical meaning. Every entry has exactly one table, at the block name below, even when the table has no rows.

Two style-level parameter names are reserved on pair styles. params.special ("lj" or "coul") gives an unregistered pair style its special class. params.mixing on a van-der-Waals pair style is its combining rule: arithmetic (Lorentz–Berthelot: σ = ½(σᵢ+σⱼ), ε = √(εᵢεⱼ)), geometric (σ = √(σᵢσⱼ), ε = √(εᵢεⱼ)) or sixthpower (σ⁶ = ½(σᵢ⁶+σⱼ⁶), ε = 2√(εᵢεⱼ)σᵢ³σⱼ³/(σᵢ⁶+σⱼ⁶)). Absent means the style declares none.

Style tables¶

Block name¶

A style's table is the block named

<category> "." <encoded style>

where the encoded style is the style's UTF-8 bytes with every byte outside A–Z a–z 0–9 - _ written as % and two uppercase hex digits. So bond/harmonic lives at bond.harmonic and pair/lj/cut/coul/long at pair.lj%2Fcut%2Fcoul%2Flong. Decoding splits at the first . and percent-decodes the rest. A reader resolves a style's table by this name; a block whose name no style entry produces is preserved as unknown content.

Rows and columns¶

A table has one row per type. Its count is the number of types. It carries no structural shape.

name

Required, string, never null, unique within the table. The label a system row names (Linking a system). Any UTF-8 string; it is never parsed into endpoints.

itom, jtom, ktom, ltom, mtom

The endpoints, string, never null: the first arity of them, in this order, and no others (Categories). A pair row always carries both itom and jtom; a self pair has itom == jtom, and a row with itom ≠ jtom is a cross row (CHARMM NBFIX, AMBER off-diagonal ACOEF/BCOEF, GROMACS [ nonbond_params ]). Linking a system, rule 3, says what a cross row does and which pairs a table may restate.

Annotation columns, string, nullable:

Parameter columns: every other column is one parameter, named as the style names it (k, r0, epsilon, periodicity2), and is f64 or string. No other dtype is admitted, with one exception: a column whose name is a canonical key has that key's dtype, as it does in every block (atomic_number is u64). An integer-valued parameter that is not a canonical key (a periodicity) is an f64. A parameter a row does not have is null in that row (nullable columns), never a sentinel such as 0 or NaN. A column declares no precision: parameters are stored exactly. Every column of a table is one value per row ([T], no trailing axes), with one exception, grid on a cmap table (below); a style-level parameter is always a scalar.

An atom table additionally recognises mass (f64, units.mass), charge (f64, units.charge) and atomic_number (u64).

grid

On a cmap table only: the row's correction table, f64[T, N, N] — one N × N grid of energies (units.energy) per row, N ≥ 2, one N for every row of the table. The first trailing axis is φ, the dihedral itom–jtom–ktom–ltom; the second is ψ, the dihedral jtom–ktom–ltom–mtom; grid[a][b] is the correction at φ = −π + 2πa/N, ψ = −π + 2πb/N. It declares no precision, and every value of a row that is not null is finite. A reader MUST refuse a cmap grid of another dtype or shape (one trailing axis, a non-square N × M, N < 2), a non-finite value in a non-null row, and a column with trailing axes anywhere else: another column of a cmap table, a grid of another category, any column of an unknown category.

Endpoints¶

endpoint_key says what the endpoint strings name:

• "type": the name of a row of an atom table;
• "class": the class of a row of an atom table (OpenMM bonded forces key on classes). Every atom table MUST then carry class;
• "smirks": nothing. The table carries no endpoint columns; each row's smirks (required, never null) assigns it, and the arity is the number of mapped atoms in the pattern.

The empty string "" is the wildcard: it matches any type or class. GROMACS X, LAMMPS * and an absent OpenMM attribute become "".

When a consumer assigns rows to a topology by endpoints (typing, not linking), a row matches a tuple of atom types when its endpoints equal the tuple in order or reversed (an improper: in order only); among matching rows the one with the fewest wildcards wins, and among those the first in table order. A record that names its rows (Linking a system) needs none of this.

Categories¶

The system blocks are standardized identifiers. A category outside this table is legal and preserved; its arity is the number of endpoint columns its table carries, which MUST be a prefix of itom, jtom, ktom, ltom, mtom.

A pair14 row replaces, for a 1-4 pair of its two types, the parameters the same-named pair style would give it, and that pair's special_bonds 1-4 weight is then not applied on top.

Linking a system¶

Types are linked by name. Each rule below is how a reader finds the parameters of a system row:

1. atoms.type names a row of an atom table. A force field whose styles are all smirks-keyed has no atom table; atoms.type then names a row of its pair table.
2. A row of a relation block of category c (table above) names, in its type column, a row of a c table. If the block carries a style column (string), the row's table is <c>.<style>; otherwise every c table holding that name applies, and their energies add.
3. pair and pair14 tables are resolved through atom types, not row names: for atoms of types a and b, the row whose endpoints are {a, b}, in either order. A cross row (itom ≠ jtom) therefore gives its pair its own parameters and overrides the style's mixing for that pair; mixing prices only the pairs no row names. A pair table MUST NOT hold two rows with the same unordered {itom, jtom} and different parameters: rows restating a pair, in either order, with equal values in every parameter column (null equal only to null; name and the annotation columns are not parameters) are one row, and a reader MUST refuse a table whose restatements differ. A cross row's name means nothing beyond its uniqueness in the table: it is not parsed, not derived from the endpoints, and no system row names it. A writer translating into a format that has no form for a cross row MUST refuse the row rather than write it as a self row of either endpoint. Failing a row, a pair style uses its mixing of the two self rows {a, a} and {b, b}; a pair14 style gives nothing, and the pair keeps its scaled pair interaction. Every pair style of the force field applies to every non-excluded pair, scaled by special_bonds (lj or coul per the style's special class). The pairs block, where present, lists intramolecular pairs explicitly; its is_14 rows are the 1-4 pairs pair14 tables apply to.
4. A relation block may carry a parameter column named as its style names it. Its value, where not null, is that row's parameter and overrides the table; a style whose table has no rows takes every parameter from the relation (a per-instance style, as MMFF and UFF are).
5. type_id, where present, is a format-local ordinal and plays no part in linking.

A name that resolves to nothing is not a format error. A reader MUST NOT refuse a record for it; a validator SHOULD report it. Two pair rows that price one pair differently (rule 3) are a format error: the table cannot say which applies.

Style registry¶

A style named here MUST mean exactly this energy and these parameters. A style not named here SHOULD carry an expression; a reader preserves it either way. Dimensions: E energy, L length, A angle, 1 a pure number. φ is the signed dihedral, χ = |φ|, θ the angle at jtom, r the distance.

Special classes: pair.lj/cut, pair.lj/class2, pair.buck, pair.morse take special_bonds.lj; pair.coul/cut and pair.coul/long/pme take special_bonds.coul. An unregistered pair style takes lj unless its params.special is "coul". pair14 styles take no weight.

In virtual_site rows the constructed site is atomi of its virtual_sites row and x_j, x_k, x_l are the positions of atomj, atomk, atoml; r_jk = x_k − x_j.

The registry's conventions are the reference implementation's. Where a source format differs — LAMMPS bond_style harmonic is K·(r − r0)², so k = 2K — the translation is in Format mappings.

Expressions¶

expression is the style's energy as one formula in the syntax of OpenMM's custom forces (Lepton): + - * / ^, parentheses, exp log sqrt sin cos tan asin acos atan abs min max step delta select, numeric literals. Its free variables are the geometric variable of the category (r for bond, pair, pair14, constraint; theta for angle; phi for dihedral; chi for improper), the style's per-type and style-level parameter names, and, for pair styles, q1 and q2. Per-term sums are written out.

A reader MUST preserve expression byte for byte. It MAY evaluate it. An expression on a registered style MUST agree with the registry.

Collections¶

A collection carries at most one force field, shared by every record: atoms.type and every relation type in every record link into it. A record of a collection carries no forcefield of its own. The LMDB binding stores it under the key ff.

Format mappings¶

Informative. How the common sources map onto this section. "→" names the table and column a source item lands in; units are the source's own unless the row says otherwise.

OpenMM / foyer XML¶

units: length nm, energy kJ/mol, angle radian, charge e, mass dalton.

<NonbondedForce> holds one <Atom> row per type, so a pair.lj/cut cross row has no form there; OpenMM keeps pair overrides as <NBFixPair> rows of a <LennardJonesForce>, which this mapping does not cover yet. A writer refuses a cross row (Linking a system, rule 3): written as an <Atom> it would replace itom's own parameters. A reader that does not map <NBFixPair> refuses the file with an error naming it, or skips the <LennardJonesForce> with a diagnostic that says so; it never drops the overrides silently, which would leave each such pair at its mixed value.

OpenFF (SMIRNOFF .offxml)¶

Every value carries its unit in the file; a translator converts each into the declared units (commonly angstrom, kcal/mol, radian, e, dalton; angles convert from degrees because force constants are per radian²).

A system parameterized from it names rows by id: bonds.type = "b1", atoms.type = "n16".

GROMACS topology¶

units: length nm, energy kJ/mol, angle radian, charge e, mass dalton. GROMACS degrees (θ₀, φₛ) convert to radians.

LAMMPS coefficients¶

units.preset is the file's units style; angles convert from degrees to radians.

AMBER prmtop¶

units: length angstrom, energy kcal/mol, angle radian, charge e, mass dalton. A type name is the atom's AMBER_ATOM_TYPE; its LJ class is its ATOM_TYPE_INDEX.

Conformance¶

The force-field suite (module = "forcefield") pins down:

• ff-minimal: a name, units and one atom style round-trip;
• ff-round-trip: atom, bond, angle, multi-term dihedral, improper, two pair styles with mixing, special_bonds and source round-trip exactly;
• ff-wildcard-endpoints: "" endpoints survive;
• ff-absent-params: a parameter some rows lack is null there, not filled;
• ff-string-params: class, element, smarts and a non-canonical string parameter survive;
• ff-style-name-encoding: pair.lj%2Fcut%2Fcoul%2Flong resolves to lj/cut/coul/long;
• ff-pair-cross-rows: a cross row whose name is no endpoint spelling, and a reversed restatement of it with equal parameters, survive beside the self rows (that the row overrides mixing is an energy, which a format suite does not compute);
• ff-hybrid-styles: two bond styles, and a record whose bonds carry style;
• ff-per-instance-style: a style with no rows beside relation columns that carry its parameters;
• ff-unknown-style-with-expression and ff-unknown-category (a cross_term.example table): preserved verbatim;
• ff-cmap-grid: a cmap table's five endpoints and its f64[T, N, N] grid come back bit for bit;
• ff-units-preserved: nm / kJ/mol numbers come back unconverted;
• ff-lj-preset: preset lj with no quantity strings;
• ff-smirks-keyed: a smirks-keyed table with no endpoint columns;
• ff-without-special-bonds: absence survives as absence;
• ff-document-keys-preserved: a document key and a table no style names survive as unknown content;
• refusals on read: reject-ff-no-units, reject-ff-units-conflict, reject-ff-duplicate-style, reject-ff-missing-table, reject-ff-duplicate-type-name, reject-ff-wrong-arity, reject-ff-param-dtype, reject-ff-null-name, reject-ff-class-key-without-class, reject-ff-pair-conflict (B–A restating A–B with another epsilon), reject-ff-cmap-grid-shape (a non-square f64[T, 3, 4] grid), reject-ff-cmap-grid-nonfinite (a NaN in a non-null row), reject-ff-grid-outside-cmap (a grid with trailing axes on a bond table).

The record suite adds record-with-forcefield (a system whose atoms.type and bonds.type link into it) and forcefield-only-record; the collection suite adds collection-forcefield and collection-cmap (a cmap grid under the LMDB key ff, linked from cmaps rows).