Basics of JULES rose-stem

What is JULES rose-stem?

This is the test battery/suite of regression tests that code development changesets must be tested on.

JULES needs to pass all of the tests for code to be accepted on the trunk.

Use the command rose stem --group=all to test all of the groups in the rose-stem test battery/groups.

Note for quick preliminary testing use --group=tutorial for the VM, JASMIN, cehlw1, niwa or --group=tutorial_linux for meto-linux or group=tutorial_xc40 for the meto-xc40 (this includes MONSooN).




Other groups are:

• loobos
• gswp2
• linux, meto only
• xc40, meto only
• tutorial
• tutorial_linux, meto only
• tutorial_xc40, meto only





Running rose-stem

The following is an example/reminder of how to run rose-stem. Use it to help with the practicals.

# Checkout the code to run rose-stem test for
mkdir -p ~/jules/vn4p9
cd ~/jules/vn4p9
fcm co fcm:jules.x_tr@vn4.9
cd ~/jules/vn4p9/trunk
rose stem --group=tutorial --new --name=my_vn4p9tr_test

Rose-stem workflow

While this is running we can discuss the workflow of rose-stem.

fcm_make_debug          gswp2_*           nccmp gswp2_*
      &           =>       &        =>          &          => housekeep
fcm_make_omp            loobos_*          nccmp_loobos_*

fcm_make_omp            eraint_*          nccmp_eraint_*

This can be explained by the following flow diagram:

fcm-make task  =>  JULES configurations either  =>  netcdf comparison task with KGO,          => tidy up task
                  using loobos/GSWP2/ERAINT data       Known Good Output for each JULES config.

The JULES output for a configuration from a trunk run version of the code, usually saved in the location /jules/rose-stem-kgo/vn#.# is known as the Known Good Output (KGO). The KGO is compared to the current output created by the rose-stem jules configuration using a netcdf comparison tool, nccmp. If any of the nccmp tasks fail then the output in the current rose-stem tests does not match the KGO and this must be justified.
Justified reasons for changes to KGO and nncmp failures


• It a new configuration and therefore no previous KGO existed
• There was a mistake in the orginal code and this has been corrected, plots and numbers show evidence of the improvment and have module leader approval and they MUST be Cc'ed in the Ticket.
• The code has been updated with new science and plots/figures/paper etc provide evidence

Present Module leaders are:

Module	Leader(s)	Email(s)
Surface	John Edwards and Richard Essery	john.m.edwards@metoffice.gov.uk and richard.essery@ed.ac.uk
Hydrology	Nic Gedney and Anne Verhoef	nicola.gedney@metoffice.gov.uk and a.verhoef@reading.ac.uk
Vegetation	Anna Harper and Lina Mercado	a.harper@exeter.ac.uk and l.mercado@exeter.ac.uk
Biochemistry	Eleanor Burke and Sarah Chadburn	eleanor.burke@metoffice.gov.uk and sarah.chadburn@metoffice.gov.uk/s.e.chadburn@exeter.ac.uk
Biogenic Fluxes	Gerd Folberth and Oliver Wild	gerd.folberth@metoffice.gov.uk and o.wild@lancaster.ac.uk
Technical Changes	TBC and TBC	TBC and TBC
Evaluation	Tristan Quaife and Graham Weedon	t.l.quaife@reading.ac.uk and graham.weedon@metoffice.gov.uk





Questions

1. What are the three ways for looking at the job stderr?
2. Where\What is the evidence for the Ticket Summary?
3. What does KGO mean?
4. When is it acceptable to have a failure in the KGO?




Answers

What are the three ways for looking at the job stderr?
In the gcylc GUI by right clicking on the task, select View, select job stderr.
In Rose Bush.
In the cylc-run/<SUITE_NAME>/log/job/1/<TASK_NAME>/NN directory.

Where\What is the evidence for the Ticket Summary?
The cylc-run/<SUITE_NAME>/trac.log file
What does KGO mean?
Known Good Output
When is it acceptable to have a failure in the KGO?
For example, when a bug has been identified and fixed, when the code has been improved.
These changes have to be justified usually with plots and approved by the code owner and Sci/tech Reviewer.

                            

Running JULES rose-stem and creating a branch and testing the new code in it

Please refer to the Working Practices for JULES development.


Here we will make a basic change to the JULES code and test it with the rose-stem test battery of tests.

We know that the JULES code passes all the tests from running it earlier, we will make a branch for your change and see if the branch change does not create failures.

Creating a Branch

Creating a branch from the latest code release of JULES:

cd ~jules

fcm bc tutorial_bc_rosestem fcm:jules.x_tr@vn4.9
please insert the most recent version number.
bc - means branch-create
"tutorial_bc_rosestem" will be the name of the branch.

If you do not have keywords setup you will have to use the URL: fcm bc tutorial_bc_rosestem https://code.metoffice.gov.uk/svn/jules/main/trunk@vn4.9

This will bring up a text editor window for you to add your commit message about the branch.

If you do not have text editor as default or wish to change the default you can use, for example: export SVN_EDITOR=vim

The editor window should look like this:

--Add your commit message ABOVE - do not alter this line or those below--
--FCM message (will be inserted automatically)--
Created /main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem from /main/trunk@5320.
--Change summary (not part of commit message)--
A    https://code.metoffice.gov.uk/svn/jules/main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem

Add a comment to the top of it and then close, save it and accept the change.

This should return text like the following:

[info] Source: https://code.metoffice.gov.uk/svn/jules/main/trunk@5320 (5320)
[info] vim: starting commit message editor...
Change summary:
--------------------------------------------------------------------------------
A    https://code.metoffice.gov.uk/svn/jules/main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem
--------------------------------------------------------------------------------
Commit message is as follows:
--------------------------------------------------------------------------------
Created /main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem from /main/trunk@5320.
--------------------------------------------------------------------------------
Create the branch?
Enter "y" or "n" (or just press <return> for "n") y
Committed revision ####.
[info] Created: https://code.metoffice.gov.uk/svn/jules/main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem

           

Working on the Branch

There are two different ways of working on a branch, for code development I use the first and for suite development I use the second. Both have different merits and are given below.

1. Check out a copy to a new directory in your ~jules/vn4p9/ directory.
   

   For example: fcm co fcm:jules.x_br/dev/MOSRS_USERNAME/BRANCH_NAME and then move to that directory.

2. Switch to the branch from within the directory of trunk@vn4.9.
   

   For example: fcm sw fcm:jules.x_br/dev/MOSRS_USERNAME/BRANCH_NAME.

Here we will use the first method (later we will use the second).




mkdir -p ~jules/vn4p9
cd ~jules/vn4p9
fcm co fcm:jules.x_br/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem
cd vn4.9_tutorial_bc_rosestem

HELPFUL HINT: if you forget your branch name you can list them using:

fcm bls

Now check the information for the directory of the repository that you are presently in (very helpful when using switch) and the status

fcm info

Path: .
Working Copy Root Path: /USER/jules/vn4.9_tutorial_bc_rosestem
URL: https://code.metoffice.gov.uk/svn/jules/main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem
Relative URL: ^/main/branches/dev/MOSRS_USERNAME/vn4.9_tutorial_bc_rosestem
Repository Root: https://code.metoffice.gov.uk/svn/jules
Repository UUID: ac5b6c67-d81e-4bef-bedc-f37a4dd2bd0a
Revision: 1222
Node Kind: directory
Schedule: normal
Last Changed Author: MOSRS_USERNAME
Last Changed Rev: 1234
Last Changed Date: 2030-12-01 09:21:40 +0000 (Mon, 01 Dec 2030)


fcm st

# returns nothing as there are no local/working copy changes in the directory.




Make a basic change to the branch:

Note we are not keeping this change so it is not important what it is.

cd ~jules/vn4p9/vn4.9_tutorial_bc_rosestem/
fcm st

#this returns nothing
cd rose-stem/
# edit the rose-suite.conf, change HOUSEKEEPING to false, save and close the file
fcm st
M       rose-suite.conf
# we have decided that we did not want to change that, so lets revert it using
# fcm.
fcm revert rose-suite.conf
fcm st

# this returns nothing as we have reverted the uncommitted change that we made
# in our local/working directory.
          

The fcm revert command is very helpful if you want to revert, one, a few or all local changes. See fcm revert --help for more options.




Now to make a change that we want to keep and test:

cd ~jules/vn4p9/vn4.9_tutorial_bc_rosestem/
# move to the source/root directory of the JULES code
cd src/science/snow
# edit tridag_mod.F90 ln 68 to be this:
  gamm(n) = c(n-1) / beta_2
# save and close the file
           

Test the change

1. Run rose-stem
2. Look at the appropriate logs to provide evidence of success or failure
3. What three methods can you use to find the answer for 2.?
4. Which do you prefer and why?

Answers and further instructions

                            
rose stem --group=tutorial --new #for meto-linux use --group=tutorial_linux

Example failures and successes:
Fails - fcm_make_meto_linux_gfortran_omp
Fails - fcm_make_meto_linux_gfortran_debug
Fails - fcm_make_meto_xc40_cee_debug
Fails - fcm_make_meto_xc40_cee_omp
Fails - fcm_make_meto_linux_intel_debug_noomp_nompi
Fails - fcm_make_meto_linux_intel_noomp_mpi
Succeed - fcm_make_meto_xc40_cce_omp
Succeed - fcm_make_meto_xc40_cce_debug
                            
                            




job stderr states IMPLICIT NONE....for data object "BETA_2"

Which is the change we made.

Now revert the change using FCM




The three methods are the gcylc GUI, Rose Bush and the cylc-run/ directory.




You should have reverted that change if you are following this tutorial, make sure there are no local changes by using fcm st if there are changes please revert them.





In the developer tutorial we will add a new variable, a new module etc.

We have created a branch, maked a change then reverted it, made another change, tested the change, found the error and corrected it by reverting the change.





A little more background information on the code repository...What does HEAD mean, etc?

The JULES code is part of the MOSRS repository.

The code is "tagged" at every release with a version number, for example vn4.9.

The working practices state that we should work at a "tagged" release. For example fcm bc my_jules_change fcm:jules.x_tr@vn4.9 this checkouts out the JULES code at vn4.9 and would provide the branch main/branches/dev/MOSRS_USERNAME/vn4.9_my_jules_change .

As from the day that "tagged" version of the JULES code is released the trunk is open for new changes to be added. New changes are added upto about three weeks before the next "tagged" version of the code is released. In that three weeks the next "tagged" release is being created and fully tested.

