UM Ancillary files


Fields like sea surface temperatures and chemical emissions are needed for a simulation to run, but aren't calculated by the model. Instead the model obtains these through ancillary data files.

Selecting Ancil Files

Ancil files are selected in the UMUI under Atmosphere->Ancillary and Input data files. There are a couple subsections here, the important ones are Climatologies and Other Ancillary Files. Also here is where you can select the initial conditions file to use, in the Start Dump panel directly under Ancillary and Input.

Umuiancils.png

Fields like SSTs and emissions are selected in the Climatologies folder. The land mask and orography details are in the Other Ancillary Files

Processing

Each ancillary field can be included in the model in one of 3 ways. The field can be ignored, for instance if the selected science sections don't use it; the field can be configured as part of the initial conditions, making the field constant throughout the simulation; or the field can be updated from the ancillary file at regular intervals.

Ancilupdate.png

The controls for these on each panel are fairly self-explanatory. If you want the ancillary field to be periodic in time the ancil file itself must be set up for this, you cannot change this from the model settings.

Creating Ancil Files

Ancillary files can be created from netcdf format files using a tool called xancil``. This is a graphical tool like the UMUI, available on Raijin under ``~access/bin.

Xancil.png

In the general settings pane you'll need to set the version number to whatever UM version your model is using (a wrong value here could make the ancil file generate upside down compared to what the model expects). You should also set the calendar to whatever your model uses, Gregorian or 360 days. The UM expects 64-bit big-endian files so leave those at the defaults.

UM ancillary files are created using the Atmosphere Ancillary Files section. This includes SSTs, the Ocean section refers to the Nemo model used by HadGEM. Enabling a section allows you to enter a NetCDF file to import data from, and the names of variables in that file to use. You can also select here whether the ancil file is periodic in time, whether to use a land mask and if the dates should be imported from the file or manually selected.

Xancilsst.png

Once you've set up the ancil files you want to generate use the Create Anc. Files button at the bottom to create the files.

Some fields need special attention in their settings:

  • Sea Ice: Use AMIPII ancillary format for sea ice, not selecting this can make time interpolation fail when the UM reads in the ancil file.

Emission Ancillaries

Emission ancillary files such as soot, organic carbon, sulphur amongst others are not directly supported by Xancil. You can create these ancillary files by using Xancil's Generalised Ancillary function. This lets you create an ancillary file with any STASH code you need.

Xancil-bc hi.png

Ozone Ancillaries

If you get a message like

     Writing Ozone ancillary file /short/w35/saw562/ozone
     ERROR: variable model_level_number from NetCDF file /short/w35/saw562/test.nc
      doesn't contain the correct level coordinates.
     model_level_number contains data for level type model_level_number

you will need to set the vertical coordinates.

In Xancil, under `Configuration -> Grid Configuration` select `Specify atmosphere vertical levels`. ACCESS 1.0 uses 38 vertical levels, so put 38 into the number of model and ozone levels. The vertical levels namelist file to use is:

/projects/access/umdir/vn7.3/ctldata/vert/vertlevs_G3

Conversion errors

If you get an error like

ERROR: in procedure get_ncatt_text 1 : NetCDF error number          -49 : NetCDF: Variable not found : latitude_longitude

try manually using the newer version of the conversion script. Use the `Save namelist` button at the bottom to save the configuration, then run

~access/bin/mkancil0.57 < xancil.namelist

Automated creation of Ancillary files

Sometimes you might want to generate lots of ancillary files that are all similar. The following is a method Holger used successfully:

xancil can run in batch mode:

$ xancil -x -j <job file>

The easiest way to create this job file is to run xancil once manually, set it to do all the things you want it to do in one iteration, and then hit 'save job as' The job file can then be edited with a normal text editor into a template by replacing the parts (for example file names) that would change every time with keywords. Then you can use the sed command to create a job file for each iteration:

$ sed -s 's/KEYWORD/actual_value/g' < template_file > job_file

You can string several different Keyword/value replacements together with a semicolon.

I have used a Makefile to generate ancillary files before:

# Instead of using an external file as the template,
# I write it in a long variable:

define SOME_MEANINGFUL_NAME
<enter the text of the template here>
enddef
export SOME_MEANINGFUL_NAME

# To create the job file, I parse the variable through sed
# to replace the keywords with the values

my_jobfile.job :
        @echo "$$SOME_MEANINGFUL_NAME" | \
        sed -e 's/KEYWORD1/$(value1)/g;s/KEYWORD2/$(value2)/g;...' > $@

# Putting the list of required netcdf files into the Makefile means that make
# will automatically fail if they aren't there -- or you could use the same
# Makefile to generate them in the first place.

my_ancillary_file.um : my_jobfile.job required_netcdf_file1.nc required_netcdf_file2.nc ...
        xancil -x -j $<

Please note that Makefiles require a single tab (not 8 spaces as above) for the indentation.

The complete Makefile that I used to download emissions data, add up the different sources, and convert them to the correct grid before using the above method of generating the ancillary files is attached. A final word of warning: I make no guarantee that that is the best, or even a good, way to do that. All that I say is that it worked for me (Holger). File:Makefile

Modifying Ancil Files

The simplest way to modify existing ancil files is to convert them to netcdf format (see how here), perform any modifications to the fields that you need & then use xancil to convert the netcdf files back to ancil format.~access/bin/mkancil0.57 < xancil.namelist