Add tutorial how to override arch params

docs/src/architectures/index.rst

@@ -1,3 +1,5 @@
+.. _available-architectures:
+
 Available Architectures
 =======================
 

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

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/.

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.

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: