UKCA & UMUI Tutorial 4
Adding new chemical tracers
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. While you may think that you should start this by editing the UKCA code, in fact you should first adapt the UM and the UMUI so that it knows that these new tracers exist. Once you have created them you can then edit the UKCA code to use them to transport chemical species around.
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_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_tr@vn8.2
before checking-out your branch by
fcm checkout fcm:um_br/dev/userid/vn8.2_your_branch_name
More information on FCM can be found at the NCAS-CMS FCM pages.
During this tutorial you will be tasked to add in two new tracers into your UM branch.
1. Adding a tracer into the UMUI
Pick a free UKCA tracer slot
The UM has 150 tracers available for use by UKCA in STASH section 34. The first 100 of these are chemical tracers, which may (or may not) be in use by the various schemes that are currently available. The last 101-150 are reserved for aerosol and diagnostic tracers. You should therefore ensure that the tracers that you add are in one of the 1-100 slots, although many of these slots will already be in use by the scheme that you are using.
To choose the correct slot(s), you should first examine the nm_spec array which is in the ukca_setd1defs.F90 routine. To do this, cd into
vn8.2_your_branch/src/atmosphere/UKCA
and view the ukca_setd1defs.F90 file. This will give the following for the nm_spec array which is found around line 360:
IF (L_UKCA_RAQ) THEN
!This list of tracers is valid for the RAQ chemistry.
!If MODE aerosols are used with it but their positions
!change in the array then the list needs to be updated.
nm_spec(1:n_all_tracers) = (/ &
'O3 ','NO ','NO3 ','NO2 ','N2O5 ', &
'HO2NO2 ','HONO2 ','H2O2 ','CH4 ','CO ', &
'HCHO ','MeOOH ','HONO ','C2H6 ','ETOOH ', &
'MeCHO ','PAN ','C3H8 ','N-PrOOH ','I-PrOOH ', &
'EtCHO ','Me2CO ','MeCOCH2OOH','PPAN ','MeONO2 ', &
'O3S ','C5H8 ','ISOOH ','ISON ','MACR ', &
'MACROOH ','MPAN ','HACET ','MGLY ','NALD ', &
'HCOOH ','MeCO3H ','MeCO2H ','MVK ','MVKOOH ', &
'Cl ','ClO ','Cl2O2 ','OClO ','Br ', &
'BrO ','BrCl ','BrONO2 ','N2O ','HCl ', &
'HOCl ','HBr ','HOBr ','ClONO2 ','CFCl3 ', &
'CF2Cl2 ','MeBr ','N ','O(3P) ','ORGNIT ', &
'MeCl ','CF2ClBr ','CCl4 ','CF2ClCFCl2','CHF2Cl ', &
'MeCCl3 ','CF3Br ','H2OS ','CH3OH ','H2 ', &
'SO2 ','H2SO4 ','DMS ','MSA ','DMSO ', &
'NH3 ','CS2 ','COS ','H2S ','H ', &
'OH ','HO2 ','MeOO ','EtOO ','MeCO3 ', &
'n-PrOO ','i-PrOO ','EtCO3 ','MeCOCH2OO ','RNC2H4 ', &
'RNC3H6 ','C2H4 ','C3H6 ','C4H10 ','C4H9OOH ', &
'MEK ','TOLUENE ','MEMALD ','GLYOXAL ','oXYLENE ', &
'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC', &
'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC', &
'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC', &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC', &
'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du', &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ', &
'Cor_SOL_OZ','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 ', &
'Dust_Div_1','Dust_Div_2','Dust_Div_3','Dust_Div_4','Dust_Div_5', &
'Dust_Div_6','Rn-222 ','Pb-210 ','XXX ','XXX ' &
/)
ELSE
! Tracers 98,99 & 100 are for lumped Nitrogen, Br and Cl for stratospheric chemistry,
! but can only be renamed in STASHmaster file not in advt or nm_spec.
nm_spec(1:n_all_tracers) = (/ &
'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
'ND_Nuc_SOL','Nuc_SOL_SU','ND_Ait_SOL','Ait_SOL_SU','Ait_SOL_BC', &
'Ait_SOL_OC','ND_Acc_SOL','Acc_SOL_SU','Acc_SOL_BC','Acc_SOL_OC', & !110
'Acc_SOL_SS','Acc_SOL_DU','ND_Cor_SOL','Cor_SOL_SU','Cor_SOL_BC', &
'Cor_SOL_OC','Cor_SOL_SS','Cor_SOL_DU','ND_Ait_INS','Ait_INS_BC', & !120
'Ait_INS_OC','ND_Acc_INS','Acc_INS_DU','ND_Cor_INS','Cor_INS_Du', &
'Nuc_SOL_OC','Ait_SOL_SS','Nuc_SOL_OZ','Ait_SOL_OZ','Acc_SOL_OZ', & !130
'Cor_SOL_OZ','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
/)
END IF
! Mode components: Su: sulphate, BC: black carbon, OC: organic carbon
! SS: sea-salt, Du: dust, OZ: organic carbon 2
! NH: ammonium, NT: nitrate, ND: number density
The settings in the UMUI UKCA panel will tell you whether you are using the RAQ chemistry or not (in this tutorial you are not). If you look through the ukca_chem_scheme.F90 file (e.g. ukca_chem_strattrop.F90) then you will see a list of the species that you are using.
We can relate this back to the nm_spec array above. The following section of that array gives the CheST/StratTrop chemical species in black. Red species are either used by the aerosol chemistry or should be avoided, and species in green are not currently used by any scheme and so can be over-written.
'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
You should pick one of the green slots (although if you are adding more than 13 new tracers and you know that you will not need any of the red ones, these can also be used. In the future the number of UKCA tracers will be extended.
In this example we will over-write tracer number 65 (CHF2Cl).
Edit your user STASHmaster file
In your UMUI job go to Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. This will contain a listing of the full path to a file that describes the UKCA tracers that you are using (in this tutorial it is called UKCA_Tr_StratTrop.prestash). Take a copy (using cp) of this file to your local directory on PUMA. If you open this file you will see that each tracer has a listing which looks like
# 1| 1 | 34 | 1 |O3 MASS MIXING RATIO AFTER TIMESTEP | 2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 | 3| 000000000000000000000000000001 | 00000000000000000001 | 1 | 4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 | 5| 0 | 1861 | 0 | 65 | 0 | 0 | 0 | 0 | 0 | #
Each of the areas coloured in red above is unique to each tracer, i.e. the name of the tracer and the number of the tracer. Since we are over-writing tracer 65, you would make a new entry in the STASHmaster file which reads
# 1| 1 | 34 | 65 |MY TRACERS NAME | 2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 | 3| 000000000000000000000000000065 | 00000000000000000001 | 1 | 4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 | 5| 0 | 1861 | 0 | 65 | 0 | 0 | 0 | 0 | 0 | #
Note: the spacing of the pipes (|) in this file is important, so be careful not to change this.
Now, in the Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. panel replace the original user STASHmaster file with your new one containing the additional tracer(s).
Initialise your tracer(s)
Now you need to initialise your tracer. By placing it in a STASHmaster file which the UM reads, as a tracer is a prognostic field, it will need to be initialised to a value in the model start dump (which is done by the reconfiguration step). To set this go to Model Selection → Atmosphere → STASH → Initialisation of User Prognostics. This will open a panel containing a table listing all the STASH items listed in all your STASHmaster files. Scroll down this list until you get to your new tracer. While the STASH number and name of the tracer (which you set in your STASHmaster file) is present, all other columns will be blank.
The simplest options are either to set the Option column to 3 (which sets the field to zero) or to 6 and then give a value to set the field to in the If 6: CONSTANT column. In either case this will set every single gridcell to be the same value. You can, if needed, make up an ancillary file containing an initial condition (option 7) if you required there to be spatial variation in your field (e.g. the ukca ozone field must always be initialised to an approximate initial condition in this way). This can be done using Xancil. Xancil will be covered in more detail in the adding new emissions tutorial. If these fields existed in the start dump you are providing then you could set this option to 1.
Tell the UMUI about your new tracer
Unfortunately you cannot edit the UMUI directly to add-in your new tracer(s), and instead you must use a hand-edit. This is a script which run when you click the Process button, and what it does is to directly make changes to one or more of the scripts that is held in your $HOME/umui_jobs/jobid directory (you can think of the UMUI as making indirect changes), and it is these scripts which are copied across to the supercomputer when you click Submit.
If you go to your $HOME/umui_jobs/jobid directory and view the SIZES script, you will see that it contains entries similar to, e.g.
TR_UKCA=72,
and
TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1,
TR_UKCA is the number of UKCA tracers, and TC_UKCA is a list of which tracers are on or not (1 being on, 0 being off). If, in this example, you were to go through the TC_UKCA list and add-up all the 1s you would find that they add-up to 72, and that you would only have a 1 where you have a corresponding number in the user STASHmaster file. Of these 72, two of them (numbers 149 and 150) are diagnostic tracers and are not considered by the chemistry scheme itself. Also, the H2O field used by UKCA comes from the UM's specific humidity field.
You will need to make up a new list. However, rather than you having to put the 1 in the correct place by hand (not easy to do!), there is the make_tracer_list script on PUMA which is located in
/home/ukca/bin/make_tracer_list
This script is run on a STASHmaster file. If this script is run on the edited user STASHmaster file (which has tracer 65 included) the output is
$ make_tracer_list UKCA_Tr_StratTrop.prestash TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1, TR_UKCA=73,
(with the changes from before highlighted in blue). You will now need to add this data into the SIZES script using a hand-edit.
Hand-edits use the ed text editor, which can be run in a batch mode. We will need to make a script (e.g. add_UKCA_Tr_StratTrop.ed) which contains the following
ed SIZES<<\EOF /TC_UKCA=/ d d d d d i TC_UKCA=1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,0,1,1,1,0,1,1,1,1,1,1,1,1,1,1,0,0,0, 0,1,0,0,0,0,1,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,1,1,1,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,1,1, . w q EOF ed SIZES<<\EOF /TR_UKCA=/ d i TR_UKCA=73, . w q EOF
The first block tells ed to search for the line TC_UKCA= and the delete this line and the next 4 lines, before inserting the text (i.e. this replaces the block in SIZES with the text here). The second block does the same but for the TR_UKCA value, hence only needed to delete 1 line.
You will need to make this file executable so that the UM can run it. To do this, in the directory where the file exists do
chmod a+rx add_UKCA_Tr_StratTrop.ed
Now, in the UMUI we go to Model Selection → Input/Output Control and Resource → User hand edit files. Put the full path to this file at the end of the list in the table and put a Y in the Include Y/N column.
Task 4.1: Make slots for two new tracers
TASK4.1: Add in two new tracers in to slots 64 and 65. The tracer in slot 64 will be called ALICE and the tracer in slot 65 will be called BOB. You should also output these two tracers through the pb/UPB stream in STASH as daily means.
Note: If you were unable to successfully complete Task 3.1, then please take a copy of the b job from the Tutorial experiment (Tutorial: solution to Task 3.1 - outputting a diagnostic) and work from there, as this will allow you to only make the changes required for this task.
Remember: If you are using MONSooN you will need to delete/move any existing output files in your archive directory.
Adding new a new chemical tracer to UKCA
Now that you have created the new tracer(s) in the UM/UMUI, you can then tell UKCA to use this tracer slot to transport round a chemical species. To do this you will need to edit the UKCA source code.
FCM branches and merging
Before we can do this we need to check and see if there are any possible conflicts that may arise by making these changes. If you go to the FCM Atmosphere panel at Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration you can view the current branches used by this job, e.g.:
fcm:um_br/dev/odarbysh/VN8.2_reinstate_ISCCP/src 9617 Y fcm:um_br/pkg/Config/VN8.2_GlobalAtmos4p0/src 9630 Y fcm:um_br/dev/odarbysh/VN8.2_qpos_col_fix/src 9619 Y fcm:um_br/dev/nhsavage/vn8.2_pkg_ukca_bugfixes/src 9882 Y fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src 9984 Y fcm:um_br/dev/jeff/VN8.2_hector_monsoon_archiving/src Y fcm:um_br/dev/luke/vn8.2_RCP_scenario/src 12080 Y fcm:um_br/pkg/Config/vn8.2_ncas/src Y fcm:um_br/dev/luke/vn8.2_UKCA_HECToR_cce_Fixes/src 12133 Y
Most of these branches will not clash with our required changes. However, the fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src branch will, as it directly changes parts of the chemistry scheme routines that we want to use. Before we can make our code changes we must first make a copy of this branch. While ideally you should be able to make a new branch and edit the source-code as is, often you need to make changes to an existing branch. The recommended way to do this is to make a new branch and then merge in the clashing branch with your own, then stop using the clashing branch in the UMUI.
You should already have made a new branch that you used to find the free tracer slots. Now cd into the highest-level directory of the branch, which contains
CodeOwners.txt COPYRIGHT.txt src/
From here you will need to merge in the vn8.2_ukca_update_rate_coeffs branch. Do
fcm merge fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src
You will then be asked to confirm the revision number (the latest, 9984, is the one used in the UMUI). Confirm by pressing return. Now you will be asked if you wish to go ahead with the merge. Confirm this by typing y and pressing return. This will now merge in all the changes from the UM trunk that the vn8.2_ukca_update_rate_coeffs contains into your branch.
In the terminal, this will have the following output:
$ fcm merge fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src Eligible merge(s) from /UM/branches/dev/foconnor/vn8.2_ukca_update_rate_coeffs@12142: 9984 9983 9982 9981 9980 9979 Enter a revision (or just press <return> for "9984"): -------------------------------------------------------------------------------- Merge: /UM/branches/dev/foconnor/vn8.2_ukca_update_rate_coeffs@9984 c.f.: /UM/trunk@9602 -------------------------------------------------------------------------dry-run --- Merging r9603 through r9984 into '.': U src/atmosphere/UKCA/asad_flux_dat.F90 U src/atmosphere/UKCA/asad_bimol.F90 U src/atmosphere/UKCA/asad_trimol.F90 U src/atmosphere/UKCA/ukca_chem_strattrop.F90 -------------------------------------------------------------------------dry-run Would you like to go ahead with the merge? Enter "y" or "n" (or just press <return> for "n"): y Merge succeeded.
Now if you type fcm status you can see which routines have been changed:
$ fcm status M src/atmosphere/UKCA/asad_flux_dat.F90 M src/atmosphere/UKCA/asad_bimol.F90 M src/atmosphere/UKCA/asad_trimol.F90 M src/atmosphere/UKCA/ukca_chem_strattrop.F90
Before you make any further changes you should commit these changes. Do this now by typing the command
fcm commit
press return and put in an appropriate comment when asked if you want to commit this branch and type y and then press return again.
Now you need to add this branch into the UMUI, and turn off the original vn8.2_ukca_update_rate_coeffs branch. We will initially use a working copy.
- Go to the Model Selection → FCM Configuration → FCM Options for Atmosphere and Reconfiguration' panel, scroll down the table and change the Y next to the fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src branch to N.
- Add your own branch to this table. The revision URL will be off the form
fcm:um_br/dev/your PUMA username/vn8.2_your_branch_name/src
Leave the revision number column empty and put a N in the Use Y/N column. - Turn on the button which says Include modifications from a user working copy and put the path to your source directory on PUMA in this box (e.g. something like /home/your PUMA username/.../vn8.2_your_branch_name/src etc.). Once we are happy that this code is working we can turn off the option to run from this copy, and turn on the option to run from the respository.
Using a working copy means that FCM will pick up any changes that you have made to your branch without you needed to fcm commit it. However, frequent committing of code to the FCM respository is encouraged. You don't even need to commit working code, as committing is a useful way of backing-up code changes.
Note: In general, you may, or may not, need to do this step. It is possible that you can make your edits on a fresh branch which contains only the UM trunk. However, it is likely that you will have conflicts of a sort with an existing branch.
Editing the advected tracer list
To edit the UKCA source code, go to your branch and cd into
src/atmosphere/UKCA/
This directory contains the majority of the UKCA specfic code, and contains over 200 files.
When we found which tracer slot to use, we did so consulting the nm_spec array in the ukca_setd1defs.F90 routine. You should open this file and edit the nm_spec array so that the slot you have chosen now contains the name of your tracer. The nm_spec array tells UKCA what slot in the 150 reserved tracers is used for which transported chemical species.
Note: remember that this name is case sensitive, and be wary of tabs as these should not be used in Fortran programs. Also remember that the string length for a UKCA species is 10 characters.
Increase the number of tracers to be used
Also in ukca_setd1defs.F90 you will find code blocks which set values for various parameters depending on the scheme used. In this example you will need to scroll down to the section which defines the CheST/StratTrop chemistry, which is located in the Stratospheric Chemistry section. In the IF block which uses L_ukca_strattrop you will find the following line
n_chem_tracers = 71 ! No chem tracers
You should increase this number by the number of tracers that you are adding. If you are adding to a different chemistry scheme then you will need to make those changes accordingly.
Note: You will find that this number may be different than that specified in the value of TR_UKCA which is set in the SIZES script. This is due to two reasons. The first is that there can be diagnostic tracers in section 34 (e.g. Age of Air, or Passive O3) which will appear in SIZES but not in the value of n_chem_tracers in ukca_setd1defs.F90. The second is that the UKCA H2O field is advected in section 0 and not section 34, and so will need to be included in ukca_setd1defs.F90, but is not needed in SIZES.
Editing the Chemistry Scheme Specification
For this example we are using the CheST/StratTrop chemistry scheme, so we will need to edit the specification of this scheme so that it knows that it is using new tracer(s). The chemistry schemes are specified in the files called ukca_chem_scheme.F90. So we should open the file called ukca_chem_strattrop.F90.
The UKCA chemistry schemes are held within Fortran modules and are defined by different derived types which hold the specification of the different components required to describe the scheme. Looking through this file you will find two blocks which hold the different species used, called chch_defs_strattrop_chem (which is used when you are running chemistry-only) and chch_defs_strattrop_aer (which is used when you are running with the CLOMAP-mode aerosol scheme coupled to the chemistry). As we are currently using chemistry only, we will only need to edit the chch_defs_strattrop_chem specification. This currently looks like
TYPE(CHCH_T), DIMENSION( 75), PUBLIC :: chch_defs_strattrop_chem=(/ & chch_t( 1,'O(3P) ', 1,'TR ','Ox ', 0, 0, 0), & ! 1 chch_t( 2,'O(1D) ', 1,'SS ','Ox ', 0, 0, 0), & ! 2 chch_t( 3,'O3 ', 1,'TR ','Ox ', 1, 0, 0), & ! 3 DD: 1, chch_t( 4,'N ', 1,'TR ','NOx ', 0, 0, 0), & ! 4 chch_t( 5,'NO ', 1,'TR ','NOx ', 1, 0, 0), & ! 5 DD: 2, chch_t( 6,'NO3 ', 1,'TR ','NOx ', 1, 1, 0), & ! 6 DD: 3,WD: 1, chch_t( 7,'NO2 ', 1,'TR ','NOx ', 1, 0, 1), & ! 7 DD: 4, EM: 1 chch_t( 8,'N2O5 ', 1,'TR ',' ', 1, 1, 0), & ! 8 DD: 5,WD: 2, chch_t( 9,'HO2NO2 ', 1,'TR ',' ', 1, 1, 0), & ! 9 DD: 6,WD: 3, chch_t( 10,'HONO2 ', 1,'TR ',' ', 1, 1, 0), & ! 10 DD: 7,WD: 4, chch_t( 11,'H2O2 ', 1,'TR ',' ', 1, 1, 0), & ! 11 DD: 8,WD: 5, chch_t( 12,'CH4 ', 1,'TR ',' ', 0, 0, 2), & ! 12 EM: 2 chch_t( 13,'CO ', 1,'TR ',' ', 1, 0, 3), & ! 13 DD: 9, EM: 3 chch_t( 14,'HCHO ', 1,'TR ',' ', 1, 1, 4), & ! 14 DD:10,WD: 6,EM: 4 chch_t( 15,'MeOO ', 1,'TR ',' ', 0, 1, 0), & ! 15 WD: 7, chch_t( 16,'MeOOH ', 1,'TR ',' ', 1, 1, 0), & ! 16 DD:11,WD: 8, chch_t( 17,'H ', 1,'TR ','HOx ', 0, 0, 0), & ! 17 chch_t( 18,'H2O ', 1,'TR ',' ', 0, 0, 0), & ! 18 chch_t( 19,'OH ', 1,'TR ','HOx ', 0, 0, 0), & ! 19 chch_t( 20,'HO2 ', 1,'TR ','HOx ', 0, 1, 0), & ! 20 WD: 9, chch_t( 21,'Cl ', 1,'TR ','Clx ', 0, 0, 0), & ! 21 chch_t( 22,'Cl2O2 ', 1,'TR ','Clx ', 0, 0, 0), & ! 22 chch_t( 23,'ClO ', 1,'TR ','Clx ', 0, 0, 0), & ! 23 chch_t( 24,'OClO ', 1,'TR ',' ', 0, 0, 0), & ! 24 chch_t( 25,'Br ', 1,'TR ','Brx ', 0, 0, 0), & ! 25 chch_t( 26,'BrO ', 1,'TR ','Brx ', 0, 0, 0), & ! 26 chch_t( 27,'BrCl ', 1,'TR ',' ', 0, 0, 0), & ! 27 chch_t( 28,'BrONO2 ', 1,'TR ',' ', 0, 1, 0), & ! 28 WD:10, chch_t( 29,'N2O ', 1,'TR ',' ', 0, 0, 0), & ! 29 chch_t( 30,'HCl ', 1,'TR ',' ', 1, 1, 0), & ! 30 DD:12,WD:11, chch_t( 31,'HOCl ', 1,'TR ',' ', 1, 1, 0), & ! 31 DD:13,WD:12, chch_t( 32,'HBr ', 1,'TR ',' ', 1, 1, 0), & ! 32 DD:14,WD:13, chch_t( 33,'HOBr ', 1,'TR ',' ', 1, 1, 0), & ! 33 DD:15,WD:14, chch_t( 34,'ClONO2 ', 1,'TR ',' ', 0, 1, 0), & ! 34 WD:15, chch_t( 35,'CFCl3 ', 1,'TR ',' ', 0, 0, 0), & ! 35 chch_t( 36,'CF2Cl2 ', 1,'TR ',' ', 0, 0, 0), & ! 36 chch_t( 37,'MeBr ', 1,'TR ',' ', 0, 0, 0), & ! 37 chch_t( 38,'HONO ', 1,'TR ',' ', 1, 1, 0), & ! 38 DD:16,WD:16, chch_t( 39,'C2H6 ', 1,'TR ',' ', 0, 0, 1), & ! 39 EM: 5 chch_t( 40,'EtOO ', 1,'TR ',' ', 0, 0, 0), & ! 40 chch_t( 41,'EtOOH ', 1,'TR ',' ', 1, 1, 0), & ! 41 DD:17,WD: 17, chch_t( 42,'MeCHO ', 1,'TR ',' ', 1, 0, 1), & ! 42 DD:18, EM: 6 chch_t( 43,'MeCO3 ', 1,'TR ',' ', 0, 0, 0), & ! 43 chch_t( 44,'PAN ', 1,'TR ',' ', 1, 0, 0), & ! 44 DD:19, chch_t( 45,'C3H8 ', 1,'TR ',' ', 0, 0, 1), & ! 45 EM: 7 chch_t( 46,'n-PrOO ', 1,'TR ',' ', 0, 0, 0), & ! 46 chch_t( 47,'i-PrOO ', 1,'TR ',' ', 0, 0, 0), & ! 47 chch_t( 48,'n-PrOOH ', 1,'TR ',' ', 1, 1, 0), & ! 48 DD:20,WD:18, chch_t( 49,'i-PrOOH ', 1,'TR ',' ', 1, 1, 0), & ! 49 DD:21,WD:19, chch_t( 50,'EtCHO ', 1,'TR ',' ', 1, 0, 0), & ! 50 DD:22, chch_t( 51,'EtCO3 ', 1,'TR ',' ', 0, 0, 0), & ! 51 chch_t( 52,'Me2CO ', 1,'TR ',' ', 0, 0, 1), & ! 52 EM: 8 chch_t( 53,'MeCOCH2OO ', 1,'TR ',' ', 0, 0, 0), & ! 53 chch_t( 54,'MeCOCH2OOH', 1,'TR ',' ', 1, 1, 0), & ! 54 DD:23,WD:20, chch_t( 55,'PPAN ', 1,'TR ',' ', 1, 0, 0), & ! 55 DD:24, chch_t( 56,'MeONO2 ', 1,'TR ',' ', 0, 0, 0), & ! 56 chch_t( 57,'C5H8 ', 1,'TR ',' ', 0, 0, 1), & ! 57 EM: 9 chch_t( 58,'ISO2 ', 1,'TR ',' ', 0, 0, 0), & ! 58 chch_t( 59,'ISOOH ', 1,'TR ',' ', 1, 1, 0), & ! 59 DD:25,WD:21, chch_t( 60,'ISON ', 1,'TR ',' ', 1, 1, 0), & ! 60 DD:26,WD:22, chch_t( 61,'MACR ', 1,'TR ',' ', 1, 0, 0), & ! 61 DD:27, chch_t( 62,'MACRO2 ', 1,'TR ',' ', 0, 0, 0), & ! 62 chch_t( 63,'MACROOH ', 1,'TR ',' ', 1, 1, 0), & ! 63 DD:28,WD:23, chch_t( 64,'MPAN ', 1,'TR ',' ', 1, 0, 0), & ! 64 DD:29, chch_t( 65,'HACET ', 1,'TR ',' ', 1, 1, 0), & ! 65 DD:30,WD:24, chch_t( 66,'MGLY ', 1,'TR ',' ', 1, 1, 0), & ! 66 DD:31,WD:25, chch_t( 67,'NALD ', 1,'TR ',' ', 1, 0, 0), & ! 67 DD:32, chch_t( 68,'HCOOH ', 1,'TR ',' ', 1, 1, 0), & ! 68 DD:33,WD:26, chch_t( 69,'MeCO3H ', 1,'TR ',' ', 1, 1, 0), & ! 69 DD:34,WD:27, chch_t( 70,'MeCO2H ', 1,'TR ',' ', 1, 1, 0), & ! 70 DD:35,WD:28, chch_t( 71,'H2 ', 1,'TR ',' ', 0, 0, 0), & ! 71 chch_t( 72,'MeOH ', 1,'TR ',' ', 1, 1, 0), & ! 72 DD:36,WD:29, chch_t( 73,'CO2 ', 1,'CT ',' ', 0, 0, 0), & ! 73 chch_t( 74,'O2 ', 1,'CT ',' ', 0, 0, 0), & ! 74 chch_t( 75,'N2 ', 1,'CT ',' ', 0, 0, 0) & ! 75 /)
You should note that even though there are 71 chemical tracers defined, there are actually 75 species considered in this scheme, as three (CO2, O2, and N2) are constants and O(1D) is set to be in steady-state and is not transported. This is set in the 4th column of the list:
- TR = tracer
- CT = constant
- SS = steady state
The 6th and 7th columns of the list control dry and wet deposition respectively. We will cover these in more detail in the adding dry deposition of chemical species and adding wet deposition of chemical species tutorials.
You should edit this list, adding the name your tracer(s) (exactly as it is called in the nm_spec array) on at the end (remember the comma on the last line!). Make sure that the last 3 columns are all set to 0. Also remember to increase the size of the chch_defs_strattrop_chem array by the number of species that you are adding.
Define conversion factors for your new tracers
The unit of the tracers is kg(species)/kg(air) (i.e. mass mixing ratio, or mmr), but inside UKCA these species are converted to volume mixing ratio (or vmr). To enable UKCA to do this you will need to add the conversion factor(s) for your new tracer(s) into the code. This is done in the ukca_constants.F90 module (Note: in UM7.3 this is done in the c_v_m.h include file).
Open this file and add the required conversion factor(s). The naming convention for these is M_species is the molecular mass of the new species in g/mol, and C_species for the converson factor from vmr to mmr (calculated as M_species/M_air, where M_air=28.97). In actuality, only the C_species listing is always required, although you may need to add the M_species value later if you are emitting into the new species that you are adding.
Tell UKCA to use these conversion factors
After you have added these in, you will need to tell UKCA to use them for your species. To do this you need to edit the ukca_cspecies.F90 module, which contains code which contructs the c_species array of conversion factors for the advected tracers. This contains a subroutine called UKCA_CALC_CSPECIES which has a long block of code that contains entries like these:
...
WHERE (advt == 'MEMALD ') c_species = c_memald
WHERE (advt == 'MVK ') c_species = c_mvk
WHERE (advt == 'MVKOOH ') c_species = c_mvkooh
WHERE (advt == 'TOLUENE ') c_species = c_toluene
...
The advt array is automatically generated by UKCA at run-time from the CHCH chemistry scheme definition you edited earlier, so your new tracer(s) will exist within it. You need to add in a new line for each of your tracers which sets the value of the c_species array to your individual C_species parameter. Add the line(s) in at the end of block.
Increase the size of JPCTR and JPSPEC
As you have changed the number of chemical species, you will need to increase the size of two integer parameters that tell UKCA how many chemical species and how many chemical tracers it should consider.
- JPSPEC is the number of chemical species used in UKCA (effectively the size of chch_defs_strattrop_chem)
- JPCTR is the number of chemical tracers used in UKCA (always less-than or equal-to JPSPEC, effectively the number TR in chch_defs_strattrop_chem, or the new value of n_chem_tracers that you set in ukca_setd1defs.F90)
These are currently set automatically by the UMUI (depending on which chemistry scheme you choose). As this cannot be edited from within the UMUI you will need to make a hand-edit to change it. The values of JPSPEC and JPCTR are set in CNTLATM. Your hand-edit should contain a block similar to the following:
ed CNTLATM<<\EOF /JPCTR/ d i JPCTR = value of n_chem_tracers, . /JPSPEC/ d i JPSPEC = new size of chch_defs_strattrop_chem array, . w q EOF
Save this hand-edit and make it executable, and place it in the table in Model Selection → Input/Output Control and Resource → User hand edit files with a Y in the Include Y/N column.
Task 4.2: Add these two new tracers to UKCA
TASK4.2: Make the required code changes so that your ALICE and BOB tracers are now specified in the UKCA CheST/StratTrop scheme. You should set the conversion factor for each of these to 1.0.
Note: If you were unable to successfully complete Task 4.1 above, then please take a copy of the c job from the Tutorial experiment (Tutorial: solution to Task 4.1 - adding new chemical tracers to the UMUI) and work from there, as this will allow you to only make the changes required for this task.
Remember: If you are using MONSooN you will need to delete/move any existing output files in your archive directory.
Written by Luke Abraham 2013
