From 4ffbc96451d9c8c68485e070b10ebd8bb582562b Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Thu, 8 May 2025 16:56:33 +0200 Subject: [PATCH 1/2] Render usage.sh with sphinx-gallery --- .gitignore | 1 + docs/generate_examples/conf.py | 6 +- docs/src/getting-started/index.rst | 2 +- docs/src/getting-started/usage.rst | 94 ------------------------ examples/basic_usage/usage.sh | 111 +++++++++++++++++++++++++++-- tox.ini | 1 + 6 files changed, 112 insertions(+), 103 deletions(-) delete mode 100644 docs/src/getting-started/usage.rst diff --git a/.gitignore b/.gitignore index 4a59cfacb..c4cf2282c 100644 --- a/.gitignore +++ b/.gitignore @@ -174,3 +174,4 @@ extensions/ # sphinx gallery docs/src/examples *execution_times* +qm9_reduced_100.zip diff --git a/docs/generate_examples/conf.py b/docs/generate_examples/conf.py index 16bbb3b7c..59d718362 100644 --- a/docs/generate_examples/conf.py +++ b/docs/generate_examples/conf.py @@ -11,8 +11,10 @@ ROOT = os.path.realpath(os.path.join(HERE, "..", "..")) sphinx_gallery_conf = { - "filename_pattern": "/*", + "filename_pattern": r"/*\.py", "copyfile_regex": r".*\.(pt|sh|xyz|yaml)", + "ignore_pattern": r"train\.sh", + "example_extensions": {".py", ".sh"}, "default_thumb_file": os.path.join(ROOT, "docs/src/logo/metatrain-512.png"), "examples_dirs": [ os.path.join(ROOT, "examples", "ase"), @@ -20,6 +22,7 @@ os.path.join(ROOT, "examples", "zbl"), os.path.join(ROOT, "examples", "programmatic", "use_architectures_outside"), os.path.join(ROOT, "examples", "programmatic", "disk_dataset"), + os.path.join(ROOT, "examples", "basic_usage"), ], "gallery_dirs": [ os.path.join(ROOT, "docs", "src", "examples", "ase"), @@ -27,6 +30,7 @@ os.path.join(ROOT, "docs", "src", "examples", "zbl"), os.path.join(ROOT, "docs", "src", "examples", "programmatic", "use_architectures_outside"), os.path.join(ROOT, "docs", "src", "examples", "programmatic", "disk_dataset"), + os.path.join(ROOT, "docs", "src", "examples", "basic_usage"), ], "min_reported_time": 5, "matplotlib_animations": True, diff --git a/docs/src/getting-started/index.rst b/docs/src/getting-started/index.rst index 6e386f774..475d0fa53 100644 --- a/docs/src/getting-started/index.rst +++ b/docs/src/getting-started/index.rst @@ -7,7 +7,7 @@ This sections describes how to install the package, and its most basic commands. :maxdepth: 1 installation - usage + ../examples/basic_usage/usage custom_dataset_conf advanced_base_config override diff --git a/docs/src/getting-started/usage.rst b/docs/src/getting-started/usage.rst deleted file mode 100644 index 0e4c101e5..000000000 --- a/docs/src/getting-started/usage.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _label_basic_usage: - -Basic Usage -=========== - -``metatrain`` is designed for a direct usage from the command line (cli). The program is -registered via the abbreviation ``mtt`` to your command line. The general help of -``metatrain`` can be accessed using - -.. code-block:: bash - - mtt --help - -We now demonstrate how to ``train`` and ``evaluate`` a model from the command line. For -this example we use the :ref:`architecture-soap-bpnn` architecture and a subset of the -`QM9 dataset `_. You can obtain the reduced -dataset from our :download:`website <../../static/qm9/qm9_reduced_100.xyz>`. - -Training -######## - -To train models, ``metatrain`` uses a dynamic override strategy for your training -options. We allow a dynamical composition and override of the default architecture with -either your custom ``options.yaml`` and even command line override grammar. For -reference and reproducibility purposes ``metatrain`` always writes the fully -expanded, including the overwritten option to ``options_restart.yaml``. The restart -options file is written into a subfolder named with the current *date* and *time* inside -the ``output`` directory of your current training run. - -The sub-command to start a model training is - -.. code-block:: bash - - mtt train - -To train a model you have to define your options. This includes the specific -architecture you want to use and the data including the training systems and target -values - -The default model and training hyperparameter for each model are listed in their -corresponding documentation page. We will use these minimal options to run an example -training using the default hyperparameters of an SOAP BPNN model - -.. literalinclude:: ../../static/qm9/options.yaml - :language: yaml - -For each training run a new output directory in the format -``outputs/YYYY-MM-DD/HH-MM-SS`` based on the current *date* and *time* is created. We -use this output directory to store checkpoints, the restart ``options_restart.yaml`` -file as well as the log files. To start the training, create an ``options.yaml`` file in -the current directory and type - -.. literalinclude:: ../../../examples/basic_usage/usage.sh - :language: bash - :lines: 3-10 - -After the training has finished, the ``mtt train`` command generates the ``model.ckpt`` -(final checkpoint) and ``model.pt`` (exported model) files in the current directory, as -well as in the ``output/YYYY-MM-DD/HH-MM-SS`` directory. - - -Evaluation -########## - -The sub-command to evaluate an already trained model is - -.. code-block:: bash - - mtt eval - -Besides the trained ``model``, you will also have to provide a file containing the -system and possible target values for evaluation. The system section of this -``eval.yaml`` is exactly the same as for a dataset in the ``options.yaml`` file. - -.. literalinclude:: ../../static/qm9/eval.yaml - :language: yaml - -Note that the ``targets`` section is optional. If the ``targets`` section is present, -the function will calculate and report RMSE values of the predictions with respect to -the real values as loaded from the ``targets`` section. You can run an evaluation by -typing - -.. literalinclude:: ../../../examples/basic_usage/usage.sh - :language: bash - :lines: 12-27 - -An important parameter of ``mtt eval`` is the ``-b`` (or ``--batch-size``) option, -which allows you to specify the batch size for the evaluation. - -Molecular simulations -##################### - -The trained model can also be used to run molecular simulations. -You can find how in the :ref:`tutorials` section. diff --git a/examples/basic_usage/usage.sh b/examples/basic_usage/usage.sh index b4986838d..a685c6c3e 100755 --- a/examples/basic_usage/usage.sh +++ b/examples/basic_usage/usage.sh @@ -1,27 +1,124 @@ -#!\bin\bash +# .. _label_basic_usage: +# +# Basic Usage +# =========== +# +# ``metatrain`` is designed for a direct usage from the command line (cli). The program +# is registered via the abbreviation ``mtt`` to your command line. The general help of +# ``metatrain`` can be accessed using +# + +mtt --help + +# %% +# +# We now demonstrate how to ``train`` and ``evaluate`` a model from the command line. +# For this example we use the :ref:`architecture-soap-bpnn` architecture and a subset of +# the `QM9 dataset `_. You can obtain the +# reduced dataset from our :download:`website <../../../static/qm9/qm9_reduced_100.xyz>`. +# +# Training +# -------- +# +# To train models, ``metatrain`` uses a dynamic override strategy for your training +# options. We allow a dynamical composition and override of the default architecture +# with either your custom ``options.yaml`` and even command line override grammar. For +# reference and reproducibility purposes ``metatrain`` always writes the fully expanded, +# including the overwritten option to ``options_restart.yaml``. The restart options file +# is written into a subfolder named with the current *date* and *time* inside the +# ``output`` directory of your current training run. +# +# The sub-command to start a model training is +# +# .. code-block:: bash +# +# mtt train +# +# To train a model you have to define your options. This includes the specific +# architecture you want to use and the data including the training systems and target +# values +# +# The default model and training hyperparameter for each model are listed in their +# corresponding documentation page. We will use these minimal options to run an example +# training using the default hyperparameters of an SOAP BPNN model +# +# .. literalinclude:: ../../../static/qm9/options.yaml +# :language: yaml +# +# For each training run a new output directory in the format +# ``outputs/YYYY-MM-DD/HH-MM-SS`` based on the current *date* and *time* is created. We +# use this output directory to store checkpoints, the restart ``options_restart.yaml`` +# file as well as the log files. To start the training, create an ``options.yaml`` file +# in the current directory and type + mtt train options.yaml +# %% +# # The functions saves the final model `model.pt` to the current output folder for later -# evaluation. An `extensions/` folder, which contains the compiled extensions for the model, -# might also be saved depending on the architecture. -# All command line flags of the train sub-command can be listed via +# evaluation. An `extensions/` folder, which contains the compiled extensions for the +# model, might also be saved depending on the architecture. All command line flags of +# the train sub-command can be listed via +# mtt train --help +# %% +# +# After the training has finished, the ``mtt train`` command generates the +# ``model.ckpt`` (final checkpoint) and ``model.pt`` (exported model) files in the +# current directory, as well as in the ``output/YYYY-MM-DD/HH-MM-SS`` directory. +# +# Evaluation +# ---------- +# +# The sub-command to evaluate an already trained model is +# +# .. code-block:: bash +# +# mtt eval +# +# Besides the trained ``model``, you will also have to provide a file containing the +# system and possible target values for evaluation. The system section of this +# ``eval.yaml`` is exactly the same as for a dataset in the ``options.yaml`` file. +# +# .. literalinclude:: ../../../static/qm9/eval.yaml +# :language: yaml +# +# Note that the ``targets`` section is optional. If the ``targets`` section is present, +# the function will calculate and report RMSE values of the predictions with respect to +# the real values as loaded from the ``targets`` section. You can run an evaluation by +# typing +# # We now evaluate the model on the training dataset, where the first arguments specifies -# trained model and the second an option file containing the path of the dataset for evaulation. -# The extensions of the model, if any, can be specified via the `-e` flag. +# trained model and the second an option file containing the path of the dataset for +# evaulation. The extensions of the model, if any, can be specified via the ``-e`` flag. mtt eval model.pt eval.yaml -e extensions/ +# %% +# # The evaluation command predicts those properties the model was trained against; here -# "U0". The predictions together with the systems have been written in a file named +# ``"U0"``. The predictions together with the systems have been written in a file named # ``output.xyz`` in the current directory. The written file starts with the following # lines head -n 20 output.xyz +# %% +# # All command line flags of the eval sub-command can be listed via mtt eval --help + +# %% +# +# An important parameter of ``mtt eval`` is the ``-b`` (or ``--batch-size``) option, +# which allows you to specify the batch size for the evaluation. +# +# Molecular simulations +# --------------------- +# +# The trained model can also be used to run molecular simulations. +# You can find how in the :ref:`tutorials` section. diff --git a/tox.ini b/tox.ini index ece15bb69..c2c35004a 100644 --- a/tox.ini +++ b/tox.ini @@ -156,6 +156,7 @@ commands_pre = bash -c "set -e && cd {toxinidir}/examples/ase && bash train.sh" bash -c "set -e && cd {toxinidir}/examples/programmatic/llpr && bash train.sh" bash -c "set -e && cd {toxinidir}/examples/zbl && bash train.sh" +commands = sphinx-build \ {posargs:-E} \ --builder html \ From 4f598e1cb6f15fe8fc71e5363d7cd109fea2f247 Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Tue, 13 May 2025 14:11:22 +0200 Subject: [PATCH 2/2] move bash calls into commands --- tox.ini | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index c2c35004a..df96b1127 100644 --- a/tox.ini +++ b/tox.ini @@ -150,13 +150,12 @@ allowlist_externals = extras = # these models are used in the documentation gap soap-bpnn -commands_pre = +commands = # Run example and usage scripts. bash -c "set -e && cd {toxinidir}/examples/basic_usage && bash usage.sh" bash -c "set -e && cd {toxinidir}/examples/ase && bash train.sh" bash -c "set -e && cd {toxinidir}/examples/programmatic/llpr && bash train.sh" bash -c "set -e && cd {toxinidir}/examples/zbl && bash train.sh" -commands = sphinx-build \ {posargs:-E} \ --builder html \