Examples

Two scholastic examples showcase the features of AutoPot:

unary: Trains an MTP on MD simulations to predict the stacking fault energy of bcc Mo using an EAM potential as a reference model.
alloy: Trains an MTP to predict the stacking fault energy of bcc MoNb over the entire composition space using an EAM potential as a reference model.

A detailed explanation of how to run the examples can be found in the corresponding subdirectories.

The unary example can also be run from the AutoPot directory:

make example

Unary Example

The unary example trains a Moment Tensor Potential (MTP) for bcc Mo on MD simulations and then validates the trained potential on material properties such as the lattice constant, stacking fault energy, elastic constants, and dislocation energy. The reference model is the EAM potential of Zhou et al. (2004).

The full unary workflow can be run in one shot from the example directory:

cd examples/unary
make

This executes the setup, workflow run, and notebook-based validation. The individual steps are useful when debugging or adapting the example.

Setup

Install the AutoPot requirements from the repository root first:

make install

Then move to the example directory and execute the configuration-generation notebook:

cd examples/unary
jupyter nbconvert --to notebook --execute --inplace create_configurations.ipynb

The notebook creates:

init_training_cfgs.xyz: Initial configurations used to train the starting potential.
md_cfgs.xyz: Two MD starting configurations: one bulk configuration and one stacking fault configuration.

Running the Unary Workflow

Initialize the BD studies, create the database, and start the launcher daemons:

cd workflow
make create launcher

The orchestrator help can be inspected with:

motoko orchestrator start -h

For the unary example, the workflow uses a level 8 MTP from potentials and starts MD selection from the generated md_cfgs.xyz file:

motoko --verbose orchestrator start \
    --potential ${PWD}/../../../potentials/08.mtp \
    --fresh_potential ${PWD}/../../../potentials/08.mtp \
    --training_set ${PWD}/../init_training_cfgs.xyz \
    --calculate_ts \
    --atom_types Mo=0 \
    --md_select \
    --md_configurations ${PWD}/../md_cfgs.xyz \
    --run_name unary

AutoPot requires absolute paths for the input files. The run_name should be unique when multiple workflows use the same database, so that runs do not conflict with each other.

The workflow has finished when the terminal shows:

terminate: workflow successful

Validation and Cleanup

After the workflow completes, return to examples/unary and run check_errors.ipynb. The notebook compares MTP predictions against EAM values for the lattice constant, stacking fault energy, elastic constants, and dislocation energy.

The notebook needs the MLIP-2 executable in PATH:

export PATH=./../../third-party/mlip-2/bin:$PATH

When finished, stop the daemon processes from the workflow directory:

cd workflow
motoko kill

Alloy Example

The alloy example trains an MTP for bcc MoNb across composition space. Like the unary example, it uses an EAM reference model and validates the trained MTP on derived material properties. Unlike the unary case, it exercises both pre-selection from a training-candidate set and MD-based selection.

The full alloy workflow can be run from the example directory:

cd examples/alloy
make

The Makefile runs four stages:

clean: Removes generated .xyz, .mtp, .cfg, .log, and .ini files and cleans the workflow directory.
init: Executes create_configurations.ipynb and starts the workflow launcher.
run_workflow: Starts the AutoPot orchestrator for the MoNb workflow.
test: Runs check_errors.ipynb with pytest --nbmake.

Configuration Generation

The alloy create_configurations.ipynb notebook builds a reference bcc bulk configuration and a bcc stacking fault configuration for the elements Mo and Nb. It uses a reference lattice constant for the equiatomic alloy as the basis for generating sampled configurations.

The notebook writes:

init_training_cfgs.xyz: Initial training configurations sampled from the bulk and stacking fault structures.
training_candidates.cfg: A larger set of training candidates written in MLIP-2 format. These candidates are used by the select stage before MD selection.

The initial training set samples both end-member compositions using create_simplex_grid(2, 2). The training-candidate set samples 2000 strained and displaced configurations from the same bulk and stacking fault templates.

Running the Alloy Workflow

The alloy workflow uses the same level 8 MTP as the unary example, but passes a two-element atom-type map and enables both select and md_select:

cd examples/alloy/workflow
motoko --verbose orchestrator start \
    --potential ${PWD}/../../../potentials/08.mtp \
    --fresh_potential ${PWD}/../../../potentials/08.mtp \
    --training_set ${PWD}/../init_training_cfgs.xyz \
    --calculate_ts \
    --atom_types Mo=0,Nb=1 \
    --select \
    --training_candidate_set ${PWD}/../training_candidates.cfg \
    --md_select \
    --run_name alloy

The command used by the example Makefile uses absolute paths derived from examples/alloy and sets PATH so that MLIP-2 can be found under third-party/mlip-2/bin.

Validation

The alloy check_errors.ipynb notebook retrieves the final trained_pot.mtp from the last Motoko train run and creates a LAMMPS MTP calculator for Mo and Nb.

It then evaluates the MTP across an 11-point MoNb composition grid and compares against stored EAM reference data for:

lattice constants;
stacking fault energies;
elastic constants C11, C12, and C44.

The notebook asserts relative error tolerances of 1e-2 for lattice constants and 1e-1 for stacking fault energies and elastic constants. If one of those assertions fails, the workflow execution or generated potential should be inspected before using the result.