Difference between revisions of "UKCA Chemistry and Aerosol Tutorial 5"

From UKCA
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[UKCA Chemistry and Aerosol Tutorials | Back to UKCA Chemistry and Aerosol Tutorials]]
 
[[UKCA Chemistry and Aerosol Tutorials | Back to UKCA Chemistry and Aerosol Tutorials]]
   
==What you will do in this tutorial==
+
==What you will learn in this Tutorial==
   
In this tutorial you will learn how to make the required changes in the UMUI and in UKCA to include new chemical tracers (although the UMUI steps also count when adding new aerosol or passive tracers). As you learn how to do this you will add two new tracers to the UKCA tutorial job you have already been running.
+
During this tutorial you will learn how to make new UM ancillary files. Then you will learn how to add new emissions into UKCA so that they emit into one of your new tracers.
   
  +
At the end of the [[UKCA Chemistry and Aerosol Tutorial 4 | previous tutorial]] you will now know how to create new tracers for use by UKCA. However, after completing the tasks, your tracers will still be empty, as nothing has been put into them. This tutorial will teach you how to create an emissions ancillary file that the UM will read, and that you can then tell UKCA to use and emit into your tracer(s).
You will first learn how to make new tracers in the UMUI, before learning how to then use these tracers in UKCA.
 
   
  +
This tutorial will go through the steps needed to make an emission into a tracer which UKCA does not currently emit into. The steps in making the ancillary file will be the same for a species which is currently emitted into, although in this simplier case you would not need to make any code changes.
==Task 5.1: Make slots for two new tracers==
 
   
  +
During this tutorial you will be tasked with making a new emissions ancillary file, and add the emissions contained within it into one of your new tracers.
<span style="color:green">'''TASK5.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.</span>
 
   
  +
==Task 5.1: Create a new emissions file and use it in your job==
'''Note:''' If you were unable to successfully complete [[UKCA & UMUI Tutorial 3#Task 3.1:_add_new_output | 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.
 
   
  +
<span style="color:green">'''Task 5.1:''' In the <pre>/work/n02/n02/ukca/Tutorial/vn8.4/Task5.1</pre> directory on ARCHER, or the <strike><pre>/projects/ukca/Tutorial/vn8.4/Task5.1</pre></strike> directory on MONSooN, there is the file '''Emissions_of_ALICE.nc''' which is a 0.5x0.5 degree resolution surface emission field. You should regrid this file to '''N96''', and then make a new surface emissions ancillary file with this as slot '''316'''. You should then use this new file, and the corresponding user STASHmaster file, in your UMUI job.</span>
==Adding new chemical tracers==
 
   
  +
'''Note:''' If you were unable to successfully complete [[UKCA Chemistry and Aerosol Tutorial 4#Task_4.2: Add these two new tracers to UKCA | Task 4.2]], then please take a copy of the '''d''' job from the Tutorial experiment (''Tutorial: solution to Task 4.2 - adding new chemical tracers to UKCA'') and work from there, as this will allow you to make only the changes required for this task. Please also make a new branch and merge-in branch '''fcm:um_br/dev/luke/vn8.4_UKCA_Tutorial_Solns''' at revision number '''14692''' to allow you to proceed.
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.
 
   
  +
==Part 1. Making a new Emissions Ancillary File==
<span style="color:green">'''For this tutorial you will need to make a new branch in the usual way. You should do this now.'''</span>
 
   
  +
The UM uses its own format to read-in initial and emissions data, the ''ancillary file''. UKCA makes use of these files for the surface and aircraft emissions, and these files can easily be made up from netCDF data using the [http://cms.ncas.ac.uk/documents/xancil/ Xancil] program. However, before we can use Xancil to create our emissions ancillary, we may first need to use [http://badc.nerc.ac.uk/help/software/xconv/ Xconv] to regrid the raw data to the correct resolution of the UM configuration that you are using.
You will have learned how to make UM branches in the NCAS-CMS [https://puma.nerc.ac.uk/trac/UM_TUTORIAL FCM Tutorial]. However, now you should use <span style="color:red">um_tr</span> as the source of your branch.
 
   
  +
===Regridding data with Xconv===
For example, first you should make a ticket on the [https://puma.nerc.ac.uk/trac/UM/newticket UM Trac pages] (login required) and then make the branch like so
 
   
  +
We are using a model at N96L85 resolution. In the horizontal this is 1.875 degrees by 1.25 degrees. There are 85 vertical levels.
fcm branch-create --type dev -k <span style="color:purple">ticket_number</span> <span style="color:blue">your_branch_name</span> fcm:um_tr@vn8.2
 
   
  +
The '''N96''' UM grid
before checking-out your branch by
 
   
  +
# Has 192 points in longitude (x) and 145 points in latitude (y)
fcm checkout fcm:um_br/dev/<span style="color:green">userid</span>/vn8.2_<span style="color:blue">your_branch_name</span>
 
  +
# Starts at 0.0 longitude with a spacing of 1.875 degrees
  +
# Starts at -90.0 latitude (i.e. the South Pole) with a spacing of 1.25 degrees
   
  +
====Horizontal Regridding====
More information on FCM can be found at the [http://cms.ncas.ac.uk/wiki/Fcm NCAS-CMS FCM pages].
 
   
  +
[[Image:Xconv_Trans_N96.png|thumb|right|Figure 1: The Xconv ''Trans'' window.]]
During this tutorial you will be tasked to add in two new tracers into your UM branch.
 
  +
Horizontal regridding in Xconv is straight-forward. First, open your dataset in Xconv by
   
  +
xconv -i <span style="color:blue">file</span>.nc
==Part 1. Adding a tracer into the UMUI==
 
   
  +
and double-click on the field that you want to regrid and then click the '''Trans''' button at the far top right. This will show a window similar to Figure 1 (which in fact shows the default settings for a N96 field).
===Pick a free UKCA tracer slot===
 
   
  +
As we are regridding an emission we need to select '''area weighted interpolation''' as we need to conserve the total amount of quantity emitted. Then scroll-down to the boxes at the end and enter the following values:
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.
 
   
  +
* Number of columns = 192
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, <tt>cd</tt> into
 
  +
* First longitude = 0.000000
  +
* Column spacing = 1.875000
  +
* Number of rows = 145
  +
* First latitude = -90.000000
  +
* Row spacing = 1.250000
   
  +
which match up with the grid definition above, and ensure that
vn8.2_<span style="color:blue">your_branch</span>/src/atmosphere/UKCA
 
   
  +
* Pole longitude = 0.000000
and view the <tt>ukca_setd1defs.F90</tt> file. This will give the following for the '''nm_spec''' array which is found around line 360:
 
  +
* Pole latitude = 90.000000
   
  +
Now click '''Apply'''. You should be given a message similar to
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
 
   
  +
Area weighted interpolation from 720x360 Regular grid to 192x145 Regular grid
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_<span style="color:blue">scheme</span>.F90''' file (e.g. ''ukca_chem_strattrop.F90'') then you will see a list of the species that you are using.
 
   
  +
in the dialogue window. You can now extract this data as a new netCDF file (you cannot re-save a file in Xconv) by putting a name in the '''output file name''' box and clicking '''convert'''.
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. <span style="color:red">Red</span> species are either used by the aerosol chemistry or should be avoided, and species in <span style="color:green">green</span> are not currently used by any scheme and so can be over-written.
 
   
  +
====Vertical Regridding====
'O3 ','NO ','NO3 ','<span style="color:red">NO2</span> ','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 ', &
 
'<span style="color:green">O3_S</span> ','C5H8 ','ISOOH ','ISON ','MACR ', & !30
 
'MACROOH ','MPAN ','HACET ','MGLY ','NALD ', &
 
'HCOOH ','MeCO3H ','MeCO2H ','<span style="color:red">H2O</span> ','ISO2 ', & !40
 
'Cl ','ClO ','Cl2O2 ','OClO ','Br ', &
 
'<span style="color:red">BrO</span> ','BrCl ','BrONO2 ','N2O ','<span style="color:red">HCl</span> ', & !50
 
'HOCl ','HBr ','HOBr ','ClONO2 ','CFCl3 ', &
 
'CF2Cl2 ','MeBr ','N ','O(3P) ','MACRO2 ', & !60
 
'<span style="color:green">MeCl</span> ','<span style="color:green">CF2ClBr</span> ','<span style="color:green">CCl4</span> ','<span style="color:green">CF2ClCFCl2</span>','<span style="color:green">CHF2Cl</span> ', &
 
'<span style="color:green">MeCCl3</span> ','<span style="color:green">CF3Br</span> ','<span style="color:red">H2OS</span> ','<span style="color:green">CH2Br2</span> ','H2 ', & !70
 
'<span style="color:red">DMS</span> ','<span style="color:red">SO2</span> ','<span style="color:red">H2SO4</span> ','<span style="color:red">MSA</span> ','<span style="color:red">DMSO</span> ', &
 
'<span style="color:red">NH3</span> ','<span style="color:red">CS2</span> ','<span style="color:red">COS</span> ','<span style="color:red">H2S</span> ','H ', & !80
 
'OH ','HO2 ','MeOO ','EtOO ','MeCO3 ', &
 
'n-PrOO ','i-PrOO ','EtCO3 ','MeCOCH2OO ','MeOH ', & !90
 
'<span style="color:red">Monoterp</span> ','<span style="color:red">Sec_Org</span> ','<span style="color:green">SESQUITERP</span>','<span style="color:red">SO3</span> ','<span style="color:green">AROM</span> ', &
 
'<span style="color:green">O(3P)_S</span> ','<span style="color:green">O(1D)_S</span> ','NO2 ','BrO ','HCl ', & !100
 
   
  +
