xnn.dnn.models.ani.ANI#

class xnn.dnn.models.ani.ANI(species=[1, 6, 7, 8], radial_cutoff=5.2, angular_cutoff=3.5, hidden=(128, 128, 64), activation='celu', atomic_energies=None, aev_kwargs=None)[source]#

Bases: DescriptorPotential

ANI (Smith et al. 2017): per-element networks on the AEV.

A DescriptorPotential whose featurizer is the AEV (radial and angular symmetry functions). Prefer the ani1() / ani1x() / ani1ccx() / ani2x() classmethods for the published parameterisations; the raw constructor exposes every knob for custom grids and architectures.

The presets are distinct published models, not tunings of one: ani1() is the original ANI-1 (Smith et al. 2017; 768-length AEV, 4.6/3.1 A cutoffs, a uniform 768:128:128:64:1 network, Gaussian activation) trained on the dense 20 M-conformation ANI-1 dataset, while ani1x() is the later ANI-1x (Smith et al. 2018) built by active learning, with a leaner 384-length AEV (5.2/3.5 A cutoffs), torchani’s per-element network widths, CELU activation, and ANI-1x self energies. ani1ccx() (Smith et al. 2019) keeps the ANI-1x architecture but was trained by transfer learning to CCSD(T)*/CBS coupled-cluster data, so only its self energies (and trained weights) differ. ani2x() (Devereux et al. 2020) extends the element set to seven (adds S, F, Cl) with a larger 1008-length AEV (5.1/3.5 A cutoffs) and wider per-element networks. From a config, the preset key ("ani-1" / "ani-1x" / "ani-1ccx" / "ani-2x") selects among them; see from_config().

Parameters:

  • species (sequence of int, optional) – Atomic numbers to build per-element networks for and to resolve the AEV into, by default [1, 6, 7, 8] (H, C, N, O).

  • radial_cutoff (float, optional) – Cutoff radius for the radial part of the AEV, by default 5.2.

  • angular_cutoff (float, optional) – Cutoff radius for the angular part of the AEV, by default 3.5.

  • hidden (sequence of int or dict[int, sequence of int], optional) – Hidden-layer widths of each per-element MLP (a shared sequence or a per-Z dict), by default (128, 128, 64).

  • activation (str or torch.nn.Module, optional) – Hidden-layer activation, by default "celu" (ANI convention).

  • atomic_energies (sequence of float or None, optional) – Per-species self atomic energy added to each atom’s contribution (aligned with species); None (default) adds nothing.

  • aev_kwargs (dict, optional) – Extra keyword arguments forwarded to AEV (symmetry-function grids, radial_prefactor, angular_cos_factor); by default None.

classmethod ani1(species=[1, 6, 7, 8], activation='gaussian', atomic_energies=None)[source]#

Build the original ANI-1 potential (Smith et al. 2017).

768-length AEV (radial cutoff 4.6 A, angular cutoff 3.1 A) with the paper’s pyramidal 768:128:128:64:1 element networks and a Gaussian hidden activation.

Parameters:

  • species (sequence of int, optional) – Atomic numbers, by default [1, 6, 7, 8].

  • activation (str or torch.nn.Module, optional) – Hidden activation, by default "gaussian" (the paper’s choice).

  • atomic_energies (sequence of float or None, optional) – Per-species self energies aligned with species.

Returns:

The ANI-1 model.

Return type:

ANI

classmethod ani1x(species=[1, 6, 7, 8], atomic_energies='torchani')[source]#

Build the ANI-1x architecture matching torchani.

384-length AEV (radial cutoff 5.2 A, angular cutoff 3.5 A) with torchani’s per-element network widths and the CELU activation. With torchani’s pretrained weights transplanted this reproduces its energies and forces.

Parameters:

  • species (sequence of int, optional) – Atomic numbers, by default [1, 6, 7, 8].

  • atomic_energies (sequence of float, str or None, optional) – Per-species self energies. "torchani" (default) uses torchani’s ANI-1x self energies in Hartree; a sequence sets them explicitly; None adds nothing.

Returns:

The ANI-1x model.

Return type:

ANI

classmethod ani1ccx(species=[1, 6, 7, 8], atomic_energies='torchani')[source]#

Build the ANI-1ccx potential (Smith et al. 2019, transfer learning).

Architecturally identical to ani1x() (384-length AEV, 5.2/3.5 A cutoffs, torchani per-element widths, CELU); the published model was retrained by transfer learning on the CCSD(T)*/CBS energies of the ANI-1ccx data set (holding 65,280 of the 325,248 network weights fixed – the matrix joining each element network’s first two hidden layers), so only the self atomic energies (and the trained weights) differ. With torchani’s pretrained ANI-1ccx weights transplanted this reproduces its energies and forces.

Parameters:

  • species (sequence of int, optional) – Atomic numbers, by default [1, 6, 7, 8].

  • atomic_energies (sequence of float, str or None, optional) – Per-species self energies. "torchani" (default) uses torchani’s ANI-1ccx self energies in Hartree (the CCSD(T)*/CBS linear fit); a sequence sets them explicitly; None adds nothing.

Returns:

The ANI-1ccx model.

Return type:

ANI

classmethod ani2x(species=[1, 6, 7, 8, 16, 9, 17], atomic_energies='torchani')[source]#

Build the ANI-2x architecture matching torchani.

The seven-element extension of ANI (Devereux et al. 2020): adds S, F, and Cl to H, C, N, O. A larger 1008-length AEV (radial cutoff 5.1 A with 16 shifts, angular cutoff 3.5 A with 8 radial x 4 angular shifts, both grids starting at 0.8 A, widths eta 19.7 / 12.5 and zeta 14.1) feeds wider per-element networks (H 256:192:160, C 224:192:160, N/O 192:160:128, S/F/Cl 160:128:96) with the CELU activation. With torchani’s pretrained ANI-2x weights transplanted this reproduces its energies and forces.

Parameters:

  • species (sequence of int, optional) – Atomic numbers, by default [1, 6, 7, 8, 16, 9, 17] (H, C, N, O, S, F, Cl, in torchani’s order).

  • atomic_energies (sequence of float, str or None, optional) – Per-species self energies. "torchani" (default) uses torchani’s ANI-2x self energies in Hartree; a sequence sets them explicitly; None adds nothing.

Returns:

The ANI-2x model.

Return type:

ANI

classmethod from_config(cfg)[source]#

Build an ANI from a configuration object.

Recognises a preset key ("ani-1" / "ani-1x" / "ani-1ccx" / "ani-2x") in extra to select a published parameterisation; any other extra keys override the corresponding constructor argument. Upstream torchani / NeuroChem key spellings are translated to xnn names by the loader (see xnn.common.config.translate). The "ani-2x" preset defaults to its seven-element set (H, C, N, O, S, F, Cl) when no species is given.

Parameters:

cfg (object) – Configuration exposing cutoff and an optional extra mapping (keys species, preset, radial_cutoff, angular_cutoff, hidden, activation, atomic_energies, aev_kwargs).

Returns:

Instantiated model.

Return type:

ANI