Glossary

application directory
The application directory is the folder in which the rose-app.conf file is located in a Rose application configuration.
batch system

A batch system or job scheduler is a system for submitting jobs onto a compute platform.

See also:

cold start

A cold start is one in which the suite starts from the initial cycle point. This is the default behaviour of cylc run.

See also:

cycle

In a cycling suite one cycle is one repetition of the workflow.

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 "foo.1" [label="foo\n1"] "bar.1" [label="bar\n1"] "baz.1" [label="baz\n1"] } subgraph cluster_2 { label = "2" style = dashed "foo.2" [label="foo\n2"] "bar.2" [label="bar\n2"] "baz.2" [label="baz\n2"] } subgraph cluster_3 { label = "3" style = dashed "foo.3" [label="foo\n3"] "bar.3" [label="bar\n3"] "baz.3" [label="baz\n3"] } "foo.1" -> "bar.1" -> "baz.1" "foo.2" -> "bar.2" -> "baz.2" "foo.3" -> "bar.3" -> "baz.3" "bar.1" -> "bar.2" -> "bar.3" }
cycle point

A cycle point is the unique label given to a particular cycle. If the suite is using integer cycling then the cycle points will be numbers e.g. 1, 2, 3, etc. If the suite is using datetime cycling then the labels will be ISO8601 datetimes e.g. 2000-01-01T00:00Z.

See also:

cycling

A cycling suite is one in which the workflow repeats.

See also:

datetime cycling

A datetime cycling is the default for a cycling suite. When using datetime cycling cycle points will be ISO8601 datetimes e.g. 2000-01-01T00:00Z and ISO8601 recurrences can be used e.g. P3D means every third day.

See also:

dependency

A dependency is a relationship between two tasks which describes a constraint on one.

For example the dependency foo => bar means that the task bar is dependent on the task foo. This means that the task bar will only run once the task foo has successfully completed.

See also:

directive

Directives are used by batch systems to determine what a job’s requirements are, e.g. how much memory it requires.

Directives are set in the suite.rc file in the [runtime] section ([runtime][<task-name>][directives]).

See also:

family

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

By convention families are named in upper case with the exception of the special root family from which all tasks inherit.

See also:

family inheritance

A task can be “added” to a family by “inheriting” from it.

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

[runtime]
    [[FAMILY]]
        [[[environment]]]
            FOO = foo
    [[task]]
        inherit = FAMILY

A task can inherit from multiple families by writing a comma-separated list e.g:

inherit = foo, bar, baz

See also:

family trigger

Tasks which “belong” to (inherit from) a family can be referred to collectively in the graph using a family trigger.

A family trigger is written using the name of the family followed by a special qualifier i.e. FAMILY_NAME:qualifier. The most commonly used qualifiers are:

succeed-all
The dependency will only be met when all of the tasks in the family have succeeded.
succeed-any
The dependency will be met as soon as any one of the tasks in the family has succeeded.
finish-all
The dependency will only be met once all of the tasks in the family have finished (either succeeded or failed).

See also:

final cycle point

In a cycling suite the final cycle point is the point at which cycling ends.

If the final cycle point were 2001 then the final cycle would be no later than the 1st of January 2001.

See also:

graph

The graph of a suite refers to the graph strings contained within the [scheduling][dependencies] section. For example the following is, collectively, a graph:

[P1D]
    graph = foo => bar
[PT12H]
    graph = baz

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

A graph string is a collection of dependencies which are placed under a graph section in the suite.rc file. E.G:

foo => bar => baz & pub => qux
pub => bool
initial cycle point

In a cycling suite the initial cycle point is the point from which cycling begins.

If the initial cycle point were 2000 then the first cycle would be on the 1st of January 2000.

See also:

integer cycling

An integer cycling suite is a cycling suite which has been configured to use integer cycling. When a suite uses integer cycling integer recurrences may be used in the graph, e.g. P3 means every third cycle. This is configured by setting [scheduling]cycling mode = integer in the suite.rc file.

