Below you will find help on a variety of different topics


Cylc7 syntax guidance



Early in 2017 year cylc 7 was released. With the new version there were some subtle changes to the suite.rc syntax with some of the more historic syntax being formally retired. This guide will quickly take you through some of the changes needed to upgrade your suite to cylc 7. In the majority of cases these changes should be relatively straight forward to apply and fall into two areas:

A short example follows of the changes you should apply:

Old syntax
[cylc]
    [[event hooks]]
        shutdown handler = rose suite-hook --mail   # Email on shutdown
        timeout handler = rose suite-hook --mail --shutdown
        timeout = P3D
# ...
[runtime]
    [[t1]]
        command scripting = true
        retry delays = PT15M,PT1H,PT6H
        [[[job submission]]]
            method = pbs
            retry delays = 2*PT30S,PT5M,PT15M,PT30M,PT1H
        [[[directives]]]
            -q = shared
            -l walltime = 70
        [[[event hooks]]]
            retry handler = rose suite-hook --mail
            submission retry handler = rose suite-hook --mail
            submission timeout handler = rose suite-hook --mail
            execution timeout handler = rose suite-hook --mail
            failed handler = rose suite-hook --mail
            submission failed handler = rose suite-hook --mail
            submission timeout = P1D
            execution timeout = PT3H

New (cylc-6.11.0 or above) syntax
[cylc]
    # Default settings for suite events, only set to override
    [[events]]
        # abort on inactivity = True
        # abort on timeout = True
        # inactivity = P30D
        # mail events = inactivity, stalled, timeout
        # timeout = P3D
# ...
[runtime]
    [[t1]]
        script = true
        # Ditto for init-script, env-script, pre-script, post-script
        [[[job]]]
            batch system = pbs
            execution retry delays = PT15M,PT1H,PT6H
            submission retry delays = 2*PT30S,PT5M,PT15M,PT30M,PT1H
            execution time limit = PT70S
        [[[directives]]]
            -q = shared
        [[[events]]]
            mail events = retry, submission retry, failed, submission failed, submission timeout, timeout
            submission timeout = P1D

Validate your suite in cylc 7

If your suite is not running, you can install and validate it on your desktop using rose suite-run -l. You will need to do this using cylc-7, depending on how you have cylc installed you may wish to use the CYLC_VERSION and ROSE_VERSION environment variables e.g:

ROSE_VERSION=<rose_version> CYLC_VERSION=<cylc_version> rose suite-run -l
If your suite is running, you can validate the suite.rc.processed file:
CYLC_VERSION=<cylc_version> cylc validate ~/cylc-run/SUITE/suite.rc.processed
If the above does not throw up any error or deprecation warning, then everything is okay with the suite design for cylc 7. However, you may want to have a look at step further to take advantage of the new *execution time limit* setting and take advantage of the new parametrization syntax.

Update command/pre/post/environment scripting

Upgrade command, pre-, post- and environment scripting to newer syntax.

Old syntax 	      | New syntax  | Remark
----------------------|-------------|-------------------------------------------
pre-command scripting |	pre-script  |	
post-command scripting| post-script |	
environment scripting |	env-script  |
initial scripting     | init-script | Usage of this to set ROSE_VERSION etc is no
                      |             | longer necessary, and should be removed.
command scripting     | script 	    |
You should also take the opportunity to check your suite for any deprecated syntax and update accordingly (ignore job submission that'll be addressed in a moment). You should be able to identify deprecated items by running rose suite-run -l and looking for deprecation/upgrade notifications in the output. Examples of deprecated items include (but are not limited to): start-up, cold-start, sequential, initial cycle time, final cycle time.

event hooks

rose suite-hook has been largely redundant for some time now, with functionality being moved into cylc itself to ensure more efficient and robust behaviour. You should move to using cylc for event handlers in your suites.
In an old suite you may have:

[runtime]
    [[root]]
        [[[event hooks]]]
            retry handler = rose suite-hook --mail
            submission retry handler = rose suite-hook --mail
            submission timeout handler = rose suite-hook --mail
            execution timeout handler = rose suite-hook --mail
            failed handler = rose suite-hook --mail
            submission failed handler = rose suite-hook --mail
            ## If you want the suite to shutdown following a failure, you should replace the 2 lines above with:
            # failed handler = rose suite-hook --mail --shutdown
            # submission failed handler = rose suite-hook --mail --shutdown
            # Adjust the values if your suite requires different timeout values.
            submission timeout = P1D
            execution timeout = PT3H


In a new suite should have:
[runtime]
    [[root]]
        [[[events]]]
            mail events = submission retry, submission failed, submission timeout, retry, failed, timeout
            ## If you want the suite to shutdown following a failure, you can do:
            # handlers = cylc shutdown "%(suite)s"
            # handler events = submission failed, failed
            ## If you want to call the os_task_hook routine for events, you can do:
            # handlers = os_suite_hook
            # handler events = ... # list of events that would previously have resulted in
            #                      # os_task_hook being called
            ## The following are default timeout values in our site `global.rc`.
            ## Uncomment and adjust the values if your suite requires different values:
            # submission timeout = P1D
            # execution timeout = PT3H

job submission and retry delays

cylc 6.11.0 has a more powerful and improved syntax for managing job timeouts, wallclock directives and retry delays.
Job directives
Should update to the new syntax:
Using execution time limit generates both the execution timeout and the wallclock time in one go. This has the benefit of helping prevent jobs getting "stuck" as it will poll at the point the job should have exited. Useful e.g. if a job gets lost in the system or hits the wallclock limit and gets hard killed.

In an old suite you may have:

[runtime] 
    [[my_task]] 
        [[[job submission]]]
            method = pbs
        [[[directives]]]
            -l walltime = 00:01:00
            -q = foo 
            -l nodes = 1

In a cylc-6.11.0 or above suite should have:
[runtime] 
    [[my_task]]
        [[[job]]]
            batch system = pbs
            execution time limit = PT1M
        [[[directives]]] 
            -q = foo 
            -l nodes = 1

Important note for "background tasks": If execution time limit is specified for a background task, its job will be wrapped by the timeout command. This is potentially very useful so as to enforce wallclock limits on background jobs, however it may catch people out where default timeouts are defined in, say, the [[root]] family.

Retry delays

Syntax for retry delays has been tweaked. This clears up ambiguity in what a retry delay is being applied to - submission or execution - also helping ensure the right one is configured.



In an old suite you may have:
[runtime]
    [[my_task]]
        retry delays = PT30M
        [[[job submission]]]
            retry delays = 3*PT5M,3*PT15M,3*PT30M

In a cylc-6.11.0 or above suite should have:
[runtime]
    [[my_task]]
        [[[job]]]
            execution retry delays = PT30M
            submission retry delays = 3*PT5M,3*PT15M,3*PT30M

parametrization

At cylc 6.11.0, task parametrization is introduced:
This change is potentially useful to suites with ensemble members generated through jinja2 looping or where there are dependencies of the form:

foo_{{ N }} => bar_{{ N }}
Use of parametrization allows you to reduce the amount of jinja2 in use, making for cleaner suites whose suite.rc.processed files are more readable.


© British Crown Copyright 2006-17 Met Office.
This document is released under the British Open Government Licence.