Adding New UKCA Tracers

You may wish to add new UKCA tracers, possibly with associated reactions. This is possible for both the TropIsop and StratChem configurations. There are two steps that you need to do - first, set up the new tracers for the UM, and second set up these tracers for UKCA. Adding tracers will require both UMUI hand-edit, STASH, and source-code changes.

UMUI Changes
- While these jobs only use a small sub-set of the total number of tracers allowed by the UM (150), due to the number of different schemes used, many of these other slots will have been reserved. While it is possible to use them, it is recommended that you choose an empty slot. To find which tracer slots are free, look in the file ukca_setd1defs.F90 which is found in the src/atmosphere/UKCA directory. In this file, locate the array specification of nm_spec (non-families). This array contains all 150 currently considered tracers. Several of these slots are unused, and these are the ones labeled XXX. Work out which number these are in the array, e.g. in the VN7.3_UKCA_CheM branch, numbers 40, 60, and 96-100 are currently free.
- Take a copy of the tracer pre-STASHmasterfile (PSM) used by the UKCA job, and add a section for the tracer you are adding. You will need to change 3 numbers and the tracer name:
  1. The item number (Item): line 1, entry 3 (should be 1-150)
  2. The option code (Option Codes): line 3, entry 1 (last 3 digits, same number as Item)
  3. The field code (PPFC) : line 5, entry 2 (tracers begin numbering at 501 for tracer 1)
  4. The name of the tracer (Name): line 1, entry 4 (this should be representative of the species you are adding for clarity)
  - An example of a PSM entry is below, with XXX marking the locations to be changed
  - You will need to make sure that the lengths of the lines remains the same, otherwise the UMUI will not be able to read the PSM.
  - Replace the previous tracer PSM with your new one in the UMUI STASHmaster Panel:
    Model Selection -> Atmosphere -> STASH -> User-STASHmasterfiles. Diags, Progs & Ancils.
  - Initialise this tracer to a value in the UMUI Initialisation Panel:
    Model Selection -> Atmosphere -> STASH -> Initialisation of User Prognostics
    Scroll down the list until you come to your new tracer. The Option column will be blank - either
    1. initialise to zero (option 3)
    2. initialise to a constant value (option 6, value specified in column 4)
    3. initialise to a 3D field (option 7, file containing field specified in column 5. You may wish to use Xancil for this option)
    - It may be best to set the tracer to zero or a constant value at this point.
    - You may also wish to add the tracer through STASH to the climate meaning stream:
      Model Selection -> Atmosphere -> STASH -> STASH. Specification of Diagnostic requirements
- With your new PSM, run the script make_tracer_list, found in the /home/ukca/bin directory on PUMA on this file. The output should be similar to:
  TC_UKCA=1,1,1,1,1,1,1,1,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, 1,0,1,1,1,1,1,1,1,1,1,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,0,0,0,1,1,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,1,
  - Take a copy of the hand-edit that your job uses to add the UKCA tracers. For TropIsop jobs this will be add_s34_CheT_tracers_L60/63.ed and for StratChem jobs this will beadd_s34_CheS_tracers_L60/85.ed.
    1. Find the lines that have the TC_UKCA definition, and replace it with the line you have generated with your PSM.
    2. Find the lines that define the value of TR_UKCA and increment this by the number of tracers you are adding.
  - Replace the original hand-edit in the UMUI with the one you have just created:
    Model Selection -> Input/Output Control and Resources -> User hand edit files
- Make sure reconfiguration is on:
  Model Selection -> Atmosphere -> Ancillary and input data files -> Start Dump
  The radio-button Using the reconfiguration should be on
