Subsections
54 Appendix A: Master List of Constants
This flag is documented in section 46.2.1.
54.2 ESMF_DIM_ARB
DESCRIPTION:
An integer named constant which is used to indicate that a particular dimension is arbitrarily distributed.
This flag is documented in section 57.1.1.
This flag is documented in section 57.1.2.
54.5 ESMF_ATTNEST
DESCRIPTION:
Indicate whether or not to descend the Attribute hierarchy.
The type of this flag is:
type(ESMF_AttNest_Flag)
The valid values are:
- ESMF_ATTNEST_ON
- Indicates that the Attribute hierarchy should be traversed.
- ESMF_ATTNEST_OFF
- Indicates that the Attribute hierarchy should not be traversed.
54.6 ESMF_ATTRECONCILE
DESCRIPTION:
Indicate whether or not to handle metadata (Attributes) in ESMF_StateReconcile().
The type of this flag is:
type(ESMF_AttReconcileFlag)
The valid values are:
- ESMF_ATTRECONCILE_ON
- Attribute reconciliation will be turned on.
- ESMF_ATTRECONCILE_OFF
- Attribute reconciliation will be turned off.
This flag is documented in section 57.1.3.
This flag is documented in section 42.2.1.
54.9 ESMF_COMPTYPE
DESCRIPTION:
Indicate the type of a Component.
The type of this flag is:
type(ESMF_CompType_Flag)
The valid values are:
- ESMF_COMPTYPE_GRID
- A ESMF_GridComp object.
- ESMF_COMPTYPE_CPL
- A ESMF_CplComp objects.
- ESMF_COMPTYPE_SCI
- A ESMF_SciComp objects.
54.10 ESMF_CONTEXT
DESCRIPTION:
Indicates the type of VM context in which a Component will be executing its
standard methods.
The type of this flag is:
type(ESMF_Context_Flag)
The valid values are:
- ESMF_CONTEXT_OWN_VM
- The component is running in its own, separate VM context. Resources
are inherited from the parent but can be arranged to fit the
component's requirements.
- ESMF_CONTEXT_PARENT_VM
- The component uses the parent's VM for resource management. Compared
to components that use their own VM context components that run in the
parent's VM context are more light-weight with respect to the overhead
of calling into their initialize, run and finalize methods.
Furthermore, VM-specific properties remain unchanged when going from
the parent component to the child component. These properties include
the MPI communicator, the number of PETs, the PET labeling,
communication attributes, threading-level.
54.11 ESMF_COORDSYS
DESCRIPTION:
A set of values which indicates in which system the coordinates in a class (e.g. Grid) are. This type is useful both
to indicate to other users the type of the coordinates, but also to control how the coordinates are interpreted in ESMF
methods which depend on the coordinates (e.g. regridding methods like ESMF_FieldRegridStore()).
The type of this flag is:
type(ESMF_CoordSys_Flag)
The valid values are:
- ESMF_COORDSYS_CART
- Cartesian coordinate system. In this system, the Cartesian coordinates are mapped to the coordinate dimensions in the following order: x,y,z. (E.g. using coordDim=2 in ESMF_GridGetCoord() references the y dimension)
- ESMF_COORDSYS_SPH_DEG
- Spherical coordinates in degrees. In this system, the spherical coordinates are mapped to the coordinate dimensions in the following order: longitude, latitude, radius. (E.g. using coordDim=2 in ESMF_GridGetCoord() references the latitude dimension.)
- ESMF_COORDSYS_SPH_RAD
- Spherical coordinates in radians. In this system, the spherical coordinates are mapped to the coordinate dimensions in the following order: longitude, latitude, radius. (E.g. using coordDim=2 in ESMF_GridGetCoord() references the latitude dimension.)
54.12 ESMF_CUBEDSPHERECALC
DESCRIPTION:
Indicates the method used to calculate coordinates during cubed sphere creation.
The type of this flag is:
type(ESMF_CubedSphereCalc_Flag)
The valid values are:
- ESMF_CUBEDSPHERECALC_1TILE:
- This is the original method used to calculate coordinates for the ESMF cubed sphere. It uses
an array the size of one tile of the cubed sphere on each PET to calculate coordinates
and ensure their symmetry.
- ESMF_CUBEDSPHERECALC_LOCAL:
- This method just uses an array large enough to hold the local cubed sphere coordinates on each PET.
It relies on careful design of loops and calculation to ensure symmetry of the coordinates. This
method will in general use less memory than ESMF_CUBEDSPHERECALC_1TILE.
54.13 ESMF_DATACOPY
DESCRIPTION:
Indicates how data references, copies, and memory allocations to hold data are
handled.
The type of this flag is:
type(ESMF_DataCopy_Flag)
The valid values are:
- ESMF_DATACOPY_ALLOC
- Create a new allocation that is sufficient in size to hold the data.
However, no data is copied and the allocation is returned uninitialized.
- ESMF_DATACOPY_REFERENCE
- Reference the data within the existing allocation.
- ESMF_DATACOPY_VALUE
- Copy the data to another allocation. If needed create the new allocation.
54.14 ESMF_DECOMP
DESCRIPTION:
Indicates how DistGrid elements are decomposed over DEs.
The type of this flag is:
type(ESMF_Decomp_Flag)
The valid values are:
- ESMF_DECOMP_BALANCED
- Decompose elements as balanced as possible across DEs. The maximum
difference in number of elements per DE is 1, with the extra elements on
the lower DEs.
- ESMF_DECOMP_CYCLIC
- Decompose elements cyclically across DEs.
- ESMF_DECOMP_RESTFIRST
- Divide elements over DEs. Assign the rest of this division to the first
DE.
- ESMF_DECOMP_RESTLAST
- Divide elements over DEs. Assign the rest of this division to the last DE.
- ESMF_DECOMP_SYMMEDGEMAX
- Decompose elements across the DEs in a symmetric fashion. Start with the
maximum number of elements at the two edge DEs, and assign a decending
number of elements to the DEs as the center of the decomposition is
approached from both sides.
This flag is documented in section 45.2.1.
This flag is documented in section 36.2.1.
This flag is documented in section 16.2.1.
54.18 ESMF_EXTRAPMETHOD
DESCRIPTION:
Specify which extrapolation method to use on unmapped destination points after regridding.
The type of this flag is:
type(ESMF_ExtrapMethod_Flag)
The valid values are:
- ESMF_EXTRAPMETHOD_NONE
- Indicates that no extrapolation should be done.
- ESMF_EXTRAPMETHOD_NEAREST_IDAVG
- Inverse distance weighted average.
Here the value of an unmapped destination point is the weighted average
of the closest N source points. The weight is
the reciprocal of the distance of the source point from the destination point raised to a power P.
All the weights contributing to one destination point are normalized so that they sum to 1.0.
The user can choose N and P when using this method, but defaults are also provided.
This extrapolation method is not supported with conservative regrid methods
(e.g. ESMF_REGRIDMETHOD_CONSERVE).
- ESMF_EXTRAPMETHOD_NEAREST_STOD
- Nearest source to destination.
Here the value of each unmapped destination point is set to the value of the closest source point.
This extrapolation method is not supported with conservative regrid methods
(e.g. ESMF_REGRIDMETHOD_CONSERVE).
- ESMF_EXTRAPMETHOD_NEAREST_D
- Nearest mapped destination to unmapped destination.
Here the value of each unmapped destination point is set to the value of the closest mapped (i.e. regridded) destination point.
This extrapolation method is not supported with conservative regrid methods
(e.g. ESMF_REGRIDMETHOD_CONSERVE).
- ESMF_EXTRAPMETHOD_CREEP
- Creep fill.
Here unmapped destination points are filled by moving data from mapped locations to neighboring unmapped locations.
The data filled into a new location is the average of its already filled neighbors' values.
This process is repeated for a user specified number of levels (e.g. in ESMF_FieldRegridStore() this is specified via the extrapNumLevels argument).
This extrapolation method is not supported with conservative regrid methods
(e.g. ESMF_REGRIDMETHOD_CONSERVE).
- ESMF_EXTRAPMETHOD_CREEP_NRST_D
- Creep fill with nearest destination.
Here unmapped destination points are filled using creep fill as described under that entry (see ESMF_EXTRAPMETHOD_CREEP above), any points not filled
by creep fill are then set to the closest filled or mapped destination point as if the nearest destination method (see ESMF_EXTRAPMETHOD_NEAREST_D above)
were run after the initial regridding followed by creep fill.
Like creep fill, this method is repeated for a user specified number of levels
(e.g. in ESMF_FieldRegridStore() this is specified via the extrapNumLevels argument).
This extrapolation method is not supported with conservative regrid methods
(e.g. ESMF_REGRIDMETHOD_CONSERVE).
This flag is documented in section 26.2.1.
54.20 ESMF_FILEFORMAT
DESCRIPTION:
This flag is used in ESMF_GridCreate and ESMF_MeshCreate
functions. It is also used in the ESMF_RegridWeightGen API as an
optional argument.
The type of this flag is:
type(ESMF_FileFormat_Flag)
The valid values are:
- ESMF_FILEFORMAT_CFGRID
- A single tile logically rectangular
grid file that follows the NetCDF CF convention. See section 12.8.3 for more detailed description.
- ESMF_FILEFORMAT_ESMFMESH
- ESMF unstructured grid file format. This format was developed by the ESMF team to match the capabilities of the Mesh class and to be efficient to convert to that class. See section 12.8.2 for more detailed description.
- ESMF_FILEFORMAT_GRIDSPEC
- Equivalent to ESMF_FILEFORMAT_CFGRID flag.
- ESMF_FILEFORMAT_MOSAIC
- This format is a proposed extension to the
CF-conventions for grid mosaics consisting of multiple logically rectangular grid
tiles. See section 12.8.5 for more detailed description.
- ESMF_FILEFORMAT_SCRIP
- SCRIP format grid file. The SCRIP format is
the format accepted by the SCRIP regridding tool [7]. See section12.8.1 for more detailed description.
- ESMF_FILEFORMAT_UGRID
- CF-convention unstructured grid file format. This format is a proposed extension to the
CF-conventions for unstructured grid data model. See section 12.8.4 for more detailed description.
54.21 ESMF_FILEMODE
DESCRIPTION:
This flag is used to indicate which mode to use when writing a weight file.
The type of this flag is:
type(ESMF_FileMode_Flag)
The valid values are:
- ESMF_FILEMODE_BASIC
- Indicates that only the factorList and factorIndexList should be written.
- ESMF_FILEMODE_WITHAUX
- Indicates that grid center coordinates should also be written.
54.22 ESMF_FILESTATUS
DESCRIPTION:
This flag is used in ESMF I/O functions. It's use is similar to the
status keyword in the Fortran open statement.
The type of this flag is:
type(ESMF_FileStatus_Flag)
The valid values are:
- ESMF_FILESTATUS_NEW
- The file must not exist, it will be created.
- ESMF_FILESTATUS_OLD
- The file must exist.
- ESMF_FILESTATUS_REPLACE
- If the file exists, all of its contents will be deleted before writing.
If the file does not exist, it will be created.
- ESMF_FILESTATUS_UNKNOWN
- The value is treated as if it were ESMF_FILESTATUS_OLD if
the corresponding file already exists. Otherwise, the value is
treated as if it were ESMF_FILESTATUS_NEW.
54.23 ESMF_GEOMTYPE
DESCRIPTION:
Different types of geometries upon which an ESMF Field or ESMF Fieldbundle may
be built.
The type of this flag is:
type(ESMF_GeomType_Flag)
The valid values are:
- ESMF_GEOMTYPE_GRID
- An ESMF_Grid, a structured grid composed of one or more logically rectangular tiles.
- ESMF_GEOMTYPE_MESH
- An ESMF_Mesh, an unstructured grid.
- ESMF_GEOMTYPE_XGRID
- An ESMF_XGrid, an exchange grid.
- ESMF_GEOMTYPE_LOCSTREAM
- An ESMF_LocStream, a disconnected series of points with associated key values.
This flag is documented in section 31.2.1.
This flag is documented in section 31.2.2.
This flag is documented in section 31.2.3.
This flag is documented in section 31.2.4.
This flag is documented in section 48.2.1.
54.29 ESMF_INDEX
DESCRIPTION:
Indicates whether index is local (per DE) or global (per object).
The type of this flag is:
type(ESMF_Index_Flag)
The valid values are:
- ESMF_INDEX_DELOCAL
- Indicates that DE-local index space starts at lower bound 1 for each DE.
- ESMF_INDEX_GLOBAL
- Indicates that global indices are used. This means that DE-local index
space starts at the global lower bound for each DE.
- ESMF_INDEX_USER
- Indicates that the DE-local index bounds are explicitly set by the user.
54.30 ESMF_IOFMT
DESCRIPTION:
Indicates I/O format options that are currently supported.
The type of this flag is:
type(ESMF_IOFmt_Flag)
The valid values are:
- ESMF_IOFMT_NETCDF
- NETCDF and PNETCDF (cdf1) format in NETCDF-3 “classic” format. Use
of PNETCDF is prioritized if available.
- ESMF_IOFMT_NETCDF_64BIT_OFFSET
- NETCDF and PNETCDF (cdf2) format. This format allows files greater
than 4GiB in NETCDF-3 “classic” format. Use of PNETCDF is prioritized
if available.
- ESMF_IOFMT_NETCDF_64BIT_DATA
- NETCDF and PNETCDF (cdf5) format. This allows individual records greater
than 4GiB in NETCDF-3 “classic” format. Use of PNETCDF is prioritized
if available.
- ESMF_IOFMT_NETCDF4P
- NETCDF-4 (HDF-5) format. If a NETCDF parallel library is available,
writes will be in parallel. Writes will use one I/O PET per
SSI (node) of the ESMF VM that calls the I/O operation. Otherwise writes
will be serial.
- ESMF_IOFMT_NETCDF4C
- NETCDF-4 (HDF-5) format with lossless compression from HDF-5 applied.
This is only available as a serial option, even if a parallel NETCDF
library is available.
54.31 ESMF_IO_NETCDF_PRESENT
DESCRIPTION:
Indicates whether netcdf feature support has been enabled
within the current ESMF build.
The type of this flag is:
logical
The valid values are:
- .true.
- Netcdf features are enabled.
- .false.
- Netcdf features are not enabled.
54.32 ESMF_IO_PIO_PRESENT
DESCRIPTION:
Indicates whether PIO (parallel I/O) feature support has been enabled
within the current ESMF build.
The type of this flag is:
logical
The valid values are:
- .true.
- PIO features are enabled.
- .false.
- PIO features are not enabled.
54.33 ESMF_IO_PNETCDF_PRESENT
DESCRIPTION:
Indicates whether parallel netcdf feature support has been enabled
within the current ESMF build.
The type of this flag is:
logical
The valid values are:
- .true.
- Parallel NETCDF features are enabled.
- .false.
- Parallel NETCDF features are not enabled.
54.34 ESMF_ITEMORDER
DESCRIPTION:
Specifies the order of items in a list.
The type of this flag is:
type(ESMF_ItemOrder_Flag)
The valid values are:
- ESMF_ITEMORDER_ABC
- The items are in alphabetical order, according to their names.
- ESMF_ITEMORDER_ADDORDER
- The items are in the order in which they were added to the container.
54.35 ESMF_KIND
DESCRIPTION:
Named constants to be used as kind-parameter in Fortran variable
declarations. For example:
integer(ESMF_KIND_I4) :: integerVariable
integer(kind=ESMF_KIND_I4) :: integerVariable
real(ESMF_KIND_R4) :: realVariable
real(kind=ESMF_KIND_R4) :: realVariable
The Fortran standard does not mandate what numeric values correspond to
actual number of bytes allocated for the various kinds. The following constants
are defined by ESMF to be correct across the supported Fortran compilers.
Note that not all compilers support every kind listed below; in particular
1 and 2 byte integers can be problematic.
The type of these named constants is:
integer
The named constants are:
- ESMF_KIND_I1
- Kind-parameter for 1 byte integer.
- ESMF_KIND_I2
- Kind-parameter for 2 byte integer.
- ESMF_KIND_I4
- Kind-parameter for 4 byte integer.
- ESMF_KIND_I8
- Kind-parameter for 8 byte integer.
- ESMF_KIND_R4
- Kind-parameter for 4 byte real.
- ESMF_KIND_R8
- Kind-parameter for 8 byte real.
54.36 ESMF_LINETYPE
DESCRIPTION:
This argument allows the user to select the path of the line which 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.
The type of this flag is:
type(ESMF_LineType_Flag)
The valid values are:
- ESMF_LINETYPE_CART
- Cartesian line. When this option is specified distances are calculated in a straight line through the 3D Cartesian space
in which the sphere is embedded. Cells are approximated by 3D planes bounded by 3D Cartesian lines between their corner vertices.
When calculating regrid weights, this line type is currently the default for non-conservative regrid methods (e.g. ESMF_REGRIDMETHOD_BILINEAR,
ESMF_REGRIDMETHOD_PATCH, ESMF_REGRIDMETHOD_NEAREST_STOD, etc.).
- ESMF_LINETYPE_GREAT_CIRCLE
- Great circle line. When this option is specified distances are calculated along a great circle path (the shortest distance
between two points on a sphere surface). Cells are bounded by great circle paths between their corner vertices. When calculating regrid
weights, this line type is currently the default for conservative regrid methods (e.g. ESMF_REGRIDMETHOD_CONSERVE, etc.).
This flag is documented in section 49.2.1.
This flag is documented in section 49.2.2.
This flag is documented in section 49.2.3.
This flag is documented in section 33.2.1.
54.41 ESMF_MESHLOC
DESCRIPTION:
Used to indicate a specific part of a Mesh. This is commonly used to specify the part of the Mesh to
create a Field on.
The type of this flag is:
type(ESMF_MeshLoc)
The valid values are:
- ESMF_MESHLOC_NODE
- The nodes (also known as corners or vertices) of a Mesh.
- ESMF_MESHLOC_ELEMENT
- The elements (also known as cells) of a Mesh.
54.42 ESMF_MESHOP
DESCRIPTION:
Specifies the spatial operation with two source Meshes, treating the Meshes as point sets.
The type of this flag is:
type(ESMF_MeshOp_Flag)
The valid values are:
- ESMF_MESHOP_DIFFERENCE
- Calculate the difference of the two point sets from the source Meshes.
54.43 ESMF_MESHSTATUS
DESCRIPTION:
The ESMF Mesh class can exist in several states. The ESMF_MESHSTATUS
flag is used to indicate which of these states a Mesh is currently in.
The type of this flag is:
type(ESMF_MeshStatus_Flag)
The valid values are:
- ESMF_MESHSTATUS_UNINIT:
- The Mesh status is uninitialized. This might
happen if the Mesh hasn't been created yet, or if the Mesh has been destroyed.
- ESMF_MESHSTATUS_EMPTY:
- Status after a Mesh has been created with
ESMF_MeshEmptyCreate. Only distribution information has been set in the Mesh.
This object can be used in the ESMF_MeshGet()
method to retrieve distgrids and the distgrid's presence.
- ESMF_MESHSTATUS_STRUCTCREATED:
- Status after a Mesh has been through the first
step of the three step creation process. The Mesh is now ready to have nodes added
to it.
- ESMF_MESHSTATUS_NODESADDED:
- Status after a Mesh has been through the second
step of the three step creation process. The Mesh is now ready to be completed with
elements.
- ESMF_MESHSTATUS_COMPLETE:
- The Mesh has been completely created
and can be used to create a Field. Further, if the internal Mesh memory hasn't been
freed, then the Mesh should be usable in any Mesh functionality (e.g.
regridding). The status of the internal Mesh memory can be checked using
the isMemFreed argument to ESMF_MeshGet().
54.44 ESMF_METHOD
DESCRIPTION:
Specify standard ESMF Component method.
The type of this flag is:
type(ESMF_Method_Flag)
The valid values are:
- ESMF_METHOD_FINALIZE
- Finalize method.
- ESMF_METHOD_INITIALIZE
- Initialize method.
- ESMF_METHOD_READRESTART
- ReadRestart method.
- ESMF_METHOD_RUN
- Run method.
- ESMF_METHOD_WRITERESTART
- WriteRestart method.
DESCRIPTION:
When doing conservative regridding (e.g. ESMF_REGRIDMETHOD_CONSERVE), this option allows the user to select the type of normalization used when producing the weights.
type(ESMF_NormType_Flag)
The valid values are:
- ESMF_NORMTYPE_DSTAREA
- Destination area normalization. Here the weights are calculated by dividing the area of overlap of the source and
destination cells by the area of the entire destination cell. In other words, the weight is the fraction of the
entire destination cell which overlaps with the given source cell.
- ESMF_NORMTYPE_FRACAREA
- Fraction area normalization. Here in addition to the weight calculation done for destination area normalization
(ESMF_NORMTYPE_DSTAREA) the weights are also divided by the fraction that the destination cell overlaps with
the entire source grid. In other words, the weight is the fraction of just the part of the destination cell that
overlaps with the entire source mesh.
This flag is documented in section 50.2.1.
This flag is documented in section 31.2.5.
54.48 ESMF_POLEMETHOD
DESCRIPTION:
When interpolating between two Grids which have been mapped to a sphere these can be used to specify the type of artificial pole to create on the source Grid during interpolation. Creating the pole allows destination points above the top row or below the bottom row of the source Grid to still be mapped.
The type of this flag is:
type(ESMF_PoleMethod_Flag)
The valid values are:
- ESMF_POLEMETHOD_NONE
- No pole. Destination points which lie above the top or below the bottom row of the source Grid won't be mapped.
- ESMF_POLEMETHOD_ALLAVG
- Construct an artificial pole placed in the center of the top (or bottom) row of nodes, but projected onto the sphere formed by the rest of the grid. The value at this pole is the average of all the source values surrounding the pole.
- ESMF_POLEMETHOD_NPNTAVG
- Construct an artificial pole placed in the center of the top (or bottom) row of nodes, but projected onto the sphere formed by the rest of the grid. The value at this pole is the average of the N source nodes next to the pole and surrounding the destination point (i.e. the value may differ for each destination point). Here N is set by using the regridPoleNPnts parameter and ranges from 1 to the number of nodes around the pole. This option is useful for interpolating values which may be zeroed out by averaging around the entire pole (e.g. vector components).
- ESMF_POLEMETHOD_TEETH
- No new pole point is constructed, instead the holes at the poles are filled by constructing triangles across the top and bottom row of the source Grid. This can be useful because no averaging occurs, however, because the top and bottom of the sphere are now flat, for a big enough mismatch between the size of the destination and source pole holes, some destination points may still not be able to be mapped to the source Grid.
54.49 ESMF_REDUCE
DESCRIPTION:
Indicates reduce operation.
The type of this flag is:
type(ESMF_Reduce_Flag)
The valid values are:
- ESMF_REDUCE_SUM
- Use arithmetic sum to add all data elements.
- ESMF_REDUCE_MIN
- Determine the minimum of all data elements.
- ESMF_REDUCE_MAX
- Determine the maximum of all data elements.
54.50 ESMF_REGION
DESCRIPTION:
Specifies various regions in the data layout of an Array or Field object.
The type of this flag is:
type(ESMF_Region_Flag)
The valid values are:
- ESMF_REGION_TOTAL
- Total allocated memory.
- ESMF_REGION_SELECT
- Region of operation-specific elements.
- ESMF_REGION_EMPTY
- The empty region contains no elements.
54.51 ESMF_REGRIDMETHOD
DESCRIPTION:
Specify which interpolation method to use during regridding. For a more detailed discussion of these methods, as well as ESMF regridding in general, see Section 24.2.
The type of this flag is:
type(ESMF_RegridMethod_Flag)
The valid values are:
- ESMF_REGRIDMETHOD_BILINEAR
- Bilinear interpolation. Destination value is a linear combination of the source values in the cell which contains the destination point. The weights for the linear combination are based on the distance of destination point from each source value.
- ESMF_REGRIDMETHOD_PATCH
- Higher-order patch recovery interpolation. Destination value is a weighted average of 2D polynomial patches constructed from cells surrounding the source cell which contains the destination point. This method typically results in better approximations to values and derivatives than bilinear. However, because of its larger stencil, it also results in a much larger interpolation matrix (and thus routeHandle) than the bilinear.
- ESMF_REGRIDMETHOD_NEAREST_STOD
- In this version of nearest neighbor interpolation each destination point is mapped to the closest source point. A given source point may go to multiple destination points, but no destination point will receive input from more than one source point.
- ESMF_REGRIDMETHOD_NEAREST_DTOS
- In this version of nearest neighbor interpolation each source point is mapped to the closest destination point. A given destination point may receive input from multiple source points, but no source point will go to more than one destination point.
- ESMF_REGRIDMETHOD_CONSERVE
- First-order conservative interpolation. The main purpose of this method is to preserve the integral of the field between the source and destination.
Will typically give a less accurate approximation to the individual field values than the bilinear or patch methods. The value of a destination cell is calculated as the weighted sum of the values of the source cells that it overlaps. The weights are determined by the amount the source cell overlaps the destination cell. Needs corner coordinate values to be provided in the Grid. Currently only works for Fields created on the Grid center stagger or the Mesh element location.
- ESMF_REGRIDMETHOD_CONSERVE_2ND
- Second-order conservative interpolation. As with first-order, preserves the integral of the value between the source and destination. However, typically produces a smoother more accurate result than first-order. Also like first-order, the value of a destination cell is calculated as the weighted sum of the values of the source cells that it overlaps. However, second-order also includes additional terms to take into account the gradient of the field across the source cell. Needs corner coordinate values to be provided in the Grid. Currently only works for Fields created on the Grid center stagger or the Mesh element location.
54.52 ESMF_REGRIDSTATUS
DESCRIPTION:
These values can be output during regridding (e.g. from ESMF_FieldRegridStore() via the dstStatusField argument). They indicate the status of each destination location.
The type of this flag is:
integer(ESMF_KIND_I4)
The valid values for all regrid methods are:
- ESMF_REGRIDSTATUS_DSTMASKED
- The destination location is masked, so no regridding has been peformed on it. This status has a numeric value of 0.
- ESMF_REGRIDSTATUS_SRCMASKED
- The destination location is within a masked part of the source grid, so no regridding has been performed on it. This status has a numeric value of 1.
- ESMF_REGRIDSTATUS_OUTSIDE
- The destination location is outside the source grid, so no regridding has been performed on it. This status has a numeric value of 2.
- ESMF_REGRIDSTATUS_MAPPED
- The destination location is within the unmasked source grid, and so has been regridded (i.e. there is an entry for it within the factorIndexList or routeHandle). This status has a numeric value of 4.
- ESMF_REGRIDSTATUS_EXMAPPED
- The destination location was not within the unmasked source grid, and so typically it wouldn't be regridded. However, extrapolation was used, and so it has been regridded (i.e. there is an entry for it within the factorIndexList or routeHandle). This status has a numeric value of 8.
In addition to the above, regridding using the conservative method can result in other values. The reason for this is that in that method one destination cell can overlap multiple source cells, so a single destination can have a combination of values.
The following are the additional values that apply to the conservative method:
- ESMF_REGRIDSTATUS_SMSK_OUT
- The destination cell overlaps a masked source cell, and extends outside the source grid. This status has a numeric value of 3.
- ESMF_REGRIDSTATUS_SMSK_MP
- The destination cell overlaps a masked source cell, and an unmasked source cell. (Because it overlaps with the unmasked source grid, there will be an entry for the destination cell within the factorIndexList or routeHandle). This status has a numeric value of 5.
- ESMF_REGRIDSTATUS_OUT_MP
- The destination cell overlaps an unmasked source cell, and extends outside the source grid. (Because it overlaps with the unmasked source grid, there will be an entry for the destination cell within the factorIndexList or routeHandle). This status has a numeric value of 6.
- ESMF_REGRIDSTATUS_SMSK_OUT_MP
- The destination cell overlaps a masked source cell, an unmasked source cell, and extends outside the source grid. (Because it overlaps with the unmasked source grid, there will be an entry for the destination cell within the factorIndexList or routeHandle). This status has a numeric value of 7.
54.53 ESMF_ROUTESYNC
DESCRIPTION:
Switch between blocking and non-blocking execution of RouteHandle based
communication calls. Every RouteHandle based communication method contains
an optional argument routesyncflag that is of type ESMF_RouteSync_Flag.
The type of this flag is:
type(ESMF_RouteSync_Flag)
The valid values are:
- ESMF_ROUTESYNC_BLOCKING
- Execute a precomputed communication pattern in blocking mode. This
mode guarantees that when the method returns all PET-local data
transfers, both in-bound and out-bound, have finished.
- ESMF_ROUTESYNC_NBSTART
- Start executing a precomputed communication pattern in non-blocking
mode. When a method returns from being called in this mode, it
guarantees that all PET-local out-bound data has been transferred.
It is now safe for the user to overwrite out-bound data elements.
No guarantees are made for in-bound data elements at this stage. It is
unsafe to access these elements until a call in
ESMF_ROUTESYNC_NBTESTFINISH mode has been issued and has returned
with finishedflag equal to .true., or a call in
ESMF_ROUTESYNC_NBWAITFINISH mode has been issued and has returned.
- ESMF_ROUTESYNC_NBTESTFINISH
- Test whether the transfer of data of a precomputed communication
pattern, started with ESMF_ROUTESYNC_NBSTART, has completed.
Finish up as much as possible and set the finishedflag to
.true. if all data operations have completed, or
.false. if there are still outstanding transfers. Only after
a finishedflag equal to .true. has been returned is it
safe to access any of the in-bound data elements.
- ESMF_ROUTESYNC_NBWAITFINISH
- Wait (i.e. block) until the transfer of data of a precomputed
communication pattern, started with ESMF_ROUTESYNC_NBSTART, has
completed. Finish up all data operations and set the returned
finishedflag to .true.. It is safe to access any of the
in-bound data elements once the call has returned.
- ESMF_ROUTESYNC_CANCEL
- Cancel outstanding transfers for a precomputed communication pattern.
This flag is documented in section 50.2.2.
This flag is documented in section 31.2.6.
54.56 ESMF_STARTREGION
DESCRIPTION:
Specifies the start of the effective halo region of an Array or Field object.
The type of this flag is:
type(ESMF_StartRegion_Flag)
The valid values are:
- ESMF_STARTREGION_EXCLUSIVE
- Region of elements that are exclusively owned by the local DE.
- ESMF_STARTREGION_COMPUTATIONAL
- User defined region, greater or equal to the exclusive region.
This flag is documented in section 21.2.1.
This flag is documented in section 21.2.2.
54.59 ESMF_SYNC
DESCRIPTION:
Indicates method blocking behavior and PET synchronization for VM communication
methods, as well as for standard Component methods, such as Initialize(), Run()
and Finalize().
For VM communication calls the ESMF_SYNC_BLOCKING and ESMF_SYNC_NONBLOCKING
modes provide behavior that is practically identical to the blocking and
non-blocking communication calls familiar from MPI.
The details of how the blocking mode setting affects Component methods are
more complex. This is a consequence of the fact that ESMF Components can be
executed in threaded or non-threaded mode. However, in the default,
non-threaded case, where an ESMF application runs as a pure MPI or mpiuni
program, most of the complexity is removed.
See the VM item in 6.6 for an
explanation of the PET and VAS concepts used in the following
descriptions.
The type of this flag is:
type(ESMF_Sync_Flag)
The valid values are:
- ESMF_SYNC_BLOCKING
- Communication calls: The called method will block until all
(PET-)local operations are complete. After the return of a blocking
communication method it is safe to modify or use all participating
local data.
Component calls: The called method will block until all PETs of
the VM have completed the operation.
For a non-threaded, pure MPI
component the behavior is identical to calling a barrier before
returning from the method. Generally this kind of rigid
synchronization is not the desirable mode of operation for an MPI
application, but may be useful for application debugging.
In the opposite case, where all PETs of the component are running as
threads in shared memory, i.e. in a single VAS, strict synchronization
of all PETs is required to prevent race conditions.
- ESMF_SYNC_VASBLOCKING
- Communication calls: Not available for communication calls.
Component calls: The called method will block each PET until
all operations in the PET-local VAS have completed.
This mode is a combination of ESMF_SYNC_BLOCKING and
ESMF_SYNC_NONBLOCKING modes. It provides a default setting
that leads to the typically desirable behavior for pure MPI
components as well as those that share address spaces between PETs.
For a non-threaded, pure MPI component each PET returns
independent of the other PETs. This is generally the expected
behavior in the pure MPI case where calling into a component method is
practically identical to a subroutine call without extra
synchronization between the processes.
In the case where some PETs of the component are running as
threads in shared memory ESMF_SYNC_VASBLOCKING becomes identical
to ESMF_SYNC_BLOCKING within thread groups, to prevent race
conditions, while there is no synchronization between the thread
groups.
- ESMF_SYNC_NONBLOCKING
- Communication calls: The called method will not block but
returns immediately after initiating the requested operation. It is
unsafe to modify or use participating local data before all local
operations have completed. Use the ESMF_VMCommWait() or
ESMF_VMCommQueueWait() method to block the local PET until
local data access is safe again.
Component calls: The behavior of this mode is fundamentally
different for threaded and non-threaded components,
independent on whether the components use shared memory or not.
The ESMF_SYNC_NONBLOCKING mode is the most complex mode for
calling component methods and should only be used if the extra
control, described below, is absolutely necessary.
For non-threaded components (the ESMF default)
calling a component method with ESMF_SYNC_NONBLOCKING
is identical to calling it with ESMF_SYNC_VASBLOCKING. However,
different than for ESMF_SYNC_VASBLOCKING, a call to
ESMF_GridCompWait() or ESMF_CplCompWait() is
required in order to deallocate memory internally allocated for the
ESMF_SYNC_NONBLOCKING mode.
For threaded components the calling PETs
of the parent component will not be blocked and return immediately
after initiating the requested child component method. In this
scenario parent and child components will run concurrently in
identical VASs. This is the most complex mode of operation.
It is unsafe to modify or use VAS local data that
may be accessed by concurrently running components until the child
component method has completed. Use the appropriate
ESMF_GridCompWait() or ESMF_CplCompWait() method to
block the local parent PET until the child component method has
completed in the local VAS.
54.60 ESMF_TERMORDER
DESCRIPTION:
Specifies the order of source terms in a destination sum, e.g. during sparse
matrix multiplication.
The type of this flag is:
type(ESMF_TermOrder_Flag)
The valid values are:
- ESMF_TERMORDER_SRCSEQ
- The source terms are in strict ascending order according to
their source sequence index.
- ESMF_TERMORDER_SRCPET
- The source terms are first ordered according to their distribution
across the source side PETs: for each destination PET the source PET
order starts with the localPet and decrements from there, modulo
petCount, until all petCount PETs are accounted for. The term order
within each source PET is given by the source term sequence index.
- ESMF_TERMORDER_FREE
- There is no prescribed term order. The source terms may be summed in
any order that optimizes performance.
54.61 ESMF_TYPEKIND
DESCRIPTION:
Named constants used to indicate type and kind combinations supported by the
overloaded ESMF interfaces. The corresponding Fortran kind-parameter constants
are described in section 54.35.
The type of these named constants is:
type(ESMF_TypeKind_Flag)
The named constants numerical types are:
- ESMF_TYPEKIND_I1
- Indicates 1 byte integer.
(Only available if ESMF was built with
ESMF_NO_INTEGER_1_BYTE = FALSE. This is not the default.)
- ESMF_TYPEKIND_I2
- Indicates 2 byte integer.
(Only available if ESMF was built with
ESMF_NO_INTEGER_2_BYTE = FALSE. This is not the default.)
- ESMF_TYPEKIND_I4
- Indicates 4 byte integer.
- ESMF_TYPEKIND_I8
- Indicates 8 byte integer.
- ESMF_TYPEKIND_R4
- Indicates 4 byte real.
- ESMF_TYPEKIND_R8
- Indicates 8 byte real.
The named constants non-numerical types are:
- ESMF_TYPEKIND_LOGICAL
- Indicates a logical value.
- ESMF_TYPEKIND_CHARACTER
- Indicates a character string.
54.62 ESMF_UNMAPPEDACTION
DESCRIPTION:
Indicates what action to take with respect to unmapped destination points
and the entries of the sparse matrix that correspond to these points.
The type of this flag is:
type(ESMF_UnmappedAction_Flag)
The valid values are:
- ESMF_UNMAPPEDACTION_ERROR
- An error is issued when there exist destination points in a regridding
operation that are not mapped by corresponding source points.
- ESMF_UNMAPPEDACTION_IGNORE
- Destination points which do not have corresponding source points are
ignored and zeros are used for the entries of the sparse matrix
that is generated.
54.63 ESMF_VERSION
DESCRIPTION:
The following named constants define the precise version of ESMF in use.
- ESMF_VERSION_BETASNAPSHOT
- Constant of type logical indicating beta snapshot phase
(.true. for any version during the pre-release development phase,
.false. for any released version of the software).
- ESMF_VERSION_MAJOR
- Constant of type integer indicating the major version number
(e.g. 5 for v5.2.0r).
- ESMF_VERSION_MINOR
- Constant of type integer indicating the minor version number
(e.g. 2 for v5.2.0r).
- ESMF_VERSION_PATCHLEVEL
- Constant of type integer indicating the patch level of a specific
revision (e.g. 0 for v5.2.0r, or 1 for v5.2.0rp1).
- ESMF_VERSION_PUBLIC
- Constant of type logical indicating public vs. internal release
status (e.g. .true. for v5.2.0r, or .false. for v5.2.0).
- ESMF_VERSION_REVISION
- Constant of type integer indicating the revision number
(e.g. 0 for v5.2.0r).
- ESMF_VERSION_STRING
- Constant of type character holding the exact release version string
(e.g. "5.2.0r").
This flag is documented in section 51.2.1.
This flag is documented in section 34.2.1.
The schematic below shows the Unified Modeling Language (UML) notation
for the class diagrams presented in this Reference Manual. For
more on UML, see references such as The Unified Modeling Language
Reference Manual, Rumbaugh et al, [19].
56 Appendix C: ESMF Error Return Codes
The tables below show the possible error return codes for Fortran and
C methods.
57 Appendix D: Attribute Class Legacy API
Documentation for the legacy ESMF_Attribute Class. It is recommended that users migrate to the ESMF_Info class (see section 40).
Notice that a few aspects of the legacy Attribute API have been modified compared to its original implementation. These changes were necessary as a consequence of the changed backend to ESMF_Info:
- The ESMF_AttributeSet() method now supports setting attributes that were not previously added via ESMF_AttributeAdd(). In other words, the ESMF_AttributeAdd() method has become optional.
- There are overloads of the ESMF_AttributeSet() and ESMF_AttributeGet() with optional convention and purpose arguments. Both arguments must either be present or absent. Any other combination is handled as an error condition. For the case that both convention and purpose arguments are absent, and no Attribute Package is specified, the default JSON key prefix is "/ESMF/General".
57.1.1 ESMF_ATTCOPY
DEPRECATED CLASS!
The entire ESMF_Attribute class has been deprecated and is scheduled for removal with ESMF 9.0.0. This includes all of the class derived types, named constants, and methods. Please use the replacment class ESMF_Info, section 40 instead!
DESCRIPTION:
Indicates which type of copy behavior is used when copying ESMF Attribute objects.
The type of this flag is:
type(ESMF_AttCopy_Flag)
The valid values are:
- ESMF_ATTCOPY_REFERENCE
- The destination Attribute hierarchy becomes a reference copy of
the Attribute hierarchy of the source object. Any further changes to one
will also be reflected in the other.
- ESMF_ATTCOPY_VALUE
- All of the Attributes and Attribute packages of the source object will be
copied by value to the destination object. None of the Attribute links to
the Attribute hierarchies of other objects are copied to the
destination object.
57.1.2 ESMF_ATTGETCOUNT
DEPRECATED CLASS!
The entire ESMF_Attribute class has been deprecated and is scheduled for removal with ESMF 9.0.0. This includes all of the class derived types, named constants, and methods. Please use the replacment class ESMF_Info, section 40 instead!
DESCRIPTION:
Indicates which type of Attribute object count to return.
The type of this flag is:
type(ESMF_AttGetCountFlag)
The valid values are:
- ESMF_ATTGETCOUNT_ATTRIBUTE
- This option will allow the routine to return the number of single Attributes.
- ESMF_ATTGETCOUNT_ATTPACK
- This option will allow the routine to return the number of Attribute packages.
- ESMF_ATTGETCOUNT_TOTAL
- This option will allow the routine to return the total number of Attributes.
57.1.3 ESMF_ATTWRITE
DEPRECATED CLASS!
The entire ESMF_Attribute class has been deprecated and is scheduled for removal with ESMF 9.0.0. This includes all of the class derived types, named constants, and methods. Please use the replacment class ESMF_Info, section 40 instead!
DESCRIPTION:
Indicates which file format to use in the write operation.
The type of this flag is:
type(ESMF_AttWriteFlag)
The valid values are:
- ESMF_ATTWRITE_JSON
- This option will allow the routine to write in JSON format.
esmf_support@ucar.edu