Near the end of a release cycle you may be asked to create a HEAD of Trunk branch, this is known as a HoT branch and is explained later. Instead of using fcm:jules.x_tr@vn4.9 you would use fcm:jules.x_tr@HEAD and the branch created would start with a r#### instead of vn#.# where the r#### is the revision number of the JULES code respository that the branch was created from.

Sometimes you are required to select a JULES code revision, for example if you want to work from a revision known committed branch. Instead of using fcm:jules.x_tr@vn4.9 you would use fcm:jules.x_tr@r### and the branch created would start with a r#### instead of vn#.# where the r#### is the revision number of the JULES code respository that the branch was created from.

Basics of Coding -UMDP3, Reviewing

Why are there coding standards and reviewing?

Coding standards provide quality assurance and help provide a consistent interface for development.

Using coding standards and following the working practices and the UMDP3 software standards aims to provide high quality code.

It is known that not all of the current JULES code meets the standards and it is being constantly improved/developed to achieve this goal.

No new code is allowed on the trunk unless it meets the coding standards.




Reviewing is a very important process, not only must code meet the coding standards and pass the regression testing (rose-stem) it must also go through a two stage review process.

• Stage one is the Sci/Tech Review - code must be approved by the appropriate module leader(s) which are to be Cc'ed in the Ticket. Then the ticket can be reviewed Scientifically/Technically by a specialist in the area whom has not been involved in the development of the code. Module leaders can give guidance on a suitable reviewer if required.
• Stage two is the Code Review - the code must meet the coding standards and be as efficient as possible. At present the code reviewer is either the JULES System Manager or a member of the UM Systems Team.




What are the top 10 Gotchas for code style in reviews?

• Brackets - please use brackets to make the equations easier to understand and check for typos.
• Alignment - please align code, this is especially important multi-line equations as it makes them easier to follow.
• Spaces around mathematical operators - makes equations easier to read and review.
• Comments - more are better, but keep them relevant and remember to answer all questions before submission for review.
• Align "&" at column 79- easier to read.
• 80 character line limit - easier to read.
• Remove trailing white spaces - easier to read.
• All Fortran keywords must be UPPER case and with the correct spacing, i.e. "END IF", "END DO", "IF (", "MAX(", "EXP(", LEN, KIND etc. Note the code at vn4.9 has had all of these corrected for the repository.
• trac.log evidence for rose stem test not being in the TicketSummary? page or not being the latest commit to the branch repository.
• rose config-dump - please run "rose config-dump <FILENAME>" on rose files that you have edited for them to be auto checked and corrected.

Working Practices and UMDP3 with the above 10 Gotchas should cover all the s=coding standards.

Basics of JULES rose suite

How are JULES-Rose suites run?

JULES-Rose suite can be run in two ways:

1. At command line

# first checkout the suite if there is not already have a local copy
# remember Rosie commands can be executed from anywhere and will populate the 
# correct directory for you, i.e. the roses/ directory.
rosie checkout <SUITE_ID>
# change to the directory of the local copy
cd ~roses/<SUITE_ID>
rose suite-run --new #--name=<DIFFERENT_NAME_IF_REQUIRED>

2. Via Rose Edit

# first checkout the suite if there is not already have a local copy
# remember Rosie commands can be executed from anywhere and will populate the
# correct directory for you, i.e. the roses/ directory.
rosie checkout <SUITE_ID>
# change to the directory of the local copy
cd ~roses/<SUITE_ID>
# open rose edit for the suite
rose edit
# now press the play button to run the suite

3. Via rosie go

rosie go
# select the suite to run and double click
# this opens rose edit
# now press the play button to run the suite

1. How can you reopen the gcylc GUI if accidently closed?
2. What does the gcylc GUI going blank usually mean?
3. What does a red square mean?
4. What does a grey square mean?
5. What does a green square mean?
6. Where is the output of a task usually located?

Answers

How can you reopen the gcylc GUI if accidently closed?
Two ways,
cylc gscan then double click on the name of the suite to open the gcylc GUI for,
or
cylc sgc --name=<SUITE_NAME>


What does the gcylc GUI going blank usually mean?
If there is "Stopped with succeeded" in the bottom left then it is finished


What does a red square mean?
The task has failed
What does a grey square mean?
The task has succeeded


What does a green square mean?
The task is running


Where is the output of a task usually located?
In the cylc-run/<SUITE_NAME>/work/1/<TASK_NAME>/output/ directory

                            




Who creates JULES-Rose suites?

There are some example suites that can be found on the JULES MOSRS pages

Some have been developed for the JULES-Rose tutorials:

• User Practical 5 and 6 - u-ai828 MetO Suite, u-ai829 VM Suite, u-ai843 JASMIN Suite, u-al388 MONSooN Suite.

Anyone can create JULES-Rose suites, but it is often best to start from a suite that is similar to the one that is desired for a given experiment.

Use ideas from others, it will save time.

Practical's

Practical 1 - Further JULES Rose Edit

Practical 1 will cover:

Make a change in Rose Edit and save it.

Search for an item in a namelist.

Make changes and undo the last one, save and commit changes.

Open the suite.rc to make changes and Other files.

View Ignored Variables and Latent Pages.

Rose Bush via Rose Edit.

Metadata and errors.




A greater understanding and familiarity of Rose Edit will provide a section of techniques for making changes to JULES-Rose suites allowing the user to choose their preferred method.

Make a change in Rose Edit and save it

Open Rose Edit for the suite u-ai828 Meto SPICE (u-ai829 VM, u-ai843 JASMIN, u-al388 MONSooN)




How To

# checkout the suite either using rosie go or command line

rosie go
# search for u-ai828 #(u-ai829 VM, u-ai843 JASMIN, u-al388 MONSooN)
# double click on it to check it out, this checks it out locally to your roses directory and opens Rose Edit

# at command line
rosie checkout u-ai828 #(u-ai829 VM, u-ai843 JASMIN, u-al388 MONSooN)
# this checks it out locally to your roses directory
cd ~/roses/u-ai828 #(u-ai829 VM, u-ai843 JASMIN, u-al388 MONSooN)
rose edit 
                            




Enable/point to the JULES code metadata if you have not already done so.

Follow the instructions below:
For example point to the trunk version of the JULES code metadata: /project/jules/vn4.9/trunk/ to the front of both of the paths for fcm_make and jules metadata.

Help on where to find the 3 locations

1. Index section on the left side -> fcm_make -> Build configuration -> Path to JULES source: /project/jules/vn4.9/trunk/rose-meta/jules-fcm-make/HEAD/rose-meta.conf
2. Index section on the left side -> fcm_make -> meta: /project/jules/vn4.9/trunk/rose-meta/jules-fcm-make/HEAD/rose-meta.conf
3. Index section on the left side -> jules -> meta: /project/jules/vn4.9/trunk/rose-meta/jules-standalone/HEAD/rose-meta.confcd




Save and check the changes.




Change the WALLTIME in the suite conf -> Runtime configuration from PT3H to PT2H40M.

The WALLTIME should have changed colour from black to blue. There should be blue dots next to suite conf and Runtime configuration.

To save the change click on a different index, for example fcm_make, then click Check and save the third icon from the left of the Rose Edit GUI, which is "Abc" underlined in a green wavy line.

Confirmation that the change has been made can be seen by the blue dots disappearing and the writing changing back to black.




Search for an item in a namelist

In the icon panel of the Rose Edit GUI there is a blank box and an icon on binoculars next to it. This is the search box and button.

Search output, press the search button repeatedly until all of the files with output are found.





Make changes and undo the last one, save and commit changes

Make some other changes:

• Change can_rad_mod from 4 to 1.
• Change the location of the output from './output' to './tester/output'

  What is the full path location that the new output directory would located?

• Change the JULES_OMP option to omp.

Save the changes.

How do you know that the changes are saved?




How To and Answer

Search "can_rad_mod"
It is located in jules -> namelist -> jules_vegetation the second box down.
Search "output"
It is located in jules -> namelist -> jules_output the second box down, output_dir.
Search "JULES_OMP"
It is located in fcm -> Build Configuration the third box down.
The blue dots and text go.
                            




Now undo the last change as we are not going to run with omp. This is done by using the Undo button. In the Rose Edit GUI this is the 6th icon button from the left and is a yellow backward curving arrow.

Note the yellow backwards arrow with a page included in the icon is the Undo Page button.

This and the green foreward curving arrow directly to the right can be used to undo and redo changes in the order that they were made.

Save the changes so there are only the three changes in total, WALLCLOCK, can_rad_mod and output_dir.

Select the Tools tab, select Launch Terminal. This opens a terminal with at the suite directory path. Now check for local changes fcm st.

M       app/jules/rose-app.conf
M       rose-suite.conf

To commit them to the repository fcm ci add a comment, save, close and accept/exit.

To revert all the changes before they are committed, close the Rose Edit GUI, fcm revert * -R.

Remember you can only commit changes if you are the suite owner as defined in the rose-suite.info file.




Open the suite.rc to make changes and Other files

Open Rose Edit again.

Click on suite conf, the right hand panel will display Other files, double click on the file suite.rc.




Other files -

There are other files, for example the Loobos data files are included in this suite.

Find them located via clicking on jules the right hand panel displays meta and Other files at the bottom of it.





View All Ignored Variables/Pages and Latent Pages

Some variable and pages are hidden from users as the default. These are known as Ignored Variable and Pages.

We may want to see them in the Rose Edit GUI, they can be made viewable by: selecting the View tab and then selecting View All Ignored Variables, View All Ignored Pages and View All Latent Pages.

With View All Ignored Variables selected click on the fcm_make -> Build Configuration section, it should now display three greyed out variables, which have the !! in front of them. This is how you would see then in a text editor, they are not used which is why they were not displayed.

With View All Ignored Pages selected click on the jules -> namelist, it should now display additional namelists, which have the !! in front of them. There should be nine. Click on one it should display:


The Latent Pages are not often required, only the poll option in Fcm Make may be useful at a later date. They show the possible other known pages that could be populated.




Rose Bush via Rose Edit

Please run the suite u-ai828 (meto-linux), or u-ai829 (VM), or, u-ai843 (JASMIN), or u-al388 (MONSooN) if you have not previously run it, note it was part of teh User Tutorial. The suite takes about 10 minutes to complete, you can run it by using the Play icon button from the Rose Edit GUI.

The output from the run can be accessed viewed in Rose Bush (the web browser output pages) by invoking Rose Bush using one of two options:

