Glossary

active
active task

An active task is a task which is near ready to run, in the process of running, or which requires user intervention. These are all the tasks being actively managed by the scheduler at this point in the run.

Active tasks are:

  • Tasks which have some, but not all of their prerequisites satisfied.

  • waiting tasks, that are actively waiting on:

  • preparing tasks - i.e. tasks in the process of submitting jobs

  • submitted and running tasks - i.e. those with active jobs

  • tasks that reached a final status without completing their required outputs (e.g. a task failed where success was required).

Active tasks are in the n=0 window which means they will always be displayed in the GUI and Tui.

The distinction between active and non-active tasks is important for the computing of the runahead limit.

active cycle

A cycle point is active if it contains any active tasks.

Active cycles are counted towards the runahead limit.

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 foo does not actually depend on any real outputs of baz in the previous cycle, then the intercycle dependence is artificial.

P1 = """
   foo => bar => baz
   baz[-P1] => foo
"""
branching
graph branching

Cylc handles workflow graphs in an event-driven way. It can automatically follow different paths depending on events at runtime. This relies on optional outputs and is called branching.

For example, the following workflow follows one of two possible paths depending on the outcome of task b:

# the success branch
a => b? => c
# the fail branch
b:fail? => r
# joining the two branches together
c | r => d

digraph example { subgraph cluster_success { label = ":succeed" color = "green" fontcolor = "green" style = "dashed" c } subgraph cluster_failure { label = ":fail" color = "red" fontcolor = "red" style = "dashed" r } a -> b -> c -> d b -> r -> d }

clock expire
expired task

Tasks in datetime cycling workflows can be configured to expire if the wallclock time exceeds some offset from the cycle point.

Expired is a final status - an expired task will not run even if its prerequisites get satisfied.

The associated :expire output can be used to trigger other tasks. It must be marked as an optional output, i.e. expiry cannot be required.

See also

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

A cold start is when the scheduler starts a workflow at the beginning of graph. In a cycling workflow this is determined by the initial cycle point.

This is the default behaviour of cylc play for 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

Conditional dependence is when a task depends on a combination of multiple upstream task outputs.

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.

<run-directory>/.service/contact

Warning

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.cylc file 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"
cycle

In a cycling workflow, cycles are repetitions of a graph string. Each cycle is identified by a cycle point. The sequence of cycle points is defined by the graph string’s recurrence pattern.

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.

For example, in the following workflow each dotted box represents a cycle and the tasks within it are the tasks belonging to that cycle. The numbers (i.e. 1, 2, 3) are the cycle points.

digraph Example { size = "3,5" subgraph cluster_1 { label = "1" style = dashed "1/foo" [label="foo\n1"] "1/bar" [label="bar\n1"] "1/baz" [label="baz\n1"] } subgraph cluster_2 { label = "2" style = dashed "2/foo" [label="foo\n2"] "2/bar" [label="bar\n2"] "2/baz" [label="baz\n2"] } subgraph cluster_3 { label = "3" style = dashed "3/foo" [label="foo\n3"] "3/bar" [label="bar\n3"] "3/baz" [label="baz\n3"] } "1/foo" -> "1/bar" -> "1/baz" "2/foo" -> "2/bar" -> "2/baz" "3/foo" -> "3/bar" -> "3/baz" "1/bar" -> "2/bar" -> "3/bar" }

cycle point

The unique label given to tasks that belong to a particular cycle. For integer cycling these will be integers, e.g. 1, 2, 3, etc. For datetime cycling they will be ISO 8601 datetimes, e.g. 2000-01-01T00:00Z.

cycle point time zone

The time zone used for task cycle points.

cycling
cycling workflow

A cycling workflow in Cylc is defined by a graph of repeating tasks with individual cycle points.

See also

cylc-run directory

This refers to the top level directory for installed workflows: ~/cylc-run.

