Skip to content

Sharing JULES metadata

Jump to bottom
Maggie edited this page Aug 29, 2026 · 1 revision

Background

A number of Met Office Science Repository Service (MOSRS) tickets dealt with the consolidation of metadata between the UM and JULES since 2017 as well as the following talks at JULES Science meetings:

The infrastructure now exists to allow the JULES metadata to be largely be identical regardless of the parent model (standalone, UM or LFRic). This allows the majority of JULES metadata to be shared and exist in one place in the JULES repository rose-meta/jules-shared and imported to the parent model metadata. As a result of historical differences there are still a large number of differences between the parent model metadata and work is continuing to consolidate and migrate metadata to rose-meta/jules-shared. Even though we have been working towards the scenario where metadata can be identical there are cases where there does genuinely need to be a difference for example, where the item doing the triggering belongs in the parent model (e.g. UM or LFRic) and should not be shared with JULES or vice versa, which prevents the metadata from actually being identical. The framework also accounts for these genuine differences by allowing amendments in the parent metadata so the bulk of the metadata can still be shared.

The shared metadata only needs to be changed once in the JULES repository, leading to a reduction in admin overheads and undesirable divergence making it more robust. There are also scientific benefits. The science pull through becomes a simpler process and offline equivalent runs can be easily created as the JULES section of the rose-app.conf file in whatever parent model can then be directly transferred to a JULES suite. The l_parent_model switch via the metadata automatically triggers off any unavailable options and the validator macro via fail-if/warn-if will suggest other changes to make.

Shared metadata structure

The metadata for each JULES namelist has a separate metadata directory and each file is imported into a parent metadata file. This makes metadata files more manageable in size, easier to share between components and the ownership of the metadata more transparent for code management purposes.

The metadata directory structure in each repository is descibed in the following sections. This is a snapshot of the current status at the time this wiki was updated.

JULES repository

This is a list of the namelists that have been migrated to jules-shared.

rose-meta/jules-shared/jules-hydrology/HEAD (partial)
rose-meta/jules-shared/jules-nvegparm/HEAD
rose-meta/jules-shared/jules-pftparm/HEAD
rose-meta/jules-shared/jules-radiation/HEAD (partial)
rose-meta/jules-shared/jules-snow/HEAD (partial)
rose-meta/jules-shared/jules-soil/HEAD (partial)
rose-meta/jules-shared/jules-surface-types/HEAD (partial)
rose-meta/jules-shared/jules-surface/HEAD
rose-meta/jules-shared/jules-urban/HEAD
rose-meta/jules-shared/jules-vegetation/HEAD (partial)
rose-meta/jules-shared/jules-model-environment/HEAD
rose-meta/jules-shared/jules-sea-seaice/HEAD

with more directories being added as more namelists migrate. Some are still in a state of partial migration as these are also imported to LFRic apps where they are used in the build to generate the namelist reading routines. These files are imported into parent metadata files, which exist in the JULES repository to keep all JULES related metadata together and reduce the need for changes in other respositories. These parent metadata files are then imported into the parent repositories. The aim is for the majority of the metadata to reside in jules-shared with only import statements and required amendments in the parent files. As more metadata is migrated to jules-shared, the need for amendments should reduce.

jules-standalone

The JULES standalone parent metadata file is:

rose-meta/jules-standalone/HEAD/rose-meta.conf

which contains

# Please see jules:wiki:SharingJULESmetadata
  	
import=jules-shared/jules-hydrology/HEAD
      =jules-shared/jules-model-environment/HEAD
      =jules-shared/jules-nvegparm/HEAD
      =jules-shared/jules-pftparm/HEAD
      =jules-shared/jules-radiation/HEAD
      =jules-shared/jules-snow/HEAD
      =jules-shared/jules-soil/HEAD
      =jules-shared/jules-surface/HEAD
      =jules-shared/jules-surface-types/HEAD
      =jules-shared/jules-urban/HEAD
      =jules-shared/jules-vegetation/HEAD

Followed by any standalone amendments including standalone IO namelists.

jules-um

The JULES-UM parent metadata file is:

