mlff.py: Batch MLFF Calculations

machine learning force field, MPNICE, QRNN, UMA, GPU

The script mlff.py runs batches of machine learning force field (MLFF) single point energy and geometry optimization calculations. It enables processing of multiple structures without needing to launch a separate Jaguar job per structure. Input structures are automatically split into batches and distributed across the available CPUs. For information on the available MLFF models, see Machine Learning Force Fields.

The workflow performs the following steps:

1. If preopt is enabled, a pre-optimization with OPLS is performed on each input structure.

2. The input structures are split into batches, determined by the batches keyword, and submitted as separate subjobs.

3. Each subjob runs a single point energy calculation or geometry optimization (if geopt is set) for each structure in the batch, using the specified MLFF model.

4. Output structures with computed energies are collected in jobname-out.mae (or .maegz, matching the input file extension).

Using the mlff.py script

The mlff.py script uses an input file that contains keywords to specify the parameters of the calculation. The command syntax is:

jaguar run mlff.py inputfile.in

See Table 1 for a full list of the available mlff.py keywords and their descriptions.

Here is an example .in file that runs a geometry optimization with the Organic_MPNICE model:

infile = molecules.mae
model = organic_mpnice
geopt = True
preopt = False

Here is an example that runs single point energies with a delta-learned model and implicit solvation. Implicit solvation is only available with delta-learned models (QRNN2, QRNN3, Organic_MPNICE_TB).

infile = molecules.mae
model = organic_mpnice_tb
implicit_solvent = True
solvent = water
solvent_model = alpb

GPU acceleration

GPU acceleration can be enabled for MLFF calculations by setting gpu to True. GPU acceleration is available for MPNICE and UMA models. QRNN models are not supported. Delta-learned models such as Organic_MPNICE_TB do not benefit significantly because the xTB portions of the calculation remain on the CPU.

To use GPU acceleration, the job must be submitted to a host with an available GPU:

infile = molecules.mae
model = uma_sm_omol
geopt = True
gpu = True

To use an MLFF with GPU acceleration through Jaguar, set gpu=1 in the &gen section of the Jaguar input file. See External Methods Keywords in the Jaguar Input File (Machine learning methods and xTB).

Custom MLFF models

Custom MLFF models can be used by specifying the model type as the model keyword value and passing the model directory with the -MLFF_DATA command-line flag. The model type name is case-insensitive. For example:

jaguar run mlff.py -MLFF_DATA /path/to/model_directory inputfile.in

The model directory is automatically transferred to the remote host when running on a remote machine.

alpb
gbsa
cosmo
cpcmx