Cylc can be configured to symlink cylc-run sub-directories to other locations.

Caution

The cylc-run directory should not be confused with specific workflow run directories below it.

datetime cycling

A datetime cycling workflow uses ISO 8601 datetime cycle points (e.g. 2000-01-01T00:00Z) and recurrences (e.g. P3D means every third day).

directive

Directives request task jobs resources such as memory and node count from external job runners. They are job runner-specific.

dummy mode

A workflow run mode that replaces all tasks with dummy tasks. See Dummy Mode.

dummy task

A task which runs a trivially simple script such as sleep 1, exit 0 or true, or which uses Skip Mode to avoid running a script at all.

event

An event is a milestone in the lifecycle of a workflow or task at which the scheduler provides a hook for attaching event handlers.

Workflow events include startup, stall, and shutdown.

Task events include task state changes, to running or failed, for example, or when the scheduler receivers CRITICAL or WARNING messages from a task job.

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

Note

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
xtrigger

External triggers allow tasks in the graph to depend on external events, such as a file being delivered to some location, or a database being updated in some way.

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.

family

In Cylc a family is a collection of tasks that share common configuration and which can be referred to collectively in the graph.

By convention, family names are upper case, with the exception of the special root family that all tasks inherit from.

family trigger

Tasks that belong to a family can be referred to collectively in the graph using a 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:

succeed-all

All members succeeded.

succeed-any

Any one member succeeded.

fail-all

All members failed.

finish-all

All members finished (succeeded or failed).

final cycle point

In a cycling workflow the final cycle point, if there is one, is the last cycle point in the graph.

final status

A task that has achieved a final status (expired, submit-failed, succeeded, or failed) will not change state in the workflow, except by manual intervention.

flow

A flow is a self-propagating run through the a Cylc workflow graph starting from some initial task or tasks.

Cylc schedulers can manage multiple flows at once.

Flows are identified by a flow number. The original flow started automatically by cylc play has flow number 1.

See also

flow front

Active tasks, i.e. tasks in the n=0 window, with a common flow number comprise the active front of the flow.

flow merge

When a flow tries to spawn a child task and finds an instance with the same task ID already exists in the n=0 active window, one merged task will carry both flow numbers forward.

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 $CYLC_TASK_FLOW_NUMBERS.

future trigger

A future trigger expresses dependence on a task in a “future” (higher-valued) cycle point.

Here, 1/bar triggers off of 2/foo; 2/bar triggers off of 3/foo; and so on:

[scheduling]
    initial cycle point = 1
    cycling mode = integer
    [[graph]]
        P1 = "foo[+P1] => bar"
graph

A workflow graph is defined by one or more graph strings under the [scheduling][graph] section of a workflow definition.

For example, the following is, collectively, a graph:

P1D = foo => bar
PT12H = baz

digraph Example { size = "7,15" subgraph cluster_1 { label = "2000-01-01T00:00Z" style = dashed "01T00/foo" [label="foo\n2000-01-01T00:00Z"] "01T00/bar" [label="bar\n2000-01-01T00:00Z"] "01T00/baz" [label="baz\n2000-01-01T00:00Z"] } subgraph cluster_2 { label = "2000-01-01T12:00Z" style = dashed "b01T12/az" [label="baz\n2000-01-01T12:00Z"] } subgraph cluster_3 { label = "2000-01-02T00:00Z" style = dashed "02T00/foo" [label="foo\n2000-01-02T00:00Z"] "02T00/bar" [label="bar\n2000-01-02T00:00Z"] "02T00/baz" [label="baz\n2000-01-02T00:00Z"] } "01T00/foo" -> "01T00/bar" "02T00/foo" -> "02T00/bar" }

graph string