rose-meta/jules-um/HEAD/rose-meta.conf

which contains

###############################################################################
# This is the UM flavour of the JULES metadata
###############################################################################
# This should only contain:
# * Import statements from jules-shared.
# * UM specific amendments to the imported metadata.
# The majority of the metadata should be under rose-meta/jules-shared.
#
# This file is imported by um-atmos in the UM repository.
#
# Please see jules:wiki:SharingJULESmetadata
###############################################################################

import=jules-shared/jules-hydrology/HEAD
      =jules-shared/jules-model-environment/HEAD
      =jules-shared/jules-nvegparm/HEAD
      =jules-shared/jules-pftparm/HEAD
      =jules-shared/jules-radiation/HEAD
      =jules-shared/jules-snow/HEAD
      =jules-shared/jules-soil/HEAD
      =jules-shared/jules-surface/HEAD
      =jules-shared/jules-surface-types/HEAD
      =jules-shared/jules-urban/HEAD
      =jules-shared/jules-vegetation/HEAD

Followed by any UM specific amendments.

jules-lfric

The JULES LFRic apps parent metadata file is:

rose-meta/jules-lfric/HEAD/rose-meta.conf

contains

##############################################################################
# This is the LFRic flavour of the JULES metadata
###############################################################################
# This should only contain:
# * Import statements from jules-shared.
# * LFRic specific amendments to the imported metadata.
# The majority of the metadata should be under rose-meta/jules-shared.
#
# This file is imported by jules-lsm in the LFRic apps repository.
#
# Please see jules:wiki:SharingJULESmetadata

import=jules-shared/jules-hydrology/HEAD
      =jules-shared/jules-nvegparm/HEAD
      =jules-shared/jules-pftparm/HEAD
      =jules-shared/jules-radiation/HEAD
      =jules-shared/jules-sea-seaice/HEAD
      =jules-shared/jules-snow/HEAD
      =jules-shared/jules-soil/HEAD
      =jules-shared/jules-surface/HEAD
      =jules-shared/jules-surface-types/HEAD
      =jules-shared/jules-urban/HEAD
      =jules-shared/jules-vegetation/HEAD

Followed by any LFRic apps specific amendments.

LFRic apps repository

The LFRic apps repository contains the LFRic apps JULES Land Surface Model interface metadata

interfaces/jules_interface/rose-meta/jules-lsm/HEAD

which contains

###############################################################################
# JULES metadata structure:
# - jules-lsm   = LFRic-JULES interface metadata not relevant to JULES
#                 repository.
#               = Imports jules-lfric.
#
# jules-lfric is imported from the JULES repository
#
# Please see https://code.metoffice.gov.uk/trac/jules/wiki/SharingJULESmetadata
###############################################################################

import=jules-lfric/HEAD

and metadata related to the LFRic apps JULES interface. JULES related metadata should not be added to this file and should be added to jules-lfric in the JULES repository.

UM repository

The UM repository contains the UM atmosphere metadata:

rose-meta/um-atmos/HEAD/rose-meta.conf

which contains

# Please see jules:wiki:SharingJULESmetadata

import=jules-um/HEAD

um-atmos currently still contains a large amount of JULES metadata.

What's in jules-shared?

All metadata that can be shared with LFRic can reside in jules-shared.

compulsory=     # true for all namelist variables, false for derived variables
description=    # For all variables
fail-if=        # Required for rose metadata checking
ns=             # Namepsace
range=          # For integer/real types
sort-key=       # For ordering an option within its namespace (see convention below)
title=          #
trigger=        # Add if any other panels/namelists/variables etc are dependent on this variables settings
type=           # Required for all namelist variables except enumerators
url=            # Link to JULES online documentation
warn-if=        # Required for rose metadata checking

A major advantage of LFRic, which cuts down on duplication and the overheads of adding a new scheme, is the introducton of a configurator tool to auto generate Fortran namelist loading modules, instead of the user having to write them, which is currently the case in JULES & the UM. This requires extra properties, used by the configurator, but not by Rose so they need to be user ignored (!). These are as follows with short description of their purpose to allow them to be recognised.

