Global Configuration

global.cylc

The global configuration which defines default Cylc Flow settings for a user or site.

To view your global config, run:

$ cylc config

Cylc will attempt to load the global configuration (global.cylc) from a hierarchy of locations, including the site directory (defaults to /etc/cylc/flow/) and the user directory (~/.cylc/flow/). For example at Cylc version 8.0.1, the hierarchy would be, in order of ascending priority:

<site-conf-path>/flow/global.cylc
<site-conf-path>/flow/8/global.cylc
<site-conf-path>/flow/8.0/global.cylc
<site-conf-path>/flow/8.0.1/global.cylc
~/.cylc/flow/global.cylc
~/.cylc/flow/8/global.cylc
~/.cylc/flow/8.0/global.cylc
~/.cylc/flow/8.0.1/global.cylc

Where <site-conf-path> is /etc/cylc/flow/ by default but can be changed by CYLC_SITE_CONF_PATH.

A setting in a file lower down in the list will override the same setting from those higher up (but if a setting is present in a file higher up and not in any files lower down, it will not be overridden).

The following environment variables can change the files which are loaded:

CYLC_CONF_PATH

If set this bypasses the default site/user configuration hierarchy used to load the Cylc Flow global configuration.

This should be set to a directory containing a global.cylc file.

CYLC_SITE_CONF_PATH

By default the site configuration is located in /etc/cylc/. For installations where this is not convenient, this path can be overridden by setting CYLC_SITE_CONF_PATH to point at another location.

Configuration for different Cylc components should be in sub-directories within this location.

For example to configure Cylc Flow you could do the following:

$CYLC_SITE_CONF_PATH/
`-- flow/
    `-- global.cylc

Note

The global.cylc file can be templated using Jinja2 variables. See Jinja2.

Changed in version 8.0.0: Prior to Cylc 8, global.cylc was named global.rc, but that name is no longer supported.

[scheduler]

Default values for entries in flow.cylc[scheduler] section.

Changed in version 8.0.0: This item was previously called [cylc].

Note

global.cylc[scheduler] should not be confused with flow.cylc[scheduling].

UTC mode
Path

global.cylc[scheduler]UTC mode

Type

boolean

Default

False

Default for flow.cylc[scheduler]UTC mode.

process pool size
Path

global.cylc[scheduler]process pool size

Type

integer

Default

4

Maximum number of concurrent processes used to execute external job submission, event handlers, and job poll and kill commands

Changed in version 8.0.0: Moved into the [scheduler] section from the top level.

See also

External Command Execution.

process pool timeout
Path

global.cylc[scheduler]process pool timeout

Type

time interval

Default

PT10M

After this interval Cylc will kill long running commands in the process pool.

Changed in version 8.0.0: Moved into the [scheduler] section from the top level.

See also

External Command Execution.

Note

The default is set quite high to avoid killing important processes when the system is under load.

auto restart delay
Path

global.cylc[scheduler]auto restart delay

Type

time interval

Maximum number of seconds the auto-restart mechanism will delay before restarting workflows.

Changed in version 8.0.0: This item was previously called global.rc[suite servers]auto restart delay.

When a host is set to automatically shutdown/restart it waits a random period of time between zero and auto restart delay seconds before beginning the process. This is to prevent large numbers of workflows from restarting simultaneously.

See also

Auto Stop-Restart

[run hosts]

Configure workflow hosts and ports for starting workflows.

Changed in version 8.0.0: This item was previously called [suite servers].

Additionally configure host selection settings specifying how to determine the most suitable run host at any given time from those configured.

available
Path

global.cylc[scheduler][run hosts]available

Type

spaceless list

A list of workflow run hosts.

Changed in version 8.0.0: This item was previously called [suite servers]run hosts.

Cylc will choose one of these hosts for a workflow to start on. (Unless an explicit host is provided as an option to the cylc play --host=<myhost> command.)

ports
Path

global.cylc[scheduler][run hosts]ports

Type

integer list

Default

43001 .. 43100

A list of allowed ports for Cylc to use to run workflows.

Changed in version 8.0.0: This item was previously called [suite servers]run ports

condemned
Path

global.cylc[scheduler][run hosts]condemned

Type

absolute host list

These hosts will not be used to run jobs.

