diff --git a/docs/src/architectures/index.rst b/docs/src/architectures/index.rst index c980b7510..65fbb5e51 100644 --- a/docs/src/architectures/index.rst +++ b/docs/src/architectures/index.rst @@ -1,3 +1,5 @@ +.. _available-architectures: + Available Architectures ======================= diff --git a/docs/src/getting-started/index.rst b/docs/src/getting-started/index.rst index e941c77e1..6a23bae4c 100644 --- a/docs/src/getting-started/index.rst +++ b/docs/src/getting-started/index.rst @@ -8,3 +8,4 @@ This sections describes how to install the package, and its most basic commands. installation usage + override diff --git a/docs/src/getting-started/override.rst b/docs/src/getting-started/override.rst new file mode 100644 index 000000000..3f3438ae6 --- /dev/null +++ b/docs/src/getting-started/override.rst @@ -0,0 +1,81 @@ +Override Architecture's Default Parameters +========================================== + +In our initial tutorial, we used default parameters to train a model employing the +SOAP-BPNN architecture, as shown in the following config: + +.. literalinclude:: ../../static/options.yaml + :language: yaml + +While default parameters often serve as a good starting point, depending on your +training target and dataset, it might be necessary to adjust the architecture's +parameters. + +First, familiarize yourself with the specific parameters of the architecture you intend +to use. We provide a list of all architectures and their parameters in the +:ref:`available-architectures` section. For SOAP-BPNN models, the parameters are +detailed at :ref:`architecture-soap-bpnn`. + +Modifying Parameters (yaml) +--------------------------- + +As an example, let's increase the number of epochs (``num_epochs``) and the ``cutoff`` +radius of the SOAP descriptor. To do this, create a new section in the ``options.yaml`` +named ``architecture``. Within this section, you can override the architecture's +hyperparameters. The adjustments for ``num_epochs`` and ``cutoff`` look like this: + +.. code-block:: yaml + + defaults: + - architecture: soap_bpnn + - _self_ + + architecture: + model: + soap: + cutoff: 7.0 + training: + num_epochs: 200 + + # Dataset config omitted for simplicity. + +Modifying Parameters (Command Line Overrides) +--------------------------------------------- + +For quick adjustments, command-line overrides are also an option. The changes above can +be achieved by: + +.. code-block:: bash + + metatensor-models train options.yaml \ + -y architecture.model.soap.cutoff=7.0 architecture.training.num_epochs=200 + +Here, the ``-y`` flag is used to parse the override flags. More details on override +syntax are available at https://hydra.cc/docs/advanced/override_grammar/basic/. + +.. note:: + `metatensor-models` always writes the fully expanded ``options.yaml`` for your reference. + +Understanding the Defaults Section +---------------------------------- + +You may have noticed the ``defaults`` section at the beginning of each file. This list +dictates how to compose the final config object and is conventionally the first item in +the config. + +Ordering of Defaults: + +- If multiple configs define the same value, the last one wins. +- If multiple configs contribute to the same dictionary, the result is a combination of + these dictionaries. + +The Importance of ``_self_``: + +- To have your primary config override values from the Defaults List, append ``_self_`` + to the end of the list. +- For the Defaults List configs to override values in your primary config, insert + ``_self_`` as the first item. + +Since we typically want to override our default architecture, it's advisable to keep +``_self_`` at the end of the Defaults List. For more background, visit +https://hydra.cc/docs/tutorials/basic/your_first_app/defaults/. diff --git a/docs/src/getting-started/usage.rst b/docs/src/getting-started/usage.rst index b8456ec4f..f7e9d8a87 100644 --- a/docs/src/getting-started/usage.rst +++ b/docs/src/getting-started/usage.rst @@ -66,3 +66,5 @@ The sub-command to evaluate a already trained model is .. literalinclude:: ../../../examples/usage.sh :language: bash :lines: 9- + +In the next tutorials we show how to override the default parameters of an architecture. diff --git a/docs/static/options.yaml b/docs/static/options.yaml index 3331fbea7..2138f4b86 100644 --- a/docs/static/options.yaml +++ b/docs/static/options.yaml @@ -1,5 +1,6 @@ defaults: - architecture: soap_bpnn # architecture used to train the model + - _self_ # Section defining the parameters for structure and target data dataset: