Examples#

Every notebook of the repository’s examples/ directory, rendered with its executed outputs. To run one yourself, see Run the Example Notebooks for the environments. Entries marked coming soon are being reviewed and become links as they are published.

Data#

The data hub: load_dataset(), splits, units, caching.

  • Loading datasets with xnn: the data hub & load_dataset()coming soon

Models#

The model hub: foundation models, xnn-trained models and Zenodo uploads under one from_pretrained() call, the cache layout and sharing your own.

  • Pre-trained models with xnn: the model hub & from_pretrained()coming soon

ANI (dnn)#

ANI from scratch on rMD17, then the four published ANI datasets, each paired with its model preset.

  • Training ANI from scratch on rMD17 (paracetamol)coming soon

  • The ANI-1 dataset in one line, and a paper-style correlation testcoming soon

  • The ANI-1x dataset in one line: forces, active learning, and the ani-1x presetcoming soon

  • The ANI-1ccx dataset: coupled-cluster labels and transfer learning with the ani-1ccx presetcoming soon

  • The ANI-2x dataset: seven elements (S, F, Cl) and the ani-2x presetcoming soon

HDNNP (dnn)#

The four generations of high-dimensional neural network potentials: their defining properties on untrained models, first and second generation on rMD17, and the 2G / 3G / 4G comparison of the fourth-generation paper.

  • The four generations of HDNNPs: symmetry functions, locality, non-local charge transfercoming soon

  • First- and second-generation potentials on rMD17 ethanolcoming soon

  • 2G, 3G and 4G HDNNPs on the benchmarks of the fourth-generation papercoming soon

PhysNet (dnn)#

Training and MD against the original TensorFlow PhysNet.

  • Training & testing PhysNet on Argon MD data: xnn vs the original PhysNet, step by stepcoming soon

  • Argon MD with PhysNet: xnn NPT density + lock-step NVE against the originalcoming soon

SchNet (gnn)#

The paper architecture trained on rMD17 ethanol, then thermostat-free NVE dynamics to show energy conservation by construction.

DimeNet and DimeNet++ (gnn)#

The directional message passing papers (Gasteiger et al., ICLR 2020 and NeurIPS-W 2020) checked with untrained models: the Bessel and spherical Fourier-Bessel bases, the envelope, twice continuous differentiability across the cutoff, the distinguishability argument and the DimeNet++ speed-up. Then the MD17 experiment of the paper on rMD17 ethanol: DimeNet, DimeNet++ and SchNet trained on 1000 structures, with the learned 2D filters.

  • DimeNet from the paper: bases, smoothness, directionality, and the DimeNet++ speed-upcoming soon

  • DimeNet and DimeNet++ on rMD17 ethanol: energies and forces from 1000 structurescoming soon

GemNet (gnn)#

The geometric message passing paper (Gasteiger et al., NeurIPS 2021) checked with untrained models: the three bases, triplets and quadruplets, what the dihedral angle adds, the variance scaling of Fig. 3, smoothness at both cutoffs, direct versus conservative forces and the cost of the variants. Then GemNet-T, -Q and -dT trained on rMD17 ethanol, with NVE energy conservation.

  • GemNet from the paper: bases, two-hop message passing, variance scaling, direct forcescoming soon

  • GemNet on rMD17 ethanol: GemNet-T, GemNet-Q and direct forcescoming soon

PaiNN (gnn)#

The equivariant message passing paper (Schütt et al., ICML 2021): the architecture and its claims checked with untrained models, the MD17 experiments and ablations of Tables III and IV, the rotational profile of substituted ferrocene at short cutoffs (Fig. 4), and the infrared and Raman spectra of ethanol from classical and ring-polymer dynamics (Fig. 5).

  • PaiNN from the paper: equivariant messages, directional information and tensorial outputscoming soon

  • PaiNN on MD17: energies and forces from 1000 structures, and the ablationscoming soon

  • Propagation of directional information: the substituted ferrocene rotationcoming soon

  • Infrared and Raman spectra of ethanol from classical and ring-polymer dynamicscoming soon

3D steerable CNN (cnn)#

The Tetris experiment of the 3D steerable CNN paper (Weiler et al., NeurIPS 2018): steerable and conventional kernels trained on the eight pieces in one orientation and tested under random rotations, with the paper’s low-pass ablation, the kernel-basis figure and the equivariance of the internal fields. Then the same comparison for interatomic potentials: the steerable and the conventional 3D CNN trained on rMD17 ethanol and evaluated on rotated structures.

  • The Tetris experiment: rotation equivariance of 3D steerable CNNscoming soon

  • Steerable against conventional 3D CNN potentials on rMD17 under rotationscoming soon

