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.
1. Adding a tracer into the UMUI
1. 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. The following list 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).
2. 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 a file that describes the UKCA tracers that you are using, in this tutorial it is called UKCA_Tr_StratTrop.prestash. Take a copy of this file to your local direcory 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 | #