See also:

inter-cycle dependency

In a cycling suite an inter-cycle dependency is a dependency between two tasks in different cycles.

For example in the following suite the task bar is dependent on its previous occurrence:

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

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

ISO8601 is an international standard for writing dates and times which is used in Cylc with datetime cycling.

See also:

ISO8601 datetime

A date-time written in the ISO8601 format, e.g:

  • 2000-01-01T00:00Z: midnight on the 1st of January 2000

See also:

ISO8601 duration

A duration written in the ISO8601 format e.g:

  • PT1H30M: one hour and thirty minutes.

See also:

job

A job is the realisation of a task consisting of a file called the job script which is executed when the job “runs”.

See also:

job host

The job host is the compute platform that a job runs on. For example some-host would be the job host for the task some-task in the following suite:

[runtime]
    [[some-task]]
        [[[remote]]]
            host = some-host
job log
job log directory

When Cylc executes a job, stdout and stderr are redirected to the job.out and job.err files which are stored in the job log directory.

The job log directory lies within the run directory:

<run directory>/log/job/<cycle>/<task-name>/<submission-no>

Other files stored in the job log directory:

  • job: the job script.
  • job-activity.log: a log file containing details of the job’s progress.
  • job.status: a file holding Cylc’s most up-to-date understanding of the job’s present status.
job script

A job script is the file containing a bash script which is executed when a job runs. A task’s job script can be found in the job log directory.

See also:

job submission number

Cylc may run multiple jobs per task (e.g. if the task failed and was re-tried). Each time Cylc runs a job it is assigned a submission number. The submission number starts at 1, incrementing with each submission.

See also:

metadata
Rose metadata

Rose metadata provides information about settings in Rose application configurations and Rose suite configurations. This information is stored in a rose-meta.conf file in a meta/ directory alongside the configuration it applies to.

This information can include:

This information is used for:

Metadata does not affect the running of an application or Cylc suite.

See also:

parameterisation

Parameterisation is a way to consolidate configuration in the Cylc suite.rc file by implicitly looping over a set of pre-defined variables e.g:

[cylc]
    [[parameters]]
        foo = 1..3
[scheduling]
    [[dependencies]]
        graph = bar<foo> => baz<foo>

digraph Mini_Cylc { bar_foo3 -> baz_foo3 baz_foo3 bar_foo1 -> baz_foo1 baz_foo1 bar_foo2 -> baz_foo2 baz_foo2 }

See also:

qualifier

A qualifier is used to determine the task state to which a dependency relates.

See also:

recurrence

A recurrence is a repeating sequence which may be used to define a cycling suite. Recurrences determine how often something repeats and take one of two forms depending on whether the suite is configured to use integer cycling or datetime cycling.

See also:

reload

Any changes made to the suite.rc file whilst the suite is running will not have any effect until the suite is either:

Reloading does not require the suite to be shutdown. When a suite is reloaded any currently “active” tasks will continue with their “pre-reload” configuration, whilst new tasks will use the new configuration.

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

See also:

restart

When a stopped suite is “restarted” Cylc will pick up where it left off. Cylc will detect any jobs which have changed state (e.g. succeeded) during the period in which the suite was shutdown.

See also:

Rose app
Rose application
Rose application configuration

A Rose application configuration (or Rose app) is a directory containing a rose-app.conf file along with some other optional files and directories.

An application can configure:

See also:

Rose built-in application

A Rose built-in application is a generic Rose application providing common functionality which is provided in the Rose installation.

See also:

Rose configuration

Rose configurations are directories containing a Rose configuration file along with other optional files and directories.

The two types of Rose configuration relevant to Cylc suites are:

See also:

Rose suite configuration

A Rose suite configuration is a rose-suite.conf file along with other optional files and directories which configure the way in which a Cylc suite is run. E.g:

See also:

Rosie Suite

