UKCA Chemistry and Aerosol vn10.4 Tutorial 4

From UKCA
Revision as of 14:22, 23 November 2016 by Nla27 (talk | contribs)

UKCA Chemistry and Aerosol Tutorials at vn10.4

What you will do in this tutorial

In this tutorial you will learn how to make the required changes in Rose and in UKCA to include new chemical tracers. As you learn how to do this you will add two new tracers to the UKCA tutorial suite you have already been running.

Task 4.1: Add new tracers into Rose and UKCA

TASK4.1: Add in two new tracers in to slots 64 and 65 for the StratTrop chemistry scheme. The tracer in slot 64 will be called ALICE and the tracer in slot 65 will be called BOB and initialise these tracers to 1.000000e-12. You should also output these two tracers through the UPK stream in STASH as daily means. In UKCA, you should set the conversion factor for each of these to 1.0.

Note: If you were unable to successfully complete Task 3.1, then you may want take a copy of u-ai084@25605 suite and work from there. However, this is not strictly necessary at this stage.

Make a branch

As UKCA is a framework, it must have the infrastructure around it to allow it to work, with the infrastructure being the UM itself. In this tutorial you will add in two new chemical tracers. In this past this was done in two steps, but in Rose this must be done in a single step from vn10.6 onwards. Even though these tutorials are at vn10.4, we will follow the same steps as for vn10.6.

For this tutorial you will need to make a new branch in the usual way. You should do this now.

You will have learned how to make UM branches in the NCAS-CMS FCM Tutorial. However, now you should use um.x_tr as the source of your branch.

For example, first you should make a ticket on the UM Trac pages (login required) and then make the branch like so

fcm branch-create --type dev -k ticket_number your_branch_name fcm:um.x_tr@vn10.4

before checking-out your branch by

fcm checkout fcm:um.x_br/dev/userid/vn10.4_your_branch_name

More information on FCM can be found at the NCAS-CMS FCM pages.

Metadata

In Rose, the GUI appearance is controlled by metadata, and it is possible to edit this metadata to add new variables to panels. We will not do this in this tutorial, but you will need to change where Rose looks for metadata, as the STASHmaster_A is also metadata.

vn10.4

At vn10.4, the um metadata associated with your suite can be found by clicking on the um menu entry. In the base suite, this is set to /home/grenville/meta/ga7_vn10.4. However, you will also need to include the metadata changes here. To do this, cd into your branch and merge-in the branch fcm:um.x_br/dev/lukeabraham/vn10.4_ga7_meta

fcm merge fcm:um.x_br/dev/lukeabraham/vn10.4_ga7_meta

and then

fcm commit

vn10.6

At vn10.6, this is not necessary, as the additional metadata for GA7.0 is already in the trunk.

Using your new metadata within Rose

To pick-up the metadata changes, you should edit the meta path in um to point to

um-atmos/HEAD

From now on, when you want to open your Rose suite for editing, instead of doing it through rosie, you should instead open the job for editing by going to your $HOME/roses/[SUITE-ID] directory, and opening it using the command

rose edit -M /path/to/vn10.4_your_branch_name/rose-meta

If you don't do this, the STASHmaster changes will not be picked up, and you won't be able to select the tracers.

Rose Changes

STASHmaster_A

In Rose-based jobs, adding new UKCA tracers is done through editing the STASHmaster_A file directly. Take a look at the STASHmaster_A file, found in

/path/to/vn10.4_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A

This is a large file, as it contains all the possible STASH items. Scroll down the file until you get to section 34, and you will see how the tracers are defined. The key entries to consider are highlighted in red. All entried are fixed-width, so when editing the file, ensure not to change the spacing, otherwise you will get errors.

#===============================================================================
# Section 34 UKCA Chemistry
#===============================================================================
#
1|    1 |   34 |    1 |O3 MASS MIXING RATIO AFTER TIMESTEP |
2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000111110 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 2101 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