It is not possible to vertically regrid data using Xconv. You will need to do this in another way. If you need to vertically regrid data, and am unsure of the best way, please contact [[User:Nla27 | Luke Abraham]] for advice.
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.
 
   
  +
Remember that
In this example we will over-write tracer number '''65''' (CHF2Cl).
 
   
  +
* Emissions data must be re-gridded in a mass conserving way, so you will probably need to integrate the field on one grid and then decompose it again on the new grid.
===Edit your user STASHmaster file===
 
  +
* Tracer data can be fitted to the profile of the field on the old grid.
   
  +
===Choosing a STASH slot for your new emission(s)===
In your UMUI job go to '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; 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 <code>cp</code>) 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
 
   
  +
To make a new ancillary file for your new emission(s), you should first decide on a STASH item for it/them. Currently UKCA makes use of the '''user single-level ancillary file''' and '''user multi-level ancillary file''' which uses STASH section 0 items 301-320 (single-level) and 321-340 (multi-level). What these numbers correspond to is set in the file '''ukca_setd1defs.F90''', as well as in the user STASHmaster file associated with the job you are using (which can be found in '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; User-STASHmaster files. Diags, Progs & Ancills''').
#
 
1| 1 | 34 | <span style="color:red">1</span> |<span style="color:red">O3 MASS MIXING RATIO AFTER TIMESTEP </span>|
 
2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 |
 
3| 000000000000000000000000000<span style="color:red">001</span> | 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 |
 
#
 
   
  +
====Listing of emissions from STASH====
Each of the areas coloured in <span style="color:red">red</span> 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
 
   
  +
{| border="1"
#
 
  +
! Stash code || Emission
1| 1 | 34 | <span style="color:blue">65</span> |<span style="color:blue">MY TRACERS NAME </span>|
 
  +
|-
2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 |
 
  +
| 301 || NOx surf emissions
3| 000000000000000000000000000<span style="color:blue">065</span> | 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 |
+
| 302 || CH4 surf emissions
  +
|-
#
 
  +
| 303 || CO surf emissions
  +
|-
  +
| 304 || HCHO surf emissions
  +
|-
  +
| 305 || C2H6 surf emissions
  +
|-
  +
| 306 || C3H8 surf emissions
  +
|-
  +
| 307 || ME2CO surf emissions
  +
|-
  +
| 308 || MECHO surf emissions
  +
|-
  +
| 309 || C5H8 surf emissions
  +
|-
  +
| 310 || BC fossil fuel surf emissions
  +
|-
  +
| 311 || BC biofuel surf emissions
  +
|-
  +
| 312 || OC fossil fuel surf emissions
  +
|-
  +
| 313 || OC biofuel surf emissions
  +
|-
  +
| 314 || Monoterpene surf emissions
  +
|-
  +
| 315 || NVOC surf emissions
  +
|-
  +
| 322 || BC BIOMASS 3D EMISSION
  +
|-
  +
| 323 || OC BIOMASS 3D EMISSION
  +
|-
  +
| 340 || NOX AIRCRAFT EMS IN KG/S/GRIDCELL
  +
|}
   
  +
====Code in ukca_setd1defs.F90====
'''Note:''' the spacing of the pipes (<tt>|</tt>) in this file is important, so be careful not to change this.
 
   
  +
The species emitted are set in two places, firstly in the definition of an array called '''em_chem_spec''' which is scheme specific, and secondly in a block of code which searches through the ''em_chem_spec'' array and assigns a STASH number to it (as defined by the list above).
Now, in the '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; User-STASHmaster files. Diags, Progs & Ancills.''' panel replace the original user STASHmaster file with your new one containing the additional tracer(s).
 
   
  +
For example, for the ''CheST/StratTrop'' chemistry (not using aerosol chemistry), em_chem_spec is set to
===Initialise your tracer(s)===
 
   
  +
em_chem_spec = &
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 &rarr; Atmosphere &rarr; STASH &rarr; 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.
 
  +
(/'NO ','CH4 ','CO ','HCHO ', &
  +
'C2H6 ','C3H8 ','Me2CO ','MeCHO ', &
  +
'C5H8 ','NO_aircrft'/)
   
  +
