.. _arch-llpr:

LLPR
====

The LLPR architecture is a "wrapper" architecture that enables cheap uncertainty
quantification via the last-layer prediction rigidity (LLPR) approach proposed by Bigi
et al:footcite:p:`bigi_mlst_2024`. It is compatible with the following ``metatrain``
models constructed from NN-based architectures: :ref:`arch-pet` and
:ref:`arch-soap_bpnn`.

This implementation further allows the user to perform gradient-based tuning of the
ensemble weights sampled from the LLPR formalism, which can lead to improved uncertainty
estimates. Gradients (e.g. forces and stresses) are not yet used.

Note that the uncertainties computed with this implementation are returned as standard
deviations, and not variances.

Additional outputs
------------------

In addition to the outputs already availble from the wrapped model, the LLPR
architecture can also output the following additional quantity:

- :ref:`mtt-aux-target-uncertainty`: The uncertainty (standard deviation) for a given
  target, computed with the LLPR approach.
- :ref:`mtt-aux-target-ensemble`: The ensemble predictions for a given target, computed
  with the LLPR approach.

.. _arch-llpr_installation:

Installation
------------

To install this architecture along with the ``metatrain`` package, run:

.. code-block:: bash

    pip install metatrain[llpr]

where the square brackets indicate that you want to install the optional
dependencies required for ``llpr``.

.. _arch-llpr_default_hypers:

Default Hyperparameters
-----------------------

The description of all the hyperparameters used in ``llpr`` is provided
further down this page. However, here we provide you with a yaml file containing all
the default hyperparameters, which might be convenient as a starting point to
create your own hyperparameter files:

.. literalinclude:: ../default_hypers/llpr-default-hypers.yaml
   :language: yaml

.. _arch-llpr_model_hypers:

Model hyperparameters
------------------------

The parameters that go under the ``architecture.model`` section of the config file
are the following:

.. container:: mtt-hypers-remove-classname

    ..

        .. autoattribute:: metatrain.llpr.documentation.ModelHypers.num_ensemble_members



.. _arch-llpr_trainer_hypers:

Trainer hyperparameters
-------------------------

The parameters that go under the ``architecture.trainer`` section of the config file
are the following:

.. container:: mtt-hypers-remove-classname

    ..

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.distributed

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.distributed_port

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.batch_size

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.regularizer

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.model_checkpoint

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.loss

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.num_epochs

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.train_all_parameters

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.warmup_fraction

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.learning_rate

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.weight_decay

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.log_interval

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.checkpoint_interval

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.per_structure_targets

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.num_workers

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.log_mae

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.log_separate_blocks

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.best_model_metric

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.grad_clip_norm

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.batch_atom_bounds

        .. autoattribute:: metatrain.llpr.documentation.TrainerHypers.calibration_method



.. _arch-llpr_references:

References
----------

.. footbibliography::