From 35ab418553d3779592764c189b9a84b0f13d77e6 Mon Sep 17 00:00:00 2001 From: Tim Pillinger <26465611+wxtim@users.noreply.github.com> Date: Thu, 27 Oct 2022 16:19:23 +0100 Subject: [PATCH 1/2] added 2 slides and tutorial giving a brief example of using cylc reinstall & reload Response to Review Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> --- .../configuration-consolidation/index.rst | 2 +- src/tutorial/runtime/index.rst | 1 + src/tutorial/runtime/reinstalling.rst | 155 ++++++++++++++++++ 3 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 src/tutorial/runtime/reinstalling.rst diff --git a/src/tutorial/runtime/configuration-consolidation/index.rst b/src/tutorial/runtime/configuration-consolidation/index.rst index 8b26c8a33b..79e4e26408 100644 --- a/src/tutorial/runtime/configuration-consolidation/index.rst +++ b/src/tutorial/runtime/configuration-consolidation/index.rst @@ -184,4 +184,4 @@ Which Approach To Use .. ifslides:: - Next section: :ref:`Rose Tutorial ` + Next section: :ref:`Reinstalling workflows ` diff --git a/src/tutorial/runtime/index.rst b/src/tutorial/runtime/index.rst index ed68447ac9..4cd09f9e64 100644 --- a/src/tutorial/runtime/index.rst +++ b/src/tutorial/runtime/index.rst @@ -17,3 +17,4 @@ This section covers: introduction runtime-configuration configuration-consolidation/index + reinstalling diff --git a/src/tutorial/runtime/reinstalling.rst b/src/tutorial/runtime/reinstalling.rst new file mode 100644 index 0000000000..a4eaf5802b --- /dev/null +++ b/src/tutorial/runtime/reinstalling.rst @@ -0,0 +1,155 @@ +.. _tutorial.Reinstalling-workflows: + +Fixing and Reloading Workflows +============================== + +.. admonition:: Aim + + Use ``cylc reinstall`` and ``cylc reload`` to repair a broken workflow + configuration without having to run the whole workflow again. + + +.. ifnotslides:: + + Consider a workflow where a a large part of the runtime has completed, + but a late task has failed. + +.. digraph:: workflow + + rankdir="LR" + get_data -> process_data + get_data[ + label="get data\n(very slow)", + color="forestgreen", + fillcolor=palegreen, + style=filled + ] + process_data[ + label="process data", + color="red", + fillcolor=palevioletred, + style=filled + ] + +.. ifnotslides:: + + Having identified the problem with the late task we want to + update the runtime definition of the installed workflow rather than + re-run the whole thing. + + +.. practical:: + + .. rubric:: In this practical we will break the + :ref:`weather-forecasting workflow ` + from the :ref:`scheduling tutorial `. + + #. **Get your own copy of the workflow** + + Use ``cylc get-resources`` to get a new copy of the workflow. + + + .. code-block:: bash + + cylc get-resources tutorial/cylc-forecasting-workflow + cd ~/cylc-src/cylc-forecasting-workflow + + + #. **Break the ``post_process`` task** + + Change the task script for the ``post_process`` task in + ``flow.cylc`` to make it fail: + + .. code-block:: diff + + - script = post-process $CYLC_TASK_PARAM_site 60 + + script = exit 1 + + #. **Install, Play and inspect the workflow** + + And check that ``post_process`` fails. + + .. spoiler:: Step-by-step + + .. code-block:: bash + + cylc validate # always good practice + cylc install + cylc play cylc-forecasting-workflow + # Either view in TUI or GUI, or run: + cylc cat-log cylc-forecasting-workflow + # Inspect job log for failed task: + cylc cat-log cylc-forecasting-workflow///post_process + + +.. nextslide:: + +.. ifnotslides:: + + You can copy any changes in the :term:`source directory` to the + :term:`run directory` using: + +.. code-block:: + + cylc reinstall + +.. ifnotslides:: + + But this does not reload the running workflow. To do that you need to use: + +.. code-block:: bash + + cylc reload + + +.. ifnotslides:: + + .. note:: + + You may prefer to use ``cylc pause`` before reloading the workflow to + make if clearer which tasks were run before and after your changes. + After reinstalling and reloading the workflow use ``cylc play`` to + resume the workflow. + + +.. practical:: + + .. rubric:: In this practical we will fix the workflow we broke in the + first practical, then re-run the broken task. + + #. **Fix the ``post_process`` task** + + Change the task script for the ``post_process`` task in + ``flow.cylc`` to make it pass again: + + .. code-block:: diff + + - script = exit 1 + + script = post-process $CYLC_TASK_PARAM_site 60 + + #. **Use Cylc Reinstall and Reload to fix the workflow** + + .. code-block:: bash + + cylc reinstall cylc-forecasting-workflow + # You can do this in the cylc tui or GUI + cylc reload cylc-forecasting-workflow + cylc trigger cylc-forecasting-workflow///post_process + + #. **Check that the workflow has finished** + + Have a look at the workflow log: + + .. code-block:: + + cylc cat-log cylc-forecasting-workflow + + You should see that ``post_process`` has succeeded: + + .. code-block:: + + INFO - [20221027T1300Z/post_process_exeter running job:02 flows:1] => succeeded + +.. ifslides:: + + Next section: :ref:`Rose Tutorial ` From ff809849f90edabe91c681e03f074181cba2e196 Mon Sep 17 00:00:00 2001 From: Hilary James Oliver Date: Tue, 30 Apr 2024 11:06:06 +1200 Subject: [PATCH 2/2] Update src/tutorial/runtime/reinstalling.rst Co-authored-by: Tim Pillinger <26465611+wxtim@users.noreply.github.com> --- src/tutorial/runtime/reinstalling.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/tutorial/runtime/reinstalling.rst b/src/tutorial/runtime/reinstalling.rst index a4eaf5802b..c4b7281a75 100644 --- a/src/tutorial/runtime/reinstalling.rst +++ b/src/tutorial/runtime/reinstalling.rst @@ -5,8 +5,13 @@ Fixing and Reloading Workflows .. admonition:: Aim - Use ``cylc reinstall`` and ``cylc reload`` to repair a broken workflow - configuration without having to run the whole workflow again. + +... note:: + + This tutorial explores one working practice. You might, alternatively, wish + to use ``cylc shutdown``, ``cylc reinstall`` and ``cylc play`` to modify and restart + an existing workflow. + .. ifnotslides::