• Select the Tools tab and then select View Output

or

• Select the View Output folder icon, the 13th from the left.

Try one of the techniques.




Metadata and errors

What is metadata?

Metadata is included as part of the JULES code to help users understand the intended use of variables, switches, parameters, etc in JULES.

Using metadata

Creating metadata and testing the metadata that you have created is covered in Practical 7

If a change is made which does not comply with the metadata either within the JULES-Rose suite or the JULES-Rose code Rose Edit provides warnings for the user.

Remember that rose edit warnings/errors can only be as good as the metadata that is either provided/created by everyone. Metadata is very important for ensuring that users use the JULES-Rose suite/code as it was intended by the developer/designer.




Let us looks at an example of a metadata warning:

Note that selecting an invalid value for MPI_NUM_TASKS provides a warning triangle and a red cog next to the offending variable, see the image below.





You should have already pointed the suite to a copy of the JULES code metadata for Rose Edit to use. If not follow the instructions below:
For example point to the trunk version of the JULES code metadata: /project/jules/vn4.9/trunk/ to the front of both of the paths for fcm_make and jules metadata.

Help on where to find the 3 locations

1. Index section on the left side -> fcm_make -> Build configuration -> Path to JULES source: /project/jules/vn4.9/trunk/rose-meta/jules-fcm-make/HEAD/rose-meta.conf
2. Index section on the left side -> fcm_make -> meta: /project/jules/vn4.9/trunk/rose-meta/jules-fcm-make/HEAD/rose-meta.conf
3. Index section on the left side -> jules -> meta: /project/jules/vn4.9/trunk/rose-meta/jules-standalone/HEAD/rose-meta.confcd




Save and check the changes.

With the metadata enabled we can see all of the information on the variables.





An example of different formats for presenting options with metadata.




Select a variable and then right click, Info
OR
Right click on the icon of a cog for info.


From the image above you can see that the date has to have the correct format.

Changing it to be incorrectly formatted provides a hover-over error, as seen in the image below.

Practical 2 - Further JULES-Rose suites - duration, domain

Practical 2 will cover:

Changing the JULES-Rose suite to run for a different domain.

Changing the JULES-Rose suite to run for a different duration.

Changing the JULES-Rose suite to run for a different domain

In JULES there are two ways to change the domain:

1. Changing the namelist jules_latlon and use a single site.
2. Changing the namelist jules_model_grid and use a gridbox domain.

The first method requires all of the Model grid variables in the Grid configuration to be false. The Latitude and Longitude must be defined and the Input grid should be set to false and be 1 x 1.

For this practical please use one of the following suites: u-ai828 (or u-ai829 for VM or u-ai843 for JASMIN, or u-ai844 for remote JASMIN from your desktop, u-al388 MONSooN) and make sure that you have added the metadata as above.





The second method requires Index Input grid -> grid_is_1d to be set to true and the other four variables to be defined as specified below:

1. Latitude and longitude set to Latitude/Longitude and specifiy the ancil file location for the dataset.
2. Longitude set to Longitude and specifiy the ancil file location for the dataset.
3. Land fraction needs the ancil file location and the name of the land fraction data.
4. Model grid has the sub grid set to true and the boundaries to the lat and long of the domain.

To see an example with the second type of setup see the JULES-Rose suite u-ai509 with the metatdata specified as above.


Note:

The suite u-ai828 (or u-ai829 for VM or u-ai843 for JASMIN, or u-ai844 for remote JASMIN from your desktop, u-al388 MONSooN) requires Loobos data which is included within the suite.




Not recommended: The suite u-ai509 (u-ai510 for VM or u-ai511 for JASMIN) require GWSP2 data which is very big but part of the VM install-jules-* extra scripts so can be run on the VM if you have downloaded the data. This data is also available from a FTP site, please see the Data retrieval section of JULES-Rose Rose/Cylc setup

Note this suite takes a while to run, about 25 mins.

Recommended: For a much faster running suite use u-aj012 (u-aj013 for VM or u-aj014 for JASMIN + remote JAMSIN, for MONSooN u-al438). The suite are the "same" as u-ai509 but they run for only 1 month and instead of 1 year and therefore takes about 5 minutes to run.

Change both suites, u-ai828 and u-aj012 (or their respective equivalent for the platform you are using):

• The u-ai828 suite to run for different site, Latitude 53.32 and Longitude 0.0.
• The u-aj012 suite to run over the gridbox lat 53.5 55.5, long -1.0 1.0.
• Extension task if you have time: The u-aj012 suite again but to run globally (use u-ah270 for help), note running this will take a very long time so you may want to use u-ai511 for testing as it is a cut down of the full suite.



Changing the JULES-Rose suite to run for a different durations




For this section please use the JULES-Rose suite u-aj012 (Meto), for the VM use u-aj013, for JASMIN use u-aj014, for MONSooN use u-al438




The suite uses GSWP2 data for one month.

One off Method v Flexiable Method

The one off method is a quick and very simple solution but means that you have to remember where you made the change and what it was called in the appropriate app. Whereas using the flexible method means all variables that a user may want to change are all in the same file, the rose-suite.conf and passed to the correct location when the developer setup the suite for you.




Why use the rose-suite.conf file?
The ethos for defining variables in the rose-suite.conf file is that users should only have to change the rose-suite.conf and not the suite.rc file for passing variables around the suite that the user may wish to change.
It is hoped that once the developer has setup the suite.rc that the user should only have to change the variables in the rose-suite.conf file.




Different time period - one off method

This is a simple change to the jules app, changing the app/jules/rose-app.conf file:

[namelist:jules_time]
main_run_end='1982-07-07 03:00:00'
main_run_start='1982-07-01 03:00:00'




Different time period - flexible method

However, if this is something that you wish to change regularly then it would be best to add variables to the rose-suite.conf file and pass them to the jules app as described below:

In the rose-suite.conf file add the variables:

MAIN_RUN_END='1982-07-07 03:00:00'
MAIN_RUN_START='1982-07-01 03:00:00' 

Example of the updated: rose-suite.conf

[jinja2:suite.rc]
DESKTOP=false
JULES_PATH='/project/jules/vn4.9/trunk'
MPI_NUM_TASKS=12
OMP_NUM_THREADS=2
WALLTIME=PT3H
MAIN_RUN_END='1982-07-07 03:00:00'
MAIN_RUN_START='1982-07-01 03:00:00'




In the suite.rc file add the environment variables:

     [[jules]]
         [[[environment]]]
             ...
             main_run_end   = {{ MAIN_RUN_END }}
             main_run_start = {{ MAIN_RUN_START }}

Example of the updated: suite.rc [[jules]] section

    [[jules]]
        inherit = None, SPICE
        script = "mkdir -p output ; rose task-run --path= --path=share/fcm_make/build/bin"
        [[[job]]]
            execution time limit = {{ WALLTIME }}
        [[[remote]]]
            host = {{ ROSE_ORIG_HOST }}
        [[[environment]]]
            JULES_PATH      = {{ JULES_PATH }}
            MPI_NUM_TASKS   = {{ MPI_NUM_TASKS }}
            OMP_NUM_THREADS = {{ OMP_NUM_THREADS }}
            NPROC           = {{ MPI_NUM_TASKS }}
            main_run_end   = {{ MAIN_RUN_END }}
            main_run_start = {{ MAIN_RUN_START }}
        [[[directives]]]
            # MPI_NUM_TASKS * OMP_NUM_THREADS
            --ntasks={{ OMP_NUM_THREADS * MPI_NUM_TASKS}}




In the app/jules/rose-app.conf change the values of the two variables as shown below:

[namelist:jules_time]
main_run_end=${main_run_end}
main_run_start=${main_run_start}




As we are using a different time which is within the driving data date range we do not have to change the namelist:jules_drive.

If we are to change the dates to a different month or year then we must change the values for the variables (only change to GSWP2 if not using Loobos data):

[namelist:jules_drive]
data_end='1982-07-31 23:59:59'
data_start='1982-07-01 03:00:00'
file='$GSWP2_INSTALL_DIR/drive/%vv/%vv198207.nc'

This may include sourcing more or different data, for example only:

      
[namelist:jules_drive]
data_end='1986-03-31 23:59:59'
data_start='1986-03-01 03:00:00'
file='$GSWP2_INSTALL_DIR/drive/%vv/%vv198603.nc'

OR

      
[namelist:jules_drive]
data_end='1996-01-01 03:00:00'
data_start='1982-07-01 03:00:00'
file='drive_file.txt'

End of examples for changing driving data.




To add flexibility to the suite use the second option for the driving data as we have access to all of the files.




Yearly or Monthly

We are going to update our suite to run JULES for a year or a month at a time. This is because not all computers allow for tasks (jobs) to run for greater than a three hour wallclock limit. Therefore some model runs, for example global data, may need to be split up into yearly/monthly JULES tasks so the computers will allow the model to not timeout.




We are going to make changes very similar to the canradmod changes in the User course Practical 6 where we supplied a list of different canradmod settings to run JULES for different optional configurations.

This suite is slightly different in its design as the first time that JULES is run it will use driving data and from then onwards it will use the previous year's data as its driving data.




This is first example is yearly, but as it takes a while we not run it. The second example is monthly and we will implement monthly and run it.


Yearly Example only

Changes to the rose-suite.conf file:

YEARS=["1984","1985","1986","1987","1988"]
WALLTIME='P3D'

Changes to the suite.rc file:

graph = """
          fcm_make =>\
          {% for year in YEARS %}
              jules_{{year}} =>\
          {% endfor %}
          housekeep
        """

{% for year in YEARS %}
    [[jules_{{year}}]]
        inherit = SPICE # (MO) or LINUX (VM) you should not need to change this line
        {% if year == YEARS[0] %}
            script = "mkdir -p output ; rose task-run --app-key=jules --path= --path=share/fcm_make/build/bin"
        {% else %}
            script = "mkdir -p output ; rose task-run --app-key=jules -O dump --path= --path=share/fcm_make/build/bin"
          #Note - upper o not zero
        {% endif %}
        env-script = year_next=$(({{year}}+1))
        [[[environment]]]
        ...
...         year={{year}}
            year_next=${year_next}
{% endfor %}

    [[housekeep]]
        script = echo "Success!"

Example of the updated: suite.rc

#!jinja2
[cylc]
    UTC mode = True

[scheduling]
    [[dependencies]]
