View source for UKCA Chemistry and Aerosol vn11.8 Tutorial 5

[[UKCA Chemistry and Aerosol Tutorials at vn11.8]]

==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 new emissions into UKCA so that they emit into one of your new tracers.

At the end of the [[UKCA Chemistry and Aerosol vn10.9 Tutorial 4 | previous tutorial]] you will now know how to create new tracers for use by UKCA. However, after completing the tasks, your tracers will still be empty, as nothing has been put into them. This tutorial will teach you how to create an emissions file that the UKCA will read, and that you can then tell UKCA to use and emit into your tracer(s).

This tutorial will go through the steps needed to make an emission into a tracer which UKCA does not currently emit into. The steps in making the netCDF file will be the same for a species which is currently emitted into, although in this simpler case you would 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 emissions file and use it in your job==

<span style="color:green">'''Task 5.1:''' In the <pre>/work/n02/n02/ukca/Tutorial/vn10.9/Task5.1</pre> directory on ARCHER there is the file '''Emissions_of_ALICE.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.</span>

==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, UKCA emissions are prescribed using netCDF files. The reason for this move away from the UM ancillary file format

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):

* '''<code>standard_name</code>:''' 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:
:: <code>“tendency_of_atmosphere_mass_content_of_nitrogen_monoxide_due_to_emission”</code>
: (note that all substrings have to be separated by underscores).
* '''<code>long_name</code>:'''  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: 
:: <code>“tendency of atmosphere mass content of nitrogen monoxide due to emission”. </code>
: The reason for this is given in the description of the attribute units.
* '''<code>tracer_name</code>:'''  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, i.e. <code>em_chem_spec</code>. 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.
* '''<code>units</code>:'''  According to CF conventions, all emissions should be expressed in <math>kg\, {m}^{-2}\, {s}^{-1}</math>. As a consequence, all files will contain the attribute
:: <code>units = "kg m-2 s-1"</code>
: 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 <code>“expressed_as_carbon”</code> 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 <code>“expressed as carbon”</code>. 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.
* '''<code>hourly_scaling</code>: (optional)''' A character attribute used to apply a diurnal cycle to emissions data with daily or lower frequency. Allowed values:
** <code>none</code> (or attribute not present): no scaling
** <code>traffic_uk</code>: used for UK air quality studies
** <code>TNO_MACC_EU_SNAPnn</code> (where nn=01 to 11): Hourly factors of emissions for Europe. Calculated by TNO for the MACC project.
** <code>diurnal_isopems</code> (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.
* '''<code>daily_scaling</code> (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:
** <code>none</code> (or attribute not present): no scaling
** <code>traffic_uk</code>: used for UK air quality studies
** <code>TNO_MACC_GB_SNAPnn</code> (where nn=01 to 11): Hourly factors of emissions for Great Britain. Calculated by TNO for the MACC project.
* '''<code>vertical_scaling</code> (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:
** <code>surface</code> (or attribute not present): treat as surface emission
** <code>all_levels</code>, <code>3D</code>: field is three-dimensional and is provided on model levels (must have the same number of levels as the model)
** <code>high_level</code>: 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.
** <code>step1</code>: used for air quality simulations, spreads emission over lowest 3 layers of the model; only allowed with 38 model levels.
** <code>EMEP_modified_SNAPnn</code> (where nn=01 to 11): Average vertical profiles for SNAP sectors, similar to implementation for EMEP model. See routine vertical emiss factors for details.
** <code>Bieser_modified_SNAPnn</code> (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:
* '''<code>update_freq_in_hours</code>:''' 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.
* '''<code>update_type</code>''': 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 [http://scitools.org.uk/iris/ Iris] python library, which is developed by the Met Office and can read Met Office formatted files. The [http://cfpython.bitbucket.org/ cf-python] library also does this, but we will not be using this here.

If you have been provided a VM, Iris will have been installed for you, and can be accessed by using the command

 pyterm

The command

 pylab 

has also been provided to give you an iPython environment which logs the commands you type and has included the <code>--pylab</code> flag.

===Personal Virtual Machine===

To be able to use Iris on the VM, you should first edit the script

 /usr/local/bin/install-iris

to use the command

 conda install -y -c conda-forge python=3.6 iris=1.13 ipython mo_pack numpy=1.15

which installs the required python packages from [https://www.continuum.io/anaconda-overview anaconda], and also creates an alias in your <code>~/.bashrc</code> file, called '''conda''', which opens a terminal with additional paths set. You may need to re-source your <code>~/.bashrc</code> by 

 . ~/.bashrc

before running the 

 conda

command.
 
===Using python===

when developing python scripts, a handy command to use can be set by the following alias:

 alias pylab='ipython --pylab --logfile=ipython-`date +"%Y%m%d-%H%M%S"`.py'

This uses [http://ipython.readthedocs.io/en/stable/ ipython], which is an interactive shell for python. The <code>--pylab</code> automatically loads some standard python libraries such as [https://www.scipy.org/ scipy], [http://www.numpy.org/ numpy], and [http://matplotlib.org/ matplotlib]. The <code>--logfile</code> means that all commands will be recorded in a file with the format <code>ipython-YYYYMMDD-HHMMSS.py</code>.

You can also execute pre-written python scripts by

* '''vm:''' launch iPython (e.g. via <code>pyterm</code> followed by <code>pylab</code>) and then run the script using
 %run "/path/to/script.py"

However, <span style="font-size: 110%; color: red">'''don't panic'''</span>. '''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.

===Example python script===

In the directory:

 Tutorials/vn11.8/Task05.1

you will find the file '''<code>regrid_ALICE_N48e.py</code>'''. You should take a copy of 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.

This file looks like:

 #!/usr/bin/env python
 
 # This file is part of the UKCA Tutorials:
 #  http://www.ukca.ac.uk/wiki/index.php/UKCA_Chemistry_and_Aerosol_Tutorials_at_vn10.9+
 
 # Copyright (C) 2017  University of Cambridge
 
 # This is free software: you can redistribute it and/or modify it under the
 # terms of the GNU Lesser General Public License as published by the Free Software
 # Foundation, either version 3 of the License, or (at your option) any later
 # version.
 
 # It is distributed in the hope that it will be useful, but WITHOUT ANY
 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 # PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 
 # You find a copy of the GNU Lesser General Public License at <http://www.gnu.org/licenses/>.
 
 # Written by N. Luke Abraham 2017-11-15 <nla27@cam.ac.uk> 
 
 # To use this script on the VM you should first
 #    install-iris
 # and then open a new terminal with the correct PATHs set using the command
 #    conda
 # once you have done this, you can run the script through ipython using
 #    %run "/path/to/regrid_ALICE_N48e.py"
 
 # preamble
 import iris
 import numpy
 # pre-Iris v1.10, use iris.unit instead of cf_units
 import cf_units
 
 # --- CHANGE THINGS BELOW THIS LINE TO WORK WITH YOUR FILES ETC. ---
 
 # name of file containing an ENDGame grid, e.g. your model output
 # NOTE: all the fields in the file should be on the same horizontal
 #       grid, as the field used MAY NOT be the first in order of STASH
 grid_file='/umshared/Tutorials/vn11.8/sample_output/Base/atmosa.pa19810901_00'
 # name of emissions file
 emissions_file='/umshared/Tutorials/vn11.8/Task05.1/Emissions_of_ALICE.nc'
 
 # --- BELOW THIS LINE, NOTHING SHOULD NEED TO BE CHANGED ---
 
 species_name='ALICE'
 
 # this is the grid we want to regrid to, e.g. N48 ENDGame
 grd=iris.load_cube(grid_file,iris.AttributeConstraint(STASH='m01s34i001'))
 grd.coord(axis='x').guess_bounds()
 grd.coord(axis='y').guess_bounds()
 
 # This is the original data
 ems=iris.load_cube(emissions_file)
 # make intersection between 0 and 360 longitude to ensure that 
 # the data is regridded correctly
 nems = ems.intersection(longitude=(0, 360))
 
 # make sure that we use the same coordinate system, otherwise regrid won't work
 nems.coord(axis='x').coord_system=grd.coord_system()
 nems.coord(axis='y').coord_system=grd.coord_system()
 
 # now guess the bounds of the new grid prior to regridding
 nems.coord(axis='x').guess_bounds()
 nems.coord(axis='y').guess_bounds()
 
 # now regrid
 ocube=nems.regrid(grd,iris.analysis.AreaWeighted())
 
 # now add correct attributes and names to netCDF file
 ocube.var_name='emissions_'+str.strip(species_name)
 ocube.long_name=str.strip(species_name)+' surf emissions'
 ocube.units=cf_units.Unit('kg m-2 s-1')
 ocube.attributes['vertical_scaling']='surface'
 ocube.attributes['tracer_name']=str.strip(species_name)
 # global attributes, so don't set in local_keys
 # NOTE: all these should be strings, including the numbers! This will change at a later UM version.
 # basic emissions type
 ocube.attributes['emission_type']='2' # periodic
 ocube.attributes['update_type']='2'   # same as above
 ocube.attributes['update_freq_in_hours']='120' # i.e. 5 days
 ocube.attributes['source']='UKCA Tutorial Task 5.1 - creating netCDF emissions'
 
 # rename and set time coord - set to be 0000/01/16:00:00-0000/12/16:00:00
 # this bit is annoyingly fiddly
 ocube.coord(axis='t').var_name='time'
 ocube.coord(axis='t').standard_name='time'
 ocube.coords(axis='t')[0].units=cf_units.Unit('hours since 1970-01-01', calendar='360_day')
 ocube.coord(axis='t').points=numpy.array([-17020440, -17019720, -17019000, -17018280,
                                           -17017560, -17016840, -17016120, -17015400, 
                                           -17014680, -17013960, -17013240, -17012520]) 
 # make z-direction.
 zdims=iris.coords.DimCoord(numpy.array([0]),standard_name = 'model_level_number',
                            units='1',attributes={'positive':'up'})
 ocube.add_aux_coord(zdims)
 ocube=iris.util.new_axis(ocube, zdims)
 # now transpose cube to put Z 2nd
 ocube.transpose([1,0,2,3])
 
 # make coordinates 64-bit
 ocube.coord(axis='x').points=ocube.coord(axis='x').points.astype(dtype='float64')
 ocube.coord(axis='y').points=ocube.coord(axis='y').points.astype(dtype='float64')
 #ocube.coord(axis='z').points=ocube.coord(axis='z').points.astype(dtype='float64') # integer
 ocube.coord(axis='t').points=ocube.coord(axis='t').points.astype(dtype='float64')
 # for some reason, longitude_bounds are double, but latitude_bounds are float
 ocube.coord('latitude').bounds=ocube.coord('latitude').bounds.astype(dtype='float64')
 
 
 # add forecast_period & forecast_reference_time
 # forecast_reference_time
 frt=numpy.array([-17020080, -17019360, -17018640, -17017920, 
                  -17017200, -17016480, -17015760, -17015040, 
                  -17014320, -17013600, -17012880, -17012160],dtype='float64')
 frt_dims=iris.coords.AuxCoord(frt,standard_name = 'forecast_reference_time',
                            units=cf_units.Unit('hours since 1970-01-01', calendar='360_day'))
 ocube.add_aux_coord(frt_dims,data_dims=0)
 ocube.coord('forecast_reference_time').guess_bounds()
 # forecast_period
 fp=numpy.array([-360],dtype='float64')
 fp_dims=iris.coords.AuxCoord(fp,standard_name = 'forecast_period',
                            units=cf_units.Unit('hours'),bounds=numpy.array([-720,0],dtype='float64'))
 ocube.add_aux_coord(fp_dims,data_dims=None)
 
 # add-in cell_methods
 ocube.cell_methods = [iris.coords.CellMethod('mean', 'time')]
 # set _FillValue
 fillval=1e+20
 ocube.data = numpy.ma.array(data=ocube.data, fill_value=fillval, dtype='float32')
 
 # output file name, based on species
 outpath='ukca_emiss_'+species_name+'.nc'
 # don't want time to be cattable, as is a periodic emissions file
 iris.FUTURE.netcdf_no_unlimited=True
 # annoying hack to set a missing_value attribute as well as a _FillValue attribute
 dict.__setitem__(ocube.attributes, 'missing_value', fillval)
 # now write-out to netCDF
 saver = iris.fileformats.netcdf.Saver(filename=outpath, netcdf_format='NETCDF3_CLASSIC')
 saver.update_global_attributes(Conventions=iris.fileformats.netcdf.CF_CONVENTIONS_VERSION)
 saver.write(ocube, local_keys=['vertical_scaling', 'missing_value','um_stash_source','tracer_name'])
 
 # end of script
 
 # Why we are messing around with metadata?
 #-----------------------------------------
 #
 # We need to adapt the metadata of the emissions data to 
 # match what UKCA is expecting. 
 #  e.g. the metadata of the 'Emissions_of_ALICE.nc file is:
 #
 #    netcdf Emissions_of_ALICE {
 #    dimensions:
 #            lon = 720 ;
 #            lat = 360 ;
 #            date = UNLIMITED ; // (12 currently)
 #    variables:
 #            float lon(lon) ;
 #                    lon:long_name = "Longitude" ;
 #                    lon:standard_name = "longitude" ;
 #                    lon:units = "degrees_east" ;
 #                    lon:point_spacing = "even" ;
 #                    lon:modulo = " " ;
 #            float lat(lat) ;
 #                    lat:long_name = "Latitude" ;
 #                    lat:standard_name = "latitude" ;
 #                    lat:units = "degrees_north" ;
 #                    lat:point_spacing = "even" ;
 #            float date(date) ;
 #                    date:long_name = "Time" ;
 #                    date:units = "days since 1960-01-01" ;
 #                    date:time_origin = "01-JAN-1960:00:00:00" ;
 #            float ALICE(date, lat, lon) ;
 #                    ALICE:source = " " ;
 #                    ALICE:name = "ALICE" ;
 #                    ALICE:title = "Emissions of ALICE in kg/m^2/s" ;
 #                    ALICE:date = "01/01/60" ;
 #                    ALICE:time = "00:00" ;
 #                    ALICE:long_name = "Emissions of ALICE in kg/m^2/s" ;
 #                    ALICE:standard_name = "tendency_of_atmosphere_mass_content_of_ALICE_due_to_emission" ;
 #                    ALICE:units = "kg/m2/s" ;
 #                    ALICE:missing_value = 2.e+20f ;
 #                    ALICE:_FillValue = 2.e+20f ;
 #                    ALICE:valid_min = 0.f ;
 #                    ALICE:valid_max = 2.60646e-08f ;
 #    
 #    // global attributes:
 #                    :history = "Tue Jun 18 14:32:42 BST 2013 - XCONV V1.92 16-February-2006" ;
 #    }
 #
 #  whereas, the metadata of the 
 #  /home/vagrant/umdir/ancil/atmos/n48e/ukca_emiss/cmip5/2000/v1/ukca_emiss_CO.nc
 #  file is, e.g.:
 #
 #    netcdf ukca_emiss_CO {
 #    dimensions:
 #            time = UNLIMITED ; // (12 currently)
 #            model_level_number = 1 ;
 #            latitude = 72 ;
 #            longitude = 96 ;
 #            bnds = 2 ;
 #    variables:
 #            double emissions_CO(time, model_level_number, latitude, longitude) ;
 #                    emissions_CO:long_name = "CO surf emissions" ;
 #                    emissions_CO:units = "kg m-2 s-1" ;
 #                    emissions_CO:um_stash_source = "m01s00i303" ;
 #                    emissions_CO:tracer_name = "CO" ;
 #                    emissions_CO:vertical_scaling = "surface" ;
 #                    emissions_CO:cell_methods = "time: mean" ;
 #                    emissions_CO:grid_mapping = "latitude_longitude" ;
 #                    emissions_CO:coordinates = "forecast_period forecast_reference_time" ;
 #            int latitude_longitude ;
 #                    latitude_longitude:grid_mapping_name = "latitude_longitude" ;
 #                    latitude_longitude:longitude_of_prime_meridian = 0. ;
 #                    latitude_longitude:earth_radius = 6371229. ;
 #            double time(time) ;
 #                    time:axis = "T" ;
 #                    time:bounds = "time_bnds" ;
 #                    time:units = "hours since 1970-01-01 00:00:00" ;
 #                    time:standard_name = "time" ;
 #                    time:calendar = "360_day" ;
 #            double time_bnds(time, bnds) ;
 #            int model_level_number(model_level_number) ;
 #                    model_level_number:axis = "Z" ;
 #                    model_level_number:units = "metre" ;
 #                    model_level_number:standard_name = "model_level_number" ;
 #                    model_level_number:long_name = "height at theta layer midpoint" ;
 #                    model_level_number:positive = "up" ;
 #            float latitude(latitude) ;
 #                    latitude:axis = "Y" ;
 #                    latitude:bounds = "latitude_bnds" ;
 #                    latitude:units = "degrees_north" ;
 #                    latitude:standard_name = "latitude" ;
 #            float latitude_bnds(latitude, bnds) ;
 #            float longitude(longitude) ;
 #                    longitude:axis = "X" ;
 #                    longitude:bounds = "longitude_bnds" ;
 #                    longitude:units = "degrees_east" ;
 #                    longitude:standard_name = "longitude" ;
 #            double longitude_bnds(longitude, bnds) ;
 #            double forecast_period ;
 #                    forecast_period:bounds = "forecast_period_bnds" ;
 #                    forecast_period:units = "hours" ;
 #                    forecast_period:standard_name = "forecast_period" ;
 #            double forecast_period_bnds(bnds) ;
 #            double forecast_reference_time(time) ;
 #                    forecast_reference_time:units = "hours since 1970-01-01 00:00:00" ;
 #                    forecast_reference_time:standard_name = "forecast_reference_time" ;
 #                    forecast_reference_time:calendar = "360_day" ;
 #    
 #    // global attributes:
 #                    :emission_type = "2" ;
 #                    :source = "Data from Met Office Unified Model" ;
 #                    :um_version = "7.3" ;
 #                    :update_freq_in_hours = "120" ;
 #                    :update_type = "2" ;
 #                    :Conventions = "CF-1.5" ;
 #    }
 #
 #  so the metadata of our new emissions file needs to be edited to be what UKCA
 #  expects.
 #
 #  After using this script, the resultant netCDF file should look like:
 #
 #    netcdf ukca_emiss_ALICE {
 #    dimensions:
 #            time = 12 ;
 #            model_level_number = 1 ;
 #            latitude = 72 ;
 #            longitude = 96 ;
 #            bnds = 2 ;
 #    variables:
 #            float emissions_ALICE(time, model_level_number, latitude, longitude) ;
 #                    emissions_ALICE:_FillValue = 1.e+20f ;
 #                    emissions_ALICE:long_name = "ALICE surf emissions" ;
 #                    emissions_ALICE:units = "kg m-2 s-1" ;
 #                    emissions_ALICE:missing_value = 1.e+20 ;
 #                    emissions_ALICE:tracer_name = "ALICE" ;
 #                    emissions_ALICE:vertical_scaling = "surface" ;
 #                    emissions_ALICE:cell_methods = "time: mean" ;
 #                    emissions_ALICE:grid_mapping = "latitude_longitude" ;
 #                    emissions_ALICE:coordinates = "forecast_period forecast_reference_time" ;
 #            int latitude_longitude ;
 #                    latitude_longitude:grid_mapping_name = "latitude_longitude" ;
 #                    latitude_longitude:longitude_of_prime_meridian = 0. ;
 #                    latitude_longitude:earth_radius = 6371229. ;
 #            double time(time) ;
 #                    time:axis = "T" ;
 #                    time:units = "hours since 1970-01-01" ;
 #                    time:standard_name = "time" ;
 #                    time:long_name = "Time" ;
 #                    time:calendar = "360_day" ;
 #                    time:time_origin = "01-JAN-1960:00:00:00" ;
 #            int model_level_number(model_level_number) ;
 #                    model_level_number:axis = "Z" ;
 #                    model_level_number:units = "1" ;
 #                    model_level_number:standard_name = "model_level_number" ;
 #                    model_level_number:positive = "up" ;
 #            double latitude(latitude) ;
 #                    latitude:axis = "Y" ;
 #                    latitude:bounds = "latitude_bnds" ;
 #                    latitude:units = "degrees_north" ;
 #                    latitude:standard_name = "latitude" ;
 #            double latitude_bnds(latitude, bnds) ;
 #            double longitude(longitude) ;
 #                    longitude:axis = "X" ;
 #                    longitude:bounds = "longitude_bnds" ;
 #                    longitude:units = "degrees_east" ;
 #                    longitude:standard_name = "longitude" ;
 #            double longitude_bnds(longitude, bnds) ;
 #            double forecast_period ;
 #                    forecast_period:bounds = "forecast_period_bnds" ;
 #                    forecast_period:units = "hours" ;
 #                    forecast_period:standard_name = "forecast_period" ;
 #            double forecast_period_bnds(bnds) ;
 #            double forecast_reference_time(time) ;
 #                    forecast_reference_time:bounds = "forecast_reference_time_bnds" ;
 #                    forecast_reference_time:units = "hours since 1970-01-01" ;
 #                    forecast_reference_time:standard_name = "forecast_reference_time" ;
 #                    forecast_reference_time:calendar = "360_day" ;
 #            double forecast_reference_time_bnds(time, bnds) ;
 #    
 #    // global attributes:
 #                    :Conventions = "CF-1.5" ;
 #                    :date = "01/01/60" ;
 #                    :emission_type = "2" ;
 #                    :history = "Tue Jun 18 14:32:42 BST 2013 - XCONV V1.92 16-February-2006" ;
 #                    :invalid_standard_name = "tendency_of_atmosphere_mass_content_of_ALICE_due_to_emission" ;
 #                    :name = "ALICE" ;
 #                    :source = "UKCA Tutorial Task 5.1 - creating netCDF emissions" ;
 #                    :time = "00:00" ;
 #                    :title = "Emissions of ALICE in kg/m^2/s" ;
 #                    :update_freq_in_hours = "120" ;
 #                    :update_type = "2" ;
 #                    :valid_max = 2.60646e-08f ;
 #                    :valid_min = 0.f ;
 #    }

All scripts provided for these tutorials can also be found on [https://github.com/theabro/ukca GitHub].

==Solution to Task5.1==

You were given the task:

* ''In the <pre>/work/n02/n02/ukca/Tutorial/vn10.9/Task5.1</pre> directory on ARCHER there is the file '''Emissions_of_ALICE.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:

<gallery widths=300px heights=300px>
Image:ALICE_ems_0.5x0.5.png|ALICE emissions prior to regridding. 
Image:Vn10.9_ALICE_emiss_N48e.png|ALICE emissions after regridding. Note the shift of the grid.
</gallery>

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

 /work/n02/n02/ukca/Tutorial/vn10.9/Task5.1/solution/ukca_emiss_ALICE.nc

==Task 5.2: make the required code changes to add your emission into UKCA==

<span style="color:green">'''TASK 5.2:''' You should now make the UKCA code changes to add your emission into the '''ALICE''' tracer. Use STASH code <code>s50i304</code> for the diagnosic.</span>

{| class="collapsible collapsed wikitable"
|-
! Hint 
|-
| You will need to add-in the molar mass of ALICE. You can calculate this from the mass of air and the conversion factor defined in [[UKCA_Chemistry_and_Aerosol_vn10.9_Tutorial_4#Task_4.1:_Add_new_tracers_into_Rose_and_UKCA|Task 4.1]].<br/> You will need to add code to allow a diagnostic of the emission to be output.
|}

==Rose changes==

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

<ol>
<li value="1">With a full path to the file</li>
<li value="2">Using environment variables set using an '''ancil_versions''' file</li>
<li value="3">A mixture of (1) and (2)</li>
<li value="4">By specifying a top-level directory in the '''<code>ukca_em_dir</code>''' Rose variable, and then paths to the required files within '''<code>ukca_em_files</code>'''</li>
</ol>

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 '''4''' above, specifying both '''<code>ukca_em_dir</code>''' and '''<code>ukca_em_files</code>'''. 

===ARCHER===

As '''<code>ukca_em_dir</code>''' is within <code>UM_INSTALL_DIR</code>, you will need to either copy or symbolically-link the directories from here to your own space on '''<code>/work</code>'''.

<code>UM_INSTALL_DIR</code> is set in the <code>suite.rc</code> file to be <code>UMDIR</code>, so you can make the required changes like this:

 mkdir ukca_emiss
 cd ukca_emiss
 ln -s /work/n02/n02/hum/ancil/atmos/n48e/ukca_emiss/andres_kasgnoc
 ln -s /work/n02/n02/hum/ancil/atmos/n48e/ukca_emiss/cmip5
 ln -s /work/n02/n02/hum/ancil/atmos/n48e/ukca_emiss/gfed3.1

You can then either copy or symbolically link your newly-created emissions file into this directory as well. 

This directory will need to be on <code>/work</code> as the batch queues are unable to see <code>/home</code>.

===Virtual Machine===

On the VM you do have write permissions for <code>UMDIR</code>, which is located at <code>/home/vagrant/umdir</code>, so you could either copy your new emissions file there, or follow the ARCHER instructions above.

===Make your Rose changes===

Once you have created the required directory structure you should change the value of '''<code>ukca_em_dir</code>''' to point to your new directory, and then go to the '''<code>ukca_em_files</code>''' list. Click the '''blue plus symbol''' to add an extra line, and put the path to the new file, relative to this directory.

If your emissions files are defined with the full path, and/or in a single long list, make the changes accordingly.

==Code changes==

===<code>ukca_chem_master.F90</code>===

You can choose to put a '''1''' in the '''E''' column of the '''<code>chch_defs</code>''' array. This is just for completeness however, as this column is not currently used.

===<code>ukca_setd1defs.F90</code>===

You will need to edit the '''<code>em_chem_spec</code>''' array for the scheme that you are using to include the new species that you are emitting into. By convention, these are ordered as 2D fields followed by 3D fields, although this order is unimportant other than the fact that the 2D emissions should be placed before the 3D emissions of '''<code>'SO2_nat'</code>''', '''<code>'BC_biomass'</code>''', '''<code>'OC_biomass'</code>''', and '''<code>'NO_aircrft'</code>''' if these are present. 

If the tracer is valid for both with and without aerosol chemistry (& GLOMAP) you will need to put this in twice. Also remember to increment this size of the '''<code>em_chem_spec</code>''' array, given by '''<code>n_chem_emissions</code>''' variable.

===<code>ukca_constants.F90</code>===

You will need to define the '''<code>M_<span style="color:blue">species</span></code>''' for the emitted species. This should be consistent with the '''<code>C_<span style="color:blue">species</span></code>''' value set  in [[UKCA_Chemistry_and_Aerosol_vn10.9_Tutorial_4#ukca_constants.F90|the previous tutorial]].

===<code>get_molmass_mod.F90</code>===

You will need to add to the '''<code>species_name</code>''' <code>CASE</code> statement, to include a line such as this

 CASE ('ALICE     ')
   get_molmass = m_ALICE

for each new species that you are emitting into.

===Emissions diagnostics===

By default, when emitting into a new species, the code requires you to create a diagnostic for these emissions as well. This is done by considering the following file and routines:

====<code>STASHmaster_A</code> and <code>STASHmaster-meta.conf</code>====

You should add a diagnostic in a similar way to the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_4#STASHmaster_A|section 34 tracers]], but in this case to '''section 50'''. It is best to copy an existing 2D (or 3D) emissions diagnostic specification, and make only the required edits to that.

Once you have made these code changes you should '''commit your branch''' to ensure that these changes are picked-up by your suite correctly.

====<code>get_emdiag_stash_mod.F90</code>====

Once you have decided on the STASH code to use, you need to add the species and 3-digit '''item''' code to this routine in the CASE statement.

====<code>ukca_emdiags_struct_mod.F90</code>====

This routine contains the derived type that holds the emissions fluxes for all species. You will need to add a logical (used to determine whether the output has been requested in STASH) and a pointer to a 2D or 3D array that will hold the emissions flux.

====<code>ukca_update_emdiagstruct_mod.F90</code>====

In this routine you will need to add the initialisation of the logical added in <code>ukca_emdiags_struct_mod.F90</code>, as well as a small block of code that copies the 2D/3D <code>em_diags</code> data into the newly created pointer in the derived type. The logical will also need to be set to <code>.TRUE.</code> if STASH output has been requested (determined by the <code>sf(item,section)</code> look-up array).

Here is it easiest to copy an existing code-block and make the necessary changes for your new emission.

====<code>ukca_emiss_diags_mod.F90</code>====

In this routine you will add a unique code-block for this diagnostic that copies the pointer in the derived type into the <code>stashwork</code> array using the <code>copydiag</code> <code>copydiag_3d</code> routines. The <code>stashwork</code> array contains all the fields that will be output through STASH.

Here is it easiest to copy an existing code-block and make the necessary changes for your new emission.

====<code>ukca_emiss_ctl_mod.F90</code>====

The call to '''<code>ukca_emiss_diags</code>''' is protected by an IF statement, and you'll need to add a check to the entry in the '''<code>sf</code>''' array to see if the diagnostic is on. This should be of the format '''<code>sf(N,section)</code>''', where '''N''' is the item number of your new emissions diagnostic.

==Solution to Task 5.2==

[[Image:Vn10.9_s34i064_addemiss.png|thumb|300px|right|Surface level (20m) concentrations (kg/kg) of ALICE after emissions have been applied.]]

You were given the task

* ''You should now make the UKCA code changes to add your emission into the ALICE tracer. Use STASH code s50i304 for the diagnosic.''

You were given the hints

* ''You will need to add-in the molar mass of ALICE. You can calculate this from the mass of air and the conversion factor defined in [[UKCA_Chemistry_and_Aerosol_vn10.9_Tutorial_4#Task_4.1:_Add_new_tracers_into_Rose_and_UKCA|Task 4.1]].''
* ''You will need to add code to allow a diagnostic of the emission to be output.''

Once you have made the required code and Rose changes, you should now see that you ALICE tracer (s34i064) no longer contains noise, but now looks a bit like the emissions field you created in [[#Task_5.1:_Create_a_new_emissions_file_and_use_it_in_your_job|Task 5.1]].

For a working Rose suite that has completed this task, please see
* '''ARCHER:''' <code>u-as292@59922</code>
* '''vm:''' <code>u-as297@59923</code>

The specific Rose changes made are:

* '''ARCHER:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/59922/a/s/2/9/2/trunk
* '''vm:''' 
** https://code.metoffice.gov.uk/trac/roses-u/changeset/59921/a/s/2/9/7/trunk
** https://code.metoffice.gov.uk/trac/roses-u/changeset/59923/a/s/2/9/7/trunk

The specific Rose changes made are:

'''ARCHER:'''
 Index: app/um/rose-app.conf
 ===================================================================
 --- app/um/rose-app.conf	(revision 59818)
 +++ app/um/rose-app.conf	(revision 59922)
 @@ -2638,7 +2638,7 @@
  ukca_cfc115mmr=4.584e-11
  ukca_ch2br2mmr=1.802e-11
  ukca_cosmmr=1.000e-9
 -ukca_em_dir='$UM_INSTALL_DIR/ancil/atmos/n48e/ukca_emiss'
 +ukca_em_dir='/work/n02/n02/ukca/Tutorial/vn10.9/ukca_emiss'
  ukca_em_files='gfed3.1/clim_2002_2011/v2/ukca_emiss_BC_biomass_L38.nc',
               ='gfed3.1/clim_2002_2011/v2/ukca_emiss_OC_biomass_L38.nc',
               ='andres_kasgnoc/v1/ukca_emiss_SO2_nat_L38.nc',
 @@ -2661,7 +2661,8 @@
               ='cmip5/2000/v1/ukca_emiss_Me2CO.nc',
               ='cmip5/2000/v1/ukca_emiss_C5H8.nc',
               ='cmip5/2000/v1/ukca_emiss_NVOC.nc',
 -             ='cmip5/2000/v1/ukca_emiss_CO.nc'
 +             ='cmip5/2000/v1/ukca_emiss_CO.nc',
 +             ='Task5.1/solution/ukca_emiss_ALICE.nc'
  ukca_h1202mmr=3.788e-13
  ukca_h1211mmr=2.225e-11
  ukca_h1301mmr=1.363e-11
 Index: app/fcm_make/rose-app.conf
 ===================================================================
 --- app/fcm_make/rose-app.conf	(revision 59818)
 +++ app/fcm_make/rose-app.conf	(revision 59922)
 @@ -42,4 +42,4 @@
  stash_version=1A
  timer_version=3A
  um_rev=vn10.9
 -um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46535
 +um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46574

These differences can be found in the file '''<code>/home/ukca/Tutorial/vn10.9/worked_solutions/Task5.2/Task5.2_rose.patch</code>''' on PUMA.

'''vm:'''
 Index: app/um/rose-app.conf
 ===================================================================
 --- app/um/rose-app.conf	(revision 59815)
 +++ app/um/rose-app.conf	(revision 59923)
 @@ -2641,7 +2641,7 @@
  ukca_cfc115mmr=4.584e-11
  ukca_ch2br2mmr=1.802e-11
  ukca_cosmmr=1.000e-9
 -ukca_em_dir='$UMDIR/ancil/atmos/n48e/ukca_emiss'
 +ukca_em_dir='/home/vagrant/ukca_emiss'
  ukca_em_files='gfed3.1/clim_2002_2011/v2/ukca_emiss_BC_biomass.nc',
               ='gfed3.1/clim_2002_2011/v2/ukca_emiss_OC_biomass.nc',
               ='andres_kasgnoc/v1/ukca_emiss_SO2_nat.nc',
 @@ -2664,7 +2664,8 @@
               ='cmip5/2000/v1/ukca_emiss_Me2CO.nc',
               ='cmip5/2000/v1/ukca_emiss_C5H8.nc',
               ='cmip5/2000/v1/ukca_emiss_NVOC.nc',
 -             ='cmip5/2000/v1/ukca_emiss_CO.nc'
 +             ='cmip5/2000/v1/ukca_emiss_CO.nc',
 +             ='Task5.1/solution/ukca_emiss_ALICE.nc'
  ukca_h1202mmr=3.788e-13
  ukca_h1211mmr=2.225e-11
  ukca_h1301mmr=1.363e-11
 Index: app/fcm_make/rose-app.conf
 ===================================================================
 --- app/fcm_make/rose-app.conf	(revision 59815)
 +++ app/fcm_make/rose-app.conf	(revision 59923)
 @@ -42,4 +42,4 @@
  stash_version=1A
  timer_version=3A
  um_rev=vn10.9
 -um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46535
 +um_sources=branches/dev/lukeabraham/vn10.9_UKCA_Tutorial_Solns@46574

For a working UM branch that has completed this task, please see 

The specific UM changes made are:

 Index: src/atmosphere/UKCA/ukca_setd1defs.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_setd1defs.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_setd1defs.F90	(revision 46574)
 @@ -313,7 +313,7 @@
        nr_phot         = 38
      END IF
    ELSE IF (L_ukca_strattrop .AND. .NOT. L_ukca_achem) THEN
 -    n_chem_emissions = 9
 +    n_chem_emissions = 10
      n_3d_emissions = 1       ! aircraft NOX
      n_aero_tracers =  0
      ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
 @@ -320,13 +320,13 @@
      em_chem_spec =                                             &
          (/'NO        ','CH4       ','CO        ','HCHO      ', &
            'C2H6      ','C3H8      ','Me2CO     ','MeCHO     ', &
 -          'C5H8      ','NO_aircrft'/)
 +          'C5H8      ','ALICE     ','NO_aircrft'/)
      n_chem_tracers = 73         ! No chem tracers
      nr_therm       = 220        ! thermal reactions
      nr_phot        = 55         ! photolytic (ATA)
  
    ELSE IF (L_ukca_strattrop .AND. L_ukca_achem) THEN
 -    n_chem_emissions = 19      ! em_chem_spec below
 +    n_chem_emissions = 20      ! em_chem_spec below
      n_3d_emissions   = 4       ! BC, OC, volc SO2 & aircraft NOX
      ALLOCATE(em_chem_spec(n_chem_emissions+n_3d_emissions))
      em_chem_spec =                                             &
 @@ -335,7 +335,7 @@
            'C5H8      ','BC_fossil ','BC_biofuel','OC_fossil ', &
            'OC_biofuel','Monoterp  ','NVOC      ','SO2_low   ', &
            'SO2_high  ','NH3       ','DMS       ','SO2_nat   ', &
 -          'BC_biomass','OC_biomass','NO_aircrft'/)
 +          'BC_biomass','OC_biomass','ALICE     ','NO_aircrft'/)
      n_aero_tracers = 12
      n_chem_tracers = 73         ! No chem tracers
      IF (L_ukca_trophet) THEN
 Index: src/atmosphere/UKCA/ukca_chem_master.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_chem_master.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_chem_master.F90	(revision 46574)
 @@ -377,7 +377,7 @@
  chch_t1(113,'MEMALD    ',1,'TR        ','          ',0,0,0,R,0,0,107),&
  chch_t1(114,'GLY       ',1,'TR        ','          ',0,1,0,R,0,0,107),&
  chch_t1(115,'oXYLENE   ',1,'TR        ','          ',0,0,1,R,0,0,107),&
 -chch_t1(116,'ALICE     ',1,'TR        ','          ',0,0,0,ST,0,0,107),&
 +chch_t1(116,'ALICE     ',1,'TR        ','          ',0,0,1,ST,0,0,107),&
  chch_t1(117,'BOB       ',1,'TR        ','          ',0,0,0,ST,0,0,107)/)
  
  ! Heterogeneous chemistry
 Index: src/atmosphere/UKCA/get_molmass_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/get_molmass_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/get_molmass_mod.F90	(revision 46574)
 @@ -243,6 +243,11 @@
    get_molmass = m_brcl
  
    ! -----------------------------------------
 +  !   UKCA Tutorial Tracer
 +CASE ('ALICE     ')
 +  get_molmass = m_ALICE
 +
 +  ! -----------------------------------------
    !   Others (report warning)
  CASE ('AGE       ')
    get_molmass =  1.0
 Index: src/atmosphere/UKCA/ukca_constants.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_constants.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_constants.F90	(revision 46574)
 @@ -370,6 +370,8 @@
  REAL, PARAMETER :: m_mgly    = 72.0
  REAL, PARAMETER :: m_hacet  = 74.0
  
 +!     UKCA Tutorial tracers - only ALICE is emitted
 +REAL, PARAMETER :: m_ALICE    = 28.97  
  
  !     Extra masses for EXTTC chemistry
  REAL, PARAMETER :: m_apin     =  136.0
 Index: src/atmosphere/UKCA/ukca_emiss_diags_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_emiss_diags_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_emiss_diags_mod.F90	(revision 46574)
 @@ -584,6 +584,23 @@
    END IF
  END IF
  
 +!---------------------------------------------------------------------
 +! Sec 50, item 304: ALICE surface emissions
 +item = get_emdiag_stash ('ALICE     ')
 +IF (sf(item, section)) THEN
 +
 +  ! DEPENDS ON: copydiag
 +  CALL copydiag (stashwork (si(item,section,im_index)),              &
 +                 emdiags%em_ALICE (:,:),                             &
 +                 row_length, rows, 0,0,0,0, at_extremity,            &
 +                 atmos_im, section, item, icode, cmessage)
 +
 +  IF (icode >  0) THEN
 +    errcode = section*1000+item
 +    CALL ereport ('UKCA_EMISS_DIAGS', errcode, cmessage)
 +  END IF
 +END IF
 +
  IF (lhook) CALL dr_hook(ModuleName//':'//RoutineName,zhook_out,zhook_handle)
  
  RETURN
 Index: src/atmosphere/UKCA/ukca_emiss_ctl_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_emiss_ctl_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_emiss_ctl_mod.F90	(revision 46574)
 @@ -788,7 +788,8 @@
      sf(168,section) .OR. sf(169,section) .OR. sf(170,section) .OR.      &
      sf(171,section) .OR. sf(172,section) .OR. sf(211,section) .OR.      &
      sf(212,section) .OR. sf(213,section) .OR. sf(214,section) .OR.      &
 -    sf(215,section) .OR. sf(216,section) .OR. sf(217,section) ) THEN
 +    sf(215,section) .OR. sf(216,section) .OR. sf(217,section) .OR.      &
 +    sf(304,section)) THEN
  
    CALL ukca_emiss_diags (row_length, rows, model_levels,                &
      len_stashwork50, stashwork50)
 Index: src/atmosphere/UKCA/get_emdiag_stash_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/get_emdiag_stash_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/get_emdiag_stash_mod.F90	(revision 46574)
 @@ -142,6 +142,9 @@
  CASE ('SO2_nat   ')
    get_emdiag_stash = 217
  
 +CASE ('ALICE     ')
 +  get_emdiag_stash = 304
 +
  CASE DEFAULT
    ! Report error unless this is an aerosol emission (BC_fossil:, etc)
    ! No diagnostics for these source emissions because the resulting
 Index: src/atmosphere/UKCA/ukca_emdiags_struct_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_emdiags_struct_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_emdiags_struct_mod.F90	(revision 46574)
 @@ -53,6 +53,7 @@
    LOGICAL :: l_em_so2low  
    LOGICAL :: l_em_so2hi  
    LOGICAL :: l_em_so2nat 
 +  LOGICAL :: l_em_ALICE
  
    ! Pointers to hold emission diagnostics
    REAL, POINTER :: em_no     (:,:)
 @@ -79,6 +80,7 @@
    REAL, POINTER :: em_so2low (:,:)
    REAL, POINTER :: em_so2hi  (:,:)
    REAL, POINTER :: em_so2nat (:,:,:)
 +  REAL, POINTER :: em_ALICE  (:,:)
  
  END TYPE emdiags_struct
  
 Index: src/atmosphere/UKCA/ukca_update_emdiagstruct_mod.F90
 ===================================================================
 --- src/atmosphere/UKCA/ukca_update_emdiagstruct_mod.F90	(revision 46535)
 +++ src/atmosphere/UKCA/ukca_update_emdiagstruct_mod.F90	(revision 46574)
 @@ -111,6 +111,7 @@
    emdiags%l_em_so2low = .FALSE.
    emdiags%l_em_so2hi  = .FALSE.
    emdiags%l_em_so2nat = .FALSE.
 +  emdiags%l_em_ALICE  = .FALSE.
  
    l_first             = .FALSE.
  END IF
 @@ -399,6 +400,17 @@
      END IF
    END IF
  
 +CASE ('ALICE      ')
 +  IF (emdiags%l_em_ALICE) THEN
 +    emdiags%em_ALICE (:,:) = em_diags (:,:,1)
 +  ELSE
 +    IF (sf(item,section)) THEN
 +      ALLOCATE (emdiags%em_ALICE (row_length, rows))
 +      emdiags%em_ALICE (:,:) = em_diags (:,:,1)
 +      emdiags%l_em_ALICE     = .TRUE.
 +    END IF
 +  END IF
 +
  CASE DEFAULT
      ! Report error unless this is an aerosol emission (BC_fossil:, etc)
    IF (.NOT. ANY(aero_ems_species == diag_name))  ierr = 1
 Index: rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf
 ===================================================================
 --- rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf	(revision 46535)
 +++ rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster-meta.conf	(revision 46574)
 @@ -22211,6 +22211,10 @@
      =
      =Available if chemistry is turned on in UKCA
  
 +[stashmaster:code(50304)]
 +description=alice emission flux (kg m-2 s-1)
 +help=Diagnostic to check the total ALICE surface emission flux
 +
  [stashmaster:code(51001)]
  description=O3 MASS MIXING RATIO ON PRESS LEVS
  help=Ozone Mass Mixing Ratio in kg/kg(Air)
 Index: rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A
 ===================================================================
 --- rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A	(revision 46535)
 +++ rose-meta/um-atmos/HEAD/etc/stash/STASHmaster/STASHmaster_A	(revision 46574)
 @@ -24236,6 +24236,12 @@
  4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
  5|    0 | 3834 |    0 |  129 |    0 |    0 |    0 |    0 |    0 |
  #
 +1|    1 |   50 |  304 |ALICE surf emissions (kg m-2 s-1)   |
 +2|    0 |    0 |    1 |    1 |    5 |   -1 |   -1 |    0 |    0 |    0 |    0 |
 +3| 000000000000000000000000010000 | 00000000000000000001 |    3 |
 +4|    1 |    0 | -99  -99  -99  -99  -99  -99  -99  -99  -99  -99 |
 +5|    0 | 1876 |    0 |  129 |    0 |    0 |    0 |    0 |    0 |
 +#
  #===============================================================================
  # Section 50 Item 999 reserved.
  #===============================================================================

 
