Regrid

class ESMF.api.regrid.Regrid(srcfield=None, dstfield=None, filename=None, rh_filename=None, src_mask_values=None, dst_mask_values=None, regrid_method=None, pole_method=None, regrid_pole_npoints=None, line_type=None, norm_type=None, extrap_method=None, extrap_num_src_pnts=None, extrap_dist_exponent=None, extrap_num_levels=None, unmapped_action=None, ignore_degenerate=None, create_rh=None, filemode=None, src_file=None, dst_file=None, src_file_type=None, dst_file_type=None, factors=False, large_file=None, src_frac_field=None, dst_frac_field=None)

The Regrid object represents a regridding operator between two Fields. The creation of this object is analogous to ESMF_FieldRegridStore(), and calling this object corresponds to ESMF_FieldRegrid(). ESMF_FieldRegridRelease() is called when the Regrid object goes out of scope (this only happens when the Manager goes out of scope, there is a destroy() call for explicit deallocation of the Regrid).

Refer to the ESMF_FieldRegrid methods in the ESMF Reference Manual for more information.

The following arguments are used to create a handle to a Regridding operation between two Fields.

REQUIRED:

Parameters

OPTIONAL:

Parameters

  • filename (string) – path to the output netCDF weight file.

  • rh_filename (string) – path to the output RouteHandle file.

  • src_mask_values (ndarray) – a numpy array of values that should be considered masked value on the source Field.

  • dst_mask_values (ndarray) – a numpy array of values that should be considered masked value on the destination Field.

  • regrid_method (RegridMethod) – specifies which RegridMethod to use. If None, defaults to BILINEAR.

  • pole_method (PoleMethod) – specifies which type of artificial pole to construct on the source Grid for regridding. If None, defaults to: NONE for regridmethod == CONSERVE, or ALLAVG for regridmethod != CONSERVE.

  • regrid_pole_npoints (int) – specifies how many points to average over if polemethod == ALLAVG.

  • line_type (LineType) – select the path of the line that connects two points on the surface of a sphere. This in turn controls the path along which distances are calculated and the shape of the edges that make up a cell. If None, defaults to: GREAT_CIRCLE for regridmethod == CONSERVE, or CART for regridmethod != CONSERVE.

  • norm_type (NormType) – control which type of normalization to do when generating conservative regridding weights. If None, defaults to DSTAREA.

  • extrap_method (ExtrapMethod) – Specify which extrapolation method to use on unmapped destination points after regridding.

  • extrap_num_src_pnts (int) – The number of source points to use for the extrapolation methods that use more than one source point (e.g. NEAREST_IDAVG). If not specified, defaults to 8.

  • extrap_dist_exponent (float) – The exponent to raise the distance to when calculating weights for the NEAREST_IDAVG extrapolation method. A higher value reduces the influence of more distant points. If not specified, defaults to 2.0.

  • extrap_num_levels (int) – The number of levels to output for the extrapolation methods that fill levels (e.g. CREEP). When a method is used that requires this, then an error will be returned if it is not specified.

  • unmapped_action (UnmappedAction) – specifies which action to take if a destination point is found which does not map to any source point. If None, defaults to ERROR.

  • ignore_degenerate (bool) – Ignore degenerate cells when checking the input Grids or Meshes for errors. If this is set to True, then the regridding proceeds, but degenerate cells will be skipped. If set to False, a degenerate cell produces an error. This currently only applies to CONSERVE, other regrid methods currently always skip degenerate cells. If None, defaults to False.

  • src_frac_field (ndarray) – return a numpy array of values containing weights corresponding to the amount of each Field value which contributes to the total mass of the Field.

  • dst_frac_field (ndarray) – return a numpy array of values containing weights corresponding to the amount of each Field value which contributes to the total mass of the Field.

  • factors (bool) –

    If True, return the factor and factor index list when calling into ESMF’s regrid store method. These lists are converted to NumPy arrays and attached to the regrid object. The factor arrays are retrievable via get_factors() or get_weights_dict(). See the respective documentation on those methods for additional information. For more information on how ESMF treats factor retrieval see the ESMF_FieldRegridStore interface in the ESMF Reference Manual.

  • large_file (bool) – If True, create the weight file in NetCDF using the 64-bit offset format to allow variables larger than 2GB. Note the 64-bit offset format is not supported in the NetCDF version earlier than 3.6.0. An error message will be generated if this flag is specified while the application is linked with a NetCDF library earlier than 3.6.0. Defaults to False.

__call__(srcfield, dstfield, zero_region=None)

Call a regridding operation from srcfield to dstfield.

REQUIRED:

Parameters

  • srcfield (Field) – the Field of source data to regrid.

  • dstfield (Field) – the Field to hold the regridded data.

OPTIONAL:

Parameters

zero_region (Region) – specify which region of the field indices will be zeroed out before adding the values resulting from the interpolation. If None, defaults to TOTAL.

Returns

dstfield

copy()

Copy a Regrid in an ESMF-safe manner.

Returns

A Regrid shallow copy.

destroy()

Release the memory associated with a Regrid.

get_factors(deep_copy=False)

Return factor and factor index arrays. These arrays will only be available if the Regrid object was initialized with factors=True. See the ESMF_FieldRegridStore interface in the ESMF Reference Manual for additional information on these arrays (see below for indexing in Python though).

>>> factors, factors_index = get_factors(...)

The first tuple element factors will have shape (m,) where m is the number of factors or weights. It will be dtype(float64). The second tupe element factors_index will have shape (m, 2) where m is the number of factors or weights. The source/col indices are selected by factors_index[:, 0]. The destination/row indices are selected by factors_index[:, 1]. It will be dtype(int32).

Note

If deep_copy=True, array memory is C contiguous according to NumPy array flags (<array>.flags).

Warning

Remember to call destroy() to deallocate memory associated with a regrid operation. This will be called by the Python garbage collector. However, if numerous regridding operations are called in a tight loop, a memory leak will occur without a call to destroy.

Parameters

deep_copy (bool) – If True, make deep copies of the returned arrays. If False (the default), the returned arrays will reference the underlying ESMF memory.

Returns

tuple of NumPy array objects

get_weights_dict(deep_copy=False)

Return a dictionary mapping that is more user-friendly for weight/factor retrieval. Please read the documentation for get_factors() before using this function.

Key

Value

weights

Weight value array

row_dst

Destination/row indices

col_src

Source/col indices

Note

If deep_copy=True, array memory is C contiguous according to NumPy array flags (<array>.flags).

Parameters

deep_copy (bool) – If True, make deep copies of the returned arrays. If False (the default), the returned arrays will reference the underlying ESMF memory.

Returns

dict