Changed in version 8.0.0: This item was previously called [suite servers]condemned hosts.

If workflows are already running on condemned hosts, Cylc will shut them down and restart them on different hosts.

See also

Auto Stop-Restart

ranking
Path

global.cylc[scheduler][run hosts]ranking

Type

string

Rank and filter run hosts based on system information.

Changed in version 8.0.0: This item was previously called [suite servers][run host select]rank.

Ranking can be used to provide load balancing to ensure no single run host is overloaded. It also provides thresholds beyond which Cylc will not attempt to start new schedulers on a host.

This should be a multiline string containing Python expressions to rank and/or filter hosts. All psutil attributes are available for use in these expressions.

Ranking

Rankings are expressions which return numerical values. The host which returns the lowest value is chosen. Examples:

# rank hosts by cpu_percent
cpu_percent()

# rank hosts by 15min average of server load
getloadavg()[2]

# rank hosts by the number of cores
# (multiple by -1 because the lowest value is chosen)
-1 * cpu_count()

Threshold

Thresholds are expressions which return boolean values. If a host returns a False value that host will not be selected. Examples:

# filter out hosts with a CPU utilisation of 70% or above
cpu_percent() < 70

# filter out hosts with less than 1GB of RAM available
virtual_memory.available > 1000000000

# filter out hosts with less than 1GB of disk space
# available on the "/" mount
disk_usage('/').free > 1000000000

Combining

Multiple rankings and thresholds can be combined in this section e.g:

# filter hosts
cpu_percent() < 70
disk_usage('/').free > 1000000000

# rank hosts by CPU count
1 / cpu_count()
# if two hosts have the same CPU count
# then rank them by CPU usage
cpu_percent()
[host self-identification]

How Cylc determines and shares the identity of the workflow host.

Changed in version 8.0.0: This item was previously called [suite host self-identification].

The workflow host’s identity must be determined locally by cylc and passed to running tasks (via $CYLC_WORKFLOW_HOST) so that task messages can target the right workflow on the right host.

method
Path

global.cylc[scheduler][host self-identification]method

Type

string

Default

name

Options

name, address, hardwired

Determines how cylc finds the identity of the workflow host.

Changed in version 8.0.0: This item was previously called [suite host self-identification].

Options:

name

(The default method) Self-identified host name. Cylc asks the workflow host for its host name. This should resolve on task hosts to the IP address of the workflow host; if it doesn’t, adjust network settings or use one of the other methods.

address

Automatically determined IP address (requires target). Cylc attempts to use a special external “target address” to determine the IP address of the workflow host as seen by remote task hosts.

hardwired

(only to be used as a last resort) Manually specified host name or IP address (requires host) of the workflow host.

target
Path

global.cylc[scheduler][host self-identification]target

Type

string

Default

google.com

Target for use by the address self-identification method.

If your workflow host sees the internet, a common address such as google.com will do; otherwise choose a host visible on your intranet.

Changed in version 8.0.0: This item was previously called [suite host self-identification].

host
Path

global.cylc[scheduler][host self-identification]host

Type

string

The name or IP address of the workflow host used by the hardwired self-identification method.

Changed in version 8.0.0: This item was previously called [suite host self-identification].

[events]

Define site defaults for flow.cylc[scheduler][events].

handlers
Path

global.cylc[scheduler][events]handlers

Type

list

handler events
Path

global.cylc[scheduler][events]handler events

Type

list

mail events
Path

global.cylc[scheduler][events]mail events

Type

list

startup handlers
Path

global.cylc[scheduler][events]startup handlers

Type

list

Handlers to run at scheduler startup.

Changed in version 8.0.0: This item was previously called startup handler.

shutdown handlers
Path

global.cylc[scheduler][events]shutdown handlers

Type

list

Handlers to run at scheduler shutdown.

Changed in version 8.0.0: This item was previously called shutdown handler.

abort handlers
Path

global.cylc[scheduler][events]abort handlers

Type

list

Handlers to run if the scheduler aborts.

Changed in version 8.0.0: This item was previously called aborted handler.

workflow timeout
Path

global.cylc[scheduler][events]workflow timeout

Type

time interval

Workflow timeout interval. The timer starts counting down at scheduler startup. It resets on workflow restart.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

workflow timeout handlers
Path

global.cylc[scheduler][events]workflow timeout handlers