graph = """
          fcm_make =>\
          {% for year in YEARS %}
              jules_{{year}} =>\
          {% endfor %}
          housekeep
        """ 
[runtime]
    [[root]]
        script = rose task-run --verbose
        [[[events]]]
            mail events = submission failed, submission timeout, failed, timeout

    [[SPICE]]
         pre-script = ". /usr/local/bin/prg_default"
        [[[job]]]
            batch system = slurm

    [[fcm_make]]
        inherit = None, SPICE 
        [[[job]]]
           execution time limit = PT20M
        [[[remote]]]
            host = {{ ROSE_ORIG_HOST }}
        [[[environment]]]
            JULES_PATH       = {{ JULES_PATH }}
            ROSE_TASK_N_JOBS = 4
        [[[directives]]]
            --ntasks=6

{% for year in YEARS %}
    [[jules_{{year}}]]
        inherit = SPICE # (MO) or LINUX (VM) you should not need to change this
line
        {% if year == YEARS[0] %}
            script = "mkdir -p output ; rose task-run --app-key=jules --path= --path=share/fcm_make/build/bin"
        {% else %}
            script = "mkdir -p output ; rose task-run --app-key=jules -O dump --path= --path=share/fcm_make/build/bin"
          #Note - upper o not zero
        {% endif %}
        env-script = year_next=$(({{year}}+1))
        [[[environment]]]
            JULES_PATH      = {{ JULES_PATH }}
            MPI_NUM_TASKS   = {{ MPI_NUM_TASKS }}
            OMP_NUM_THREADS = {{ OMP_NUM_THREADS }}
            NPROC           = {{ MPI_NUM_TASKS }}
            year={{year}}
            year_next=${year_next}
{% endfor %}

    [[housekeep]]
        script = echo "Success!"




Changes to the app/jules/ files and directory: Add an opt/ directory.




Add a file rose-app-dump.conf to the opt/ directory:

[namelist:jules_initial]
dump_file=.true.
file='${CYLC_TASK_WORK_DIR}/output/gl6_notop_gswp2.dump.${year}0101.10800nc'

Changes to the app/jules/rose-app.conf file:

[namelist:jules_time]
main_run_end='${year_next}-01-01 01:00:00'
main_run_start='${year}-01-01 01:00:00'

[namelist:jules_drive]
data_end='1996-01-01 03:00:00'
data_start='1982-07-01 03:00:00'
file='drive_file.txt'
nfiles=162
read_list=.true.

These are all of the changes that would need to be made.


Monthly Example to do and run

Changes to the rose-suite.conf file:

MONTHS=["07","08","09","10","11"]
YEAR="1985"

Changes to the suite.rc file:

graph = """
          fcm_make =>\
          {% for month in MONTHS %}
              jules_{{"%0.2d" % month|int}} =>\
          {% endfor %}
          housekeep
        """

{% for month in MONTHS %}
    [[jules_{{"%0.2d" % month|int}}]]
        inherit = SPICE  # (MO) or LINUX (VM) you should not need to change this
line
        {% if month == MONTHS[0] %}
            script = "mkdir -p output ; rose task-run --app-key=jules --path= --path=share/fcm_make/build/bin"
        {% else %}
            script = "mkdir -p output ; rose task-run --app-key=jules -O dump --path= --path=share/fcm_make/build/bin"
                      #Note - upper o not zero
        {% endif %}
        env-script = """ month_next='{{ "%0.2d" % (month|int + 1)}}' """
        [[[environment]]]
        ...
...         month={{"%0.2d" % month|int}}
            month_next=${month_next}
            year={{ YEAR }}
{% endfor %}

    [[housekeep]]
        script = echo "Success!"

Example of the updated: suite.rc (MO Linux)

#!jinja2
[cylc]
    UTC mode = True

[scheduling]
    [[dependencies]]
graph = """
          fcm_make =>\
          {% for month in MONTHS %}
              jules_{{"%0.2d" % month|int}} =>\
          {% endfor %}
          housekeep
        """
[runtime]
    [[root]]
        script = rose task-run --verbose
        [[[events]]]
            mail events = submission failed, submission timeout, failed, timeout

    [[SPICE]]
         pre-script = ". /usr/local/bin/prg_default"
        [[[job]]]
            batch system = slurm

    [[fcm_make]]
        inherit = None, SPICE
        [[[job]]]
           execution time limit = PT20M
        [[[remote]]]
            host = {{ ROSE_ORIG_HOST }}
        [[[environment]]]
            JULES_PATH       = {{ JULES_PATH }}
            ROSE_TASK_N_JOBS = 4
        [[[directives]]]
            --ntasks=6

{% for month in MONTHS %}
    [[jules_{{"%0.2d" % month|int}}]]
        inherit = SPICE  # (MO) or LINUX (VM) you should not need to change this
line
        {% if month == MONTHS[0] %}
            script = "mkdir -p output ; rose task-run --app-key=jules --path= --path=share/fcm_make/build/bin"
        {% else %}
            script = "mkdir -p output ; rose task-run --app-key=jules -O dump --path= --path=share/fcm_make/build/bin"
                      #Note - upper o not zero
        {% endif %}
        env-script = """ month_next='{{ "%0.2d" % (month|int + 1)}}' """
        [[[environment]]]
            JULES_PATH      = {{ JULES_PATH }}
            MPI_NUM_TASKS   = {{ MPI_NUM_TASKS }}
            OMP_NUM_THREADS = {{ OMP_NUM_THREADS }}
            NPROC           = {{ MPI_NUM_TASKS }}
            month={{"%0.2d" % month|int}}
            month_next=${month_next}
            year={{ YEAR }}
{% endfor %}

    [[housekeep]]
        script = echo "Success!"




Example of the updated: suite.rc (VM)

#!jinja2
[cylc]
    UTC mode = True

[scheduling]
    [[dependencies]]
graph = """
          fcm_make =>\
          {% for month in MONTHS %}
              jules_{{"%0.2d" % month|int}} =>\
          {% endfor %}
          housekeep
        """
[runtime]
    [[root]]
        script = rose task-run --verbose
        [[[events]]]
            mail events = submission failed, submission timeout, failed, timeout

    [[LINUX]]
         pre-script = "ulimit -s unlimited"
        [[[job]]]
            batch system = background
        [[[environment]]]
            GSWP2_INSTALL_DIR = {{ GSWP2_INSTALL_DIR }}

    [[fcm_make]]
        inherit = None, LINUX
        [[[remote]]]
            host = {{ ROSE_ORIG_HOST }}
        [[[environment]]]
            JULES_PATH       = {{ JULES_PATH }}
            JULES_PATH_META  = {{ JULES_PATH }}/rose-meta/
            ROSE_TASK_N_JOBS = 2

{% for month in MONTHS %}
    [[jules_{{"%0.2d" % month|int}}]]
        inherit = LINUX #(VM) you should not need to change this
line
        {% if month == MONTHS[0] %}
            script = "mkdir -p output ; rose task-run --app-key=jules --path= --path=share/fcm_make/build/bin"
        {% else %}
            script = "mkdir -p output ; rose task-run --app-key=jules -O dump --path= --path=share/fcm_make/build/bin"
                      #Note - upper o not zero
        {% endif %}
        env-script = """ month_next='{{ "%0.2d" % (month|int + 1)}}' """
        [[[environment]]]
            JULES_PATH      = {{ JULES_PATH }}
            MPI_NUM_TASKS   = {{ MPI_NUM_TASKS }}
            OMP_NUM_THREADS = {{ OMP_NUM_THREADS }}
            NPROC           = {{ MPI_NUM_TASKS }}
            month={{"%0.2d" % month|int}}
            month_next=${month_next}
            year={{ YEAR }}
{% endfor %}

    [[housekeep]]
        script = echo "Success!"




Changes to the app/jules/ files and directory: Add an opt/ directory.




Add a file called rose-app-dump.conf to the opt/ directory and then add the following information to overwrite the variables in the standard rose-app.conf:

[namelist:jules_initial]
dump_file=.true.
file='${CYLC_TASK_WORK_DIR}/output/gl6_notop_gswp2.dump.${year}${month}01.10800nc'

Changes to the app/jules/rose-app.conf file:

[namelist:jules_time]
main_run_end='${year}-${month_next}-01 01:00:00'
main_run_start='${year}-${month}-01 01:00:00'

[namelist:jules_drive]
data_end='1996-01-01 03:00:00'
data_start='1982-07-01 03:00:00'
file='drive_file.txt'
nfiles=162
read_list=.true.

Now run the suite... ...look at the job.out for each task and check that the suite ran as you expected.




A branch was created for this suite it is called "duration_ly_prac2", it has been fully tested and it can be used for comparison.

Practical 3 - Further JULES rose-stem - namelists, modules

Practical 3 will cover:

Add a namelist to rose-stem.

Add a new module to rose-stem.

• Hints are provided below the example by linking to the Trac diffs.




Add a namelist to rose-stem

A new namelist will always change the following files:

1. rose-meta/jules-standalone/HEAD/rose-meta.conf
2. rose-meta/jules-standalone/versions.py

It will change a control file for the appropriate module in:

3. src/control/shared/???_mod.F90

It will also require changes to the relevant science schemes i.e. in:

4. src/science/<scheme>/<routine>.F90


A simple example


We want to add a the namelist jules_hydrology=l_drench_soil for using our new science l_drench_soil to drench the soil at each timestep.

1. Create a branch (dev)
2. Add the science
3. Update the metadata
4. Add the upgrade macro
5. Test the science, (on a dev branch)
6. Create a branch (test) from the dev branch - a bob
7. Test the science after running the upgrade macro (on a test branch)
8. Test Rose Edit (on a test branch)
9. Run rose-stem on the test branch
10. Test the new science switched on

Normally you would create a ticket first, but here we will use #296 as this has been set up for tutorials.




1. Create a branch (dev) - use the -k option to specify the ticket number when creating the branch.

   How To

   fcm bc -k 296 namelist_example fcm:jules.x_tr@vn4.9
   

   Add a suitable commit message and type y and press the enter/return key to create the branch.
   Checkout the branch to your jules/vn4p9/ directory.

   How To

   fcm co fcm:jules.x_br/dev/MOSRS_USERNAME/vn4.9_namelist_example
   



