Difference between revisions of "UKCA & UMUI Tutorial 6"

From UKCA
 
(58 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
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.
 
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.
   
ASAD considers four different types of chemical reactions: bimolecular reactions, trimolecular reactions, heterogeneous reactions, and photolysis reactions.
+
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
  +
  +
vn8.2_<span style="color:blue">your_branch_name</span>/src/atmosphere/UKCA
  +
  +
During this tutorial you will be tasked with adding a new reaction into your branch.
   
 
==Biomolecular Reactions==
 
==Biomolecular Reactions==
Line 15: Line 19:
 
</math>
 
</math>
   
===Chemistry Defition Routines===
+
===Bimolecular Reaction Definition===
   
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 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.
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.
 
   
To format of this '''ratb_t''' type is
+
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>',&
 
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>',&
'<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:green">Fraction of Product 3 produced</span>, <span style="color:purple">Fraction of Product 4 produced</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:green">Fraction of Product 3 produced</span>, <span style="color:purple">Fraction of Product 4 produced</span>), &
   
Where the fraction of a product can be set to 0.000 if this functionality does not need to be used, i.e. the fraction is 1.0.
+
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.
   
The specifications of the induvidual reactions are done as, e.g.
+
The specifications of the individual reactions are done as, e.g.
   
  +
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
 
ratb_t('OH ','C5H8 ','ISO2 ',' ',' ',& ! B144
 
' ', 2.70E-11, 0.00, -390.00, 0.000, 0.000, 0.000, 0.000), & ! B144 IUPAC2009
 
' ', 2.70E-11, 0.00, -390.00, 0.000, 0.000, 0.000, 0.000), & ! B144 IUPAC2009
Line 35: Line 42:
 
' ', 1.80E-12, 0.00, 250.00, 0.000, 0.000, 0.000, 0.000), & ! B159 JPL2011
 
' ', 1.80E-12, 0.00, 250.00, 0.000, 0.000, 0.000, 0.000), & ! B159 JPL2011
   
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 Laboritory]. 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].
+
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.
   
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> directory.
+
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.
   
 
===Increase the size of JPBK (and JPNR)===
 
===Increase the size of JPBK (and JPNR)===
Line 46: Line 53:
 
* '''JPNR''' is the total number of 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 value can be found by saving and processing the job, and then viewing the ''CNTLATM'' file in the <tt>$HOME/umui_jobs/<span style="color:blue">jobid</span></tt> directory.
+
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.
   
  +
==Termolecular Reactions==
===Task 6.1: Add a bimolecular reaction===
 
  +
  +
As well as defining reactions involving a third body, the termolecular rate definition can also be used to define unimolecular reactions.
  +
  +
The pressure and temperature dependent rate, <math>k</math>, of a termolecular reaction is given by
  +
  +
<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>
  +
  +
where the low pressure rate constant <math>k_{0}</math> is given by
  +
  +
<math>
  +
k_{0} = k_{1} \left(\frac{T}{300}\right)^{{\alpha}_{1}} \textrm{exp} \left(\frac{-{\beta}_{1}}{T}\right)
  +
</math>
  +
  +
and the high pressure rate constant <math>k_{\infty}</math> is given by
  +
  +
<math>
  +
k_{\infty} = k_{2} \left(\frac{T}{300}\right)^{{\alpha}_{2}} \textrm{exp} \left(\frac{-{\beta}_{2}}{T}\right)
  +
</math>
  +
  +
===Termolecular Reaction Definition===
  +
  +
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).
  +
  +
To format of this '''ratt_t''' type is
  +
  +
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>), &
  +
  +
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.
  +
  +
The <math>f</math> value is used to define the <math>F_{c}</math> value by
  +
  +
<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>
  +
  +
as <math>F_{c}</math> may or may not be highly temperature dependent.
  +
  +
Examples of these reactions are
  +
  +
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
  +
  +
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).
  +
  +
===Increase the size of JPTK (and JPNR)===
  +
  +
As with the bimolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are
  +
  +
* '''JPTK''' is the number of termolecular 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.
  +
  +
==Heterogeneous Reactions==
  +
  +
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.
  +
  +
===Heterogeneous Reaction Definition===
  +
  +
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
  +
  +
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
  +
  +
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), &
  +
  +
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'''.
  +
  +
===Increase the size of JPHK (and JPNR)===
  +
  +
As with the bimolecular and termolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are
  +
  +
* '''JPHK''' is the number of heterogeneous 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.
  +
  +
==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.
  +
  +
===Tropospheric Off-Line Photolysis===
  +
  +
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].
  +
  +
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
  +
  +
on HECToR, and in
  +
  +
/projects/um1/vn8.2/ctldata/UKCA/tropdata/photol
  +
  +
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'''.
  +
  +
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.
  +
  +
'''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
  +
  +
===Stratospheric Look-Up Table Photolysis===
  +
  +
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'''
  +
# Lary, D. and Pyle, J.: Diffuse-radiation, twilight, and photochemistry, J. Atmos. Chem., 13, 393–406, 1991.
  +
  +
===Interactive Photolysis===
  +
  +
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>
 
<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>
Line 66: Line 246:
 
|}
 
|}
   
  +
'''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 UKCA & UMUI Tutorial 6 Task 6.1 | Solution]]
 
   
  +
'''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]]
   
 
----
 
----

Latest revision as of 15:15, 15 July 2013

Back to UKCA & UMUI Tutorials

Adding new Chemical Reactions

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 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.

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

vn8.2_your_branch_name/src/atmosphere/UKCA

