esmf_regrid.experimental.unstructured_scheme module#

Provides an iris interface for unstructured regridding.

class esmf_regrid.experimental.unstructured_scheme.GridToMeshESMFRegridder(src, tgt, mdtol=None, method=Method.CONSERVATIVE, precomputed_weights=None, src_resolution=None, use_src_mask=False, use_tgt_mask=False, tgt_location=None, esmf_args=None)[source]#

Bases: _ESMFRegridder

Regridder class for rectilinear to unstructured Cube\ s.

Create regridder for conversions between source grid and target mesh.

Parameters:

  • src (iris.cube.Cube) – The rectilinear Cube cube providing the source grid.

  • tgt (iris.cube.Cube or iris.mesh.MeshXY) – The unstructured MeshXY providing the target mesh.

  • mdtol (float, optional) – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of masked data exceeds mdtol. mdtol=0 means no missing data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the contributing elements of data are masked. Defaults to 1 for conservative regregridding and 0 for bilinear regridding.

  • method (Constants.Method, default=Constants.Method.CONSERVATIVE) – The method used to calculate weights.

  • precomputed_weights (scipy.sparse.spmatrix, optional) – If None, esmpy will be used to calculate regridding weights. Otherwise, esmpy will be bypassed and precomputed_weights will be used as the regridding weights.

  • src_resolution (int, optional) – If present, represents the amount of latitude slices per cell given to ESMF for calculation. If src_resolution is set, src must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).

  • use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src. If False, no mask will be taken and all points will be used in weights calculation.

  • use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in tgt. If False, no mask will be taken and all points will be used in weights calculation.

  • tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.

  • esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF.

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src or tgt respectively are not constant over non-horizontal dimensions.

class esmf_regrid.experimental.unstructured_scheme.MeshToGridESMFRegridder(src, tgt, mdtol=None, method=Method.CONSERVATIVE, precomputed_weights=None, tgt_resolution=None, use_src_mask=False, use_tgt_mask=False, esmf_args=None)[source]#

Bases: _ESMFRegridder

Regridder class for unstructured to rectilinear Cube\ s.

Create regridder for conversions between source mesh and target grid.

Parameters:

  • src_mesh_cube (iris.cube.Cube) – The unstructured Cube providing the source mesh.

  • target_grid_cube (iris.cube.Cube) – The Cube providing the target grid.

  • mdtol (float, optional) – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of masked data exceeds mdtol. mdtol=0 means no missing data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the contributing elements of data are masked. Defaults to 1 for conservative regregridding and 0 for bilinear regridding.

  • method (Constants.Method, default=Constants.Method.CONSERVATIVE) – The method used to calculate weights.

  • precomputed_weights (scipy.sparse.spmatrix, optional) – If None, esmpy will be used to calculate regridding weights. Otherwise, esmpy will be bypassed and precomputed_weights will be used as the regridding weights.

  • tgt_resolution (int, optional) – If present, represents the amount of latitude slices per cell given to ESMF for calculation. If tgt_resolution is set, tgt must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).

  • use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src. If False, no mask will be taken and all points will be used in weights calculation.

  • use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in tgt. If False, no mask will be taken and all points will be used in weights calculation.

  • esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF.

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src or tgt respectively are not constant over non-horizontal dimensions.

esmf_regrid.experimental.unstructured_scheme.regrid_rectilinear_to_unstructured(src_cube, mesh_cube, mdtol=0, method=Method.CONSERVATIVE, src_resolution=None, use_src_mask=False, use_tgt_mask=False)[source]#

Regrid rectilinear Cube onto unstructured mesh.

Return a new Cube with data values calculated using weights generated by esmpy to give the weighted mean of data values from src_cube regridded onto the horizontal mesh of mesh_cube. The dimensions on the Cube associated with the grid will be replaced by a dimension associated with the mesh. That dimension will be the first of the grid dimensions, whether it is associated with the x or y coordinate. Since two dimensions are being replaced by one, coordinates associated with dimensions after the grid will become associated with dimensions one lower. This function requires that the horizontal dimension of mesh_cube is described by a 2D mesh with data located on the faces of that mesh for conservative regridding and located on either faces or nodes for bilinear regridding. This function allows the horizontal grid of grid_cube to be either rectilinear or curvilinear (i.e. expressed in terms of two orthogonal 1D coordinates or via a pair of 2D coordinates). This function also requires that the Coord\ s describing the horizontal grid have bounds.

