Clock Triggered Tasks

In a datetime cycling workflow the time represented by the cycle points bear no relation to the real-world time. Using clock-triggers we can make tasks wait until their cycle point time before running.

Clock-triggering effectively enables us to tether the “cycle time” to the “real world time” which we refer to as the wallclock time.

Note

Clock triggers are External Triggers. They differ from custom external triggers only in that they are provided with Cylc, and that the :interval suffix has no effect.

Clock Triggering

When clock-triggering tasks we can use different offsets to the cycle time as follows:

my_clock_trigger = wall_clock(offset=<iso8601 duration>)

Note

Regardless of the offset used, the task still belongs to the cycle from which the offset has been applied.

Example

Our example workflow will simulate a clock chiming on the hour.

Within your ~/cylc-src directory create a new directory called clock-trigger:

mkdir ~/cylc-src/clock-trigger
cd ~/cylc-src/clock-trigger

Paste the following code into a flow.cylc file:

[scheduling]
    initial cycle point = TODO
    final cycle point = +P1D # Run for one day
    [[graph]]
        PT1H = bell

[runtime]
    [[root]]
        [[[events]]]
            mail events = failed
    [[bell]]
        script = printf 'bong%.02d\n' $(seq 1 $(cylc cyclepoint --print-hour))

Change the initial cycle point to 00:00 this morning (e.g. if it was the first of January 2000 we would write 2000-01-01T00Z).

We now have a simple workflow with a single task that prints “bong” a number of times equal to the (cycle point) hour.

Run your workflow using:

cylc validate .
cylc install
cylc play clock-trigger

Stop the workflow after a few cycles using cylc stop --now --now clock-trigger. Notice how the tasks run as soon as possible rather than waiting for the actual time to be equal to the cycle point.

Clock-Triggering Tasks

We want our clock to only ring in real-time rather than the simulated cycle time.

To do this, modify the [scheduling][graph] section of your flow.cylc:

PT1H = @wall_clock  => bell

This tells the workflow to clock trigger the bell task with a cycle offset of 0 hours.

Save your changes, install and run your workflow.

Your workflow should now be running the bell task in real-time. Any cycle times that have already passed (such as the one defined by initial cycle time) will be run as soon as possible, while those in the future will wait for that time to pass.

At this point you may want to leave your workflow running until the next hour has passed in order to confirm the clock triggering is working correctly. Once you are satisfied, stop your workflow.

By making the bell task a clock triggered task we have made it run in real-time. Thus, when the wallclock time caught up with the cycle time, the bell task triggered.

Adding More Clock-Triggered Tasks

Running clock triggered tests at the cycle time is a special case: We will now modify our workflow to run tasks at quarter-past, half-past and quarter-to the hour.

Open your flow.cylc and modify the [runtime] section by adding the following:

[[quarter_past, half_past, quarter_to]]
    script = echo 'chimes'

Edit the [[scheduling]] section to read:

initial cycle point = now
final cycle point = +P1D # Run for one day
[[xtriggers]]
    quarter_past_trigger = wall_clock(offset=PT15M)
    half_past_trigger = wall_clock(offset=PT30M)
    quarter_to_trigger = wall_clock(offset=PT45M)
[[graph]]
    PT1H = """
        @wall_clock => bell
        @quarter_past_trigger => quarter_past
        @half_past_trigger => half_past
        @quarter_to_trigger => quarter_to
    """

Note the different values used for the cycle offsets of the clock-trigger tasks.

Save your changes, install and run your workflow using:

cylc validate .
cylc install
cylc play clock-trigger

Note

Setting initial cycle point = now will run your workflow using the current time at startup as the initial cycle point.

Again, notice how the tasks trigger until the current time is reached.

Leave your workflow running for a while to confirm it is working as expected before stopping it.

Summary

For more information see the Cylc User Guide.