The meaning of these entries is:

First Line:

  • 34: The STASH section, in this case Section 34, UKCA prognostics.
  • 1: The STASH item, in this case, the first item in s34, ozone.
  • O3 MASS MIXING RATIO AFTER TIMESTEP: The name of the field in the STASHmaster file. This can be anything descriptive, but it isn't read by the model, and is only considered in Rose (or e.g. Xconv).

Second Line:

  • 2: The Space Code, which tells the UM whether the field should be held in the restart dump or not. For prognostics, this should be 2, but for diagnostics that are only passed to output files, this should be 0.


Third Line:

  • 000000000000000000000000111110: These are Options Codes which determine which scheme the STASH field (i.e. tracer in this case) are valid for. These are counted from the right, n1 to n30, and for UKCA only the first 8 are used. These have the following meaning:
    • n1: Age-of-air tracer only (ageair)
    • n2: Standard Tropospheric Chemistry scheme using the Backward Euler solver (trop)
    • n3: Regional Air Quality Chemistry scheme using the Backward Euler solver (raq)
    • n4: Tropospheric Chemistry with Isoprene scheme using the Newton-Raphson solver (tropisop)
    • n5: Stratospheric-Tropospheric Chemistry using the Newton-Raphson solver (strattrop, also know as CheST)
    • n6: Standard Stratospheric Chemistry using the Newton-Raphson solver (strat)
    • n7: Offline-oxidants scheme (to drive GLOMAP-mode) using the Newton-Raphson solver (offline)
    • n8: Offline-oxidants scheme (to drive GLOMAP-mode) using the Newton-Raphson solver (offline_be)

Therefore, looking at the option code for ozone (s34i001), it is valid for the trop, raq, tropisop, strattrop, and strat chemistry schemes.

Fifth Line:

  • 2101: This is the PP Field Code and should be unique to each tracer. Here these begin counting at 2101 (s34i001) and end at 2250 (s34i150) for vn10.4, or 2356 (s34i256) for vn10.6, as the number of tracers has been increased.

So to make a STASH entry for a single tracer called ALICE in slot s34i064 that is only valid in the StratTrop scheme, the STASHmaster_A entry would look like

#
1|    1 |   34 |   64 |ALICE MASS MIXING RATIO AFTER TSTEP |
2|    2 |    0 |    1 |    1 |    2 |   40 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000010000 | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 2164 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

Remember: You need to add 2 tracers, ALICE in s34i064 and BOB in s34i065.

You should make these changes to STASHmaster_A, and then fcm commit these changes. This is important, otherwise ARCHER will not be able to see the changes you have made.

Section 51

All STASH entries in Section 34 need a corresponding pressure-level field to be added to section 51. The equivalent STASHmaster_A entry for s51 ozone is:

#
#===============================================================================
# Section 51 UKCA Chemistry on pressure levels
#===============================================================================
#
1|    1 |   51 |    1 |O3 MASS MIXING RATIO ON PRESS LEVS  |
2|    0 |    0 |    1 |    1 |    3 |    1 |    2 |    0 |    0 |    0 |    1 |
3| 000000000000000000000000111110 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 | 2101 |    0 |    8 |    0 |    0 |    0 |    0 |    0 |
#


Use your new STASHmaster file in Rose

To get Rose to recognise your STASHmaster file, you will need to make a number of changes:

  1. Point the um metadata to um-atmos/HEAD and edit Rose using rose edit -M /path/to/vn10.4_your_branch_name/rose-meta (you should already be doing this after following the instructions in the metadata section above.
  2. You need to open the $HOME/roses/[SUITE-ID]/app/um/rose-app.conf file in a text editor (e.g. vim, emacs, nedit etc.) and add the line STASHMSTR=STASHmaster inside the [env] block
  3. You need to open the $HOME/roses/[SUITE-ID]/rose-suite.conf file in a text editor and add the following lines at the top of the file:
[file:app/um/file/STASHmaster]
source=fcm:um.xm_br/dev/[your MOSRS userid]/vn10.4_your_branch_name/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@HEAD
You need to ensure that you have committed your STASHmaster_A changes, otherwise your new tracer(s) will not be seen on ARCHER during the reconfiguration or atmosphere steps.

At this point, a vn10.4 job (in fact, all Rose jobs prior to vn10.5) will be able to run and output these tracers. However, at vn10.6 the number of tracers was increased to 256, and when doing this extra checks were included that prevented jobs from running with s34 tracers turned on, but without UKCA using them. Because of this we will also include the UKCA changes now as well.

Initialise your new tracer(s)

Your new tracer(s) is a prognostic variable, as therefore the UM requires prior knowledge of the values it has to be able to run properly. To do this you need to go to um namelist Reconfiguration and Ancillary Control Configure ancils and initialise dump fields. Here you will see a list of fields. You can change the order of these by e.g. STASH number, as this often makes it easier to view.

To add new fields, right click anywhere within the table and click Add new section. This will make a new entry with index 1, if you add another entry, it will be given index 2 etc.. Right-click on this and click on View namelist:items(X) (where X is the index number). This will open a new tab where you can select the STASH section and item for the field you want to initialise using the drop-down menus. Some UKCA tracers need to be given full 3D initial conditions in ancillary file format. However, for this example we will initialise the tracer to a small number, . To do this, select the radio button for Set to a specified constant value and put 1.000000e-12 in the dialog box labelled user_prog_rconst at the bottom of the panel.

You will need to do this for each of the tracers you are adding. When you have finished, you will need to go to the STASH Requests panel (see the STASH tutorial) and run the TidyStashTransform macro to correctly generate the required index value for each tracer initialisation.

Output your new tracers

To output your tracers, go to the STASH panel and output your tracers as described in the What is STASH? tutorial.

Required UKCA Code Changes

ukca_set_nmspec.F90

Inside UKCA there is a master mapping array that tells the UKCA code which transported species are placed into a particular item number in section 34. At vn10.4 these are contained in the first 150 slots, and at vn10.6 these are in the first 256 slots.

This array is called nm_spec, and it can be found in ukca_set_nmspec.F90. At vn10.4, it looks like this:

nm_spec(1:a_max_ukcavars) = (/                                     &
'O3        ','NO        ','NO3       ','NO2       ','N2O5      ',  &
'HO2NO2    ','HONO2     ','H2O2      ','CH4       ','CO        ',  & !10
'HCHO      ','MeOOH     ','HONO      ','C2H6      ','EtOOH     ',  &
'MeCHO     ','PAN       ','C3H8      ','n-PrOOH   ','i-PrOOH   ',  & !20
'EtCHO     ','Me2CO     ','MeCOCH2OOH','PPAN      ','MeONO2    ',  &
'O3_S      ','C5H8      ','ISOOH     ','ISON      ','MACR      ',  & !30
'MACROOH   ','MPAN      ','HACET     ','MGLY      ','NALD      ',  &
'HCOOH     ','MeCO3H    ','MeCO2H    ','H2O       ','ISO2      ',  & !40
'Cl        ','ClO       ','Cl2O2     ','OClO      ','Br        ',  &
'BrO       ','BrCl      ','BrONO2    ','N2O       ','HCl       ',  & !50
'HOCl      ','HBr       ','HOBr      ','ClONO2    ','CFCl3     ',  &
'CF2Cl2    ','MeBr      ','N         ','O(3P)     ','MACRO2    ',  & !60
'MeCl      ','CF2ClBr   ','CCl4      ','CF2ClCFCl2','CHF2Cl    ',  &
'MeCCl3    ','CF3Br     ','H2OS      ','CH2Br2    ','H2        ',  & !70
'DMS       ','SO2       ','H2SO4     ','MSA       ','DMSO      ',  &
'NH3       ','CS2       ','COS       ','H2S       ','H         ',  & !80
'OH        ','HO2       ','MeOO      ','EtOO      ','MeCO3     ',  &
'n-PrOO    ','i-PrOO    ','EtCO3     ','MeCOCH2OO ','MeOH      ',  & !90
'Monoterp  ','Sec_Org   ','SESQUITERP','SO3       ','AROM      ',  &
'O(3P)_S   ','O(1D)_S   ','NO2       ','BrO       ','HCl       ',  & !100
'Nuc_SOL_ND','Nuc_SOL_SU','Ait_SOL_ND','Ait_SOL_SU','Ait_SOL_BC',  &
'Ait_SOL_OC','Acc_SOL_ND','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  & !110
'Acc_SOL_SS','Acc_SOL_DU','Cor_SOL_ND','Cor_SOL_SU','Cor_SOL_BC',  &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','Ait_INS_ND','Ait_INS_BC',  & !120
'Ait_INS_OC','Acc_INS_ND','Acc_INS_DU','Cor_INS_ND','Cor_INS_DU',  &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_SO','Ait_SOL_SO','Acc_SOL_SO',  & !130
'Cor_SOL_SO','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH',  &
'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX       ',  & !140
'Anth_Prec ','Bio_Prec  ','Anth_Cond ','Bio_Cond  ','XXX       ',  &
'XXX       ','XXX       ','XXX       ','PASSIVE O3','AGE OF AIR'   & !150
 /)

This array is case sensitive and each string is a fixed length of 10 characters, with the whitespace being made up of spaces and not another tpye of white space (e.g. tabs).

When adding new tracers you should not overwrite tracers that are already in use by the chemistry scheme that you are using (e.g. StratTrop etc.), and it is best to also take care and avoid tracers in use by other schemes, if possible. You can see the tracers used by each scheme by looking in the chch_defs array at the top of each ukca_chem_scheme.F90 (e.g. ukca_chem_strattrop.F90 etc.).

Here you should put a new species, 'ALICE     ', into tracer slot 64 (current specified as 'CF2ClCFCl2', which is not in use by any scheme at the moment).

Remember: You need to add 2 tracers, ALICE in s34i064 and BOB in s34i065.

ukca_chem_scheme.F90

We will go through changes that need to be made for the StratTrop chemistry scheme, but equivalent changes would need to be made for others, e.g. TropIsop or Strat.


In ukca_set_nmspec.F90:

nm_spec(1:a_max_ukcavars) = (/                                     &
'O3        ','NO        ','NO3       ','NO2       ','N2O5      ',  &
'HO2NO2    ','HONO2     ','H2O2      ','CH4       ','CO        ',  & !10
'HCHO      ','MeOOH     ','HONO      ','C2H6      ','EtOOH     ',  &
'MeCHO     ','PAN       ','C3H8      ','n-PrOOH   ','i-PrOOH   ',  & !20
'EtCHO     ','Me2CO     ','MeCOCH2OOH','PPAN      ','MeONO2    ',  &
'O3_S      ','C5H8      ','ISOOH     ','ISON      ','MACR      ',  & !30
'MACROOH   ','MPAN      ','HACET     ','MGLY      ','NALD      ',  &
'HCOOH     ','MeCO3H    ','MeCO2H    ','H2O       ','ISO2      ',  & !40
'Cl        ','ClO       ','Cl2O2     ','OClO      ','Br        ',  &
'BrO       ','BrCl      ','BrONO2    ','N2O       ','HCl       ',  & !50
'HOCl      ','HBr       ','HOBr      ','ClONO2    ','CFCl3     ',  &
'CF2Cl2    ','MeBr      ','N         ','O(3P)     ','MACRO2    ',  & !60
'MeCl      ','CF2ClBr   ','CCl4      ','CF2ClCFCl2','CHF2Cl    ',  &
'MeCCl3    ','CF3Br     ','H2OS      ','CH2Br2    ','H2        ',  & !70
'DMS       ','SO2       ','H2SO4     ','MSA       ','DMSO      ',  &
'NH3       ','CS2       ','COS       ','H2S       ','H         ',  & !80
'OH        ','HO2       ','MeOO      ','EtOO      ','MeCO3     ',  &
'n-PrOO    ','i-PrOO    ','EtCO3     ','MeCOCH2OO ','MeOH      ',  & !90
'Monoterp  ','Sec_Org   ','SESQUITERP','SO3       ','AROM      ',  &
'O(3P)_S   ','O(1D)_S   ','NO2       ','BrO       ','HCl       ',  & !100
'Nuc_SOL_ND','Nuc_SOL_SU','Ait_SOL_ND','Ait_SOL_SU','Ait_SOL_BC',  &
'Ait_SOL_OC','Acc_SOL_ND','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC',  & !110
'Acc_SOL_SS','Acc_SOL_DU','Cor_SOL_ND','Cor_SOL_SU','Cor_SOL_BC',  &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','Ait_INS_ND','Ait_INS_BC',  & !120
'Ait_INS_OC','Acc_INS_ND','Acc_INS_DU','Cor_INS_ND','Cor_INS_DU',  &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_SO','Ait_SOL_SO','Acc_SOL_SO',  & !130
'Cor_SOL_SO','Nuc_SOL_NH','Ait_SOL_NH','Acc_SOL_NH','Cor_SOL_NH',  &
'Nuc_SOL_NT','Ait_SOL_NT','Acc_SOL_NT','Cor_SOL_NT','XXX       ',  & !140
'Anth_Prec ','Bio_Prec  ','Anth_Cond ','Bio_Cond  ','XXX       ',  &
'XXX       ','XXX       ','XXX       ','PASSIVE O3','AGE OF AIR'   & !150
 /)

See section 2.1 ("UKCA specific option codes") in UMDP084. NR StratTrop is n5

Make a ticket and a branch, then merge-in fcm:um.x_br/dev/lukeabraham/vn10.4_ga7_meta@28589 then call rose from within the suite directory:

cd $HOME/roses/[SUITE-ID]
rose edit -M /full/path/to/vn10.4_branch/rose-meta &
e.g.
    rose edit -M /home/luke/FCM/vn10.4/vn10.4_UKCA_Tutorials/rose-meta &

then click on um and edit the meta box to point to um-atmos/HEAD

Make changes to include STASHmaster_A edits for ALICE & BOB. Click "refresh metadata". Can now select tracers in STASH.

Commit your STASH changes to your fcm branch (keeping note of the revision number [REVISION]), then edit the app/um/rose-app.conf file as follows:

  1. Add STASHMSTR=STASHmaster at the end of the [env] block
  2. After the [file:foo] lines, add the following:
[file:STASHmaster]
source=fcm:um.xm_br/dev/[YOUR MOSRS USERID]/[YOUR BRANCH NAME]/rose-meta/um-atmos/HEAD/etc/stash/STASHmaster@[REVISION]


Add requests to initialisation panel & initialise to 1.000000e-12

Time for fcm_make2_um = ~00:18:30

See u-ag308@21785


Now you can add ALICE & BOB to ukca_chem_strattrop.F90. Add to both chch_defs_strattrop_chem & chch_defs_strattrop_aer.

Then increment jpctr and jpspec in ukca_setup_chem.F90 by 2 each.

Increment n_chem_tracers in ukca_setd1defs.F90 at each ELSE IF (L_ukca_strattrop code block

Now add pressure-level output of ALICE & BOB.

0    : 192   144   36    1     O3 MASS MIXING RATIO
1    : 192   144   36    1     Molar flux density
2    : 192   144   85    1     O3 MASS MIXING RATIO
3    : 192   144   85    1     Field code =  2164
4    : 192   144   85    1     Field code =  2165



Written by Luke Abraham 2016