Parameters:

  • src_cube (iris.cube.Cube) – A rectilinear instance of Cube that supplies the data, metadata and coordinates.

  • mesh_cube (iris.cube.Cube) – An unstructured instance of Cube that supplies the desired horizontal mesh definition.

  • mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned Cube\ ‘s data array will be masked if the fraction of masked data in the overlapping cells of the source cube exceeds mdtol. This fraction is calculated based on the area of masked cells within each target cell. mdtol=0 means no missing data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the overlapping cells of the src_cube are masked.

  • method (Constants.Method, default=Constants.Method.CONSERVATIVE) – The method used to calculate weights.

  • src_resolution (int, optional) – If present, represents the amount of latitude slices per cell given to ESMF for calculation.

  • use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src_cube. If False, no mask will be taken and all points will be used in weights calculation.

  • use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in grid_cube. If False, no mask will be taken and all points will be used in weights calculation.

Returns:

A new Cube instance.

Return type:

iris.cube.Cube

esmf_regrid.experimental.unstructured_scheme.regrid_unstructured_to_rectilinear(src_cube, grid_cube, mdtol=0, method=Method.CONSERVATIVE, tgt_resolution=None, use_src_mask=False, use_tgt_mask=False)[source]#

Regrid unstructured Cube onto rectilinear grid.

Return a new Cube with data values calculated using weights generated by esmpy to give the weighted mean of data values from src_cube regridded onto the horizontal grid of grid_cube. The dimension on the Cube belonging to the mesh will be replaced by the two dimensions associated with the grid. This function requires that the horizontal dimension of src_cube is described by a 2D mesh with data located on the faces of that mesh for conservative regridding and located on either faces or nodes for bilinear regridding. This function allows the horizontal grid of grid_cube to be either rectilinear or curvilinear (i.e. expressed in terms of two orthogonal 1D coordinates or via a pair of 2D coordinates). This function also requires that the Coord\ s describing the horizontal grid have bounds.

Parameters:

  • src_cube (iris.cube.Cube) – An unstructured instance of Cube that supplies the data, metadata and coordinates.

  • grid_cube (iris.cube.Cube) – An instance of Cube that supplies the desired horizontal grid definition.

  • mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned Cube\ ‘s data array will be masked if the fraction of masked data in the overlapping cells of src_cube exceeds mdtol. This fraction is calculated based on the area of masked cells within each target cell. mdtol=0 means no missing data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the overlapping cells of src_cube are masked.

  • method (Constants.Method, default=Constants.Method.CONSERVATIVE) – The method used to calculate weights.

  • tgt_resolution (int, optional) – If present, represents the amount of latitude slices per cell given to ESMF for calculation.

  • use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src_cube. If False, no mask will be taken and all points will be used in weights calculation.

  • use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in grid_cube. If False, no mask will be taken and all points will be used in weights calculation.

Returns:

A new Cube instance.

Return type:

iris.cube.Cube

esmf_regrid.experimental.unstructured_scheme.regrid_unstructured_to_unstructured(src_mesh_cube, tgt_mesh_cube, mdtol=0, method=Method.CONSERVATIVE, use_src_mask=False, use_tgt_mask=False)[source]#

Regrid rectilinear Cube onto unstructured mesh.

Return a new Cube with data values calculated using weights generated by esmpy to give the weighted mean of data values from src_mesh_cube regridded onto the horizontal mesh of tgt_mesh_cube. The resulting cube will have the same mesh_dim as src_mesh_cube.

Parameters:

  • src_mesh_cube (iris.cube.Cube) – A unstructured instance of Cube that supplies the data, metadata and coordinates.

  • tgt_mesh_cube (iris.cube.Cube) – An unstructured instance of Cube that supplies the desired horizontal mesh definition.

  • mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned Cube\ ‘s data array will be masked if the fraction of masked data in the overlapping cells of the source cube exceeds mdtol. This fraction is calculated based on the area of masked cells within each target cell. mdtol=0 means no missing data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the overlapping cells of the src_cube are masked.

  • method (Constants.Method, default=Constants.Method.CONSERVATIVE) – The method used to calculate weights.

  • use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src_cube. If False, no mask will be taken and all points will be used in weights calculation.

  • use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in grid_cube. If False, no mask will be taken and all points will be used in weights calculation.

Returns:

A new Cube instance.

Return type:

iris.cube.Cube