Regrid¶

class
ESMF.api.regrid.
Regrid
(srcfield=None, dstfield=None, 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, unmapped_action=None, ignore_degenerate=None, create_rh=None, src_frac_field=None, dst_frac_field=None, factors=False)¶ The
Regrid
object represents a regridding operator between twoFields
. The creation of this object is analogous to ESMF_FieldRegridStore(), and calling this object corresponds to ESMF_FieldRegrid(). ESMF_FieldRegridRelease() is called when theRegrid
object goes out of scope (this only happens when theManager
goes out of scope, there is a destroy() call for explicit deallocation of theRegrid
).For more information about the ESMF Regridding functionality, please see the ESMF Regrid documentation.
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
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. IfNone
, defaults toBILINEAR
.pole_method (PoleMethod) – specifies which type of artificial pole to construct on the source
Grid
for regridding. IfNone
, defaults to:NONE
for regridmethod ==CONSERVE
, orALLAVG
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
, orCART
for regridmethod !=CONSERVE
.norm_type (NormType) – control which type of normalization to do when generating conservative regridding weights. If
None
, defaults toDSTAREA
.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 to2.0
.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 toERROR
.ignore_degenerate (bool) – Ignore degenerate cells when checking the input
Grids
orMeshes
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 toCONSERVE
, other regrid methods currently always skip degenerate cells. IfNone
, defaults toFalse
.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 theField
.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 theField
.factors (bool) – If
True
, return the factor and factor index list when calling intoESMF
’s regrid store method. These lists are converted to NumPy arrays and attached to the regrid object. The factor arrays are retrievable viaget_factors()
orget_weights_dict()
. See the respective documentation on those methods for additional information. For more information on howESMF
treats factor retrieval see the documentation for ESMF_FieldRegridStore.

__call__
(srcfield, dstfield, zero_region=None)¶ Call a regridding operation from srcfield to dstfield.
REQUIRED:
 Parameters
OPTIONAL:

get_factors
(deep_copy=False)¶ Return factor and factor index arrays. These arrays will only be available if the
Regrid
object was initialized withfactors=True
. See the ESMF documentation 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,)
wherem
is the number of factors or weights. It will bedtype(float64)
. The second tupe elementfactors_index
will have shape(m, 2)
wherem
is the number of factors or weights. The source/col indices are selected byfactors_index[:, 0]
. The destination/row indices are selected byfactors_index[:, 1]
. It will bedtype(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 todestroy
. Parameters
deep_copy (bool) – If
True
, make deep copies of the returned arrays. IfFalse
(the default), the returned arrays will reference the underlyingESMF
memory. Returns
tuple of NumPy array objects

get_weights_dict
(deep_copy=False)¶ Return a dictionary mapping that is more userfriendly 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. IfFalse
(the default), the returned arrays will reference the underlyingESMF
memory. Returns
dict