Using the UM Git test suites

Using the Git-based UM/UKCA test suites : UM14+

14.1: (2026.03.1) u-dx502

14.0: (2025.12.1) u-dw675

The workflows listed here can be executed on Met Office EX and the Monsoon3 HPC. (vn14+ only)

Pre-requisite

In addition to other Git setup on the parent Rose UKCA suites page:'. The HPC systems (Ex, Monsoon) do not have access to github.com to extract any source code directly. To use these workflows on the HPCs, the source needs to be accessed from site-specific mirrors (same as MOSRS code (e.g. fcm:um.xm_br). To force the extract tasks to use mirrors, enter the following commands :
On Monsoon:
$ git config --global url."/path/to/local/mirrors/".insteadOf "localmirrors:" $ git config --global --add safe.directory "/path/to/local/mirrors/*"
On Met Office EX:
$ git config --global url."host:/path/to/local/mirrors/".insteadOf "localmirrors:"
On Met Office VDI:
$ git config --global --add safe.directory "/path/to/local/mirrors/*"

Pl get in touch for the paths to the local mirrors, as these could change in the future.

Using the Test workflows

1. Create a suitable folder for the suite. (default name ~/roses)
2. cd to the folder and create a copy of the Suite

   ~/roses $ rosie copy u-dx502 (See suites for other versions above)

   This will create a copy of the suite (probably as) u-xxNNN and check it out to the ~/roses folder.