These differences can be found in the file '''<code>/home/ukca/Tutorial/vn10.9/worked_solutions/Task5.2/Task5.2_code.patch</code>''' on PUMA. 

Sample output from this task can be found at '''<code>/work/n02/n02/ukca/Tutorial/vn10.9/sample_output/Task5.2/atmosa.pa19810901_00</code>''' on ARCHER.

==Task 5.3: Output the diagnostic of your new emission==

<span style="color:green">'''Task 5.3:''' Now that you are able to run the model with your new emission file, output this as a diagnostic to the '''UPA''' stream as a 3-hour mean.</span>

You should reference the [[UKCA_Chemistry_and_Aerosol_vn10.9%2B_Tutorial_3|what is STASH]] tutorial for information on how to do this

==Solution to Task 5.3==

[[Image:Vn10.9_s50i304.png|thumb|300px|right|ALICE emission flux diagnostic output.]]

You were given the task:

* ''Now that you are able to run the model with your new emission file, output this as a diagnostic to the '''UPA''' stream as a 3-hour mean.''

This achieved by outputting s50i304 to the UPA stream in STASH.

You will now find the additional field in your output file:

  23   : 96    72    1     1     mflux: Stash code 50304

For a working Rose suite that has completed this task, please see
* '''ARCHER:''' <code>u-as292@59937</code>
* '''vm:''' <code>u-as297@59931</code>

