From 497a74e769293f20ebd40619aa7818d1df14d6f3 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 30 Jan 2024 12:02:39 +0000 Subject: [PATCH] example: extending workflow --- .../etc/examples/extending-workflow/.validate | 80 +++++++++++++++++++ .../etc/examples/extending-workflow/index.rst | 77 ++++++++++++++++++ .../extending-workflow/simple/flow.cylc | 24 ++++++ 3 files changed, 181 insertions(+) create mode 100755 cylc/flow/etc/examples/extending-workflow/.validate create mode 100644 cylc/flow/etc/examples/extending-workflow/index.rst create mode 100644 cylc/flow/etc/examples/extending-workflow/simple/flow.cylc diff --git a/cylc/flow/etc/examples/extending-workflow/.validate b/cylc/flow/etc/examples/extending-workflow/.validate new file mode 100755 index 00000000000..43c810372ce --- /dev/null +++ b/cylc/flow/etc/examples/extending-workflow/.validate @@ -0,0 +1,80 @@ +#!/bin/bash +# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE. +# Copyright (C) NIWA & British Crown (Met Office) & Contributors. +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +set -eux + +test_simple () { + local ID + ID="$(< /dev/urandom tr -dc A-Za-z | head -c6)" + + # lint + cylc lint ./simple + + # copy into a temp directory + local SRC_DIR + SRC_DIR="$(mktemp -d)" + cp simple/flow.cylc "$SRC_DIR" + + # speed things up with simulation mode + cat >>"${SRC_DIR}/flow.cylc" <<__HERE__ + [runtime] + [[root]] + [[[simulation]]] + default run length = PT0S +__HERE__ + + # start the workflow + cylc vip \ + --check-circular \ + --no-run-name \ + --no-detach \ + --workflow-name "$ID" \ + --mode=simulation \ + "$SRC_DIR" + + # it should have reached the 2002 cycle + grep '2002/a' "${HOME}/cylc-run/${ID}/log/scheduler/log" + if grep '2003/a' "${HOME}/cylc-run/${ID}/log/scheduler/log"; then + exit 1 + fi + + # edit the "stop after cycle point" + sed -i \ + 's/stop after cycle point.*/stop after cycle point = 2004/' \ + "${SRC_DIR}/flow.cylc" + + # continue the run + cylc vr \ + --no-detach \ + --mode=simulation \ + --yes \ + "$ID" + + # it should have reached the 2004 cycle + grep '2004/a' "${HOME}/cylc-run/${ID}/log/scheduler/log" + if grep '2005/a' "${HOME}/cylc-run/${ID}/log/scheduler/log"; then + exit 1 + fi + + # clean up + cylc clean "$ID" + + rm -r "${SRC_DIR}" +} + + +test_simple diff --git a/cylc/flow/etc/examples/extending-workflow/index.rst b/cylc/flow/etc/examples/extending-workflow/index.rst new file mode 100644 index 00000000000..c5bc023dc11 --- /dev/null +++ b/cylc/flow/etc/examples/extending-workflow/index.rst @@ -0,0 +1,77 @@ +Extending Workflow +================== + +.. cylc-scope:: flow.cylc[scheduling] + +Sometimes we may run a workflow to :term:`completion `, +but subsequently wish to run it for a few more cycles. + +With Cylc 7 this was often done by changing the `final cycle point` and +restarting the workflow. This approach worked, but was a little awkward. +It's possible with Cylc 8, but we would recommend moving away from this +pattern instead. + +The recommended approach to this problem (Cylc 6+) is to use the +`stop after cycle point` rather than the `final cycle point`. + +The `stop after cycle point` tells Cylc to **stop** after the workflow passes +the specified point, whereas the `final cycle point` tells Cylc that the +workflow **finishes** at the specified point. + +When a workflow **finishes**, it is a little awkward to restart as you have to +tell Cylc which tasks to continue on from. The `stop after cycle point` +solution avoids this issue. + + +Example +------- + +.. admonition:: Get a copy of this example + :class: hint + + .. code-block:: console + + $ cylc get-resources examples/extending-workflow/simple + +This workflow will stop at the end of the ``2002`` cycle: + +.. literalinclude:: simple/flow.cylc + :language: cylc + +After it has run and shut down, change the `stop after cycle point` to +the desired value and restart it. E.g: + +.. code-block:: bash + + # install and run the workflow: + cylc vip + + # then later edit "stop after cycle point" to "2004" + + # then reinstall and restart the workflow: + cylc vr + +The workflow will continue from where it left off and run until the end of the +``2004`` cycle. Because the workflow never hit the `final cycle point` it +never "finished" so no special steps are required to restart the workflow. + +You can also set the `stop after cycle point` when you start the workflow: + +.. code-block:: bash + + cylc play --stop-cycle-point=2020 myworkflow + +Or change it at any point whilst the workflow is running: + +.. code-block:: bash + + cylc stop myworkflow//2030 # change the stop after cycle point to 2030 + +.. note:: + + If you set the `stop after cycle point` on the command line, this value will + take precedence over the one in the workflow configuration. Use + ``cylc play --stop-cycle-point=reload`` to restart the workflow using the + `stop after cycle point` configured in the workflow configuration. + +.. cylc-scope:: diff --git a/cylc/flow/etc/examples/extending-workflow/simple/flow.cylc b/cylc/flow/etc/examples/extending-workflow/simple/flow.cylc new file mode 100644 index 00000000000..2de2f28f2ea --- /dev/null +++ b/cylc/flow/etc/examples/extending-workflow/simple/flow.cylc @@ -0,0 +1,24 @@ +[meta] + title = "Basic extendable workflow" + description = """ + Use the "stop after cycle point" rather than the "final cycle point" + to allow this workflow to be easily extended at a later date. + """ + +[scheduler] + # use the year for the cycle point + # (strip off the month, day, hour and minute) + cycle point format = CCYY + +[scheduling] + initial cycle point = 2000 + stop after cycle point = 2002 # stop after two years of simulated time + [[graph]] + P1Y = """ + z[-P1Y] => a + a => z + """ + +[runtime] + [[a]] + [[z]]