Using Xancil


Xancil is a graphical package that is used to create Unfied Model ancillary files from netCDF files. Prior to using Xancil to create your files, you should ensure that the input netCDF files are on the correct grid (both horizontal and vertical) for the UM configuration that you are using.

Xancil is installed on ARCHER at


and on MONSooN (on the postproc03 machine) at


Xancil Settings

Figure 1: The Xancil GUI

You may already have this location in your PATH and so can just launch Xancil from the command line by typing xancil. When you do this it will load up the Xancil window, which is initially rather empty. You should click on the Xancil text in the top-left corner. This will give 4 options:

  • Configuration
  • Atmosphere Ancillary Files
  • Ocean Ancillary Files
  • Generalised Ancillary Files

Figure 1 shows the Xancil GUI with some of the menus open. You will probably not need to make up any ocean files, as HadGEM3 uses the NEMO ocean, but you will need to make use of the Atmosphere and Generalised Ancillary files when using UKCA.


General Configuration

In this panel you need to set the UM version number for the ancillary file you are creating (e.g. 8.4 etc). Failiure to do this will cause an error when running (as the default is UM4.5).

If you are using nudging you will need to change the calendar, and you may also want to output well-formed ancillary files.

On this panel you should tell Xancil which netCDF files it should read (which contain the data you want to make into ancillary files) and which corresponding STASHmaster files it should use that describe this data.

Grid Configuration

This panel is used to define the vertical grid being used, as well as being able to set the times used in the output ancillary files (although the time information can also be set in the individual ancillary file panels).

The vertical settings are only important for 3D ancillary files (e.g. UKCA aircraft emissions, which are on the theta grid), but in this case you will need use the specify atmosphere vertical levels, which takes the vertical level structure from the UM namelist that contains this information. The location of this namelist is specified in the UMUI in Model Selection → Atmosphere → Model Resolution and Domain → Vertical.

If you made up your input netCDF file using Xconv, and then you try to use the option which uses the name of the vertical levels from the netCDF file you may get the following error:

ERROR: variable hybrid_ht from NetCDF file 
name of netCDF input file
 doesn't contain the standard_name attribute needed to
 calculate vertical level values.

as Xconv does not output vertical levels which Xancil can read.

The ability to set the date and the number of times in the ancillary file is useful here, if needed.

Atmosphere Ancillary Files

This list gives the list of all the ancillary files that Xancil currently has defined settings for. We will not go through these in detail, but there are some options that you should be aware of.

At the top of each file panel will be the option "Is field to output periodic in time?" with Yes and No buttons. If you are making time-series ancillary file (e.g. data from 1960-2010) then the answer is No, but if you are making a climatology (e.g. 12 monthly values (Jan-Dec) or 4 seasonal values, or 1 annual value) then the answer is Yes.

You can use the Select button to choose the required field from the netCDF file. Usually Xancil will match up the name of the field in the file with the field code from the STASHmaster file, but if the name does not match (or matches a different field) then you will need to select this manually.

Generalised Ancillary Files

The Atmosphere Ancillary Files menu has only a sub-set of the number of ancillary files that you may wish to make up. If you want to make up a file that is not catered for you should use the Generalised Ancillary Files option.

There is feature of the Generalised Ancillary Files settings that you may need to be aware of. In the Generalised Ancillary Files → Configuration sub-menu you can select the number of different generalised ancillary files that you want to make (by default there is only one). If you make more than one, and then save your job using the Save button along the bottom of the GUI, when loading it again only the first file panel will appear. You will need to go back to the Generalised Ancillary Files → Configuration panel (which will show the correct number of files you wanted to make) increase the number by one, then decrease it back by one again. The full number of files (and their internal settings) will now be shown.

This panel is useful for making UKCA initial conditions.


Using the buttons along the bottom of the GUI you can Save (or Save As) the current job you are working on or Load an existing .job file (as well as the namelists associated with the files). You should use the Create Anc. Files button to create the ancillary files when you are ready to do this.

Note: When you are using Xancil from scratch with your own STASHmaster file, Xancil will change the name in the Ancillary File panels (but not the file itself, when it is created) to that in your STASHmaster file. Another feature of Xancil is that often, when re-loading a saved .job file, the name of the fields defined in the user STASHmaster file has been lost, and instead it reverts to the name in the STASHmaster_A file. This does not affect the data in each field however.

When making the ancillary files, you will be given messages both to the Output messages window, and to the terminal.

Written by Luke Abraham 2013