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

Installing KGO on the VM, showing the initial failed state.

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

• https://code.metoffice.gov.uk/trac/um/newticket

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.

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

Rose-stem failing.

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?

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.?

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)

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?

Adding new namelist input

A better solution is to introduce the logical l_ukca_linox_logp into the namelist and allow it to be set by a user in Rose. To do this we must make several code changes.

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/

UKCA Chemistry and Aerosol Tutorials at vn10.9

---

Written by Luke Abraham 2017