xnn.ffnn.models.opls.OPLS#

class xnn.ffnn.models.opls.OPLS(ffield, topology, *, cutoff=10.0, switch_width=0.0, fudge_lj=None, fudge_qq=None, trainable=(), keep_intermediates=False, auto_impropers=True)[source]#

Bases: InteratomicPotential

The OPLS fixed-topology force field (all-atom or united-atom).

An instance binds a parameter library to one molecular topology: bonded terms, exclusions and scaled 1,4 pairs are resolved once at construction, and forward evaluates the full OPLS energy on any conformation (or batch of conformations) of that system. Forces and stress come from autograd via ForceStressOutput.

Parameters:

  • ffield (OPLSLibrary, OPLSForceField, str or Path) – The parameter library – a parsed OPLSLibrary, a variant shipped with xnn ("oplsaa", "oplsaa-1996", "lopls", "CL&P"), a .frc or native JSON path, or an existing OPLSForceField to share parameters with other models.

  • topology (MolecularTopology, str or Path) – The system’s topology (or a path to a topology JSON file).

  • cutoff (float, optional) – Nonbonded (Lennard-Jones / Coulomb) cutoff in Angstrom, and the model’s neighbor-list cutoff; by default 10.0. 1,4 pairs are independent of this cutoff.

  • switch_width (float, optional) – Width in Angstrom of a quintic switching function that takes the nonbonded interactions smoothly to zero at the cutoff; by default 0.0 (plain truncation).

  • fudge_lj (float, optional) – Override the library’s 1,4 scaling factors (both 0.5 for OPLS).

  • fudge_qq (float, optional) – Override the library’s 1,4 scaling factors (both 0.5 for OPLS).

  • trainable (sequence of str or "all", optional) – Trainable parameter groups, forwarded to OPLSForceField (ignored when ffield is already an OPLSForceField).

  • keep_intermediates (bool, optional) – If True, stash the intermediate tensors of the last evaluation (bond lengths, angles, dihedral cosines, per-interaction energies) in self.intermediates. Default False.

  • auto_impropers (bool, optional) – When the topology lists no impropers, place one improper at every three-connected atom whose classes match an improper_opls pattern of the library (the SEAMM convention; centers without a pattern get none). Default True. Explicitly listed impropers are always used as given.

Notes

forward returns, besides the standard node_energy / energy / node_features keys, the fixed partial charges (N,) and one per-structure tensor per term: e_bond, e_angle, e_torsion, e_improper, e_lj, e_coulomb, e_lj14, e_coulomb14. Every structure in a batch must have this topology’s atom count and element sequence (conformers of the bound system).

classmethod from_atoms(structure, ffield='oplsaa', *, charge=0, bonds=None, **kwargs)[source]#

Build an OPLS model for a structure, typing it with the library’s SMARTS templates.

Bonding is perceived from the coordinates (or taken from bonds), atom types are assigned by assign_atom_types(), and the topology is derived from the perceived bonds – so nothing about the force field’s own type names has to be known in advance.

Parameters:

  • structure (object) – An ase.Atoms, a (positions, atomic_numbers) pair, a dict with "pos" / "atomic_numbers", an RDKit molecule or a SMILES string.

  • ffield (OPLSLibrary, str or Path, optional) – The parameter library (must carry templates); default "oplsaa".

  • charge (int, optional) – Total charge of the structure (for bond-order perception).

  • bonds (sequence of (int, int), optional) – Known connectivity; bond orders are then perceived, not bonds.

  • **kwargs – Forwarded to the constructor (cutoff, trainable, …).

Returns:

The model, bound to the derived topology.

Return type:

OPLS

forward(data)[source]#

Evaluate the OPLS energy on a (batched) atomic graph.

Parameters:

data (AtomicGraph) – The batched graph; every structure must be a conformation of the bound topology (same atom count and element sequence), and the neighbor list must have been built with this model’s cutoff.

Returns:

node_energy (N,), energy (B,), charges (N,), node_features (N, 1) and the per-structure energy decomposition (see the class docstring).

Return type:

dict of str to Tensor

Raises:

ValueError – If a structure in the batch does not match the bound topology.

export_library()[source]#

Export the current parameters as an OPLSLibrary.

Returns:

See OPLSForceField.export_library().

Return type:

OPLSLibrary

property masses: Tensor#

Per-atom masses (u) of the bound topology.

Type:

Tensor

classmethod from_config(cfg)[source]#

Construct an OPLS model from a core model config.

Core field: cfg.cutoff is the nonbonded cutoff. Everything else is read from cfg.extra: library (required; a variant shipped with xnn such as oplsaa, a .frc path or a native JSON path) and either topology (path to a topology JSON file) or types + bonds (+ optional impropers / improper_keys) inline. Optional: switch_width, fudge_lj, fudge_qq, trainable. Alternative spellings used by other MD packages are translated by xnn.common.config.translate.

Parameters:

cfg (xnn.common.config.schema.ModelConfig) – The core model config.

Returns:

The model.

Return type:

OPLS

Raises:

ValueError – If the library or the topology specification is missing.