Type

list

Handlers to run if the workflow timer times out.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

abort on workflow timeout
Path

global.cylc[scheduler][events]abort on workflow timeout

Type

boolean

Default

False

Whether to abort if the workflow timer times out.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

stall handlers
Path

global.cylc[scheduler][events]stall handlers

Type

list

Handlers to run if the scheduler stalls.

Changed in version 8.0.0: This item was previously called stalled handler.

stall timeout
Path

global.cylc[scheduler][events]stall timeout

Type

time interval

Default

PT1H

The length of a timer which starts if the scheduler stalls.

A workflow will stall if there are no tasks ready to run and no waiting external triggers, but the presence of incomplete tasks or unsatisified prerequisites shows the workflow did not run to completion. The stall timer turns off on any post-stall task activity. It resets on restarting a stalled workflow.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

stall timeout handlers
Path

global.cylc[scheduler][events]stall timeout handlers

Type

list

Handlers to run if the stall timer times out.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

abort on stall timeout
Path

global.cylc[scheduler][events]abort on stall timeout

Type

boolean

Default

True

Whether to abort if the stall timer times out.

New in version 8.0.0: Previously, ‘timeout’ was a stall timeout.

inactivity timeout
Path

global.cylc[scheduler][events]inactivity timeout

Type

time interval

Scheduler inactivity timeout interval. The timer resets when any workflow activity occurs.

Changed in version 8.0.0: This item was previously called inactivity.

inactivity timeout handlers
Path

global.cylc[scheduler][events]inactivity timeout handlers

Type

list

Handlers to run if the inactivity timer times out.

Changed in version 8.0.0: This item was previously called inactivity handler.

abort on inactivity timeout
Path

global.cylc[scheduler][events]abort on inactivity timeout

Type

boolean

Default

False

Whether to abort if the inactivity timer times out.

Changed in version 8.0.0: This item was previously called abort on inactivity.

[mail]

Options for email handling.

Changed in version 8.0.0: This item was previously called [cylc][events]mail <item>.

from
Path

global.cylc[scheduler][mail]from

Type

string

smtp
Path

global.cylc[scheduler][mail]smtp

Type

string

to
Path

global.cylc[scheduler][mail]to

Type

string

footer
Path

global.cylc[scheduler][mail]footer

Type

string

task event batch interval
Path

global.cylc[scheduler][mail]task event batch interval

Type

time interval

Default

PT5M

Default for flow.cylc[scheduler][mail]task event batch interval

Changed in version 8.0.0: This item was previously [cylc]task event mail interval

[main loop]

Configuration of the Cylc Scheduler’s main loop.

New in version 8.0.0.

plugins
Path

global.cylc[scheduler][main loop]plugins

Type

list

Default

'health check', 'reset bad hosts'

Configure the default main loop plugins to use when starting new workflows.

New in version 8.0.0.

[<plugin name>]

Configure a main loop plugin.

interval
Path

global.cylc[scheduler][main loop][<plugin name>]interval

Type

time interval

The interval with which this plugin is run.

New in version 8.0.0.

[health check]
Inherits

global.cylc[scheduler][main loop][<plugin name>]

Checks the integrity of the workflow run directory.

New in version 8.0.0.

interval
Path

global.cylc[scheduler][main loop][health check]interval

Type

time interval

Default

PT10M

The interval with which this plugin is run.

New in version 8.0.0.

[reset bad hosts]
Inherits

global.cylc[scheduler][main loop][<plugin name>]

Periodically clear the scheduler list of unreachable (bad) hosts.

New in version 8.0.0.

interval
Path

global.cylc[scheduler][main loop][reset bad hosts]interval

Type

time interval

Default

PT30M

How often (in seconds) to run this plugin.

New in version 8.0.0.

[logging]

Settings for the workflow event log.

The workflow event log, held under the workflow run directory, is maintained as a rolling archive. Logs are rolled over (backed up and started anew) when they reach a configurable limit size.

Changed in version 8.0.0: This item was previously called [suite logging].

rolling archive length
Path

global.cylc[scheduler][logging]rolling archive length

Type

integer

Default

5

How many rolled logs to retain in the archive.

maximum size in bytes
Path

global.cylc[scheduler][logging]maximum size in bytes

Type

integer