A graph string is a collection of task dependencies in the [scheduling][graph] section of a workflow definition, with an associated recurrence that defines its sequence of cycle points.

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
"""
handler
event handler
event handlers

An event handler is a user-defined executable that the scheduler runs when selected task or workflow events occur.

Use-cases include:

  • Send an email message.

  • Run a Cylc command.

  • Run any user-specified script or command.

hold
held task
hold after cycle point

A task held with cylc hold will not submit its jobs when ready to run.

It is also possible to set a “hold after cycle point”; all tasks after this cycle point will be held.

Note

Workflows can be paused with cylc pause, and unpaused/resumed with cylc play.

Tasks can be held with cylc hold and released with cylc release.

When a workflow is resumed, any held tasks remain held.

implicit task

Implicit tasks are tasks which are not defined in the [runtime] section.

Like regular tasks they inherit from the root family.

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 [runtime].

Here bar is implicit:

[scheduling]
    [[graph]]
        R1 = foo & bar
[runtime]
    [[foo]]
# eof

Cylc 7

In Cylc 7 and earlier, implicit tasks were known as “naked dummy tasks”.

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

In a cycling workflow the initial cycle point is the first cycle point in the graph.

install
installation
workflow installation

The cylc install command installs workflow source files into a new run directory under the cylc-run directory.

See also

install target

Cylc uses install targets to determine which platforms share file systems. Install targets should normally be managed at site level. They are configured in global.cylc[platforms][<platform name>]install target.

integer cycling

An integer cycling workflow uses integer cycle points and recurrences (e.g. P3 means every third cycle).

intercycle dependence
intercycle dependency
intercycle trigger

In a cycling workflow, intercycle dependence refers to a task depending on other tasks at different cycle points.

For example, in the following workflow the task bar depends on its own previous instance:

[scheduling]
    initial cycle point = 1
    cycling mode = integer
    [[graph]]
        P1 = """
            foo => bar => baz
            bar[-P1] => bar
        """

digraph Example { size = "3,5" subgraph cluster_1 { label = "1" style = dashed "1/foo" [label="foo\n1"] "1/bar" [label="bar\n1"] "1/baz" [label="baz\n1"] } subgraph cluster_2 { label = "2" style = dashed "2/foo" [label="foo\n2"] "2/bar" [label="bar\n2"] "2/baz" [label="baz\n2"] } subgraph cluster_3 { label = "3" style = dashed "3/foo" [label="foo\n3"] "3/bar" [label="bar\n3"] "3/baz" [label="baz\n3"] } "1/foo" -> "1/bar" -> "1/baz" "2/foo" -> "2/bar" -> "2/baz" "3/foo" -> "3/bar" -> "3/baz" "1/bar" -> "2/bar" -> "3/bar" }

ISO 8601
ISO8601

ISO 8601 is an international standard for writing datetimes, durations, and recurrences (sequences of datetimes). Cylc uses ISO 8601 for datetime cycling.

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.

See also

ISO 8601 duration
ISO8601 duration

A duration written in the ISO 8601 format e.g:

  • PT1H30M: one hour and thirty minutes.

job

Jobs are the real processes that tasks represent in a workflow. In Cylc, they are implemented by job scripts prepared by the scheduler.

job host

A job host is a compute resource that a job runs on. For example node_1 would be one of two possible job hosts on the platform my_hpc for the task solver in the following workflow:

global.cylc
[platforms]
    [[my_hpc]]
        hosts = node_1, node_2
        job runner = slurm
flow.cylc
[runtime]
    [[solver]]
        platform = my_hpc
job log
job log directory

Task job log files are stored in job specific log directories under the workflow run directory. These include:

job

The task job script.

job.out

Job stdout.

job.err

Job stderr.

job.status

Job status data in case of lost contact with the scheduler.

job-activity.log

Job data logged by the scheduler, rather than the job itself, such as output from the job submission command.

job.xtrace

Debugging information from Bash captured when Cylc is run in --debug mode.

<run-directory>/log/job/<cycle-point>/<task-name>/<job-submit-num>

You can print 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

A job runner is a system for submitting task jobs to run on a job platform.

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 global.cylc.

Cylc 7

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

A single task may run multiple jobs as a result of automatic retries or manually retriggering. The job submission number is incremented each time, starting from 1.

message trigger

A message trigger is a trigger based on a custom task output. The task job must send a user-defined message to the scheduler to complete the output.

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:x?, or foo:fail?, or foo? (short for foo:succeed?). The may or may not be completed at runtime. Optional outputs are primarily used for graph branching.

output
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. Tasks can trigger off of upstream task outputs in the graph.

Outputs are written as task-name:output in the graph, and can be required or optional.

Tasks may have custom outputs as well as standard outputs.

Here the task bar depends on the standard :started output of foo:

foo:started => bar

The standard :succeeded output is usually implicit:

foo => bar  # means foo:succeeded => bar
output completion
output completion condition

A task’s outputs are complete if its output completion condition is satisfied.

The completion condition can be defined by the user in flow.cylc[runtime][<namespace>]completion, otherwise it is automatically generated according to the rules:

  • All required outputs (referenced in the graph) must be completed.

  • Or, if success is optional, then the outputs are complete if it fails.

  • Or, if submission is optional, then the outputs are complete if it submit-fails.

  • Or, if expiry is optional, then the outputs are complete if it expires.

Tasks that achieve a final status with complete outputs have done their job, allowing the workflow to move on.

Tasks that achieve a final status with incomplete outputs are retained in n=0 pending user intervention, and will stall the workflow.

pause

When a workflow is “paused” the scheduler is still running but it will not submit any new jobs.

This can be useful if you want to make a change to a running workflow.

Pause a workflow with cylc pause and resume it with cylc play.

See also

platform
job platform

A platform for running Cylc task jobs is primarily defined by the combination of a job runner and a group of hosts that share a file system.

For example my_hpc could be the platform for the task solver in the following workflow:

Global configuration (global.cylc)
[platforms]
    [[my_hpc]]
        hosts = node_1, node_2
        job runner = slurm
Workflow configuration (flow.cylc)
[runtime]
    [[solver]]
        platform = my_hpc

See also

platform group

A set of platforms grouped under a common name.

Platforms are configured by global.cylc[platform groups].

play

The cylc play command runs an instance of the scheduler program to start or restart a workflow.

You can play, pause and stop a workflow, Cylc will always carry on where it left off.

prerequisite
dependence
dependency

Dependencies in the graph show how tasks depend on some combination of the outputs of other tasks.

For example, in the following dependency the task baz depends on both foo and bar succeeding:

foo & bar => baz

Tasks can also depend on external triggers.

qualifier

A qualifier is what follows task or family family names after a colon : in triggers, in the graph, to specify exactly which task outputs must be completed for the dependency to be satisfied.

For example, in foo:start => bar, the :start qualifier means that the started output of task foo must be completed to satisfy the dependency.

queue
internal queue

Internal queues (so called to distinguish them from external batch queueing systems) limit how many jobs can be active 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.

recurrence

In a cycling workflow a recurrence determines the sequence of cycle points given to task instances that appear in the associated graph string.

Recurrences for datetime cycling are based on the ISO8601 standard. Those for integer cycling are designed to have similar syntax, but are much simpler.

reinstall
reinstallation

The cylc reinstall command reinstalls workflow source files into an existing run directory under the cylc-run directory.

See also

release

Held tasks can be released with cylc release, allowing submission of task jobs once again.

It is also possible to remove the “hold after cycle point” if set, using cylc release --all. This will also release all held tasks.

reload

Schedulers can reload their workflow configuration from the installed flow.cylc file, to pick up changes made at runtime.

We recommend that changes are reinstalled from the workflow source directory before reload, rather than made by editing the installed files directly.

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. The next instance of the task (at the next cycle point) will adopt the new configuration.

Reloading changes is safe providing they don’t affect the workflow’s graph. Changes to the graph have certain caveats attached, see the Cylc User Guide for details.

See also

required output
expected output

Task outputs that are not marked as optional in the graph must be completed at runtime. If a task achieves a final status without completing its required outputs, the scheduler will keep it in the n=0 window pending user intervention.

See also

restart

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.cylc file 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.

retry
task retry
try number

Tasks can be configured to retry automatically on failure, one or more times. They return to the waiting state with a clock trigger to delay the retry, and only go to the failed state once the final try fails.

The task try number increments with every automatic retry, and is passed to the job environment as $CYLC_TASK_TRY_NUMBER.

See also

run directory
workflow run directory

This is a location under the cylc-run directory that contains the installed configuration used to run a workflow.

At runtime, task jobs can get their workflow run directory from the environment variable CYLC_WORKFLOW_RUN_DIR.

runahead limit
runahead

In a cycling workflow, the runahead limit determines how far ahead of the oldest active cycle the workflow is permitted to run.

The “oldest active cycle point” is the first cycle in the workflow to contain any active tasks (e.g. running tasks).

runtime inheritance
family inheritance

A task is a member of a family if it inherits the family configuration via [runtime][<namespace>]inherit.

For example the task cheddar “belongs” to the family CHEESE in the following snippet:

[runtime]
    [[CHEESE]]
        [[[environment]]]
            COLOR = yellow
    [[cheddar]]
        inherit = FAMILY

Families can also inherit from other families. All tasks implicitly inherit from a special root family at the base of the inheritance hierarchy.

Tasks can inherit from multiple families at once using a comma-separated list:

inherit = foo, bar, baz
scheduler

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.

Cylc 7

In Cylc 7 and earlier, schedulers were known as “suite daemons”.

service directory

The hidden service directory, under the workflow run directory, stores information for internal use by Cylc. It is created at install time.

<run-directory>/.service/
share 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.

<run-directory>/share

Tasks can get their own share directory path at runtime from the CYLC_WORKFLOW_SHARE_DIR environment variable.

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 install or reinstallation with cylc reinstall.

These locations are configurable. The default is ~/cylc-src.

stall
stalled workflow

A stalled workflow has not run to completion but cannot continue without manual intervention.

A stalled scheduler stays alive for a configurable timeout period pending manual intervention. If it shuts down (on the stall timeout or otherwise) it will remain in the stalled state on restart.

Stalls are usually caused by unexpected task failures:

digraph Example { foo [style="filled" color="#ada5a5"] bar [style="filled" color="#ff0000" fontcolor="white"] baz [color="#88c6ff"] foo -> bar -> baz }

In this example the task bar has failed, so that baz cannot run, but bar:fail was not marked as an optional output.

User intervention is required to fix a stall, e.g. by retriggering tasks after fixing the problems that caused them to fail.

standard output

Every task has a set of standard outputs that trigger task state changes:

  • :expired`

  • :submitted, or :submit-failed

  • :started

  • :succeeded, or :failed

start
startup

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

In a cycling workflow the start cycle point is the cycle point where the scheduler starts running the workflow.

This may be at or after the initial cycle point.

start task

A start task is task in the graph from which the scheduler starts running a workflow from scratch.

Earlier tasks depended on by start tasks are treated as if they have succeeded.

Cylc 7

Cylc 7 and earlier did not have the capability to start from any task in the graph.

stop
shutdown

A scheduler can shut down on request, or automatically on workflow completion. The workflow is then stopped and no further jobs will be submitted.

By default, the scheduler waits for any submitted or running task jobs to finish (either succeed or fail) before shutting down.

stop cycle point

The stop cycle point is the cycle point where scheduler stops running the workflow and shuts down.

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 $CYLC_TASK_SUBMIT_NUMBER.

Submit number also appears in the job log path so that job log files don’t get overwritten.

suicide trigger

Suicide triggers remove tasks from the active window at runtime.

They are denoted by exclamation marks, and are triggered like normal dependencies. For instance, the following suicide trigger will remove the task bar if foo succeeds:

foo => ! bar

Warning

Suicide triggers are not needed in Cylc 8 for graph branching. They are retained for backward compatibility and rare edge cases.

See also

task

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 definitions are used to create a job script that is executed as a job on behalf of the task.

Tasks submit jobs. Each job belongs to one task, but one task can submit multiple jobs.

task parameters
parameterization

Task parameterization is one way of consolidating configuration in the flow.cylc file. Cylc implicitly loops over ranges or lists of pre-defined parameters to automatically generate sets of similar tasks.

Other ways of consolidating configuration include runtime inheritance and templating with Jinja2.

[task parameters]
    m = 1..3
[scheduling]
    [[graph]]
        R1 = bar<m> => baz<m>

digraph Mini_Cylc { baz_m2 bar_m2 -> baz_m2 baz_m3 bar_m3 -> baz_m3 bar_m1 -> baz_m1 baz_m1 }

task state

A task progresses through a series of states in its lifetime. These include the submitted state after job submission; running after execution commences, and succeeded after successful job execution.

trigger
task trigger

A trigger is the left-hand side of a dependency in the graph. It defines the combination of task outputs that must be completed before downstream tasks can run.

In this example, the task bar can be said to trigger off of completion of the foo:started output:

foo:started => bar

Triggers can be based on standard or custom task outputs. In the latter case they are known as message triggers.

validation
workflow validation

Validation parses a flow.cylc file 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 validate command after making changes.

wallclock time

The actual time (in the real world).

warm start

A warm start is when the scheduler starts a cycling workflow running from a start cycle point after the initial cycle point.

To satisfy unbounded intercycle dependence in the graph, tasks prior to the start cycle point are treated as if they have succeeded.

window
n-window
active window

The GUI provides a graph-based window or view of the workflow at runtime, including tasks out to n graph edges from current active tasks.

Active tasks form the n=0 window.

See also

work directory

Cylc executes task jobs inside a job-specific working directory, automatically created under the workflow run directory.

<run-directory>/work/<cycle-point>/<task-name>

Tasks can get their own work directory path at runtime from the CYLC_TASK_WORK_DIR environment variable or the Posix pwd command.

workflow
cylc workflow

A workflow is a collection of tasks with dependencies between them that govern the order in which they can run.

Cylc workflows are defined in flow.cylc files.

For example, the following workflow represents the beer brewing process:

flow.cylc
[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
        """