2. Add the science - edit src/science/soil/surf_hyd_jls_mod.F90 by increasing the large-scale rainfall in the surface hydrology scheme. At line ~150 add the LOGICAL and REAL's for the three variables that we are adding:

   LOGICAL, PARAMETER :: l_drench_soil = .TRUE.
   REAL :: ls_rain_local(land_pts)
   REAL :: drench_increment = 0.0001
   

   At ~ line 168 after the Fortran intrinsics are defined add:

   !If we are using the drenching feature, add the water to ls_rain
   IF ( l_drench_soil ) THEN
     ls_rain_local(:) = ls_rain_land(:) + drench_increment
   END IF
   
   !NOTES:
   ! If this was a more complicated piece of code, we would consider doing this
   ! differently to allow the compiler to take advantage of OpenMP and other
   ! optimisations.
   

   and change ls_rain_land to ls_rain_local in three places, at ~ line 200, ~ line 271 and ~ line 276.
   edit src/control/shared/jules_hydrology_mod.F90 At ~ line 22 add the following:

   !-----------------------------------------------------------------------------
   ! Drench functionality for the practice development
   !-----------------------------------------------------------------------------
     LOGICAL         :: l_drench_soil = .FALSE.
           !Switch for turning on the drench code
     
     REAL, PARAMETER :: drench_increment = 0.001
           !Amount the drench the soil by in kg/m2/s
           !3.6 mm/h is 0.001 kg/m2/s
   

   Ideally we would add these the appropriate section (at the bottom of the LOGICAL section ~ line 48 and at the bottom of the REAL section ~line 62). Remember:
   • Default switch value should be false.
   • USE statements should be added where you need to use the variable.
   • A parameter must be used and not a "magic number" (an unique values with unexplained meaning).
   Add to the Namelist ~ line 76-82 l_drench_soil to the end of the namelist.

   !------------------------------------------------------------------------------
   ! Single namelist definition for UM and standalone
   !------------------------------------------------------------------------------
     NAMELIST /jules_hydrology/                                                  &
       l_hydrology, l_top, l_pdm, l_spdmvar, l_baseflow_corr, l_var_rainfrac,    &
       l_wetland_unfrozen,                                                       &
       dz_pdm, b_pdm, s_pdm, slope_pdm_max, ti_max, ti_wetl, zw_max, nfita,      &
       l_drench_soil
   

   Add l_drench_soil to jules_hydrology ~ line 172

       WRITE(lineBuffer, *) '  l_drench_soil = ', l_drench_soil
       CALL jules_print('jules_hydrology', lineBuffer)
   

   Add increase the number of n_log by one ~ line 216

       INTEGER, PARAMETER :: n_log = 8
   

   Add the LOGICAL to the TYPE my_namelist list ~ line 235

         LOGICAL :: l_drench_soil
   

   Update the setup of the namelist ~ line 255

         my_nml % l_drench_soil   = l_drench_soil
   

   Update the namelists broadacst ~ line 280

         l_drench_soil   = my_nml % l_drench_soil
   

   
   Edit src/initialisation/standalone/init_hydrology.F90 Add the l_drench_soil to the USE statement

     USE jules_hydrology_mod, ONLY : jules_hydrology, check_jules_hydrology,     &
                                     l_top, l_pdm, l_drench_soil
   

   Adding a log message at ~ line 85 after the other CALLs.

     IF ( l_drench_soil ) THEN
       CALL log_info("init_hydrology", "Soil drenching is switched on")
     END IF
   

   This should be all the science, we will test the science shortly.
   Diff of vn4.9 trunk to a vn4.9 branch with the changes made.


3. Update the metadata - edit rose-meta/jules-standalone/HEAD/rose-meta.conf as shown:

   [namelist:jules_hydrology=l_drench_soil]
   compulsory = false
   description = Drench the soil at each timestep
   url = http://jules-lsm.github.io/vn<VERSION>/namelists/jules_hydrology.nml.html#JULES_HYDROLOGY::l_drench_soil
   type = logical
   sort-key = h
   




4. Add the upgrade macro - edit rose-meta/jules-standalone/versions.py file just before the comment line about the template (Note this is based on the idea that you are creating a branch at vn4.9 for ticket #296):

   class vn49_t296(rose.upgrade.MacroUpgrade):
   
       """Upgrade macro from JULES by USERNAME/NAME"""
   
       BEFORE_TAG = "vn4.9"
       AFTER_TAG = "vn4.9_t296"
   
       def upgrade(self, config, meta_config=None):
           """Upgrade a JULES runtime app configuration."""
   
           '''
              This adds the l_drench_soil switch to increase the large-scale
              rainfall in the surface hydrology.
           '''
           # Add a new namelist item with its default value
           self.add_setting(config, ["namelist:jules_hydrology", "l_drench_soil"], ".false.")
   
           # Add settings
           return config, self.reports
   



5. Test the science, (on a dev branch)

   We have already created a branch and are working on it. By default fcm bc creates the branch on dev.

   Check the status of the code and commit the changes.

   Run the rose-stem tests

   Answers

   fcm st
   fcm ci
   #for running the tutorial rose-stem tests for a evidence for the Ticket Summary
   #as part of the Ticket for review.
   #(_linux/_xc40 for Met Office intenal only)
   rose stem --group=tutorial(_linux/_xc40) --new
   

   
   

   All rose-stem tests should pass.

   A trac.log file will be produced for copying to the Ticket Summary of the Ticket. It is located in the ~/cylc-run/<BRANCH_NAME>/ directory.



6. Create a branch (test) from the branch (dev), a branch-of-branch bob.

   cd ~/jules/vn4p9/
   fcm branch-create -k 296 --branch-of-branch -t test namelist_example_test_branch fcm:jules.x_br/dev/MOSRSUSERNAME/vn4.9_namelist_example
   fcm co fcm:jules.x_br/test/MOSRSUSERNAME/r####_namelist_example_test_branch
   cd r####_namelist_example_test_branch
   



7. Test the science after running the upgrade macro (on a test branch)

   ./bin/upgrade_jules_test_apps vn4.9_t296
   



8. Test Rose Edit (on a test branch)

   rose edit
   

   Navigate the Rose Edit GUI to check the section that you have changed, including the namelist being present with the true/false option.



9. Run rose-stem on the test branch

   Check the status of the code and commit the changes.

   Run the rose-stem tests, normally we would run using the --group=all option but for the tutorial please use the --group=tutorial or --group=tutorial_linux if you are at the MO site.

   Answers

   fcm st
   fcm ci
   #for running the tutorial rose-stem tests for a evidence for the Ticket Summary
   #as part of the Ticket for review.
   #(_linux/_xc40 for Met Office intenal only)
   rose stem --group=tutorial(_linux/_xc40) --new
   

   
   

   The rose-stem tests should pass.

   A trac.log file will be produced for copying to the Ticket Summary of the Ticket. It is located in the ~/cylc-run/<BRANCH_NAME>/ directory.



10. Test the new science switched on - We need to demonstrate how the new science works for the review process.

    Make a copy of u-ai828 (meto) or u-ai829 VM or u-ai843 JASMIN or u-al388.

    Apply the upgrade macro using

    #Firstly change the path to JULES metadata to be your branch
    #in all three locations as done above (fcm_make, fcm_make-Build Configuration,
    # jules)
    # Apply upgrade macros
    rose app-upgrade -M ~/jules/vn4p9/vn4.9_namelist_example -C app/fcm_make vn4.9_269  && rose macro --fix -M ~/jules/vn4p9/vn4.9_namelist_example -C app/fcm_make 
    # fcm-make not always required, skip if it does not work with: "[FAIL] Error: could not find meta flag"
    rose app-upgrade -M ~/jules/vn4p9/vn4.9_namelist_example -C app/jules vn4.9_269 && rose macro --fix -M ~/jules/vn4p9/vn4.9_namelist_example -C app/jules
    

    Run the suite:

    rose suite-run --new
    

    Compare the output.




A complicated example just for reference and ideas

Lets add a namelist.

This is an example of how to add a namelist which is taken from a namelist being added for JULES vn4.7 code release:

1. Create a branch the JULES code from the trunk at vn4.6, include tutorial in its name
2. Checkout the branch
3. Add the following namelist to the rose-meta.conf

   [namelist:jules_surface=bio_hum_CN]
   complusory=true
   ns=namelist/Science settings/Surface options/Parameters
   description=Bio and Hum Soil Carbon pools CN ratio
   url=http://jules-lsm.github.io/vn4.6/namelists/jules_surface.nml.html#JULES_SURFACE::bio_hum_cn
   type=real
   range=0.01:
   sort-key=m
   

4. Edit the versions.py file to include your metadata and the original template, use vn4.6_t309 and

   self.add_setting(config, ["namelist:jules_surface", "bio_hum_cn"], "10.0")
   

5. To src/control/shared/jules_surface_mod.F90 add (~line (ln) 275):

   ! Parameters for soil respiration.
   bio_hum_CN = 10.0
   ! Soil Bio and Hum CN ratio parameter
   

   add (~ln 290):

   ! Parameters
   bio_hum_CN
   

   add (~ln 465)

   WRITE(lineBuffer, *) '  bio_hum_CN = ', bio_hum_CN
   CALL jules_print('jules_surface', lineBuffer)
   

   (~ln 505) increase the number to 12

   INTEGER, PARAMETER :: n_real = 11 + 4
   

   add (~ln 530, 575, 610)

   REAL :: bio_hum_CN
   my_nml % bio_hum_cn         = bio_hum_cn
   bio_hum_CN         = my_nml % bio_hum_CN       
   

6. rc/initialisation/standalone/initial_conditions/init_ic.inc add bio_hum_cn to the correct USE, add ns_pool_gb, cs_pool_gb to the correct USE add (~ln 470)

   !-------------------------------------------------------------------------------
   ! Initialise soil bio and hum pools from soil carbon
   !-------------------------------------------------------------------------------
     IF (l_triffid ) THEN
       ns_pool_gb(:,3) = cs_pool_gb(:,3) / bio_hum_cn
       ns_pool_gb(:,4) = cs_pool_gb(:,4) / bio_hum_cn
     ENDIF 
   

7. src/science/vegetation/soilcarb_jls.F90 add bio_hum_cn to the USE including the module remove soil_cn = 10.0 update (~ln 120), soil_cn wih bio_hum_cn

     cn(l,3) = bio_hum_cn           ! C:N ratio of BIO - Fixed
     cn(l,4) = bio_hum_cn           ! C:N ratio of HUM - Fixed
   

   add (~ln 125)

   ! N pool BIO+HUM are diagnostic from equivalent cSoil pool
     ns_pool_gb(l,3) = cs(l,3) / bio_hum_cn
     ns_pool_gb(l,4) = cs(l,4) / bio_hum_cn
   

   update (~ln 220), soil_cn wih bio_hum_cn

     IF (ns_pool_gb(l,3) <  cs_min / bio_hum_cn) THEN
       neg_n(l) = neg_n(l) + ns_pool_gb(l,3) - cs_min / bio_hum_cn
     END IF
     IF (ns_pool_gb(l,4) <  cs_min / bio_hum_cn) THEN
       neg_n(l) = neg_n(l) + ns_pool_gb(l,4) - cs_min / bio_hum_cn
   

   update (~ln 230), soil_cn wih bio_hum_cn

     ns_pool_gb(l,3) = MAX(ns_pool_gb(l,3),cs_min / bio_hum_cn)
     ns_pool_gb(l,4) = MAX(ns_pool_gb(l,4),cs_min / bio_hum_cn)
   

Diff from #309





If you have added an Upgrade Macro you MUST also test it in Rose Edit and apply the changes to the JULES code:

#rose edit test, check the metadata is as intended
rose edit -M /path/to/the/metadata/for/testing/rose-meta
#run the upgrade macro
rose app-upgrade -M /path/to/the/metadata/for/testing/rose-meta app/fcm_make <vn#.#_t###> && rose macro --fix -M /path/to/the/metadata/for/testing/rose-meta -C app/fcm_make
rose app-upgrade -M /path/to/the/metadata/for/testing/rose-meta app/jules <vn#.#_t###> && rose macro --fix -M /path/to/the/metadata/for/testing/rose-meta -C app/jules
#or
./bin/upgrade_jules_test_apps vn#.#_t###

#here the <version> would be HEAD.






Run the JULES rose-stem tests to make sure that all of the tests pass.




Other examples:

• Diff from #414
• Diff from #298




Add a new module to the JULES code

Why use modules and not subroutines with DEPENDS ON?

• Modules are simple and make finding the piece of Fortran code that you are looking for easier to find. They also modulise the code therefore making files more user friendly and readable. Further, adding, replacing and removing obsolete modules is easy.

Other reasons to use modules:

1. The compiler will check the number and types of arguments.
2. the compiler can use memory in smarter ways.
3. Code is more portable.
4. It takes seconds and can save hours of difficult debugging.




We will start by explaining the simplest form of how to use modules and then we try adding our own and testing it.




• Simplest form:

Modules must start and end like this:

MODULE my_mod
  CHARACTER(LEN=*), PARAMETER, PRIVATE :: ModuleName='MY_MOD'
  CONTAINS
  SUBROUTINE mycode(arg1, arg2)

  USE ...
  ...
  IMPLICIT NONE
  ....INTENT(IN)
  ....INTENT(INOUT)
  ....INTENT(OUT)
  ...
  INTEGER(KIND=jpim), PARAMETER :: zhook_in  = 0
  INTEGER(KIND=jpim), PARAMETER :: zhook_out = 1
  REAL(KIND=jprb)               :: zhook_handle
	
  CHARACTER(LEN=*), PARAMETER :: RoutineName='mycode'

  IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_in,zhook_handle)
  ...
  ...
  IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_out,zhook_handle)
  RETURN
  END SUBROUTINE mycode