Default

1000000

Workflow event logs are rolled over when they reach this file size.

[install]

Configure directories and files to be installed on remote hosts.

New in version 8.0.0.

source dirs
Path

global.cylc[install]source dirs

Type

list

Default

~/cylc-src

List of paths that Cylc searches for workflows to install.

All workflow source directories in these locations will also show up in the GUI, ready for installation.

Caution

If workflow source directories of the same name exist in more than one of these paths, only the first one will be picked up.

Configure alternate workflow run directory locations.

Symlinks from the the standard $HOME/cylc-run locations will be created.

New in version 8.0.0.

Path

global.cylc[install][symlink dirs][<install target>]run

Type

string

Alternative location for the run dir.

If specified, the workflow run directory will be created in <this-path>/cylc-run/<workflow-name> and a symbolic link will be created from $HOME/cylc-run/<workflow-name>. If not specified the workflow run directory will be created in $HOME/cylc-run/<workflow-name>. All the workflow files and the .service directory get installed into this directory.

New in version 8.0.0.

Path

global.cylc[install][symlink dirs][<install target>]log

Type

string

Alternative location for the log dir.

If specified the workflow log directory will be created in <this-path>/cylc-run/<workflow-name>/log and a symbolic link will be created from $HOME/cylc-run/<workflow-name>/log. If not specified the workflow log directory will be created in $HOME/cylc-run/<workflow-name>/log.

New in version 8.0.0.

Path

global.cylc[install][symlink dirs][<install target>]share

Type

string

Alternative location for the share dir.

If specified the workflow share directory will be created in <this-path>/cylc-run/<workflow-name>/share and a symbolic link will be created from <$HOME/cylc-run/<workflow-name>/share. If not specified the workflow share directory will be created in $HOME/cylc-run/<workflow-name>/share.

New in version 8.0.0.

Path

global.cylc[install][symlink dirs][<install target>]share/cycle

Type

string

Alternative directory for the share/cycle dir.

If specified the workflow share/cycle directory will be created in <this-path>/cylc-run/<workflow-name>/share/cycle and a symbolic link will be created from $HOME/cylc-run/<workflow-name>/share/cycle. If not specified the workflow share/cycle directory will be created in $HOME/cylc-run/<workflow-name>/share/cycle.

New in version 8.0.0.

Path

global.cylc[install][symlink dirs][<install target>]work

Type

string

Alternative directory for the work dir.

If specified the workflow work directory will be created in <this-path>/cylc-run/<workflow-name>/work and a symbolic link will be created from $HOME/cylc-run/<workflow-name>/work. If not specified the workflow work directory will be created in $HOME/cylc-run/<workflow-name>/work.

New in version 8.0.0.

[editors]

Choose your favourite text editor for editing workflow configurations.

terminal
Path

global.cylc[editors]terminal

Type

string

An in-terminal text editor to be used by the Cylc command line.

If unspecified Cylc will use the environment variable $EDITOR which is the preferred way to set your text editor.

Note

You can set your $EDITOR in your shell profile file (e.g. ~.bashrc)

If neither this or $EDITOR are specified then Cylc will default to vi.

Examples:

ed
emacs -nw
nano
vi
gui
Path

global.cylc[editors]gui

Type

string

A graphical text editor to be used by cylc.

If unspecified Cylc will use the environment variable $GEDITOR which is the preferred way to set your text editor.

Note

You can set your $GEDITOR in your shell profile file (e.g. ~.bashrc)

If neither this or $GEDITOR are specified then Cylc will default to gvim -fg.

Examples:

atom --wait
code --new-window --wait
emacs
gedit -s
gvim -fg
nedit
[platforms]

Platforms allow you to define compute resources available at your site.

New in version 8.0.0.

A platform consists of a group of one or more hosts which share a file system and a job runner (batch system).

A platform must allow interaction with the same task job from any of its hosts.

[<platform name>]

Configuration defining a platform.

New in version 8.0.0: Many of the items in platform definitions have been moved from flow.cylc[runtime][<namespace>][job] and flow.cylc[runtime][<namespace>][remote]

Platform names can be regular expressions: If you have a set of compute resources such as bigmachine1, bigmachine2 or desktop0000, .., desktop9999 one would define platforms with names [[bigmachine[12]]] and [[desktop[0-9]{4}]].

