ugants.regrid package#

Submodules#

ugants.regrid.applications module#

Implementation for the mesh to grid regrid application.

class ugants.regrid.applications.MeshToGridRegrid(source: CubeList, target_grid: CubeList, horizontal_regrid_scheme: Literal['conservative', 'bilinear', 'nearest'], input_weights: str = '', output_weights: str = '')[source]#

Bases: Application

Regrid unstructured grid data to regular lat lon.

Parameters:

source – The ugrid source data.
target_grid – The regular gridded target grid.
horizontal_regrid_scheme – The horizontal regrid scheme to be used. Supported schemes are “conservative”, “bilinear”, “nearest”.
input_weights – Path to cached input weights. An optional file containing the pre-generated weights for the mesh being used for regridding.
output_weights – An optional target path for output cached weights. Using pre-cached weights makes the regridding process less computationally expensive.

run()[source]#: Regrid self.source to self.target_grid.

save()[source]#: Save self.results to self.output.

class ugants.regrid.applications.SplitMeshToGridByLatitude(source: CubeList, target: CubeList, number_of_bands: int)[source]#

Bases: Application

Split the provided UGrid source and regular grid target into latitude bands.

Parameters:

source (CubeList) – The global UGrid source data to be split.
target (Mesh) – The regular grid target to be split.
number_of_bands (int) – Number of latitude bands to split by.

source_bands: CubeList#: The domain of each cube completely covers the corresponding band in target_bands. An attribute band_number is added to distinguish each cube.

target_bands: list[Mesh]#: Each target band covers a latitude band, approximately evenly spaced. There are no overlapping cells between any two bands, so each band covers a unique region. Together, the bands cover the entire target domain.

output: str = None#: The output directory to which to write the source_bands and target_bands.

run()[source]#

Split the target and source cubes into bands.

The target is first split into bands by latitude, with the resulting bands stored in target_bands. These bands are then used to calculate the source bands, where each source band fully contains the corresponding target band. The source bands are stored in source_bands.

save()[source]#

Save source and target bands.

Saves all the source and target bands to individual netCDF files. Source bands are saved to the output directory, with a name of source_band_N.nc for the Nth source band. The corresponding Nth target band is saved in the same directory with the name target_band_N.nc.

class ugants.regrid.applications.RecombineGridBands(slices: CubeList)[source]#

Bases: Application

Combines individual split results into a single result.

Parameters:: slices (iris.cube.CubeList) – Paths to files containing individual results.

run()[source]#

Recombine individual split results into a complete result.

Sets the results to the complete result. If the individual split results have different data types, this promotes the data type of the result to the highest precision data type in the split results. The history attribute of the combined result is set to be the history of the first individual band.

save()[source]#

Save recombined grid bands to sinlge output file.

Specifically, saves recombined results to output.

ugants.regrid.band_utils module#

Utility functions for band regridding.

ugants.regrid.band_utils.mesh_to_cube(mesh, dtype: ~numpy.dtype = <class 'numpy.float64'>)[source]#

Turn a mesh into a iris.cube.Cube with data using np.nan.

Parameters:

mesh (iris.experimental.ugrid.mesh.Mesh) – The mesh to be converted to an iris.cube.Cube
dtype (numpy.dtype) – The data type used for the cube.data numpy.ndarray, by default np.float64.

Returns:

The providied mesh as an iris.cube.Cube.

Return type:

iris.cube.Cube

ugants.regrid.band_utils.generate_band_bounds(start: float, stop: float, n_bands: int)[source]#

Generate a list of tuples representing bands of latitude or longitude.

Divides an arbitrary interval, defined by start and stop, into equally spaced subdivisions.

Example

>>> generate_band_bounds(0.0, 15.0, 3)
[(0.0, 5.0), (5.0, 10.0), (10.0, 15.0)]

Parameters:

start (float) – The start latitude/longitude limit.
stop (float) – The end latitude/longitude limit.
n_bands (int) – Number of bands to generate.

Returns:

A list of tuples, with each tuple defining a band.

Return type:

list[tuple[float, float]]

Raises:

ValueError – When n_bands is less than 2.

ugants.regrid.band_utils.find_cell_centres_within_latitude_bounds(cube, bounds: tuple, min_inclusive: bool = True, max_inclusive: bool = True)[source]#

Return a boolean mask of cells where the centres are within latitude bounds.

Parameters:

cube (iris.cube.Cube) – An iris.cube.Cube with a mesh.
bounds (tuple[float, float]) – The latitude bounds to check.
min_inclusive (bool) – Include cell centres equal to the minimum latitude, by default True
max_inclusive (bool) – Include cell centres equal to the maximum latitude, by default True

Returns:

An array of bools representing the face indices to subset.

Return type:

numpy.ndarray