During this tutorial you will be tasked with adding a new reaction into your branch.

Biomolecular Reactions

For most bimolecular reactions, it is sufficient to provide the , , and coefficients that are used to compute the rate coefficient from the Arrhenius expression

Bimolecular Reaction Definition

The bimolecular reactions are defined in the ukca_chem_scheme.F90 routines using the ratb_t Fortran type specification, and are held in arrays. At the end of this routine the ratb_defs_scheme array is created from these, and if that scheme is selected in UKCA these reactions are copied across into the master ratb_defs array.

The format of this ratb_t type is

ratb_t('Reactant 1','Reactant 2','Product 1 ','Product 2 ','Product 3 ',&
'Product 4 ',  ,  ,  , Fraction of Product 1 produced, Fraction of Product 2 produced, &
Fraction of Product 3 produced, Fraction of Product 4 produced), & 

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.

The specifications of the individual reactions are done as, e.g.

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   

The first reaction in these examples takes its kinetic data from IUPAC. Going to this website, this reaction is defined here. The second reaction above takes its kinetic data from NASA's Jet Propulsion Laboratory. The rate for this can be found on page 1-19 of the JPL2011 document. When adding new reactions you will need to increment the size of the array holding the ratb_t type.

To add new bimolecular reactions you will need to append equivalent lines for the new reactions to the end of the ratb_defs_scheme 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 UKCA/ source-code directory.

Increase the size of JPBK (and JPNR)

As well as adding these reactions to the ukca_chem_scheme.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

  • JPBK is the number of bimolecular 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 &RUN_UKCA 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 $HOME/umui_jobs/jobid directory.

Termolecular Reactions

As well as defining reactions involving a third body, the termolecular rate definition can also be used to define unimolecular reactions.

The pressure and temperature dependent rate, , of a termolecular reaction is given by

where the low pressure rate constant is given by

and the high pressure rate constant is given by

Termolecular Reaction Definition

The termolecular reactions are defined in the ukca_chem_scheme.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).

To format of this ratt_t type is

ratt_t('Reactant 1','Reactant 2','Product 1 ','Product 2 ', , &
,  ,  , ,  ,  , Fraction of Product 1 produced, Fraction of Product 2 produced), & 

and as in ratb_t, where the fraction of a product should be set to 0.000 if this functionality does not need to be used.

The value is used to define the value by

If then
else

as may or may not be highly temperature dependent.

Examples of these reactions are

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  

To add new termolecular reactions you will need to append equivalent lines for the new reactions to the end of the ratt_defs_scheme array (increasing the array sizes accordingly).

Increase the size of JPTK (and JPNR)

As with the bimolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are

  • JPTK is the number of termolecular 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 &RUN_UKCA 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 $HOME/umui_jobs/jobid directory.

Heterogeneous Reactions

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.

Heterogeneous Reaction Definition

The heterogeneous reactions are defined in the ukca_chem_scheme.F90 routines using the rath_t Fortran type specification, usually in one array. To format of this rath_t type is

rath_t('Reactant 1','Reactant 2','Product 1 ','Product 2 ','Product 3 ',&
'Product 4 ', Fraction of Product 1 produced, Fraction of Product 2 produced, &
Fraction of Product 3 produced, Fraction of Product 4 produced), & 

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

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),                               &

To add new heterogeneous reactions you will need to append equivalent lines for the new reactions to the end of the ratt_defs_scheme array (increasing the array sizes accordingly), before adding code to either ukca_hetero_mod.F90 or asad_hetero.F90.

Increase the size of JPHK (and JPNR)

As with the bimolecular and termolecular reactions, you will also need to increase the values of two parameters that UKCA needs. These are

  • JPHK is the number of heterogeneous 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 &RUN_UKCA 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 $HOME/umui_jobs/jobid directory.

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.

Tropospheric Off-Line Photolysis

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].

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

on HECToR, and in

/projects/um1/vn8.2/ctldata/UKCA/tropdata/photol

on MONSooN. To use this scheme, in the UMUI go to Model Selection → Atmosphere → Model Configuration → UKCA Chemistry and Aerosols → 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.

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.

References

  1. Hough, A. M.: The calculation of photolysis rates for use in global modelling studies, Tech. rep., UK Atomic Energy Authority, Harwell, Oxon., UK, 1988
  2. 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

Stratospheric Look-Up Table Photolysis

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 → Atmosphere → Model Configuration → UKCA Chemistry and Aerosols → PHOTO and click 2D Photolysis Scheme. The code for this scheme is held in ukca_photolib.F90.

References

  1. Lary, D. and Pyle, J.: Diffuse-radiation, twilight, and photochemistry, J. Atmos. Chem., 13, 393–406, 1991.

Interactive Photolysis

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 → Atmosphere → Model Configuration → UKCA Chemistry and Aerosols → 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 UKCA/ 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 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

  1. 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
  2. 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
  3. 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_scheme.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','Product 1 ','Product 2 ','Product 3 ',&
'Product 4 ', Fraction of Product 1 produced, Fraction of Product 2 produced, &
Fraction of Product 3 produced, Fraction of Product 4 produced, 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 &RUN_UKCA 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 $HOME/umui_jobs/jobid directory.

Task 6.1: Add a bimolecular reaction

TASK 6.1: You should now add in the bimolecular reaction of ALICE with OH to form BOB. This reaction is given by:

Parameter Value
2.70E-11
0.00
-390.00

Note: If you were unable to successfully complete 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.

Remember: If you are using MONSooN you will need to delete/move any existing output files in your archive directory.

Solution


Written by Luke Abraham 2013