Note

Each possible match to the definition regular expression is considered a separate platform.

If you had a supercomputer with multiple login nodes this would be a single platform with multiple hosts

See also

hosts
Path

global.cylc[platforms][<platform name>]hosts

Type

list

A list of hosts from which the job host can be selected using [selection]method.

New in version 8.0.0.

All hosts should share a file system.

job runner
Path

global.cylc[platforms][<platform name>]job runner

Type

string

Default

background

The batch system/job submit method used to run jobs on the platform.

Changed in version 8.0.0: This item was previously called suite.rc[runtime][<namespace>][job]batch system.

Examples:

  • background

  • slurm

  • pbs

job runner command template
Path

global.cylc[platforms][<platform name>]job runner command template

Type

string

Set the command used by the chosen job runner.

Changed in version 8.0.0: This item was previously called suite.rc[runtime][<namespace>][job] batch system command template.

The template’s %(job)s will be substituted by the job file path.

shell
Path

global.cylc[platforms][<platform name>]shell

Type

string

Default

/bin/bash

Changed in version 8.0.0: Moved from suite.rc[runtime][<namespace>]job.

communication method
Path

global.cylc[platforms][<platform name>]communication method

Type

string

Default

zmq

Options

poll, ssh, zmq

The means by which task progress messages are reported back to the running workflow.

Options:

zmq

Direct client-server TCP communication via network ports

poll

The workflow polls for task status (no task messaging)

ssh

Use non-interactive ssh for task communications

submission polling intervals
Path

global.cylc[platforms][<platform name>]submission polling intervals

Type

time interval list

List of intervals at which to poll status of job submission.

Changed in version 8.0.0: Moved from suite.rc[runtime][<namespace>]job.

Cylc can poll submitted jobs to catch problems that prevent the submitted job from executing at all, such as deletion from an external job runner queue. Routine polling is done only for the polling task communication method unless workflow-specific polling is configured in the workflow configuration. A list of interval values can be specified as for execution polling but a single value is probably sufficient for job submission polling.

Example:

5*PT1M, 10*PT5M
submission retry delays
Path

global.cylc[platforms][<platform name>]submission retry delays

Type

time interval list

Changed in version 8.0.0: Moved from suite.rc[runtime][<namespace>]job.

execution polling intervals
Path

global.cylc[platforms][<platform name>]execution polling intervals

Type

time interval list

List of intervals at which to poll status of job execution.

Changed in version 8.0.0: Moved from suite.rc[runtime][<namespace>]job.

Cylc can poll running jobs to catch problems that prevent task messages from being sent back to the workflow, such as hard job kills, network outages, or unplanned task host shutdown. Routine polling is done only for the polling task communication method (below) unless polling is configured in the workflow configuration. A list of interval values can be specified, with the last value used repeatedly until the task is finished - this allows more frequent polling near the beginning and end of the anticipated task run time. Multipliers can be used as shorthand as in the example below.

Example:

5*PT1M, 10*PT5M
execution time limit polling intervals
Path

global.cylc[platforms][<platform name>]execution time limit polling intervals

Type

time interval list

List of intervals after execution time limit to poll jobs.

The intervals between polling after a task job (submitted to the relevant job runner on the relevant host) exceeds its execution time limit. The default setting is PT1M, PT2M, PT7M. The accumulated times (in minutes) for these intervals will be roughly 1, 1 + 2 = 3 and 1 + 2 + 7 = 10 after a task job exceeds its execution time limit.

ssh command
Path

global.cylc[platforms][<platform name>]ssh command

Type

string

Default

ssh -oBatchMode=yes -oConnectTimeout=10

A communication command used to invoke commands on this platform.

Not used on the workflow host unless you run local tasks under another user account. The value is assumed to be ssh with some initial options or a command that implements a similar interface to ssh.

use login shell
Path

global.cylc[platforms][<platform name>]use login shell

Type

boolean

Default

True

Whether to use a login shell or not for remote command invocation.

By default, Cylc runs remote SSH commands using a login shell:

ssh user@host 'bash --login cylc ...'

which will source the following files (in order):

  • /etc/profile

  • ~/.bash_profile

  • ~/.bash_login

  • ~/.profile

For more information on login shells see the “Invocation” section of the Bash man pages.