!bounds=        # Required if "length=:" present and you wish to use another variable to specify the length dimension 
!enumeration=   # Required for enumeration variables, `Note:` This will flag the variable as an enumeration, not the value, set it to true to be consistent with rest of metadata 
!expression=    # Required for derived variables
!kind=          # Set to default if omitted, only used when type != character
!string_length= # Set to default if omitted, only used when type == character

These can happily reside in the jules-shared directory as they are ignored by Rose so you will see them in jules-shared files, although JULES does not use them yet. Please see the following extract from rose-meta/jules-shared/jules-vegetation/HEAD/rose-meta.conf as an example:

[namelist:jules_vegetation]
compulsory=true
description=Options for vegetation parametrisations
ns=namelist/JULES Science Settings/jules_vegetation
sort-key=Section-A12b
title=Vegetation options
url=http://jules-lsm.github.io/latest/namelists/jules_vegetation.nml.html

[namelist:jules_vegetation=can_rad_mod]
compulsory=true
description=Vegetation canopy radiation model
!enumeration=true
sort-key=Panel-I13
url=http://jules-lsm.github.io/latest/namelists/jules_vegetation.nml.html#JULES_VEGETATION::can_rad_mod
value-titles=1: Single canopy layer,
            =4: Multi-layer two stream approach,
            =5: Multi-layer with Sunfleck penetration and sunlit and shaded leaves,
            =6: Multi-layer with exponential decline in leaf N

[namelist:jules_vegetation=l_limit_canhc]
compulsory=true
description=Logical for capping vegetation canopy areal thermal heat capacity
!kind=default
sort-key=Panel-I04
type=logical
url=http://jules-lsm.github.io/latest/namelists/jules_vegetation.nml.html#JULES_VEGETATION::l_limit_canhc

[namelist:jules_vegetation=l_spec_veg_z0]
compulsory=true
description=Logical switch for setting explicit vegetation roughness lengths
!kind=default
sort-key=Panel-I05
type=logical
url=http://jules-lsm.github.io/latest/namelists/jules_vegetation.nml.html#JULES_VEGETATION::l_spec_veg_z0

What's in jules-standalone, jules-lfric or jules-um?

These are the main metadata files for the JULES parent model. They contain:

  1. Import statements for the shared files.
  2. Everything specific to the parent model related to the JULES repository, for example I/O.
  3. Everything that cannot be shared i.e. required amendments for example values, some trigger.
  4. Everything that has not yet been shared.

Using the jules_vegetation namelist as an example, the parent specific entries for these are:

jules-standalone

[namelist:jules_vegetation=can_rad_mod]
trigger=namelist:jules_vegetation=ilayers: 4,5,6;
	   =namelist:jules_pftparm=knl_io: 6;
values=1,4,5,6
widget[rose-config-edit]=cylc8_compat.ComboBoxValueWidget

[namelist:jules_vegetation=l_spec_veg_z0]
trigger=namelist:jules_pftparm=dz0v_dh_io: .false.;
	   =namelist:jules_pftparm=z0v_io: .true.;

jules-lfric

[namelist:jules_vegetation=can_rad_mod]
values='one','four','five','six'

[namelist:jules_vegetation=l_spec_veg_z0]
trigger=namelist:jules_pftparm=z0v_io: .true.;
	   =namelist:stochastic_physics=rp_lsfc_z0v: .true.;
	   =namelist:stochastic_physics=rp_lsfc_z0v_max: .true.;
	   =namelist:stochastic_physics=rp_lsfc_z0v_min: .true.;

Noting that [namelist:jules_vegetation=l_limit_canhc] does not feature in jules-standalone, jules-lfric or jules-um as it can be shared in its entirety. Instructions added to the parent metadata will override what is initially imported. There are extra triggers for l_spec_veg_z0 as these are specific to LFRic apps.

Values

As a result of the configurator tool, there is a fundamental difference between LFRic and JULES metadata, concerning the values= field. LFRic introduces a key new data-type: the enumeration. Enumerations replace integer 'magic-number' inputs, instead using human-readable text-strings in both the metadata and code. This leads to a difference in the values= field and therefore has to reside in the parent metadata file.