A Rosie suite is a Rose suite configuration which is managed using the Rosie system.

When a suite is managed using Rosie:

  • The suite directory is added to version control.
  • The suite is registered in a database.

See also:

run directory

When a suite is run a directory is created for all of the files generated whilst the suite is running. This is called the run directory and typically resides in the cylc-run directory:

~/cylc-run/<suite-name>

Note

If a suite is written in the cylc-run directory the run directory is also the suite directory.

The run directory can be accessed by a running suite using the environment variable CYLC_SUITE_RUN_DIR.

See also:

share directory

The share directory resides within a suite’s run directory. It serves the purpose of providing a storage place for any files which need to be shared between different tasks.

<run directory>/share

The location of the share directory can be accessed by a job via the environment variable CYLC_SUITE_SHARE_DIR.

In cycling suites files are typically stored in cycle sub-directories.

See also:

stalled suite
stalled state

If Cylc is unable to proceed running a workflow due to unmet dependencies the suite is said to be stalled.

This usually happens because of a task failure as in the following diagram:

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 meaning that baz is unable to run as its dependency (bar:succeed) has not been met.

When a Cylc detects that a suite has stalled an email will be sent to the user. Human interaction is required to escape a stalled state.

start
startup

When a suite starts the Cylc suite server program is run. This program controls the suite and is what we refer to as “running”.

A suite start can be either cold or warm (cold by default).

See also:

stop
shutdown

When a suite is shutdown the suite server program is stopped. This means that no further jobs will be submitted.

By default Cylc waits for any submitted or running jobs to complete (either succeed or fail) before shutting down.

See also:

suite
Cylc suite

A Cylc suite is a directory containing a suite.rc file which contains graphing representing a workflow.

See also:

suite directory

The suite directory contains all of the configuration for a suite (e.g. the suite.rc file and for Rose suites the rose-suite.conf file).

This is the directory which is registered using cylc reg or, for Rose suites, it is the one in which the rose suite-run command is executed.

Note

If a suite is written in the cylc-run directory the suite directory is also the run directory.

See also:

suite log
suite log directory

A Cylc suite logs events and other information to the suite log files when it runs. There are three log files:

  • out - the stdout of the suite.
  • err - the stderr of the suite, which may contain useful debugging information in the event of any error(s).
  • log - a log of suite events, consisting of information about user interaction.

The suite log directory lies within the run directory:

<run directory>/log/suite
suite server program

When we say that a suite is “running” we mean that the cylc suite server program is running.

The suite server program is responsible for running the suite. It submits jobs, monitors their status and maintains the suite state.

By default a suite server program is a daemon meaning that it runs in the background (potentially on another host).

task

A task represents an activity in a workflow. It is a specification of that activity consisting of the script or executable to run and certain details of the environment it is run in.

The task specification is used to create a job which is executed on behalf of the task.

Tasks submit jobs and therefore each job belongs to one task. Each task can submit multiple jobs.

See also:

task state

During a task’s life it will proceed through various states. These include:

  • waiting
  • running
  • succeeded

See also:

task trigger

Dependency relationships can be thought of the other way around as “triggers”.

For example the dependency foo => bar could be described in two ways:

  • “bar is dependent on foo”
  • “foo is triggered by bar”

In practice a trigger is the left-hand side of a dependency (foo in this example).

See also:

wall-clock time

In a Cylc suite the wall-clock time refers to the actual time (in the real world).

See also:

warm start

In a cycling suite a warm start is one in which the suite starts from a cycle point after the initial cycle point. Tasks in cycles before this point as assumed to have succeeded.

See also:

work directory

When Cylc executes a job it does so inside the job’s working directory. This directory is created by Cylc and lies within the directory tree inside the relevant suite’s run directory.

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

The location of the work directory can be accessed by a job via the environment variable CYLC_TASK_WORK_DIR.

Any files installed by Rose apps will be placed within this directory.

See also: