Difference between revisions of "UKCA Chemistry and Aerosol vn11.8 Tutorial 6"

From UKCA
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[UKCA Chemistry and Aerosol Tutorials at vn11.8]]
 
[[UKCA Chemistry and Aerosol Tutorials at vn11.8]]
  +
  +
{| class="wikitable" border = "1px"
  +
|-
  +
| Difficulty || '''<span style="color:orange">MEDIUM</span>'''
  +
|-
  +
| Time to Complete || '''1-2 hours'''
  +
|-
  +
| Video instructions || '''https://youtu.be/6XqYfW2qHKY?t=454'''
  +
|}
  +
  +
'''Remember to run <tt>mosrs-cache-password</tt> in your Rose suite and UM branch terminals.'''
   
 
==What you will learn in this tutorial==
 
==What you will learn in this tutorial==
Line 7: Line 18:
 
==Task 6.1: Add a bimolecular reaction==
 
==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''' and a '''''secondary organic compound''''' (labelled in UKCA as '''Sec_Org'''). 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''' and a '''''secondary organic compound''''' (labelled in UKCA as '''Sec_Org'''). You should use version '''111'''. This reaction is given by:</span>
   
 
<math>
 
<math>
Line 22: Line 33:
 
|-
 
|-
 
| <math>\beta</math> || -390.00
 
| <math>\beta</math> || -390.00
  +
|}
  +
  +
{| class="collapsible collapsed wikitable"
  +
|-
  +
! Hint
  +
|-
  +
| As <tt>Sec_Org</tt> is part of the aerosol chemistry, this reaction should be given the '''a''' qualifier. You should increment the value of <tt>nr_therm</tt> accordingly.
 
|}
 
|}
   
 
==Adding new Chemical Reactions==
 
