xnn.ffnn.models.reaxff.ReaxFF#

class xnn.ffnn.models.reaxff.ReaxFF(ffield, *, species=None, nn=None, messages=None, vdw_cutoff=10.0, hb_short=6.75, hb_long=7.5, trainable=(), keep_intermediates=False)[source]#

Bases: InteratomicPotential

ReaxFF / ReaxFF-nn reactive force field.

The model is fully specified by a parameter library (ffield text or ReaxFF-nn JSON); it evaluates the complete ReaxFF energy – bond, lone-pair, over/under-coordination, valence angle, penalty, three-body conjugation, torsion, four-body conjugation, hydrogen bond, tapered/shielded van der Waals and Coulomb terms with EEM-equilibrated charges – and, in nn mode, the ReaxFF-nn message-passing bond-order and bond-energy networks. Forces and stress come from autograd via ForceStressOutput.

Parameters:

  • ffield (str or Path or FFieldLibrary) – The parameter library (path, or a pre-parsed FFieldLibrary).

  • species (sequence of str or int, optional) – Chemical symbols (or atomic numbers) this instance supports; must be a subset of the library’s species. Default: every species in the library.

  • nn (bool, optional) – Use the ReaxFF-nn neural bond blocks. Default: True exactly when the library carries network weights.

  • messages (int, optional) – Number of message-passing steps T (nn mode). Default: the library’s value.

  • vdw_cutoff (float, optional) – Nonbonded (vdW / Coulomb / EEM) cutoff in Angstrom, and the model’s neighbor-list cutoff; by default 10.0, the ReaxFF standard.

  • hb_short (float, optional) – Donor–acceptor (X..Z) distance window of the hydrogen-bond taper, by default 6.75 and 7.5 Angstrom.

  • hb_long (float, optional) – Donor–acceptor (X..Z) distance window of the hydrogen-bond taper, by default 6.75 and 7.5 Angstrom.

  • trainable (sequence of str or "all", optional) – Which classical parameter groups to expose to the optimizer, by library name (e.g. ("Desi", "be1", "V2"); angle, torsion and hydrogen-bond groups are addressed as "ang_theta0", "tor_V2", "hb_Dehb", …); "all" unfreezes every group. Network weights (nn mode) are always trainable. Default: none (a fixed classical force field).

  • keep_intermediates (bool, optional) – If True, stash the intermediate tensors of the last evaluation (bond orders, per-interaction energies, angle/torsion indices, …) in self.intermediates for inspection – used by the fidelity notebook. Default False.

Notes

forward returns, besides the standard node_energy / energy / node_features keys, the EEM charges (N,) and one per-structure tensor per energy term (e_bond, e_lone, e_over, e_under, e_angle, e_penalty, e_three_conj, e_torsion, e_four_conj, e_vdw, e_coulomb, e_hbond, e_self). A per-structure total_charge attribute on the graph (shape (B,)) is honored by the EEM solve; the default is charge neutrality.

forward(data)[source]#

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

Parameters:

data (AtomicGraph) – The batched atomic graph; its neighbor list must have been built with this model’s cutoff (the nonbonded cutoff).

Returns:

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

Return type:

dict of str to Tensor

export_library()[source]#

Export the current parameters as a portable FFieldLibrary.

The inverse of construction: dense tensors are unpacked into the flat library dictionary (energies converted back to kcal/mol), every pair / angle / torsion / hydrogen-bond type is listed explicitly, and the network weights (nn mode) are included. FFieldLibrary.save writes the result as a ReaxFF-nn JSON file, so a trained force field can be used outside xnn.

Returns:

The exported library.

Return type:

FFieldLibrary

classmethod from_ffield(path, **kwargs)[source]#

Construct a ReaxFF from a parameter library on disk.

Parameters:

  • path (str or Path) – Path to a ffield text library or a ReaxFF-nn JSON library.

  • **kwargs – Forwarded to the constructor.

Returns:

The model.

Return type:

ReaxFF

classmethod from_config(cfg)[source]#

Construct a ReaxFF from a core model config.

Core field: cfg.cutoff is the nonbonded (vdW / Coulomb / EEM) cutoff. Everything else is read from cfg.extra (ffield is required); alternative spellings used by other ReaxFF tools are translated by xnn.common.config.translate.

Parameters:

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

Returns:

The model.

Return type:

ReaxFF