From 9061f1c94bc8c556cf8cbffa46132d80ab82399b Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Thu, 18 Jan 2024 13:39:48 +0100 Subject: [PATCH] Add tutorial how to override arch params --- docs/src/architectures/index.rst | 2 + .../getting-started/custom_dataset_conf.rst | 2 + docs/src/getting-started/index.rst | 1 + docs/src/getting-started/override.rst | 80 +++++++++++++++++++ docs/src/getting-started/usage.rst | 6 +- 5 files changed, 88 insertions(+), 3 deletions(-) create mode 100644 docs/src/getting-started/override.rst 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/custom_dataset_conf.rst b/docs/src/getting-started/custom_dataset_conf.rst index c35515017..35db196a3 100644 --- a/docs/src/getting-started/custom_dataset_conf.rst +++ b/docs/src/getting-started/custom_dataset_conf.rst @@ -132,3 +132,5 @@ by default. .. note:: Unknown keys are ignored and not deleted in all sections during dataset parsing. + +In the next tutorials we show how to override the default parameters of an architecture. diff --git a/docs/src/getting-started/index.rst b/docs/src/getting-started/index.rst index 6920aa3d4..49ec67d18 100644 --- a/docs/src/getting-started/index.rst +++ b/docs/src/getting-started/index.rst @@ -9,3 +9,4 @@ This sections describes how to install the package, and its most basic commands. installation usage custom_dataset_conf + override diff --git a/docs/src/getting-started/override.rst b/docs/src/getting-started/override.rst new file mode 100644 index 000000000..5167851dd --- /dev/null +++ b/docs/src/getting-started/override.rst @@ -0,0 +1,80 @@ +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 example, the parameters of the SOAP-BPNN +models 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 + + training_set: + structures: "qm9_reduced_100.xyz" + targets: + energy: + key: "U0" + + test_set: 0.1 + validation_set: 0.1 + +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:: + + For your reference and reproducibility purposes `metatensor-models` always writes the + fully expanded options to the ``.hydra`` subdirectory inside the ``output`` + directory of your current training run. + + +Understanding the Defaults Section +---------------------------------- + +You may have noticed the ``defaults`` section at the beginning of each file. This list +dictates which defaults should be loaded and how to compose the final config object and +is conventionally the first item in the config. + +Append ``_self_`` to the end of the list to have your primary config override values +from the Defaults List. If you do not add a ``_self_`` entry still your primary config +Overrides values from the Defaults List, but Hydra will throw a warning. 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 bb87acd59..06242589f 100644 --- a/docs/src/getting-started/usage.rst +++ b/docs/src/getting-started/usage.rst @@ -42,8 +42,9 @@ training using the default hyperparameters of an SOAP BPNN model .. literalinclude:: ../../static/options.yaml :language: yaml -For each training run a new output directory based on the current date and time is -created. By default, this output directory is used to store Hydra's output for the run +For each training run a new output directory in the format +``output/YYYY-MM-DD/HH-MM-SS`` based on the current date and time is created. By +default, this output directory is used to store Hydra's output for the run (configuration, Logs etc). You can `override `_ this behavior in the options file. To start the training create an ``options.yaml`` file in @@ -67,6 +68,5 @@ The sub-command to evaluate a already trained model is :language: bash :lines: 9- - In the next tutorials we show how adjust the dataset section of ``options.yaml`` file to use it for your own datasets.