xnn.ffnn.models.dreiding.Dreiding#

class xnn.ffnn.models.dreiding.Dreiding(ffield='dreiding', topology=None, *, cutoff=10.0, switch_width=0.0, charges=None, bond_style='harmonic', angle_style='cosine', hbond=True, hbond_cutoff=None, hbond_angle=90.0, trainable=(), keep_intermediates=False)[source]#

Bases: InteratomicPotential

The DREIDING rule-generated force field, bound to one topology.

An instance binds the parameter library to one molecular topology: all valence terms are generated once at construction by the DREIDING rules (from the atom types, connectivity and bond orders), and forward evaluates the full energy on any conformation (or batch of conformations) of that system. Forces and stress come from autograd via ForceStressOutput.

Parameters:

  • ffield (DreidingLibrary, DreidingForceField, str or Path, optional) – The parameter library – "dreiding" (Lennard-Jones nonbonds, the default), "dreiding/X6" (exponential-6), a .frc or native JSON path, a parsed DreidingLibrary, or an existing DreidingForceField to share parameters with other models.

  • topology (MolecularTopology, str or Path) – The system’s topology (or a path to a topology JSON file). Its bond_orders drive the bond force constants and torsion rules; an empty list means all single bonds.

  • cutoff (float, optional) – Nonbonded (van der Waals / Coulomb) cutoff in Angstrom, and the model’s neighbor-list cutoff; by default 10.0.

  • 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).

  • charges (sequence of float, optional) – Per-atom partial charges in e (DREIDING prescribes none itself; the paper recommends Gasteiger charges where electrostatics matter, see from_atoms()). Default: no electrostatics.

  • bond_style (str, optional) – "harmonic" (default) or "morse" (the DREIDING/M variant).

  • angle_style (str, optional) – "cosine" (the harmonic-cosine default, eq 10) or "harmonic" (the theta form, eq 11). Linear centers always use eq 10’.

  • hbond (bool, optional) – Include the explicit hydrogen-bond term (eq 38) on donor triplets; default True (it vanishes without H__HB atoms).

  • hbond_cutoff (float, optional) – Donor-acceptor distance cutoff of the hydrogen-bond term, by default the nonbonded cutoff.

  • hbond_angle (float, optional) – Donor-hydrogen-acceptor angle cutoff in degrees (the term counts only angles beyond it); by default 90.0, the paper’s restriction.

  • trainable (sequence of str or "all", optional) – Trainable parameter groups, forwarded to DreidingForceField (ignored when ffield is already one); the extra group "charge" unfreezes this model’s per-atom charges.

  • keep_intermediates (bool, optional) – If True, stash the intermediate tensors of the last evaluation in self.intermediates. Default False.

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_inversion, e_vdw, e_coulomb, e_hbond. Every structure in a batch must have this topology’s atom count and element sequence.

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

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

Bonding and bond orders are perceived from the coordinates (or the orders alone when bonds is given), atom types are assigned by assign_atom_types(), and the topology follows from the perceived bonds.

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 (DreidingLibrary, DreidingForceField, str or Path, optional) – The parameter library (must carry templates); default "dreiding".

  • 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.

  • charges ("gasteiger" or sequence of float, optional) – Per-atom partial charges, or "gasteiger" to compute Gasteiger charges with RDKit (the paper’s recommendation when electrostatics matter). Default: none.

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

Returns:

The model, bound to the derived topology.

Return type:

Dreiding

forward(data)[source]#

Evaluate the DREIDING 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 a DreidingLibrary.

Returns:

See DreidingForceField.export_library().

Return type:

DreidingLibrary

property masses: Tensor#

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

Type:

Tensor

classmethod from_config(cfg)[source]#

Construct a Dreiding model from a core model config.

Core field: cfg.cutoff is the nonbonded cutoff. Everything else is read from cfg.extra: ffield ("dreiding" when absent; "dreiding/X6", a .frc path or a native JSON path) and either topology (path to a topology JSON file) or types + bonds (+ optional bond_orders) inline. Optional: charges (a list), switch_width, bond_style, angle_style, hbond, hbond_cutoff, hbond_angle, 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:

Dreiding

Raises:

ValueError – If the topology specification is missing.