ants.fileformats.namelist package#

Module for reading Fortran namelist files and constructing Python or Iris objects, as appropriate, from the contents.

ants.fileformats.namelist.apply_um_conventions(cube)[source]#

Apply UM specific conventions to the resulting cube.

Latitude cells are enforced S-N in direction.

ants.fileformats.namelist.load_cap_horizontal(filenames, callback=None)[source]#

Load the horizontal namelist definition.

Load a model grid definition from one or more Fortran namelists, supporting both regular and variable resolution, global and regional grids.

Submodules#

ants.fileformats.namelist.umgrid module#

UM grid namelist format#

This module intends to generate cubes from UM grid namelist files.

The grid namelist specification for UM grids is historically split into two distinct encodings/usage: one was that defined by the central ancillary program (CAP) for geneating ancillaries; another is that utilised by the UM ecosystem.

The implementation here, supports the CAP specification for the purpose of the generation of ancillaries. However, we also support a subset of the UM ecosystem namelist specification (for supporting vertical levels) and also for horizontal grid namelists where it overlaps with the CAP specification.

For details on the specification supported here, the user should refer to CAPGridRegular for regular grids, CAPGridVariable for variable resolution grids and VerticalLevels for the vertical definition specification.

class ants.fileformats.namelist.umgrid.CAPGridRegular(definition)[source]#

Bases: _CAPGrid

UM grid regular grid namelist (‘GRID’) interpreter.

See the following specification:

points_lambda_targ
    - Number of columns (longitudes).
    - Optional: Parameter is derived if `delta_lambda_targ` specified.

points_phi_targ:
    - Number of rows (latitudes).
    - Optional: Parameter is derived if `phi_lambda_targ` specified.

lambda_origin_targ
    - Longitude origin.
    - Default: 0.0 if not specified.

phi_origin_targ:
    - Latitude origin.
    - Default: 90.0 if not specified. This parameter should be specified
      for ENDgame grids.

delta_lambda_targ:
    - Longitude spacing (degrees).
    - Optional: Parameter is derived if `points_lambda_targ` specified.

delta_phi_targ:
    - Latitutde spacing (degrees).
    - Optional: Parameter is derived if `points_phi_targ` specified.

phi_pole:
    - Real latitude of North Pole of the rotated grid.
    - Default: 90.0

lambda_pole:
    - Real longitude of North Pole of the rotated grid.
    - Default: 0.0

global:
    - Global grid.
    - Default: T (True).

igrid_targ:
    - Grid indicator (2=ArwakawaB, 3=ArwakawaC, 6=ENDgame).
    - Default: 6

inwsw:
    - ==0 if phi origin specified as NW corner. ==1 if SW corner.
    - Default: 1

Raises:

RuntimeError – If the grid is overspecified, and the number of points is not consistent with the spacing between the points, a RunTimeError will be raised.
RuntimeError – In the case where grids are underspecified, a suitable RuntimeError exception will be raised.

__init__(definition)[source]#

property attributes#: Return attributes extracted from the namelist.

defaults = {'grid': {'delta_lambda_targ': None, 'delta_phi_targ': None, 'global': True, 'igrid_targ': 6, 'inwsw': 0, 'lambda_origin_targ': 0.0, 'lambda_pole': 0.0, 'phi_origin_targ': 90.0, 'phi_pole': 90.0, 'points_lambda_targ': None, 'points_phi_targ': None, 'rotated_interp': None}}#

property is_endgame#: Return True for an ENDgame grid and false otherwise.

property shape#: Return tuple representing the shape of the grid.

property x#: Return x tuple (points, bounds).

property y#: Return y tuple (points, bounds).

class ants.fileformats.namelist.umgrid.CAPGridVariable(definition)[source]#

Bases: _CAPGrid

UM grid variable resolution grid namelist interpreter.

Variable resolution grids are defined using both ‘GRID’ and ‘HORIZGRID’ files. The former is the regular grid definition as defined in CAPGridRegular, except where variable grids are defined, only the coordinate system information (phi_pole, lambda_pole) is interpreted. Everything else is silently ignored.

The later file (‘HORIZGRID’) contains the definition of the variable resolution grid points:

lambda_input_p:
    - Longitude 'p' grid points.

lambda_input_u:
    - Longitude 'u' grid points.

phi_input_p:
    - Latitude 'p' grid points.

phi_input_v:
    - Latitude 'v' grid points.