Spherical CNN (cnn)#

The QM7 experiment of the spherical CNN paper (Cohen et al., ICLR 2018): atomization energies from the potentials of the atoms sampled on spheres, with the Table 3 network and the DeepSet readout, and the rotation invariance of the energy.

  • Spherical CNN on QM7: atomization energies from spherical signalscoming soon

NequIP, MACE, Allegro, CACE, AIMNet2 (gnn)#

The argon train, evaluate and MD series, one pair of notebooks per model against its reference code; a block-by-block walkthrough of the MACE architecture; the MACE-OFF23 and MACE-MP foundation models on organic chemistry and materials; the fine-tuning strategies (naive, readout-only, LoRA, multi-head replay) side by side; and the published AIMNet2 models on neutral, charged and open-shell molecules.

  • Training & testing NequIP on Argon MD data: xnn vs the original NequIP, step by stepcoming soon

  • Argon density from MD: xnn vs the original NequIPcoming soon

  • Training & testing MACE on Argon MD data: xnn vs the original MACE, step by stepcoming soon

  • Argon density from MD: xnn vs the original MACEcoming soon

  • 04 · Recreating the MACE architecture, block by block: original MACE and xnncoming soon

  • MACE-OFF23 in xnn: organic chemistry with a pretrained foundation modelcoming soon

  • Fine-tuning strategies for a foundation model: naive, LoRA and multi-head replaycoming soon

  • MACE-MP foundation models in xnn: materials properties across generationscoming soon

  • Training & testing Allegro on Argon MD data: xnn vs the original Allegro, step by stepcoming soon

  • Argon density from MD: xnn vs the original Allegrocoming soon

  • Training & testing CACE on Argon MD data: xnn vs the original CACE, step by stepcoming soon

  • Argon density from MD: xnn vs the original CACEcoming soon

  • AIMNet2 in xnn: neutral, charged and open-shell molecules with a pretrained foundation modelcoming soon

Long-range: Latent Ewald Summation (gnn)#

  • Why long-range matters: molecular-dimer binding curves (xnn LES vs a short-range model)coming soon

Dispersion: DFT-D4 (common)#

Reproductions of the D4 paper’s examples, a benchmark against the reference dftd4 with deployment through every channel, and the large-system regime pushed to the memory limit of one GPU.

  • DFT-D4 in xnn: reproducing examples of the D4 papercoming soon

  • DFT-D4 in xnn vs the reference dftd4: accuracy, speed, and deployment with an MLIPcoming soon

  • Large-scale DFT-D4: liquid ethanol from rMD17 conformers, up to the memory limitcoming soon

Dispersion: DFT-D3 (common)#

Reproductions of the two Grimme papers and a benchmark against simple-dftd3 for every damping function.

  • DFT-D3 in xnn: reproducing examples of the two Grimme paperscoming soon

  • DFT-D3 in xnn vs the reference simple-dftd3: accuracy, speed, and deployment with an MLIPcoming soon

BAMBOO (hybrid)#

  • BAMBOO charges, energy decomposition, and deploymentcoming soon

  • BAMBOO on charged / polar molecular dimers: why the charge-equilibrium term matterscoming soon

SpookyNet (hybrid)#

The SpookyNet paper (Unke et al., Nat. Commun. 2021): the building blocks checked with untrained models and the published example model, the electronic-state surfaces of Ag3+ / Ag3- and singlet / triplet CH2 (Fig. 4), the dissociation of diatomics with and without nonlocal interactions (Fig. 5), the 4G-HDNNP charge-transfer benchmarks (Table 1) and MD17 (Table 3).

  • SpookyNet from the paper: electronic states, orbital-like interactions and nonlocalitycoming soon

  • Electronic states: Ag3+ / Ag3- and singlet / triplet CH2coming soon

  • Nonlocal effects: dissociation of diatomic moleculescoming soon

  • Nonlocal charge transfer: the 4G-HDNNP benchmarkscoming soon

  • SpookyNet on MD17coming soon

ReaxFF / ReaxFF-nn (ffnn)#

A reactive force field fit by gradient descent to rMD17 malonaldehyde, then MD with the trained library: bond orders, EEM charges and a dissociation scan.

  • Training ReaxFF-nn on rMD17 (malonaldehyde)coming soon

  • ReaxFF in action: bond orders, charges, MD and dissociationcoming soon

