diff --git a/docs/source/usage.rst b/docs/source/usage.rst index a9828711..aeb94ac4 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -25,18 +25,23 @@ Experiment names and metadata ----------------------------- The *laboratory* contains the following subdirectories: + * ``work``, which is where the model is run. This contains a temporary directory for each experiment which is removed after a successful run. -* ``archive``, which is where the output of completed runs is stored for each -experiment. + +* ``archive``, which contains the output of completed runs for each +experiment. An experiment name is used identify the experiment inside the ``work`` and ``archive`` sub-directories. This is stored in a metadata file, ``metadata.yaml``, in the *control directory*. The experiment name and a UUID, to uniquely identify the experiment, is set in ``metadata.yaml`` when: + * Using payu to clone a pre-existing git_ repository of the *control directory* + * Using payu to create and checkout a new git branch in the *control directory* + * Or, it is set automatically when setting up an experiment run if there is not a pre-existing metadata file. @@ -47,10 +52,13 @@ git branches and ensure uniqueness in shared archives, the branch name and a short version of the experiment UUID are added to new experiment names. For example, given a control directory named ``my_expt`` and a UUID of ``9fAsTc4sNYsH2ZBQGYK9TG``, the experiment name would be: + * ``my_expt-perturb-9fAsT`` - if running an experiment on a branch named ``perturb``. + * ``my_expt-9fAsT`` - if the control directory was not a git repository or running experiments from the ``main`` or ``master`` branch. + * or ``my_expt`` - if running an older experiment that has a pre-existing archive.