ugants.regrid.band_utils.subset_mesh_cube_by_indices(cube: Cube, indices)[source]#

Create a subset of a cube with a mesh by indexing its mesh dimension.

Parameters:

cube (iris.cube.Cube) – A cube containing the mesh to be subset.
indices (numpy.ndarray) – A boolean or integer array representing the indices of the mesh dimension to be sliced.

Returns:

The subsetted cube.

Return type:

iris.cube.Cube

Note

Mesh cube subsetting is currently only available for data located on faces.

ugants.regrid.band_utils.reconstruct_mesh_cube(cube: Cube, mesh_dim: int)[source]#

Reconstruct a cube with a mesh that has been broken into AuxCoords.

When a cube is subset along a mesh dimension, the MeshCoords will be converted to AuxCoords, so the cube will no longer have a mesh. This function reconstructs the mesh from the AuxCoords, and adds corresponding MeshCoords to the cube.

Parameters:

cube (iris.cube.Cube) – The cube with a broken mesh to be reconstructed.
mesh_dim (int) – The dimension of the cube which the mesh describes.

Returns:

A copy of the original cube with a reconstructed mesh.

Return type:

iris.cube.Cube

Notes

Note

The reconstructed cube’s mesh location is set to “face”. Other mesh locations (edge, node) are not supported.

Note

The reconstructed mesh’s face_node_connectivity will be 0 indexed.

Note

Face order is preserved, but node order is not preserved under reconstruction.

ugants.regrid.band_utils.cube_subset_latitude_bounds(mesh, coord, fraction=0.05)[source]#

Calculate latitude bounds that subset the cube so that it encloses the mesh.

Parameters:

mesh (iris.experimental.ugrid.Mesh) – The target mesh.
coord (iris.coords.Coord) – The latitude coord.

Returns:

Latitude bounds required to subset a cube.

Return type:

tuple

ugants.regrid.band_utils.constrain_source_cube_latitude(cube, bounds, padding=0.0)[source]#

Constrain a cube based on latitude bounds and optional padding.

Parameters:

cube (iris.cube.Cube) – Source cube to constrain.
bounds (tuple[float, float]) – Lower and upper latitude limit.
padding (float) – Optional padding to be applied to both limits.

Return type:

iris.cube.Cube

ugants.regrid.band_utils.split_cube(cube, n_slices, axis='Y')[source]#

Split a cube along the given dimension into approximately equal sub-cubes.

The generated sub-cubes will be non-overlapping.

Parameters:

cube (iris.cube.Cube) – The cube to split.
n_slices (int) – Total number of sub-cubes to return.
axis (str) – Axis to split over. Valid values are “Y” (default) to split on latitude, or “X” to split on longitude. This is case insensitive.

Returns:

The sub cubes as a cube list.

Return type:

iris.cube.CubeList

Raises:

ValueError – If the axis not one of “X” or “Y”.

ugants.regrid.band_utils.get_faces_that_overlap_bounds(cube, bounds, index=1)[source]#

Get the indices of faces with one or more nodes within given latitude bounds.

Parameters:

cube (iris.cube.Cube) – A cube with associated mesh.
bounds (tuple[float, float]) – The latitude bounds to check for overlapping faces.

Return type:

numpy.ndarray

ugants.regrid.band_utils.cube_latitude_bounds(cube)[source]#

Get the max and min of the latitude bounds from a cube.

A copy of the “latitude” coordinate is taken in order to avoid mutating the provided cube if guessing bounds.

Parameters:: cube (iris.cube.Cube) – The cube to find latitude limits of.
Returns:: The minimum and maximum latitude of the cube.
Return type:: tuple[float, float]

ugants.regrid.command_line module#

Implementation for the regrid application.

class ugants.regrid.command_line.Regrid(source: CubeList, target_mesh: Mesh, horizontal_regrid_scheme: Literal['conservative', 'bilinear', 'nearest'], tolerance: float = 0, input_weights: str = '', output_weights: str = '')[source]#

Bases: Application

Regrid regular grid data to an unstructured mesh.

Parameters:

source (iris.cube.CubeList) – The regular gridded source data to be regridded.
target_mesh (iris.experimental.ugrid.Mesh) – The UGrid target mesh.
horizontal_regrid_scheme (str) – The horizontal regrid scheme to be used. Supported schemes are “conservative”, “bilinear”, “nearest”.
tolerance (float) – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of masked data exceeds this tolerance. If not provided, the default tolerance value is zero. This option is not available for the “nearest” scheme.
input_weights – Path to cached input weights. An optional file containing the pre-generated weights for the mesh being used for regridding.
output_weights – An optional target path for output cached weights. Using pre-cached weights makes the regridding process less computationally expensive.

Raises:

ValueError – If a tolerance is provided and the horizontal_regrid_scheme is “nearest”.

Note

