xnn.ffnn.models.reaxff#

ReaxFF: the reactive force field, classical and machine-learned (ReaxFF-nn).

ReaxFF (van Duin, Dasgupta, Lorant & Goddard, J. Phys. Chem. A 105, 9396, 2001) writes the total energy as a sum of bond-order-dependent valence terms plus shielded, tapered nonbonded terms evaluated between all atom pairs:

E = E_bond + E_lp + E_over + E_under + E_val + E_pen + E_coa

  • E_tors + E_conj + E_hbond + E_vdWaals + E_Coulomb (+ E_self)

Bond orders are computed directly from interatomic distances (sigma, pi and double-pi contributions, eq 2 of the paper), corrected for over-coordination and residual 1-3 contributions (eq 3), and every valence term is written in terms of these bond orders so that it vanishes smoothly as bonds break – which is what makes the force field reactive. Partial charges are re-equilibrated at every geometry with the electronegativity-equalization method (EEM), giving geometry-dependent Coulomb energies. The transition-metal extension (Nielson et al., J. Phys. Chem. A 109, 493, 2005) and the modern standard form (Senftle et al., npj Comput. Mater. 2, 15011, 2016) share this term structure.

ReaxFF-nn (Guo et al., Comput. Mater. Sci. 172, 109393, 2020; Xue et al., Phys. Chem. Chem. Phys. 23, 19457, 2021 – ReaxFF-MPNN; Guo et al., 2023 – ReaxFF-nn in GULP) replaces the closed-form bond-order correction with a message-passing neural network acting on the uncorrected bond orders and (optionally) the closed-form bond energy with a small per-bond network, keeping every other ReaxFF term intact. Both variants are implemented here in one model; every term is checked against the published equations in tests/test_reaxff.py (see the fidelity notes in the documentation for why no third-party verification artifact is distributed).

Conventions and scope#

  • All parameters come from a standard ffield text library or a ReaxFF-nn JSON library (see xnn.ffnn.models.ffield); energies are converted from kcal/mol to eV at assembly.

  • Any parameter group can be made trainable (trainable=...): the ReaxFF functional form is differentiable end-to-end, so classical parameters can be refit by gradient descent (Guo et al. 2020). In ReaxFF-nn mode the network weights are trainable by default.

  • Nonbonded terms (vdW / Coulomb / EEM) are evaluated on the model’s neighbor list within vdw_cutoff with the standard 7th-order taper, which has zero value and slope at the cutoff.

  • Valence angles and torsions use the composed edge geometry (r_ik = |r_ij + r_jk|), which is well defined for any cell size.

  • A handful of conventions (switching-function regularization, unit handling of unlisted angle types, the hydrogen-bond angle numerator) follow the behavior under which published ReaxFF-nn parameter libraries were trained, so that such libraries evaluate correctly; each is marked in the code.

  • The neural vdW taper of the ReaxFF-nn JSON format (VdwFunction > 0 with vdW network weights) and the per-molecule training offsets (MolEnergy) are not implemented.

Functions

guarded_exp(x)

exp with the argument capped at 40.

nonbonded_taper(r, cutoff)

The 7th-order ReaxFF nonbonded taper Tap(r).

reverse_edge_permutation(src, dst, shifts)

For each directed edge, the index of its reversed counterpart.

taper_down(x, rmin, rmax)

Descending distance taper: 1 below rmin, 0 above rmax.

taper_up(x, rmin, rmax)

Ascending bond-order taper: 0 below rmin, 1 above rmax.

Classes

ReaxFF(ffield, *[, species, nn, messages, ...])

ReaxFF / ReaxFF-nn reactive force field.
On this page
Show Source