Cylc 7

In Cylc 7 and earlier, “workflows” were referred to as “suites”.

workflow completion

A workflow is complete, and the scheduler will automatically shut down, if no tasks remain in the n=0.

That is, all active tasks have finished, and no tasks remain waiting on prerequisites or “external” constraints (such as xtriggers or task hold).

If no active tasks remain and all external constraints are satisfied, but the n=0 window contains tasks waiting with partially satisfied prerequisites, or tasks with final status and incomplete outputs, then the workflow is not complete and the scheduler will stall pending manual intervention.

workflow id

A workflow can be uniquely identified by the relative path between the cylc-run directory (~/cylc-run) and its run directory.

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 ~/cylc-run/foo/bar/run1 is foo/bar/run1.

Unlike workflow name the ID is always a unique identifier. In the example below each run has a different ID despite sharing the same workflow name (my_workflow).

`- 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 <run-directory>/log/scheduler/log

<run-directory>/log/scheduler/

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.

Tasks can get the workflow name from $CYLC_WORKFLOW_NAME in their runtime environment.

Unlike workflow id the name is not always a unique identifier. In the example below run1 and run2 would both have the same name, my_workflow:

`- my_workflow
  |- runN
  |- run1
  `- run2

Note

If you are not using named or numbered runs, the workflow name will be the same as workflow id.