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:
- updating from deprecated items
- exploiting more recent improved and more robust functionality
[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 -lIf your suite is running, you can validate the
suite.rc.processed file:
CYLC_VERSION=<cylc_version> cylc validate ~/cylc-run/SUITE/suite.rc.processedIf 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.
This document is released under the British Open Government Licence.