This can be found in the '''Stratospheric Chemistry''' section, controlled by the IF block where <code>(L_ukca_strattrop .AND. .NOT. L_ukca_achem)</code>. If you are using aerosol chemistry then em_chem_spec is set to
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 [http://cms.ncas.ac.uk/documents/xancil/ Xancil]. Xancil will be covered in more detail in the [[UKCA & UMUI Tutorial 5 | adding new emissions]] tutorial. If these fields existed in the start dump you are providing then you could set this option to '''1'''.
 
   
  +
em_chem_spec = &
===Tell the UMUI about your new tracer===
 
  +
(/'NO ','CH4 ','CO ','HCHO ', &
  +
'C2H6 ','C3H8 ','Me2CO ','MeCHO ', &
  +
'C5H8 ','BC_fossil ','BC_biofuel','OC_fossil ', &
  +
'OC_biofuel','Monoterp ','NVOC ','SO2_low ', &
  +
'SO2_high ','DMS ','NH3 ','SO2_nat ', &
  +
'BC_biomass','OC_biomass','NO_aircrft'/)
   
  +
in the section of the IF block controlled by <code>(L_ukca_strattrop .AND. L_ukca_achem)</code>.
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 <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> 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'''.
 
   
  +
Further down the code there is this block of code:
If you go to your <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory and view the SIZES script, you will see that it contains entries similar to, e.g.
 
   
  +
J = n_use_tracers
TR_UKCA=72,
 
  +
IF (n_chem_emissions+n_3d_emissions+n_mode_emissions > 0) THEN
  +
DO i=1,n_chem_emissions + n_3d_emissions
  +
UkcaD1Codes(J+i)%section = 0
  +
UkcaD1Codes(J+i)%item = n_emiss_first+i-1 ! trop chemistry
  +
UkcaD1Codes(J+i)%len_dim1 = row_length ! uses stash codes
  +
UkcaD1Codes(J+i)%len_dim2 = rows ! 301-309 for
  +
UkcaD1Codes(J+i)%required = .true. ! surface emissions
  +
UkcaD1Codes(J+i)%prognostic = .true. ! from Section 0
  +
! Special cases, emissions already available in UM
  +
IF (em_chem_spec(i)(1:7) == 'SO2_low') THEN
  +
UkcaD1Codes(J+i)%item = 58
  +
IF (.NOT. L_SO2_SURFEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 surface emissions from UM are not flagged'
  +
errcode=58
  +
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:7) == 'SO2_nat') THEN
  +
UkcaD1Codes(J+i)%item = 121
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
IF (.NOT. L_SO2_NATEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 natural emissions from UM are not flagged'
  +
errcode=121
  +
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:8) == 'SO2_high') THEN
  +
UkcaD1Codes(J+i)%item = 126
  +
IF (.NOT. L_SO2_HILEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 high-level emissions are not flagged'
  +
errcode = UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:3) == 'NH3') THEN
  +
UkcaD1Codes(J+i)%item = 127
  +
IF (.NOT. L_NH3_EM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='NH3 surface emissions from UM are not flagged'
  +
errcode = UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i) == 'BC_fossil ') THEN
  +
UkcaD1Codes(J+i)%item = 310
  +
ELSEIF (em_chem_spec(i) == 'BC_biofuel') THEN
  +
UkcaD1Codes(J+i)%item = 311
  +
ELSEIF (em_chem_spec(i) == 'OC_fossil ') THEN
  +
UkcaD1Codes(J+i)%item = 312
  +
ELSEIF (em_chem_spec(i) == 'OC_biofuel') THEN
  +
UkcaD1Codes(J+i)%item = 313
  +
ELSEIF (em_chem_spec(i) == 'Monoterp ') THEN
  +
UkcaD1Codes(J+i)%item = 314
  +
ELSEIF (em_chem_spec(i) == 'NVOC ') THEN
  +
UkcaD1Codes(J+i)%item = 315
  +
ELSEIF (em_chem_spec(i) == 'BC_biomass') THEN
  +
UkcaD1Codes(J+i)%item = 322
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i) == 'OC_biomass') THEN
  +
UkcaD1Codes(J+i)%item = 323
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i) == 'SO2_biomas') THEN
  +
UkcaD1Codes(J+i)%item = 324
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i)(1:3) == 'DMS') THEN
  +
UkcaD1Codes(J+i)%section = 17
  +
UkcaD1Codes(J+i)%item = 205
  +
UkcaD1Codes(J+i)%prognostic = .false.
  +
IF (.NOT. L_DMS_EM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='DMS surface emissions from UM are not flagged'
  +
errcode = UkcaD1Codes(J+i)%section*1000 + &
  +
UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:7) == 'NO_airc') THEN
  +
UkcaD1Codes(J+i)%item = 340
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ENDIF
  +
ENDDO
  +
ENDIF
   
  +
This block of code is rather complicated, but what it essentially means is that for the STASH codes 301-309, the emissions are assumed to be in the order of the species in ''em_chem_spec'', but for the other emissions the STASH numbers are explicitly defined. As you can see from the table above, for 2D (surface) emissions the numbers 301-315 are reserved, and for 3D emissions the numbers 322, 323, and 340 are reserved.
and
 
   
  +
This means that if you are adding in a new surface emission(s) it is best to use the slots 316-320, unless you need more than 5 slots. For 3D emissions you have more leeway.
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,
 
   
  +
====Emissions STASHmaster File====
'''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.
 
   
  +
Now that you have selected your slot(s), you need to create a new STASH specification for it/them. The easiest way to do this is to copy the existing user STASHmaster file that defines your current (possible) emissions, and extend that. This is found in '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; User-STASHmaster files. Diags, Progs & Ancills'''. This will be a different STASHmaster file to the one that contains the UKCA tracers, and e.g. in the UKCA Tutorial job, is called '''emiss_TCMIM_Aero.presm'''.
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
 
   
  +
This contains entries like
/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
 
  +
1| 1 | 0 | 301 |NOx surf emissions |
  +
2| 2 | 0 | 1 | 1 | 5 | -1 | -1 | 0 | 0 | 0 | 0 |
  +
3| 000000000000000000000000000000 | 00000000000000000001 | 3 |
  +
4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
  +
5| 0 | 531 | 0 | 129 | 0 | 0 | 0 | 0 | 0 |
  +
#
  +
  +
#
  +
1| 1 | 0 | 340 |NOX AIRCRAFT EMS IN KG/S/GRIDCELL |
  +
2| 2 | 0 | 1 | 1 | 2 | 10 | 11 | 0 | 0 | 0 | 0 |
  +
3| 000000000000000000000000000000 | 00000000000000000001 | 3 |
  +
4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
  +
5| 0 | 520 | 20 | 65 | 0 | 0 | 0 | 9999 | 0 |
  +
#
   
  +
The top entry (''NOx surf emissions'') defines a 2D field, and the other (''NOX AIRCRAFT EMS IN KG/S/GRIDCELL'') defines a 3D field. You can see that there are differences in the numbers (other than the 301/340 item number) in various places in these specifications, which effectively (in this instance) tell STASH if the field is 2D or 3D.
$ 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,<span style="color:blue">'''1'''</span>,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=<span style="color:blue">'''73'''</span>,
 
   
  +
Full details on what each of these numbers mean can be found in appendix 3 of ''Unified Model Documentation Paper C4'' which can be found on the [http://collab.metoffice.gov.uk/twiki/bin/view/Support/Umdp Met Office Collaboration Twiki (password required)].
(with the changes from before highlighted in <span style="color:blue">blue</span>). You will now need to add this data into the '''SIZES''' script using a hand-edit.
 
   
  +
You should copy either the 2D or 3D specification, depending on what type of emission you are adding in, and edit only the '''STASH item number''', '''name of field''', and the '''field code'''. These can be found here:
Hand-edits use the [http://linux.die.net/man/1/ed 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
 
  +
1| 1 | 0 | <span style="color:red">301</span> |<span style="color:red">NOx surf emissions</span> |
/TC_UKCA=/
 
  +
2| 2 | 0 | 1 | 1 | 5 | -1 | -1 | 0 | 0 | 0 | 0 |
d
 
  +
3| 000000000000000000000000000000 | 00000000000000000001 | 3 |
d
 
  +
4| 1 | 0 | -99 -99 -99 -99 -99 -99 -99 -99 -99 -99 |
d
 
  +
5| 0 | <span style="color:red">531</span> | 0 | 129 | 0 | 0 | 0 | 0 | 0 |
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
 
   
  +
For the field code (531 above), if you were making a new emission at 316, it is advisable that you increase the current code above by 15 as well, e.g. ''546''. Xconv uses this field code for the name of the variable, so it is best to have them different. A listing of available field codes can be found on the [http://cms.ncas.ac.uk/documents/IDL/@fcodes.txt NCAS CMS website], although these may be a little out of date.
The first block tells ''ed'' to search for the line <tt>TC_UKCA=</tt> 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 should make these changes to your copy of the original emissions user STASHmaster file, save this, and then replace the original file in the UMUI's ''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; User-STASHmaster files. Diags, Progs & Ancills'' table with your new file. Now go to '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; Initialisation of User Prognostics''' and scroll down the table until you find your new emission. Set the value in the '''Option''' column to '''2''' (''Initialise to User Ancillary File'').
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
 
   
  +
As you need to make up a new ancillary file, you should copy this user STASHmaster file onto the supercomputer, as it will be needed by Xancil when you make the new ancillary file. It is advisable to put it in the same directory as the one containing your new emission(s) file.
chmod a+rx add_UKCA_Tr_StratTrop.ed
 
   
  +
===Using Xancil===
Now, in the UMUI we go to '''Model Selection &rarr; Input/Output Control and Resource &rarr; 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.
 
   
  +
====Extract your current emissions====
==Solution to Task 5.1: Make slots for two new tracers==
 
   
  +
Due to current limitations of the UM, you can only have one user single-level and one multi-level file. If you want to add a new emissions field, you must include the existing emissions in your new file along with it.
Please see [[Solution to UKCA Chemistry and Aerosol Tutorial 5 Task 5.1 |this page]] for a solution to [[#Task 5.1: Make slots for two new tracers|Task 5.1]]
 
   
  +
You can use Xconv to extract these fields. You must first find the location of the current file(s). To do this, go to '''Model Selection &rarr; Atmosphere &rarr; Ancillary data and input data files &rarr; Climatologies and potential climatologies''' and either open the '''User multi-level ancillary file & fields''' or '''User single-level ancillary file & fields''' panel. This will give two boxes giving the '''directory name or environment variable''' and the '''file name'''. This first box will contain an environment variable which sets the directory location. You can find the value of this environment variable in '''Model Selection &rarr; Input/Output Control and Resources &rarr; Time Convention and SCRIPT Environment Variables'''.
==Task 5.2: Add these two new tracers to UKCA==
 
   
  +
Once you have found the required file, extract all the fields within it to one of your own directories (ideally the one containing the netCDF file of your new emission(s)).
<span style="color:green">'''TASK5.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.</span>
 
   
  +
====Make a new emissions ancillary file====
'''Note:''' If you were unable to successfully complete Task 5.1 above, then please take a copy of the '''d''' job from the Tutorial experiment (''Tutorial: solution to Task 5.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.
 
   
  +
Xancil is installed on both ARCHER at
==Part 2. Adding new a new chemical tracer to UKCA==
 
   
  +
/work/n02/n02/hum/bin/xancil
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.
 
   
  +
and on MONSooN (the postproc machine) at
===FCM branches and merging===
 
   
  +
/projects/um1/linux/bin/xancil
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 &rarr; FCM Configuration &rarr; FCM Options for Atmosphere and Reconfiguration''' you can view the current branches used by this job, e.g.:
 
   
  +
You may already have this location in your PATH and so can just launch Xancil from the command line by typing <code>xancil</code>. When you do this it will load up the Xancil window, which is initially rather empty. You should click on the '''Xancil''' text in the top-left corner. This will give 4 options:
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
 
   
  +
* Configuration
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.
 
  +
* Atmosphere Ancillary Files
  +
* Ocean Ancillary Files
  +
* Generalised Ancillary Files
   
  +
When using UKCA you will need to make use of all of these options, with the exception of the ''Ocean Ancillary Files''.
You should already have made a new branch that you used to find the free tracer slots. Now <tt>cd</tt> into the highest-level directory of the branch, which contains
 
   
  +
'''You should view the ''[[Using Xancil]]'' page for more details on each of these sub-menus.'''
CodeOwners.txt COPYRIGHT.txt src/
 
   
  +
Load your netCDF and user STASHmaster files into the '''Xancil &rarr; Configuration''' panel, and [[Using Xancil#Grid Configuration | define the vertical levels]] if you are making a 3D ancillary file.
From here you will need to merge in the '''vn8.2_ukca_update_rate_coeffs''' branch. Do
 
  +
  +
Click on the ''Atmosphere Ancillary Files'' text and either open the '''Multi-level User Fields''' or '''Single-level User Fields''' panels. You should now
   
  +
* Set the output file name
fcm merge fcm:um_br/dev/foconnor/vn8.2_ukca_update_rate_coeffs/src
 
  +
* Define the dates. If the ones in the netCDf file are fine to use then you can use them, or you can specify them. For this latter option you can either use the dates from the [[Using Xancil#Grid Configuration | grid configuration panel]], or you can define them again here
  +
* Enter the number of ancillary fields. This will need to be the total of the number of fields in the original ancillary file, plus the number of new emissions you are adding
  +
* For each individual field you should select it with the mouse, then
  +
** Define which netCDF file to use (it will remember the preference from the previous field)
  +
** Enter the STASH code (the PP code should be filled in automatically)
  +
** Either enter or confirm the variable name. Xancil takes the variable name from the ''field code'' defined in the STASHmaster file specification for each field. If there are multiple fields in the netCDF file with the same field code then Xancil may select the wrong one. If the name does not match a field code you will need to select it manually.
   
  +
Once you have entered all the data for all fields you should
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.
 
   
  +
* Use the '''Save/Save As''' button to save the job, as it may be needed later
In the terminal, this will have the following output:
 
  +
* Click the '''Output Anc. Files''' button to create the new ancillary file. Any errors will appear in the '''Output messages''' window, or to the terminal.
   
  +
===Use your new emissions file in the UMUI===
$ 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:
 
   
  +
Now that you have created your new emissions file you can use this in the UMUI. Go to '''Model Selection &rarr; Atmosphere &rarr; Ancillary data and input data files &rarr; Climatologies and potential climatologies''' and either open the '''User multi-level ancillary file & fields''' or '''User single-level ancillary file & fields''' panel, and set the '''Directory name or Environment Variable''' to the directory containing your new emissions file, and the '''file name''' to the name of your new file.
$ 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
 
   
  +
'''Note:''' On ARCHER this directory must be located on '''/work''' as the ''/home'' directory cannot be read at run time. This includes any symbolic links from /work to /home and ''vice versa''.
Before you make any further changes you should '''commit''' these changes. Do this now by typing the command
 
   
  +
==Solution to Task 5.1: Create a new emissions file and use it in your job==
fcm commit
 
   
  +
Please see [[Solution to UKCA Chemistry and Aerosol Tutorial 5 Task 5.1 |this page]] for a solution to [[#Task 5.1: Create a new emissions file and use it in your job|Task 5.1]]
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.
 
   
  +
==Task 5.2: make the required code changes to add your emission into UKCA==
Now you need to add this branch into the UMUI, and turn off the original <tt>vn8.2_ukca_update_rate_coeffs</tt> branch. We will initially use a '''working copy'''.
 
   
  +
<span style="color:green">'''TASK 5.2:''' You should now make the UKCA code changes to add your emission into the '''ALICE''' tracer. No run-time processing of this surface emission is required. You will also need to add-in the molar-mass of '''ALICE'''.</span>
* Go to the ''Model Selection &rarr; FCM Configuration &rarr; 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 <br/> '''fcm:um_br/dev/<span style="color:blue">your PUMA username</span>/vn8.2_<span style="color:blue">your_branch_name</span>/src''' <br/> 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/<span style="color:blue">your PUMA username</span>/.../vn8.2_<span style="color:blue">your_branch_name</span>/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.
 
   
  +
{| class="collapsible collapsed wikitable"
Using a '''working copy''' means that FCM will pick up any changes that you have made to your branch without you needed to <tt>fcm commit</tt> 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.
 
  +
|-
  +
! Hint
  +
|-
  +
| You can calculate the molar mass from the mass of air and the conversion factor defined in [[UKCA Chemistry and Aerosol Tutorial 5#Task 5.2: Add these two new tracers to UKCA|Task 5.2]].
  +
|}
   
  +
'''Note:''' If you were unable to successfully complete Task 6.1 above, then please take a copy of the '''e''' job from the Tutorial experiment (''Tutorial: solution to Task 5.1 - adding a new chemical emissions ancillary file'') and work from there, as this will allow you to make only the changes required for this task. Please also make a new branch and merge-in branch '''fcm:um_br/dev/luke/vn8.4_UKCA_Tutorial_Solns''' at revision number '''14692''' to allow you to proceed.
'''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.
 
   
  +
You can also find a copy of an emissions ancillary file, with the required emissions, at
===Editing the advected tracer list===
 
   
  +
/work/n02/n02/ukca/Tutorial/vn8.4/Task5.1/solution/Task5.1_AR5_2000.anc
To edit the UKCA source code, go to your branch and '''cd''' into
 
   
  +
on ARCHER, and at
src/atmosphere/UKCA/
 
   
  +
<strike>/projects/ukca/Tutorial/vn8.4/Task5.1/solution/Task5.1_AR5_2000.anc</strike>
This directory contains the majority of the UKCA specfic code, and contains over 200 files.
 
   
  +
on MONSooN.
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.
 
   
  +
==Part 2. UKCA Code Changes==
'''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'''.
 
   
  +
===Changes to ukca_setd1defs.F90===
===Increase the number of tracers to be used===
 
   
  +
The ukca_setd1defs.F90 tells UKCA what fields it should expect to find from the UM to allow it to run. Previously you edited this routine so that UKCA knew about your new tracers, now you must edited to tell it about your new emissions. This is done in two places
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
 
   
  +
====Add the species to em_chem_spec====
n_chem_tracers = 71 ! No chem tracers
 
   
  +
You will need to find the '''em_chem_spec''' definition for the scheme that you are using. For example, the ''CheST/StratTrop'' chemistry is located in the ''Stratospheric Chemistry'' section and contained in the IF block controlled by <code>(L_ukca_strattrop .AND. .NOT. L_ukca_achem)</code> if you are not using aerosol chemistry, and by <code>(L_ukca_strattrop .AND. L_ukca_achem)</code> if you are using aerosol chemistry. For the former case this is defined by
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.
 
   
  +
n_chem_emissions = 9
'''Note:''' You will find that this number may be different than that specified in the value of <code>TR_UKCA</code> 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 <code>n_chem_tracers</code> 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.
 
  +
n_3d_emissions = 1 ! aircraft NOX
  +
  +
ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
  +
em_chem_spec = &
  +
(/'NO ','CH4 ','CO ','HCHO ', &
  +
'C2H6 ','C3H8 ','Me2CO ','MeCHO ', &
  +
'C5H8 ','NO_aircrft'/)
   
  +
and for the latter case by
===Editing the Chemistry Scheme Specification===
 
   
  +
n_chem_emissions = 21 ! em_chem_spec below
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_<span style="color:blue">scheme</span>.F90'''. So we should open the file called '''ukca_chem_strattrop.F90'''.
 
  +
n_3d_emissions = 2 ! volc SO2 & aircraft NOX
  +
ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
  +
em_chem_spec = &
  +
(/'NO ','CH4 ','CO ','HCHO ', &
  +
'C2H6 ','C3H8 ','Me2CO ','MeCHO ', &
  +
'C5H8 ','BC_fossil ','BC_biofuel','OC_fossil ', &
  +
'OC_biofuel','Monoterp ','NVOC ','SO2_low ', &
  +
'SO2_high ','DMS ','NH3 ','SO2_nat ', &
  +
'BC_biomass','OC_biomass','NO_aircrft'/)
   
  +
You should edit the equivalent block. You should first increase the value of '''n_chem_emissions''' (for surface emissions) or '''n_3d_emissions''' (for 3D emissions) by the number of emissions that you are adding, and you should then add the names of the species (as they appear in the '''nm_spec''' array in ''ukca_setd1defs.F90'', and how they appear in the ''CHCH_DEFS'' specification in the ''ukca_chem_<span style="color:blue">scheme</span>.F90'' routine) that you are emitting into. Convention is that these are in ascending order by STASH code. The first 9 species in the above list are STASH codes 301-309, and <code>'NO_aircrft'</code> is STASH code 340, so all new species should be placed before <code>'NO_aircrft'</code> if you are not using aerosol chemistry, and before the <code>'SO2_low '</code> if you are. You should make sure that the size of ''em_chem_spec'' is correct for the number of species within it.
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
 
   
  +
====Tell UKCA the STASH code associated with your new emission====
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
 
/)
 
   
  +
In the [[UKCA Chemistry and Aerosol Tutorial 5#Code in ukca_setd1defs.F90 | previous ukca_setd1defs.F90 discussion]] above we saw the following block of code
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:
 
   
  +
J = n_use_tracers
* TR = tracer
 
  +
IF (n_chem_emissions+n_3d_emissions+n_mode_emissions > 0) THEN
* CT = constant
 
  +
DO i=1,n_chem_emissions + n_3d_emissions
* SS = steady state
 
  +
UkcaD1Codes(J+i)%section = 0
  +
UkcaD1Codes(J+i)%item = n_emiss_first+i-1 ! trop chemistry
  +
UkcaD1Codes(J+i)%len_dim1 = row_length ! uses stash codes
  +
UkcaD1Codes(J+i)%len_dim2 = rows ! 301-309 for
  +
UkcaD1Codes(J+i)%required = .true. ! surface emissions
  +
UkcaD1Codes(J+i)%prognostic = .true. ! from Section 0
  +
! Special cases, emissions already available in UM
  +
IF (em_chem_spec(i)(1:7) == 'SO2_low') THEN
  +
UkcaD1Codes(J+i)%item = 58
  +
IF (.NOT. L_SO2_SURFEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 surface emissions from UM are not flagged'
  +
errcode=58
  +
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:7) == 'SO2_nat') THEN
  +
UkcaD1Codes(J+i)%item = 121
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
IF (.NOT. L_SO2_NATEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 natural emissions from UM are not flagged'
  +
errcode=121
  +
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:8) == 'SO2_high') THEN
  +
UkcaD1Codes(J+i)%item = 126
  +
IF (.NOT. L_SO2_HILEM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='SO2 high-level emissions are not flagged'
  +
errcode = UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:3) == 'NH3') THEN
  +
UkcaD1Codes(J+i)%item = 127
  +
IF (.NOT. L_NH3_EM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='NH3 surface emissions from UM are not flagged'
  +
errcode = UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i) == 'BC_fossil ') THEN
  +
UkcaD1Codes(J+i)%item = 310
  +
ELSEIF (em_chem_spec(i) == 'BC_biofuel') THEN
  +
UkcaD1Codes(J+i)%item = 311
  +
ELSEIF (em_chem_spec(i) == 'OC_fossil ') THEN
  +
UkcaD1Codes(J+i)%item = 312
  +
ELSEIF (em_chem_spec(i) == 'OC_biofuel') THEN
  +
UkcaD1Codes(J+i)%item = 313
  +
ELSEIF (em_chem_spec(i) == 'Monoterp ') THEN
  +
UkcaD1Codes(J+i)%item = 314
  +
ELSEIF (em_chem_spec(i) == 'NVOC ') THEN
  +
UkcaD1Codes(J+i)%item = 315
  +
ELSEIF (em_chem_spec(i) == 'BC_biomass') THEN
  +
UkcaD1Codes(J+i)%item = 322
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i) == 'OC_biomass') THEN
  +
UkcaD1Codes(J+i)%item = 323
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i) == 'SO2_biomas') THEN
  +
UkcaD1Codes(J+i)%item = 324
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ELSEIF (em_chem_spec(i)(1:3) == 'DMS') THEN
  +
UkcaD1Codes(J+i)%section = 17
  +
UkcaD1Codes(J+i)%item = 205
  +
UkcaD1Codes(J+i)%prognostic = .false.
  +
IF (.NOT. L_DMS_EM .AND. (L_ukca_aerchem .OR. &
  +
L_ukca_achem)) THEN
  +
cmessage='DMS surface emissions from UM are not flagged'
  +
errcode = UkcaD1Codes(J+i)%section*1000 + &
  +
UkcaD1Codes(J+i)%item
  +
CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
  +
ENDIF
  +
ELSEIF (em_chem_spec(i)(1:7) == 'NO_airc') THEN
  +
UkcaD1Codes(J+i)%item = 340
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
  +
ENDIF
  +
ENDDO
  +
ENDIF
   
  +
You will need to add code at the end of this block to tell UKCA what STASH code is associated with which species. The best thing to do is to copy one of the explict blocks at the end, and adjust accordingly, e.g.
The 6th and 7th columns of the list control dry and wet deposition respectively. We will cover these in more detail in the [[UKCA & UMUI Tutorial 7 | adding dry deposition of chemical species]] and [[UKCA & UMUI Tutorial 8 | adding wet deposition of chemical species]] tutorials.
 
   
  +
For surface (2D) emissions you should add in the following
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.
 
   
  +
ELSEIF (em_chem_spec(i) == '<span style="color:blue">Your Species</span>') THEN
===Define conversion factors for your new tracers===
 
  +
UkcaD1Codes(J+i)%item = <span style="color:blue">Your Species STASH code (301-320)</span>
   
  +
and for 3D emissions you should add in the following
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).
 
   
  +
ELSEIF (em_chem_spec(i) == '<span style="color:blue">Your Species</span>') THEN
Open this file and add the required conversion factor(s). The naming convention for these is '''M_<span style="color:blue">species</span>''' is the molecular mass of the new species in g/mol, and '''C_<span style="color:blue">species</span>''' for the converson factor from vmr to mmr (calculated as M_<span style="color:blue">species</span>/M_air, where M_air=28.97). In actuality, only the C_<span style="color:blue">species</span> listing is always required, although you may need to add the M_<span style="color:blue">species</span> value later if you are emitting into the new species that you are adding.
 
  +
UkcaD1Codes(J+i)%item = <span style="color:blue">Your Species STASH code (321-340)</span>
  +
UkcaD1Codes(J+i)%len_dim3 = tr_levels
   
  +
Remember that the character string length for a UKCA species is '''10 characters'''.
===Tell UKCA to use these conversion factors===
 
   
  +
===Changes to ukca_constants.F90===
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:
 
  +
  +
As you are adding in an emission you may need to define the molar mass (in g/mol) of the species that you are emitting in to, if it is not already defined. Add this definition into '''ukca_constants.F90''', e.g.
   
 
...
 
...
WHERE (advt == 'MEMALD ') c_species = c_memald
+
REAL, PARAMETER :: m_co = 28.
WHERE (advt == 'MVK ') c_species = c_mvk
+
REAL, PARAMETER :: m_hcho = 30.
WHERE (advt == 'MVKOOH ') c_species = c_mvkooh
 
WHERE (advt == 'TOLUENE ') c_species = c_toluene
 
 
...
 
...
   
  +
===Changes to ukca_emission_ctl.F90===
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_<span style="color:blue">species</span> parameter. Add the line(s) in at the end of block.
 
  +
  +
You will need to ensure that the '''molmass''' array is filled for the tracer that you are emitting in to. This is filled in the '''WHERE''' block which has entries like
  +
  +
...
  +
WHERE (em_chem_spec == 'CO ') molmass = m_co
  +
WHERE (em_chem_spec == 'HCHO ') molmass = m_hcho
  +
...
  +
  +
You should add an additional line for each new emission.
  +
  +
For surface emissions, unless your new emissions data requires further run-time processing, such as adding a diurnal cycle (see how isoprene (C5H8) is treated below), then you will not need to make too many additional changes to the '''ukca_emission_ctl.F90''' routine. If you do need to add functionality such as this then you will need edit the following IF block:
   
  +
DO l=1,n_emissions
===Increase the size of JPCTR and JPSPEC===
 
  +
IF (advt(k) == em_chem_spec(l) .AND. &
  +
em_chem_spec(l) == 'NO ' ) THEN
  +
! Convert from kg NO2/m2/s to kg NO/m2/s
  +
em_field(:,:,k) = emissions(:,:,l)*m_no/m_no2
  +
ELSE IF (advt(k) == em_chem_spec(l)(1:3) .AND. &
  +
em_chem_spec(l) == 'SO2_low ' ) THEN
  +
! Convert from kg S/m2/s to kg SO2/m2/s and take off sulphate fraction
  +
em_field(:,:,k) = emissions(:,:,l)* &
  +
(1.0 - mode_parfrac/100.0)*m_so2/m_s
  +
ELSE IF (advt(k) == em_chem_spec(l) .AND. &
  +
em_chem_spec(l) == 'DMS ' ) THEN
  +
! Convert from kg S/m2/s to kg DMS/m2/s
  +
em_field(:,:,k) = emissions(:,:,l)*m_dms/m_s
  +
ELSE IF (advt(k) == 'MeOH ' .AND. &
  +
em_chem_spec(l) == 'NVOC ' ) THEN
  +
! Convert from kg C/m2/s to kg CH3OH/m2/s
  +
em_field(:,:,k) = emissions(:,:,l)*meoh_factor* &
  +
m_meoh/(m_c*3.0)
  +
ELSE IF (advt(k) == em_chem_spec(l) .AND. &
  +
em_chem_spec(l) == 'Monoterp ' ) THEN
  +
! Convert from kg C/m2/s to kg C10H16/m2/s
  +
em_field(:,:,k) = emissions(:,:,l)*m_monoterp/(m_c*10.0)
  +
! === biogenic emissions ===
  +
ELSE IF (advt(k) == em_chem_spec(l) .AND. &
  +
em_chem_spec(l) == 'C5H8 ') THEN
  +
IF (L_ukca_diurnal_isopems) THEN
  +
tmp_in_em_field(:,:) = emissions(:,:,l)*(m_isop/(5.0*m_c))
  +
! DEPENDS ON: ukca_diurnal_isop_ems
  +
! testdcycl = .TRUE.
  +
CALL UKCA_DIURNAL_ISOP_EMS(row_length, rows, &
  +
tmp_in_em_field, cos_zenith_angle, &
  +
int_zenith_angle, &
  +
sin_theta_latitude, FV_cos_theta_latitude, &
  +
tan_theta_latitude, timestep, tmp_out_em_field,&
  +
testdcycl)
  +
em_field(:,:,k) = tmp_out_em_field(:,:)
  +
ELSE
  +
em_field(:,:,k) = emissions(:,:,l)*(m_isop/(5.0*m_c))
  +
END IF
  +
ELSE IF (advt(k) == em_chem_spec(l) ) THEN
  +
em_field(:,:,k) = emissions(:,:,l)
  +
ENDIF ! end advt(k)
   
  +
If nothing needs to be done to the emissions field, then the final section
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.
 
   
  +
ELSE IF (advt(k) == em_chem_spec(l) ) THEN
* '''JPSPEC''' is the number of chemical species used in UKCA (effectively the size of ''chch_defs_strattrop_chem'')
 
  +
em_field(:,:,k) = emissions(:,:,l)
* '''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'')
 
   
  +
just adds the emissions field from the ancillary file into the correct place to be emitted to the tracer.
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:
 
   
  +
After this is done the UM boundary layer mixing scheme is called (''TR_MIX'') for each tracer, and this is also where the emissions are added to the tracer field.
ed CNTLATM<<\EOF
 
/JPCTR/
 
d
 
i
 
JPCTR = <span style="color:blue">value of n_chem_tracers</span>,
 
.
 
/JPSPEC/
 
d
 
i
 
JPSPEC = <span style="color:blue">new size of chch_defs_strattrop_chem array</span>,
 
.
 
w
 
q
 
EOF
 
   
  +
For 3D emissions you will need to explicitly add this into the required tracer using the ''TRSRCE'' subroutine. This is done for lightning emissions (calculated on-line) and aircraft emissions (read-in from the multi-level user ancillary file). You should copy what is done for e.g. aircraft emissions and adapt accordingly.
Save this hand-edit and make it executable, and place it in the table in '''Model Selection &rarr; Input/Output Control and Resource &rarr; User hand edit files''' with a '''Y''' in the '''Include Y/N''' column.
 
   
==Solution to Task 4.2: Add these two new tracers to UKCA==
+
==Solution to Task 5.2: make the required code changes to add your emission into UKCA==
   
Please see [[Solution to UKCA & UMUI Tutorial 4 Task 4.2|this page]] for a solution to [[#Task 4.2: Add these two new tracers to UKCA|Task 4.2]]
+
Please see [[Solution to UKCA Chemistry and Aerosol Tutorial 5 Task 5.2 |this page]] for a solution to [[#Task 5.2: make the required code changes to add your emission into UKCA|Task 5.2]]
   
 
----
 
----

Latest revision as of 14:08, 15 December 2015

Back to UKCA Chemistry and Aerosol Tutorials

What you will learn in this Tutorial

During this tutorial you will learn how to make new UM ancillary files. Then you will learn how to add new emissions into UKCA so that they emit into one of your new tracers.

At the end of the previous tutorial you will now know how to create new tracers for use by UKCA. However, after completing the tasks, your tracers will still be empty, as nothing has been put into them. This tutorial will teach you how to create an emissions ancillary file that the UM will read, and that you can then tell UKCA to use and emit into your tracer(s).

This tutorial will go through the steps needed to make an emission into a tracer which UKCA does not currently emit into. The steps in making the ancillary file will be the same for a species which is currently emitted into, although in this simplier case you would not need to make any code changes.

During this tutorial you will be tasked with making a new emissions ancillary file, and add the emissions contained within it into one of your new tracers.

Task 5.1: Create a new emissions file and use it in your job

Task 5.1: In the
/work/n02/n02/ukca/Tutorial/vn8.4/Task5.1
directory on ARCHER, or the
/projects/ukca/Tutorial/vn8.4/Task5.1
directory on MONSooN, there is the file Emissions_of_ALICE.nc which is a 0.5x0.5 degree resolution surface emission field. You should regrid this file to N96, and then make a new surface emissions ancillary file with this as slot 316. You should then use this new file, and the corresponding user STASHmaster file, in your UMUI job.

Note: If you were unable to successfully complete Task 4.2, then please take a copy of the d job from the Tutorial experiment (Tutorial: solution to Task 4.2 - adding new chemical tracers to UKCA) and work from there, as this will allow you to make only the changes required for this task. Please also make a new branch and merge-in branch fcm:um_br/dev/luke/vn8.4_UKCA_Tutorial_Solns at revision number 14692 to allow you to proceed.

Part 1. Making a new Emissions Ancillary File

The UM uses its own format to read-in initial and emissions data, the ancillary file. UKCA makes use of these files for the surface and aircraft emissions, and these files can easily be made up from netCDF data using the Xancil program. However, before we can use Xancil to create our emissions ancillary, we may first need to use Xconv to regrid the raw data to the correct resolution of the UM configuration that you are using.

Regridding data with Xconv

We are using a model at N96L85 resolution. In the horizontal this is 1.875 degrees by 1.25 degrees. There are 85 vertical levels.

The N96 UM grid

  1. Has 192 points in longitude (x) and 145 points in latitude (y)
  2. Starts at 0.0 longitude with a spacing of 1.875 degrees
  3. Starts at -90.0 latitude (i.e. the South Pole) with a spacing of 1.25 degrees

Horizontal Regridding

Figure 1: The Xconv Trans window.

Horizontal regridding in Xconv is straight-forward. First, open your dataset in Xconv by

xconv -i file.nc

and double-click on the field that you want to regrid and then click the Trans button at the far top right. This will show a window similar to Figure 1 (which in fact shows the default settings for a N96 field).

As we are regridding an emission we need to select area weighted interpolation as we need to conserve the total amount of quantity emitted. Then scroll-down to the boxes at the end and enter the following values:

  • Number of columns = 192
  • First longitude = 0.000000
  • Column spacing = 1.875000
  • Number of rows = 145
  • First latitude = -90.000000
  • Row spacing = 1.250000

which match up with the grid definition above, and ensure that

  • Pole longitude = 0.000000
  • Pole latitude = 90.000000

Now click Apply. You should be given a message similar to

Area weighted interpolation from 720x360 Regular grid to 192x145 Regular grid

in the dialogue window. You can now extract this data as a new netCDF file (you cannot re-save a file in Xconv) by putting a name in the output file name box and clicking convert.

Vertical Regridding

It is not possible to vertically regrid data using Xconv. You will need to do this in another way. If you need to vertically regrid data, and am unsure of the best way, please contact Luke Abraham for advice.

Remember that

  • Emissions data must be re-gridded in a mass conserving way, so you will probably need to integrate the field on one grid and then decompose it again on the new grid.
  • Tracer data can be fitted to the profile of the field on the old grid.

Choosing a STASH slot for your new emission(s)

To make a new ancillary file for your new emission(s), you should first decide on a STASH item for it/them. Currently UKCA makes use of the user single-level ancillary file and user multi-level ancillary file which uses STASH section 0 items 301-320 (single-level) and 321-340 (multi-level). What these numbers correspond to is set in the file ukca_setd1defs.F90, as well as in the user STASHmaster file associated with the job you are using (which can be found in Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills).

Listing of emissions from STASH

Stash code Emission
301 NOx surf emissions
302 CH4 surf emissions
303 CO surf emissions
304 HCHO surf emissions
305 C2H6 surf emissions
306 C3H8 surf emissions
307 ME2CO surf emissions
308 MECHO surf emissions
309 C5H8 surf emissions
310 BC fossil fuel surf emissions
311 BC biofuel surf emissions
312 OC fossil fuel surf emissions
313 OC biofuel surf emissions
314 Monoterpene surf emissions
315 NVOC surf emissions
322 BC BIOMASS 3D EMISSION
323 OC BIOMASS 3D EMISSION
340 NOX AIRCRAFT EMS IN KG/S/GRIDCELL

Code in ukca_setd1defs.F90

The species emitted are set in two places, firstly in the definition of an array called em_chem_spec which is scheme specific, and secondly in a block of code which searches through the em_chem_spec array and assigns a STASH number to it (as defined by the list above).

For example, for the CheST/StratTrop chemistry (not using aerosol chemistry), em_chem_spec is set to

            em_chem_spec =                                             &
                (/'NO        ','CH4       ','CO        ','HCHO      ', &
                  'C2H6      ','C3H8      ','Me2CO     ','MeCHO     ', &
                  'C5H8      ','NO_aircrft'/)

This can be found in the Stratospheric Chemistry section, controlled by the IF block where (L_ukca_strattrop .AND. .NOT. L_ukca_achem). If you are using aerosol chemistry then em_chem_spec is set to

            em_chem_spec =                                             &
                (/'NO        ','CH4       ','CO        ','HCHO      ', &
                  'C2H6      ','C3H8      ','Me2CO     ','MeCHO     ', &
                  'C5H8      ','BC_fossil ','BC_biofuel','OC_fossil ', &
                  'OC_biofuel','Monoterp  ','NVOC      ','SO2_low   ', &
                  'SO2_high  ','DMS       ','NH3       ','SO2_nat   ', &
                  'BC_biomass','OC_biomass','NO_aircrft'/)

in the section of the IF block controlled by (L_ukca_strattrop .AND. L_ukca_achem).

Further down the code there is this block of code:

     J = n_use_tracers
     IF (n_chem_emissions+n_3d_emissions+n_mode_emissions > 0) THEN
       DO i=1,n_chem_emissions + n_3d_emissions
         UkcaD1Codes(J+i)%section    = 0
         UkcaD1Codes(J+i)%item       = n_emiss_first+i-1  ! trop chemistry
         UkcaD1Codes(J+i)%len_dim1   = row_length         ! uses stash codes
         UkcaD1Codes(J+i)%len_dim2   = rows               ! 301-309 for
         UkcaD1Codes(J+i)%required   = .true.             ! surface emissions
         UkcaD1Codes(J+i)%prognostic = .true.             ! from Section 0
! Special cases, emissions already available in UM
         IF (em_chem_spec(i)(1:7) == 'SO2_low') THEN
           UkcaD1Codes(J+i)%item     = 58
           IF (.NOT. L_SO2_SURFEM .AND. (L_ukca_aerchem .OR.           &
                                         L_ukca_achem)) THEN
             cmessage='SO2 surface emissions from UM are not flagged'
             errcode=58

             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:7) == 'SO2_nat') THEN
           UkcaD1Codes(J+i)%item     = 121
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
           IF (.NOT. L_SO2_NATEM .AND. (L_ukca_aerchem .OR.            &
                     L_ukca_achem)) THEN
             cmessage='SO2 natural emissions from UM are not flagged'
             errcode=121

             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:8) == 'SO2_high') THEN
           UkcaD1Codes(J+i)%item     = 126
           IF (.NOT. L_SO2_HILEM .AND. (L_ukca_aerchem .OR.            &
                                        L_ukca_achem)) THEN
             cmessage='SO2 high-level emissions are not flagged'
             errcode = UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:3) == 'NH3') THEN
           UkcaD1Codes(J+i)%item     = 127
           IF (.NOT. L_NH3_EM .AND. (L_ukca_aerchem .OR.               &
                                     L_ukca_achem)) THEN
             cmessage='NH3 surface emissions from UM are not flagged'
             errcode = UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i) == 'BC_fossil ') THEN
           UkcaD1Codes(J+i)%item = 310
         ELSEIF (em_chem_spec(i) == 'BC_biofuel') THEN
           UkcaD1Codes(J+i)%item = 311
         ELSEIF (em_chem_spec(i) == 'OC_fossil ') THEN
           UkcaD1Codes(J+i)%item = 312
         ELSEIF (em_chem_spec(i) == 'OC_biofuel') THEN
           UkcaD1Codes(J+i)%item = 313
         ELSEIF (em_chem_spec(i) == 'Monoterp  ') THEN
           UkcaD1Codes(J+i)%item = 314
         ELSEIF (em_chem_spec(i) == 'NVOC      ') THEN
           UkcaD1Codes(J+i)%item = 315
         ELSEIF (em_chem_spec(i) == 'BC_biomass') THEN
           UkcaD1Codes(J+i)%item = 322
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i) == 'OC_biomass') THEN
           UkcaD1Codes(J+i)%item = 323
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i) == 'SO2_biomas') THEN
           UkcaD1Codes(J+i)%item = 324
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i)(1:3) == 'DMS') THEN
           UkcaD1Codes(J+i)%section  = 17
           UkcaD1Codes(J+i)%item     = 205
           UkcaD1Codes(J+i)%prognostic = .false.
           IF (.NOT. L_DMS_EM .AND. (L_ukca_aerchem .OR.               &
                     L_ukca_achem)) THEN
             cmessage='DMS surface emissions from UM are not flagged'
             errcode = UkcaD1Codes(J+i)%section*1000 +                   &
                      UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:7) == 'NO_airc') THEN
           UkcaD1Codes(J+i)%item     = 340
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ENDIF
       ENDDO
     ENDIF

This block of code is rather complicated, but what it essentially means is that for the STASH codes 301-309, the emissions are assumed to be in the order of the species in em_chem_spec, but for the other emissions the STASH numbers are explicitly defined. As you can see from the table above, for 2D (surface) emissions the numbers 301-315 are reserved, and for 3D emissions the numbers 322, 323, and 340 are reserved.

This means that if you are adding in a new surface emission(s) it is best to use the slots 316-320, unless you need more than 5 slots. For 3D emissions you have more leeway.

Emissions STASHmaster File

Now that you have selected your slot(s), you need to create a new STASH specification for it/them. The easiest way to do this is to copy the existing user STASHmaster file that defines your current (possible) emissions, and extend that. This is found in Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills. This will be a different STASHmaster file to the one that contains the UKCA tracers, and e.g. in the UKCA Tutorial job, is called emiss_TCMIM_Aero.presm.

This contains entries like

#
1|    1 |    0 |  301 |NOx surf emissions                  |
2|    2 |    0 |    1 |    1 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |  531 |    0 |  129 |    0 |    0 |    0 |    0 |    0 |
# 
 
#
1|    1 |    0 |  340 |NOX AIRCRAFT EMS IN KG/S/GRIDCELL   |
2|    2 |    0 |    1 |    1 |    2 |   10 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |  520 |   20 |   65 |    0 |    0 |    0 | 9999 |    0 |
#

The top entry (NOx surf emissions) defines a 2D field, and the other (NOX AIRCRAFT EMS IN KG/S/GRIDCELL) defines a 3D field. You can see that there are differences in the numbers (other than the 301/340 item number) in various places in these specifications, which effectively (in this instance) tell STASH if the field is 2D or 3D.

Full details on what each of these numbers mean can be found in appendix 3 of Unified Model Documentation Paper C4 which can be found on the Met Office Collaboration Twiki (password required).

You should copy either the 2D or 3D specification, depending on what type of emission you are adding in, and edit only the STASH item number, name of field, and the field code. These can be found here:

#
1|    1 |    0 |  301 |NOx surf emissions                  |
2|    2 |    0 |    1 |    1 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000001 |    3 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |  531 |    0 |  129 |    0 |    0 |    0 |    0 |    0 |
# 

For the field code (531 above), if you were making a new emission at 316, it is advisable that you increase the current code above by 15 as well, e.g. 546. Xconv uses this field code for the name of the variable, so it is best to have them different. A listing of available field codes can be found on the NCAS CMS website, although these may be a little out of date.

You should make these changes to your copy of the original emissions user STASHmaster file, save this, and then replace the original file in the UMUI's Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancills table with your new file. Now go to Model Selection → Atmosphere → STASH → Initialisation of User Prognostics and scroll down the table until you find your new emission. Set the value in the Option column to 2 (Initialise to User Ancillary File).

As you need to make up a new ancillary file, you should copy this user STASHmaster file onto the supercomputer, as it will be needed by Xancil when you make the new ancillary file. It is advisable to put it in the same directory as the one containing your new emission(s) file.

Using Xancil

Extract your current emissions

Due to current limitations of the UM, you can only have one user single-level and one multi-level file. If you want to add a new emissions field, you must include the existing emissions in your new file along with it.

You can use Xconv to extract these fields. You must first find the location of the current file(s). To do this, go to Model Selection → Atmosphere → Ancillary data and input data files → Climatologies and potential climatologies and either open the User multi-level ancillary file & fields or User single-level ancillary file & fields panel. This will give two boxes giving the directory name or environment variable and the file name. This first box will contain an environment variable which sets the directory location. You can find the value of this environment variable in Model Selection → Input/Output Control and Resources → Time Convention and SCRIPT Environment Variables.

Once you have found the required file, extract all the fields within it to one of your own directories (ideally the one containing the netCDF file of your new emission(s)).

Make a new emissions ancillary file

Xancil is installed on both ARCHER at

/work/n02/n02/hum/bin/xancil

and on MONSooN (the postproc machine) at

/projects/um1/linux/bin/xancil

You may already have this location in your PATH and so can just launch Xancil from the command line by typing xancil. When you do this it will load up the Xancil window, which is initially rather empty. You should click on the Xancil text in the top-left corner. This will give 4 options:

  • Configuration
  • Atmosphere Ancillary Files
  • Ocean Ancillary Files
  • Generalised Ancillary Files

When using UKCA you will need to make use of all of these options, with the exception of the Ocean Ancillary Files.

You should view the Using Xancil page for more details on each of these sub-menus.

Load your netCDF and user STASHmaster files into the Xancil → Configuration panel, and define the vertical levels if you are making a 3D ancillary file.

Click on the Atmosphere Ancillary Files text and either open the Multi-level User Fields or Single-level User Fields panels. You should now

  • Set the output file name
  • Define the dates. If the ones in the netCDf file are fine to use then you can use them, or you can specify them. For this latter option you can either use the dates from the grid configuration panel, or you can define them again here
  • Enter the number of ancillary fields. This will need to be the total of the number of fields in the original ancillary file, plus the number of new emissions you are adding
  • For each individual field you should select it with the mouse, then
    • Define which netCDF file to use (it will remember the preference from the previous field)
    • Enter the STASH code (the PP code should be filled in automatically)
    • Either enter or confirm the variable name. Xancil takes the variable name from the field code defined in the STASHmaster file specification for each field. If there are multiple fields in the netCDF file with the same field code then Xancil may select the wrong one. If the name does not match a field code you will need to select it manually.

Once you have entered all the data for all fields you should

  • Use the Save/Save As button to save the job, as it may be needed later
  • Click the Output Anc. Files button to create the new ancillary file. Any errors will appear in the Output messages window, or to the terminal.

Use your new emissions file in the UMUI

Now that you have created your new emissions file you can use this in the UMUI. Go to Model Selection → Atmosphere → Ancillary data and input data files → Climatologies and potential climatologies and either open the User multi-level ancillary file & fields or User single-level ancillary file & fields panel, and set the Directory name or Environment Variable to the directory containing your new emissions file, and the file name to the name of your new file.

Note: On ARCHER this directory must be located on /work as the /home directory cannot be read at run time. This includes any symbolic links from /work to /home and vice versa.

Solution to Task 5.1: Create a new emissions file and use it in your job

Please see this page for a solution to Task 5.1

Task 5.2: make the required code changes to add your emission into UKCA

TASK 5.2: You should now make the UKCA code changes to add your emission into the ALICE tracer. No run-time processing of this surface emission is required. You will also need to add-in the molar-mass of ALICE.

Note: If you were unable to successfully complete Task 6.1 above, then please take a copy of the e job from the Tutorial experiment (Tutorial: solution to Task 5.1 - adding a new chemical emissions ancillary file) and work from there, as this will allow you to make only the changes required for this task. Please also make a new branch and merge-in branch fcm:um_br/dev/luke/vn8.4_UKCA_Tutorial_Solns at revision number 14692 to allow you to proceed.

You can also find a copy of an emissions ancillary file, with the required emissions, at

/work/n02/n02/ukca/Tutorial/vn8.4/Task5.1/solution/Task5.1_AR5_2000.anc

on ARCHER, and at

/projects/ukca/Tutorial/vn8.4/Task5.1/solution/Task5.1_AR5_2000.anc

on MONSooN.

Part 2. UKCA Code Changes

Changes to ukca_setd1defs.F90

The ukca_setd1defs.F90 tells UKCA what fields it should expect to find from the UM to allow it to run. Previously you edited this routine so that UKCA knew about your new tracers, now you must edited to tell it about your new emissions. This is done in two places

Add the species to em_chem_spec

You will need to find the em_chem_spec definition for the scheme that you are using. For example, the CheST/StratTrop chemistry is located in the Stratospheric Chemistry section and contained in the IF block controlled by (L_ukca_strattrop .AND. .NOT. L_ukca_achem) if you are not using aerosol chemistry, and by (L_ukca_strattrop .AND. L_ukca_achem) if you are using aerosol chemistry. For the former case this is defined by

            n_chem_emissions = 9
            n_3d_emissions = 1       ! aircraft NOX

            ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
            em_chem_spec =                                             &
                (/'NO        ','CH4       ','CO        ','HCHO      ', &
                  'C2H6      ','C3H8      ','Me2CO     ','MeCHO     ', &
                  'C5H8      ','NO_aircrft'/)

and for the latter case by

            n_chem_emissions = 21      ! em_chem_spec below
            n_3d_emissions   = 2       ! volc SO2 & aircraft NOX
            ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
            em_chem_spec =                                             &
                (/'NO        ','CH4       ','CO        ','HCHO      ', &
                  'C2H6      ','C3H8      ','Me2CO     ','MeCHO     ', &
                  'C5H8      ','BC_fossil ','BC_biofuel','OC_fossil ', &
                  'OC_biofuel','Monoterp  ','NVOC      ','SO2_low   ', &
                  'SO2_high  ','DMS       ','NH3       ','SO2_nat   ', &
                  'BC_biomass','OC_biomass','NO_aircrft'/)

You should edit the equivalent block. You should first increase the value of n_chem_emissions (for surface emissions) or n_3d_emissions (for 3D emissions) by the number of emissions that you are adding, and you should then add the names of the species (as they appear in the nm_spec array in ukca_setd1defs.F90, and how they appear in the CHCH_DEFS specification in the ukca_chem_scheme.F90 routine) that you are emitting into. Convention is that these are in ascending order by STASH code. The first 9 species in the above list are STASH codes 301-309, and 'NO_aircrft' is STASH code 340, so all new species should be placed before 'NO_aircrft' if you are not using aerosol chemistry, and before the 'SO2_low ' if you are. You should make sure that the size of em_chem_spec is correct for the number of species within it.

Tell UKCA the STASH code associated with your new emission

In the previous ukca_setd1defs.F90 discussion above we saw the following block of code

     J = n_use_tracers
     IF (n_chem_emissions+n_3d_emissions+n_mode_emissions > 0) THEN
       DO i=1,n_chem_emissions + n_3d_emissions
         UkcaD1Codes(J+i)%section    = 0
         UkcaD1Codes(J+i)%item       = n_emiss_first+i-1  ! trop chemistry
         UkcaD1Codes(J+i)%len_dim1   = row_length         ! uses stash codes
         UkcaD1Codes(J+i)%len_dim2   = rows               ! 301-309 for
         UkcaD1Codes(J+i)%required   = .true.             ! surface emissions
         UkcaD1Codes(J+i)%prognostic = .true.             ! from Section 0
! Special cases, emissions already available in UM
         IF (em_chem_spec(i)(1:7) == 'SO2_low') THEN
           UkcaD1Codes(J+i)%item     = 58
           IF (.NOT. L_SO2_SURFEM .AND. (L_ukca_aerchem .OR.           &
                                         L_ukca_achem)) THEN
             cmessage='SO2 surface emissions from UM are not flagged'
             errcode=58

             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:7) == 'SO2_nat') THEN
           UkcaD1Codes(J+i)%item     = 121
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
           IF (.NOT. L_SO2_NATEM .AND. (L_ukca_aerchem .OR.            &
                     L_ukca_achem)) THEN
             cmessage='SO2 natural emissions from UM are not flagged'
             errcode=121

             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:8) == 'SO2_high') THEN
           UkcaD1Codes(J+i)%item     = 126
           IF (.NOT. L_SO2_HILEM .AND. (L_ukca_aerchem .OR.            &
                                        L_ukca_achem)) THEN
             cmessage='SO2 high-level emissions are not flagged'
             errcode = UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:3) == 'NH3') THEN
           UkcaD1Codes(J+i)%item     = 127
           IF (.NOT. L_NH3_EM .AND. (L_ukca_aerchem .OR.               &
                                     L_ukca_achem)) THEN
             cmessage='NH3 surface emissions from UM are not flagged'
             errcode = UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i) == 'BC_fossil ') THEN
           UkcaD1Codes(J+i)%item = 310
         ELSEIF (em_chem_spec(i) == 'BC_biofuel') THEN
           UkcaD1Codes(J+i)%item = 311
         ELSEIF (em_chem_spec(i) == 'OC_fossil ') THEN
           UkcaD1Codes(J+i)%item = 312
         ELSEIF (em_chem_spec(i) == 'OC_biofuel') THEN
           UkcaD1Codes(J+i)%item = 313
         ELSEIF (em_chem_spec(i) == 'Monoterp  ') THEN
           UkcaD1Codes(J+i)%item = 314
         ELSEIF (em_chem_spec(i) == 'NVOC      ') THEN
           UkcaD1Codes(J+i)%item = 315
         ELSEIF (em_chem_spec(i) == 'BC_biomass') THEN
           UkcaD1Codes(J+i)%item = 322
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i) == 'OC_biomass') THEN
           UkcaD1Codes(J+i)%item = 323
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i) == 'SO2_biomas') THEN
           UkcaD1Codes(J+i)%item = 324
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ELSEIF (em_chem_spec(i)(1:3) == 'DMS') THEN
           UkcaD1Codes(J+i)%section  = 17
           UkcaD1Codes(J+i)%item     = 205
           UkcaD1Codes(J+i)%prognostic = .false.
           IF (.NOT. L_DMS_EM .AND. (L_ukca_aerchem .OR.               &
                     L_ukca_achem)) THEN
             cmessage='DMS surface emissions from UM are not flagged'
             errcode = UkcaD1Codes(J+i)%section*1000 +                   &
                      UkcaD1Codes(J+i)%item
             CALL EREPORT('UKCA_SETD1DEFS',errcode,cmessage)
           ENDIF
         ELSEIF (em_chem_spec(i)(1:7) == 'NO_airc') THEN
           UkcaD1Codes(J+i)%item     = 340
           UkcaD1Codes(J+i)%len_dim3 = tr_levels
         ENDIF
       ENDDO
     ENDIF

You will need to add code at the end of this block to tell UKCA what STASH code is associated with which species. The best thing to do is to copy one of the explict blocks at the end, and adjust accordingly, e.g.

For surface (2D) emissions you should add in the following

         ELSEIF (em_chem_spec(i) == 'Your Species') THEN
           UkcaD1Codes(J+i)%item = Your Species STASH code (301-320)

and for 3D emissions you should add in the following

         ELSEIF (em_chem_spec(i) == 'Your Species') THEN
           UkcaD1Codes(J+i)%item = Your Species STASH code (321-340)
           UkcaD1Codes(J+i)%len_dim3 = tr_levels

Remember that the character string length for a UKCA species is 10 characters.

Changes to ukca_constants.F90

As you are adding in an emission you may need to define the molar mass (in g/mol) of the species that you are emitting in to, if it is not already defined. Add this definition into ukca_constants.F90, e.g.

     ...
     REAL, PARAMETER :: m_co      =  28.
     REAL, PARAMETER :: m_hcho    =  30. 
     ...

Changes to ukca_emission_ctl.F90

You will need to ensure that the molmass array is filled for the tracer that you are emitting in to. This is filled in the WHERE block which has entries like

           ...
           WHERE (em_chem_spec == 'CO        ') molmass = m_co
           WHERE (em_chem_spec == 'HCHO      ') molmass = m_hcho
           ...

You should add an additional line for each new emission.

For surface emissions, unless your new emissions data requires further run-time processing, such as adding a diurnal cycle (see how isoprene (C5H8) is treated below), then you will not need to make too many additional changes to the ukca_emission_ctl.F90 routine. If you do need to add functionality such as this then you will need edit the following IF block:

       DO l=1,n_emissions
         IF (advt(k) == em_chem_spec(l) .AND.                         &
           em_chem_spec(l) == 'NO      ' ) THEN
!          Convert from kg NO2/m2/s to kg NO/m2/s
           em_field(:,:,k) = emissions(:,:,l)*m_no/m_no2
         ELSE IF (advt(k) == em_chem_spec(l)(1:3) .AND.                &
           em_chem_spec(l) == 'SO2_low ' ) THEN
!          Convert from kg S/m2/s to kg SO2/m2/s and take off sulphate fraction
           em_field(:,:,k) = emissions(:,:,l)*                         &
                              (1.0 - mode_parfrac/100.0)*m_so2/m_s
         ELSE IF (advt(k) == em_chem_spec(l) .AND.                     &
           em_chem_spec(l) == 'DMS     ' ) THEN
!          Convert from kg S/m2/s to kg DMS/m2/s
           em_field(:,:,k) = emissions(:,:,l)*m_dms/m_s
         ELSE IF (advt(k) == 'MeOH      ' .AND.                        &
           em_chem_spec(l) == 'NVOC      ' ) THEN
!          Convert from kg C/m2/s to kg CH3OH/m2/s
           em_field(:,:,k) = emissions(:,:,l)*meoh_factor*             &
               m_meoh/(m_c*3.0)
         ELSE IF (advt(k) == em_chem_spec(l) .AND.                    &
           em_chem_spec(l) == 'Monoterp  ' ) THEN
!          Convert from kg C/m2/s to kg C10H16/m2/s
           em_field(:,:,k) = emissions(:,:,l)*m_monoterp/(m_c*10.0)
!           === biogenic emissions ===
         ELSE IF (advt(k) == em_chem_spec(l) .AND.                    &
                 em_chem_spec(l) == 'C5H8      ') THEN
           IF (L_ukca_diurnal_isopems) THEN
             tmp_in_em_field(:,:) = emissions(:,:,l)*(m_isop/(5.0*m_c))
! DEPENDS ON: ukca_diurnal_isop_ems
!                testdcycl = .TRUE.
               CALL UKCA_DIURNAL_ISOP_EMS(row_length, rows,             &
                         tmp_in_em_field,  cos_zenith_angle,            &
                         int_zenith_angle,                              &
                         sin_theta_latitude, FV_cos_theta_latitude,     &
                         tan_theta_latitude, timestep, tmp_out_em_field,&
                         testdcycl)
               em_field(:,:,k) = tmp_out_em_field(:,:)
           ELSE
               em_field(:,:,k) = emissions(:,:,l)*(m_isop/(5.0*m_c))
           END IF
         ELSE IF (advt(k) == em_chem_spec(l) ) THEN
           em_field(:,:,k) = emissions(:,:,l)
         ENDIF             ! end advt(k)

If nothing needs to be done to the emissions field, then the final section

         ELSE IF (advt(k) == em_chem_spec(l) ) THEN
           em_field(:,:,k) = emissions(:,:,l)

just adds the emissions field from the ancillary file into the correct place to be emitted to the tracer.

After this is done the UM boundary layer mixing scheme is called (TR_MIX) for each tracer, and this is also where the emissions are added to the tracer field.

For 3D emissions you will need to explicitly add this into the required tracer using the TRSRCE subroutine. This is done for lightning emissions (calculated on-line) and aircraft emissions (read-in from the multi-level user ancillary file). You should copy what is done for e.g. aircraft emissions and adapt accordingly.

Solution to Task 5.2: make the required code changes to add your emission into UKCA

Please see this page for a solution to Task 5.2


Written by Luke Abraham 2014