OPLS / L-OPLS (ffnn)#

Table 1 of the 1996 paper from relaxed dihedral scans, then the L-OPLS hexane torsion re-derived by gradient descent to the published coefficients.

  • OPLS-AA conformational energetics: reproducing Table 1 of Jorgensen et al. (1996)coming soon

  • L-OPLS, and refitting OPLS torsions by gradient descentcoming soon

DREIDING (ffnn)#

Tables XI and XII of the 1990 paper from relaxed scans, then the generators refit on benzene and tested for transfer to naphthalene and toluene.

  • DREIDING conformational energetics: reproducing Tables XI and XII of the 1990 papercoming soon

  • Retraining DREIDING: refitting the generators, and testing whether they transfercoming soon

Semiempirical methods (sqmnn)#

The tables of the PM3, PM6, PM7 and PM6-ORG papers reproduced with the published parameters: heats of formation, dipoles and ionization potentials, the modified core-core terms, and the S22 / S66 interaction energies; then the parameters refit by gradient descent and written back for MOPAC.

  • PM3 heats of formation, dipole moments and ionization potentials (Stewart 1989)coming soon

  • PM6: the modified NDDO approximations of the 2007 papercoming soon

  • Noncovalent interactions: PM7 (S22, S66) and PM6-ORGcoming soon

  • Refitting NDDO parameters: hydrogen bonds, MOPAC export and force trainingcoming soon

Deployment: MDI (common)#

A checkpoint served as an MDI engine, driven first from a minimal Python driver and then from LAMMPS fix mdi/qm.

  • Deploying a trained model as an MDI engine: liquid argon over the MolSSI Driver Interfacecoming soon

  • Driving the xnn MDI engine from LAMMPS: liquid-argon NVE and \(g(r)\)coming soon

Fidelity checks#

Block-by-block verification of each implementation against its upstream reference (Model Fidelity to Upstream Codes), ending with a weight transplant.

  • SchNet, block by block: verifying the xnn implementation against the manuscriptscoming soon

  • 3D steerable CNN, block by block: the kernel basis, equivariance and the reference implementationcoming soon

  • Spherical CNN, block by block: harmonic analysis, correlations, equivariance and the reference implementationcoming soon

  • DimeNet and DimeNet++ against the authors’ TensorFlow implementation, including the published QM9 modelcoming soon

  • GemNet against the reference implementation, including the published weightscoming soon

  • PaiNN, block by block: the paper’s equations and the reference implementationcoming soon

  • SpookyNet, block by block: the paper’s equations and the reference implementationcoming soon

  • HDNNP (2G, 3G, 4G) against the RuNNer code, including a published 4G modelcoming soon

  • ANI-1, block by block: reproducing the original implementation with xnncoming soon

  • PhysNet, block by block: reproducing the original implementation with xnncoming soon

  • NequIP, block by block: reproducing the original implementation with xnncoming soon

  • MACE, block by block: reproducing the original implementation with xnncoming soon

  • MACE foundation models: verifying MACE.from_foundation() against mace-torchcoming soon

  • AIMNet2 foundation models: verifying AIMNet2.from_foundation() against the aimnet packagecoming soon

  • Allegro, block by block: reproducing the original implementation with xnncoming soon

  • CACE, block by block: reproducing the original implementation with xnncoming soon

  • Latent Ewald Summation (LES), block by block: reproducing the original implementation with xnncoming soon

  • DFT-D4 dispersion, block by block: reproducing the reference dftd4 with xnncoming soon

  • DFT-D3 dispersion, block by block: reproducing the reference simple-dftd3 with xnncoming soon

  • BAMBOO fidelity check: xnn vs the original bytedance/bamboo, block by blockcoming soon

  • OPLS: verifying the xnn implementation against OpenMM and the 1996 papercoming soon

  • DREIDING: verifying the xnn implementation against LAMMPS and the 1990 papercoming soon

  • PM3, PM6, PM6-ORG and PM7 against the MOPAC programcoming soon

Parity checks#

The fast paths (Run Models on Fused GPU Kernels) against the reference implementations they replace: energies, forces, stress, charges, training gradients and timings.

  • MACE and NequIP on cuEquivariance: parity with the referencecoming soon

  • Dispersion fast paths: parity with the reference (DFT-D3, DFT-D4)coming soon