Getting Started

Installation

The xnn plug-in is probably already installed in your SEAMM environment, but if not or if you wish to check, follow the directions for the SEAMM Installer. In the SEAMM conda environment:

seamm-installer install --update xnn-step

The plug-in needs the xnn code itself (published on PyPI as xnns), with PyTorch, in its own conda environment (seamm-xnn by default). xnn-step-installer creates it from the bundled seamm-xnn.yml and records it in ~/SEAMM/xnn.ini:

xnn-step-installer install

The installer chooses the PyTorch build for the machine. PyTorch wheels bundle their CUDA runtime, so the NVIDIA driver decides which build runs, and PyPI’s default wheel – which bundles the newest runtime – silently falls back to the CPU on an older driver. The installer reads the driver with nvidia-smi, installs torch from the matching PyTorch index (PyPI’s own wheel on macOS, which supports Apple’s mps), and then checks that torch sees the GPU and that xnn imports; it prints what it found. Using a GPU then needs no more than device = cuda in xnn.ini.

On a machine where the driver cannot be read – a cluster whose login node has no GPU – the installer stops and asks you to decide. Set torch-build in xnn.ini (cu128 for a current driver, cpu for a machine without a GPU) or run:

xnn-step-installer install --torch-tag cu128

A torch that already works is never replaced. One that cannot use the GPU (for instance installed from PyPI before this) is reported and left alone, since it may be deliberate; xnn-step-installer update --torch-tag cu128 replaces it.

pymdi, which provides the MDI library, comes from conda-forge: only that build links MDI against MPI, which the -method MPI launch used for LAMMPS dynamics needs.

Note

conda-environment in xnn.ini may name an environment you built yourself, for instance one shared with LAMMPS. The installer recognises an environment it did not create (from conda’s own history) and leaves it alone; to have it add xnn to such an environment anyway, run its update --torch-tag <tag> deliberately. The file’s pip part is applied without upgrading what is already present, on torch’s index.

Adding models

Put the trained checkpoints (best.pt files written by the xnn trainer) in ~/.seamm.d/data/Forcefields/xnn (your own models) or ~/SEAMM/data/Forcefields/xnn (models shared by everyone on the machine). Those two directories are searched by default, and a personal model shadows a machine-wide one of the same name. Other directories can be listed under models in xnn.ini, one per line. Each file is offered to the Model Chemistry step by its file stem, so ~/.seamm.d/data/Forcefields/xnn/water_mace_les.pt becomes the model chemistry xnn:MLFF@water_mace_les.

Using a model

In the flowchart editor add a Model Chemistry step, choose the type MLFF and the model, then follow it with an Energy step (to evaluate structures) or a LAMMPS step (to run dynamics with the MLFF as the QM engine). For example, to label an ensemble:

Parameters -> Model Chemistry (xnn:MLFF@water_mace_les) -> from SMILES
           -> Normal Mode Sampling -> Energy (configurations: all)
           -> Write Structure (Results.extxyz)

That should be enough to get started. For more detail about the functionality in this plug-in, see the User Guide.