UKCA Chemistry and Aerosol UMvn13.9 Tutorial 5

UKCA Chemistry and Aerosol Tutorials at UMvn13.9

Difficulty	MEDIUM
Time to Complete	1-2 hours
Video instructions	https://www.youtube.com/watch?v=aysibeNdLUY&t=5304s

Remember to run mosrs-cache-password.

What you will learn in this Tutorial

During this tutorial you will learn how to make new UKCA netCDF emissions files. Then you will learn how to add this new emissions file in Rose UKCA so that it emits into an existing tracer.

This tutorial will go through the steps needed to make an emission file for a tracer which UKCA may or may not currently emit into. If emissions are already expected for a tracer this is a simpler case and you do not need to make any code changes.

This example only deals with a single field. For a more detailed examples on changing emissions for all species, please see the Emissions for ACSIS webpage.

Task 5.1: Create a new NetCDF emissions file

Task 5.1: In the

Tutorials/UMvn13.9/data/Task05.1

directory there is the file Emissions_of_CO.nc which is a 0.5x0.5 degree resolution surface emission field. You should regrid this file to the N48 ENDGame grid, and output it as a netCDF file that has the required netCDF metadata for a climatological surface emission without any diurnal cycle.

The netCDF emissions system

UKCA uses netCDF files to specify the emissions into UKCA species. Using netCDF files means that the metadata in the file can be used to specify various options, such as which diurnal cycle to use.

Metadata

In Global Atmosphere 7.0 and above, UKCA emissions are prescribed using NetCDF files, rather than using the the UM ancillary file format as NetCDF files allow for more flexibility and include informative metadata. For further information also see the UKCA documentation paper.

Emission field metadata

Each emission field in the NetCDF files needs to include the following variable metadata attributes (there is no requirement for the netCDF variable names themselves except that they be no longer than 80 characters):

