- active task
An active task is a task in the submitted or running state.
- active-waiting task
An active-waiting task is a task in the scheduler’s
n=0active window that is ready to run according to its task prerequisites, but is still waiting on a limiting mechanism such as a clock trigger, task hold, or internal queue.
- artificial dependency
An artificial dependency in the graph does not reflect real dependence between the tasks involved. This can sometimes be useful but should be avoided if possible. Artificial dependencies muddy the real dependencies of the workflow and they may unnecessarily constrain the scheduler.
In the following cycling workflow, if the task
foodoes not actually depend on any real outputs of
bazin the previous cycle, then the intercycle dependence is artificial.
P1 = """ foo => bar => baz baz[-P1] => foo """
- graph branching
For example, the following workflow follows one of two possible paths depending on the outcome of task
# the success branch a => b? => c # the fail branch b:fail? => r # joining the two branches together c | r => d
- clock trigger
Clock triggers connect cycle points to the wallclock time, in datetime cycling workflows. Tasks that depend on a clock trigger will not trigger until the wallclock time is equal to their cycle point plus or minus some offset.
- cold start
This is the default behaviour of
cylc playfor an installed workflow that hasn’t run yet.
To satisfy unbounded intercycle dependence in the graph, tasks prior to the initial cycle point are treated as if they have succeeded.
- conditional dependence
- conditional dependency
- conditional trigger
a & (b:fail | c) => d
The left hand side of a conditional dependency can be called a conditional trigger.
- contact file
The contact file, in the service directory, records information about a running scheduler such as host, TCP port, and process ID. It is read by Cylc client commands so they can target the right scheduler.
The contact file is created at scheduler startup and removed on clean shutdown. If you delete it, the scheduler will (after a delay) notice this and shut down.
If the scheduler dies in an uncontrolled way, for example if the process is killed or the host goes down, the contact file may be left behind. Some Cylc commands automatically detect these files and remove them, otherwise they should be manually removed.
- custom output
A custom task output is a user-defined task output that marks an event runtime event between task job start and finish. To complete a custom output, the job must send a message defined in the
flow.cylcfile to the scheduler.
Triggers based on custom outputs are called message triggers.
[runtime] [[foo]] [[[outputs]]] # output name = output message out1 = "Output 1 completed" out2 = "Output 2 completed"
This defines the structure of the graph. At runtime, however, Cylc does not impose a global loop over cycles. Each individual task, with its own cycle point, advances according to its own dependencies.
- cycle point
The unique label given to tasks that belong to a particular cycle. For integer cycling these will be integers, e.g.
3, etc. For datetime cycling they will be ISO 8601 datetimes, e.g.
- cycle point time zone
The time zone used for task cycle points.
- cycling workflow
- cylc-run directory
This refers to the top level directory for installed workflows:
Cylc can be configured to symlink cylc-run sub-directories to other locations.
The cylc-run directory should not be confused with specific workflow run directories below it.
- datetime cycling
For example, in the following dependency the task
bazdepends on both
foo & bar => baz
- exact datetime unit
An exact datetime unit is any unit of a datetime that has a fixed duration, which does not depend on its position in the calendar. In Cylc, the following are exact units:
second: SI base unit
minute: 60 seconds
hour: 60 minutes
day: 24 hours
week: 7 days
Although the ISO 8601 standard specifies that weeks and days are inexact due to the possibility of daylight saving time, leap seconds etc., they are always exact in Cylc because workflows always maintain the same time zone, and leap seconds are not supported.
- external trigger
The scheduler can repeatedly call a user-supplied Python function to check that the external event has occurred.
Cylc has a built in external trigger for triggering off of events in other workflows.
By convention, family names are upper case, with the exception of the special
rootfamily that all tasks inherit from.
- family trigger
Family triggers take the form
family-name:qualifier, where the qualifier describes the collective state of member tasks needed for the dependency to be met. Some commonly used qualifiers are:
All members succeeded.
Any one member succeeded.
All members failed.
All members finished (succeeded or failed).
- final cycle point
Cylc schedulers can manage multiple flows at once.
Flows are identified by a flow number. The original flow started automatically by
cylc playhas flow number
- flow front
- flow merge
- flow number
Flow numbers are integers passed down from parent task to child task in the graph as a flow progresses, to identify which flow (or flows) the tasks belong to. They are passed to job environments as
- future trigger
A future trigger expresses dependence on a task in a “future” (higher-valued) cycle point.
1/bartriggers off of
2/bartriggers off of
3/foo; and so on:
[scheduling] initial cycle point = 1 cycling mode = integer [[graph]] P1 = "foo[+P1] => bar"
For example, the following is, collectively, a graph:
P1D = foo => bar PT12H = baz
- graph string
The example below shows one graph string in a datetime cycling workflow, with a daily cycle point sequence:
R/^/P1D = """ foo => bar => baz & pub => qux pub => bool """
- event handler
- event handlers
Send an email message.
Run a Cylc command.
Run any user-specified script or command.
- held task
- hold after cycle point
It is also possible to set a “hold after cycle point”; all tasks after this cycle point will be held.
- implicit task
Implicit tasks submit real jobs that just exit without doing anything useful. They may be useful placeholders during workflow development but are not allowed by default because they can be created accidentally by simply misspelling a task name in the graph or under
[scheduling] [[graph]] R1 = foo & bar [runtime] [[foo]] # eof
In Cylc 7 and earlier, implicit tasks were known as “naked dummy tasks”.
- incomplete task
Incomplete tasks are tasks that finish (succeed or fail) without completing all required outputs. They are retained by the scheduler in the n=0 window pending user intervention, and will cause a stall if there are no more tasks to run.
- inexact datetime unit
- nominal duration
An inexact datetime unit is any unit of a datetime that does not have a fixed duration; it instead depends on its position in the calendar. In Cylc, the following are inexact units (when using the Gregorian calendar):
year: either 365 or 366 days depending on whether it is a leap year
month: between 28 - 31 days depending on the specific month and year
- initial cycle point
- workflow installation
- integer cycling
- intercycle dependence
- intercycle dependency
- intercycle trigger
For example, in the following workflow the task
bardepends on its own previous instance:
[scheduling] initial cycle point = 1 cycling mode = integer [[graph]] P1 = """ foo => bar => baz bar[-P1] => bar """
- ISO 8601
- ISO 8601 datetime
- ISO8601 datetime
A datetime written in the ISO 8601 format, e.g:
2000-01-01T00:00Z: midnight on the 1st of January 2000, UTC.
- ISO 8601 duration
- ISO8601 duration
A duration written in the ISO 8601 format e.g:
PT1H30M: one hour and thirty minutes.
- job host
[platforms] [[my_hpc]] hosts = node_1, node_2 job runner = slurm
[runtime] [[solver]] platform = my_hpc
- job log
- job log directory
The task job script.
Job status data in case of lost contact with the scheduler.
Job data logged by the scheduler, rather than the job itself, such as output from the job submission command.
Debugging information from Bash captured when Cylc is run in
You can print task job logs at the terminal with
cylc cat-log <workflow-name> <task-id>. By default this prints
job.out. There are command options to select the other logs.
- job runner
Cylc supports various job runners, from direct background process execution to HPC batch queueing systems like PBS and Slurm (these are also known as job schedulers and resource managers).
Job runners are configured on a per-platform basis in
In Cylc 7 and earlier, job runners were referred to as “batch systems”.
- job script
A Cylc job script is a file containing bash code to implement a task definition in a workflow. It prepared and submitted to run by the scheduler when the task is ready to run.
Job scripts can be found in the task job log directory.
- job submission number
- message trigger
For brevity, the trigger in the graph uses the output name, not the full message:
[scheduling] [[graph]] R1 = """ foo:out1 => proc-out-1 foo:out2 => proc-out-2 """ [runtime] [[foo]] script = """ # ... cylc message "Output 1 completed" # ... cylc message "Output 2 completed" """ [[[outputs]]] # output name = output message out1 = "Output 1 completed" out2 = "Output 2 completed"
However, if you don’t need a descriptive message for the workflow log, you can make the message the same as its name:
[[[outputs]]] out1 = out1
- optional output
Optional task outputs are marked with a question mark in the graph, e.g.
foo:succeed?). The may or may not be completed at runtime. Optional outputs are primarily used for graph branching.
This can be useful if you want to make a change to a running workflow.
Pause a workflow with
cylc pauseand resume it with
- job platform
my_hpccould be the platform for the task
solverin the following workflow:
[platforms] [[my_hpc]] hosts = node_1, node_2 job runner = slurm
[runtime] [[solver]] platform = my_hpc
- platform group
A set of platforms grouped under a common name.
Platforms are configured by
For example, in
foo:start => bar, the
:startqualifier means that the
startedoutput of task
foomust be completed to satisfy the dependency.
- internal queue
Internal queues (so called to distinguish them from external batch queueing systems) allow you to limit how many tasks can be active (submitted or running) at once, across defined groups of tasks.
Use queues prevent large or busy workflows from swamping their job platforms with too many jobs at once.
It is also possible to remove the “hold after cycle point” if set, using
cylc release --all. This will also release all held tasks.
Remote Initialization will be redone for each job platform, when the first job is submitted there after a reload.
Any task that is active at reload will continue with its pre-reload configuration. It’s next instance (at the next cycle point) will adopt the new configuration.
- required output
- expected output
When a stopped workflow is played again, the scheduler picks up where it left off rather than starting again from scratch. It also detects any orphaned jobs that changed state (e.g. succeeded) while the system was down.
Changes made to the installed
flow.cylcfile will be picked at restart. We recommend that changes are reinstalled from the workflow source directory before restart, rather than made by editing the installed files directly.
- task retry
- try number
Tasks can be configured to retry automatically on failure, one or more times. They return to the
waitingstate with a clock trigger to delay the retry, and only go to the
failedstate once the final try fails.
The task try number increments with every automatic retry, and is passed to the job environment as
- run directory
- workflow run directory
At runtime, task jobs can get their workflow run directory from the environment variable
- runahead limit
In a cycling workflow, the runahead limit determines the maximum number of consecutive cycle points that can be active at once.
- runtime inheritance
- family inheritance
[runtime] [[CHEESE]] [[[environment]]] COLOR = yellow [[cheddar]] inherit = FAMILY
Families can also inherit from other families. All tasks implicitly inherit from a special
rootfamily at the base of the inheritance hierarchy.
Tasks can inherit from multiple families at once using a comma-separated list:
inherit = foo, bar, baz
The Cylc scheduler is a program responsible for managing a single Cylc workflow. It determines when each tasks is ready to run, submits its jobs to selected job runners, tracks job status, maintains the workflow state, and listens for queries and commands from the user.
By default, Cylc schedulers run as daemons (and potentially on a remote host) so they won’t be killed if you log out.
In Cylc 7 and earlier, schedulers were known as “suite daemons”.
- service directory
Cylc automatically creates a share directory inside the workflow run directory as a place to store files that need to be shared between tasks.
Task jobs can get their own share directory path at runtime from the
In cycling workflows files are typically stored in cycle point sub-directories of the share directory.
- source directory
- source workflow
A source directory is any location where workflows are written and stored in preparation for installation with
cylc installor reinstallation with
These locations are configurable. The default is
- stalled workflow
- stalled state
Stalls are usually caused by unexpected task failures:
In this example the task
barhas failed, so that
bazcannot run, but
bar:failwas not marked as an optional output.
User intervention is required to fix a stall, e.g. by retriggering incomplete tasks after fixing the problems that caused them to fail.
- standard output
This refers to starting a new instance of the Cylc scheduler program to manage a particular workflow. This can be from scratch, for installed workflows that haven’t run previously, or to restart one that shut down prior to completion.
- start cycle point
This may be at or after the initial cycle point.
- start task
Earlier tasks depended on by start tasks are treated as if they have succeeded.
Cylc 7 and earlier did not have the capability to start from any task in the graph.
By default, the scheduler waits for any submitted or running task jobs to finish (either succeed or fail) before shutting down.
- stop cycle point
This may be at or before the final cycle point.
- submit number
- task submit number
Every time a task re-runs, whether by automatic retry or manual triggering, its submit number increments. It is passed to the job environment as
Submit number also appears in the job log path so that job log files don’t get overwritten.
- suicide trigger
They are denoted by exclamation marks, and are triggered like normal dependencies. For instance, the following suicide trigger will remove the task
barfrom the active window if
foo => ! bar
Suicide triggers are not needed in Cylc 8 for graph branching. They are retained for backward compatibility and rare edge cases.
A task represents an activity in a workflow. The workflow definition specifies how tasks depends on other tasks, what they should do, how and where to run them, and details of their runtime environment.
- task output
Task outputs mark the progression of a task from waiting (for prerequisites to be satisfied) through to success or failure at run time. Downstream tasks can trigger off of the outputs of other tasks, as determined by the graph.
Here the task
bardepends on the standard
foo:started => bar
:succeededoutput is usually implicit:
foo => bar # means foo:succeeded => bar
- task parameters
Task parameterisation is one way of consolidating configuration in the
flow.cylcfile. Cylc implicitly loops over ranges or lists of pre-defined parameters to automatically generate sets of similar tasks.
[task parameters] m = 1..3 [scheduling] [[graph]] R1 = bar<m> => baz<m>
- task state
- task trigger
In this example, the task
barcan be said to trigger off of completion of the
foo:started => bar
- workflow validation
Validation parses a
flow.cylcfile to report any illegal items, syntax errors, deprecation warnings, and other problems.
It is done automatically at start up, and should be done manually with the
cylc validatecommand after making changes.
- wallclock time
The actual time (in the real world).
- warm start
To satisfy unbounded intercycle dependence in the graph, tasks prior to the start cycle point are treated as if they have succeeded.
- active window
- workflow window
- active task pool
- work directory
Task jobs can get their own work directory path at runtime from the
CYLC_TASK_WORK_DIRenvironment variable or the Posix
- cylc workflow
Cylc workflows are defined in
For example, the following workflow represents the beer brewing process:
[scheduling] cycling mode = integer initial cycle point = 1 [[graph]] # repeat this for each batch P1 = """ # the stages of brewing in the order they must occur in: malt => mash => sparge => boil => chill => ferment => rack # finish the sparge of one batch before starting the next: sparge[-P1] => mash """
In Cylc 7 and earlier, “workflows” were referred to as “suites”.
- workflow completion
A workflow is deemed complete if there are no more tasks to run, according to the graph, and there are no incomplete task present.
If the workflow is complete, the scheduler will automatically shut down.
If there are no more tasks to run, but there are incomplete tasks present, the scheduler will stall rather than shut down.
- workflow id
This ID is used on the command line and in the GUI, to target the right workflow.
For example, the ID of the workflow in
`- my_workflow |- runN |- run1 # CYLC_WORKFLOW_ID = my_workflow/run1 `- run2 # CYLC_WORKFLOW_ID = my_workflow/run2
- workflow log
- scheduler log
- workflow log directory
At runtime the scheduler logs timestamped events and other information to files under the workflow run directory. These logs take the format <log-number>-<start/restart>-<start-number>.log, with the latest log being automatically symlinked to
You can print the scheduler log at the terminal with
cylc cat-log <workflow-name>.
- workflow name
The workflow name is a path relative to the cylc-run directory which contains one or more workflow run directories.
Task jobs can get the workflow name from
$CYLC_WORKFLOW_NAMEin their runtime environment.
Unlike workflow id the name is not always a unique identifier. In the example below
run2would both have the same name,
`- my_workflow |- runN |- run1 `- run2
If you are not using named or numbered runs, the workflow name will be the same as workflow id.