Tutorial
========

AutoPot provides a tutorial that explains how to implement active learning
algorithms using Motoko. It does not require any third-party simulation
software and can be run directly from a notebook.

Tutorial Description
--------------------

The tutorial is a minimal active-learning workflow for a one-dimensional toy
potential. It shows the control flow used by AutoPot without requiring MLIP-2,
LAMMPS, VASP, ASE structures, or atomistic input files.

The workflow is closely related to the active-learning example in
Podryabinkin and Shapeev, *Active learning of linearly parametrized interatomic
potentials*, arXiv:1611.09346. That paper introduces an active-learning method
based on the D-optimality criterion for selecting configurations used to fit
linearly parametrized interatomic potentials.

In this tutorial, the same ideas are reduced to scalar points:

* a point ``x`` stands in for an atomistic configuration;
* a simple nonlinear function stands in for the expensive reference model;
* a two-parameter polynomial stands in for the machine-learning potential;
* the selection task computes an extrapolation grade and chooses points above a
  threshold;
* the orchestrator repeats the sequence calculate, train, select, calculate,
  train.

Files
-----

``tutorial.ipynb``
   Executable notebook that creates the Motoko task managers, launches the
   workflow, and plots the resulting models.

``workflow/motoko.yaml``
   Tutorial workflow configuration. It aliases the toy task managers as
   ``sp_calc``, ``train``, and ``select``.

``workflow/orchestrator.py``
   Motoko orchestrator for the tutorial active learning loop.

``../tasks/sp_calc/toy_model/doIt.py``
   Reference calculation for one scalar point.

``../tasks/train/toy_model/doIt.py``
   Fit of the toy potential coefficients.

``../tasks/select/toy_model/doIt.py``
   D-optimality-style selection of new training points.

Model
-----

The reference model is:

.. code-block:: python

   E_ref(x) = x**2 + x**3 * exp(-x**2 / 2)

The fitted model is:

.. code-block:: python

   E_model(x) = c0 * x**2 + c1 * x**3

The initial training set contains two points, which is the minimum needed to
fit the two model coefficients. Candidate points are then scanned, assigned an
extrapolation grade, and added to the training set when their grade exceeds the
current threshold.

Workflow
--------

The notebook uses the following inputs:

.. code-block:: python

   training_pts = [-1, 0.5]
   candidate_pts = list(np.linspace(-4, 4, 17))
   thresholds = [100, 10, 1]

The orchestrator performs:

#. ``calculate_ts_workflow``: calculate reference energies for the initial
   training points.
#. ``spawn_train_task``: fit the toy model to the current training set.
#. ``select_workflow``: loop over thresholds and select candidate points with a
   high extrapolation grade.
#. For each non-empty selection, calculate the new reference energies and
   retrain.

The final notebook cell plots the reference function and the fitted model after
each training round.

Running
-------

From the AutoPot repository root, open and run:

.. code-block:: bash

   jupyter notebook tutorial/tutorial.ipynb

The notebook starts Motoko launcher daemons and stops them at the end. If a run
is interrupted, clean up from the tutorial workflow directory:

.. code-block:: bash

   cd tutorial/workflow
   motoko kill

Relation to the Main AutoPot Workflow
-------------------------------------

.. list-table::
   :header-rows: 1

   * - Tutorial task
     - Main AutoPot task
     - Meaning
   * - ``sp_calc-toy_model``
     - ``sp_calc/eam`` or ``sp_calc/vasp``
     - reference calculation
   * - ``train-toy_model``
     - ``train/mlip2``
     - fit the potential
   * - ``select-toy_model``
     - ``select``
     - choose high-grade candidates
   * - ``workflow/orchestrator.py``
     - ``autopot_workflow/orchestrator.py``
     - coordinate active learning

The main workflow replaces scalar points with atomistic configurations, the toy
reference function with EAM or VASP calculations, and the polynomial fit with
an MLIP-2 moment tensor potential.

Reference
---------

Evgeny V. Podryabinkin and Alexander V. Shapeev, *Active learning of linearly
parametrized interatomic potentials*, Computational Materials Science 140,
171-180, 2017. arXiv: https://arxiv.org/abs/1611.09346