• standard_name: It should be included if an appropriate name is present in the CF Standard Name Table (see http://cfconventions.org/standard-names.html). An example of a valid ‘standard name’ is

  “tendency_of_atmosphere_mass_content_of_nitrogen_monoxide_due_to_emission”

  (note that all substrings have to be separated by underscores).
• long_name: It is recommendable but only compulsory if there is no ‘standard_name’ available for that emission field. There are no specific CF conventions for standard names, but within the UKCA code all substrings should be separated by white space as shown in this example:

  “tendency of atmosphere mass content of nitrogen monoxide due to emission”. 

  The reason for this is given in the description of the attribute units.
• tracer_name: This attribute has to be equal to the name of a tracer (or of an emission field such as ‘NO - aircrft’) present in the list of emissions for the given chemical scheme that is held in the character array em_chem_spec. This name is used by the subroutine UKCA_ADD_EMISS to add the emission field to the corresponding tracer. There should be at least one emission field in the NetCDF files (or alternatively an online emission field) with the value of tracer name equal to one of the items in em_chem_spec, otherwise the subroutine UKCA_EMISS_INIT (in module UKCA_EMISS_MOD) will report a missing tracer in the emission files and the model will stop with error. You will learn more about how to add new emissions to em_chem_spec in Tutorial 10.
• units: According to CF conventions, all emissions should be expressed in $kg\,{m}^{-2}\,{s}^{-1}$. As a consequence, all files will contain the attribute

  units = "kg m-2 s-1"

  However, under some circumstances emission fields need to be reported as kg of a given species (e.g. nitrogen, carbon, sulfur). When that is the case this needs to be indicated in the standard name attribute if possible (see example below), otherwise in the long name attribute. As an example, in the case of an emission field reported as kg of carbon, the attribute units will be “kg m-2 s-1” while the attribute standard name should contain the substring “expressed_as_carbon” if that is accepted by CF conventions for standard names (see http://cf-pcmdi.llnl.gov/documents/cf-standard-names); otherwise the attribute long name should contain the substring “expressed as carbon”. The UM subroutines BASE_EMISS_FACTORS and GET_BASE_SCALING will look for such substrings and apply some conversions if needed. It is therefore essential that the substrings in standard_name and long_name are separated by underscores and white spaces, respectively, as indicated above.
• hourly_scaling: (optional) A character attribute used to apply a diurnal cycle to emissions data with daily or lower frequency. Allowed values:
  • none (or attribute not present): no scaling
  • traffic_uk: used for UK air quality studies
  • TNO_MACC_EU_SNAPnn (where nn=01 to 11): Hourly factors of emissions for Europe. Calculated by TNO for the MACC project.
  • diurnal_isopems (for isoprene emissions): use the routine UKCA DIURNAL ISOP EMS to calculate a diurnal cycle using solar zenith angle and latitude to compute the expected number of sunshine hours.
• daily_scaling (optional): A character attribute used to apply a weekly cycle to emissions weekly or lower frequency. Only allowed when the model is using the Gregorian calendar. Allowed values:
  • none (or attribute not present): no scaling
  • traffic_uk: used for UK air quality studies
  • TNO_MACC_GB_SNAPnn (where nn=01 to 11): Hourly factors of emissions for Great Britain. Calculated by TNO for the MACC project.
• vertical_scaling (optional): A character attribute defining the vertical distribution of the emission. This allows the user to supply a 2D field to be applied over multiple levels. Allowed values:
  • surface (or attribute not present): treat as surface emission
  • all_levels, 3D: field is three-dimensional and is provided on model levels (must have the same number of levels as the model)
  • high_level: spread a 2D field over multiple model levels, weighting by model layer thickness to achieve a uniform distribution in height. Must be accompanied by variable attributes lowest_level and highest_level to indicate the model levels over which to distribute the emission.
  • step1: used for air quality simulations, spreads emission over lowest 3 layers of the model; only allowed with 38 model levels.
  • EMEP_modified_SNAPnn (where nn=01 to 11): Average vertical profiles for SNAP sectors, similar to implementation for EMEP model. See routine vertical emiss factors for details.
  • Bieser_modified_SNAPnn (where nn=01 to 11): Average vertical profiles for SNAP sectors, similar to implementation of Bieser et al. (2011) with the SMOKE model and including fugitive emissions. See routine vertical_emiss_factors for details. In addition, each NetCDF file has to include two global attributes with information that is valid for all emission fields present in the file:

Time coordinate metadata

These metadata items are associated with the time dimension coordinate:

• calendar: A string indicating the calendar used, e.g. gregorian, 360day etc.
• calendar_flexible (optional): Integer number indicating whether or not the emission field can be used with other calendar types. This is typically allowed when used with monthly mean values.
  • 0: Cannot be used with other calendar types
  • 1: Can be used with other calendar types (i.e. a field designated as a 360day could also be used in a simulation using the Gregorian calendar, e.g. when nudging).

Global metadata

These metadata items are set globally:

• update_freq_in_hours: Integer indicating the frequency (in hours) at which all emission fields present in that file should be read to update emissions(:)%values (:,:,:) in the UKCA code. Update points are calculated relative the model’s ancil reftime.
• update_type: Integer number indicating the times at which the data is provided. The same conventions as for ancillary files have been adopted:
  • 0: Single time
  • 1: Time series
  • 2: Periodic time series

When emissions are treated as time series (update_type=1) the user is responsible for creating emission fields which cover the whole period for which the model is run; otherwise the model will not find the time registers to do interpolations and will stop with error. When emissions are periodic (update_type=2) each emission field has to include exactly 12 monthly average emissions (Jan, Feb, ..., Dec). Other attributes, in particular some global attributes, as well as some additional fields (e.g. a variable indicating the type of grid mapping) should be present in the files to comply with CF conventions for NetCDF data, but they are not used by the UKCA code.

Using python to regrid your emissions

For this task we will be using the the Met Office Iris library to regrid the emissions. This can also be done using cf-python. For information on using cf-python to regrid emissions, please see the UKCA UMvn13.0 Tutorials.

However, don't panic. You are not expected to know python to complete this tutorial. You will be provided with an example script to use that you only need to edit a few lines to get to work. You do not need to write a script from scratch, just read-through the provided script and try to understand what it does, and why.

Python notebook

In the directory:

Tutorials/UMvn13.9/data/Task05.1

you will find the file Emissions_of_CO.nc. Using this file, and using your output .pa file from your suite, you should regrid the emissions into the N48 ENDGame grid. You will later use the resulting NetCDF file in your suite. A Jupyter notebook using Iris has been provided to regrid these emissions, and can be found here:

Tutorials/UMvn13.9/notebooks/iris_UM-UKCA_T051.ipynb

This can also be seen online here:

• iris_UM-UKCA_T051.ipynb

Connect to the notebook using the Jupyter Lab option from your Cylc 8 GUI Dashboard, and use the ukca kernel when running.

• http://localhost:4801/?token=UKCATraining

Solution to Task5.1

You were given the task:

• In the

  Tutorials/UMvn13.9/data/Task05.1

  directory there is the file Emissions_of_CO.nc which is a 0.5x0.5 degree resolution surface emission field. You should regrid this file to the N48 ENDGame grid, and output it as a netCDF file that has the required netCDF metadata for a climatological surface emission without any diurnal cycle.

It should be straight-forward to point to your .pa file to use in the script. You should read through it and have an understanding of how it works.

Once the file has been regridded, you should see the output looking like this:

• 

  CO emissions prior to regridding.

• 

  CO emissions after regridding.

A file that has been produced by the above script can be found at

Tutorials/UMvn13.9/sample_output/Task05.1/ukca_emiss_CO.nc

Task 5.2: make the required Rose changes to add your emissions into UKCA

TASK 5.2: You should now make the UKCA code changes to add your new emissions into the CO tracer. Compare your CO field at the end of the run with your previous simulation to see the differences.

UKCA emissions are addative - you can include multiple emissions files for the same species and UKCA will add them up. This is useful when planning experiments where you may only want to change one particular sector, e.g. transport, but want to keep other sectors the same across multiple simulations.

As new STASH items are defined by namelist entries, the model does not have to be recompiled and the reconfiguration step does not need to be re-run before rerunning the atmosphere task.

Hint
Remember to save your atmosa.pa19810901_00 file to a different location before you re-run your suite.

Rose changes

Include your new emissions file

There are several ways that the location of emissions files can be defined within the UKCA panel. These are:

1. With a full path to the file
2. Using environment variables set using an ancil_versions file
3. A mixture of (1) and (2)
4. By specifying a top-level directory in the ukca_em_dir Rose variable, and then paths to the required files within ukca_em_files

Within Rose you may also find that the files are in separate boxes (one for each file) or in a single long list.

The UKCA training suite uses option 1 above, specifying the full path in ukca_em_files. Note that ukca_em_dir is blank in this suite.

It is easier to add the emissions file by editing the app/um/rose-app.conf file directly in a text editor than by using rose edit. This is because Rose can sometimes make all the files appear on a single line, whereas in the text file they will be on separate lines. To find this block save and close your suite, and then open the app/um/rose-app.conf file in a text editor (e.g. emacs, vim, or leafpad). Search for ukca_em_files and you will find the text below:

ukca_em_files='$UMDIR/ancil/atmos/n48e/ukca_emiss/gfed3.1/clim_2002_2011/v2/ukca_emiss_BC_biomass.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/gfed3.1/clim_2002_2011/v2/ukca_emiss_OC_biomass.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/andres_kasgnoc/v1/ukca_emiss_SO2_nat.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_Monoterp.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/1970_2010/v1/ukca_emiss_SO2_low.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_BC_fossil.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_BC_biofuel.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_OC_fossil.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_OC_biofuel.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/1970_2010/v1/ukca_emiss_SO2_high.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/1970_2010/v1/ukca_emiss_DMS.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/1970_2010/v1/ukca_emiss_NH3.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_NO_aircrft.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_HCHO.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_CH4.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_MeCHO.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_C3H8.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_NO.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_C2H6.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_Me2CO.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_C5H8.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/biogenic/v1/biogenic/MEGAN-MACC_biogenic_MeOH_clim_2001-2010.nc',
             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_CO.nc'

you will need to add a new line at the end of the block, with the = sign aligned, specifying the path to your new file. Don't forget to add a comma (,) at the end of the line above.

Diagnostics

You should have already added CO diagnostics to the STASH panel in Tutorial 4. If you are doing this for a different tracer(s) as part of your work you may wish to output equivalent diagnostics at this stage.

Worked Solution to Task 5.2

• 

  Surface level (20m) concentrations (kg/kg) of CO after the new emissions have been applied.

• 

  Surface level (20m) emissions (kg^2 m^-1 s^-1) of CO after the new emissions have been applied.

• 

  Difference in surface level (20m) concentrations (kg/kg) of CO after the new emissions have been applied.

• 

  Difference in surface level (20m) emissions (kg^2 m^-1 s^-1) of CO after the new emissions have been applied.

You were given the task

• You should now make the UKCA code changes to add your new emissions into the CO tracer. Compare your CO field at the end of the run with your previous simulation to see the differences.

You were given the hint

• Remember to save your atmosa.pa19810901_00 file to a different location before you re-run your suite.

Once you have made the required Rose changes and run your suite, you should be able to calculate and plot the differences in the CO emissions and the CO tracer.

The specific Rose changes made are:

• https://code.metoffice.gov.uk/trac/roses-u/changeset/337614/d/u/5/1/6/trunk

Index: app/um/rose-app.conf
===================================================================
--- app/um/rose-app.conf	(revision 337612)
+++ app/um/rose-app.conf	(revision 337614)
@@ -3251,7 +3251,8 @@
              ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_Me2CO.nc',
              ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_C5H8.nc',
              ='$UMDIR/ancil/atmos/n48e/ukca_emiss/biogenic/v1/biogenic/MEGAN-MACC_biogenic_MeOH_clim_2001-2010.nc',
-             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_CO.nc'
+             ='$UMDIR/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_CO.nc',
+             ='/home/vagrant/ukca_emiss_CO.nc'
 ukca_h1202mmr=3.788e-13
 ukca_h1211mmr=2.225e-11
 ukca_h1301mmr=1.363e-11

These differences can be found here:

Tutorials/UMvn13.9/worked_solutions/Task05.2/Task05.2_rose.patch

Sample output from this task can be found at

Tutorials/UMvn13.9/sample_output/Task05.2/

Checklist

☐ Obtain emissions data for the species of interest.

☐ Regrid the emissions to the correct MetUM resolution that you are using.

☐ Save these emissions as netCDF, including the required metadata that UKCA requires.

☐ In your suite, include this file in the ukca_em_files variable in the UKCA panel: um $\rightarrow$ namelist $\rightarrow$ UM Science Settings $\rightarrow$ Section 34 - UKCA: UK Aerosols and Chemistry $\rightarrow$ Emissions. You can add this directly to the app/um/rose-app.conf file, but you should close your suite first to prevent any changes being lost.

☐ Output your emissions diagnostic in: um $\rightarrow$ namelist $\rightarrow$ Model Input and Output $\rightarrow$ STASH Requests and Profiles $\rightarrow$ STASH Requests.

☐ Run the TidyStashTransform transform macro.

☐ Save your suite.

☐ In the roses/[SUITE-ID] directory, run fcm commit to commit your changes to the repository.

☐ Run your suite.

Tutorial 6

UKCA Chemistry and Aerosol Tutorials at UMvn13.9

---

Written by Luke Abraham 2025