END MODULE my_mod

They are used and called by:

  ...
  USE my_mod, ONLY: mycode
  ...
  IMPLICIT NONE
  ...
  CALL mycode(arg1, arg2)
  ...




• Adding our own module:

Let us apply this to a new module that we would like to add to the code.

We are going to take the JULES vn4.9 release and move some code into a module.

• Check out the JULES vn4.9 code release as vn4p9_tr
• Change to the created directory
• touch src/science/soil/n_leach_mod.F90
• Open the file src/science/soil/hydrol_jls.F90
• Line 63 add the USE statement for the new module "n_leach_mod" for the subroutine n_leach
• Lines 715-722 remove
• Add a CALL for the subroutine and all the arguments it needs, as shown above in the "Simplest form" example
• Lines 723-808 copy to the module called "n_leach_mod.F90"
• Add to the top and bottom of the n_leach_mod.F90 file as shown above in the "Simplest form" example




How To

src/science/soil/hydrol_jls.F90

USE n_leach_mod,              ONLY: n_leach

  CALL n_leach(npnts, nshyd, timestep, smcl, w_flux,                          &
               sub_surf_roff, qbase_l, k_1m)

src/science/soil/n_leach_mod.F90

MODULE n_leach_mod
  CHARACTER(LEN=*), PARAMETER, PRIVATE :: ModuleName='N_LEACH_MOD'
  CONTAINS
  SUBROUTINE n_leach(npnts, nshyd, timestep, smcl, w_flux,                    &
                     sub_surf_roff, qbase_l, k_1m)

USE parkind1, ONLY                : jprb, jpim
USE yomhook, ONLY                 : lhook, dr_hook
USE jules_surface_mod, ONLY       : l_layeredC
USE jules_hydrology_mod, ONLY     : l_top
USE jules_soil_mod, ONLY          : sm_levels, dzsoil
USE jules_surface_types_mod, ONLY : npft
USE prognostics, ONLY             : n_inorg_gb_lyrs, n_inorg_avail_pft
USE trif_vars_mod, ONLY           : n_leach_gb
USE jules_surface_mod, ONLY       : sorp

IMPLICIT NONE

INTEGER, INTENT(IN) ::                                                        &
 npnts                                                                        &
                     ! IN Number of gridpoints.
,nshyd                                                                        &
                     ! IN Number of soil moisture levels.
,k_1m
                     !Layer index for top 1m



REAL, INTENT(IN) ::                                                           &
 timestep                                                                     &
                      ! Model timestep (s).
,w_flux(npnts,0:sm_levels)                                                    &
                      ! Fluxes of water between layers  (kg/m2/s)
,qbase_l(npnts,sm_levels+1)                                                   &
                      ! Base flow from each level (kg/m2/s).
,sub_surf_roff(npnts)                                                         &
                      ! Sub-surface runoff (kg/m2/s).
,smcl(npnts,sm_levels)
                      ! Soil moisture content of each layer (kg/m2).

INTEGER ::                                                                    &
  i,                                                                          &
    !Counter for land points
  n
          !Counter for soil level

REAL ::                                                                       &
 n_inorg_gb_old(npnts,sm_levels)                                              &
          !Start value of inorganic nitrogen
,n_inorg_avail_old(npnts,npft,sm_levels)                                      &
          !Start value of available inorganic nitrogen
,n_inorg_gb_tmp(npnts,nshyd)                                                  &
,n_inorg_avail_tmp(npnts,npft,nshyd)
                      ! WORK temporary variables for inorganic Nitrogen



INTEGER(KIND=jpim), PARAMETER :: zhook_in  = 0
INTEGER(KIND=jpim), PARAMETER :: zhook_out = 1
REAL(KIND=jprb)               :: zhook_handle

CHARACTER(LEN=*), PARAMETER :: RoutineName='N_LEACH'


IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_in,zhook_handle)

!----------------------------------------------------------------------

  n_leach_gb(:) = 0.0
  DO i=1,npnts
    n_leach_gb(i) = 0.0
    IF (.NOT. l_layeredC) THEN
      IF (SUM(smcl(i,1:k_1m)) > EPSILON(0.0)) THEN
        n_leach_gb(i) = sub_surf_roff(i) * (n_inorg_gb_lyrs(i,1) / sorp)      &
                        / SUM(smcl(i,1:k_1m))  ! (top 1m)
      END IF
      n_leach_gb(i) = MIN(n_leach_gb(i),(n_inorg_gb_lyrs(i,1) / sorp)         &
                      / timestep)
      !H20 flux                ! N concentration Kg [N]/kg [H20]
      n_inorg_gb_lyrs(i,1) = n_inorg_gb_lyrs(i,1) - n_leach_gb(i) * timestep
    ELSE !IF LAYERED C
      !Record old n_inorg, so we can calculate leaching.
      DO n=1,nshyd
        n_inorg_gb_tmp(i,n) = n_inorg_gb_lyrs(i,n)
        n_inorg_avail_tmp(i,:,n) = n_inorg_avail_pft(i,:,n)
      END DO

      ! Explicitly move n_inorg through the layers with w_flux.
      DO n=2,nshyd
        IF (w_flux(i,n-1) >= 0.0 .AND. smcl(i,n-1) > EPSILON(0.0)) THEN
          n_inorg_gb_lyrs(i,n) = n_inorg_gb_lyrs(i,n) + (timestep *           &
                                 w_flux(i,n-1) * n_inorg_gb_tmp(i,n-1))       &
                                 / (sorp * smcl(i,n-1))
          n_inorg_gb_lyrs(i,n-1) = n_inorg_gb_lyrs(i,n-1) - (timestep *       &
                                   w_flux(i,n-1) * n_inorg_gb_tmp(i,n-1)) /   &
                                   (sorp * smcl(i,n-1))
          n_inorg_avail_pft(i,:,n) = n_inorg_avail_pft(i,:,n) + (timestep *   &
                                     w_flux(i,n-1) *                          &
                                     n_inorg_avail_tmp(i,:,n-1)) /            &
                                    (sorp * smcl(i,n-1))
          n_inorg_avail_pft(i,:,n-1) = n_inorg_avail_pft(i,:,n-1) - (timestep &
                                       * w_flux(i,n-1) *                      &
                                       n_inorg_avail_tmp(i,:,n-1)) /          &
                                       (sorp * smcl(i,n-1))
        ELSE IF (w_flux(i,n-1) < 0.0 .AND. smcl(i,n) > EPSILON(0.0)) THEN
          n_inorg_gb_lyrs(i,n) = n_inorg_gb_lyrs(i,n) + (timestep *           &
                                 w_flux(i,n-1) * n_inorg_gb_tmp(i,n)) /       &
                                 (sorp * smcl(i,n))
          n_inorg_gb_lyrs(i,n-1) = n_inorg_gb_lyrs(i,n-1) - (timestep *       &
                                   w_flux(i,n-1) * n_inorg_gb_tmp(i,n)) /     &
                                   (sorp * smcl(i,n))
          n_inorg_avail_pft(i,:,n) = n_inorg_avail_pft(i,:,n) + (timestep *   &
                                     w_flux(i,n-1) * n_inorg_avail_tmp(i,:,n))&
                                     / (sorp * smcl(i,n))
          n_inorg_avail_pft(i,:,n-1) = n_inorg_avail_pft(i,:,n-1) - (timestep &
                                       * w_flux(i,n-1) *                      &
                                       n_inorg_avail_tmp(i,:,n)) /            &
                                       (sorp * smcl(i,n))
        END IF
      END DO
      IF (w_flux(i,nshyd) > 0.0 .AND. smcl(i,nshyd) > EPSILON(0.0)) THEN
        n_inorg_gb_lyrs(i,nshyd) = n_inorg_gb_lyrs(i,nshyd) - (timestep *     &
                                   w_flux(i,nshyd) *n_inorg_gb_tmp(i,nshyd))  &
                                   / (sorp * smcl(i,nshyd))
        n_inorg_avail_pft(i,:,nshyd) = n_inorg_avail_pft(i,:,nshyd) -         &
                                       (timestep * w_flux(i,nshyd) *          &
                                       n_inorg_avail_tmp(i,:,nshyd)) /        &
                                       (sorp * smcl(i,nshyd))
      END IF
      IF (w_flux(i,0) < 0.0 .AND. smcl(i,1) > EPSILON(0.0)) THEN
        n_inorg_gb_lyrs(i,1) = n_inorg_gb_lyrs(i,1) +  (timestep *            &
                               w_flux(i,0) * n_inorg_gb_tmp(i,1)) /           &
                               (sorp * smcl(i,1))
        n_inorg_avail_pft(i,:,1) = n_inorg_avail_pft(i,:,1) + (timestep *     &
                                   w_flux(i,0) * n_inorg_avail_tmp(i,:,1)) /  &
                                  (sorp * smcl(i,1))
      END IF
      IF (l_top) THEN ! LSH on: include leaching from lateral runoff.
        DO n=1,nshyd
          n_inorg_gb_lyrs(i,n) = n_inorg_gb_lyrs(i,n) - (timestep *           &
                                 qbase_l(i,n) * n_inorg_gb_tmp(i,n)) /        &
                                 (sorp * smcl(i,n))
          n_inorg_avail_pft(i,:,n) = n_inorg_avail_pft(i,:,n) - (timestep *   &
                                     qbase_l(i,n) * n_inorg_avail_tmp(i,:,n)) /&
                                     (sorp * smcl(i,n))
        END DO
      END IF ! LSH on.
      ! Calculate total leaching as difference in total inorganic
      ! nitrogen
      n_leach_gb(i) = (SUM(n_inorg_gb_tmp(i,:)) -                             &
                       SUM(n_inorg_gb_lyrs(i,:))) / timestep
      n_leach_gb(i) = MAX(n_leach_gb(i),0.0)
    END IF !l_layeredC

  END DO

IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_out,zhook_handle)
RETURN
END SUBROUTINE n_leach
END MODULE n_leach_mod
                            




This example is based on JULES ticket#394 which is on the trunk and part of the JULES vn4.9 code release, but it is different to the code on the trunk as soil tiling was implemented before this ticket.





Run the JULES rose-stem tests to make sure that all of the tests pass.




What if tests failed?

If we wanted this code on the JULES trunk then we would have to make sure that none of the tests fail. Where could you look if tests failed for information on why they had failed? We are not going to submit this code change for review as the code was correctly implemented for vn4.9 with the soil tiling. This is just an example of how we could add a module.

Practical 4 - More on Tickets - Populating

Practical 4 will cover:

Why create a ticket?

Creating a ticket.

Filling in the empty ticket.

Creating the Ticket Summary.

Filling in the Ticket Summary.

Adding the trac.log output.

The review process.





Why create a ticket?

There is something that needs improving in the JULES code.

You have created a branch that you wish to go on the JULES code trunk for everyone to benefit from. Firstly make sure that you have followed all of the working practices.


Creating a ticket

Anyone can create a ticket to highlight an area of the JULES code that need development.

Ideally you will also want and be able to resolve the ticket, or know someone that can.




First login to the JULES MOSRS trac wiki.

Either select the New Ticket tab at the top right of the page or use the link: Create a ticket





Filling in the empty ticket

Complete the Summary section. Chose the appropriate Type and only change the Milestone to the upcoming JULES code release if you think that you will complete it in time. Owner must be provided and is usually the person that has opened the ticket. If someone is to be assigned please get their permission first. The Priority should be provided. You must Cc the appropriate module leader(s). Only Keywords are allowed to be left empty.

The Description should be a clear and concise explanation of the problem and the proposed solution. There also needs to be a link to the branch and the Ticket Summary page. These can be created in preparation for the change even if they are not 100% ready, for example:

