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 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
).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. 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
.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 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 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 toFalse
.
- __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_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,)
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 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. IfFalse
(the default), the returned arrays will reference the underlyingESMF
memory.- Returns:
dict