==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 [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 a 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 a symbolic Backward Euler solver with Newton-Raphson iteration, which is known within UKCA as the ''"Newton Raphson"''. In this tutorial we will only consider the ASAD framework, as this is easily extended by a user. Further details on the solver implementation can be found in [https://gmd.copernicus.org/articles/11/3089/2018/ Esentürk ''et al.'' (2018)][1].
   
 
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
 
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
   
vn10.9_<span style="color:blue">your_branch_name</span>/src/atmosphere/UKCA
+
vn11.8_<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.
 
During this tutorial you will be tasked with adding a new reaction into your branch.
  +
  +
'''References'''
  +
# Esentürk, E., Abraham, N. L., Archer-Nicholls, S., Mitsakou, C., Griffiths, P., Archibald, A., and Pyle, J.: Quasi-Newton methods for atmospheric chemistry simulations: implementation in UKCA UM vn10.8, Geosci. Model Dev., 11, 3089–3108, https://doi.org/10.5194/gmd-11-3089-2018, 2018.
  +
  +
== Code Changes ==
  +
  +
=== <code>ukca_chem_master.F90</code> ===
  +
  +
You will need to add your reaction(s) to the appropriate array within the <tt>ukca_chem_master.F90</tt> module. Details covering what is required for each reaction type are below.
  +
  +
=== <code>ukca_config_defs_mod.F90</code> ===
  +
  +
Within the <tt>IF</tt> blocks for each chemistry scheme are variables called '''<tt>nr_therm</tt>''' (for all bimolecular, termolecular, and heterogeneous reactions) and '''<tt>nr_phot</tt>''' (for photolysis reactions). When adding reactions you should increment the appropriate variable for your configuration.
  +
  +
While these values are not used for the ASAD Newton Raphson based chemistry schemes, they are used by other schemes which use different solver (a hard-coded Backward Euler), which are the RAQ, Standard Tropospheric, and one configuration of the offline-oxidants scheme that is used to drive GLOMAP-mode in Global Atmosphere configurations.
   
 
==Biomolecular Reactions==
 
==Biomolecular Reactions==
Line 54: Line 87:
 
If fractional products are not required for a reaction, then the ''fraction of each product'' formed should be set to 0.00. 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.
 
If fractional products are not required for a reaction, then the ''fraction of each product'' formed should be set to 0.00. 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 settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
+
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn11.8_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
   
 
The specifications of the individual reactions are done as, e.g.
 
The specifications of the individual reactions are done as, e.g.
Line 71: Line 104:
 
ratb_t1(62,'HO2 ','O3 ','OH ','O2 ','O2 ', &
 
ratb_t1(62,'HO2 ','O3 ','OH ','O2 ','O2 ', &
 
' ',2.03e-16, 4.57, -693.00, 0.00, 0.00, 0.00, 0.00,s,0,0,107), &
 
' ',2.03e-16, 4.57, -693.00, 0.00, 0.00, 0.00, 0.00,s,0,0,107), &
  +
 
 
! B204
 
! B204
 
ratb_t1(204,'DMSO ','OH ','SO2 ',' ',' ', &
 
ratb_t1(204,'DMSO ','OH ','SO2 ',' ',' ', &
Line 80: Line 113:
 
' ',5.80e-11, 0.00, 0.00, 0.60, 0.40, 0.00, 0.00, st,a,0,117), &
 
' ',5.80e-11, 0.00, 0.00, 0.60, 0.40, 0.00, 0.00, st,a,0,117), &
   
The first 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-10 (with further description on page 1-51) of the [http://jpldataeval.jpl.nasa.gov/pdf/JPL%2010-6%20Final%2015June2011.pdf JPL2011 document]. The second reaction in these examples takes its kinetic data from '''[http://iupac.pole-ether.fr/ IUPAC]'''. Going to this website, this reaction is defined [http://iupac.pole-ether.fr/htdocs/datasheets/pdf/HOx15_HO2_O3.pdf here]. The third reaction shows the use of fractional products.
+
* The first 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-10 (with further description on page 1-51) of the [http://jpldataeval.jpl.nasa.gov/pdf/JPL%2010-6%20Final%2015June2011.pdf JPL2011 document].
  +
* The second reaction in these examples takes its kinetic data from '''[http://iupac.pole-ether.fr/ IUPAC]'''. Going to this website, this reaction is defined [http://iupac.pole-ether.fr/htdocs/datasheets/pdf/HOx15_HO2_O3.pdf here].
  +
* The third reaction shows the use of fractional products.
   
 
You can see that in the instances above, different chemistry schemes use slightly different rates or species, as may be required by the scheme and species considered.
 
You can see that in the instances above, different chemistry schemes use slightly different rates or species, as may be required by the scheme and species considered.
   
When adding new reactions you will need to increment the size of the array holding the <tt>ratb_t1</tt> type (<tt>n_bimol_master</tt>). Due to the large number of bimolecular reactions, the array containing them has been broken up into several blocks. If you are not adding new reactions to the last block (for instance, if you are adding a variation on an existing reaction) you will need to increment the '''stride''' as well, e.g.
+
When adding new reactions you will need to increment the size of the array holding the <tt>ratb_t1</tt> type ('''<tt>n_bimol_master</tt>'''). Due to the large number of bimolecular reactions, the array containing them has been broken up into several blocks. If you are not adding new reactions to the last block (for instance, if you are adding a variation on an existing reaction) you will need to increment the '''stride''' as well, e.g.
   
 
n_ratb_s = n_ratb_e+1
 
n_ratb_s = n_ratb_e+1
Line 132: Line 167:
 
and as in <code>rabt_t1</code>, where the fraction of a product should be set to 0.0 if this functionality does not need to be used.
 
and as in <code>rabt_t1</code>, where the fraction of a product should be set to 0.0 if this functionality does not need to be used.
   
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
+
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn11.8_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
   
 
The <math>f</math> value is used to define the <math>F_{c}</math> value by
 
The <math>f</math> value is used to define the <math>F_{c}</math> value by
Line 145: Line 180:
 
Examples of these reactions are
 
Examples of these reactions are
   
! T024 IUPAC 2001
+
! T004 JPL 2011
ratt_t1(24,'NO ','NO ','NO2 ','NO2 ', 0.0,&
+
ratt_t1(4,'O(1D) ','N2 ','N2O ','m ', 0.0, &
3.30e-39, 0.00,-530., 0.00e+00, 0.0, 0.0, 0.0, 0.0, T+ST,0,0,107),&
+
2.80e-36, -0.90, 0.00, 0.00e+00, 0.0, 0.0, 0.0, 0.0, st+cs,0,0,107), &
  +
! JPL 2003
! B; not in TI/TI scheme
 
ratt_t1(24,'NO ','NO ','NO2 ','NO2 ', 0.0,&
+
ratt_t1(4,'O(1D) ','N2 ','N2O ','m ', 0.0, &
6.93e-40, 0.00,-530., 0.00e+00, 0.0, 0.0, 0.0, 0.0, S,0,0,107),&
+
3.50e-37, -0.60, 0.00, 0.00e+00, 0.0, 0.0, 0.0, 0.0, s,0,0,107) , &
  +
! T005 JPL 2011
ratt_t1(25,'SO2 ','OH ','SO3 ','HO2 ', 0.6,&
 
  +
ratt_t1(5,'BrO ','NO2 ','BrONO2 ','m ', 0.6, &
3.00e-31, -3.30, 0.00, 1.50e-12, 0.0, 0.0, 0.0, 0.0, ST+S,A,0,107),&
 
  +
5.20e-31, -3.20, 0.00, 6.90e-12, 0.0, 0.0, 0.0, 0.0, st+cs,0,0,107), &
ratt_t1(25,'SO2 ','OH ','HO2 ','H2SO4 ', 0.6,&
 
  +
ratt_t1(5,'BrO ','NO2 ','BrONO2 ','m ', 327.0, &
3.00e-31, -3.30, 0.00, 1.50e-12, 0.0, 0.0, 0.0, 0.0, TI,A,0,107),&
 
ratt_t1(25,'SO2 ','OH ','H2SO4 ',' ', 0.6,&
+
4.70e-31, -3.10, 0.00, 1.40e-11, -1.2, 0.0, 0.0, 0.0, s,0,0,107) , &
3.00e-31, -3.30, 0.00, 1.50e-12, 0.0, 0.0, 0.0, 0.0, OL,A,0,107),&
 
   
   
To add new termolecular reactions you will need to append equivalent lines for the new reactions to the end of the '''<code>ratt_defs_master</code>''' array (increasing the array sizes accordingly). If there is any special code that needs to be added, this should be placed in the '''<code>asad_trimol.F90</code>''' routine, which is held in the <tt>UKCA/</tt> source-code directory.
+
To add new termolecular reactions you will need to append equivalent lines for the new reactions to the end of the '''<code>ratt_defs_master</code>''' array (increasing the array size '''<tt>n_ratt_master</tt>''' accordingly). If there is any special code that needs to be added, this should be placed in the '''<code>asad_trimol.F90</code>''' routine, which is held in the <tt>UKCA/</tt> source-code directory.
   
 
==Heterogeneous Reactions==
 
==Heterogeneous Reactions==
Line 177: Line 211:
 
i.e. there is no rate information provided. For reactions on PSCs special code has been added to the routines in '''<code>ukca_hetero_mod.F90</code>''', and for other reactions there is code in '''<code>asad_hetero.F90</code>'''.
 
i.e. there is no rate information provided. For reactions on PSCs special code has been added to the routines in '''<code>ukca_hetero_mod.F90</code>''', and for other reactions there is code in '''<code>asad_hetero.F90</code>'''.
   
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
+
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn11.8_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
   
 
Examples of this type are
 
Examples of this type are
   
nrath_t1(2,'ClONO2 ','HCl ','Cl ','Cl ','HONO2 ', &
+
rath_t1(5,'N2O5 ','HCl ','Cl ','NO2 ','HONO2 ', &
' ', 0.000, 0.000, 0.000, 0.000, S+ST,HP,0,107), &
+
' ', 0.000, 0.000, 0.000, 0.000, s+st+cs,hp,0,107), &
  +
rath_t1(6,'ClONO2 ','HBr ','BrCl ','HONO2 ',' ', &
!HSO3+H2O2(aq)
 
rath_t1(6,'SO2 ','H2O2 ','NULL0 ',' ',' ', &
+
' ', 0.000, 0.000, 0.000, 0.000, s+st+cs,eh,0,111), &
' ', 0.000, 0.000, 0.000, 0.000, TI+S+ST+OL+R,A,0,107), &
 
   
To add new heterogeneous reactions you will need to append equivalent lines for the new reactions to the end of the array (increasing the array sizes accordingly), before adding code to either '''<code>ukca_hetero_mod.F90</code>''' (for stratospheric reactions) or '''<code>asad_hetero.F90</code>''' (for tropospheric reactions).
+
To add new heterogeneous reactions you will need to append equivalent lines for the new reactions to the end of the <tt>rath_defs_master</tt> array (increasing the array size '''<tt>n_het_master</tt>''' accordingly), before adding code to either '''<code>ukca_hetero_mod.F90</code>''' (for stratospheric reactions) or '''<code>asad_hetero.F90</code>''' (for tropospheric reactions).
  +
  +
In the above block you can also see the use of the chemical mechanism version specification.
   
 
==Photolysis Reactions==
 
==Photolysis Reactions==
Line 195: Line 230:
 
===Tropospheric Off-Line Photolysis===
 
===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].
+
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)[2] and Law ''et al'' (1998)[3].
   
 
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 vn10.4 these files can be found in
 
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 vn10.4 these files can be found in
 
 
$UMDIR/vn10.4/ctldata/UKCA/tropdata/photol
+
$UMDIR/vn11.8/ctldata/UKCA/tropdata/photol
   
 
To use this scheme set the value of <code>i_ukca_photol</code> by clicking '''2D Photolysis Scheme'''. You will then need to give the location of the files (above). The code controlling this scheme is held in '''<code>ukca_phot2d.F90</code>'''.
 
To use this scheme set the value of <code>i_ukca_photol</code> by clicking '''2D Photolysis Scheme'''. You will then need to give the location of the files (above). The code controlling this scheme is held in '''<code>ukca_phot2d.F90</code>'''.
Line 206: Line 241:
   
 
'''References'''
 
'''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
+
# <li value="2"> 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
 
# 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===
 
===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 set the value of <code>i_ukca_photol</code> by clicking '''2D Photolysis Scheme'''. The code for this scheme is held in '''<code>ukca_strat_update.F90</code>'''.
+
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)[4] is used (below 300hPa the tropospheric scheme described above is used). To use this scheme set the value of <code>i_ukca_photol</code> by clicking '''2D Photolysis Scheme'''. The code for this scheme is held in '''<code>ukca_strat_update.F90</code>'''.
   
 
'''References'''
 
'''References'''
# Lary, D. and Pyle, J.: Diffuse-radiation, twilight, and photochemistry, J. Atmos. Chem., 13, 393–406, 1991.
+
# <li value="4"> Lary, D. and Pyle, J.: Diffuse-radiation, twilight, and photochemistry, J. Atmos. Chem., 13, 393–406, 1991.</li>
   
 
===Interactive Photolysis===
 
===Interactive Photolysis===
   
The original Fast-J scheme (Wild ''et al'', 2000)[1] uses 7 different wavelength bins appropriate for the troposphere, and the updated Fast-JX scheme (Neu et al, 2007)[2] adds up to an extra 11 bins allowing use in the stratosphere. At vn10.4 only Fast-JX is available, although previous UM version used Fast-J as well.
+
The original Fast-J scheme (Wild ''et al'', 2000)[5] uses 7 different wavelength bins appropriate for the troposphere, and the updated Fast-JX scheme (Neu et al, 2007)[6] adds up to an extra 11 bins allowing use in the stratosphere. At present only Fast-JX is available, although some previous UM versions used the older Fast-J scheme as well.
   
 
To use this scheme set the value of '''<code>i_ukca_photol</code>''' by clicking '''FastJ-X'''. You will then need to give the location of several input data files used by this scheme.
 
To use this scheme set the value of '''<code>i_ukca_photol</code>''' by clicking '''FastJ-X'''. You will then need to give the location of several input data files used by this scheme.
   
Further details on how the the Fast-JX scheme 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].
+
Further details on how the the Fast-JX scheme 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)][7].
   
 
The Fast-JX data files are held in
 
The Fast-JX data files are held in
   
$UMDIR/vn10.9/ctldata/UKCA/fastj
+
$UMDIR/vn11.8/ctldata/UKCA/fastj
   
 
on ARCHER.
 
on ARCHER.
   
 
'''References'''
 
'''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
+
# <li value="5"> 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</li>
 
# 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
 
# 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.
 
# 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.
Line 247: Line 282:
 
The '''Look-Up Label''' is used to define the file used for the 2D photolysis, and is used by 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. ''Reactant 2'' will always be ''PHOTON''.
 
The '''Look-Up Label''' is used to define the file used for the 2D photolysis, and is used by 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. ''Reactant 2'' will always be ''PHOTON''.
   
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
+
The settings for <code>N</code>, <code><span style="color:red">SCHEME</span></code>, <code><span style="color:green">QUALIFIER</span></code>, <code><span style="color:blue">DISQUALIFIER</span></code>, and <code>VN</code> are the same as in the [[UKCA_Chemistry_and_Aerosol_vn11.8_Tutorial_4#ukca_chem_master.F90|adding new tracers tutorial]], although here '''<code>N</code>''' should be incremented for each new '''reaction''', where there might be the same reaction specified several times with changes to reaction rates or even species.
   
 
Examples of this type are
 
Examples of this type are
Line 253: Line 288:
 
! 3
 
! 3
 
! This should produce H+ CHO -> H + HO2 + CO in ST scheme.
 
! This should produce H+ CHO -> H + HO2 + CO in ST scheme.
ratj_t1(3,'HCHO ','PHOTON ','HO2 ','HO2 ','CO ',&
+
ratj_t1(3,'HCHO ','PHOTON ','HO2 ','HO2 ','CO ', &
' ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa ',TI+T+ST+R,0,0,107) ,&
+
' ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa ',ti+t+st+r+cs,0,0,107),&
ratj_t1(3,'HCHO ','PHOTON ','H ','CO ','HO2 ',&
+
ratj_t1(3,'HCHO ','PHOTON ','H ','CO ','HO2 ', &
' ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa ',S,0,0,107) ,&
+
' ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa ',s,0,0,107) , &
 
! 4
 
! 4
ratj_t1(4,'HCHO ','PHOTON ','H2 ','CO ',' ',&
+
ratj_t1(4,'HCHO ','PHOTON ','H2 ','CO ',' ', &
' ', 0.0,0.0,0.0,0.0, 100.000,'jhchob ',TI+S+T+ST+R,0,0,107) ,&
+
' ', 0.0,0.0,0.0,0.0, 100.0,'jhchob ',ti+s+t+st+r+cs,0,0,107),&
  +
  +
To add new photolysis reactions you will need to append equivalent lines for the new reactions to the end of the <tt>ratj_defs_master</tt> array (increasing the array size '''<tt>n_ratj_master</tt>''' accordingly), adding new files/code as necessary as described above.
   
 
==Solution to Task 6.1: Add a bimolecular reaction==
 
==Solution to Task 6.1: Add a bimolecular reaction==
 
[[Image:Vn10.9_s34i065_addrxn.png|thumb|300px|right|Surface level concentrations (kg/kg) of BOB after the reaction has been applied.]]
 
   
 
You were given the task
 
You were given the task
   
* ''You should now add in the bimolecular reaction of '''ALICE''' with '''OH''' to form '''BOB''' and a '''''secondary organic compound''''' (labelled in UKCA as '''Sec_Org'''). This reaction is given by:''
+
* ''You should now add in the bimolecular reaction of '''ALICE''' with '''OH''' to form '''BOB''' and a '''secondary organic compound''' (labelled in UKCA as '''Sec_Org'''). You should use version '''111'''. This reaction is given by:''
   
 
<math>
 
<math>
\textrm{ALICE} + \textrm{OH} \longrightarrow \textrm{BOB} + \textrm{Sec\_Org}
+
\textrm{ALICE} + \textrm{OH} \longrightarrow \textrm{BOB} + \textrm{Sec}\_\textrm{Org}
 
</math>
 
</math>
   
Line 283: Line 318:
 
| <math>\beta</math> || -390.00
 
| <math>\beta</math> || -390.00
 
|}
 
|}
  +
  +
You were given the hint
  +
* ''As <tt>Sec_Org</tt> is part of the aerosol chemistry, this reaction should be given the '''a''' qualifier. You should increment the value of <tt>nr_therm</tt> accordingly.''
  +
  +
[[Image:UM11.8_s34i499_Task061.png|thumb|300px|right|Surface level concentrations (kg/kg) of BOB after the reaction has been applied.]]
   
 
For a working Rose suite that has completed this task, please see
 
For a working Rose suite that has completed this task, please see
* '''ARCHER:''' <code>u-as292@60067</code>
+
* '''vm:''' <code>u-ca024@182668</code>
* '''vm:''' <code>u-as297@59986</code>
 
   
 
The specific Rose changes made are:
 
The specific Rose changes made are:
  +
* '''vm:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/182668/c/a/0/2/4/trunk
 
* '''ARCHER:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/60067/a/s/2/9/2/trunk
 
* '''vm:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/59986/a/s/2/9/7/trunk
 
   
 
The specific Rose changes made are:
 
The specific Rose changes made are:
 
'''ARCHER:'''
 
Index: app/fcm_make/rose-app.conf
 
===================================================================
 
--- app/fcm_make/rose-app.conf (revision 59937)
 
+++ app/fcm_make/rose-app.conf (revision 60067)
 
@@ -42,4 +42,4 @@
 
stash_version=1A
 
timer_version=3A
 
um_rev=vn10.9
 
-um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46574
 
+um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46619
 
 
These differences can be found in the file '''<code>/home/ukca/Tutorial/vn10.9/worked_solutions/Task6.1/Task6.1_rose.patch</code>''' on PUMA.
 
   
 
'''vm:'''
 
'''vm:'''
 
Index: app/fcm_make/rose-app.conf
 
Index: app/fcm_make/rose-app.conf
 
===================================================================
 
===================================================================
--- app/fcm_make/rose-app.conf (revision 59931)
+
--- app/fcm_make/rose-app.conf (revision 182503)
+++ app/fcm_make/rose-app.conf (revision 59986)
+
+++ app/fcm_make/rose-app.conf (revision 182668)
@@ -42,4 +42,4 @@
+
@@ -43,4 +43,4 @@
  +
thread_utils=false
stash_version=1A
 
 
timer_version=3A
 
timer_version=3A
um_rev=vn10.9
+
um_rev=$BASE_UM_REV
-um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46574
+
-um_sources=branches/dev/lukeabraham/vn11.8_UKCA_Tutorial_Solns@93871
+um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46619
+
+um_sources=branches/dev/lukeabraham/vn11.8_UKCA_Tutorial_Solns@94024
  +
  +
These differences can be found in the file '''<code>Tutorials/vn11.8/worked_solutions/Task06.1/Task06.1_rose.patch</code>'''.
   
 
The specific UM changes made are:
 
The specific UM changes made are:
  +
* https://code.metoffice.gov.uk/trac/um/changeset/94024/main/branches/dev/lukeabraham/vn11.8_UKCA_Tutorial_Solns
   
 
Index: src/atmosphere/UKCA/ukca_chem_master.F90
 
Index: src/atmosphere/UKCA/ukca_chem_master.F90
 
===================================================================
 
===================================================================
--- src/atmosphere/UKCA/ukca_chem_master.F90 (revision 46574)
+
--- src/atmosphere/UKCA/ukca_chem_master.F90 (revision 93871)
+++ src/atmosphere/UKCA/ukca_chem_master.F90 (revision 46619)
+
+++ src/atmosphere/UKCA/ukca_chem_master.F90 (revision 94024)
@@ -83,7 +83,7 @@
+
@@ -98,7 +98,7 @@
INTEGER, PARAMETER :: n_het_master = 10 ! number of heterogeneous reactions
+
INTEGER, PARAMETER :: n_het_master = 18 ! number of heterogeneous reactions
INTEGER, PARAMETER :: n_dry_master = 57 ! number of dry deposition reactions
+
INTEGER, PARAMETER :: n_dry_master = 149 ! number of dry deposition reactions
INTEGER, PARAMETER :: n_wet_master = 49 ! number of wet deposition reactions
+
INTEGER, PARAMETER :: n_wet_master = 106 ! number of wet deposition reactions
-INTEGER, PARAMETER :: n_bimol_master= 400 ! number of bimolecular reactions
+
-INTEGER, PARAMETER :: n_bimol_master= 854 ! number of bimolecular reactions
+INTEGER, PARAMETER :: n_bimol_master= 401 ! number of bimolecular reactions
+
+INTEGER, PARAMETER :: n_bimol_master= 855 ! number of bimolecular reactions
INTEGER, PARAMETER :: n_ratj_master = 76 ! number of photolysis reactions
+
INTEGER, PARAMETER :: n_ratj_master = 158 ! number of photolysis reactions
INTEGER, PARAMETER :: n_ratt_master = 49 ! number of termolecular reactions
+
INTEGER, PARAMETER :: n_ratt_master = 76 ! number of termolecular reactions
 
 
@@ -2152,7 +2152,9 @@
+
@@ -4712,7 +4712,9 @@
ratb_t1(276,'MACRO2 ','MeOO ','MGLY ','HACET ','MeCO3 ',&
+
'H2O ',9.00e-11, 0.00, 0.00, 0.95, 0.05, 0.05, 1.00,cs,a,0,107), &
  +
! B697
'HCHO ',1.00e-12, 0.00, 0.00, 1.00, 0.75, 0.25, 2.75, TI,0,0,107),&
 
ratb_t1(277,'MACRO2 ','MeOO ','HO2 ','CO ',' ',&
+
ratb_t1(697,'MSIA ','NO3 ','MeSO2 ','HONO2 ',' ', &
-' ',1.00e-12, 0.00, 0.00, 1.17, 0.25, 0.00, 0.00, TI,0,0,107) /)
+
-' ',1.00e-13, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00,cs,a,0,107) &
+' ',1.00e-12, 0.00, 0.00, 1.17, 0.25, 0.00, 0.00, TI,0,0,107),&
+
+' ',1.00e-13, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00,cs,a,0,107), &
+ratb_t1(278,'ALICE ','OH ','BOB ','Sec_Org ',' ',&
+
+ratb_t1(698,'ALICE ','OH ','BOB ','Sec_Org ',' ', &
+' ',2.70E-11, 0.00, -390.00, 0.00, 0.00, 0.00, 0.00, ST,0,0,107) /)
+
+' ',2.70E-11, 0.00, -390.00, 0.00, 0.00, 0.00, 0.00,st,a,0,111) &
  +
/)
  +
  +
  +
Index: src/atmosphere/UKCA/ukca_config_defs_mod.F90
  +
===================================================================
  +
--- src/atmosphere/UKCA/ukca_config_defs_mod.F90 (revision 93871)
  +
+++ src/atmosphere/UKCA/ukca_config_defs_mod.F90 (revision 94024)
  +
@@ -333,9 +333,9 @@
  +
n_aero_tracers = 12
  +
n_chem_tracers = 73 ! No chem tracers
  +
IF (ukca_config%l_ukca_trophet) THEN
  +
- nr_therm = 241 ! thermal reactions
  +
+ nr_therm = 242 ! thermal reactions
  +
ELSE
  +
- nr_therm = 239 ! thermal reactions
  +
+ nr_therm = 240 ! thermal reactions
  +
END IF
  +
nr_phot = 59 ! photolytic (ATA)
 
 
!----------------------------------------------------------------------
 
! NOTES: CheST Bimolecular Reactions
 
   
These differences can be found in the file '''<code>/home/ukca/Tutorial/vn10.9/worked_solutions/Task6.1/Task6.1_code.patch</code>''' on PUMA.
+
These differences can be found in the file '''<code>Tutorials/vn11.8/worked_solutions/Task06.1/Task06.1_code.patch</code>'''.
   
Sample output from this task can be found at '''<code>/work/n02/n02/ukca/Tutorial/vn10.9/sample_output/Task6.1/atmosa.pa19810901_00</code>''' on ARCHER.
+
Sample output from this task can be found at '''<code>Tutorials/vn11.8/sample_output/Task06.1/atmosa.pa19810901_00</code>'''.
   
 
==Checklist==
 
==Checklist==
   
 
: <span style="font-size:20px">☐</span> Add the new reaction into the correct reaction type array in <code>ukca_chem_master.F90</code>, incrementing the size of the array accordingly.
 
: <span style="font-size:20px">☐</span> Add the new reaction into the correct reaction type array in <code>ukca_chem_master.F90</code>, incrementing the size of the array accordingly.
  +
: <span style="font-size:20px">☐</span> Increment the value of <tt>nr_therm</tt> and/or <tt>nr_phot</tt> in <code>ukca_config_defs_mod.F90</code>.
 
: <span style="font-size:20px">☐</span> If required, add special code to the <code>asad_bimol.F90</code>, <code>asad_trimol.F90</code>, <code>ukca_hetero_mod.F90</code>, or <code>asad_hetero.F90</code> routines.
 
: <span style="font-size:20px">☐</span> If required, add special code to the <code>asad_bimol.F90</code>, <code>asad_trimol.F90</code>, <code>ukca_hetero_mod.F90</code>, or <code>asad_hetero.F90</code> routines.
 
: <span style="font-size:20px">☐</span> For photolysis reactions, further work is required to calculate new cross sections. Code will also need to be added to <code>ukca_strat_update.F90</code>.
 
: <span style="font-size:20px">☐</span> For photolysis reactions, further work is required to calculate new cross sections. Code will also need to be added to <code>ukca_strat_update.F90</code>.

Latest revision as of 09:41, 4 February 2021

UKCA Chemistry and Aerosol Tutorials at vn11.8

Difficulty MEDIUM
Time to Complete 1-2 hours
Video instructions https://youtu.be/6XqYfW2qHKY?t=454

Remember to run mosrs-cache-password in your Rose suite and UM branch terminals.

What you will learn in this tutorial

During this tutorial you will learn how UKCA specifies different chemical reactions. You will then add a new reaction involving the new tracers that you have added.

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 and a secondary organic compound (labelled in UKCA as Sec_Org). You should use version 111. This reaction is given by:

Parameter Value
2.70E-11
0.00
-390.00

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 a symbolic Backward Euler solver with Newton-Raphson iteration, which is known within UKCA as the "Newton Raphson". In this tutorial we will only consider the ASAD framework, as this is easily extended by a user. Further details on the solver implementation can be found in Esentürk et al. (2018)[1].

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

vn11.8_your_branch_name/src/atmosphere/UKCA

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

References

  1. Esentürk, E., Abraham, N. L., Archer-Nicholls, S., Mitsakou, C., Griffiths, P., Archibald, A., and Pyle, J.: Quasi-Newton methods for atmospheric chemistry simulations: implementation in UKCA UM vn10.8, Geosci. Model Dev., 11, 3089–3108, https://doi.org/10.5194/gmd-11-3089-2018, 2018.

Code Changes

ukca_chem_master.F90

You will need to add your reaction(s) to the appropriate array within the ukca_chem_master.F90 module. Details covering what is required for each reaction type are below.

ukca_config_defs_mod.F90

Within the IF blocks for each chemistry scheme are variables called nr_therm (for all bimolecular, termolecular, and heterogeneous reactions) and nr_phot (for photolysis reactions). When adding reactions you should increment the appropriate variable for your configuration.

While these values are not used for the ASAD Newton Raphson based chemistry schemes, they are used by other schemes which use different solver (a hard-coded Backward Euler), which are the RAQ, Standard Tropospheric, and one configuration of the offline-oxidants scheme that is used to drive GLOMAP-mode in Global Atmosphere configurations.

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_master.F90 module using the ratb_t1 Fortran type specification, and are held in arrays. At the end of this routine the ratb_defs_master 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_t1 type (defined in ukca_chem_defs_mod.F90) is

ratb_t1(N, '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, SCHEME, QUALIFIER, DISQUALIFIER, VN), & 

If fractional products are not required for a reaction, then the fraction of each product formed should be set to 0.00. 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 settings for N, SCHEME, QUALIFIER, DISQUALIFIER, and VN are the same as in the adding new tracers tutorial, although here N should be incremented for each new reaction, where there might be the same reaction specified several times with changes to reaction rates or even species.

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

! B060 JPL2011
ratb_t1(60,'HO2       ','NO        ','OH        ','NO2       ','          ',   &
'          ',3.30e-12,  0.00, -270.00, 0.00, 0.00, 0.00, 0.00,st+r,0,0,107),   &
ratb_t1(60,'HO2       ','NO        ','OH        ','NO2       ','          ',   &
'          ',3.50e-12,  0.00, -250.00, 0.00, 0.00, 0.00, 0.00,s,0,0,107),      &
ratb_t1(60,'HO2       ','NO        ','OH        ','NO2       ','          ',   &
'          ',3.60e-12,  0.00, -270.00, 0.00, 0.00, 0.00, 0.00,ti+t+cs,0,0,107),&

! B062 IUPAC2001
ratb_t1(62,'HO2       ','O3        ','OH        ','O2        ','          ',   &
'          ',2.03e-16,  4.57, -693.00, 0.0, 0.0,0.0,0.0,ti+t+st+r+cs,0,0,107), &
ratb_t1(62,'HO2       ','O3        ','OH        ','O2        ','O2        ',   &
'          ',2.03e-16,  4.57, -693.00, 0.00, 0.00, 0.00, 0.00,s,0,0,107),      &

! B204
ratb_t1(204,'DMSO      ','OH        ','SO2       ','          ','          ',  &
'          ',5.80e-11,  0.00,    0.00, 0.60, 0.00, 0.00, 0.00, ol+r,a,0,107),  &
ratb_t1(204,'DMSO      ','OH        ','SO2       ','MSA       ','          ',  &
'          ',5.80e-11,  0.00,    0.00, 0.60, 0.40, 0.00, 0.00, ti,a,0,107),    &
ratb_t1(204,'DMSO      ','OH        ','SO2       ','MSA       ','          ',  &
'          ',5.80e-11,  0.00,    0.00, 0.60, 0.40, 0.00, 0.00, st,a,0,117),    &
  • The first reaction above takes its kinetic data from NASA's Jet Propulsion Laboratory. The rate for this can be found on page 1-10 (with further description on page 1-51) of the JPL2011 document.
  • The second reaction in these examples takes its kinetic data from IUPAC. Going to this website, this reaction is defined here.
  • The third reaction shows the use of fractional products.

You can see that in the instances above, different chemistry schemes use slightly different rates or species, as may be required by the scheme and species considered.

When adding new reactions you will need to increment the size of the array holding the ratb_t1 type (n_bimol_master). Due to the large number of bimolecular reactions, the array containing them has been broken up into several blocks. If you are not adding new reactions to the last block (for instance, if you are adding a variation on an existing reaction) you will need to increment the stride as well, e.g.

n_ratb_s = n_ratb_e+1
n_ratb_e = n_ratb_s+49
ratb_defs_master(n_ratb_s:n_ratb_e) = (/                                       &

would become

n_ratb_s = n_ratb_e+1
n_ratb_e = n_ratb_s+50
ratb_defs_master(n_ratb_s:n_ratb_e) = (/                                       &

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.

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_master.F90 module using the ratt_t1 Fortran type specification and are held in the ratt_defs_master array.

To format of this ratt_t1 type is

ratt_t(N,'Reactant 1','Reactant 2','Product 1 ','Product 2 ', , &
,  ,  , ,  ,  , Fraction of Product 1 produced, Fraction of Product 2 produced,SCHEME,QUALIFIER,
DISQUALIFIER,VN), & 

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

The settings for N, SCHEME, QUALIFIER, DISQUALIFIER, and VN are the same as in the adding new tracers tutorial, although here N should be incremented for each new reaction, where there might be the same reaction specified several times with changes to reaction rates or even species.

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

! T004 JPL 2011
ratt_t1(4,'O(1D)     ','N2        ','N2O       ','m         ',     0.0,        &
  2.80e-36, -0.90, 0.00,  0.00e+00,  0.0, 0.0, 0.0, 0.0, st+cs,0,0,107),       &
! JPL 2003
ratt_t1(4,'O(1D)     ','N2        ','N2O       ','m         ',     0.0,        &
  3.50e-37, -0.60, 0.00,  0.00e+00,  0.0, 0.0, 0.0, 0.0, s,0,0,107) ,          &
! T005 JPL 2011
ratt_t1(5,'BrO       ','NO2       ','BrONO2    ','m         ',     0.6,        &
  5.20e-31, -3.20, 0.00,  6.90e-12,  0.0, 0.0, 0.0, 0.0, st+cs,0,0,107),       &
ratt_t1(5,'BrO       ','NO2       ','BrONO2    ','m         ',   327.0,        &
  4.70e-31, -3.10, 0.00,  1.40e-11, -1.2, 0.0, 0.0, 0.0, s,0,0,107) ,          &


To add new termolecular reactions you will need to append equivalent lines for the new reactions to the end of the ratt_defs_master array (increasing the array size n_ratt_master accordingly). If there is any special code that needs to be added, this should be placed in the asad_trimol.F90 routine, which is held in the UKCA/ source-code 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_master.F90 module using the rath_t1 Fortran type specification, usually in one array (rath_defs_master).

To format of this rath_t1 type is

rath_t(N,'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,SCHEME,QUALIFIER,DISQUALIFIER,VN), & 

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.

The settings for N, SCHEME, QUALIFIER, DISQUALIFIER, and VN are the same as in the adding new tracers tutorial, although here N should be incremented for each new reaction, where there might be the same reaction specified several times with changes to reaction rates or even species.

Examples of this type are

rath_t1(5,'N2O5      ','HCl       ','Cl        ','NO2       ','HONO2     ',    &
'          ', 0.000, 0.000, 0.000, 0.000, s+st+cs,hp,0,107),                   &
rath_t1(6,'ClONO2    ','HBr       ','BrCl      ','HONO2     ','          ',    &
'          ', 0.000, 0.000, 0.000, 0.000, s+st+cs,eh,0,111),                   &

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

In the above block you can also see the use of the chemical mechanism version specification.

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 a separate photolysis code, Fast-JX, is used to interactively calculate the rate of reaction throughout the 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)[2] and Law et al (1998)[3].

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 vn10.4 these files can be found in

$UMDIR/vn11.8/ctldata/UKCA/tropdata/photol

To use this scheme set the value of i_ukca_photol by clicking 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 Fast-JX interactive photolysis should be used instead.

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)[4] is used (below 300hPa the tropospheric scheme described above is used). To use this scheme set the value of i_ukca_photol by clicking 2D Photolysis Scheme. The code for this scheme is held in ukca_strat_update.F90.

References

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

Interactive Photolysis

The original Fast-J scheme (Wild et al, 2000)[5] uses 7 different wavelength bins appropriate for the troposphere, and the updated Fast-JX scheme (Neu et al, 2007)[6] adds up to an extra 11 bins allowing use in the stratosphere. At present only Fast-JX is available, although some previous UM versions used the older Fast-J scheme as well.

To use this scheme set the value of i_ukca_photol by clicking FastJ-X. You will then need to give the location of several input data files used by this scheme.

Further details on how the the Fast-JX scheme is used in UKCA, can be found in Telford et al (2013)[7].

The Fast-JX data files are held in

$UMDIR/vn11.8/ctldata/UKCA/fastj

on ARCHER.

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_master.F90 module using the ratj_t1 Fortran type specification and held in the ratj_defs_master array.

To format of this ratj_t1 type is

ratj_t1(N,'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,SCHEME,QUALIFIER,DISQUALIFIER,VN), & 

The Look-Up Label is used to define the file used for the 2D photolysis, and is used by 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. Reactant 2 will always be PHOTON.

The settings for N, SCHEME, QUALIFIER, DISQUALIFIER, and VN are the same as in the adding new tracers tutorial, although here N should be incremented for each new reaction, where there might be the same reaction specified several times with changes to reaction rates or even species.

Examples of this type are

! 3
! This should produce H+ CHO -> H + HO2 + CO in ST scheme.
ratj_t1(3,'HCHO      ','PHOTON    ','HO2       ','HO2       ','CO        ',    &
     '          ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa    ',ti+t+st+r+cs,0,0,107),&
ratj_t1(3,'HCHO      ','PHOTON    ','H         ','CO        ','HO2       ',    &
     '          ', 0.0,0.0,0.0,0.0, 100.000,'jhchoa    ',s,0,0,107) ,          &
! 4
ratj_t1(4,'HCHO      ','PHOTON    ','H2        ','CO        ','          ',    &
     '          ', 0.0,0.0,0.0,0.0, 100.0,'jhchob    ',ti+s+t+st+r+cs,0,0,107),&

To add new photolysis reactions you will need to append equivalent lines for the new reactions to the end of the ratj_defs_master array (increasing the array size n_ratj_master accordingly), adding new files/code as necessary as described above.

Solution to Task 6.1: Add a bimolecular reaction

You were given the task

  • You should now add in the bimolecular reaction of ALICE with OH to form BOB and a secondary organic compound (labelled in UKCA as Sec_Org). You should use version 111. This reaction is given by:

Parameter Value
2.70E-11
0.00
-390.00

You were given the hint

  • As Sec_Org is part of the aerosol chemistry, this reaction should be given the a qualifier. You should increment the value of nr_therm accordingly.
Surface level concentrations (kg/kg) of BOB after the reaction has been applied.

For a working Rose suite that has completed this task, please see

  • vm: u-ca024@182668

The specific Rose changes made are:

The specific Rose changes made are:

vm:

Index: app/fcm_make/rose-app.conf
===================================================================
--- app/fcm_make/rose-app.conf	(revision 182503)
+++ app/fcm_make/rose-app.conf	(revision 182668)
@@ -43,4 +43,4 @@
 thread_utils=false
 timer_version=3A
 um_rev=$BASE_UM_REV
-um_sources=branches/dev/lukeabraham/vn11.8_UKCA_Tutorial_Solns@93871
+um_sources=branches/dev/lukeabraham/vn11.8_UKCA_Tutorial_Solns@94024

These differences can be found in the file Tutorials/vn11.8/worked_solutions/Task06.1/Task06.1_rose.patch.

The specific UM changes made are:

Index: src/atmosphere/UKCA/ukca_chem_master.F90
===================================================================
--- src/atmosphere/UKCA/ukca_chem_master.F90	(revision 93871)
+++ src/atmosphere/UKCA/ukca_chem_master.F90	(revision 94024)
@@ -98,7 +98,7 @@
 INTEGER, PARAMETER :: n_het_master  =  18 ! number of heterogeneous reactions
 INTEGER, PARAMETER :: n_dry_master  = 149 ! number of dry deposition reactions
 INTEGER, PARAMETER :: n_wet_master  = 106 ! number of wet deposition reactions
-INTEGER, PARAMETER :: n_bimol_master= 854 ! number of bimolecular reactions
+INTEGER, PARAMETER :: n_bimol_master= 855 ! number of bimolecular reactions
 INTEGER, PARAMETER :: n_ratj_master = 158 ! number of photolysis reactions
 INTEGER, PARAMETER :: n_ratt_master =  76 ! number of termolecular reactions
 
@@ -4712,7 +4712,9 @@
 'H2O       ',9.00e-11,  0.00,    0.00, 0.95, 0.05, 0.05, 1.00,cs,a,0,107),     &
 ! B697
 ratb_t1(697,'MSIA      ','NO3       ','MeSO2     ','HONO2     ','          ',  &
-'          ',1.00e-13,  0.00,    0.00, 0.00, 0.00, 0.00, 0.00,cs,a,0,107)      &
+'          ',1.00e-13,  0.00,    0.00, 0.00, 0.00, 0.00, 0.00,cs,a,0,107),     &
+ratb_t1(698,'ALICE     ','OH        ','BOB       ','Sec_Org   ','          ',  & 
+'          ',2.70E-11,  0.00, -390.00, 0.00, 0.00, 0.00, 0.00,st,a,0,111)      &
 /)
 
 
Index: src/atmosphere/UKCA/ukca_config_defs_mod.F90
===================================================================
--- src/atmosphere/UKCA/ukca_config_defs_mod.F90	(revision 93871)
+++ src/atmosphere/UKCA/ukca_config_defs_mod.F90	(revision 94024)
@@ -333,9 +333,9 @@
       n_aero_tracers = 12
       n_chem_tracers = 73         ! No chem tracers
       IF (ukca_config%l_ukca_trophet) THEN
-        nr_therm     = 241        ! thermal reactions
+        nr_therm     = 242        ! thermal reactions
       ELSE
-        nr_therm     = 239        ! thermal reactions
+        nr_therm     = 240        ! thermal reactions
       END IF
       nr_phot        = 59         ! photolytic (ATA)
 

These differences can be found in the file Tutorials/vn11.8/worked_solutions/Task06.1/Task06.1_code.patch.

Sample output from this task can be found at Tutorials/vn11.8/sample_output/Task06.1/atmosa.pa19810901_00.

Checklist

Add the new reaction into the correct reaction type array in ukca_chem_master.F90, incrementing the size of the array accordingly.
Increment the value of nr_therm and/or nr_phot in ukca_config_defs_mod.F90.
If required, add special code to the asad_bimol.F90, asad_trimol.F90, ukca_hetero_mod.F90, or asad_hetero.F90 routines.
For photolysis reactions, further work is required to calculate new cross sections. Code will also need to be added to ukca_strat_update.F90.

Tutorial 7


Written by Luke Abraham 2021