For security reasons some institutions do not allow unattended commands to start login shells, so you can turn off this behaviour to get:

ssh user@host 'cylc ...'

which will use the default shell on the remote machine, sourcing ~/.bashrc (or ~/.cshrc) to set up the environment.

cylc path
Path

global.cylc[platforms][<platform name>]cylc path

Type

string

The path containing the cylc executable on a remote platform.

Changed in version 8.0.0: Moved from suite.rc[runtime][<namespace>][job] cylc executable.

This may be necessary if the cylc executable is not in the $PATH for an ssh call. Test whether this is the case by using ssh <host> command -v cylc.

This path is used for remote invocations of the cylc command and is added to the $PATH in job scripts for the configured platform.

Note

If use login shell=True (the default) then an alternative approach is to add cylc to the $PATH in the system or user Bash profile files (e.g. ~/.bash_profile).

Tip

For multi-version installations this should point to the Cylc wrapper script rather than the cylc executable itself.

See Managing Environments for more information on the wrapper script.

global init-script
Path

global.cylc[platforms][<platform name>]global init-script

Type

string

Add a script before the init-script of all jobs on this platform.

If specified, the value of this setting will be inserted to just before the init-script section of all job scripts that are to be submitted to the specified platform.

copyable environment variables
Path

global.cylc[platforms][<platform name>]copyable environment variables

Type

list

A list containing the names of the environment variables to be copied from the scheduler to a job.

retrieve job logs
Path

global.cylc[platforms][<platform name>]retrieve job logs

Type

boolean

Global default for flow.cylc[runtime][<namespace>][remote]retrieve job logs.

retrieve job logs command
Path

global.cylc[platforms][<platform name>]retrieve job logs command

Type

string

Default

rsync -a

If rsync -a is unavailable or insufficient to retrieve job logs from a remote platform, you can use this setting to specify a suitable command.

retrieve job logs max size
Path

global.cylc[platforms][<platform name>]retrieve job logs max size

Type

string

Global default for flow.cylc[runtime][<namespace>][remote]retrieve job logs max size for this platform.

retrieve job logs retry delays
Path

global.cylc[platforms][<platform name>]retrieve job logs retry delays

Type

time interval list

Global default for flow.cylc[runtime][<namespace>][remote]retrieve job logs retry delays for this platform.

tail command template
Path

global.cylc[platforms][<platform name>]tail command template

Type

string

Default

tail -n +1 -F %(filename)s

A command template (with %(filename)s substitution) to tail-follow job logs this platform, by cylc cat-log.

You are are unlikely to need to override this.

err tailer
Path

global.cylc[platforms][<platform name>]err tailer

Type

string

A command template (with %(job_id)s substitution) that can be used to tail-follow the stderr stream of a running job if SYSTEM does not use the normal log file location while the job is running. This setting overrides tail command template.

Examples:

# for PBS
qcat -f -e %(job_id)s
out tailer
Path

global.cylc[platforms][<platform name>]out tailer

Type

string

A command template (with %(job_id)s substitution) that can be used to tail-follow the stdout stream of a running job if SYSTEM does not use the normal log file location while the job is running. This setting overrides tail command template.

Examples:

# for PBS
qcat -f -o %(job_id)s
err viewer
Path

global.cylc[platforms][<platform name>]err viewer

Type

string

A command template (with %(job_id)s substitution) that can be used to view the stderr stream of a running job if SYSTEM does not use the normal log file location while the job is running.

Examples:

# for PBS
qcat -e %(job_id)s
out viewer
Path

global.cylc[platforms][<platform name>]out viewer

Type

string

A command template (with %(job_id)s substitution) that can be used to view the stdout stream of a running job if SYSTEM does not use the normal log file location while the job is running.

Examples:

# for PBS
qcat -o %(job_id)s
job name length maximum
Path

global.cylc[platforms][<platform name>]job name length maximum

Type

integer

The maximum length for job name acceptable by a job runner on a given host. Currently, this setting is only meaningful for PBS jobs. For example, PBS 12 or older will fail a job submit if the job name has more than 15 characters; whereas PBS 13 accepts up to 236 characters.

install target
Path

global.cylc[platforms][<platform name>]install target

Type

string

This defaults to the platform name. This will be used as the target for remote file installation. For example, if Platform_A shares a file system with localhost:

