diff --git a/doc/sphinx/source/utils/RTW/add_a_recipe.rst b/doc/sphinx/source/utils/RTW/add_a_recipe.rst index 6e495e1f1c..954b518a36 100644 --- a/doc/sphinx/source/utils/RTW/add_a_recipe.rst +++ b/doc/sphinx/source/utils/RTW/add_a_recipe.rst @@ -3,116 +3,141 @@ How to add a recipe to the |RTW| .. include:: common.txt -.. note:: - Before you follow these steps to add your recipe, you must be able to - successfully run the recipe with the latest version of ESMValTool on the - compute server you use at your site, as detailed by the ``platform`` option - in the ``[[COMPUTE]]`` section in the site-specific ``.cylc`` file in the - ``esmvaltool/utils/recipe_test_workflow/site/`` directory. +Overview +-------- -#. Open a `new ESMValTool issue`_ on GitHub, assign yourself to the issue, and - add the ``Recipe Test Workflow (RTW)`` label to the issue, see - `ESMValTool issue #3663`_ for an example. +To add a recipe to the |RTW| you will: -#. Create a branch. +* Run the recipe at your site +* Note the actual duration and memory usage +* Edit your site's recipe file +* Create the recipe's KGOs +* Request a review -#. Obtain the duration and memory usage of the recipe from the messages printed - to screen, or at the end of the ``run/main_log.txt`` file in the recipe - output directory after running your recipe on the compute cluster you use at - your site; these messages will look something like:: +The recipe will then run at your site whenever the |RTW| is run. - YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Time for running the recipe was: 0:02:13.334742 - YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Maximum memory used (estimate): 2.4 GB - [...] - YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Run was successful +Preparation +----------- -#. Add the recipe to the ``[task parameters]`` section in the - ``esmvaltool/utils/recipe_test_workflow/flow.cylc`` file. +#. Open a `new ESMValTool issue`_ on GitHub. Assign yourself to the issue and + add the ``Recipe Test Workflow (RTW)`` label. `ESMValTool issue #3663`_ + provides an example. - .. hint:: - If the recipe takes less than 10 minutes to run then it should be added - to the ``fast`` option. Recipes that take longer than ten minutes should - be added to the ``medium`` option. +#. Create a branch. + +#. Run the recipe: + + * with the latest version of ESMValTool + * on the compute server you use at your site .. hint:: - The line added should follow the format of ``recipe_new_recipe, \``, - unless the line is the last one in the list, in which case the line added - should follow the format of ``recipe_new_recipe``. - -#. If the duration of the recipe is larger than the value specified by the - ``execution time limit`` option in the ``[[COMPUTE]]`` section in the - aforementioned site-specific ``.cylc`` file, and / or the memory usage of - the recipe is larger than the value specified by the ``--mem`` option in the - ``[[[directives]]]`` section in the ``[[COMPUTE]]`` section, add a section - (in alphabetical order) to this file as shown below (round the duration to - the nearest second):: - - [[process]] - # Actual: 0m31s, 2.5 GB on 2024-04-08. - execution time limit = PT2M - [[[directives]]] - --mem = 3G + Your compute server is defined in the + ``esmvaltool/utils/recipe_test_workflow/site/.cylc`` file as + follows:: + + [[COMPUTE]] + platform = + +#. Obtain the actual duration and memory usage of the recipe. This can be found + either in the message printed to screen, or at the end of the + ``run/main_log.txt`` file in the recipe output directory. The relevant lines will + look something like:: + + YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Time for running the recipe was: 0:02:13.334742 + YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Maximum memory used (estimate): 2.4 GB + [...] + YYYY-MM-DD HH:MM:SS:sss UTC [12345] INFO Run was successful + +Adding the recipe +----------------- + +#. Add the recipe in alphabetical order to either ``FAST_RECIPES`` or + ``MEDIUM_RECIPES`` in the ``-recipes.jinja`` file. It should look + something like:: + + { + 'recipe_path': 'recipe_a_fast_recipe', + 'actual': '2m13s, 2.4 GB on YYYY-MM-DD', + 'max_time': 'PT3M', + 'max_memory': '3G', + } + + .. important:: + Add the recipe to ``FAST_RECIPES`` if it takes *less* than 10 mins to + run at your site. Add the recipe to ``MEDIUM_RECIPES`` if it takes *more* + than 10 mins. .. hint:: - The ``fast`` key in the example task definition above - (``[[process]]``) should match name of the - option the recipe was added to in the ``[task parameters]`` section in - the ``esmvaltool/utils/recipe_test_workflow/flow.cylc`` file + The :ref:`site/site-recipes.jinja `. + file provides more information. .. hint:: - Set the ``execution time limit`` to 10-20% more than the actual duration. - For actual durations of up to ``1m45s``, set the ``execution time limit`` - to ``PT2M`` (2 minutes). + Set the ``max_time`` to 10-20% more than the actual duration. For actual + durations of up to ``1m45s``, set ``max_time`` to ``PT2M`` (2 minutes). .. hint:: Try not to regularly waste more than 500 MiB in memory usage. Typically, rounding the actual memory usage up to the nearest integer is acceptable. -#. Stop any running ``recipe_test_workflow`` workflows:: - - cylc stop recipe_test_workflow/* +Create the |KGOs| +----------------- #. Run the |RTW|, as detailed in the :ref:`quick_start_guide`; it is expected that the ``compare`` task will fail. -#. Update the Known Good Outputs (|KGOs|): + .. important:: + The ``compare`` task fails because the |KGOs| for the recipe do not yet + exist. This run of the |RTW| will generate the outputs that will be + used as |KGOs|. - * Recursively copy the recipe output directory (i.e. - ``recipe___