The data is always regridded to the faces of the unstructured grid.

results: CubeList = None#: The source data regridded onto the faces of the target mesh.

source: CubeList = None#: The source data to be regridded.

target_mesh: Mesh = None#: The mesh to regrid to.

run()[source]#

Regrid source to target_mesh.

The result of the regrid is stored in results.

save()[source]#: Save self.results to self.output.

class ugants.regrid.command_line.RegridMeshToMesh(source: CubeList, target_mesh: Mesh, horizontal_regrid_scheme: Literal['conservative', 'bilinear', 'nearest'], tolerance: float = 0)[source]#

Bases: Application

Regrid unstructured mesh data to an unstructured mesh of a different resolution.

Parameters:

source – The unstructured mesh data to be regridded.
target_mesh – The UGrid target resolution mesh.
horizontal_regrid_scheme – The horizontal regrid scheme to be used. Supported schemes are “conservative”, “bilinear”, “nearest”.
tolerance – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of masked data exceeds this tolerance. If not provided, the default tolerance value is zero. This option is not available for the “nearest” scheme.

Raises:

ValueError – If a tolerance is provided and the horizontal_regrid_scheme is “nearest”.

Note

The data is always regridded to the faces of the unstructured mesh.

results: CubeList = None#: The source data regridded onto the faces of the target mesh.

run()[source]#: Regrid self.source to self.target_mesh.

class ugants.regrid.command_line.SplitGridToMeshByLatitude(source: CubeList, target_mesh: Mesh, number_of_bands: int)[source]#

Bases: Application

Split the provided regular gridded source and target mesh into latitude bands.

Parameters:

source (CubeList) – The global, regular gridded source data to be split.
target_mesh (Mesh) – The target mesh to be split.
number_of_bands (int) – Number of latitude bands to split by.

results: list[CubeList] = None#: A list of CubeLists, one for each latitude band. Each CubeList contains the same number of cubes as the source CubeList. The domain of each cube completely covers the corresponding mesh band in mesh_bands. Padding is added ensure that the mesh band is fully enclosed, so there will be overlap between adjacent source bands. See cube_subset_latitude_bounds() for more details on how the padding is calculated. An attribute band_number is added to distinguish each cube.

mesh_bands: list[Mesh]#: Each mesh covers a latitude band, approximately evenly spaced. There are no overlapping cells between any two mesh bands, so each mesh band covers a unique region. Together, the mesh bands cover the entire target mesh.

mesh_mapping_cube: Cube#: A UGrid cube constructed from the target_mesh. The data maps each cell to its corresponding latitude band. For example, if a cell has a value of 1, then it belongs in latitude band 1.

output: str = None#: The output directory to which to write the results, mesh_bands and mesh_mapping_cube.

run()[source]#

Run the application.

The source and target are split into bands of approximately equal latitude.

There is no overlap between target bands, i.e. a cell in the original target mesh will appear in one target band only. The mapping between target mesh cells and band number is recorded in the mesh_mapping_cube.

There is overlap between source bands, i.e. a cell in the original source may appear in more than one source band. This is because the source domain must extend beyond the target domain in order to capture all the required data for regridding.

The following attributes are set by this method:

results
mesh_bands
mesh_mapping_cube

save()[source]#

Save the latitude bands to NetCDF.

Three types of file are saved to the directory specified by self.output:

results: number_of_bands such files are output, named source_band_{band_number}.nc.
mesh_bands: number_of_bands such files are output, named mesh_band_{band_number}.nc.
mesh_mapping_cube: only one such file is output, named mesh_band_mapping.nc.

In total, 2*number_of_bands + 1 files are output.

class ugants.regrid.command_line.RecombineMeshBands(mesh_mapping: CubeList, bands: CubeList)[source]#

Bases: Application

Recombine regridded latitude bands into a single cube.

Parameters:

mesh_mapping (iris.cube.CubeList) – A single-element CubList which maps individual latitude bands to cells in the target mesh. See also SplitGridToMeshByLatitude.mesh_mapping_cube.
bands (iris.cube.CubeList) – The regridded latitude bands to recombine into a single UGrid cube. Each band cube must have a band_number attribute, which maps the band to its location on the mesh_mapping.

results: CubeList = None#: The recombined bands in a single cube. The cube’s mesh is identical to that of the mesh mapping, and the data is taken from the cubes in bands.

run()[source]#

Recombine the latitude bands into a single cube.

The data from each latitude band cube in the bands CubeList are used to fill the corresponding cells in the target mesh, according to the band cube’s band_number attribute.

The mesh_mapping_cube provides the target mesh to be filled with data from the regridded latitude bands. The data in mesh_mapping_cube describe which latitude band is to be used to fill the cells.

For example, cells with value 2 in the mesh_mapping_cube are filled with data from band number 2.

This method sets the results attribute.