[log:main/dev/<MOSRS_USERNAME>/<BRANCH_NAME> <BRANCH_NAME>]
[wiki:ticket/###/TicketSummary Ticket Summary]

The ### will be replaced by the ticket number once the ticket is created.

Create the ticket using the Create ticket button.


Creating the Ticket Summary

Clicking on the Ticket Summary? link this will allow you to create the Ticket Summary page.

This opens a new page which displays:

The page ticket/###/TicketSummary does not exist. You can create it here.

You could also create the same page higher in the hierarchy:

    TicketSummary?
"Create this page"  Using the template: "(blank page)"

Choose the option Ticketsummary not the (blank page), then click the button "Create this page". This will create the Ticket Summary page for you to fill in.




Filling in the Ticket Summary page

You must be logged in to edit the Ticket Summary page.

Go to the bottom of the page and select the button Edit this page. Fill in all of the sections that you can at the time.




Adding the trac.log's

After you have made your code change and are happy with it you must run the JULES rose-stem tests for your branch.

More detail on rose-stem have been discussed earlier in these tutorials.

Once rose-stem has completed then the trac.log can be copied from the ~/cylc-run/ directory to the Ticket Summary.

The location of the trac.log: ~/cylc-run/<BRANCH_NAME>/trac.log.

Note that UM-JULES rose-stem tests must be run with the groups --group=jules,developer if your site does not have this capability please email Jules-Support@metoffice.gov.uk to request assistance.




The review process

You must have module leader approval for your change before it is reviewed, they should have been Cc'ed into the ticket when you created the ticket.

You will need to find a sci/tech reviewer (appropriate module leaders can give guidance) and the JULES System Manger (and or the UM Systems Team as appropriate) will code review your change.

Please email people that you think may be willing to sci/tech review your change to ask for a review before you assign it to them.

Note: no one that has contributed to the branch can review the branch.

Once the sci/tech review is done they should sign it off and assign it to the JULES System Manager for the code review. They are responsible for checking the overall integrity of the change. They will check to see if the change will cause issues on the trunk, decided if the testing was sufficient, and if the appropriate permissions and standards have been achieved.

They can ask you create a HoT branch if required and to make the appropriate changes to the code to make it suitable for the trunk.

Practical 5 - HEAD of TRUNK (HoT) branches and merging branch into it

Practical 5 will cover:

Why do we need to create HoT branches.

Creating a HoT branch.

Merging in our original branch to the HoT branch.





Why do we need to create HoT branches

Branches should be created from the current JULES code release version. A HoT branch is either requested or required if the present branch may either cause conflicts with the HEAD of the trunk or they need to include the new code from the HEAD to check that it does not break the latest HEAD of the trunk.




Creating a HoT branch

Below are the instructions for creating a HoT Branch, please follow them and create your own HoT.

# Create a branch from the JULES code repository at the head of the current trunk.
fcm bc <HOT_BRANCH_NAME> fcm:jules.x_tr@HEAD
# Add a comment to the commit message, include the ticket number if you have one. 
# Check out the HoT branch.
fcm co fcm:jules.x_br/dev/<MOSRS_USERNAME>/<HOT_BRANCH_NAME> 




Merging in our original branch to the HoT branch

Now we have a HoT we can merge our original branch into and then check the difference using FCM. When we are happy with the code merge we can run all of our JULES rose-stem tests for the Ticket Summary for the trac.log to be include in.

Please follow the following instructions to include your original branch in the HoT branch tat you have just created.

# Move to the HoT branch directory.
cd <HOT_BRANCH_NAME>/
# Merge your branch to the HoT branch.
fcm merge fcm:jules.x_br/dev/<MOSRS_USERNAME>/<BRANCH_NAME>
# Check the merge
fcm diff -g
# Once happy commit the changes to the HoT branch.
fcm ci
# Add a suitable comment.

Practical 6 - UM-JULES only for users with UM code access

Practical 6 will cover:

Why and When do we need to do a UM-JULES rose-stem test?

How do we run UM-JULES rose-stem?

What if there are failures?





Why and When do we need to do a UM-JULES rose-stem test?

There are many reasons to why we may need to run a UM-JULES rose stem test. For example:

• To check that there is no coding impact on the UM from the JULES code change when use in in the coupled UM-JULES model.
• To prove that the JULES code change does not change KGO when run as the coupled UM-JULES model.
• When the JULES change also requires a UM change.




How do we run UM-JULES rose-stem?

Only for testing a JULES change.

Note you or the site you are working on must have access to the UM code repository. If not you cannot do this testing and must ask the JULES System Manager for assistance.

1. Create a JULES ticket if it is not already created.
2. Commit your JULES branch changes to the repository.
3. Tested your JULES code changes and check the rose-stem tests all pass.
4. Where do you find the evidence for the JULES rose-stem tests for your branch?
5. Where does the evidence need to be copied to?
6. Checkout the UM trunk at the revision that your JULES change is for.
7. Run the rose-stem test.
8. Where do you find the evidence for the UM rose-stem tests for the JULES branch?
9. Where does the evidence need to be copied to?




How To and Answers

See Tickets User and Tickets Developer.
fcm st
# check that all files are expected to have changes have and that any new
#are added and any removed are deleted.
fcm ci
# add a commit comment, save and close.
y
#to commit.
In the directory of the branch.
rose stem --group=all --new
~cylc-run/<JULES_BRANCH_NAME>/trac.log
JULES Ticket, Ticket Summary

cd
mkdir -p um/
cd um
fcm co fcm:um.x_tr@vn10.8
# or if no fcm keywords set up
fcm co https://metoffice.code.gov.uk/svn/um/main/trunk@vn10.8
# for example if the change was a JULES vn4.9 branch
cd trunk
rose stem --group=jules,developer --new --name=umtr_jls<JULES_ticket_no> --sourece=. --source=/full/path/to/jules/branch/to/be/tested
~cylc-run/umtr_jls<JULES_ticket_no>/trac.log
JULES Ticket, Ticket Summary

                            




For testing a JULES and UM combined change.

1. Create a JULES ticket if it is not already created.
2. Commit your JULES branch changes to the repository.
3. Tested your JULES code changes and check the rose-stem tests all pass.
4. Provide the evidence for you JULES branch rose-stem tests in the JULES the Ticket Summary.
5. Create a UM ticket and reference it in the JULES ticket, reference the JULES ticket in the UM ticket.
6. Follow the UM working practices
7. Create a UM branch.
8. Make changes.
9. Run the rose-stem tests on the UM-JULES coupled branches.
10. Where do you find the evidence for the UM-JULES rose-stem tests for the UM-JULES coupled branch?
11. Where does the evidence need to be copied to?
12. Make sure you document both JULES and UM changes on their respective branches and metadata help.




How To and Answers

See Tickets User and Tickets Developer.
fcm st
# check that all files are expected to have changes have and that any new
#are added and any removed are deleted.
fcm ci
# add a commit comment, save and close.
y
#to commit.
In the directory of the branch.
rose stem --group=all --new
Copy the ~cylc-run/<JULES_BRANCH_NAME>/trac.log to the JULES Ticket, Ticket Summary
See answer 1 but it is to be applied to the UM trac wiki pages using the UM working practices.
As it says

cd
mkdir -p um/
cd um
fcm bc <UM_BRANCH_NAME> fcm:um.x_tr@10.8
# or if no fcm keywords set up
fcm bc <UM_BRANCH_NAME> https://metoffice.code.gov.uk/svn/um/main/trunk@vn10.8
# for example if the change was a JULES vn4.9 branch
cd <UM_BRANCH_NAME>
Make your changes and commit them to the repository as you would for JULES.
rose stem --group=jules,developer --new --source=. --source=/full/path/to/jules/branch/to/be/tested
~cylc-run/<UM_BRANCH_NAME>/trac.log
UM Ticket, Ticket Summary and the JULES Ticket, Ticket Summary

                            




Note if it is a combined UM-JULES ticket then you need to get the tickets approved by the UM Systems team and the JULES System Manager. Please email the UM System to ask to be assigned reviewers.




What if there are failures?

This as with a standard/standalone JULES change then the KGO can only have failures for explained reasons and scientifically or technically approved reasons. When is it acceptable to have a failure in the KGO?

Practical 7 - Metadata

Practical 7 will cover:

What is the metadata for?

How do I create metadata?

How do I test metadata?





What is the metadata for?

Metadata is included as part of the JULES code to help users understand the intended use of variables, switches, parameters, etc in JULES.

Metadata locations:

JULES code
• benchmark/meta/rose-meta.conf
• rose-meta/jules-fcm-make/*/rose-meta.conf
• rose-meta/jules-standalone/*/rose-meta.conf
• rose-stem/meta/rose-meta.conf

JULES-Rose suites
• meta/rose-meta.conf




How do I create metadata?

This depends on where the metadata is required.




JULES-Rose suites

u-ai828 is missing metadata for the rose-suite.conf file, which is called in by the suite.rc file.

What two sets of metadata are missing from the the meta/rose-meta.conf file?

Checkout u-ai828, create a branch of u-ai828, switch to the branch, change the meta/rose-meta.conf file to include helpful information for the two missing variables, commit the changes to the branch and test using rose edit. Change the metadata so a negative values cannot be used, metadata help (Viewing the Info) and the MPI_NUM_TASKS to help. Change the sort order. Commit your changes to the branch and re-check it.




How To Example

rosie checkout u-ai828 #(u-ai829 VM, u-ai843 JASMIN, u-al388 MONSooN)
fcm bc metadata
fcm sw metadata
# edit meta/rose-meta.conf e.g.
[jinja2:suite.rc=JULES_PATH]
ns=Runtime configuration
compulsory=true
description=The path to the JULES code depending on the platform.
type=character
sort-key=d
# don't forget the other variable.
fcm ci
rose edit
# edit meta/rose-meta.conf sort-key and negative values not allowed.
fcm ci
rose edit
                            





JULES code - rose-stem

This is very similar to the JULES-Rose suite example above, the metadata is in the rose-stem/meta/rose-meta.conf file. Most users and developers will never have to edit this file.




JULES code - benchmark

This is very similar to the JULES-Rose suite example above, the metadata is in the rose-stem/meta/rose-meta.conf file.




JULES code - rose-meta

This is the file that most users that are not purely using JULES-Rose suites will want to edit.

It is very infrequent that the rose-meta/jules-fcm-make/versions.py needs updating except for a release. It is not expected that a user/developer will need to edit this file.




Therefore the corresponding rose-meta/jules-fcm-make/HEAD/rose-meta.conf file is not expected to be edited by a user/developer.




In both the rose-meta/jules-fcm-make/ and the rose-meta/jules-standalone/ directory there are vn#.#/rose-meta.conf files these are updated at each release and or using the upgrade macro and are not to be edited.




The file for editing is only the most recent rose-meta/jules-standalone/versions.py file.

An example of the file at the start of a release:

import rose.upgrade

from .version34_40 import *
from .version40_41 import *
from .version41_42 import *
from .version42_43 import *
from .version43_44 import *
from .version44_45 import *
from .version45_46 import *
from .version46_47 import *
from .version47_48 import *
from .version48_49 import *

class vn49_txxx(rose.upgrade.MacroUpgrade):

    """Upgrade macro from JULES by Author"""

    BEFORE_TAG = "vn4.9"
    AFTER_TAG = "vn4.9_txxx"

    def upgrade(self, config, meta_config=None):
        """Upgrade a JULES runtime app configuration."""

        # Add settings
        return config, self.reports


'''
Do not edit any lines below this point - this is the template.
'''

class vn49_txxx(rose.upgrade.MacroUpgrade):

    """Upgrade macro from JULES by Author"""

    BEFORE_TAG = "vn4.9_txxx"
    AFTER_TAG = "vn4.9_txxx"

    def upgrade(self, config, meta_config=None):
        """Upgrade a JULES runtime app configuration."""

        # Add settings
        return config, self.reports

During a release, after an edit:

import rose.upgrade

from .version34_40 import *
from .version40_41 import *
from .version41_42 import *
from .version42_43 import *
from .version43_44 import *
from .version44_45 import *
from .version45_46 import *
from .version46_47 import *

class vn47_t414(rose.upgrade.MacroUpgrade):

    """Upgrade macro from JULES by Adrian Lock"""

    BEFORE_TAG = "vn4.7"
    AFTER_TAG = "vn4.7_t414"

    def upgrade(self, config, meta_config=None):
        """Upgrade a JULES runtime app configuration."""

        # Add settings
        self.add_setting(config, ["namelist:jules_snow", "graupel_options"],
                         "0")
        return config, self.reports


'''
Do not edit any lines below this point - this is the template.
'''

class vn47_txxx(rose.upgrade.MacroUpgrade):

    """Upgrade macro from JULES by Author"""

    BEFORE_TAG = "vn4.7_txxx"
    AFTER_TAG = "vn4.7_txxx"

    def upgrade(self, config, meta_config=None):
        """Upgrade a JULES runtime app configuration."""

        # Add settings
        return config, self.reports




Accompanying this rose-meta/jules-standalone/versions.py change is also a rose-meta/jules-standalone/HEAD/rose-meta.conf file change.

For example, with the above change some sort-key values were updated and a new section added:

[namelist:jules_snow=graupel_options]
compulsory=true
description=Switch for treatment of graupel in the snow scheme
help=Always "Include graupel as snowfall" in standalone JULES because separate
    =snow and graupel driving data are not available.
    =If graupel is included in the UM surface snowfall diagnostic
    =then JULES can either include this graupel as snow in the surface scheme (option 0),
    =ignore this graupel completely, thereby breaking conservation
    =of water and energy in the coupled land-atmosphere model (option 1) or
    =treat graupel seperately (currently this only means allowing graupel to
    =fall straight through the canopy)
value-titles=Include graupel as snowfall,Ignore graupel in the surface snowfall,
            =Treat graupel seperately
values=0,1,2
url=http://jules-lsm.github.io/vn4.7/namelists/jules_snow.nml.html#JULES_SNOW::graupel_options




Note in the jules-fcm-make/ directory there is only versions.py and no versions*_*.py files like in the jules-standalone. This is because there are relatively few changes to the jules-fcm-make metadata unlike the jules-standalone metadata.


How do I test metadata?

rose edit checks the metadata, but if you do not have GUI's or prefer command line you can use rose metadata-check in the metadata directory to check the metadata.




After changing the metadata in anyway or adding a new rose-stem test (see Developer Advanced Tutorial)

rose macro --fix -M /path/to/the/metadata/for/testing/




If you have added an Upgrade Macro you MUST also test it and apply the changes to the JULES code:

rose app-upgrade -M /path/to/the/metadata/for/testing/ app/fcm_make <version> && rose macro --fix -M /path/to/the/metadata/for/testing/
#or
./bin/upgrade_jules_test_apps vn#.#_t###

Practical 8 - Upgrade macros

Practical 8 will cover:




The versions.py in the above Practical leads us onto upgrade macros.




How to run an upgrade macro.

How to create an upgrade macro.

create-rose-app.py





How to run an upgrade macro

Generally you will only need to run the following upgrade macros as documented below. For further information please see:

# Checkout the suite
rosie checkout <suite_id>
# OR copy the suite to get a new id
rosie copy <suite_id>
# move to the directory of the (new)suite id
cd ~/roses/<(new)suite_id>

# Apply upgrade macros
rose app-upgrade -C app/fcm_make <version> && rose macro --fix -C app/fcm_make
rose app-upgrade -C app/jules <version>  && rose macro --fix -C app/jules

# Commit the changes, noting the revision number from the commit
fcm ci

Try upgrading u-aa799 by copying it and then upgrading it.




How to create an upgrade macro

Above in Practical 7 an upgrade macro was created in: rose-meta/jules-standalone/versions.py.


create-rose-app.py

This is a utility to make namelists into a JULES-Rose suite. The app's can then be used in a rosie u repository suite for science experiments.

# create-rose-app vn_from vn_to namelist_path suite_name jules_code_path
#  for example:
create-rose-app vn4.4 vn4.9 /path/to/my/4.4/namelist/ my_4p4_conversion /path/to/my/jules/code/at/4.9/

If you have a directory with old namelists files, please try the create-rose-app command.





For more on Rose Upgrade and Upgrade Macros please see: Rose Documentation.

Upgrading.

Upgrade Macro Development.

Congratulations you have completed the Developer Tutorial!