From 464dd5aed6dd10bc420fda5bee6161cf392f50b2 Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Mon, 10 Jul 2023 16:03:40 +0200 Subject: [PATCH] Add docs about expids --- docs/source/index.rst | 1 + docs/source/userguide/expids.rst | 61 ++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/source/userguide/expids.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 67658a011..06a425cfd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -43,6 +43,7 @@ Welcome to autosubmit's documentation! /userguide/monitor_and_check/index /userguide/set_and_share_the_configuration/index /userguide/variables + /userguide/expids .. toctree:: :caption: Database Documentation diff --git a/docs/source/userguide/expids.rst b/docs/source/userguide/expids.rst new file mode 100644 index 000000000..977fd5a50 --- /dev/null +++ b/docs/source/userguide/expids.rst @@ -0,0 +1,61 @@ +############### +Experiment ID's +############### + +Autosubmit 4 uses a SQLite database to automatically generate unique +experiment ID’s. The ID’s of Autosubmit experiments start from ``a000`` +and have at least four alpha-numerical characters, using digits from +``0`` to ``9`` and the ``26`` letters from the English alphabet, from ``a`` +to ``z``. + +Internally, experiment ID’s are case insensitive, but for Autosubmit +commands this may not always be true, i.e. ``autosubmit monitor a000`` +works for the experiment ``a000``, but not ``autosubmit monitor A000``, +even though internally both ``a000`` and ``A000`` would be stored the same +way in the SQLite database. + +That is because experiment ID’s are treated as Base-36 strings, being +first decoded into integers with Base-36 (where ``a`` and ``A`` are both equal +to ``10``, ``b`` and ``B`` equal to ``11``, etc. — ``int('a', 36)`` in Python). + +Autosubmit provides functions that could be used by external code to produce +a new experiment, or to simply calculate the next experiment ID, given the +last available experiment ID. The code below shows an example of the latter: + +.. code-block:: python + + from autosubmit.experiment.experiment_common import next_experiment_id + + expid = next_experiment_id('a000’) + print(expid) # prints 'a001’ + + expid = next_experiment_id('jedi’) + print(expid) # prints 'jedj’ + + expid = next_experiment_id('zzzz’) + print(expid) # prints '10000’ + +To generate the next experiment ID, the decoded integer value is incremented +by ``1``, and then re-encoded as a Base-36 string. For example, ``a000`` is decoded +as ``466560``, so the next ID is calculated as ``466560 + 1 = 466561``. Finally, +``466561`` is re-encoded as Base-36, resulting in ``a001``. + +After the default initial experiment ID ``a000``, the next generated experiment +ID is ``a001``, and it keeps being increased automatically by Autosubmit from +``a001``, to ``a002``, ``a003``, …, ``azzz`` and then the next experiment ID ``b000``. + +And the process repeats every time users ask Autosubmit to create a new +experiment. + +Users can create “test experiments” which experiment ID’s start at ``t001``, +and “operational experiments” which experiment ID’s start at ``o001``. +This is done via flags passed to the ``autosubmit expid`` in the command-line. + +There is no other way for users to modify the automatic generation of +experiment ID’s in Autosubmit (other than manually editing the SQLite database). + +The total number of available unique experiment ID’s in Autosubmit with four +characters is ``1213055`` experiment ID’s (the difference between ``a000`` and +``zzzz`` Base-36 decoded as integers). After the experiment ``zzzz``, the next +experiment ID generated by Autosubmit would be ``10000``, followed by ``10001``, +``10002``, and so on successfully. -- GitLab