Triggers

trigger= fields cannot be shared when the item referenced does not exist in the parent model. For example, namelist:jules_vegetation=ilayers in LFRic does not exist as a namelist input yet and is thus not in the metadata (it is currently set as a default in the code). The trigger can therefore not be shared and must reside in the jules-standalone metadata. The triggers for l_spec_veg_z0 cannot be shared as namelist:stochastic_physics is an LFRic apps namelist. Unfortunately single triggers cannot be added as an amendment and the whole trigger list needs to be added even if there is only one item that is different. As more options are added to the shared metadata then more triggers can also migrate.

sort-keys convention

The LFRic format of the sort keys has been adopted and extended. For instance:

sort-key=Panel-A00a
  • "A" is an uppercase letter associated with the namelist
  • "00" is a number associated with the namelist item
  • "a" is a lower case letter associated with items triggered by item 00

This makes it easier to add new items that are triggered by existing switches without having to renumber all the sort keys.

Making changes to jules-shared

As jules-shared is imported to both LFRic apps & UM, developments to jules-shared need to be picked up from a JULES local clone or branch. Regardless of repository (lfric_apps, um or jules) as the import path is relative to rose-meta, the path needs to be explicitly set to run Rose utilities, which require metadata e.g. rose edit, rose app-upgrade, rose macro, on the command line unless using a script which sets the path from dependencies.yaml. The most straightforward way for the Rose utilities to pick up jules-shared developments is to export the ROSE_META_PATH environment variable i.e.

export ROSE_META_PATH=/absolute/path/to/JULES/local/clone/rose-meta

and nothing further needs to be done (making sure it's the full path to the rose-meta directory). Bearing in mind that the required branch must be the active branch in the JULES local clone. It can also be specified for individual commands using a colon separated list using the "-M/--meta-path=" e.g.:

rose app-upgrade -M rose-meta:/absolute/path/to/JULES/local/clone/rose-meta -C rose-stem/app/um_ga7_amip -a vnY.Y_txxxx

However, there are certain Rose utilities, e.g. rose metadata-check, that does not take a colon separated list, so the former method is more straightforward.

Future plans

This is a pathway to methodically consolidate and migrate metadata until we have one shared source existing in the JULES repository with the aim that no JULES metadata remains in the parent repositories. The JULES science namelists are being moved one namelist at a time from the metadata in the parent repositories (um-atmos and jules-standalone) to jules-shared.

The shared metadata solution will also be rolled out to Rivers-standalone.

Implications for users & developers

Users

The only impact that users should see is the relative location of the panels within the GUI move while the migration takes place as a result of sort-key changes.

Developers

When developers are making metadata changes in a migrated namelist, they will need to consider whether the change should be in jules-standalone, um-atmos or the appropriate shared metadata file under jules-shared. While the project is ongoing please contact @maggiehendry for advice. Where these namelist are imported to jules-lfric, jules-standalone or jules-um, science options that are not being made available to the parent model must explicitly be made unavailable both in the metadata using l_jules_parent (LFRic apps for technical reasons has it's own version in jules-lfric) and in the code using the appropriate routine:

src/control/lfric/check_unavailable_options_mod.F90
src/control/standalone/check_unavailable_options_mod.F90
src/control/um/check_unavailable_options_mod.F90

Science options should not appear to be available when they are not. Conversely, when making science options available, these need to be removed.

Changes to jules-shared will require Rose stem testing of any model that imports them.

When using Rose utilities on the command line, the ROSE_META_PATH environment variable will need to be set as described in Making changes to jules-shared.

Required LFRic app changes

The configurator tool uses the metadata to create routines to read the namelists into LFRic apps. JULES namelist items must be plumbed from the LFRic apps JULES interface to the modules used in the JULES respository in interfaces/jules_interface/source/support/jules_physics_init_mod.f90 or in its subroutines <jules_namelist>_init_mod.f90 (jules_physics_init is in the process of being modularised).

Clone this wiki locally