[platforms]
    [[Platform_A]]
        install target = localhost
clean job submission environment
Path

global.cylc[platforms][<platform name>]clean job submission environment

Type

boolean

Default

False

Job submission subprocesses inherit their parent environment by default. Remote jobs inherit the default non-interative shell environment for their platform. Jobs on the scheduler host inherit the scheduler environment (unless their job runner prevents this).

If, for example, the $PYTHON variable is different on the scheduler and the remote host the same program may run in different ways.

We recommend using a clean job submission environment for consistent handling of local and remote jobs. However, this is not the default behavior because it prevents local task jobs from running, unless $PATH contains the cylc wrapper script.

Specific environment variables can be singled out to pass through to the clean environment, if necessary.

A standard set of executable paths is passed through to clean environments, and can be added to if necessary.

job submission environment pass-through
Path

global.cylc[platforms][<platform name>]job submission environment pass-through

Type

list

List of environment variable names to pass through to job submission subprocesses.

$HOME is passed automatically.

You are unlikely to need this.

job submission executable paths
Path

global.cylc[platforms][<platform name>]job submission executable paths

Type

list

Additional executable locations to pass to the job submission subprocess beyond the standard locations /bin, /usr/bin, /usr/local/bin, /sbin, /usr/sbin, /usr/local/sbin. You are unlikely to need this.

max batch submit size
Path

global.cylc[platforms][<platform name>]max batch submit size

Type

integer

Default

100

Limits the maximum number of jobs that can be submitted at once.

Where possible Cylc will batch together job submissions to the same platform for efficiency. Submitting very large numbers of jobs can cause problems with some submission systems so for safety there is an upper limit on the number of job submissions which can be batched together.

[selection]

How to select platform from list of hosts.

New in version 8.0.0.

method
Path

global.cylc[platforms][<platform name>][selection]method

Type

string

Default

random

Options

random, definition order

Method for choosing the job host from the platform.

New in version 8.0.0.

Available options

  • random: Choose randomly from the list of hosts. This is suitable for a pool of identical hosts.

  • definition order: Take the first host in the list unless that host was unreachable. In many cases this is likely to cause load imbalances, but might be appropriate if following the pattern hosts = main, backup, failsafe.

[localhost]
Inherits

global.cylc[platforms][<platform name>]

A default platform defining settings for jobs to be run on the same host as the workflow scheduler.

Attention

It is common practice to run the Cylc scheduler on a dedicated host: In this case “localhost” will refer to the host where the scheduler is running and not the computer where you ran “cylc play”.

hosts
Path

global.cylc[platforms][localhost]hosts

Type

list

Default

localhost

[selection]
Inherits

global.cylc[platforms][<platform name>][selection]

method
Path

global.cylc[platforms][localhost][selection]method

Type

string

Default

definition order

[platform groups]

Platform groups allow you to group together platforms which would all be suitable for a given job.

New in version 8.0.0.

When Cylc sets up a task job it will pick a platform from a group. Cylc will then use the selected platform for all interactions with that job.

For example, if you have a group of computers without a shared file system, but otherwise identical called bigmachine01..02 you might set up a platform group [[bigmachines]]platforms=bigmachine01, bigmachine02.

See also

[<group>]
platforms
Path

global.cylc[platform groups][<group>]platforms

Type

list

A list of platforms which can be selected if flow.cylc[runtime][<namespace>]platform matches the name of this platform group.

New in version 8.0.0.

[selection]
method
Path

global.cylc[platform groups][<group>][selection]method

Type

string

Default

random

Options

random, definition order

Method for selecting platform from group.

New in version 8.0.0.

options:

  • random: Suitable for an identical pool of platforms.

  • definition order: Pick the first available platform from the list.

[task events]

Global site/user defaults for flow.cylc[runtime][<namespace>][events].

execution timeout
Path

global.cylc[task events]execution timeout

Type

time interval

handlers
Path

global.cylc[task events]handlers

Type

list

handler events
Path

global.cylc[task events]handler events

Type

list

handler retry delays
Path

global.cylc[task events]handler retry delays

Type

time interval list

mail events
Path

global.cylc[task events]mail events

Type

list

submission timeout
Path

global.cylc[task events]submission timeout

Type

time interval