Ancillaries are nearly always exclusively defined with the centre of the cells corresponding to the ‘p’ grid points. ‘u’ and ‘v’ points are then utilised in the definition to derive suitable bounds.

property attributes#: Return attributes extracted from the namelist.

defaults = {'grid': {'lambda_pole': 0, 'phi_pole': 90}, 'horizgrid': {'lambda_input_p': None, 'lambda_input_u': None, 'phi_input_p': None, 'phi_input_v': None}}#

property shape#: Return tuple representing the shape of the grid.

property x#: Return x tuple (points, bounds).

property y#: Return y tuple (points, bounds).

class ants.fileformats.namelist.umgrid.VerticalLevels(namelist_dict)[source]#

Bases: object

UM vertical level namelist interpreter.

Processes vertical namelists into iris vertical coordinates. There’s three distinct sets of vertical coordinates involved: The namelist defines the top of the model (z_top_of_model); the first spherical shell level (first_constant_r_rho_level) and the eta_theta and eta_rho levels (see UM New Dynamics Formulation for details). From these, the intermediate set of vertical coordinates - blev, brlev, bhlev and bhrlev are calculated (see UM input and output file formats (F03) for details).

The intermediate coordinates are used to calculate the final iris vertical coordinates: level_height (Zsea in F03 appendix A), sigma (C in F03 appendix A) and model level number. An additional method is provided to calculate a one dimensional cube with these vertical coordinates.

__init__(namelist_dict)[source]#

Parameters:

namelist_dict (dict) –

Dictionary containing the following items:

z_top_of_model : float
    height of model top [m]
first_constant_r_rho_level : int
    index of first pure spherical shell level (note: FORTRAN
    namelist, so indexed from 1)
eta_theta : list of float
    eta value for theta levels, must be one more float than the
    list for eta_rho.
eta_rho : list of float
    eta value for rho (density) levels, must be one fewer float
    than the list for eta_theta.

Raises:

ValueError – Raised if eta theta are eta rho are not consistent lengths.

get_cube(apply_UM_workaround=True)[source]#

Returns a one dimensional cube with the vertical coordinates attached.

Returns:: A cube with vertical coordinates model_level_number, level_height and sigma.
Return type:: iris.cube.Cube

property level_height#

Derive level_height AuxCoord with bounds.

The points of the coordinate are derived from eta_theta levels, while the bounds are derived from eta_rho levels. See Appendix A of F03 for details of the calculation.

Returns:: Coordinate describing the level heights derived from the vertical namelist.
Return type:: iris.coords.AuxCoord
Raises:: ValueError – Raised if the level height is not monotonically increasing.

property model_level_number#

Creates a model_level_number DimCoord without bounds.

Returns:: Coordinate describing the model level numbers derived from the vertical namelist.
Return type:: iris.coords.DimCoord

property sigma#

Creates a sigma AuxCoord with bounds.

The points of the coordinate are derived from eta_theta levels, while the bounds are derived from eta_rho levels. See Appendix A of F03 for details of the calculation.

Returns:: Coordinate describing the sigma (i.e. terrain following coordinate) derived from the vertical namelist.
Return type:: iris.coords.AuxCoord
Raises:: ValueError – Raised if the calculated coordinate is not monotonically decreasing.

ants.fileformats.namelist.umgrid.ngrid(n_number, grid_staggering)[source]#

Return the shape for the provided UM notation for global grid resolution.

The UM uses a notation of Nxxx for its global grid resolutions. These numbers map fairly straight forwardly onto the numbers of grid points in longitude and latitude.

The number of longitudes is twice the ‘N’ number.
The number of latitudes is 3/2 times the N’ number rounded down to the nearest integer (+1 for newdynamics).

Parameters:

n_number (int) – The UM global grid resolution notation.
grid_staggering (str or int) – The grid staggering, see ants.fileformats.ancil.template.GRIDS.

Returns:

tuple – Shape, representing the number of latitudes by the number of longitudes.
>>> ngrid(96, grid_staggering=6)
(144, 192)
>>> ngrid(96, grid_staggering=3)
(145, 192)
>>> ngrid(96, grid_staggering=’endgame’)
(144, 192)
>>> ngrid(216, grid_staggering=6)
(324, 432)
>>> ngrid(512, grid_staggering=6)
(768, 1024)
>>> ngrid(2048, grid_staggering=6)
(3072, 4096)