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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash make install Then move to the example directory and execute the configuration-generation notebook: .. code-block:: bash 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: .. code-block:: bash cd workflow make create launcher The orchestrator help can be inspected with: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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``: .. code-block:: bash export PATH=./../../third-party/mlip-2/bin:$PATH When finished, stop the daemon processes from the workflow directory: .. code-block:: bash 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: .. code-block:: bash 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``: .. code-block:: bash 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.