Domains domain

Domains `domain`#

Domain plugins for pyCIF.

A domain plugin loads and stores all geographical information about a model or data-stream grid — both horizontal and vertical. Every other plugin that handles spatially gridded data (models, transforms, fluxes, …) references a domain to know the grid layout.

Required attributes and functions#

The following attributes and functions must be defined for any domain plugin.

Initialisation attributes#

Set in read_grid or create_domain:

unstructured_domain (optional): Set to True when the grid cannot be represented as a regular 2-D array; cells are stored as a flat list instead.

Warning

For unstructured domains, always set nlon = number of cells and nlat = 1.
regular_degrees (optional): Used together with unstructured_domain; set to True when cells are regular rectangles in degrees (speeds up area computation).
nlon / nlat / nlev: Grid dimensions (zonal, meridional, vertical).
zlon / zlat: Cell-centre coordinate arrays; shape (nlat, nlon) for structured grids or (1, ncells) for unstructured grids.
zlonc / zlatc: Cell-corner coordinate arrays; shape (nlat+1, nlon+1) for structured grids or (nvertices, ncells) for unstructured grids.
sigma_a / sigma_b: Alpha / beta coefficients of sigma pressure levels (p = sigma_a + sigma_b * psurf).
pressure_unit (optional): Pressure unit for sigma levels: 'Pa' or 'hPa' (default 'Pa').
heights (optional): Heights above ground level (m) for each vertical level.

Warning

When both sigma levels and heights are provided, only sigma levels are used.
lon_cyclic (optional): True for globally cyclic (periodic) zonal grids.
projection (optional): Set to 'xy' when coordinates are in metres from a reference point rather than GPS degrees.

The horizontal grid definition drives horizontal regridding and the vertical grid definition drives vertical interpolation.

Online attributes#

Computed on demand during the run:

zlon_side / zlat_side: Longitudes / latitudes of the domain lateral boundary (or buffer region).
zlonc_side / zlatc_side: Corner equivalents of the side coordinates.
nlon_side / nlat_side: Number of cells along the sides; nlat_side > 1 for buffer regions.
areas: Grid-cell areas (m²).

Required functions#

read_grid(self, **kwargs)

Called first during domain initialisation. Should populate all attributes listed above from pre-existing coordinate files. If it raises IOError or AttributeError, create_domain is called automatically as a fallback.

def read_grid(self, **kwargs):
    self.zlon = ...
    self.zlat = ...
    self.zlonc = ...
    self.zlatc = ...
    self.nlon = ...
    self.nlat = ...
    self.nlev = ...
    self.sigma_a = ...
    self.sigma_b = ...

See pycif.plugins.domains.chimere.read_grid() for a full example.

create_domain(self, **kwargs)

Fallback called when read_grid fails. Generates the grid from YAML configuration parameters instead of reading from files.

See pycif.plugins.domains.chimere.create_domain() for a full example.

get_sides(self) (optional)

Defines zlon_side, zlat_side, zlonc_side, zlatc_side, nlon_side, nlat_side. When not provided, the default implementation (outer border of the domain) from pycif.utils.classes.domains.Domain.get_sides() is used.

class pycif.utils.classes.domains.Domain(**kwargs)[source]#

Bases: Plugin

Plugin type for spatial model domains.

Stores horizontal (lon/lat grid centres and corners) and vertical (hybrid sigma-pressure or height-above-ground) grid definitions, and provides utilities for computing cell areas and boundary coordinates.

Concrete implementations live in pycif/plugins/domains/.

get_sides()[source]#

Compute and store the boundary (side) coordinates of the domain.

Concatenates the West, East, South and North edge lon/lat corner coordinates into zlonc_side / zlatc_side, and the corresponding midpoint coordinates into zlon_side / zlat_side. Sets nlon_side and nlat_side.

Available Domains `domain`#

The following domains are implemented in pyCIF so far: