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

From UKCA
m (Protected "UKCA Chemistry and Aerosol Tutorial 9" ([edit=sysop] (indefinite) [move=sysop] (indefinite)) [cascading])
 
(9 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 learn in this Tutorial==
−
==Adding new Chemical Reactions==
  
   
  +
In this tutorial you will learn about the UKCA diagnostics package and the different diagnostics that you can output using it. You will also learn how to add new diagnostics from the new reactions and deposition that you have added.
−
UKCA currently uses two different methods of defining the chemical reactions solved in the model. The first is a backward Euler solver, and is used for the ''RAQ'' and ''StdTrop'' chemistry schemes where the solver itself is created by a code-writer. The second makes use of the [http://www.atm.ch.cam.ac.uk/acmsu/asad/ ASAD chemical integration software package], and is used for the ''CheT/TropIsop'', ''CheS/Strat'', and ''CheST/StratTrop'' chemistry schemes. ASAD can use many different solvers, although currently it uses symbolic Newton-Raphson solver. In this tutorial we will only consider the ASAD framework, as this is easily extended by a user.
  
   
  +
==Task 9.1: Output new diagnostics==
−
ASAD considers four different types of chemical reactions: bimolecular reactions, termolecular reactions, heterogeneous reactions, and photolysis reactions. To make changes and add reactions you will need to make changes to the UKCA source code which can be found in
 
   
  +
<span style="color:green">'''TASK 9.1:''' Output diagnostics of the reaction <math>\textrm{ALICE} + \textrm{OH} \longrightarrow \textrm{BOB} + \textrm{SEC\_ORG}</math> to STASH code '''34461''', the dry deposition of '''ALICE''' to STASH code '''34462''', and the wet deposition of '''BOB''' to '''34463'''. They should be outputted as a daily mean to the '''pa/UPA''' stream.</span>
−
vn8.2_<span style="color:blue">your_branch_name</span>/src/atmosphere/UKCA
  
   
  +
{| class="collapsible collapsed wikitable"
−
During this tutorial you will be tasked with adding a new reaction into your branch.
  
  +
|-
  +
! Hint
  +
|-
  +
| Remember to use the correct sampling frequency.
  +
|-
  +
|}
  +
  +
'''Note:''' If you were unable to successfully complete [[UKCA Chemistry and Aerosol Tutorial 8#Task 8.1: Add wet deposition of a species|Task 8.1]] , then please take a copy of the '''i''' job from the Tutorial experiment (''Tutorial: solution to Task 8.1 - add new wet deposition'') and work from there, as this will allow you to only make 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/src''' at revision number '''14713''' to allow you to proceed.
   
  +
==Adding New UKCA Diagnostics==
−
==Biomolecular Reactions==
  
   
  +
If you are using one of the chemistry schemes that uses ASAD (e.g. ''CheT/TropIsop'', ''CheS/Strat'', ''CheST/StratTrop'') then you can make use of the ASAD Reaction Flux Diagnostics module (held in '''asad_chem_flux_diags.F90'''). These allow you to straight-forwardly output new reaction and deposition fluxes.
−
For most bimolecular reactions, it is sufficient to provide the <math>k_{0}</math>, <math>\alpha</math>, and <math>\beta</math> coefficients that are used to compute the rate coefficient <math>k</math> from the Arrhenius expression
  
   
  +
To output new diagnostics you will first need to define them in the '''asad_flux_dat.F90''' module, and then create new STASHmaster file specifications for them.
−
<math>
  
−
k = k_{0} \left(\frac{T}{300}\right)^{\alpha} \textrm{exp} \left(\frac{-\beta}{T}\right)
  
−
</math>
  
   
  +
During this tutorial you will be tasked with outputting the reaction and deposition fluxes that you have added in to your branch.
−
===Bimolecular Reaction Definition===
  
   
  +
==Flux Definitions in asad_flux_dat.F90==
−
The bimolecular reactions are defined in the '''ukca_chem_<span style="color:blue">scheme</span>.F90''' routines using the '''ratb_t''' Fortran type specification, and are held in arrays. At the end of this routine the '''ratb_defs_<span style="color:blue">scheme</span>''' array is created from these, and if that scheme is selected in UKCA these reactions are copied across into the master '''ratb_defs''' array.
  
   
  +
Within the '''asad_flux_dat.F90''' module the diagnostics are defined in blocks with the format
−
The format of this '''ratb_t''' type is
  
   
−
ratb_t('Reactant 1','Reactant 2','<span style="color:blue">Product 1 </span>','<span style="color:red">Product 2 </span>','<span style="color:green">Product 3 </span>',&
 +
asad_flux_defn(<span style="color:blue">'Diagnostic type'</span>,<span style="color:red">STASH code</span>,<span style="color:blue">'Diagnostic specification'</span>,<span style="color:brown">Mask</span>,Reaction number,<span style="color:magenta">Number of species</span>, &
−
'<span style="color:purple">Product 4 </span>', <math>k_{0}</math>, <math>\alpha</math>, <math>\beta</math>, <span style="color:blue">Fraction of Product 1 produced</span>, <span style="color:red">Fraction of Product 2 produced</span>, &
 +
(/'<span style="color:purple">Species</span>/<span style="color:green">Reactant 1</span>','<span style="color:green">Reactant 2</span>'/), &
−
<span style="color:green">Fraction of Product 3 produced</span>, <span style="color:purple">Fraction of Product 4 produced</span>), &
+
(/'<span style="color:green">Product 1</span>','<span style="color:green">Product 2</span>','<span style="color:green">Product 3</span>','<span style="color:green">Product 4</span>'/)), &
   
  +
Which have the following meaning:
−
If fractional products are not required for a reaction, then the ''fraction of each product'' formed should be set to 0.000. If fractional products are required for any one of the products then the fraction of each product formed should be set to its correct value.
  
   
  +
===Diagnostic Type===
−
The specifications of the individual reactions are done as, e.g.
  
   
  +
This is a '''three character string''' which defines what type of diagnostic is being requested. This can take the values
−
ratb_t('O3 ','C5H8 ','HO2 ','OH ',' ',& ! B133
 
−
' ', 3.33E-15, 0.00, 1995.00, 0.750, 0.750, 0.000, 0.000), & ! B133 IUPAC2007*
 
−
...
  
−
ratb_t('OH ','C5H8 ','ISO2 ',' ',' ',& ! B144
 
−
' ', 2.70E-11, 0.00, -390.00, 0.000, 0.000, 0.000, 0.000), & ! B144 IUPAC2009
 
−
...
  
−
ratb_t('OH ','HCl ','H2O ','Cl ',' ',& ! B159
 
−
' ', 1.80E-12, 0.00, 250.00, 0.000, 0.000, 0.000, 0.000), & ! B159 JPL2011
 
   
  +
* '''RXN''' to output the flux through a reaction (in moles/gridcell/s)
−
The first reaction in these examples takes its kinetic data from [http://www.iupac-kinetic.ch.cam.ac.uk/ IUPAC]. Going to this website, this reaction is defined [http://www.iupac-kinetic.ch.cam.ac.uk/datasheets/xhtml/HOx_VOC8_HO_CH2C%28CH3%29CHCH2%28isoprene%29.xhtml_mathml.xml here]. The second reaction above takes its kinetic data from [http://jpldataeval.jpl.nasa.gov/ NASA's Jet Propulsion Laboratory]. The rate for this can be found on page 1-19 of the [http://jpldataeval.jpl.nasa.gov/pdf/JPL%2010-6%20Final%2015June2011.pdf JPL2011 document]. When adding new reactions you will need to increment the size of the array holding the <tt>ratb_t</tt> type.
  
  +
* '''DEP''' to output the deposition flux of a species (in moles/gridcell/s)
  +
* '''EMS''' to output the emission flux into a species (in moles/gridcell/s)
  +
* '''NET''' to output the net chemical tendency of a species (in moles/gridcell/s)
  +
* '''STE''' to output the net dynamical tendency of a species (in moles/gridcell/s)
  +
* '''MAS''' to output the mass of the atmosphere (in kg/gridcell)
  +
* '''PSC''' to output polar stratospheric cloud diagnostics (1 when the gridcell contains a PSC, 0 otherwise - monthly mean field will be a fraction in range 0 &rarr; 1)
  +
* '''TPM''' to output the tropospheric mask (1 for troposphere, 0 otherwise - monthly mean field will be a fraction in range 0 &rarr; 1)
  +
* '''OUT''' to output a tracer in mmr. Only really useful if the field is masked to give the tropospheric concentration only (see the discussion of the '''Mask''' option)
  +
* '''RTE''' to output the rate of a reaction (in gridcell/s)
   
  +
===STASH Code===
−
To add new bimolecular reactions you will need to append equivalent lines for the new reactions to the end of the '''ratb_defs_<span style="color:blue">scheme</span>''' array (increasing the array sizes accordingly). If there is a reaction that is an exception to the general Arrhenius equation then special code needs to be placed in the '''asad_bimol.F90''' routine, which is held in the <tt>UKCA/</tt> source-code directory.
  
   
  +
This is a '''5 digit integer''' defining the STASH code that the diagnostic will be outputted to (e.g. 34301). Currently this must be in '''section 34'''.
−
===Increase the size of JPBK (and JPNR)===
  
   
  +
===Diagnostic Specification===
−
As well as adding these reactions to the ''ukca_chem_<span style="color:blue">scheme</span>.F90'' routine (and incrementing the size of the arrays in that routine accordingly, you will also need to increase the values of two parameters that UKCA needs. These are
  
   
  +
This is a '''one character string''' which is needed to further define what diagnostic is required. If it isn't needed then it should just be set to '''X''' or left blank.
−
* '''JPBK''' is the number of bimolecular reactions
  
−
* '''JPNR''' is the total number of reactions
  
   
  +
* ''RXN''
−
These are set automatically in the UMUI (depending on what scheme is chosen), and are placed in the <code>&RUN_UKCA</code> namelist in '''CNTLATM'''. You will need to make a hand-edit to change these accordingly. The current values can be found by saving and processing the job, and then viewing the ''CNTLATM'' file in your <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory.
  
  +
** '''B''' to output the flux through a bimolecular reaction
  +
** '''T''' to output the flux through a termolecular reaction
  +
** '''H''' to output the flux through a heterogeneous reaction
  +
** '''J''' to output the flux through a photolysis reaction
  +
* ''DEP''
  +
** '''D''' to output the dry deposition flux
  +
** '''W''' to output the wet deposition flux
  +
* ''EMS''
  +
** '''S''' to output a surface emission (2D)
  +
** '''A''' to output aircraft emissions (3D)
  +
** '''L''' to output lightning emissions (3D)
  +
** '''V''' to output volcanic SO2 emissions (3D)
  +
** '''T''' to output SO2 emissions (3D)
  +
* ''PSC''
  +
** '''1''' to output the fraction of Type 1 PSCs
  +
** '''2''' to output the fraction of Type 2 PSCs
  +
* ''RTE''
  +
** '''B''' to output the rate of a bimolecular reaction
  +
** '''T''' to output the rate of a termolecular reaction
  +
** '''H''' to output the rate of a heterogeneous reaction
  +
** '''J''' to output the rate of a photolysis reaction
   
  +
===Mask===
−
==Termolecular Reactions==
  
   
  +
This is a '''logical''' which defines whether only the tropospheric values of the diagnostic are outputted ('''.TRUE.''') or not ('''.FALSE.'''). It is calculated every timestep.
−
As well as defining reactions involving a third body, the termolecular rate definition can also be used to define unimolecular reactions.
 
   
  +
For the ''STE'' diagnostic this is required if you wish to output the diagnosed stratosphere-troposphere exchange of a species. For the ''OUT'' diagnostic this can be used to output only the tropospheric concentration of a tracer. This is also used in the calculation of the of the ''TPM'' diagnostic.
−
The pressure and temperature dependent rate, <math>k</math>, of a termolecular reaction is given by
  
   
  +
===Reaction number===
−
<math>
  
−
k = \left(\frac{k_{0}\left[M\right]}{1+k_{0}\left[M\right]/k_{\infty}}\right)F_{c}^{\left(1+\left[\textrm{log}_{10}\left(\frac{k_{0}\left[M\right]}{k_{\infty}}\right)\right]^{2}\right)^{-1}}
  
−
</math>
  
   
  +
This is an '''integer''', and should only be used in the special case of there being two (or more) reactions with the exactly the same reactants and products, but with different rate coefficients. In this case the first reaction in the list would be given number '''1''' and the second '''2''' etc. If this is not needed then it should be set to '''0''' (which will be usual for most reactions).
−
where the low pressure rate constant <math>k_{0}</math> is given by
  
   
  +
===Number of Species===
−
<math>
  
−
k_{0} = k_{1} \left(\frac{T}{300}\right)^{{\alpha}_{1}} \textrm{exp} \left(\frac{-{\beta}_{1}}{T}\right)
  
−
</math>
  
   
  +
This is an '''integer''', and should give the total number of species, so this will be '''1''' for diagnostics such as ''DEP'', ''STE'', ''NET'' etc., which only consider a single species, and the '''total number of reactants and products''' for diagnostics ''RXN'' and ''RTE''.
−
and the high pressure rate constant <math>k_{\infty}</math> is given by
  
   
  +
===Species===
−
<math>
  
−
k_{\infty} = k_{2} \left(\frac{T}{300}\right)^{{\alpha}_{2}} \textrm{exp} \left(\frac{-{\beta}_{2}}{T}\right)
  
−
</math>
  
   
  +
This is a '''10-character string''' giving the exact name of the species that the diagnostic should be considered for (including capitalisation). This is only used for the ''DEP'', ''EMS'', ''NET'', ''STE'', and ''OUT''. For the ''RXN'' and ''RTE'' diagnostics the full list of reactants and products should be given (see below). For the ''MAS'', ''PSC'', and ''TPM'' diagnostics this isn't needed and could either be set to '''XXX''' or left blank. If it is needed the other reactant/product slots should be left blank.
−
===Termolecular Reaction Definition===
  
   
  +
===Reactants and Products===
−
The termolecular reactions are defined in the '''ukca_chem_<span style="color:blue">scheme</span>.F90''' routines using the '''ratt_t''' Fortran type specification, and are usually held in one single array (there are not usually enough reactions to require splitting the reactions over several arrays).
 
   
  +
These are '''10-character strings''', and should be as the reaction is defined in the '''ukca_chem_<span style="color:blue">scheme</span>.F90''' modules.
−
To format of this '''ratt_t''' type is
  
   
  +
===Addition of Diagnostics===
−
ratt_t('Reactant 1','Reactant 2','<span style="color:blue">Product 1 </span>','<span style="color:red">Product 2 </span>', <math>f</math>, &
  
−
<math>k_{1}</math>, <math>{\alpha}_{1}</math>, <math>{\beta}_{1}</math>, <math>k_{1}</math>, <math>{\alpha}_{1}</math>, <math>{\beta}_{1}</math>, <span style="color:blue">Fraction of Product 1 produced</span>, <span style="color:red">Fraction of Product 2 produced</span>), &
 
   
  +
If you define more than one diagnostic to be output to the same STASH code, then the diagnostic routines will sum these diagnostics together. This can be useful (e.g., if you wanted to output the sum of all NO+RO2 reactions to one STASH item), but can be problematic if you accidentally output two fields to the same STASH code, as this will give strange results!
−
and as in <tt>ratb_t</tt>, where the fraction of a product should be set to 0.000 if this functionality does not need to be used.
  
   
  +
===Changes to asad_flux_dat.F90===
−
The <math>f</math> value is used to define the <math>F_{c}</math> value by
  
   
  +
After you have defined your new diagnostics at the top of this module, you will need to make sure that they have been added correctly to the '''asad_chemical_fluxes''' array, which is defined in the '''ASAD_LOAD_DEFAULT_FLUXES''' subroutine held in the '''asad_flux_dat.F90'''.
−
<blockquote>
  
−
If <math>f < 1.0</math> then <math>F_{c} = f</math><br/>
  
−
else <math>F_{c} = \textrm{exp}\left(-T/f\right)</math>
  
−
</blockquote>
  
   
  +
==STASHmaster file==
−
as <math>F_{c}</math> may or may not be highly temperature dependent.
  
   
  +
While the diagnostics are defined in '''asad_flux_dat.F90''' they are turned on by requesting the item through STASH. To do this you will need to make a new STASHmaster file for diagnostics that you have defined yourself. The easiest option is to copy an existing diagnostic specification from the ''STASHmaster_A'' file, which is located at
−
Examples of these reactions are
  
   
  +
/work/n02/n02/hum/vn8.4/ctldata/STASHmaster/STASHmaster_A
−
ratt_t('N2O5 ','m ','NO2 ','NO3 ', 0.3, & ! T023
 
−
1.30E-03, -3.50, 11000.00, 9.70E+14, 0.10, 11080.00, 0.000, 0.000), & ! T023 IUPAC 2002
 
−
ratt_t('NO ','NO ','NO2 ','NO2 ', 0.0, & ! T024
 
−
3.30E-39, 0.00, -530.00, 0.00E+00, 0.00, 0.00, 0.000, 0.000) & ! T024 IUPAC 2001
 
   
  +
on ARCHER, and at
−
To add new termolecular reactions you will need to append equivalent lines for the new reactions to the end of the '''ratt_defs_<span style="color:blue">scheme</span>''' array (increasing the array sizes accordingly).
  
   
  +
/projects/um1/vn8.4/ctldata/STASHmaster/STASHmaster_A
−
===Increase the size of JPTK (and JPNR)===
  
   
  +
on MONSooN.
−
As with the bimolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are
  
   
  +
===2D Diagnostic Fields===
−
* '''JPTK''' is the number of termolecular reactions
  
−
* '''JPNR''' is the total number of reactions
  
   
  +
If you are outputting a 2D field such as a surface emission or a dry deposition field (e.g. you are using the old 2D dry deposition scheme) then the fact that this is a 2D surface field is defined in the STASHmaster entry, which looks like this e.g.
−
These are set automatically in the UMUI (depending on what scheme is chosen), and are placed in the <code>&RUN_UKCA</code> namelist in '''CNTLATM'''. You will need to make a hand-edit to change these accordingly. The current values can be found by saving and processing the job, and then viewing the ''CNTLATM'' file in your <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory.
  
   
  +
#
−
==Heterogeneous Reactions==
  
  +
1| 1 | 34 | <span style="color:red">321</span> |<span style="color:red">Ox BUDGET: O3 DRY DEPOSITION (2D)</span> |
  +
2| 0 | 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 | 1871 | 1 | 129 | 0 | 0 | 0 | 0 | 0 |
  +
#
   
  +
However, you can always output a surface diagnostic using a STASHmaster file that defines a 3D field, it is just that only the surface values will be non-zero (if the full field is output).
−
Heterogeneous reactions are those that occur on aerosol surfaces. There is no functional form defined for these reactions, with special code needed to be added for each case.
  
   
  +
You will need to edit the two elements in <span style="color:red">red</span> to match your new diagnostic.
−
===Heterogeneous Reaction Definition===
  
   
  +
===3D Diagnostic Fields===
−
The heterogeneous reactions are defined in the '''ukca_chem_<span style="color:blue">scheme</span>.F90''' routines using the '''rath_t''' Fortran type specification, usually in one array.
  
−
To format of this '''rath_t''' type is
  
   
  +
A 3D diagnostic field has slightly different values for some of the elements of the STASHmaster definition. These can been seen by comparing the specification above with the one below
−
rath_t('Reactant 1','Reactant 2','<span style="color:blue">Product 1 </span>','<span style="color:red">Product 2 </span>','<span style="color:green">Product 3 </span>',&
  
−
'<span style="color:purple">Product 4 </span>', <span style="color:blue">Fraction of Product 1 produced</span>, <span style="color:red">Fraction of Product 2 produced</span>, &
  
−
<span style="color:green">Fraction of Product 3 produced</span>, <span style="color:purple">Fraction of Product 4 produced</span>), &
 
   
  +
#
−
i.e. there is no rate information provided. For reactions on PSCs special code has been added to the routines in '''ukca_hetero_mod.F90''', and for other reactions there is code in '''asad_hetero.F90'''. Examples of this type are
  
  +
1| 1 | 34 | <span style="color:red">321</span> |<span style="color:red">Ox BUDGET: O3 DRY DEPOSITION (3D)</span> |
  +
2| 0 | 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 | 1871 | 0 | 65 | 0 | 0 | 0 | 0 | 0 |
  +
#
   
  +
You will need to edit the two elements in <span style="color:red">red</span> to match your new diagnostic.
−
rath_t('ClONO2 ','H2O ','HOCl ','HONO2 ',' ', &
  
−
' ', 0.000, 0.000, 0.000, 0.000), &
  
−
...
  
−
rath_t('SO2 ','H2O2 ','NULL0 ',' ',' ', & !HSO3+H2O2(aq)
  
−
' ', 0.000, 0.000, 0.000, 0.000), &
  
   
  +
===STASHmaster file format===
−
To add new heterogeneous reactions you will need to append equivalent lines for the new reactions to the end of the '''ratt_defs_<span style="color:blue">scheme</span>''' array (increasing the array sizes accordingly), before adding code to either '''ukca_hetero_mod.F90''' or '''asad_hetero.F90'''.
  
   
  +
As well as defining the STASH items in your new user STASHmaster file, you will also need to include the correct preamble and an end of file specifier. These are
−
===Increase the size of JPHK (and JPNR)===
  
   
  +
Preamble:
−
As with the bimolecular and termolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are
  
   
  +
H1| SUBMODEL_NUMBER=1
−
* '''JPHK''' is the number of heterogeneous reactions
  
  +
H2| SUBMODEL_NAME=ATMOS
−
* '''JPNR''' is the total number of reactions
  
  +
H3| UM_VERSION=8.4
  +
#
  +
#|Model |Sectn | Item |Name |
  +
#|Space |Point | Time | Grid |LevelT|LevelF|LevelL|PseudT|PseudF|PseudL|LevCom|
  +
#| Option Codes | Version Mask | Halo |
  +
#|DataT |DumpP | PC1 PC2 PC3 PC4 PC5 PC6 PC7 PC8 PC9 PCA |
  +
#|Rotate| PPF | USER | LBVC | BLEV | TLEV |RBLEVV| CFLL | CFFF |
  +
#
   
  +
which is also helpful in describing what the elements in the STASH specification are.
−
These are set automatically in the UMUI (depending on what scheme is chosen), and are placed in the <code>&RUN_UKCA</code> namelist in '''CNTLATM'''. You will need to make a hand-edit to change these accordingly. The current values can be found by saving and processing the job, and then viewing the ''CNTLATM'' file in your <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory.
  
   
  +
End of file specifier:
−
==Photolysis Reactions==
  
   
  +
#
−
These define a reaction where a chemical compound is broken down by photons. There is no functional form defined for this type of reaction. Instead, either (in the troposphere) input files are used to define the reaction rates for each species, while (in the stratosphere) on-line look-up tables are generated for the rates for each species, or separate photolysis codes, '''Fast-J''' or '''Fast-JX''', are used to interactively calculate the rate of reaction throughout the troposphere (for Fast-J) or the whole atmosphere (for Fast-JX). These interactive schemes are preferred as they take the effect of aerosols or clouds into account at each timestep, allowing for more feedbacks to be investigated. In the upper stratosphere there are some wavelength regions that Fast-JX does not consider, and so the 3D on-line look-up tables are also used for these regions.
  
  +
1| -1 | -1 | -1 |END OF FILE MARK |
  +
2| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
  +
3| 000000000000000000000000000000 | 00000000000000000000 | 0 |
  +
4| 0 | 0 | -99 -99 -99 -99 -30 -99 -99 -99 -99 -99 |
  +
5| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
  +
#
   
  +
===UMUI Changes===
−
===Tropospheric Off-Line Photolysis===
 
   
  +
After you have made your STASHmaster file with the required diagnostics, you should add it to the UMUI in '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; User-STASHmaster files. Diags, Progs & Ancils'''. You will also need to give it an initial value in '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; Initialisation of User Prognostics''' (you can just set it to '''zero''', i.e. '''3''' in the '''Option''' column). After you have done this you can select the diagnostic in the '''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; STASH. Specification of Diagnostics requirements''' panel.
−
If Fast-JX is not being used, then the off-line two-dimensional (zonally average) tropospheric photolysis is used (for all schemes). It is based on the work of Hough (1988)[1] and Law ''et al'' (1998)[2].
  
   
  +
==Time Validity==
−
This scheme makes use of datafiles which define the reaction rate for a particular species (e.g. H2O2), or if no rate is known, a '''nil''' rate can be used. For UM 8.2 these files (in ASCII format) can be found in
  
−
 
−
/work/n02/n02/hum/vn8.2/ctldata/UKCA/tropdata/photol
  
   
  +
When outputting UKCA reaction and deposition fluxes, you need to consider what time-points these diagnostics are valid at. Tracer fields are valid at all timesteps, but for reaction fluxes this is not the case. For all the chemistry schemes which use ASAD/Newton-Raphson (''CheT/TropIsop'', ''CheS/Strat'', and ''CheST/StratTrop''), the UKCA chemical timestep is every hour.
−
on HECToR, and in
  
   
  +
This means that when you output this diagnostic through STASH you need to change the ''sampling frequency''. To do this, go to the STASH panel in the UMUI ('''Model Selection &rarr; Atmosphere &rarr; STASH &rarr; STASH. Specification of Diagnostic requirements''') and '''copy''' the '''time profile''' you would like to use for the diagnostic to a new profile (giving it a similar, but slightly different name) and then change the '''sampling frequency''' to be
−
/projects/um1/vn8.2/ctldata/UKCA/tropdata/photol
  
   
  +
* '''Frequency (every)''' to be '''3'''
−
on MONSooN. To use this scheme, in the UMUI go to '''Model Selection &rarr; Atmosphere &rarr; Model Configuration &rarr; UKCA Chemistry and Aerosols &rarr; PHOTO''' and click '''2D Photolysis Scheme'''. You will then need to give the location of the files (above). The code controlling this scheme is held in '''ukca_phot2d.F90'''.
  
  +
* '''Offset''' to be '''2'''
   
  +
This will then sample the diagnostic on the UKCA timesteps. If you don't sample the diagnostic using this sampling frequency, then the output may be incorrect.
−
It is advised that this scheme is no longer used, and interactive photolysis should be used instead. For the ''CheS/Strat'' or ''CheST/StratTrop'' schemes, Fast-JX should be used as this covers the stratosphere as well as the troposphere.
  
   
  +
The following diagnostics are valid on '''all timesteps''':
−
'''References'''
  
−
# Hough, A. M.: The calculation of photolysis rates for use in global modelling studies, Tech. rep., UK Atomic Energy Authority, Harwell, Oxon., UK, 1988
  
−
# Law, K., Plantevin, P., Shallcross, D., Rogers, H., Pyle, J., Grouhel, C., Thouret, V., and Marenco, A.: Evaluation of modeled O3 using Measurement of Ozone by Airbus In-Service Aircraft (MOZAIC) data, J. Geophys. Res., 103, 25721–25737, 1998
  
   
  +
* ''MAS''
−
===Stratospheric Look-Up Table Photolysis===
  
  +
* ''OUT''
  +
* ''TPM''
  +
* ''STE''
  +
* ''EMS''
   
  +
The following diagnostics are only valid on '''chemical timesteps''':
−
In a chemistry scheme which has stratospheric chemistry, such as ''CheS/Strat'' and ''CheST/StratTrop'', if interactive photolysis is not used, then above 300hPa the look-up table approach of Lary and Pyle (1991)[1] is used (below 300hPa the tropospheric scheme described above is used). To use this scheme, in the UMUI go to '''Model Selection &rarr; Atmosphere &rarr; Model Configuration &rarr; UKCA Chemistry and Aerosols &rarr; PHOTO''' and click '''2D Photolysis Scheme'''. The code for this scheme is held in '''ukca_photolib.F90'''.
  
   
−
'''References'''
 +
* ''RXN''
  +
* ''DEP''
−
# Lary, D. and Pyle, J.: Diffuse-radiation, twilight, and photochemistry, J. Atmos. Chem., 13, 393–406, 1991.
  
  +
* ''RTE''
  +
* ''PSC''
   
  +
===Why should I use these numbers?===
−
===Interactive Photolysis===
  
   
  +
The standard N96L85 GA4.0 job has a timestep of 20-minutes (72 timesteps per day). This means that 1-hour is 3 timesteps, and the first timestep of a day is the 1st. An off-set of 2 will then mean outputting on the hour.
−
The Fast-J scheme (Wild ''et al'', 2000)[1] uses 7 different wavelength bins appropriate for the troposphere, and the Fast-JX scheme (Neu et al, 2007)[2] adds up to an extra 11 bins allowing use in the stratosphere.
  
−  
−
To use these schemes, in the UMUI go to '''Model Selection &rarr; Atmosphere &rarr; Model Configuration &rarr; UKCA Chemistry and Aerosols &rarr; PHOTO''' and click either '''FASTJ Photolysis Scheme''' or '''FASTJX Photolysis Scheme'''. You will then need to give the location of several input data files used by these schemes. The code for Fast-J is in the <tt>UKCA/</tt> directory in the '''fastj_*.F90''' files (controlled by '''ukca_fastj.F90'''), and the code for Fast-JX is in the '''fastjx_*.F90''' files (controlled by '''ukca_fastjx.F90''').
  
−  
−
Further details on the Fast-JX scheme, and how it is used in UKCA, can be found in [http://www.geosci-model-dev.net/6/161/2013/gmd-6-161-2013.html Telford ''et al'' (2013)][3].
  
−  
−
The Fast-J/Fast-JX data files are held in
 
−  
−
/work/n02/n02/hum/vn8.2/ctldata/UKCA/fastj
  
−  
−
on HECToR, and
 
−  
−
/projects/um1/vn8.2/ctldata/UKCA/fastj
  
−  
−
on MONSooN.
  
−  
−
'''References'''
  
−
# Wild, O., Zhu, X., and Prather, M.: Fast-J: accurate simulation of in- and below-cloud photolysis in tropospheric chemical models, J. Atmos. Chem., 37, 245–282, doi:10.1023/A:1006415919030, 2000
  
−
# Neu, J., Prather, M., and Penner, J.: Global atmospheric chemistry: integrating over fractional cloud cover, J. Geophys. Res., 112, D11306, 12 pp., doi:10.1029/2006JD008007, 2007
  
−
# Telford, P. J., Abraham, N. L., Archibald, A. T., Braesicke, P., Dalvi, M., Morgenstern, O., O'Connor, F. M., Richards, N. A. D., and Pyle, J. A.: Implementation of the Fast-JX Photolysis scheme (v6.4) into the UKCA component of the MetUM chemistry-climate model (v7.3), Geosci. Model Dev., 6, 161-177, doi:10.5194/gmd-6-161-2013, 2013.
  
−  
−
===Photolysis Reaction Definition===
  
−  
−
The photolysis reactions are defined in the '''ukca_chem_<span style="color:blue">scheme</span>.F90''' routines using the '''ratj_t''' Fortran type specification, usually in several arrays.
  
−
To format of this '''ratj_t''' type is
  
−  
−
ratj_t('Reactant 1','Reactant 2','<span style="color:blue">Product 1 </span>','<span style="color:red">Product 2 </span>','<span style="color:green">Product 3 </span>',&
  
−
'<span style="color:purple">Product 4 </span>', <span style="color:blue">Fraction of Product 1 produced</span>, <span style="color:red">Fraction of Product 2 produced</span>, &
  
−
<span style="color:green">Fraction of Product 3 produced</span>, <span style="color:purple">Fraction of Product 4 produced</span>, Quantum Yield, Look-up Label), &
 
−  
−
The '''Look-Up Label''' is used to define the file used for the 2D photolysis, and is used by Fast-J/Fast-JX to find the correct values for each species in the input data files. This is a 10-character string, although only the first '''7''' characters are read by Fast-JX.
  
−  
−
Examples of this type are
  
−  
−
ratj_t('H2O2 ','PHOTON ','OH ','OH ',' ', &
  
−
' ', 0.0, 0.0, 0.0, 0.0, 100.000,'jh2o2 ') , &
  
−
ratj_t('HCHO ','PHOTON ','HO2 ','HO2 ','CO ', &
  
−
' ', 0.0, 0.0, 0.0, 0.0, 100.000,'jhchoa ') , &
  
−  
−
===Increase the size of JPPJ (and JPNR)===
  
−  
−
As with the bimolecular, termolecular, and heterogeneous reactions, you will also need to increase the values of two parameters that UKCA needs. These are
  
−  
−
* '''JPPJ''' is the number of photolysis reactions
  
−
* '''JPNR''' is the total number of reactions
  
−  
−
These are set automatically in the UMUI (depending on what scheme is chosen), and are placed in the <code>&RUN_UKCA</code> namelist in '''CNTLATM'''. You will need to make a hand-edit to change these accordingly. The current values can be found by saving and processing the job, and then viewing the ''CNTLATM'' file in your <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory.
  
−  
−
==Task 6.1: Add a bimolecular reaction==
  
−  
−
<span style="color:green">'''TASK 6.1:''' You should now add in the bimolecular reaction of '''ALICE''' with '''OH''' to form '''BOB'''. This reaction is given by:</span>
  
−  
−
<math>
  
−
\textrm{ALICE} + \textrm{OH} \longrightarrow \textrm{BOB}
  
−
</math>
  
−  
−
{| border="1"
  
−
! Parameter || Value
  
−
|-
  
−
| <math>k_{0}</math> || 2.70E-11
  
−
|-
  
−
| <math>\alpha</math> || 0.00
  
−
|-
  
−
| <math>\beta</math> || -390.00
  
−
|}
  
   
  +
'''Note:''' If you are using a job with a different timestep you will need to change this sampling, as by default UKCA will still run with a 1-hour timestep.
−
'''Note:''' If you were unable to successfully complete [[UKCA & UMUI Tutorial 5#Task 5.2: make the required code changes to add your emission into UKCA| Task 5.2]], then please take a copy of the '''f''' job from the Tutorial experiment (''Tutorial: solution to Task 5.2 - adding new chemical emissions in UKCA'') and work from there, as this will allow you to only make the required changes.
  
   
  +
==Solution to Task 9.1: Output new diagnostics==
−
'''Remember:''' If you are using MONSooN you will need to delete/move any existing output files in your '''[[UKCA & UMUI Tutorials: Things to know before you start#Archiving|archive]]''' directory.
  
   
−
[[Solution to UKCA & UMUI Tutorial 6 Task 6.1 | Solution]]
 +
Please see [[Solution to UKCA Chemistry and Aerosol Tutorial 9 Task 9.1 |this page]] for a solution to [[#Task 9.1: Output new diagnostics|Task 9.1]].
   
 
----
  
----

Latest revision as of 15:29, 15 December 2015

Back to UKCA Chemistry and Aerosol Tutorials

What you will learn in this Tutorial

In this tutorial you will learn about the UKCA diagnostics package and the different diagnostics that you can output using it. You will also learn how to add new diagnostics from the new reactions and deposition that you have added.

Task 9.1: Output new diagnostics

TASK 9.1: Output diagnostics of the reaction to STASH code 34461, the dry deposition of ALICE to STASH code 34462, and the wet deposition of BOB to 34463. They should be outputted as a daily mean to the pa/UPA stream.

Note: If you were unable to successfully complete Task 8.1 , then please take a copy of the i job from the Tutorial experiment (Tutorial: solution to Task 8.1 - add new wet deposition) and work from there, as this will allow you to only make 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/src at revision number 14713 to allow you to proceed.

Adding New UKCA Diagnostics

If you are using one of the chemistry schemes that uses ASAD (e.g. CheT/TropIsop, CheS/Strat, CheST/StratTrop) then you can make use of the ASAD Reaction Flux Diagnostics module (held in asad_chem_flux_diags.F90). These allow you to straight-forwardly output new reaction and deposition fluxes.

To output new diagnostics you will first need to define them in the asad_flux_dat.F90 module, and then create new STASHmaster file specifications for them.

During this tutorial you will be tasked with outputting the reaction and deposition fluxes that you have added in to your branch.

Flux Definitions in asad_flux_dat.F90

Within the asad_flux_dat.F90 module the diagnostics are defined in blocks with the format 

      asad_flux_defn('Diagnostic type',STASH code,'Diagnostic specification',Mask,Reaction number,Number of species, &
      (/'Species/Reactant 1','Reactant 2'/),                                                                         &
      (/'Product 1','Product 2','Product 3','Product 4'/)),                                                          &

Which have the following meaning:

Diagnostic Type

This is a three character string which defines what type of diagnostic is being requested. This can take the values

  • RXN to output the flux through a reaction (in moles/gridcell/s)
  • DEP to output the deposition flux of a species (in moles/gridcell/s)
  • EMS to output the emission flux into a species (in moles/gridcell/s)
  • NET to output the net chemical tendency of a species (in moles/gridcell/s)
  • STE to output the net dynamical tendency of a species (in moles/gridcell/s)
  • MAS to output the mass of the atmosphere (in kg/gridcell)
  • PSC to output polar stratospheric cloud diagnostics (1 when the gridcell contains a PSC, 0 otherwise - monthly mean field will be a fraction in range 0 → 1)
  • TPM to output the tropospheric mask (1 for troposphere, 0 otherwise - monthly mean field will be a fraction in range 0 → 1)
  • OUT to output a tracer in mmr. Only really useful if the field is masked to give the tropospheric concentration only (see the discussion of the Mask option)
  • RTE to output the rate of a reaction (in gridcell/s)

STASH Code

This is a 5 digit integer defining the STASH code that the diagnostic will be outputted to (e.g. 34301). Currently this must be in section 34.

Diagnostic Specification

This is a one character string which is needed to further define what diagnostic is required. If it isn't needed then it should just be set to X or left blank.

  • RXN
    • B to output the flux through a bimolecular reaction
    • T to output the flux through a termolecular reaction
    • H to output the flux through a heterogeneous reaction
    • J to output the flux through a photolysis reaction
  • DEP
    • D to output the dry deposition flux
    • W to output the wet deposition flux
  • EMS
    • S to output a surface emission (2D)
    • A to output aircraft emissions (3D)
    • L to output lightning emissions (3D)
    • V to output volcanic SO2 emissions (3D)
    • T to output SO2 emissions (3D)
  • PSC
    • 1 to output the fraction of Type 1 PSCs
    • 2 to output the fraction of Type 2 PSCs
  • RTE
    • B to output the rate of a bimolecular reaction
    • T to output the rate of a termolecular reaction
    • H to output the rate of a heterogeneous reaction
    • J to output the rate of a photolysis reaction

Mask

This is a logical which defines whether only the tropospheric values of the diagnostic are outputted (.TRUE.) or not (.FALSE.). It is calculated every timestep.

For the STE diagnostic this is required if you wish to output the diagnosed stratosphere-troposphere exchange of a species. For the OUT diagnostic this can be used to output only the tropospheric concentration of a tracer. This is also used in the calculation of the of the TPM diagnostic.

Reaction number

This is an integer, and should only be used in the special case of there being two (or more) reactions with the exactly the same reactants and products, but with different rate coefficients. In this case the first reaction in the list would be given number 1 and the second 2 etc. If this is not needed then it should be set to 0 (which will be usual for most reactions).

Number of Species

This is an integer, and should give the total number of species, so this will be 1 for diagnostics such as DEP, STE, NET etc., which only consider a single species, and the total number of reactants and products for diagnostics RXN and RTE.

Species

This is a 10-character string giving the exact name of the species that the diagnostic should be considered for (including capitalisation). This is only used for the DEP, EMS, NET, STE, and OUT. For the RXN and RTE diagnostics the full list of reactants and products should be given (see below). For the MAS, PSC, and TPM diagnostics this isn't needed and could either be set to XXX or left blank. If it is needed the other reactant/product slots should be left blank.

Reactants and Products

These are 10-character strings, and should be as the reaction is defined in the ukca_chem_scheme.F90 modules.

Addition of Diagnostics

If you define more than one diagnostic to be output to the same STASH code, then the diagnostic routines will sum these diagnostics together. This can be useful (e.g., if you wanted to output the sum of all NO+RO2 reactions to one STASH item), but can be problematic if you accidentally output two fields to the same STASH code, as this will give strange results!

Changes to asad_flux_dat.F90

After you have defined your new diagnostics at the top of this module, you will need to make sure that they have been added correctly to the asad_chemical_fluxes array, which is defined in the ASAD_LOAD_DEFAULT_FLUXES subroutine held in the asad_flux_dat.F90.

STASHmaster file

While the diagnostics are defined in asad_flux_dat.F90 they are turned on by requesting the item through STASH. To do this you will need to make a new STASHmaster file for diagnostics that you have defined yourself. The easiest option is to copy an existing diagnostic specification from the STASHmaster_A file, which is located at 

/work/n02/n02/hum/vn8.4/ctldata/STASHmaster/STASHmaster_A

on ARCHER, and at 

/projects/um1/vn8.4/ctldata/STASHmaster/STASHmaster_A

on MONSooN.

2D Diagnostic Fields

If you are outputting a 2D field such as a surface emission or a dry deposition field (e.g. you are using the old 2D dry deposition scheme) then the fact that this is a 2D surface field is defined in the STASHmaster entry, which looks like this e.g. 

#
1|    1 |   34 |  321 |Ox BUDGET: O3 DRY DEPOSITION (2D)   |
2|    0 |    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 | 1871 |    1 |  129 |    0 |    0 |    0 |    0 |    0 |
#

However, you can always output a surface diagnostic using a STASHmaster file that defines a 3D field, it is just that only the surface values will be non-zero (if the full field is output).

You will need to edit the two elements in red to match your new diagnostic.

3D Diagnostic Fields

A 3D diagnostic field has slightly different values for some of the elements of the STASHmaster definition. These can been seen by comparing the specification above with the one below 

#
1|    1 |   34 |  321 |Ox BUDGET: O3 DRY DEPOSITION (3D)   |
2|    0 |    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 | 1871 |    0 |   65 |    0 |    0 |    0 |    0 |    0 |
#

You will need to edit the two elements in red to match your new diagnostic.

STASHmaster file format

As well as defining the STASH items in your new user STASHmaster file, you will also need to include the correct preamble and an end of file specifier. These are

Preamble: 

H1| SUBMODEL_NUMBER=1
H2| SUBMODEL_NAME=ATMOS
H3| UM_VERSION=8.4
#
#|Model |Sectn | Item |Name                                |
#|Space |Point | Time | Grid |LevelT|LevelF|LevelL|PseudT|PseudF|PseudL|LevCom|
#| Option Codes                   | Version Mask         | Halo |
#|DataT |DumpP | PC1  PC2  PC3  PC4  PC5  PC6  PC7  PC8  PC9  PCA |
#|Rotate| PPF  | USER | LBVC | BLEV | TLEV |RBLEVV| CFLL | CFFF |
#

which is also helpful in describing what the elements in the STASH specification are.

End of file specifier: 

#
1|   -1 |   -1 |   -1 |END OF FILE MARK                    |
2|    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000000 | 00000000000000000000 |    0 |
4|    0 |    0 | -99  -99  -99  -99  -30  -99  -99  -99  -99  -99 |
5|    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |    0 |
#

UMUI Changes

After you have made your STASHmaster file with the required diagnostics, you should add it to the UMUI in Model Selection → Atmosphere → STASH → User-STASHmaster files. Diags, Progs & Ancils. You will also need to give it an initial value in Model Selection → Atmosphere → STASH → Initialisation of User Prognostics (you can just set it to zero, i.e. 3 in the Option column). After you have done this you can select the diagnostic in the Model Selection → Atmosphere → STASH → STASH. Specification of Diagnostics requirements panel.

Time Validity

When outputting UKCA reaction and deposition fluxes, you need to consider what time-points these diagnostics are valid at. Tracer fields are valid at all timesteps, but for reaction fluxes this is not the case. For all the chemistry schemes which use ASAD/Newton-Raphson (CheT/TropIsop, CheS/Strat, and CheST/StratTrop), the UKCA chemical timestep is every hour.

This means that when you output this diagnostic through STASH you need to change the sampling frequency. To do this, go to the STASH panel in the UMUI (Model Selection → Atmosphere → STASH → STASH. Specification of Diagnostic requirements) and copy the time profile you would like to use for the diagnostic to a new profile (giving it a similar, but slightly different name) and then change the sampling frequency to be

  • Frequency (every) to be 3
  • Offset to be 2

This will then sample the diagnostic on the UKCA timesteps. If you don't sample the diagnostic using this sampling frequency, then the output may be incorrect.

The following diagnostics are valid on all timesteps:

  • MAS
  • OUT
  • TPM
  • STE
  • EMS

The following diagnostics are only valid on chemical timesteps:

  • RXN
  • DEP
  • RTE
  • PSC

Why should I use these numbers?

The standard N96L85 GA4.0 job has a timestep of 20-minutes (72 timesteps per day). This means that 1-hour is 3 timesteps, and the first timestep of a day is the 1st. An off-set of 2 will then mean outputting on the hour.

Note: If you are using a job with a different timestep you will need to change this sampling, as by default UKCA will still run with a 1-hour timestep.

Solution to Task 9.1: Output new diagnostics

Please see this page for a solution to Task 9.1.

Written by Luke Abraham 2014

Retrieved from "http://www.ukca.ac.uk/wiki/index.php?title=UKCA_Chemistry_and_Aerosol_Tutorial_9&oldid=4953"
Powered by MediaWiki