UKCA Chemistry and Aerosol vn10.9 Tutorial 11
UKCA Chemistry and Aerosol Tutorials at vn10.9
What you will learn in this Tutorial
In this tutorial you will go through a worked example showing you how to commit code to the UM trunk.
You should also open the working practices for the UM page on MOSRS and read through that as well.
This can only be completed on the Virtual Machine, as rose-stem does not currently work on ARCHER.
Before you start this Tutorial
Before you start this tutorial you will need to have a working Virtual Machine where known good output (or KGO) has been installed for the vm_n48_ukca_eg_noomp. You can do this by running the command
rose stem --group=vm_n48_ukca_eg_noomp -S GENERATE_KGO=true
within a vanilla copy of the vn10.9 trunk. When this runs for the first time the two KGO tasks will fail, but when this happens the KGO is installed. You just need to re-trigger these two tasks to run again, and they will succeed and the suite will stop.
For more information on the VM you should read-through umdp_X10.
Create a ticket
You will need to fill-in several headings. These can all be changed later if needed.
- Summary: Give a short description of what the change is for.
- Description: Give a longer and more detailed description.
- Type: Putting enhancement is usually fine here.
- Milestone: This should be the UM (or Mule) version that you are targeting. If you don't know a particular version leave this as Hopefully, and if you aren't targeting a version then you can put this as Not for Builds. In this example please use Not for Builds.
- Severity: Usually changes will be minor or significant, depending on if results are changed. Usually wholesale and trivial aren't used very often. This doesn't matter too much, as the Code Reviewer will often change this during their review.
- Keywords: When working on UKCA, please include UKCA and SC0138 (this is to make it easy to search for UKCA tickets)
Once you have created it, you should Modify it and start work and then click submit. This will change the ownership to you and change the ticket statue to in_progress. You will now be able to find your ticket on your view tickets page.
You can find an example of this here: um:#3639.
Tickets are important as they track the change through the MOSRS system. While initially "owned" by you, when you submit your code for review it will be passed to someone else. They will then mark on the ticket when it passes (or fails) their review and pass it on to the next stage prior to commit (or back to you to fix/clarify things). When the code is eventually committed it will be classed as "closed" and passed back to you.
It is best to keep the front page of the ticket relatively clear, as it will be used to pass information between yourself and the reviewers as the ticket progresses. You can always make sub-pages linked from the ticket to hold more information if needed.
Make a branch
Please make a branch as covered in Tutorial 4, e.g.
fcm branch-create --type dev -k ticket_number your_branch_name fcm:um.x_tr@vn10.9
and then check-out your branch by
fcm checkout fcm:um.x_br/dev/userid/vn10.9_your_branch_name
Merge in Initial Changes
You should merge-in branch dev/lukeabraham/vn10.9_UKCA_Worked_Example by changing into the top-level directory of your branch and doing
fcm merge fcm:um.x_br/dev/lukeabraham/vn10.9_UKCA_Worked_Example@47427
(Note: the revision number 47427 is important here) and then fcm commit your branch.
The code that you are checking in can be found here: https://code.metoffice.gov.uk/trac/um/changeset/47427
Index: src/atmosphere/UKCA/ukca_light.F90 =================================================================== --- src/atmosphere/UKCA/ukca_light.F90 (revision 47420) +++ src/atmosphere/UKCA/ukca_light.F90 (revision 47427) @@ -241,27 +241,60 @@ ! 3 from cloud base to 2 above top ! KLT is the level above cloud top - dpcg = ppress(1) - ppress(jniv) - dpcc = ppress(jniv) - ppress(klt) + IF (l_ukca_linox_logp) THEN + ! DO EVERYTHING LINEARLY IN LOG(PRESSURE) + ! sanity check to prevent dpcg==0 + IF (jniv <= 1) jniv=2 + + dpcg = LOG(ppress(1)) - LOG(ppress(jniv)) + dpcc = LOG(ppress(jniv)) - LOG(ppress(klt)) + ! ...construct L-NOx profile in kg(N)/gridcell/s + ! ...first cloud-to-ground L-NOx profiles (kg(N)/gridcell/s) + IF ((jniv-1) == 1) THEN + anox(1) = acgnox + ELSE + DO k = 1,jniv-1 + anox(k) = acgnox * ((LOG(ppress(k))-LOG(ppress(k+1)))/dpcg) + END DO + END IF + + ! ...then cloud-to-cloud L-NOx profiles (kg(N)/gridcell/s) + IF (LOG(ppress(jniv)) <= LOG(ppress(klt))) THEN + ! jniv (level of the 500hPa level) is above the + ! cloud-top-height. In this case, put all C2C N + ! into the cloud-top level. + anox(klt-1) = anox(klt-1) + accnox + ELSE + ! jniv is greater than the cloud-top-height + ! Note: anox(k) is also on the RHS of this equation + DO k = jniv,klt-1 + anox(k) = anox(k) + accnox * ( (LOG(ppress(k)) - LOG(ppress(k+1))) / dpcc ) + END DO + END IF + ELSE ! .not. l_ukca_linox_logp + ! DO EVERYTHING LINEARLY IN PRESSURE + dpcg = ppress(1) - ppress(jniv) + dpcc = ppress(jniv) - ppress(klt) + ! ...construct L-NOx profile in kg(N)/gridcell/s + ! ...first cloud-to-ground L-NOx profiles (kg(N)/gridcell/s) + IF ((jniv-1) == 1) THEN + anox(1) = acgnox + ELSE + DO k = 1,jniv-1 + anox(k) = acgnox * ((ppress(k)-ppress(k+1))/dpcg) + END DO + END IF + + ! ...then cloud-to-cloud L-NOx profiles (kg(N)/gridcell/s) + IF (ppress(jniv) <= ppress(klt)) THEN + anox(klt-1) = anox(klt-1) + accnox + ELSE + DO k = jniv,klt-1 + anox(k) = accnox * ((ppress(k)-ppress(k+1))/dpcc) + END DO + END IF + END IF ! l_ukca_linox_logp - ! ...construct L-NOx profile in kg(N)/gridcell/s - ! ...first cloud-to-ground L-NOx profiles (kg(N)/gridcell/s) - IF ((jniv-1) == 1) THEN - anox(1) = acgnox - ELSE - DO k = 1,jniv-1 - anox(k) = acgnox * ((ppress(k)-ppress(k+1))/dpcg) - END DO - END IF - - ! ...then cloud-to-cloud L-NOx profiles (kg(N)/gridcell/s) - IF (ppress(jniv) <= ppress(klt)) THEN - anox(klt-1) = anox(klt-1) + accnox - ELSE - DO k = jniv,klt-1 - anox(k) = accnox * ((ppress(k)-ppress(k+1))/dpcc) - END DO - END IF END IF IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_out,zhook_handle)
The aim of this change is to allow the code to either redistribute lightning NOx emissions vertically either linearly in pressure (the current default) or linearly in LOG(pressure) (the new change).
Take a look through this code. Can you spot any issues that you think it might have?.
Run rose-stem
You should now run this through rose-stem by running the command
rose stem --group=vm_n48_ukca_eg_noomp,umdp3_check
The vm_n48_ukca_eg_noomp will run the code through one of the UKCA jobs, and the umdp3_check will test for coding standard compliance.
Rose-stem will fail. How does it fail? What are the error messages? What can you do to fix them?
Monsoon2
If you have access to Monsoon2, you should be able to run equivalent test to this by using the following rose-stem command
rose stem --group=meto_xc40_n48_ukca_eg_omp_noios_gnu,umdp3_check -S PROJECT=\'your-monsoon-project\' -S HOST_XC40=\'xcslc0\'
This will run the Met Office (meto) equivalent to the virtual machine rose-stem job. The xc40 indicates that it runs on the Cray XC40 architecture, rather than elsewhere (e.g. on a GNU/Linux system).
Note that as all the Met Office rose-stem tests are available, running --group=developer, --group=ukca, or any one of the larger groups will take a long time to complete due to the reduced size of the system. It is best to limit the number of tests to the minimum for this exercise.
umdp3_check
The error message (in the job.out file) is:
The following files have failed the UMDP3 compliance tests: File src/atmosphere/UKCA/ukca_light.F90 : Line longer than 80 characters: ' anox(k) = anox(k) + accnox * ( (LOG(ppress(k)) - LOG(ppress(k+1))) / dpcc ) '
This is relatively easy to solve by adding a continuation line.
Index: src/atmosphere/UKCA/ukca_light.F90
===================================================================
--- src/atmosphere/UKCA/ukca_light.F90 (revision 47427)
+++ src/atmosphere/UKCA/ukca_light.F90 (revision 47436)
@@ -268,7 +268,8 @@
! jniv is greater than the cloud-top-height
! Note: anox(k) is also on the RHS of this equation
DO k = jniv,klt-1
- anox(k) = anox(k) + accnox * ( (LOG(ppress(k)) - LOG(ppress(k+1))) / dpcc )
+ anox(k) = anox(k) + accnox * &
+ ( (LOG(ppress(k)) - LOG(ppress(k+1))) / dpcc )
END DO
END IF
ELSE ! .not. l_ukca_linox_logp
See https://code.metoffice.gov.uk/trac/um/changeset/47436
If you make this change and then fcm commit you can then re-run the umdp3_check task again (after stopping any still running suites).
rose stem --group=umdp3_check
You should find that it passes successfully.
fcm_make_vm_gnu_um_safe_noomp
The error is (in the job.err fail) is:
[FAIL] /home/vagrant/cylc-run/vn10.9_UKCA_Worked_Example/share/fcm_make_vm_gnu_um_safe_noomp/preprocess-atmos/src/um/src/atmosphere/UKCA/ukca_light.F90:257:23: [FAIL] [FAIL] IF (l_ukca_linox_logp) THEN [FAIL] 1 [FAIL] Error: Symbol ‘l_ukca_linox_logp’ at (1) has no IMPLICIT type [FAIL] compile 0.2 ! ukca_light_mod.o <- um/src/atmosphere/UKCA/ukca_light.F90 [FAIL] ! ukca_light_mod.mod : depends on failed target: ukca_light_mod.o [FAIL] ! ukca_light_mod.o : update task failed
This can be easily fixed by adding the following at the top of the ukca_light.F90 routine:
Index: src/atmosphere/UKCA/ukca_light.F90 =================================================================== --- src/atmosphere/UKCA/ukca_light.F90 (revision 47436) +++ src/atmosphere/UKCA/ukca_light.F90 (revision 47439) @@ -138,6 +138,9 @@ REAL :: ns_res_deg ! gridbox height in degrees REAL :: fr_calib_fac ! model resolution calibration factor +! logical to select redistribution in pressure (F) or LOG(pressure) (T) +LOGICAL, PARAMETER :: l_ukca_linox_logp = .false. + INTEGER(KIND=jpim), PARAMETER :: zhook_in = 0 INTEGER(KIND=jpim), PARAMETER :: zhook_out = 1 REAL(KIND=jprb) :: zhook_handle
See https://code.metoffice.gov.uk/trac/um/changeset/47439/
Note that the logical is set to .false. above, meaning that the code will continue to use the old method.
You can now run rose-stem again:
rose stem --group=vm_n48_ukca_eg_noomp
Rose-stem will now pass all tests and complete successfully.
What happens if you set l_ukca_linox_logp = .true.?
Index: src/atmosphere/UKCA/ukca_light.F90 =================================================================== --- src/atmosphere/UKCA/ukca_light.F90 (revision 47439) +++ src/atmosphere/UKCA/ukca_light.F90 (revision 47446) @@ -139,7 +139,7 @@ REAL :: fr_calib_fac ! model resolution calibration factor ! logical to select redistribution in pressure (F) or LOG(pressure) (T) -LOGICAL, PARAMETER :: l_ukca_linox_logp = .false. +LOGICAL, PARAMETER :: l_ukca_linox_logp = .true. INTEGER(KIND=jpim), PARAMETER :: zhook_in = 0 INTEGER(KIND=jpim), PARAMETER :: zhook_out = 1
See https://code.metoffice.gov.uk/trac/um/changeset/47446
If you now make this change and re-run rose stem
rose stem --group=vm_n48_ukca_eg_noomp
what happens?
rose_ana_vm_n48_ukca_eg_noomp_atmos_kgo
Now, the rose-ana task fails with the following error (in the job.out file):
[FAIL] %%%%%%%%%%%%%%%%%%%%%%%%%%%%% [FAIL] * CUMF-II Comparison Report * [FAIL] %%%%%%%%%%%%%%%%%%%%%%%%%%%%% [FAIL] [FAIL] File 1: /home/vagrant/umdir/standard_jobs/kgo/vm_n48_ukca_eg_1x2/vn10.9/atmosa.pa19810901_00 [FAIL] File 2: /home/vagrant/cylc-run/vn10.9_UKCA_Worked_Example/work/1/atmos_vm_n48_ukca_eg_noomp_1x2/atmosa.pa19810901_00 [FAIL] Files DO NOT compare [FAIL] * 0 differences in fixed_length_header (with 7 ignored indices) [FAIL] * 387 field differences, of which 387 are in data [FAIL] [FAIL] Compared 583/583 fields, with 196 matches [FAIL] Maximum RMS diff as % of data in file 1: 129.036987416 (field 496) [FAIL] Maximum RMS diff as % of data in file 2: 56.3431083041 (field 496)
i.e. the results have changed. When finished, rose-stem will generate a file, called trac.log, that can be found in the cylc-run directory of your branch. For the test above, this will show that it has failed one test, but passed the others.
You can see an example of this output here: https://code.metoffice.gov.uk/trac/um/wiki/ticket/3639/stemfail
The trac.log file is formatted so that when it is pasted onto the MOSRS Twiki system it will appear as a formatted table. This is because rose-stem output (in the form of the trac.log file) is required to complete a ticket for submission to the trunk. More on this will be discussed later.
It is important not to paste the contents of the trac.log file to the front page of the ticket, as the formatting makes this hard to read. If you want to keep a record of multiple rose-stem tests, you should make a new wiki page linked from the ticket and copy the information there.
Hard-coding a logical is not a good idea in this case, as it can only be changed by re-compiling the code. It is easy to forget to do this, and also many UM runs use standard binaries.
Adding new namelist input
A better solution is to introduce the logical l_ukca_linox_logp into the input namelist and allow it to be set by a user in Rose. To do this we must make several code changes.
ukca_option_mod.F90
All variables within the run_ukca namelist, that holds all the UKCA inputs, are declared in ukca_option_mod.F90. This module also contains the namelist itself, as well as some umPrint statements and handling for parallel calls. To add a new namelist variable you need to:
- Add a declaration for it, e.g.
LOGICAL :: l_ukca_linox_logp =.FALSE.
- All logicals must be set to
.FALSE., character variables must be set to'VARIABLE NAME is unset'and integers and reals must be set to missing data values (defined asimdiandrmdirespectively).
- Add the variable to the
run_ukcanamelist. - Print the value, e.g.
WRITE(lineBuffer,'(A33,L1)')' l_ukca_linox_logp = ', l_ukca_linox_logpCALL umPrint(lineBuffer,src='ukca_option_mod')
- Add the variable to the
my_namelistderived type. - On processor 0, save the value of the new variable within the
my_nmlvariable (which is of typemy_namelist). - After
my_nmlhas been broadcast, on all other processors copy the value of the variable out of themy_nmlvariable and into the variable itself. This then means that it can be used as expected in all routines. - If required, you may also need to add some checks on the variable to the
check_run_ukcaroutine within this module, to ensure that the value (or value range) is correct.
ukca_light.F90
In ukca_light.F90 we now need to stop declaring the variable at the top of the routine, and instead USE it from ukca_option_mod.F90, e.g.
USE ukca_option_mod, ONLY: l_ukca_linox_logp
rose-meta/um-atmos/HEAD/rose-meta.conf
We need to add a section here on the new variable to tell Rose how to treat it, e.g.
[namelist:run_ukca=l_ukca_linox_logp]
compulsory=true
description=When T, Lightning NOx emissions are distributed
=vertically using LOG(pressure)
help=When T, this logical makes the UKCA Lightning NOx routine
=redistribute the Lightning NOx emissions in the vertical
=linearly using LOG(pressure)
sort-key=b16
type=logical
There needs to be help text (which will be shown by Rose when selecting help when clicking on the cog associated with the variable, as well as short description that is shown under the variable name to tell the user what it's for. The sort-key is used to order the variables in the Rose panel. For integer or real variables, it's possible to give an allowed range of values, or use radio buttons etc.
rose-meta/um-atmos/version109_110.py
As a new namelist input has been added (and similarly if one is removed or changed in some way), then an upgrade macro will need to be written to all the new variable to be automatically be inserted into Rose. When the UM goes from one version to another these macros are run sequentially to upgrade Rose to be able to use the new UM version, containing all the new (or changed) namelist items.
This macro takes the form of a short python function which inserts default values (formatted as strings), and looks like this:
class vn109_t3639(rose.upgrade.MacroUpgrade):
"""Upgrade macro for ticket #3639 by Luke Abraham."""
BEFORE_TAG = "vn10.9"
AFTER_TAG = "vn10.9_t3639"
def upgrade(self, config, meta_config=None):
"""
Introduce logical to interpolate linearly in LOG(p)
for the vertical redistribution of Lightning NOx.
"""
self.add_setting(config,["namelist:run_ukca",
"l_ukca_linox_logp"],".false.")
return config, self.reports
The name of the function is of the form vnX.Y_tticket_number.
All changes
Index: src/atmosphere/UKCA/ukca_light.F90
===================================================================
--- src/atmosphere/UKCA/ukca_light.F90 (revision 47446)
+++ src/atmosphere/UKCA/ukca_light.F90 (revision 47454)
@@ -57,6 +57,7 @@
USE parkind1, ONLY: jprb, jpim
USE parcons_mod, ONLY: rad, deg
USE ukca_constants, ONLY: avc
+USE ukca_option_mod, ONLY: l_ukca_linox_logp
IMPLICIT NONE
@@ -138,9 +139,6 @@
REAL :: ns_res_deg ! gridbox height in degrees
REAL :: fr_calib_fac ! model resolution calibration factor
-! logical to select redistribution in pressure (F) or LOG(pressure) (T)
-LOGICAL, PARAMETER :: l_ukca_linox_logp = .true.
-
INTEGER(KIND=jpim), PARAMETER :: zhook_in = 0
INTEGER(KIND=jpim), PARAMETER :: zhook_out = 1
REAL(KIND=jprb) :: zhook_handle
Index: src/atmosphere/UKCA/ukca_option_mod.F90
===================================================================
--- src/atmosphere/UKCA/ukca_option_mod.F90 (revision 47446)
+++ src/atmosphere/UKCA/ukca_option_mod.F90 (revision 47454)
@@ -78,6 +78,9 @@
! T to pass columns to ASAD rather than theta_field
LOGICAL :: l_ukca_asad_columns =.FALSE.
+! T to use LOG(p) to distribute lightning NOx in the vertical
+LOGICAL :: l_ukca_linox_logp =.FALSE.
+
INTEGER :: chem_timestep = imdi ! Chemical timestep in seconds for N-R
! and Offline oxidant schemes
INTEGER :: dts0 = 300 ! Default Backward Euler timestep
@@ -358,7 +361,7 @@
i_ageair_reset_method, max_ageair_reset_level, &
max_ageair_reset_height, &
i_ukca_sad_months, i_ukca_sad_start_year, &
- l_ukca_limit_nat
+ l_ukca_limit_nat, l_ukca_linox_logp
! -----------------------------------------------------------------------------
! These are set in ukca_setup_chem_mod after the namelist is read
@@ -756,6 +759,8 @@
l_ukca_use_background_aerosol
WRITE(lineBuffer,'(A33,L1)')' l_ukca_asad_columns = ', &
l_ukca_asad_columns
+WRITE(lineBuffer,'(A33,L1)')' l_ukca_linox_logp = ', &
+ l_ukca_linox_logp
CALL umPrint(lineBuffer,src='ukca_option_mod')
WRITE(lineBuffer,'(A33,L1)')' l_ukca_primsu = ',l_ukca_primsu
CALL umPrint(lineBuffer,src='ukca_option_mod')
@@ -1000,7 +1005,7 @@
INTEGER, PARAMETER :: no_of_types = 4
INTEGER, PARAMETER :: n_int = 21 + a_max_ukcavars
INTEGER, PARAMETER :: n_real = 25
-INTEGER, PARAMETER :: n_log = 51
+INTEGER, PARAMETER :: n_log = 52
INTEGER, PARAMETER :: n_chars = 10 * filenamelength &
+ filenamelength * (1+ nr_cdf_files) &
+ filenamelength * (1+ max_offline_files) &
@@ -1106,6 +1111,7 @@
LOGICAL :: l_ukca_so2ems_expvolc
LOGICAL :: l_ukca_quasinewton
LOGICAL :: l_ukca_limit_nat
+ LOGICAL :: l_ukca_linox_logp
CHARACTER (LEN=filenamelength) :: jvspec_dir
CHARACTER (LEN=filenamelength) :: jvspec_file
CHARACTER (LEN=filenamelength) :: jvscat_file
@@ -1243,6 +1249,7 @@
my_nml % l_ukca_so2ems_expvolc = l_ukca_so2ems_expvolc
my_nml % l_ukca_quasinewton = l_ukca_quasinewton
my_nml % l_ukca_limit_nat = l_ukca_limit_nat
+ my_nml % l_ukca_linox_logp = l_ukca_linox_logp
! end of logicals
my_nml % jvspec_dir = jvspec_dir
my_nml % jvspec_file = jvspec_file
@@ -1371,6 +1378,7 @@
l_ukca_so2ems_expvolc = my_nml % l_ukca_so2ems_expvolc
l_ukca_quasinewton = my_nml % l_ukca_quasinewton
l_ukca_limit_nat = my_nml % l_ukca_limit_nat
+ l_ukca_linox_logp = my_nml % l_ukca_linox_logp
! end of logicals
jvspec_dir = my_nml % jvspec_dir
jvspec_file = my_nml % jvspec_file
Index: rose-meta/um-atmos/version109_110.py
===================================================================
--- rose-meta/um-atmos/version109_110.py (revision 47446)
+++ rose-meta/um-atmos/version109_110.py (revision 47454)
@@ -17,15 +17,23 @@
-class vn109_tXXXX(rose.upgrade.MacroUpgrade):
+class vn109_t3639(rose.upgrade.MacroUpgrade):
- """Upgrade macro for ticket #XXXX by <author>."""
+ """Upgrade macro for ticket #3639 by Luke Abraham."""
BEFORE_TAG = "vn10.9"
- AFTER_TAG = "vn10.9_tXXXX"
+ AFTER_TAG = "vn10.9_t3639"
def upgrade(self, config, meta_config=None):
- """Upgrade a UM runtime app configuration."""
- # Input your macro commands here
+ """
+ Introduce logical to interpolate linearly in LOG(p)
+ for the vertical redistribution of Lightning NOx.
+ """
+
+ self.add_setting(config,["namelist:run_ukca",
+ "l_ukca_linox_logp"],".false.")
+
return config, self.reports
+
+
Index: rose-meta/um-atmos/HEAD/rose-meta.conf
===================================================================
--- rose-meta/um-atmos/HEAD/rose-meta.conf (revision 47446)
+++ rose-meta/um-atmos/HEAD/rose-meta.conf (revision 47454)
@@ -23534,6 +23534,16 @@
sort-key=b15
type=real
+[namelist:run_ukca=l_ukca_linox_logp]
+compulsory=true
+description=When T, Lightning NOx emissions are distributed
+ =vertically using LOG(pressure)
+help=When T, this logical makes the UKCA Lightning NOx routine
+ =redistribute the Lightning NOx emissions in the vertical
+ =linearly using LOG(pressure)
+sort-key=b16
+type=logical
+
[namelist:run_ukca=max_ageair_reset_height]
compulsory=true
description=Maximum height for resetting Age-of-air tracer values
See https://code.metoffice.gov.uk/trac/um/changeset/47454/
Make a test branch and test it with rose-stem
fcm branch-create -k ticket_number --branch-of-branch -t test your_branch_name fcm:um.x_br/dev/your_MOSRS_username/vn10.9_your_branch_name
You should then checkout this branch, cd into its top-level directory and run the command
./admin/rose-stem/update_all.py /home/vagrant/path/to/rXXXXX_your_branch_name --um=vn10.9_tticket_number
where XXXXX is the last revision number of vn10.9_your_branch_name prior to you creating the test branch.
This python script will then go through and upgrade all the apps, which are different configurations of the UM used for testing, and insert the new namelist input and check the metadata.
A full list of the changes made in this case can be found here: https://code.metoffice.gov.uk/trac/um/changeset/47481
You should fcm commit your changes, and then run rose-stem again
rose stem --group=vm_n48_ukca_eg_noomp,scripts
where the scripts group runs the umdp3_check as well as some other checks. This will now pass, and you can see in the trac.log file that everything has completed successfully.
The Virtual Machine set of standard tests can be found here: https://code.metoffice.gov.uk/trac/um/wiki/VirtualMachine/StandardJobs10.9
The Met Office set of standard tests can be found here: https://code.metoffice.gov.uk/trac/um/wiki/StandardJobs10.9
The minimum group that is needed to be checked is developer group at the Met Office. If you do not have access to Monsoon2 you will need to ask someone who does to run these tests, or ask someone with access to the internal Met Office network.
Documentation
There are two levels of documentation on the ticket and in the relevant documentation paper (UMDP). All changes must have a ticket description, and some may also require updates to one or model Unified Model documentation papers (UMDPs).
Ticket
For small changes, all that will be required is some text in the ticket Description, but for more involved changes a ticket details page will need to be added. To do this, modify the ticket to add the following at the end of the description:
[wiki:ticket/ticket_number/TicketDetails Ticket Details]
Save, and then click on the gray link. You will then be asked to create the page, and do so using the TicketDetails template from the drop-down menu. this will make a blank page containing the following:
= Ticket Details <#Ticket Nr> = == Author: <name> == ----- == Branch == [log:main/branches/] ----- == Documentation and Testing == Please add details here: -----
You should add-in the information on the branch and the ticket etc., and then add details under the Documentation and Testing section. This should be as detailed as possible to describe what the ticket does. A blank example for this ticket/branch can be found here: https://code.metoffice.gov.uk/trac/um/wiki/ticket/3639/TicketDetails
UMDP
Please also see https://code.metoffice.gov.uk/trac/um/wiki/WorkingPractices/Documentation/UpdatingUMDPs
Note: Until UM vn11.0 it is not possible to generate UMDPs on the VM - this requires the change in #3612, which has been committed at r47913. This means it is possible to make a documentation branch from the head of the trunk (HoT) instead.
Small changes often do not require detailed documentation to be added - the ticket itself is usually sufficient. However, for changes to namelist variables (such as the change added here) the documentation must be updated. This does not need to be a big change, but the changes to the namelist need to be kept up-to-date. The documentation paper is a living document and so needs to reflect the state of the code that is being committed to the trunk.
A documentation branch is required for this, e.g.
fcm branch-create -k ticket_number your_documentation_branch_name fcm:um_doc.x_br@vn10.9
where your_documentation_branch_name will need to be different from your_branch_name to avoid confusion.
Virtual Machine Head of Trunk branch
To make a HoT branch on the VM the process is similar, e.g.
fcm branch-create -k ticket_number your_documentation_branch_name fcm:um_doc.x_br@HEAD
The name the branch created will now be something like rXXXXX_your_documentation_branch_name rather than vn10.9_your_documentation_branch_name. This is the only appreciable difference. If you wanted instead of HEAD you could also specify r47913 instead.
For the VM to be able to build UMDPs correctly you need to have created a VM after 6th December 2017 that includes pull request #12 as this adds support for LaTeX. You may also need to run apt-get to install a PDF viewer such as evince or xpdf.
You should then checkout your documenation branch and make the changes required. For this change they are:
umdp84_app_control_vars.tex
The file source/084/umdp84_app_control_vars.tex contains a table listing all the namelist variables used by UKCA. You will need to add information here:
Index: doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_app_control_vars.tex
===================================================================
--- a/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_app_control_vars.tex
+++ b/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_app_control_vars.tex
@@ -93,4 +93,6 @@
L\_UKCA\_ASAD\_COLUMNS & True to pass columns to ASAD Newton-Raphson solver \\
& rather than latitude-longitude slices. \\
+ L\_UKCA\_LINOX\_LOGP & True to redistribute Lightning NOx \\
+ & emissions vertically using log(pressure) \\
\hline
\multicolumn{2}{|l|}{MODE Options} \\
umdp84_emissions.tex
A technical or scientific description of the change will also be required. Here this should be made to the source/084/umdp84_emissions.tex file, e.g.
Index: doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_emissions.tex
===================================================================
--- a/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_emissions.tex
+++ b/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84_emissions.tex
@@ -265,4 +265,5 @@
users to scale the derived Lightning NOx emissions by any factor between 0.0 and 5.0.
+If the control logical L\_UKCA\_LINOX\_LOGP is true, lightning NO$_x$ emissions will be vertically redistributed linearly in $\log($pressure$)$. If this is false then the emissions are vertically redistributed
linearly in pressure.
\subsubsection{Sea salt primary emissions}
UM version
Unless you are working on a head of trunk branch, you will also need to update the UM version number in the UMDP to show that the change is in line with the next version. This is done in the source/084/umdp84.tex file:
Index: doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84.tex
===================================================================
--- a/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84.tex
+++ b/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc/source/084/umdp84.tex
@@ -3,5 +3,5 @@
\title{United Kingdom Chemistry and Aerosol (UKCA) Technical Description}
\paperno{084}
-\umversion{10.9}
+\umversion{11.0}
\owner{Luke Abraham}
\author{
This must be done for all changes to UMDPs
The documentation branch containing these changes can be seen here: https://code.metoffice.gov.uk/trac/um/log/doc/branches/dev/lukeabraham/vn10.9_UKCA_Worked_Example_Doc
The UMDP containing all these changes can be found here: https://code.metoffice.gov.uk/trac/um/attachment/ticket/3639/Worked_Example-umdp_084.pdf
Next Steps
Ticket Summary
Once you've documented your ticket and made your UMDP, you will need to make a ticket summary prior to submitting the change to the trunk. A blank example can be found here: https://code.metoffice.gov.uk/trac/um/wiki/ticket/3639/TicketSummary
You will need to answer all the questions and append your final rose-stem output.
SciTech Review
When you have completed everything you will pass the ticket to someone else for Sci/Tech Review. This person may be the code owner of the (largest) section you are altering, or it may be someone else suitable who you have previously approached. They will then complete the Sci/Tech Review template and will either approve the change, or ask for further changes or clarification. If the latter, they will pass the ticket back to you, and when you're happy that you've answered all questions you should hand the ticket back to Sci/Tech Reviewer, and document the ticket, ticket details, or ticket summary with more information as appropriate.
When you pass the ticket to the Sci/Tech reviewer it is also a good idea to email the UM Systems Team at this point and ask for the name of the Code Reviewer, as the Sci/Tech Reviewer can pass it directly to them when the change is approved.
A blank Sci/Tech Review template can be found here: https://code.metoffice.gov.uk/trac/um/wiki/ticket/3639/SciTechReview
Code Review
Anyone with an SRS account can be a Sci/Tech Reviewer, but (generally) only members of the UM Systems Team can be Code Reviewers, as the Code Reviewer is the person who will commit the change to the trunk.
Once your change has passed Sci/Tech Review it will then be checked by the Code Reviewer for coding standards and consistency, whether the code change is linked to changes in other models, such as JULES, whether documentation has been made etc. A blank Code/System Review template can be seen here: https://code.metoffice.gov.uk/trac/um/wiki/ticket/3639/CodeSystemReview
The Code Reviewer may have further changes or questions which will also need to be answered prior to the code being accepted for the UM trunk. They will pass the ticket back to you, and you will need to make changes and then pass the ticket back to them before they will respond. It is important that the ownership of the ticket is changed to the correct person at each step.
Once the code change has been approved the status of the ticket will be changed to approved, and when the code has been committed it will be committed. Then the code change will be automatically be checked overnight in the standard testing suites, and if there are no problems the ticket will be set to closed a few days later. At that point the Code Reviewer will change the ownership of the ticket to you again.
Congratuations! You have successfully had a change committed to the trunk!
Checklist
- ☐ Use
rose-stemto test and develop your change. - ☐ Remember to check for UMDP3 code compliance.
- ☐ Document your ticket sufficiently.
- ☐ You may need to make a test brach.
- ☐ You may need to update UMDPs. Remember to update the UM version number if you do.
- ☐ Remember to respond to all questions/corrections from your SciTech and Code reviewers.
- ☐ Remember to pass ownership of the ticket back to the appropriate reviewer when required.
UKCA Chemistry and Aerosol Tutorials at vn10.9
Written by Luke Abraham 2017
