Running a Cylc Workflow#

Now that you have successfully copied and edited a workflow, you are ready to run it! This section will guide you through the process of installing and running your workflow, monitoring its progress, and verifying that it has completed successfully.

Installing and Running the Workflow#

Navigate into the roses/<suite-id> directory you created.

Validate the workflow, install it to ~/cylc-run and play it using:

cylc validate-install-play --opt-conf-key=meto-exab

# Or for ease of typing: cylc vip -O meto-exab

See also

For help choosing the correct Monsoon3 service and finding the official setup guidance, see Using Monsoon3.

cylc validate-install-play --opt-conf-key=monsoon

# Or for ease of typing: cylc vip -O monsoon

Warning

“Other” means your own machine, or a system run by another institution (see Choosing your platform). This step cannot be completed there without local equivalents of the Met Office services it depends on: a supported LFRic build environment, repository access, shared ancillary data, and an HPC batch queue. The commands below are given so you can follow along and adapt them to your site, not because they will work unchanged.

cylc validate-install-play --opt-conf-key=<yoursite>

# Or for ease of typing: cylc vip -O <yoursite>

Site settings are stored as Rose Optional Configuration files. For example a configuration file opt/rose-suite-yoursite.conf would be selected using -O yoursite.

See also

Cylc Compound Commands

Note

We recommend opening a separate terminal window to monitor your workflow, so you can track progress without disrupting your main workflow terminal.

Monitoring Progress#

Use one of the following Cylc commands to monitor task states:

Running graphical applications over SSH

If you are connected to a remote system over SSH, graphical applications need X11 forwarding to display on your computer. Start an X server on your computer first (for example, XQuartz on macOS), then connect from a terminal using generic host details supplied by your service:

ssh -AY <remote-host>

Repeat the options for every additional SSH hop. The -Y option enables trusted X11 forwarding. The -A option forwards your SSH authentication agent and should only be used with systems you trust. A terminal integrated into an editor such as VS Code works in the same way as any other terminal.

On the system where you will start the graphical application, run echo "$DISPLAY". It should return a value. If it is blank, disconnect and reconnect with X11 forwarding enabled at every hop before continuing.

cylc gui
# or, if you prefer the terminal interface
cylc tui

See also

For help choosing the correct Monsoon3 service and finding the official setup guidance, see Using Monsoon3.

cylc tui

Note

Use cylc tui on Monsoon3. cylc gui needs a browser or an X11 connection that is not available from every Monsoon3 service.

Note

“Other” means your own machine, or a system run by another institution. You provide the environment yourself. See Choosing your platform.

cylc gui
# or, if a graphical interface is not available
cylc tui

Both interfaces show nearly identical information, so the choice is largely personal preference:

  • cylc gui — easier to interact with, but needs a browser or an X11 connection.

  • cylc tui — lightweight and works in any terminal without X11.

Verifying the Workflow Has Run Successfully#

After successful completion of the workflow, you should see all tasks marked as succeeded in the monitoring interface. You can also inspect the output files generated by the model in the suite run directory to confirm that the expected diagnostics or fields are present.

As a check:

  • Confirm all required tasks have the succeeded status.

  • Inspect model output in the suite run directory.

  • Validate expected files, fields, or diagnostics from the exercise.

Restarting a Workflow#

If you have a workflow that has finished running and you wish to make a change and restart it, use the cylc vr command:

cylc vr <suite-id>/run#

cylc vr <suite-id>/run#

cylc vr <suite-id>/run#

This will validate and reinstall the workflow, capturing any changes you have made, and then continue running from where it left off.

Stopping or Cleaning a Workflow#

To stop a running workflow:

cylc stop <suite-id>

cylc stop <suite-id>

cylc stop <suite-id>

Note

You do not need to wait for the workflow to stop before removing it.

To remove an installed workflow:

cylc clean <suite-id>

cylc clean <suite-id>

cylc clean <suite-id>

This removes the workflow from the system, but the suite directory will still exist in ~/roses. You can remove this manually if you wish.