3. To ensure that the base settings work for you:

   $ cd ~/roses/u-xxNNN

   rose edit

   Under suite conf --> template variables panel, select Site : as Meto_exab ; Meto_excd ; Monsoon

   For Monsoon, this will prompt for choice of the account to be used

   ACCOUNT_MONSOON : The Monsoon account (project) under which the suite is to be run. (You need to be a part of that project!) (As of March 2026 --enter other'). .

   Execution options
   

   Compilation (Build) On/Off: BUILD=true/false

   StratTrop Chemistry scheme: RUN_STRATTROP=true/false

   CRI-Strat Chemistry scheme: RUN_CRI=true/false

   Offline Oxidants Chemistry scheme: RUN_OFFLINE=true/false

   Run KGO, PE, OpenMP, NRUN-CRUN and Rigorous build Tests: RUN_TESTS=true/false (additional option RUN_RIGOROUS=true/false)

   Run Housekeeping to clear model output: HOUSEKEEP=true/false

   Setting Offline, StratTrop, CRI-Strat options to false will convert the suite to a compile-only job.

   Save and exit

   $ cylc vip u-xxNNN (can be executed from anywhere as Cylc will search for workflow in ~/roses and ~/cylc-src)

   vip = validate, install and play (equivalent to rose suite-run at Cylc-7)

   This will check and preprocess the configuration, install it in $HOME/cylc-run and launch the tasks in the background.

   Note:' Each instance of the workflow is installed in a separate run folder e.g. u=xxNNN/run1, u-xxNNN/run2, etc. This can be overridden by using --no-run-name argument

   Monitoring the workflow

   At Cylc-8 there are two options depending on the Site (especially X-display, Cylc-hub server and browser configurations). On Met Office systems the Cylc-Hub server can be launched via web browsers:

   https://cylchub/user/(myusername)/cylc/#/

   For Monsoon, see https://code.metoffice.gov.uk/doc/monsoon3/faqs.html#can-i-use-the-cylc-gui-on-cazccylc1

   Where browser-based access in not available a simple command-line/ cursor-based utility is available:

   $cylc tui

   For further details refer to Cylc8-UIs and Task States

   Once all the tasks complete (Status = stopped with 'succeeded' or check output in the GUI), the Suite can now be modified to test your changes.

   Additional Options:

   Change the length of the run(s): Set RUN_TESTS=false, this will activate the TASKEND and DUMPFREQ options. Modify TASKEND='0,Months,Days,Hours,Minutes,0' (Note: Climate meaning and suite-cycling is Off, so the apps can be run only up to one month)

   Change the frequency of restart dumps: set DUMPFREQ=number-of-days (1-day by default).

   Both these options are only available if testing is switched Off, since the tests require a specific run-length and dumping frequency.

4. Testing your UM, UKCA (or JULES, SOCRATES, CASIM) branches

   If you are only making changes to the code and not modifying any namelists, the suite only needs to be pointed to the new branch.

   For git-based workflows, the atmospheric model components are specified via a dependencies.yaml file at the top-level. This contains source specifications in the format:

   repo:

   source: Is either the url to the repository (the upstream or a fork) or a path to a local clone with format `host:/path/to/clone`

   ref: Is a valid git reference. This can either be a commit hash, a tag or a branch name

   Note: To use committed branches, these need to be included in the Met Office mirrors local to each system as the HPCs do not have access to github.com to download these. To include your branch in the local mirrors, invite the mo-gitassist bot to your fork as described here.

   Note also that it can take upto 10 minutes for any committed changes to be copied over to the mirror.

   To use your UKCA branch, edit depedencies.yaml :

   ukca:

   - source: git@github.com:username/ukca.git

   ref: my_branch_name
   

   To use a local clone ('working copy')

   - source: <host>:/path/to/local/git/sources/ukca (do not add .git)

   ref : my_branch_name

   host can be skipped for Monsoon as same filesystem is visible on cylc and HPC nodes

   It is also possible to specify multiple branches in this way, but it is up to the user to ensure these merge cleanly

   Now rerun the suite:

   $ cylc vip u-xxNNN

   As mentioned, this will launch the workflow in a completely new runX folder, keeping your original run intact

   If any code changes are expected to change the results for this configuration, failure of the comparison against Known Good Output (KGO) i.e. the rose_ana_atmos_*_kgo tasks can be ignored. However, if the comparison tests fail unexpectedly, this indicates a bug somewhere in the implementation which needs to be traced, corrected and re-tested.

5. Namelist changes

   If there are any modifications to the namelists e.g. addition or deletion of items, moving items between namelists, these need to be applied in u-xxNNN/app/um/rose-app.conf

   Note: Since the base app/um/rose-app.conf needs to work for both UKCA configurations, any new settings that are specific to a configuration need to be made in the optional configurations viz app/um/opt/rose-app.offline.conf and app/um/opt/rose-app-stratdiags.conf.

   For adding the accompanying metadata changes:

   Modify the meta-data file : your-um-clone/rose-meta/um-atmos/HEAD/rose-meta.conf to add/remove/modify the namelist items.

   Edit the u-xxNNN/app/um/rose-app.conf and replace the line:

   meta=um-atmos/vn14.1 (or earlier vn14.X) with meta=/path/to/your-um-clone/rose-meta/um-atmos/HEAD

   Open the apps with rose edit to ensure that the namelist changes are consistent with the metadata.

   Now rerun the suite to make sure the Rose namelist changes are consistent with the Fortran namelist changes.

6. Making and Testing changes to STASHmaster

   This is actually easier than updating in FCM workflows, since the UKCA test suites are set up to use the git-extracted STASHmaster by default. So, just adding your branch/ clone to dependencies.yaml will ensure that the merged STASHmaster is used by the UM run. However, for the GUI to see the e.g. new items, the metadata still needs to be pointed to your clone:

   Edit the u-xxNNN/app/um/rose-app.conf and replace the line:

   meta=um-atmos/vn14.1' with meta=/path/to/your-um-clone/rose-meta/um-atmos/HEAD

   Commit the suite-changes and re-run as normal

Warning: If any of the tasks in the workflow fails, the corresponding housekeeping task will not be carried out and all the data generated will remain in $DATADIR/cylc-run/runX/u-xxNNN on the HPC. This may have to be cleaned manually after testing through the command:

$ cylc clean u-xxNNN (or u-xxNNN/runX)

For other Cylc-8 commands to stop/ restart/ reload workflows, refer to the Official Guide