- SAVE, PROCESS and SUBMIT the job. This should run with the extra tracer added. Look in a dump file to be sure that the tracer is there, and that it's value is as was set in the initialisation panel.
UKCA code changes
1. Adding the tracer
  - Before making these changes, you should run through the UM FCM Tutorial.
  - Any code changes should be made to a branch that you own. Make a new branch and merge in the UKCA branch that you are using (e.g. fcm:br/dev/luke/VN7.3_UKCA_CheM)
  - For these changes, you must be a copy of the UKCA branch. We suggest using a working copy rather than committing the changes:
    Model Selection -> FCM Configuration -> FCM Options for Atmosphere and Reconfiguration
    Set the UKCA branch to N and select the radio-button Include modifications from user working copy and put the full path (on PUMA) to the local copy of your branch
  - You will need to make some changes to ukca_setd1defs.F90
    - Edit the nm_spec (non-Families) array so that the slot used for the PSM now contains your tracer
    - Increment n_chem_tracers for the scheme you are using by the number of tracers added
    - You may also be adding emissions or surface boundary conditions.
      - For emissions, you would also increment n_chem_emissions and make changes to em_chem_spec, and the emissions ancillary file.
      - For boundary conditions, you would also increment n_boundary_vals and make changes to lbc_spec, and you may also make changes to ukca_scenario_prescribed/wmoa1.F90.
  - Take a copy of the jp_for_CheT/S.ed ( $T=TropIsop$ $T=TropIsop$ , $S=StratChem$ $S=StratChem$ ) hand-edit:
    Model Selection -> Input/Output Control and Resources -> User hand edit files
    - Increase the values of JPCTR and JPSPEC by the number of tracers you are adding
    - Add the tracers:
      - For StratChem: Edit the file ukca_chem1_dat.F90 to add your tracer(s) into the chch_defs_strat type array, making sure that you use the same name as in the nm_spec array.
      - For TropIsop: Edit the file ukca_chem1_tropisop.F90 to add your tracer(s) into the chch_defs_tropisop type array, making sure that you use the same name as in the nm_spec array.
  - This should now run with the extra tracer considered as such by UKCA. However, there are no reactions/deposition being performed on it, so the tracer still should not change when viewed in a dump file
2. Adding reactions, deposition etc
  - You will need to edit the ukca_chem1_dat.F90 or ukca_chem1_tropisop.F90 as appropriate to add reactions. These are defined
    - ratb_defs: Bimolecular reactions (JPBK in jp_for_CheT/S.ed)
    - ratt_defs: Termolecular reactions (JPTK in jp_for_CheT/S.ed)
    - rath_defs: Heterogeneous reactions (for StratChem only) (JPHK in jp_for_CheT/S.ed)
    - ratj_defs: Photolysis reactions (JPPJ in jp_for_CheT/S.ed)
    - depvel_defs: Dry-deposition (JPDD in jp_for_CheT/S.ed)
      - For species which are dry-deposited, you will also need to edit the chch_defs type, and put a 1 in the first column of the block of three numbers
      - The ordering of the depvel_defs type is dependent on the ordering of the tracers in chch_defs, so you will need to make sure that this is correct
    - henry_defs: Wet-deposition (Henry's Law) (JPDW in jp_for_CheT/S.ed)
      - For species which are wet-deposited, you will also need to edit the chch_defs type, and put a 1 in the second column of the block of three numbers
      - The ordering of the henry_defs type is dependent on the ordering of the tracers in chch_defs, so you will need to make sure that this is correct
    - NOTE: Emissions are not considered in ukca_chem1_dat/tropisop.F90
      - Emissions for most tropospheric species are considered by adding a field to the user single-level ancillary file (see above), and adding code to src/atmosphere/UKCA/ukca_setd1defs.F90 and src/atmosphere/UKCA/ukca_emission_ctl.F90.
      - Most stratospheric species are set as lower boundary conditions to the species. These are set in src/atmosphere/UKCA/ukca_scenario_wmoa1.F90 and src/atmosphere/UKCA/ukca_scenario_prescribed.F90 and the lbc_spec array is altered in src/atmosphere/UKCA/ukca_setd1defs.F90
    - These configurations of UKCA are built using the ASAD chemical integration package. For documentation on using ASAD, please see the ASAD webpage.
  - Edit the jp_for_CheT/S.ed to increment the JP counter(s) (listed above) associated with your changes, and also increase the size of JPNR, the total number of reactions, accordingly (dry- and wet-deposition are not counted in JPNR):
    Model Selection -> Input/Output Control and Resources -> User hand edit files
  - You may also need to add the conversion factor from MMR to VMR for your tracer:
    1. If needed, add the conversion factor to src/include/constant/c_v_m.h
    2. If needed, add a line to the WHERE block to copy this conversion factor into the c_species array in src/atmosphere/UKCA/ukca_cspecies.F90
  - SAVE, PROCESS and SUBMIT the job. This should now be using the new tracer in UKCA.

Blank pre-STASHmasterfile

The XXX labeled sections are ones which should be changed when adding a new UKCA tracer.

1|    1 |   34 |  XXX | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
2|    2 |    0 |    1 |    1 |    2 |   10 |   11 |    0 |    0 |    0 |    0 |
3| 000000000000000000000000000XXX | 00000000000000000001 |    1 |
4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
5|    0 |  XXX |    1 |   65 |    0 |    0 |    0 |    0 |    0 |