The specific Rose changes made are:

* '''ARCHER:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/59937/a/s/2/9/2/trunk
* '''vm:''' https://code.metoffice.gov.uk/trac/roses-u/changeset/59931/a/s/2/9/7/trunk

The specific Rose changes made are:

'''ARCHER:'''
 Index: app/um/rose-app.conf
 ===================================================================
 --- app/um/rose-app.conf	(revision 59922)
 +++ app/um/rose-app.conf	(revision 59937)
 @@ -3449,6 +3449,14 @@
  tim_name='T3HMN'
  use_name='UPA'
  
 +[namelist:umstash_streq(50304_f1d61e7a)]
 +dom_name='DIAG'
 +isec=50
 +item=304
 +package=''
 +tim_name='T3HMN'
 +use_name='UPA'
 +
  [namelist:umstash_streq(51001_3e6241a4)]
  dom_name='DP27CCM'
  isec=51

These differences can be found in the file '''<code>/home/ukca/Tutorial/vn10.9/worked_solutions/Task5.3/Task5.3_rose.patch</code>''' on PUMA.

'''vm:'''
 Index: app/um/rose-app.conf
 ===================================================================
 --- app/um/rose-app.conf	(revision 59923)
 +++ app/um/rose-app.conf	(revision 59931)
 @@ -4041,6 +4041,14 @@
  tim_name='T3HMN'
  use_name='UPA'
  
 +[namelist:umstash_streq(50304_f1d61e7a)]
 +dom_name='DIAG'
 +isec=50
 +item=304
 +package=''
 +tim_name='T3HMN'
 +use_name='UPA'
 +
  [namelist:umstash_streq(51001_3e6241a4)]
  dom_name='DP27CCM'
  isec=51

Sample output from this task can be found at '''<code>/work/n02/n02/ukca/Tutorial/vn10.9/sample_output/Task5.3/atmosa.pa19810901_00</code>''' on ARCHER.

==Checklist==

: <span style="font-size:20px">☐</span> Obtain emissions data for the species of interest.
: <span style="font-size:20px">☐</span> Regrid the emissions to the correct MetUM resolution that you are using.
: <span style="font-size:20px">☐</span> Save these emissions as netCDF, including the required metadata that UKCA requires.
: <span style="font-size:20px">☐</span> In your suite, include this file in the <code>ukca_em_files</code> variable in the UKCA panel: um <math>\rightarrow</math> namelist <math>\rightarrow</math> UM Science Settings <math>\rightarrow</math> Section 34 - UKCA: UK Aerosols and Chemistry.
: <span style="font-size:20px">☐</span> (Optional) Put a 1 in the E column of the <code>chch_defs_master</code> in <code>ukca_chem_master.F90</code>.
: <span style="font-size:20px">☐</span> Put the species being emitted into the <code>em_chem_spec</code> array in <code>ukca_setd1defs.F90</code>, and increment <code>n_chem_emissions</code>.
: <span style="font-size:20px">☐</span> Put the correct M_species value in <code>ukca_constants.F90</code>.
: <span style="font-size:20px">☐</span> In <code>get_molmass_mod.F90</code>, append the CASE statement with your new species.
: <span style="font-size:20px">☐</span> Make diagnostics output slots for your new emissions in <code>STASHmaster_A</code> and add help-text to <code>STASHmaster-meta.conf</code>. 
: <span style="font-size:20px">☐</span> In <code>get_emdiag_stash_mod.F90</code> add the species and 3-digit item code to the CASE statement.
: <span style="font-size:20px">☐</span> In <code>ukca_emdiags_struct_mod.F90</code> add a logical and array pointer to the derived type for your new species.
: <span style="font-size:20px">☐</span> In <code>ukca_update_emdiagstruct_mod.F90</code> initialise your new derived type entries, and add a block of code to copy the emissions field into the diagnostic pointer.
: <span style="font-size:20px">☐</span> In <code>ukca_emiss_diags_mod.F90</code> add a code block to copy the field to the <code>stashwork</code> array using <code>copydiag</code>/<code>copydiag_3d</code>. 
: <span style="font-size:20px">☐</span> In <code>ukca_emiss_ctl_mod.F90</code> add the <code>sf(ITEM,section)</code> check in the IF statement protecting the call to <code>ukca_emiss_diags</code>.
: <span style="font-size:20px">☐</span> <code> fcm commit</code> the changes to your branch.
: <span style="font-size:20px">☐</span> Output your emissions diagnostic in: um <math>\rightarrow</math> namelist <math>\rightarrow</math> Model Input and Output <math>\rightarrow</math> STASH Requests and Profiles <math>\rightarrow</math> STASH Requests.
: <span style="font-size:20px">☐</span> Run the TidyStashTransform transform macro.
: <span style="font-size:20px">☐</span> Save your suite.
: <span style="font-size:20px">☐</span> In the <code>roses/[SUITE-ID]</code> directory, run <code>fcm commit</code> to commit your changes to the repository.
: <span style="font-size:20px">☐</span> Run your suite.

[[UKCA Chemistry and Aerosol vn11.8 Tutorial 6|Tutorial 6]]
----
''Written by [[User:Nla27 | Luke Abraham]] 2020. Many thanks to Alistair Sellar for the notes on netCDF metadata.''