Input Variables, Rose Metadata and Upgrade Macros#
Sometimes the developer needs to alter model namelists and input variables. A common reason is for the inclusion of a new piece of code which has to be turned off by default.
If a developer changes the namelist inputs they are also expected to alter the following areas of the code:
The inclusion of appropriate defensive checks.
Changes to Rose metadata.
Upgrade macros.
Defensive checks abort the model run if the user sets variables outside of their expected range or a combination of variables that will lead to an error. Most namelist modules contain a subroutine which performs this checking and which can be modified.
The project metadata can be found in the following locations:
vnXX.Y_<_branch_name>/rose-meta/um-atmos/HEAD/rose-meta.conf
vnXX.Y_<_branch_name>/rose-meta/*/*/HEAD/rose-meta.conf
vnXX.Y_<branch_name>/<sub-module>/rose-meta/*/HEAD/rose-meta.conf
All new namelist variables need a new entry so that the metadata loads into the Rose GUI for users to switch it on. Additionally, sometimes the metadata needs to be modified without changing a namelist variable. Guidance for updating the metadata is available.
Note
JULES developers also need to update the JULES documentation whenever they add or remove namelist variables.
Important
All changes which alter namelists require an upgrade macro for them to work with the model.
Changes to the metadata which don’t involve namelist changes may or may not require an upgrade macro. If you are unsure whether a UM change needs an upgrade macro, then run the following command on your branch:
rose stem --group=scripts
If all of the tests pass then there is no requirement to add an upgrade macro. If any of the metadata tests fail, then the developer should add a blank upgrade macro which contains no upgrade commands but simply points the rose stem suite to the new metadata.
How to add an upgrade macro to your branch#
Please see this page for further information.
Tip
When developing a change that updates the input and/or user interface, then repeatedly running/reverting the upgrade macro on the dev branch, or creating many test branches can be tiresome. Consider working up your change with the new options hard-coded in until such time as you are ready to connect up to the input for real.
Important
If your development includes an upgrade macro, you must add the
macro keyword to your ticket.
Do not apply the upgrade macro to your dev branch prior to the review process. Instead you must create a test branch. See Testing Your Change.