Next: 5 Infrastructure: Utilities Up: ESMF_refdoc Previous: 3 Superstructure Contents
The ESMF infrastructure data classes are part of the framework's hierarchy of structures for handling Earth system model data and metadata on parallel platforms. The hierarchy is in complexity; the simplest data class in the infrastructure represents a distributed data array and the most complex data class represents a bundle of physical fields that are discretized on the same grid. Data class methods are called both from user-written code and from other classes internal to the framework.
Data classes are distributed over DEs, or Decomposition Elements. A DE represents a piece of a decomposition. A DELayout is a collection of DEs with some associated connectivity that describes a specific distribution. For example, the distribution of a grid divided into four segments in the x-dimension would be expressed in ESMF as a DELayout with four DEs lying along an x-axis. This abstract concept enables a data decomposition to be defined in terms of threads, MPI processes, virtual decomposition elements, or combinations of these without changes to user code. This is a primary strategy for ensuring optimal performance and portability for codes using ESMF for communications.
ESMF data classes provide a standard, convenient way for developers to collect together information related to model or observational data. The information assembled in a data class includes a data pointer, a set of attributes (e.g. units, although attributes can also be user-defined), and a description of an associated grid. The same set of information within an ESMF data object can be used by the framework to arrange intercomponent data transfers, to perform I/O, for communications such as gathers and scatters, for simplification of interfaces within user code, for debugging, and for other functions. This unifies and organizes codes overall so that the user need not define different representations of metadata for the same field for I/O and for component coupling.
Since it is critical that users be able to introduce ESMF into their codes easily and incrementally, ESMF data classes can be created based on native Fortran pointers. Likewise, there are methods for retrieving native Fortran pointers from within ESMF data objects. This allows the user to perform allocations using ESMF, and to retrieve Fortran arrays later for optimized model calculations. The ESMF data classes do not have associated differential operators or other mathematical methods.
For flexibility, it is not necessary to build an ESMF data object all at once. For example, it's possible to create a field but to defer allocation of the associated field data until a later time.
|
Key Features |
| Hierarchy of data structures designed specifically for the Earth system domain and high performance, parallel computing. |
| Multi-use ESMF structures simplify user code overall. |
| Data objects support incremental construction and deferred allocation. |
| Native Fortran arrays can be associated with or retrieved from ESMF data objects, for ease of adoption, convenience, and performance. |
| A variety of operations are provided for manipulating data in data objects such as regridding, redistribution, halo communication, and sparse matrix multiply. |
The main classes that are used for model and observational data manipulation are as follows:
Data elements in Arrays are partitioned into categories defined by the role the data element plays in distributed halo operations. Haloing - sometimes called ghosting - is the practice of copying portions of array data to multiple memory locations to ensure that data dependencies can be satisfied quickly when performing a calculation. ESMF Arrays contain an exclusive domain, which contains data elements updated exclusively and definitively by a given DE; a computational domain, which contains all data elements with values that are updated by the DE in computations; and a total domain, which includes both the computational domain and data elements from other DEs which may be read but are not updated in computations.
FieldBundle objects contain methods for setting and retrieving constituent fields, regridding, data I/O, and reordering of data in memory.
Bit-for-bit reproducibility is at the core of the regression testing schemes of many scientific model codes. The bit-for-bit requirement makes it easy to compare the numerical results of simulation runs using standard binary diff tools.
For the most part, ESMF methods do not modify user data numerically, and thus have no effect on the bit-for-bit characteristics of the model code. The exceptions are the regrid weight generation and the sparse matrix multiplication.
In the case of the regrid weight generation, user data is used to produce interpolation weights following specific numerical schemes. The bit-for-bit reproducibility of the generated weights depends on the implementation details. Section 24.2 provides more details about the bit-for-bit considerations with respect to the regrid weights generated by ESMF.
In the case of the sparse matrix multiplication, which is the typical method that is used to apply the regrid weights, user data is directly manipulated by ESMF. In order to help users with the implementation of their bit-for-bit requirements, while also considering the associated performance impact, the ESMF sparse matrix implementation provides three levels of bit-for-bit support. The strictest level ensures that the numerical results are bit-for-bit identical, even when executing across different numbers of PETs. In the relaxed level, bit-for-bit reproducibility is guaranteed when running across an unchanged number of PETs. The lowest level makes no guarantees about bit-for-bit reproducibility, however, it provides the greatest performance potential for those cases where numerical round-off differences are acceptable. An in-depth discussion of bit-for-bit reproducibility, and the performance aspects of route-based communication methods, such the sparse matrix multiplication, is given in section 37.2.1.
This section describes the regridding methods provided by ESMF. Regridding, also called remapping or interpolation, is the process of changing the grid that underlies data values while preserving qualities of the original data. Different kinds of transformations are appropriate for different problems. Regridding may be needed when communicating data between Earth system model components such as land and atmosphere, or between different data sets to support operations such as visualization.
Regridding can be broken into two stages. The first stage is generation of an interpolation weight matrix that describes how points in the source grid contribute to points in the destination grid. The second stage is the multiplication of values on the source grid by the interpolation weight matrix to produce values on the destination grid. This is implemented as a parallel sparse matrix multiplication.
There are two options for accessing ESMF regridding functionality: offline and integrated. Offline regridding is a process whereby interpolation weights are generated by a separate ESMF command line tool, not within the user code. The ESMF offline regridding tool also only generates the interpolation matrix, the user is responsible for reading in this matrix and doing the actual interpolation (multiplication by the sparse matrix) in their code. Please see Section 12 for a description of the offline regridding command line tool and the options it supports. For user convenience, there is also a method interface to the offline regrid tool functionality which is described in Section 24.3.1. In contrast to offline regridding, integrated regridding is a process whereby interpolation weights are generated via subroutine calls during the execution of the user's code. In addition to generating the weights, integrated regridding can also produce a RouteHandle (described in Section 37.1) which allows the user to perform the parallel sparse matrix multiplication using ESMF methods. In other words, ESMF integrated regridding allows a user to perform the whole process of interpolation within their code.
To see what types of grids and other options are supported in the two types of regridding and their testing status, please see the ESMF Regridding Status webpage for this version of ESMF. Figure 24.2 shows a comparison of different regrid interfaces and where they can be found in the documentation.
The rest of this section further describes the various options available in ESMF regridding.
| ||||||||||||||||||||||||||||||||||||
In 2D, ESMF supports bilinear regridding between any combination of the following:
In 3D, ESMF supports bilinear regridding between any combination of the following:
Restrictions:
To use the bilinear method the user may create their Fields on any stagger location (e.g. ESMF_STAGGERLOC_CENTER) for a Grid, or any Mesh location (e.g. ESMF_MESHLOC_NODE) for a Mesh. For either a Grid or a Mesh, the location upon which the Field is built must contain coordinates. This method will also work with a destination Field built on a LocStream that contains coordinates, or with a source or destination Field built on an XGrid.
Patch (or higher-order) interpolation is the ESMF version of a technique called “patch recovery” commonly used in finite element modeling [28] [24]. It typically results in better approximations to values and derivatives when compared to bilinear interpolation. Patch interpolation works by constructing multiple polynomial patches to represent the data in a source cell. For 2D grids, these polynomials are currently 2nd degree 2D polynomials. One patch is constructed for each corner of the source cell, and the patch is constructed by doing a least squares fit through the data in the cells surrounding the corner. The interpolated value at the destination point is then a weighted average of the values of the patches at that point.
The patch method has a larger stencil than the bilinear, for this reason the patch weight matrix can be correspondingly larger than the bilinear matrix (e.g. for a quadrilateral grid the patch matrix is around 4x the size of the bilinear matrix). This can be an issue when performing a regrid operation close to the memory limit on a machine.
The patch method does not guarantee that after regridding the range of values in the destination field is within the range of values in the source field. For example, if the mininum value in the source field is 0.0, then it's possible that after regridding with the patch method, the destination field will contain values less than 0.0.
In 2D, ESMF supports patch regridding between any combination of the following:
In 3D, ESMF supports patch regridding between any combination of the following:
Restrictions:
To use the patch method the user may create their Fields on any stagger location (e.g. ESMF_STAGGERLOC_CENTER) for a Grid, or any Mesh location (e.g. ESMF_MESHLOC_NODE) for a Mesh. For either a Grid or a Mesh, the location upon which the Field is built must contain coordinates. This method will also work with a destination Field built on a LocStream that contains coordinates, or with a source or destination Field built on an XGrid.
In 2D, ESMF supports nearest source to destination regridding between any combination of the following:
In 3D, ESMF supports nearest source to destination regridding between any combination of the following:
Restrictions:
NONE
To use the nearest source to destination method the user may create their Fields on any stagger location (e.g. ESMF_STAGGERLOC_CENTER) for a Grid, or any Mesh location (e.g. ESMF_MESHLOC_NODE) for a Mesh. For either a Grid or a Mesh, the location upon which the Field is built must contain coordinates. This method will also work with a source or destination Field built on a LocStream that contains coordinates, or when the source or destination Field is built on an XGrid.
In 2D, ESMF supports nearest destination to source regridding between any combination of the following:
In 3D, ESMF supports nearest destination to source regridding between any combination of the following:
Restrictions:
To use the nearest destination to source method the user may create their Fields on any stagger location (e.g. ESMF_STAGGERLOC_CENTER) for a Grid, or any Mesh location (e.g. ESMF_MESHLOC_NODE) for a Mesh. For either a Grid or a Mesh, the location upon which the Field is built must contain coordinates. This method will also work with a source or destination Field built on a LocStream that contains coordinates, or when the source or destination Field is built on an XGrid.
In the first-order method, the values for a particular destination cell are a calculated as a combination of the values of the intersecting source cells. The weight of a given source cell's contribution to the total being the amount that that source cell overlaps with the destination cell. In particular, the weight is the ratio of the area of intersection of the source and destination cells to the area of the whole destination cell.
To see a description of how the different normalization options affect the values and integrals produced by the conservative methods see section 24.2.8. For Grids, Meshes, or XGrids on a sphere this method uses great circle cells, for a description of potential problems with these see 24.2.9.
In 2D, ESMF supports conservative regridding between any combination of the following:
In 3D, ESMF supports conservative regridding between any combination of the following:
Restrictions:
To use the conservative method the user should create their Fields on the center stagger location (ESMF_STAGGERLOC_CENTER in 2D or ESMF_STAGGERLOC_CENTER_VCENTER in 3D) for Grids or the element location (ESMF_MESHLOC_ELEMENT) for Meshes. For Grids, the corner stagger location (ESMF_STAGGERLOC_CORNER in 2D or ESMF_STAGGERLOC_CORNER_VFACE in 3D) must contain coordinates describing the outer perimeter of the Grid cells. This method will also work when the source or destination Field is built on an XGrid.
Like the first-order method, the values for a particular destination cell with the second-order method
are a combination of the values of the intersecting source cells with the weight of a given source cell's contribution to the total
being the amount that that source cell overlaps with the destination cell.
However, with the second-order conservative interpolation there are additional terms that take into account the gradient of the field
across the source cell. In particular, the value 
for a given destination cell is calculated as:
Where:
To see a description of how the different normalization options affect the values and integrals produced by the conservative methods see section 24.2.8. For Grids, Meshes, or XGrids on a sphere this method uses great circle cells, for a description of potential problems with these see 24.2.9.
In 2D, ESMF supports second-order conservative regridding between any combination of the following:
In 3D, ESMF supports second-order conservative regridding between any combination of the following:
Restrictions:
To use the second-order conservative method the user should create their Fields on the center stagger location (ESMF_STAGGERLOC_CENTER for Grids or the element location (ESMF_MESHLOC_ELEMENT) for Meshes. For Grids, the corner stagger location (ESMF_STAGGERLOC_CORNER in 2D must contain coordinates describing the outer perimeter of the Grid cells. This method will also work when the source or destination Field is built on an XGrid.
, where
V is the variable being regridded and A is the area of a cell. The subscripts s and d refer to source and destination values, and the i and j are the source and destination grid cell indices (flattening the arrays to 1 dimension).
If the user doesn't specify a cell areas in the involved Grids or Meshes, then the areas (A) in the above equation are calculated by ESMF. For Cartesian grids, the area of a grid cell calculated by ESMF is the typical Cartesian area. For grids on a sphere, cell areas are calculated by connecting the corner coordinates of each grid cell with great circles. If the user does specify the areas in the Grid or Mesh, then the conservation will be adjusted to work for the areas provided by the user. This means that the above equation will hold, but with the areas (A) being the ones specified by the user.
The user should be aware that because of the conservation relationship between the source and destination fields, the more the total source area differs from the total destination area the more the values of the source field will differ from the corresponding values of the destination field, likely giving a higher interpolation error. It is best to have the total source and destination areas the same (this will automatically be true if no user areas are specified). For source and destination grids that only partially overlap, the overlapping regions of the source and destination should be the same.
For weights generated using destination area normalization (either by not specifying any normalization type or by specifying normType=ESMF_NORMTYPE_DSTAREA), if a destination field extends outside the unmasked source field, then the values of the cells which extend partway outside the unmasked source field are decreased by the fraction they extend outside. To correct these values, the destination field (dst_field) resulting from the ESMF_FieldRegrid() call can be divided by the destination fraction dst_frac from the ESMF_FieldRegridStore() call. The following pseudocode demonstrates how to do this:
for each destination element i
if (dst_frac(i) not equal to 0.0) then
dst_field(i)=dst_field(i)/dst_frac(i)
end if
end for
For weights generated using destination area normalization (either by not specifying any normalization type or by specifying normType=ESMF_NORMTYPE_DSTAREA), the following pseudo-code shows how to compute the total destination integral (dst_total) given the destination field values (dst_field) resulting from the ESMF_FieldRegrid() call, the destination area (dst_area) from the ESMF_FieldRegridGetArea() call, and the destination fraction (dst_frac) from the ESMF_FieldRegridStore() call. As shown in the previous paragraph, it also shows how to adjust the destination field (dst_field) resulting from the ESMF_FieldRegrid() call by the fraction (dst_frac) from the ESMF_FieldRegridStore() call:
dst_total=0.0
for each destination element i
if (dst_frac(i) not equal to 0.0) then
dst_total=dst_total+dst_field(i)*dst_area(i)
dst_field(i)=dst_field(i)/dst_frac(i)
! If mass computed here after dst_field adjust, would need to be:
! dst_total=dst_total+dst_field(i)*dst_area(i)*dst_frac(i)
end if
end for
For weights generated using fraction area normalization (by specifying normType=ESMF_NORMTYPE_FRACAREA), no adjustment of the destination field is necessary. The following pseudo-code shows how to compute the total destination integral (dst_total) given the destination field values (dst_field) resulting from the ESMF_FieldRegrid() call, the destination area (dst_area) from the ESMF_FieldRegridGetArea() call, and the destination fraction (dst_frac) from the ESMF_FieldRegridStore() call:
dst_total=0.0
for each destination element i
dst_total=dst_total+dst_field(i)*dst_area(i)*dst_frac(i)
end for
For both normalization types, the following pseudo-code shows how to compute the total source integral (src_total) given the source field values (src_field), the source area (src_area) from the ESMF_FieldRegridGetArea() call, and the source fraction (src_frac) from the ESMF_FieldRegridStore() call:
src_total=0.0
for each source element i
src_total=src_total+src_field(i)*src_area(i)*src_frac(i)
end for
A great circle edge isn't necessarily the same as a straight line in latitude longitude space. For small edges, this difference will be small, but for long edges it could be significant. This means if the user expects cell edges as straight lines in latitude longitude space, they should avoid using one large cell with long edges to compute an average over a region (e.g. over an ocean basin).
Also, the user should also avoid using cells that contain one edge that runs half way or more around the earth, because the regrid weight calculation assumes the edge follows the shorter great circle path. There isn't a unique great circle edge defined between points on the exact opposite side of the earth from one another (antipodal points). However, the user can work around both of these problem by breaking the long edge into two smaller edges by inserting an extra node, or by breaking the large target grid cells into two or more smaller grid cells. This allows the application to resolve the ambiguity in edge direction.
The user may mask out points in the source Field or destination Field or both. To do masking the user sets mask information in the Grid (see 31.3.17), Mesh (see 33.3.11), or LocStream (see 32.2.2) upon which the Fields passed into the ESMF_FieldRegridStore() call are built. The srcMaskValues and dstMaskValues arguments to that call can then be used to specify which values in that mask information indicate that a location should be masked out. For example, if dstMaskValues is set to (/1,2/), then any location that has a value of 1 or 2 in the mask information of the Grid, Mesh or LocStream upon which the destination Field is built will be masked out.
Masking behavior differs slightly between regridding methods. For non-conservative regridding methods (e.g. bilinear or high-order patch), masking is done on points. For these methods, masking a destination point means that that point won't participate in regridding (e.g. won't be interpolated to). For these methods, masking a source point means that the entire source cell using that point is masked out. In other words, if any corner point making up a source cell is masked then the cell is masked. For conservative regridding methods (e.g. first-order conservative) masking is done on cells. Masking a destination cell means that the cell won't participate in regridding (e.g. won't be interpolated to). Similarly, masking a source cell means that the cell won't participate in regridding (e.g. won't be interpolated from). For any type of interpolation method (conservative or non-conservative) the masking is set on the location upon which the Fields passed into the regridding call are built. For example, if Fields built on ESMF_STAGGERLOC_CENTER are passed into the ESMF_FieldRegridStore() call then the masking should also be set on ESMF_STAGGERLOC_CENTER.
Extrapolation in the ESMF regridding system is a way to automatically fill some or all of the destination points left unmapped by a regridding method. Weights generated by the extrapolation method are merged into the regridding weights to yield one set of weights or routehandle. Currently extrapolation is not supported with conservative regridding methods, because doing so would result in non-conservative weights.
If there is at least one unmasked source point, then this method is expected to fill all unmapped points.
If there is at least one unmasked source point, then this method is expected to fill all unmapped points.
Unlike some extrapolation methods, creep fill does not necessarily fill all unmapped destination points. Unfilled destination points are still unmapped with the usual consequences (e.g. they won't be in the resulting regridding matrix, and won't be set by the application of the regridding weights).
Because it depends on the connections in the destination grid, creep fill extrapolation is not supported when the destination Field is built on a Location Stream (ESMF_LocStream). Also, creep fill is currently only supported for 2D Grids, Meshes, or XGrids
For Grids on a sphere, the regridding occurs in 3D Cartesian to avoid problems with periodicity and with the pole singularity. This library supports four options for handling the pole region (i.e. the empty area above the top row of the source grid or below the bottom row of the source grid). Note that all of these pole options currently only work for the Fields build on the Grid class.
The first option is to leave the pole region empty (polemethod=ESMF_POLEMETHOD_NONE), in this case if a destination point lies above or below the top row of the source grid, it will fail to map, yielding an error (unless unmappedaction=ESMF_UNMAPPEDACTION_IGNORE is specified).
With the next two options (ESMF_POLEMETHOD_ALLAVG and ESMF_POLEMETHOD_NPNTAVG), the pole region is handled by constructing an artificial pole in the center of the top and bottom row of grid points and then filling in the region from this pole to the edges of the source grid with triangles. The pole is located at the average of the position of the points surrounding it, but moved outward to be at the same radius as the rest of the points in the grid. The difference between the two artificial pole options is what value is used at the pole. The option (polemethod=ESMF_POLEMETHOD_ALLAVG) sets the value at the pole to be the average of the values of all of the grid points surrounding the pole. The option (polemethod=ESMF_POLEMETHOD_NPNTAVG) allows the user to choose a number N from 1 to the number of source grid points around the pole. The value N is set via the argument regridPoleNPnts. For each destination point, the value at the pole is then the average of the N source points surrounding that destination point.
The last option (polemethod=ESMF_POLEMETHOD_TEETH) does not construct an artificial pole, instead the pole region is covered by connecting points across the top and bottom row of the source Grid into triangles. As this makes the top and bottom of the source sphere flat, for a big enough difference between the size of the source and destination pole regions, this can still result in unmapped destination points. Only pole option ESMF_POLEMETHOD_NONE is currently supported with the conservative interpolation methods (e.g. regridmethod=ESMF_REGRIDMETHOD_CONSERVE) and with the nearest neighbor interpolation options (e.g. regridmethod=ESMF_REGRIDMETHOD_NEAREST_STOD).
Another variation in the regridding supported with spherical grids is line type. This is controlled in the ESMF_FieldRegridStore() method by the lineType argument. This argument allows the user to select the path of the line which connects two points on a sphere surface. This in turn controls the path along which distances are calculated and the shape of the edges that make up a cell. Both of these quantities can influence how interpolation weights are calculated, for example in bilinear interpolation the distances are used to calculate the weights and the cell edges are used to determine to which source cell a destination point should be mapped.
ESMF currently supports two line types: ESMF_LINETYPE_CART and ESMF_LINETYPE_GREAT_CIRCLE. The ESMF_LINETYPE_CART option specifies that the line between two points follows a straight path through the 3D Cartesian space in which the sphere is embedded. Distances are measured along this 3D Cartesian line. Under this option cells are approximated by planes in 3D space, and their boundaries are 3D Cartesian lines between their corner points. The ESMF_LINETYPE_GREAT_CIRCLE option specifies that the line between two points follows a great circle path along the sphere surface. (A great circle is the shortest path between two points on a sphere.) Distances are measured along the great circle path. Under this option cells are on the sphere surface, and their boundaries are great circle paths between their corner points.
Figure 24.2.16 shows which line types are supported for each regrid method as well as the defaults (indicated by *).
ESMF's initial vector regridding capability is intended to give cleaner results for 2D spherical vectors expressed in terms of local directions (e.g. east and north) than regridding each vector component separately. To do this, it converts the vectors to 3D Cartesian space and then does the regridding there. This allows all the vectors participating in the regridding to have a consistent representation. After regridding, the resulting 3D vectors are then converted back to the local direction form. This entire process is expressed in the usual weight matrix and/or routeHandle form and so the typical ESMF_FieldRegridStore()/ESMF_FieldRegrid()/ESMF_FieldRegridRelease() regridding paradigm can be used. However, the weight matrix will be in the format that allows it to contain tensor dimension indices (i.e. the leading dimension of the factorIndexList will be of size 4).
In this initial version the meaning of the different entries in the vector dimension are fixed. They will be interpreted as:
Note that because the different components are mixed, using vector regridding with a conservative regrid method will not necessarily produce vectors whose components are conservative.
The below is a list of problems users commonly encounter with regridding and potential solutions. This is by no means an exhaustive list, so if none of these problems fit your case, or if the solutions don't fix your problem, please feel free to email esmf support (esmf_support@ucar.edu).
Problem: Regridding is too slow.
Possible Cause: The ESMF_FieldRegridStore() method is called more than is necessary.
The ESMF_FieldRegridStore() operation is a complex one and can be
relatively slow for some cases (large Grids, 3D grids, etc.)
Solution: Reduce the number of ESMF_FieldRegridStore() calls to the minimum necessary. The routeHandle generated by the ESMF_FieldRegridStore() call depends on only four factors: the stagger locations that the input Fields are created on, the coordinates in the Grids the input Fields are built on at those stagger locations, the padding of the input Fields (specified by the totalWidth arguments in FieldCreate) and the size of the tensor dimensions in the input Fields (specified by the ungridded arguments in FieldCreate). For any pair of Fields which share these attributes with the Fields used in the ESMF_FieldRegridStore call the same routeHandle can be used. Note that the data in the Fields does NOT matter, the same routeHandle can be used no matter how the data in the Fields changes.
In particular:
Problem: Distortions in destination Field at periodic boundary.
Possible Cause: The Grid overlaps itself. With a periodic Grid, the regrid system expects the first point to not be a repeat of the last point. In other words, regrid constructs its own connection and overlap between the first and last points of the periodic dimension and so the Grid doesn't need to contain these. If the Grid does, then this can cause problems.
Solution: Define the Grid so that it doesn't contain the overlap point. This typically means simply making the Grid one point smaller in the periodic dimension. If a Field constructed on the Grid needs to contain these overlap points then the user can use the totalWidth arguments to include this extra padding in the Field. Note, however, that the regrid won't update these extra points, so the user will have to do a copy to fill the points in the overlap region in the Field.
The ESMF regrid weight calculation functionality has been designed to enable it to support a wide range of grid and interpolation types without needing to support each individual combination of source grid type, destination grid type, and interpolation method. To avoid the quadratic growth of the number of pairs of grid types, all grids are converted to a common internal format and the regrid weight calculation is performed on that format. This vastly reduces the variety of grids that need to be supported in the weight calculations for each interpolation method. It also has the added benefit of making it straightforward to add new grid types and to allow them to work with all the existing grid types. To hook into the existing weight calculation code, the new type just needs to be converted to the internal format.
The internal grid format used by the ESMF regrid weight calculation is a finite element unstructured mesh. This was chosen because it was the most general format and all the others could be converted to it. The ESMF finite element unstructured mesh (ESMF FEM) is similar in some respects to the SIERRA [20] package developed at Sandia National Laboratory. The ESMF code relies on some of the same underlying toolkits (e.g. Zoltan [18] library for calculating mesh partitions) and adds a layer on top that allows the calculation of regrid weights and some mesh operations (e.g. mesh redistribution) that ESMF needs. The ESMF FEM has similar notions to SIERRA about the basic structure of the mesh entities, fields, iteration and a similar notion of parallel distribution.
Currently we use the ESMF FEM internal mesh to hold the structure of our Mesh class and in our regrid weight calculation. The parts of the internal FEM code that are used/tested by ESMF are the following:
INTERFACE:
! Private name; call using ESMF_RegridWeightGen()
subroutine ESMF_RegridWeightGenFile(srcFile, dstFile, &
weightFile, rhFile, regridmethod, polemethod, regridPoleNPnts, lineType, normType, &
extrapMethod, extrapNumSrcPnts, extrapDistExponent, extrapNumLevels, &
unmappedaction, ignoreDegenerate, srcFileType, dstFileType, &
srcRegionalFlag, dstRegionalFlag, srcMeshname, dstMeshname, &
srcMissingvalueFlag, srcMissingvalueVar, &
dstMissingvalueFlag, dstMissingvalueVar, &
useSrcCoordFlag, srcCoordinateVars, &
useDstCoordFlag, dstCoordinateVars, &
useSrcCornerFlag, useDstCornerFlag, &
useUserAreaFlag, largefileFlag, &
netcdf4fileFlag, weightOnlyFlag, &
tileFilePath, &
verboseFlag, checkFlag, rc)
ARGUMENTS:
character(len=*), intent(in) :: srcFile character(len=*), intent(in) :: dstFile -- The following arguments require argument keyword syntax (e.g. rc=rc). -- character(len=*), intent(in), optional :: weightFile character(len=*), intent(in), optional :: rhFile type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod type(ESMF_PoleMethod_Flag), intent(in), optional :: polemethod integer, intent(in), optional :: regridPoleNPnts type(ESMF_LineType_Flag), intent(in), optional :: lineType type(ESMF_NormType_Flag), intent(in), optional :: normType type(ESMF_ExtrapMethod_Flag), intent(in), optional :: extrapMethod integer, intent(in), optional :: extrapNumSrcPnts real, intent(in), optional :: extrapDistExponent integer, intent(in), optional :: extrapNumLevels type(ESMF_UnmappedAction_Flag),intent(in), optional :: unmappedaction logical, intent(in), optional :: ignoreDegenerate type(ESMF_FileFormat_Flag), intent(in), optional :: srcFileType type(ESMF_FileFormat_Flag), intent(in), optional :: dstFileType logical, intent(in), optional :: srcRegionalFlag logical, intent(in), optional :: dstRegionalFlag character(len=*), intent(in), optional :: srcMeshname character(len=*), intent(in), optional :: dstMeshname logical, intent(in), optional :: srcMissingValueFlag character(len=*), intent(in), optional :: srcMissingValueVar logical, intent(in), optional :: dstMissingValueFlag character(len=*), intent(in), optional :: dstMissingValueVar logical, intent(in), optional :: useSrcCoordFlag character(len=*), intent(in), optional :: srcCoordinateVars(:) logical, intent(in), optional :: useDstCoordFlag character(len=*), intent(in), optional :: dstCoordinateVars(:) logical, intent(in), optional :: useSrcCornerFlag logical, intent(in), optional :: useDstCornerFlag logical, intent(in), optional :: useUserAreaFlag logical, intent(in), optional :: largefileFlag logical, intent(in), optional :: netcdf4fileFlag logical, intent(in), optional :: weightOnlyFlag character(len=*), intent(in), optional :: tileFilePath logical, intent(in), optional :: verboseFlag logical, intent(in), optional :: checkFlag integer, intent(out), optional :: rcDESCRIPTION:
This subroutine provides the same function as the ESMF_RegridWeightGen application described in Section 12. It takes two grid files in NetCDF format and writes out an interpolation weight file also in NetCDF format. The interpolation weights can be generated with the bilinear (24.2.1), higher-order patch (24.2.2), or first order conservative (24.2.5) methods. The grid files can be in one of the following four formats:
The arguments are:
INTERFACE:
! Private name; call using ESMF_RegridWeightGen()
subroutine ESMF_RegridWeightGenDG(srcFile, dstFile, regridRouteHandle, &
srcElementDistgrid, dstElementDistgrid, &
srcNodalDistgrid, dstNodalDistgrid, &
weightFile, regridmethod, lineType, normType, &
extrapMethod, extrapNumSrcPnts, extrapDistExponent, extrapNumLevels,&
unmappedaction, ignoreDegenerate, useUserAreaFlag, &
largefileFlag, netcdf4fileFlag, &
weightOnlyFlag, verboseFlag, rc)
ARGUMENTS:
character(len=*), intent(in) :: srcFile character(len=*), intent(in) :: dstFile type(ESMF_RouteHandle), intent(out) :: regridRouteHandle -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DistGrid), intent(in), optional :: srcElementDistgrid type(ESMF_DistGrid), intent(in), optional :: dstElementDistgrid character(len=*), intent(in), optional :: weightFile type(ESMF_DistGrid), intent(in), optional :: srcNodalDistgrid type(ESMF_DistGrid), intent(in), optional :: dstNodalDistgrid type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod type(ESMF_LineType_Flag), intent(in), optional :: lineType type(ESMF_NormType_Flag), intent(in), optional :: normType type(ESMF_ExtrapMethod_Flag), intent(in), optional :: extrapMethod integer, intent(in), optional :: extrapNumSrcPnts real, intent(in), optional :: extrapDistExponent integer, intent(in), optional :: extrapNumLevels type(ESMF_UnmappedAction_Flag),intent(in), optional :: unmappedaction logical, intent(in), optional :: ignoreDegenerate logical, intent(in), optional :: useUserAreaFlag logical, intent(in), optional :: largefileFlag logical, intent(in), optional :: netcdf4fileFlag logical, intent(in), optional :: weightOnlyFlag logical, intent(in), optional :: verboseFlag integer, intent(out), optional :: rcDESCRIPTION:
This subroutine does online regridding weight generation from files with user specified distribution. The main differences between this API and the one in 24.3.1 are listed below:
The arguments are:
INTERFACE:
subroutine ESMF_FileRegrid(srcFile, dstFile, srcVarName, dstVarName, &
dstLoc, srcDataFile, dstDataFile, tileFilePath, &
dstCoordVars, regridmethod, polemethod, regridPoleNPnts, &
unmappedaction, ignoreDegenerate, srcRegionalFlag, dstRegionalFlag, &
verboseFlag, rc)
ARGUMENTS:
character(len=*), intent(in) :: srcFile character(len=*), intent(in) :: dstFile character(len=*), intent(in) :: srcVarName character(len=*), intent(in) :: dstVarName -- The following arguments require argument keyword syntax (e.g. rc=rc). -- character(len=*), intent(in), optional :: dstLoc character(len=*), intent(in), optional :: srcDataFile character(len=*), intent(in), optional :: dstDataFile character(len=*), intent(in), optional :: tileFilePath character(len=*), intent(in), optional :: dstCoordVars type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod type(ESMF_PoleMethod_Flag), intent(in), optional :: polemethod integer, intent(in), optional :: regridPoleNPnts type(ESMF_UnmappedAction_Flag),intent(in), optional :: unmappedaction logical, intent(in), optional :: ignoreDegenerate logical, intent(in), optional :: srcRegionalFlag logical, intent(in), optional :: dstRegionalFlag logical, intent(in), optional :: verboseFlag integer, intent(out), optional :: rcDESCRIPTION:
This subroutine provides the same function as the ESMF_Regrid application described in Section 13. It takes two grid files in NetCDF format and interpolate the variable defined in the source grid file to the destination variable using one of the ESMF supported regrid methods - bilinear (24.2.1), higher-order patch (24.2.2), first order conservative (24.2.5) or nearest neighbor methods. The grid files can be in one of the following two formats:
The arguments are:
A FieldBundle functions mainly as a convenient container for storing similar Fields. It represents “bundles” of Fields that are discretized on the same Grid, Mesh, LocStream, or XGrid and distributed in the same manner. The FieldBundle is an important data structure because it can be added to a State, which is used for sending and receiving data between Components.
In the common case where FieldBundle is built on top of a Grid, Fields within a FieldBundle may be located at different locations relative to the vertices of their common Grid. The Fields in a FieldBundle may be of different dimensions, as long as the Grid dimensions that are distributed are the same. For example, a surface Field on a distributed lat/lon Grid and a 3D Field with an added vertical dimension on the same distributed lat/lon Grid can be included in the same FieldBundle.
FieldBundles can be created and destroyed, can have Attributes added or retrieved, and can have Fields added, removed, replaced, or retrieved. Methods include queries that return information about the FieldBundle itself and about the Fields that it contains. The Fortran data pointer of a Field within a FieldBundle can be obtained by first retrieving the Field with a call to ESMF_FieldBundleGet(), and then using ESMF_FieldGet() to get the data.
In the future FieldBundles will serve as a mechanism for performance optimization. ESMF will take advantage of the similarities of the Fields within a FieldBundle to optimize collective communication, I/O, and regridding. See Section 25.3 for a description of features that are scheduled for future work.
Examples of creating, accessing and destroying FieldBundles and their constituent Fields are provided in this section, along with some notes on FieldBundle methods.
!-------------------------------------------------------------------------
! ! Create several Fields and add them to a new FieldBundle.
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/100,200/), &
regDecomp=(/2,2/), name="atmgrid", rc=rc)
call ESMF_ArraySpecSet(arrayspec, 2, ESMF_TYPEKIND_R8, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field(1) = ESMF_FieldCreate(grid, arrayspec, &
staggerloc=ESMF_STAGGERLOC_CENTER, &
name="temperature", rc=rc)
field(2) = ESMF_FieldCreate(grid, arrayspec, &
staggerloc=ESMF_STAGGERLOC_CENTER, &
name="pressure", rc=rc)
field(3) = ESMF_FieldCreate(grid, arrayspec, &
staggerloc=ESMF_STAGGERLOC_CENTER, &
name="heat flux", rc=rc)
bundle1 = ESMF_FieldBundleCreate(fieldList=field(1:3), &
name="atmosphere data", rc=rc)
print *, "FieldBundle example 1 returned"
!-------------------------------------------------------------------------
! ! Create an empty FieldBundle and then add a single field to it.
simplefield = ESMF_FieldCreate(grid, arrayspec, &
staggerloc=ESMF_STAGGERLOC_CENTER, name="rh", rc=rc)
bundle2 = ESMF_FieldBundleCreate(name="time step 1", rc=rc)
call ESMF_FieldBundleAdd(bundle2, (/simplefield/), rc=rc)
call ESMF_FieldBundleGet(bundle2, fieldCount=fieldcount, rc=rc)
print *, "FieldBundle example 2 returned, fieldcount =", fieldcount
!-------------------------------------------------------------------------
! ! Create an empty FieldBundle and then add multiple fields to it.
bundle3 = ESMF_FieldBundleCreate(name="southern hemisphere", rc=rc)
call ESMF_FieldBundleAdd(bundle3, field(1:3), rc=rc)
call ESMF_FieldBundleGet(bundle3, fieldCount=fieldcount, rc=rc)
print *, "FieldBundle example 3 returned, fieldcount =", fieldcount
!-------------------------------------------------------------------------
! ! Get a Field back from a FieldBundle, first by name and then by index.
! ! Also get the FieldBundle name.
call ESMF_FieldBundleGet(bundle1, "pressure", field=returnedfield1, rc=rc)
call ESMF_FieldGet(returnedfield1, name=fname1, rc=rc)
call ESMF_FieldBundleGet(bundle1, 2, returnedfield2, rc=rc)
call ESMF_FieldGet(returnedfield2, name=fname2, rc=rc)
call ESMF_FieldBundleGet(bundle1, name=bname1, rc=rc)
print *, "FieldBundle example 4 returned, field names = ", &
trim(fname1), ", ", trim(fname2)
print *, "FieldBundle name = ", trim(bname1)
call ESMF_FieldBundleGet(bundle1, fieldList=r_fields, rc=rc)
do i = 1, 3
call ESMF_FieldGet(r_fields(i), name=fname1, rc=rc)
print *, fname1
enddo
call ESMF_FieldBundleGet(bundle1, fieldList=r_fields, &
itemorderflag=ESMF_ITEMORDER_ADDORDER, rc=rc)
do i = 1, 3
call ESMF_FieldGet(r_fields(i), name=fname1, rc=rc)
print *, fname1
enddo
Create a 2D grid of 4x1 regular decomposition on 4 PETs, each PET has 10x50 elements. The index space of the entire Grid is 40x50.
gridxy = ESMF_GridCreateNoPeriDim(maxIndex=(/40,50/), regDecomp=(/4,1/), rc=rc)
Allocate a packed Fortran array pointer containing 10 packed fields, each field has 3 time slices and uses the 2D grid created. Note that gridToFieldMap uses the position of the grid dimension as elements, 3rd element of the packedPtr is 10, 4th element of the packedPtr is 50.
allocate(packedPtr(10, 3, 10, 50)) ! fieldDim, time, y, x fieldDim = 1 packedFB = ESMF_FieldBundleCreate(fieldNameList, packedPtr, gridxy, fieldDim, & gridToFieldMap=(/3,4/), staggerloc=ESMF_Staggerloc_Center, rc=rc)
Due to the verbosity of the MeshCreate process, the code for MeshCreate is not shown below, user can either refer to the MeshCreate section 33.3.1 or examine the FieldBundleCreate example source code contained in the ESMF source distribution directly. A ESMF Mesh on 4 PETs with one mesh element on each PET is created.
Allocate the packed Fortran array pointer, the first dimension is fieldDim; second dimension is the data associated with mesh element, since there is only one mesh element on each processor in this example, the allocation is 1; last dimension is the time dimension which contains 3 time slices.
allocate(packedPtr3D(10, 1, 3))
fieldDim = 1
packedFB = ESMF_FieldBundleCreate(fieldNameList, packedPtr3D, meshEx, fieldDim, &
gridToFieldMap=(/2/), meshloc=ESMF_MESHLOC_ELEMENT, rc=rc)
The user must call ESMF_FieldBundleDestroy() before deleting any of the Fields it contains. Because Fields can be shared by multiple FieldBundles and States, they are not deleted by this call.
!-------------------------------------------------------------------------
call ESMF_FieldBundleDestroy(bundle1, rc=rc)
The ESMF_FieldBundleRedist interface can be used to redistribute data from source FieldBundle to destination FieldBundle. This interface is overloaded by type and kind; In the version of ESMF_FieldBundleRedist without factor argument, a default value of factor 1 is used.
In this example, we first create two FieldBundles, a source FieldBundle and a destination FieldBundle. Then we use ESMF_FieldBundleRedist to redistribute data from source FieldBundle to destination FieldBundle.
! perform redist
call ESMF_FieldBundleRedistStore(srcFieldBundle, dstFieldBundle, &
routehandle, rc=rc)
call ESMF_FieldBundleRedist(srcFieldBundle, dstFieldBundle, &
routehandle, rc=rc)
The ESMF_FieldBundleRedist interface can be used to redistribute data from source FieldBundle to destination FieldBundle when both Bundles are packed with same number of fields.
In this example, we first create two packed FieldBundles, a source FieldBundle and a destination FieldBundle. Then we use ESMF_FieldBundleRedist to redistribute data from source FieldBundle to destination FieldBundle.
The same Grid is used where the source and destination packed FieldBundle are built upon. Source and destination Bundle have different memory layout.
allocate(srcfptr(3,5,10), dstfptr(10,5,3))
srcfptr = lpe
srcFieldBundle = ESMF_FieldBundleCreate((/'field01', 'field02', 'field03'/), &
srcfptr, grid, 1, gridToFieldMap=(/2,3/), rc=rc)
dstFieldBundle = ESMF_FieldBundleCreate((/'field01', 'field02', 'field03'/), &
dstfptr, grid, 3, gridToFieldMap=(/2,1/), rc=rc)
! perform redist
call ESMF_FieldBundleRedistStore(srcFieldBundle, dstFieldBundle, &
routehandle, rc=rc)
call ESMF_FieldBundleRedist(srcFieldBundle, dstFieldBundle, &
routehandle, rc=rc)
The ESMF_FieldBundleSMM interface can be used to perform SMM from source FieldBundle to destination FieldBundle. This interface is overloaded by type and kind;
In this example, we first create two FieldBundles, a source FieldBundle and a destination FieldBundle. Then we use ESMF_FieldBundleSMM to perform sparse matrix multiplication from source FieldBundle to destination FieldBundle.
The operation performed in this example is better illustrated in section 26.3.33.
Section 28.2.18 provides a detailed discussion of the sparse matrix multiplication operation implemented in ESMF.
call ESMF_VMGetCurrent(vm, rc=rc)
call ESMF_VMGet(vm, localPet=lpe, rc=rc)
! create distgrid and grid
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/16/), &
regDecomp=(/4/), &
rc=rc)
grid = ESMF_GridCreate(distgrid=distgrid, &
gridEdgeLWidth=(/0/), gridEdgeUWidth=(/0/), &
name="grid", rc=rc)
call ESMF_ArraySpecSet(arrayspec, 1, ESMF_TYPEKIND_I4, rc=rc)
! create field bundles and fields
srcFieldBundle = ESMF_FieldBundleCreate(rc=rc)
dstFieldBundle = ESMF_FieldBundleCreate(rc=rc)
do i = 1, 3
srcField(i) = ESMF_FieldCreate(grid, arrayspec, &
totalLWidth=(/1/), totalUWidth=(/2/), &
rc=rc)
call ESMF_FieldGet(srcField(i), localDe=0, farrayPtr=srcfptr, rc=rc)
srcfptr = 1
call ESMF_FieldBundleAdd(srcFieldBundle, (/srcField(i)/), rc=rc)
dstField(i) = ESMF_FieldCreate(grid, arrayspec, &
totalLWidth=(/1/), totalUWidth=(/2/), &
rc=rc)
call ESMF_FieldGet(dstField(i), localDe=0, farrayPtr=dstfptr, rc=rc)
dstfptr = 0
call ESMF_FieldBundleAdd(dstFieldBundle, (/dstField(i)/), rc=rc)
enddo
! initialize factorList and factorIndexList
allocate(factorList(4))
allocate(factorIndexList(2,4))
factorList = (/1,2,3,4/)
factorIndexList(1,:) = (/lpe*4+1,lpe*4+2,lpe*4+3,lpe*4+4/)
factorIndexList(2,:) = (/lpe*4+1,lpe*4+2,lpe*4+3,lpe*4+4/)
call ESMF_FieldBundleSMMStore(srcFieldBundle, dstFieldBundle, &
routehandle, factorList, factorIndexList, rc=rc)
! perform smm
call ESMF_FieldBundleSMM(srcFieldBundle, dstFieldBundle, routehandle, &
rc=rc)
! release SMM route handle
call ESMF_FieldBundleSMMRelease(routehandle, rc=rc)
ESMF_FieldBundleHalo interface can be used to perform halo updates for all the Fields contained in the ESMF_FieldBundle.
In this example, we will set up a FieldBundle for a 2D inviscid and compressible flow problem. We will illustrate the FieldBundle halo update operation but we will not solve the non-linear PDEs. The emphasis here is to demonstrate how to set up halo regions, how a numerical scheme updates the exclusive regions, and how a halo update communicates data in the halo regions. Here are the governing equations:
(conservation of momentum in x-direction)
(conservation of momentum in y-direction)
(conservation of mass)
(conservation of energy)
The four unknowns are pressure 
, density 
, velocity (
, 
). The grids
are set up using Arakawa D stagger ( on corner, at center, and on edges).
, , , and are bounded by necessary boundary conditions and initial conditions.
Section 28.2.15 provides a detailed discussion of the halo operation implemented in ESMF.
! create distgrid and grid according to the following decomposition
! and stagger pattern, r is density.
!
! p--------u-------+p+-------u--------p
! ! | |
! ! | |
! ! | |
! v r v r v
! ! PET 0 | PET 1 |
! ! | |
! ! | |
! p--------u-------+p+-------u--------p
! ! | |
! ! | |
! ! | |
! v r v r v
! ! PET 2 | PET 3 |
! ! | |
! ! | |
! p--------u-------+p+-------u--------p
!
distgrid = ESMF_DistGridCreate(minIndex=(/1,1/), maxIndex=(/256,256/), &
regDecomp=(/2,2/), &
rc=rc)
grid = ESMF_GridCreate(distgrid=distgrid, name="grid", rc=rc)
call ESMF_ArraySpecSet(arrayspec, 2, ESMF_TYPEKIND_R4, rc=rc)
! create field bundles and fields
fieldBundle = ESMF_FieldBundleCreate(rc=rc)
! set up exclusive/total region for the fields
!
! halo: L/U, nDim, nField, nPet
! halo configuration for pressure, and similarly for density, u, and v
halo(1,1,1,1) = 0
halo(2,1,1,1) = 0
halo(1,2,1,1) = 0
halo(2,2,1,1) = 0
halo(1,1,1,2) = 1 ! halo in x direction on left hand side of pet 1
halo(2,1,1,2) = 0
halo(1,2,1,2) = 0
halo(2,2,1,2) = 0
halo(1,1,1,3) = 0
halo(2,1,1,3) = 1 ! halo in y direction on upper side of pet 2
halo(1,2,1,3) = 0
halo(2,2,1,3) = 0
halo(1,1,1,4) = 1 ! halo in x direction on left hand side of pet 3
halo(2,1,1,4) = 1 ! halo in y direction on upper side of pet 3
halo(1,2,1,4) = 0
halo(2,2,1,4) = 0
! names and staggers of the 4 unknown fields
names(1) = "pressure"
names(2) = "density"
names(3) = "u"
names(4) = "v"
staggers(1) = ESMF_STAGGERLOC_CORNER
staggers(2) = ESMF_STAGGERLOC_CENTER
staggers(3) = ESMF_STAGGERLOC_EDGE2
staggers(4) = ESMF_STAGGERLOC_EDGE1
! create a FieldBundle
lpe = lpe + 1
do i = 1, 4
field(i) = ESMF_FieldCreate(grid, arrayspec, &
totalLWidth=(/halo(1,1,i,lpe), halo(1,2,i,lpe)/), &
totalUWidth=(/halo(2,1,i,lpe), halo(2,2,i,lpe)/), &
staggerloc=staggers(i), name=names(i), &
rc=rc)
call ESMF_FieldBundleAdd(fieldBundle, (/field(i)/), rc=rc)
enddo
! compute the routehandle
call ESMF_FieldBundleHaloStore(fieldBundle, routehandle=routehandle, &
rc=rc)
do iter = 1, 10
do i = 1, 4
call ESMF_FieldGet(field(i), farrayPtr=fptr, &
exclusiveLBound=excllb, exclusiveUBound=exclub, rc=rc)
sizes = exclub - excllb
! fill the total region with 0.
fptr = 0.
! only update the exclusive region on local PET
do j = excllb(1), exclub(1)
do k = excllb(2), exclub(2)
fptr(j,k) = iter * cos(2.*PI*j/sizes(1))*sin(2.*PI*k/sizes(2))
enddo
enddo
enddo
! call halo execution to update the data in the halo region,
! it can be verified that the halo regions change from 0.
! to non zero values.
call ESMF_FieldBundleHalo(fieldbundle, routehandle=routehandle, rc=rc)
enddo
! release halo route handle
call ESMF_FieldBundleHaloRelease(routehandle, rc=rc)
CAUTION: For communication methods, the undistributed dimension representing the number of fields must have identical size between source and destination packed data. Communication methods do not permute the order of fields in the source and destination packed FieldBundle.
INTERFACE:
interface assignment(=) fieldbundle1 = fieldbundle2ARGUMENTS:
type(ESMF_FieldBundle) :: fieldbundle1 type(ESMF_FieldBundle) :: fieldbundle2STATUS:
DESCRIPTION:
Assign fieldbundle1 as an alias to the same ESMF fieldbundle object in memory as fieldbundle2. If fieldbundle2 is invalid, then fieldbundle1 will be equally invalid after the assignment.
The arguments are:
INTERFACE:
interface operator(==) if (fieldbundle1 == fieldbundle2) then ... endif OR result = (fieldbundle1 == fieldbundle2)RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle1 type(ESMF_FieldBundle), intent(in) :: fieldbundle2STATUS:
DESCRIPTION:
Test whether fieldbundle1 and fieldbundle2 are valid aliases to the same ESMF fieldbundle object in memory. For a more general comparison of two ESMF FieldBundles, going beyond the simple alias test, the ESMF_FieldBundleMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
interface operator(/=) if (fieldbundle1 /= fieldbundle2) then ... endif OR result = (fieldbundle1 /= fieldbundle2)RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle1 type(ESMF_FieldBundle), intent(in) :: fieldbundle2STATUS:
DESCRIPTION:
Test whether fieldbundle1 and fieldbundle2 are not valid aliases to the same ESMF fieldbundle object in memory. For a more general comparison of two ESMF FieldBundles, going beyond the simple alias test, the ESMF_FieldBundleMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleAdd()
subroutine ESMF_FieldBundleAddList(fieldbundle, fieldList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_Field), intent(in) :: fieldList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Add Field(s) to a FieldBundle. It is an error if fieldList contains Fields that match by name Fields already contained in fieldbundle when multiflag is set to .false. and relaxedflag is set to .false..
INTERFACE:
subroutine ESMF_FieldBundleAddReplace(fieldbundle, fieldList, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_Field), intent(in) :: fieldList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Fields in fieldList that do not match any Fields by name in fieldbundle are added to the FieldBundle. Fields in fieldList that match any Fields by name in fieldbundle replace those Fields.
INTERFACE:
! Private name; call using ESMF_FieldBundleCreate()
function ESMF_FieldBundleCreateDefault(fieldList, &
multiflag, relaxedflag, name, rc)
RETURN VALUE:
type(ESMF_FieldBundle) :: ESMF_FieldBundleCreateDefaultARGUMENTS:
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Field), intent(in), optional :: fieldList(:)
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
character (len=*),intent(in), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Create an ESMF_FieldBundle object from a list of existing Fields.
The creation of a FieldBundle leaves the bundled Fields unchanged, they remain valid individual objects. a FieldBundle is a light weight container of Field references. The actual data remains in place, there are no data movements or duplications associated with the creation of an FieldBundle.
INTERFACE:
! Private name; call using ESMF_FieldBundleCreate() function ESMF_FieldBundleCreateGrid<rank><type><kind>(fieldNameList, & farrayPtr, grid, fieldDim, & indexflag, staggerLoc, & gridToFieldMap, & totalLWidth, totalUWidth, name, rc)RETURN VALUE:
type(ESMF_FieldBundle) :: ESMF_FieldBundleCreateGridDataPtr<rank><type><kind>ARGUMENTS:
character(len=*), intent(in) :: fieldNameList(:) <type> (ESMF_KIND_<kind>), dimension(<rank>), pointer :: farrayPtr type(ESMF_Grid), intent(in) :: grid integer, intent(in) :: fieldDim -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_Index_Flag), intent(in), optional :: indexflag type(ESMF_StaggerLoc), intent(in), optional :: staggerloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create a packed FieldBundle from user supplied list of field names, pre-allocated Fortran array pointer, and ESMF_Grid object.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleCreate() function ESMF_FieldBundleCreateMesh<rank><type><kind>(fieldNameList, & farrayPtr, Mesh, fieldDim, & meshLoc, gridToFieldMap, name, rc)RETURN VALUE:
type(ESMF_FieldBundle) :: ESMF_FieldBundleCreateMeshDataPtr<rank><type><kind>ARGUMENTS:
character(len=*), intent(in) :: fieldNameList(:) <type> (ESMF_KIND_<kind>), dimension(<rank>), pointer :: farrayPtr type(ESMF_Mesh), intent(in) :: mesh integer, intent(in) :: fieldDim -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_MeshLoc), intent(in), optional:: meshloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create a packed FieldBundle from user supplied list of field names, pre-allocated Fortran array pointer, and ESMF_Mesh object.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleDestroy(fieldbundle, noGarbage, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Destroy an ESMF_FieldBundle object. The member Fields are not touched by this operation and remain valid objects that need to be destroyed individually if necessary.
The arguments are:
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldBundleGet()
subroutine ESMF_FieldBundleGetListAll(fieldbundle, &
itemorderflag, geomtype, grid, locstream, mesh, xgrid, &
fieldCount, fieldList, fieldNameList, isPacked, name, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_ItemOrder_Flag), intent(in), optional :: itemorderflag
type(ESMF_GeomType_Flag), intent(out), optional :: geomtype
type(ESMF_Grid), intent(out), optional :: grid
type(ESMF_LocStream), intent(out), optional :: locstream
type(ESMF_Mesh), intent(out), optional :: mesh
type(ESMF_XGrid), intent(out), optional :: xgrid
integer, intent(out), optional :: fieldCount
type(ESMF_Field), intent(out), optional :: fieldList(:)
character(len=*), intent(out), optional :: fieldNameList(:)
logical, intent(out), optional :: isPacked
character(len=*), intent(out), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get the list of all Fields and field names bundled in a FieldBundle.
INTERFACE:
! Private name; call using ESMF_FieldBundleGet()
subroutine ESMF_FieldBundleGetItem(fieldbundle, fieldName, &
field, fieldCount, isPresent, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
character(len=*), intent(in) :: fieldName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Field), intent(out), optional :: field
integer, intent(out), optional :: fieldCount
logical, intent(out), optional :: isPresent
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get information about items that match fieldName in FieldBundle.
INTERFACE:
! Private name; call using ESMF_FieldBundleGet()
subroutine ESMF_FieldBundleGetList(fieldbundle, fieldName, fieldList, &
itemorderflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
character(len=*), intent(in) :: fieldName
type(ESMF_Field), intent(out) :: fieldList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_ItemOrder_Flag), intent(in), optional :: itemorderflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get the list of Fields from fieldbundle that match fieldName.
INTERFACE:
! Private name; call using ESMF_FieldBundleGet() function ESMF_FieldBundleGetDataPtr<rank><type><kind>(fieldBundle, & localDe, farrayPtr, & rc)RETURN VALUE:
type(ESMF_FieldBundle) :: ESMF_FieldBundleGetDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldBundle integer, intent(in), optional :: localDe <type> (ESMF_KIND_<kind>), dimension(<rank>), pointer :: farrayPtr -- The following arguments require argument keyword syntax (e.g. rc=rc). -- integer, intent(out), optional :: rcDESCRIPTION:
Get a Fortran pointer to DE-local memory allocation within packed FieldBundle. It's erroneous to perform this call on a FieldBundle that's not packed.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleHalo(fieldbundle, routehandle, &
checkflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed halo operation for the Fields in fieldbundle. The FieldBundle must match the respective FieldBundle used during ESMF_FieldBundleHaloStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
See ESMF_FieldBundleHaloStore() on how to precompute routehandle.
INTERFACE:
subroutine ESMF_FieldBundleHaloRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a FieldBundle halo operation. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
subroutine ESMF_FieldBundleHaloStore(fieldbundle, routehandle, &
rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a FieldBundle halo operation over the data in fieldbundle. By definition, all elements in the total Field regions that lie outside the exclusive regions will be considered potential destination elements for the halo operation. However, only those elements that have a corresponding halo source element, i.e. an exclusive element on one of the DEs, will be updated under the halo operation. Elements that have no associated source remain unchanged under halo.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleHalo() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
INTERFACE:
function ESMF_FieldBundleIsCreated(fieldbundle, rc)RETURN VALUE:
logical :: ESMF_FieldBundleIsCreatedARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Return .true. if the fieldbundle has been created. Otherwise return .false.. If an error occurs, i.e. rc /= ESMF_SUCCESS is returned, the return value of the function will also be .false..
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundlePrint(fieldbundle, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Print internal information of the specified fieldbundle object.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleRead(fieldbundle, fileName, &
singleFile, timeslice, iofmt, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
character(*), intent(in) :: fileName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: singleFile
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
DESCRIPTION:
Read field data to a FieldBundle object from file(s). For this API to be functional, the environment variable ESMF_PIO should be set to either "internal" or "external" when the ESMF library is built. Please see the section on Data I/O, 38.2.
Limitations:
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleRedist(srcFieldBundle, dstFieldBundle, &
routehandle, checkflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in), optional :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout), optional :: dstFieldBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed redistribution from srcFieldBundle to dstFieldBundle. Both srcFieldBundle and dstFieldBundle must match the respective FieldBundles used during ESMF_FieldBundleRedistStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcFieldBundle and dstFieldBundle arguments are optional in support of the situation where srcFieldBundle and/or dstFieldBundle are not defined on all PETs. The srcFieldBundle and dstFieldBundle must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
See ESMF_FieldBundleRedistStore() on how to precompute routehandle.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.9.
INTERFACE:
subroutine ESMF_FieldBundleRedistRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a FieldBundle redistribution. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldBundleRedistStore() subroutine ESMF_FieldBundleRedistStore<type><kind>(srcFieldBundle, & dstFieldBundle, routehandle, factor, & ignoreUnmatchedIndicesFlag, srcToDstTransposeMap, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle type(ESMF_RouteHandle), intent(inout) :: routehandle <type>(ESMF_KIND_<kind>), intent(in) :: factor -- The following arguments require argument keyword syntax (e.g. rc=rc). -- logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:) integer, intent(in), optional :: srcToDstTransposeMap(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Store a FieldBundle redistribution operation from srcFieldBundle to dstFieldBundle. PETs that specify a factor argument must use the <type><kind> overloaded interface. Other PETs call into the interface without factor argument. If multiple PETs specify the factor argument its type and kind as well as its value must match across all PETs. If none of the PETs specifies a factor argument the default will be a factor of 1.
Both srcFieldBundle and dstFieldBundle are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. Redistribution corresponds to an identity mapping of the source FieldBundle vector to the destination FieldBundle vector.
Source and destination FieldBundles may be of different <type><kind>. Further source and destination FieldBundles may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleRedist() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.9.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleRedistStore()
subroutine ESMF_FieldBundleRedistStoreNF(srcFieldBundle, dstFieldBundle, &
routehandle, ignoreUnmatchedIndicesFlag, &
srcToDstTransposeMap, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:)
integer, intent(in), optional :: srcToDstTransposeMap(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a FieldBundle redistribution operation from srcFieldBundle to dstFieldBundle. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcFieldBundle and dstFieldBundle are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. Redistribution corresponds to an identity mapping of the source FieldBundle vector to the destination FieldBundle vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleRedist() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.9.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleRegrid(srcFieldBundle, dstFieldBundle, &
routehandle, zeroregion, termorderflag, checkflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in), optional :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout), optional :: dstFieldBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Region_Flag), intent(in), optional :: zeroregion
type(ESMF_TermOrder_Flag), intent(in), optional :: termorderflag(:)
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed regrid from srcFieldBundle to dstFieldBundle. Both srcFieldBundle and dstFieldBundle must match the respective FieldBundles used during ESMF_FieldBundleRedistStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcFieldBundle and dstFieldBundle arguments are optional in support of the situation where srcFieldBundle and/or dstFieldBundle are not defined on all PETs. The srcFieldBundle and dstFieldBundle must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
See ESMF_FieldBundleRegridStore() on how to precompute routehandle.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_FieldBundleRegridRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a FieldBundle regrid operation. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
subroutine ESMF_FieldBundleRegridStore(srcFieldBundle, dstFieldBundle, &
srcMaskValues, dstMaskValues, regridmethod, polemethod, regridPoleNPnts, &
lineType, normType, extrapMethod, extrapNumSrcPnts, extrapDistExponent, &
extrapNumLevels, unmappedaction, ignoreDegenerate, srcTermProcessing, &
pipelineDepth, routehandle, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer(ESMF_KIND_I4), target, intent(in), optional :: srcMaskValues(:)
integer(ESMF_KIND_I4), target, intent(in), optional :: dstMaskValues(:)
type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod
type(ESMF_PoleMethod_Flag), intent(in), optional :: polemethod
integer, intent(in), optional :: regridPoleNPnts
type(ESMF_LineType_Flag), intent(in), optional :: lineType
type(ESMF_NormType_Flag), intent(in), optional :: normType
type(ESMF_ExtrapMethod_Flag), intent(in), optional :: extrapMethod
integer, intent(in), optional :: extrapNumSrcPnts
real, intent(in), optional :: extrapDistExponent
integer, intent(in), optional :: extrapNumLevels
type(ESMF_UnmappedAction_Flag),intent(in), optional :: unmappedaction
logical, intent(in), optional :: ignoreDegenerate
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipelineDepth
type(ESMF_RouteHandle), intent(inout), optional :: routehandle
integer, intent(out), optional :: rc
STATUS:
Added arguments extrapMethod, extrapNumSrcPnts, and extrapDistExponent. These three new extrapolation arguments allow the user to extrapolate destination points not mapped by the regrid method. extrapMethod allows the user to choose the extrapolation method. extrapNumSrcPnts and extrapDistExponent are parameters that allow the user to tune the behavior of the ESMF_EXTRAPMETHOD_NEAREST_IDAVG method.
DESCRIPTION:
Store a FieldBundle regrid operation over the data in srcFieldBundle and dstFieldBundle pair.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleRegrid() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument 
is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is 
, the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
subroutine ESMF_FieldBundleRemove(fieldbundle, fieldNameList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
character(len=*), intent(in) :: fieldNameList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Remove field(s) by name from FieldBundle. In the relaxed setting it is not an error if fieldNameList contains names that are not found in fieldbundle.
INTERFACE:
subroutine ESMF_FieldBundleReplace(fieldbundle, fieldList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_Field), intent(in) :: fieldList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Replace field(s) by name in FieldBundle. In the relaxed setting it is not an error if fieldList contains Fields that do not match by name any item in fieldbundle. These Fields are simply ignored in this case.
INTERFACE:
! Private name; call using ESMF_FieldBundleSet()
subroutine ESMF_FieldBundleSetGrid(fieldbundle, grid, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_Grid), intent(in) :: grid
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Sets the grid for a fieldbundle.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleSet()
subroutine ESMF_FieldBundleSetMesh(fieldbundle, mesh, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_Mesh), intent(in) :: mesh
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Sets the mesh for a fieldbundle.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleSet()
subroutine ESMF_FieldBundleSetLS(fieldbundle, locstream, &
rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_LocStream), intent(in) :: locstream
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Sets the locstream for a fieldbundle.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleSet()
subroutine ESMF_FieldBundleSetXGrid(fieldbundle, xgrid, &
rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(inout) :: fieldbundle
type(ESMF_XGrid), intent(in) :: xgrid
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Sets the xgrid for a fieldbundle
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleSMM(srcFieldBundle, dstFieldBundle, &
routehandle, &
zeroregion, & ! DEPRECATED ARGUMENT
zeroregionflag, termorderflag, checkflag, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in), optional :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout), optional :: dstFieldBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Region_Flag), intent(in), optional :: zeroregion ! DEPRECATED ARGUMENT
type(ESMF_Region_Flag), intent(in), target, optional :: zeroregionflag(:)
type(ESMF_TermOrder_Flag), intent(in), optional :: termorderflag(:)
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed sparse matrix multiplication from srcFieldBundle to dstFieldBundle. Both srcFieldBundle and dstFieldBundle must match the respective FieldBundles used during ESMF_FieldBundleRedistStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcFieldBundle and dstFieldBundle arguments are optional in support of the situation where srcFieldBundle and/or dstFieldBundle are not defined on all PETs. The srcFieldBundle and dstFieldBundle must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
See ESMF_FieldBundleSMMStore() on how to precompute routehandle.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.11.
INTERFACE:
subroutine ESMF_FieldBundleSMMRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a FieldBundle sparse matrix multiplication. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldBundleSMMStore() subroutine ESMF_FieldBundleSMMStore<type><kind>(srcFieldBundle, & dstFieldBundle, routehandle, factorList, factorIndexList, & ignoreUnmatchedIndicesFlag, srcTermProcessing, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle type(ESMF_RouteHandle), intent(inout) :: routehandle <type>(ESMF_KIND_<kind>), intent(in) :: factorList(:) integer, intent(in), :: factorIndexList(:,:) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:) integer, intent(inout), optional :: srcTermProcessing(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Store a FieldBundle sparse matrix multiplication operation from srcFieldBundle to dstFieldBundle. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcFieldBundle and dstFieldBundle are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source FieldBundle vector to the destination FieldBundle vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleSMM() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.11.
The arguments are:
The second dimension of factorIndexList steps through the list of pairs, i.e. size(factorIndexList,2) == size(factorList). The first dimension of factorIndexList is either of size 2 or size 4.
In the size 2 format factorIndexList(1,:) specifies the sequence index of the source element in the srcFieldBundle while factorIndexList(2,:) specifies the sequence index of the destination element in dstFieldBundle. For this format to be a valid option source and destination FieldBundles must have matching number of tensor elements (the product of the sizes of all Field tensor dimensions). Under this condition an identity matrix can be applied within the space of tensor elements for each sparse matrix factor.
The size 4 format is more general and does not require a matching tensor element count. Here the
factorIndexList(1,:) specifies the sequence index while factorIndexList(2,:) specifies the tensor sequence index of the source element in the srcFieldBundle. Further factorIndexList(3,:) specifies the sequence index and factorIndexList(4,:) specifies the tensor sequence index of the destination element in the dstFieldBundle.
See section 28.2.18 for details on the definition of sequence indices and tensor sequence indices.
INTERFACE:
! Private name; call using ESMF_FieldBundleSMMStore()
subroutine ESMF_FieldBundleSMMStoreNF(srcFieldBundle, dstFieldBundle, &
routehandle, ignoreUnmatchedIndicesFlag, &
srcTermProcessing, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:)
integer, intent(inout), optional :: srcTermProcessing(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a FieldBundle sparse matrix multiplication operation from srcFieldBundle to dstFieldBundle. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcFieldBundle and dstFieldBundle are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source FieldBundle vector to the destination FieldBundle vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical FieldBundle object for srcFieldBundle and dstFieldBundle arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldBundleSMM() on any pair of FieldBundles that matches srcFieldBundle and dstFieldBundle in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8, ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 25.2.11.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldBundleSMMStore()
subroutine ESMF_FieldBundleSMMStoreFromFile(srcFieldBundle, dstFieldBundle, &
filename, routehandle, ignoreUnmatchedIndicesFlag, &
srcTermProcessing, rc)
! ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: srcFieldBundle
type(ESMF_FieldBundle), intent(inout) :: dstFieldBundle
character(len=*), intent(in) :: filename
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:)
integer, intent(inout), optional :: srcTermProcessing(:)
integer, intent(out), optional :: rc
DESCRIPTION:
Compute an ESMF_RouteHandle using factors read from file.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleValidate(fieldbundle, rc)ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
integer, intent(out), optional :: rc
DESCRIPTION:
Validates that the fieldbundle is internally consistent. The method returns an error code if problems are found.
The arguments are:
INTERFACE:
subroutine ESMF_FieldBundleWrite(fieldbundle, fileName, &
convention, purpose, singleFile, overwrite, status, timeslice, iofmt, rc)
ARGUMENTS:
type(ESMF_FieldBundle), intent(in) :: fieldbundle
character(*), intent(in) :: fileName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character(*), intent(in), optional :: convention
character(*), intent(in), optional :: purpose
logical, intent(in), optional :: singleFile
logical , intent(in), optional :: overwrite
type(ESMF_FileStatus_Flag), intent(in), optional :: status
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
DESCRIPTION:
Write the Fields into a file. For this API to be functional, the environment variable ESMF_PIO should be set to either "internal" or "external" when the ESMF library is built. Please see the section on Data I/O, 38.2.
When convention and purpose arguments are specified, NetCDF dimension labels and variable attributes are written from each Field in the FieldBundle from the corresponding Attribute package. Additionally, Attributes may be set on the FieldBundle level under the same Attribute package. This allows the specification of global attributes within the file. As with individual Fields, the value associated with each name may be either a scalar character string, or a scalar or array of type integer, real, or double precision.
Limitations:
The arguments are:
An ESMF Field represents a physical field, such as temperature. The motivation for including Fields in ESMF is that bundles of Fields are the entities that are normally exchanged when coupling Components.
The ESMF Field class contains distributed and discretized field data, a reference to its associated grid, and metadata. The Field class stores the grid staggering for that physical field. This is the relationship of how the data array of a field maps onto a grid (e.g. one item per cell located at the cell center, one item per cell located at the NW corner, one item per cell vertex, etc.). This means that different Fields which are on the same underlying ESMF Grid but have different staggerings can share the same Grid object without needing to replicate it multiple times.
Fields can be added to States for use in inter-Component data communications. Fields can also be added to FieldBundles, which are groups of Fields on the same underlying Grid. One motivation for packing Fields into FieldBundles is convenience; another is the ability to perform optimized collective data transfers.
Field communication capabilities include: data redistribution, regridding, scatter, gather, sparse-matrix multiplication, and halo update. These are discussed in more detail in the documentation for the specific method calls. ESMF does not currently support vector fields, so the components of a vector field must be stored as separate Field objects.
The Field class allows the user to easily perform a number of operations on the data stored in a Field. This section gives a brief summary of the different types of operations and the range of their capabilities. The operations covered here are: redistribution (ESMF_FieldRedistStore()), sparse matrix multiply (ESMF_FieldSMMStore()), and regridding (ESMF_FieldRegridStore()).
The redistribution operation (ESMF_FieldRedistStore()) allows the user to move data between two Fields with the same size, but different distribution. This operation is useful, for example, to move data between two components with different distributions. Please see Section 26.3.30 for an example of the redistribution capability.
The sparse matrix multiplication operation (ESMF_FieldSMMStore()) allows the user to multiply the data in a Field by a sparse matrix. This operation is useful, for example, if the user has an interpolation matrix and wants to apply it to the data in a Field. Please see Section 26.3.33 for an example of the sparse matrix multiply capability.
The regridding operation (ESMF_FieldRegridStore()) allows the user to move data from one grid to another while maintaining certain properties of the data. Regridding is also called interpolation or remapping. In the Field regridding operation the grids the data is being moved between are the grids associated with the Fields storing the data. The regridding operation works on Fields built on Meshes, Grids, or Location Streams. There are six regridding methods available: bilinear, higher-order patch, two types of nearest neighbor, first-order conservative, and second-order conservative. Please see section 24.2 for a more indepth description of regridding including in which situations each method is supported. Please see section 26.3.25 for a description of the regridding capability as it applies to Fields. Several sections following section 26.3.25 contain examples of using regridding.
DESCRIPTION:
An ESMF_Field can be in different status after initialization. Field status can be queried using ESMF_FieldGet() method.
The type of this flag is:
type(ESMF_FieldStatus_Flag)
The valid values are:
A Field serves as an annotator of data, since it carries a description of the grid it is associated with and metadata such as name and units. Fields can be used in this capacity alone, as convenient, descriptive containers into which arrays can be placed and retrieved. However, for most codes the primary use of Fields is in the context of import and export States, which are the objects that carry coupling information between Components. Fields enable data to be self-describing, and a State holding ESMF Fields contains data in a standard format that can be queried and manipulated.
The sections below go into more detail about Field usage.
Fields can be created and destroyed at any time during application execution. However, these Field methods require some time to complete. We do not recommend that the user create or destroy Fields inside performance-critical computational loops.
All versions of the ESMF_FieldCreate() routines require a Grid object as input, or require a Grid be added before most operations involving Fields can be performed. The Grid contains the information needed to know which Decomposition Elements (DEs) are participating in the processing of this Field, and which subsets of the data are local to a particular DE.
The details of how the create process happens depend on which of the variants of the ESMF_FieldCreate() call is used. Some of the variants are discussed below.
There are versions of the ESMF_FieldCreate() interface which create the Field based on the input Grid. The ESMF can allocate the proper amount of space but not assign initial values. The user code can then get the pointer to the uninitialized buffer and set the initial data values.
Other versions of the ESMF_FieldCreate() interface allow user code to attach arrays that have already been allocated by the user. Empty Fields can also be created in which case the data can be added at some later time.
For versions of Create which do not specify data values, user code can create an ArraySpec object, which contains information about the typekind and rank of the data values in the array. Then at Field create time, the appropriate amount of memory is allocated to contain the data which is local to each DE.
When finished with a ESMF_Field, the ESMF_FieldDestroy method removes it. However, the objects inside the ESMF_Field created externally should be destroyed separately, since objects can be added to more than one ESMF_Field. For example, the same ESMF_Grid can be referenced by multiple ESMF_Fields. In this case the internal Grid is not deleted by the ESMF_FieldDestroy call.
A user can get bounds and counts information from an ESMF_Field through the ESMF_FieldGet() interface. Also available through this interface is the intrinsic Fortran data pointer contained in the internal ESMF_Array object of an ESMF_Field. The bounds and counts information are DE specific for the associated Fortran data pointer.
For a better discussion of the terminologies, bounds and widths in ESMF e.g. exclusive, computational, total bounds for the lower and upper corner of data region, etc.., user can refer to the explanation of these concepts for Grid and Array in their respective sections in the Reference Manual, e.g. Section 28.2.6 on Array and Section 31.3.19 on Grid.
In this example, we first create a 3D Field based on a 3D Grid and Array. Then we use the ESMF_FieldGet() interface to retrieve the data pointer, potentially updating or verifying its values. We also retrieve the bounds and counts information of the 3D Field to assist in data element iteration.
xdim = 180
ydim = 90
zdim = 50
! create a 3D data Field from a Grid and Array.
! first create a Grid
grid3d = ESMF_GridCreateNoPeriDim(minIndex=(/1,1,1/), &
maxIndex=(/xdim,ydim,zdim/), &
regDecomp=(/2,2,1/), name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridGet(grid=grid3d, staggerloc=ESMF_STAGGERLOC_CENTER, &
distgrid=distgrid3d, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridGetFieldBounds(grid=grid3d, localDe=0, &
staggerloc=ESMF_STAGGERLOC_CENTER, totalCount=fa_shape, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
allocate(farray(fa_shape(1), fa_shape(2), fa_shape(3)) )
! create an Array
array3d = ESMF_ArrayCreate(distgrid3d, farray, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a Field
field = ESMF_FieldCreate(grid=grid3d, array=array3d, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! retrieve the Fortran data pointer from the Field
call ESMF_FieldGet(field=field, localDe=0, farrayPtr=farray1, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! retrieve the Fortran data pointer from the Field and bounds
call ESMF_FieldGet(field=field, localDe=0, farrayPtr=farray1, &
computationalLBound=compLBnd, computationalUBound=compUBnd, &
exclusiveLBound=exclLBnd, exclusiveUBound=exclUBnd, &
totalLBound=totalLBnd, totalUBound=totalUBnd, &
computationalCount=comp_count, &
exclusiveCount=excl_count, &
totalCount=total_count, &
rc=rc)
! iterate through the total bounds of the field data pointer
do k = totalLBnd(3), totalUBnd(3)
do j = totalLBnd(2), totalUBnd(2)
do i = totalLBnd(1), totalUBnd(1)
farray1(i, j, k) = sin(2*i/total_count(1)*PI) + &
sin(4*j/total_count(2)*PI) + &
sin(8*k/total_count(2)*PI)
enddo
enddo
enddo
A user can get the internal ESMF_Grid and ESMF_Array from a ESMF_Field. Note that the user should not issue any destroy command on the retrieved grid or array object since they are referenced from within the ESMF_Field. The retrieved objects should be used in a read-only fashion to query additional information not directly available through the ESMF_FieldGet() interface.
call ESMF_FieldGet(field, grid=grid, array=array, &
typekind=typekind, dimCount=dimCount, staggerloc=staggerloc, &
gridToFieldMap=gridToFieldMap, &
ungriddedLBound=ungriddedLBound, ungriddedUBound=ungriddedUBound, &
totalLWidth=totalLWidth, totalUWidth=totalUWidth, &
name=name, &
rc=rc)
A user can create an ESMF_Field from an ESMF_Grid and typekind/rank. This create method associates the two objects.
We first create a Grid with a regular distribution that is 10x20 index in 2x2 DEs. This version of Field create simply associates the data with the Grid. The data is referenced explicitly on a regular 2x2 uniform grid. Finally we create a Field from the Grid, typekind, rank, and a user specified StaggerLoc.
This example also illustrates a typical use of this Field creation method. By creating a Field from a Grid and typekind/rank, the user allows the ESMF library to create a internal Array in the Field. Then the user can use ESMF_FieldGet() to retrieve the Fortran data array and necessary bounds information to assign initial values to it.
! create a grid
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/10,20/), &
regDecomp=(/2,2/), name="atmgrid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a Field from the Grid and arrayspec
field1 = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_R4, &
indexflag=ESMF_INDEX_DELOCAL, &
staggerloc=ESMF_STAGGERLOC_CENTER, name="pressure", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field1, localDe=0, farrayPtr=farray2dd, &
totalLBound=ftlb, totalUBound=ftub, totalCount=ftc, rc=rc)
do i = ftlb(1), ftub(1)
do j = ftlb(2), ftub(2)
farray2dd(i, j) = sin(i/ftc(1)*PI) * cos(j/ftc(2)*PI)
enddo
enddo
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
A user can create an ESMF_Field from an ESMF_Grid and a ESMF_Arrayspec with corresponding rank and type. This create method associates the two objects.
We first create a Grid with a regular distribution that is 10x20 index in 2x2 DEs. This version of Field create simply associates the data with the Grid. The data is referenced explicitly on a regular 2x2 uniform grid. Then we create an ArraySpec. Finally we create a Field from the Grid, ArraySpec, and a user specified StaggerLoc.
This example also illustrates a typical use of this Field creation method. By creating a Field from a Grid and an ArraySpec, the user allows the ESMF library to create a internal Array in the Field. Then the user can use ESMF_FieldGet() to retrieve the Fortran data array and necessary bounds information to assign initial values to it.
! create a grid
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/10,20/), &
regDecomp=(/2,2/), name="atmgrid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! setup arrayspec
call ESMF_ArraySpecSet(arrayspec, 2, ESMF_TYPEKIND_R4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a Field from the Grid and arrayspec
field1 = ESMF_FieldCreate(grid, arrayspec, &
indexflag=ESMF_INDEX_DELOCAL, &
staggerloc=ESMF_STAGGERLOC_CENTER, name="pressure", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field1, localDe=0, farrayPtr=farray2dd, &
totalLBound=ftlb, totalUBound=ftub, totalCount=ftc, rc=rc)
do i = ftlb(1), ftub(1)
do j = ftlb(2), ftub(2)
farray2dd(i, j) = sin(i/ftc(1)*PI) * cos(j/ftc(2)*PI)
enddo
enddo
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
A user can also create an ArraySpec that has a different rank from the Grid, For example, the following code shows creation of of 3D Field from a 2D Grid using a 3D ArraySpec.
This example also demonstrates the technique to create a typical 3D data Field that has 2 gridded dimensions and 1 ungridded dimension.
First we create a 2D grid with an index space of 180x360 equivalent to 180x360 Grid cells (note that for a distributed memory computer, this means each grid cell will be on a separate PE!). In the FieldCreate call, we use gridToFieldMap to indicate the mapping between Grid dimension and Field dimension. For the ungridded dimension (typically the altitude), we use ungriddedLBound and ungriddedUBound to describe its bounds. Internally the ungridded dimension has a stride of 1, so the number of elements of the ungridded dimension is ungriddedUBound - ungriddedLBound + 1.
Note that gridToFieldMap in this specific example is (/1,2/) which is the default value so the user can neglect this argument for the FieldCreate call.
grid2d = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), &
maxIndex=(/180,360/), regDecomp=(/2,2/), name="atmgrid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_ArraySpecSet(arrayspec, 3, ESMF_TYPEKIND_R4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field1 = ESMF_FieldCreate(grid2d, arrayspec, &
indexflag=ESMF_INDEX_DELOCAL, &
staggerloc=ESMF_STAGGERLOC_CENTER, &
gridToFieldMap=(/1,2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/50/), &
name="pressure", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
A user can create an ESMF_Field from an ESMF_Grid and a ESMF_Array. The Grid was created in the previous example.
This example creates a 2D ESMF_Field from a 2D ESMF_Grid and a 2D ESMF_Array.
! Get necessary information from the Grid
call ESMF_GridGet(grid, staggerloc=ESMF_STAGGERLOC_CENTER, &
distgrid=distgrid, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create a 2D ESMF_TYPEKIND_R4 arrayspec
call ESMF_ArraySpecSet(arrayspec, 2, ESMF_TYPEKIND_R4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create a ESMF_Array from the arrayspec and distgrid
array2d = ESMF_ArrayCreate(arrayspec=arrayspec, &
distgrid=distgrid, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create a ESMF_Field from the grid and array
field4 = ESMF_FieldCreate(grid, array2d, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
A user can create an ESMF_Field in three steps: first create an empty ESMF_Field; then set a ESMF_Grid on the empty ESMF_Field; and finally complete the ESMF_Field by calling ESMF_FieldEmptyComplete.
! create an empty Field
field3 = ESMF_FieldEmptyCreate(name="precip", rc=rc)
! use FieldGet to retrieve the Field Status
call ESMF_FieldGet(field3, status=fstatus, rc=rc)
Once the Field is created, we can verify that the status of the Field is ESMF_FIELDSTATUS_EMPTY.
! Test the status of the Field
if (fstatus /= ESMF_FIELDSTATUS_EMPTY) then
call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
Next we set a Grid on the empty Field. We use the 2D grid created in a previous example simply to demonstrate the method. The Field data points will be on east edge of the Grid cells with the specified ESMF_STAGGERLOC_EDGE1.
! Set a grid on the Field
call ESMF_FieldEmptySet(field3, grid2d, &
staggerloc=ESMF_STAGGERLOC_EDGE1, rc=rc)
! use FieldGet to retrieve the Field Status again
call ESMF_FieldGet(field3, status=fstatus, rc=rc)
! Test the status of the Field
if (fstatus /= ESMF_FIELDSTATUS_GRIDSET) then
call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
The partially created Field is completed by specifying the typekind of its data storage. This method is overloaded with one of the following parameters, arrayspec, typekind, Fortran array, or Fortran array pointer. Additional optional arguments can be used to specify ungridded dimensions and halo regions similar to the other Field creation methods.
! Complete the Field by specifying the data typekind
! to be allocated internally.
call ESMF_FieldEmptyComplete(field3, typekind=ESMF_TYPEKIND_R8, &
ungriddedLBound=(/1/), ungriddedUBound=(/5/), rc=rc)
! use FieldGet to retrieve the Field Status again
call ESMF_FieldGet(field3, status=fstatus, rc=rc)
! Test the status of the Field
if (fstatus /= ESMF_FIELDSTATUS_COMPLETE) then
call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
A user can create an empty ESMF_Field. Then the user can finalize the empty ESMF_Field from a ESMF_Grid and an intrinsic Fortran data array. This interface is overloaded for typekind and rank of the Fortran data array.
In this example, both the grid and the Fortran array pointer are 2 dimensional and each dimension of the grid is mapped to the corresponding dimension of the Fortran array pointer, i.e. 1st dimension of grid maps to 1st dimension of Fortran array pointer, 2nd dimension of grid maps to 2nd dimension of Fortran array pointer, so on and so forth.
In order to create or complete a Field from a Grid and a Fortran array pointer, certain rules of the Fortran array bounds must be obeyed. We will discuss these rules as we progress in Field creation examples. We will make frequent reference to the terminologies for bounds and widths in ESMF. For a better discussion of these terminologies and concepts behind them, e.g. exclusive, computational, total bounds for the lower and upper corner of data region, etc.., users can refer to the explanation of these concepts for Grid and Array in their respective sections in the Reference Manual, e.g. Section 28.2.6 on Array and Section 31.3.19 on Grid. The examples here are designed to help a user to get up to speed with creating Fields for typical use.
This example introduces a helper method, the ESMF_GridGetFieldBounds interface that facilitates the computation of Fortran data array bounds and shape to assist ESMF_FieldEmptyComplete finalizing a Field from an intrinsic Fortran data array and a Grid.
! create an empty Field
field3 = ESMF_FieldEmptyCreate(name="precip", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! use FieldGet to retrieve total counts
call ESMF_GridGetFieldBounds(grid2d, localDe=0, &
staggerloc=ESMF_STAGGERLOC_CENTER, totalCount=ftc, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! allocate the 2d Fortran array based on retrieved total counts
allocate(farray2d(ftc(1), ftc(2)))
! finalize the Field
call ESMF_FieldEmptyComplete(field3, grid2d, farray2d, rc=rc)
In this example, we will show how to create a 7D Field from a 5D ESMF_Grid and 2D ungridded bounds with arbitrary halo widths and gridToFieldMap.
We first create a 5D DistGrid and a 5D Grid based on the DistGrid; then ESMF_GridGetFieldBounds computes the shape of a 7D array in fsize. We can then create a 7D Field from the 5D Grid and the 7D Fortran data array with other assimilating parameters.
! create a 5d distgrid
distgrid5d = ESMF_DistGridCreate(minIndex=(/1,1,1,1,1/), &
maxIndex=(/10,4,10,4,6/), regDecomp=(/2,1,2,1,1/), rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create a 5d Grid
grid5d = ESMF_GridCreate(distgrid=distgrid5d, name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! use FieldGet to retrieve total counts
call ESMF_GridGetFieldBounds(grid5d, localDe=0, ungriddedLBound=(/1,2/), &
ungriddedUBound=(/4,5/), &
totalLWidth=(/1,1,1,2,2/), totalUWidth=(/1,2,3,4,5/), &
gridToFieldMap=(/3,2,5,4,1/), &
totalCount=fsize, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! allocate the 7d Fortran array based on retrieved total counts
allocate(farray7d(fsize(1), fsize(2), fsize(3), fsize(4), fsize(5), &
fsize(6), fsize(7)))
! create the Field
field7d = ESMF_FieldCreate(grid5d, farray7d, ESMF_INDEX_DELOCAL, &
ungriddedLBound=(/1,2/), ungriddedUBound=(/4,5/), &
totalLWidth=(/1,1,1,2,2/), totalUWidth=(/1,2,3,4,5/), &
gridToFieldMap=(/3,2,5,4,1/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
A user can allocate the Fortran array in a different manner using the lower and upper bounds returned from FieldGet through the optional totalLBound and totalUBound arguments. In the following example, we create another 7D Field by retrieving the bounds and allocate the Fortran array with this approach. In this scheme, indexing the Fortran array is sometimes more convenient than using the shape directly.
call ESMF_GridGetFieldBounds(grid5d, localDe=0, ungriddedLBound=(/1,2/), &
ungriddedUBound=(/4,5/), &
totalLWidth=(/1,1,1,2,2/), totalUWidth=(/1,2,3,4,5/), &
gridToFieldMap=(/3,2,5,4,1/), &
totalLBound=flbound, totalUBound=fubound, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
allocate(farray7d2(flbound(1):fubound(1), flbound(2):fubound(2), &
flbound(3):fubound(3), flbound(4):fubound(4), &
flbound(5):fubound(5), flbound(6):fubound(6), &
flbound(7):fubound(7)) )
field7d2 = ESMF_FieldCreate(grid5d, farray7d2, ESMF_INDEX_DELOCAL, &
ungriddedLBound=(/1,2/), ungriddedUBound=(/4,5/), &
totalLWidth=(/1,1,1,2,2/), totalUWidth=(/1,2,3,4,5/), &
gridToFieldMap=(/3,2,5,4,1/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
See 28.2.13 for a introduction of the DE pinning feature. Here we focus on demonstrating the use of the DE pinning feature in the context of ESMF Field.
When an ESMF Field object is created, the specified underlying DistGrid indicates how many Decomposition Elements (DEs) are created. Each DE has its own memory allocation to hold user data. The DELayout, referenced by the DistGrid, determines which PET is considered the owner of each of the DEs. Queried for the local DEs, the Field object returns the list of DEs that are owned by the local PET making the query.
By default DEs are pinned to the PETs under which they were created. The memory allocation associated with a specific DE is only defined in the VAS of the PET to which the DE is pinned. As a consequence, only the PET owning a DE has access to its memory allocation.
On shared memory systems, however, ESMF allows DEs to be pinned to SSIs instead of PETs. In this case the PET under which a DE was created is still consider the owner, but now all PETs under the same SSI have access to the DE. For this the memory allocation associated with the DE is mapped into the VAS of all the PETs under the SSI.
To create an Field with each DE pinned to SSI instead of PET, first query the VM for the available level of support.
call ESMF_VMGet(vm, ssiSharedMemoryEnabledFlag=ssiSharedMemoryEnabled, rc=rc)
if (ssiSharedMemoryEnabled) then
Knowing that the SSI shared memory feature is available, it is now possible to create an Field object with DE to SSI pinning.
grid = ESMF_GridCreateNoPeriDim(maxIndex=(/40,10/), regDecomp=(/4,1/), &
coordSys = ESMF_COORDSYS_CART, &
rc=rc)
field = ESMF_FieldCreate(typekind=ESMF_TYPEKIND_R8, grid=grid, &
pinflag=ESMF_PIN_DE_TO_SSI, rc=rc)
Just as in the cases discussed before, where the same Grid was used, a default DELayout with as many DEs as PETs in the VM is constructed. Setting the pinflag to ESMF_PIN_DE_TO_SSI does not change the fact that each PET owns exactly one of the DEs. However, assuming that this code is run on a set of PETs that are all located under the same SSI, every PET now has access to all of the DEs. The situation can be observed by querying for both the localDeCount, and the ssiLocalDeCount.
call ESMF_FieldGet(field, localDeCount=localDeCount, &
ssiLocalDeCount=ssiLocalDeCount, rc=rc)
Assuming execution on 4 PETs, all located on the same SSI, the values of the returned variable are localDeCount==1 and ssiLocalDeCount==4 on all of the PETs. The mapping between each PET's local DE, and the global DE index is provided through the localDeToDeMap array argument. The amount of mapping information returned is dependent on how large localDeToDeMap has been sized by the user. For size(localDeToDeMap)==localDeCount, only mapping information for those DEs owned by the local PET is filled in. However for size(localDeToDeMap)==ssiLocalDeCount, mapping information for all locally accessible DEs is returned, including those owned by other PETs on the same SSI.
allocate(localDeToDeMap(0:ssiLocalDeCount-1))
call ESMF_FieldGet(field, localDeToDeMap=localDeToDeMap, rc=rc)
The first localDeCount entries of localDeToDeMap are always the global DE indices of the DEs owned by the local PET. The remaining ssiLocalDeCount-localDeCount entries are the global DE indices of DEs shared by other PETs. The ordering of the shared DEs is from smallest to greatest, excluding the locally owned DEs, which were already listed at the beginning of localDeToDeMap. For the current case, again assuming execution on 4 PETs all located on the same SSI, we expect the following situation:
PET 0: localDeToDeMap==(/0,1,2,3/)
PET 1: localDeToDeMap==(/1,0,2,3/)
PET 2: localDeToDeMap==(/2,0,1,3/)
PET 3: localDeToDeMap==(/3,0,1,2/)
Each PET can access the memory allocations associated with all of the DEs listed in the localDeToDeMap returned by the Field object. Direct access to the Fortran array pointer of a specific memory allocation is available through ESMF_FieldGet(). Here each PET queries for the farrayPtr of localDe==2, i.e. the 2nd shared DE.
call ESMF_FieldGet(field, farrayPtr=myFarray, localDe=2, rc=rc)
Now variable myFarray on PETs 0 and 1 both point to the same memory allocation for global DE 2. Both PETs have access to the same piece of shared memory! The same is true for PETs 2 and 3, pointing to the shared memory allocation of global DE 1.
It is important to note that all of the typical considerations surrounding shared memory programming apply when accessing shared DEs! Proper synchronization between PETs accessing shared DEs is critical to avoid race conditions. Also performance issues like false sharing need to be considered for optimal use.
For a simple demonstration, PETs 0 and 2 fill the entire memory allocation of DE 2 and 1, respectively, to a unique value.
if (localPet==0) then
myFarray = 12345.6789d0
else if (localPet==2) then
myFarray = 6789.12345d0
endif
Here synchronization is needed before any PETs that share access to the same DEs can safely access the data without race condition. The Field class provides a simple synchronization method that can be used.
call ESMF_FieldSync(field, rc=rc) ! prevent race condition
Now it is safe for PETs 1 and 3 to access the shared DEs. We expect to find the data that was set above. For simplicity of the code only the first array element is inspected here.
if (localPet==1) then
if (abs(myFarray(1,1)-12345.6789d0)>1.d10) print *, "bad data detected"
else if (localPet==3) then
if (abs(myFarray(1,1)-6789.12345d0)>1.d10) print *, "bad data detected"
endif
endif ! ending the ssiSharedMemoryEnabled conditional
A user can create an ESMF_Field directly from an ESMF_Grid and an intrinsic Fortran data array. This interface is overloaded for typekind and rank of the Fortran data array.
In the following example, each dimension size of the Fortran array is equal to the exclusive bounds of its corresponding Grid dimension queried from the Grid through ESMF_GridGet() public interface.
Formally let fa_shape(i) be the shape of i-th dimension of user supplied Fortran array, then rule 1 states:
(1) fa_shape(i) = exclusiveCount(i)
i = 1...GridDimCount
fa_shape(i) defines the shape of i-th dimension of the Fortran array. ExclusiveCount are the number of data elements of i-th dimension in the exclusive region queried from ESMF_GridGet interface. Rule 1 assumes that the Grid and the Fortran intrinsic array have same number of dimensions; and optional arguments of FieldCreate from Fortran array are left unspecified using default setup. These assumptions are true for most typical uses of FieldCreate from Fortran data array. This is the easiest way to create a Field from a Grid and a Fortran intrinsic data array.
Fortran array dimension sizes (called shape in most Fortran language books) are equivalent to the bounds and counts used in this manual. The following equation holds:
fa_shape(i) = shape(i) = counts(i) = upper_bound(i) - lower_bound(i) + 1
These typically mean the same concept unless specifically explained to mean something else. For example, ESMF uses DimCount very often to mean number of dimensions instead of its meaning implied in the above equation. We'll clarify the meaning of a word when ambiguity could occur.
Rule 1 is most useful for a user working with Field creation from a Grid and a Fortran data array in most scenarios. It extends to higher dimension count, 3D, 4D, etc... Typically, as the code example demonstrates, a user first creates a Grid, then uses ESMF_GridGet() to retrieve the exclusive counts. Next the user calculates the shape of each Fortran array dimension according to rule 1. The Fortran data array is allocated and initialized based on the computed shape. A Field can either be created in one shot or created empty and finished using ESMF_FieldEmptyComplete.
There are important details that can be skipped but are good to know for ESMF_FieldEmptyComplete
and ESMF_FieldCreate from a Fortran data array. 1) these methods require each PET contains
exactly one DE. This implies that a code using FieldCreate from a data array or FieldEmptyComplete must
have the same number of DEs and PETs, formally
. Violation of this condition
will cause run time failures. 2) the bounds and counts retrieved from GridGet are DE specific
or equivalently PET specific, which means that the Fortran array shape could be different from one
PET to another.
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/10,20/), &
regDecomp=(/2,2/), name="atmgrid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridGet(grid, localDE=0, staggerloc=ESMF_STAGGERLOC_CENTER, &
exclusiveCount=gec, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
allocate(farray(gec(1), gec(2)) )
field = ESMF_FieldCreate(grid, farray, ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
The setup of this example is similar to the previous section except that the Field is created from a data pointer instead of a data array. We highlight the ability to deallocate the internal Fortran data pointer queried from the Field. This gives a user more flexibility with memory management.
allocate(farrayPtr(gec(1), gec(2)) )
field = ESMF_FieldCreate(grid, farrayPtr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field, farrayPtr=farrayPtr2, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! deallocate the retrieved Fortran array pointer
deallocate(farrayPtr2)
This example demonstrates a typical use of ESMF_Field combining a 2D grid and a 3D Fortran native data array. One immediate problem follows: how does one define the bounds of the ungridded dimension? This is solved by the optional arguments ungriddedLBound and ungriddedUBound of the ESMF_FieldCreate interface. By definition, ungriddedLBound and ungriddedUBound are both 1 dimensional integer Fortran arrays.
Formally, let fa_shape(j=1...FieldDimCount-GridDimCount) be the shape of the ungridded dimensions of a Field relative to the Grid used in Field creation. The Field dimension count is equal to the number of dimensions of the Fortran array, which equals the number of dimensions of the resultant Field. GridDimCount is the number of dimensions of the Grid.
fa_shape(j) is computed as:
fa_shape(j) = ungriddedUBound(j) - ungriddedLBound(j) + 1
fa_shape is easy to compute when the gridded and ungridded dimensions do not mix. However, it's conceivable that at higher dimension count, gridded and ungridded dimensions can interleave. To aid the computation of ungridded dimension shape we formally introduce the mapping concept.
Let
, and
![$i_B \in [\phi, 1...n_B]$](img45.png){kind=small}
. 
is the number
of elements in set A, 
is the number of elements in set B. 
defines
a mapping from i-th element of set A to 
-th element in set B. 
indicates there does not exist a mapping from i-th element of set A to set B.
Suppose we have a mapping from dimension index of ungriddedLBound (or
ungriddedUBound) to Fortran array dimension index, called ugb2fa.
By definition, equals to the dimension count of
ungriddedLBound (or ungriddedUBound), equals to the dimension count of
the Fortran array. We can now formulate the computation of ungridded
dimension shape as rule 2:
(2) fa_shape(ugb2fa(j)) = ungriddedUBound(j) - ungriddedLBound(j) + 1
j = 1..FortranArrayDimCount - GridDimCount
The mapping can be computed in linear time proportional to the Fortran array dimension count (or rank) using the following algorithm in pseudocode:
map_index = 1
do i = 1, farray_rank
if i-th dimension of farray is ungridded
ugb2fa(map_index) = i
map_index = map_index + 1
endif
enddo
Here we use rank and dimension count interchangeably. These 2 terminologies are typically equivalent. But there are subtle differences under certain conditions. Rank is the total number of dimensions of a tensor object. Dimension count allows a finer description of the heterogeneous dimensions in that object. For example, a Field of rank 5 can have 3 gridded dimensions and 2 ungridded dimensions. Rank is precisely the summation of dimension count of all types of dimensions.
For example, if a 5D array is used with a 3D Grid, there are 2 ungridded dimensions: ungriddedLBound=(/1,2/) and ungriddedUBound=(/5,7/). Suppose the distribution of dimensions looks like (O, X, O, X, O), O means gridded, X means ungridded. Then the mapping from ungridded bounds to Fortran array is ugb2fa=(/2, 4/). The shape of 2nd and 4th dimension of Fortran array should equal (5, 8).
Back to our 3D Field created from a 2D Grid and 3D Fortran array example, suppose the 3rd Field dimension is ungridded, ungriddedLBound=(/3/), ungriddedUBound=(/9/). First we use rule 1 to compute shapes of the gridded Fortran array dimension, then we use rule 2 to compute shapes of the ungridded Fortran array dimension. In this example, we used the exclusive bounds obtained in the previous example.
fa_shape(1) = gec(1) ! rule 1
fa_shape(2) = gec(2)
fa_shape(3) = 7 ! rule 2 9-3+1
allocate(farray3d(fa_shape(1), fa_shape(2), fa_shape(3)))
field = ESMF_FieldCreate(grid, farray3d, ESMF_INDEX_DELOCAL, &
ungriddedLBound=(/3/), ungriddedUBound=(/9/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Building upon the previous example, we will create a 3D Field from a 2D grid and 3D array but with a slight twist. In this example, we introduce the gridToFieldMap argument that allows a user to map Grid dimension index to Field dimension index.
In this example, both dimensions of the Grid are distributed and the mapping from DistGrid to Grid is (/1,2/). We will introduce rule 3 assuming distgridToGridMap=(/1,2,3...gridDimCount/), and distgridDimCount equals to gridDimCount. This is a reasonable assumption in typical Field use.
We apply the mapping gridToFieldMap on rule 1 to create rule 3:
(3) fa_shape(gridToFieldMap(i)) = exclusiveCount(i)
i = 1,..GridDimCount.
Back to our example, suppose the 2nd Field dimension is ungridded, ungriddedLBound=(/3/), ungriddedUBound=(/9/). gridToFieldMap=(/3,1/), meaning the 1st Grid dimension maps to 3rd Field dimension, and 2nd Grid dimension maps to 1st Field dimension.
First we use rule 3 to compute shapes of the gridded Fortran array dimension, then we use rule 2 to compute shapes of the ungridded Fortran array dimension. In this example, we use the exclusive bounds obtained in the previous example.
gridToFieldMap2d(1) = 3
gridToFieldMap2d(2) = 1
do i = 1, 2
fa_shape(gridToFieldMap2d(i)) = gec(i)
end do
fa_shape(2) = 7
allocate(farray3d(fa_shape(1), fa_shape(2), fa_shape(3)))
field = ESMF_FieldCreate(grid, farray3d, ESMF_INDEX_DELOCAL, &
ungriddedLBound=(/3/), ungriddedUBound=(/9/), &
gridToFieldMap=gridToFieldMap2d, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
This example is similar to example 26.3.14. In addition, here we will show how a user can associate different halo widths to a Fortran array to create a Field through the totalLWidth and totalUWidth optional arguments. A diagram of the dimension configuration from Grid, halos, and Fortran data array is shown here.
The ESMF_FieldCreate() interface supports creating a Field from a Grid and a Fortran array padded with halos on the distributed dimensions of the Fortran array. Using this technique one can avoid passing non-contiguous Fortran array slice to FieldCreate. It guarantees the same exclusive region, and by using halos, it also defines a bigger total region to contain the entire contiguous memory block of the Fortran array.
The elements of totalLWidth and totalUWidth are applied in the order distributed dimensions appear in the Fortran array. By definition, totalLWidth and totalUWidth are 1 dimensional arrays of non-negative integer values. The size of haloWidth arrays is equal to the number of distributed dimensions of the Fortran array, which is also equal to the number of distributed dimensions of the Grid used in the Field creation.
Because the order of totalWidth (representing both totalLWidth and totalUWidth) element is applied to the order distributed dimensions appear in the Fortran array dimensions, it's quite simple to compute the shape of distributed dimensions of the Fortran array. They are done in a similar manner when applying ungriddedLBound and ungriddedUBound to ungridded dimensions of the Fortran array defined by rule 2.
Assume we have the mapping from the dimension index of totalWidth to the dimension index of Fortran array, called mhw2fa; and we also have the mapping from dimension index of Fortran array to dimension index of the Grid, called fa2g. The shape of distributed dimensions of a Fortran array can be computed by rule 4:
(4) fa_shape(mhw2fa(k)) = exclusiveCount(fa2g(mhw2fa(k)) +
totalUWidth(k) + totalLWidth(k)
k = 1...size(totalWidth)
This rule may seem confusing but algorithmically the computation can be done by the following pseudocode:
fa_index = 1
do i = 1, farray_rank
if i-th dimension of Fortran array is distributed
fa_shape(i) = exclusiveCount(fa2g(i)) +
totalUWidth(fa_index) + totalLWidth(fa_index)
fa_index = fa_index + 1
endif
enddo
The only complication then is to figure out the mapping from Fortran array dimension index to Grid dimension index. This process can be done by computing the reverse mapping from Field to Grid.
Typically, we don't have to consider these complications if the following conditions are met: 1) All Grid dimensions are distributed. 2) DistGrid in the Grid has a dimension index mapping to the Grid in the form of natural order (/1,2,3,.../). This natural order mapping is the default mapping between various objects throughout ESMF. 3) Grid to Field mapping is in the form of natural order, i.e. default mapping. These seem like a lot of conditions but they are the default case in the interaction among DistGrid, Grid, and Field. When these conditions are met, which is typically true, the shape of distributed dimensions of Fortran array follows rule 5 in a simple form:
(5) fa_shape(k) = exclusiveCount(k) +
totalUWidth(k) + totalLWidth(k)
k = 1...size(totalWidth)
Let's examine an example on how to apply rule 5. Suppose we have a 5D array and a 3D Grid that has its first 3 dimensions mapped to the first 3 dimensions of the Fortran array. totalLWidth=(/1,2,3/), totalUWidth=(/7,9,10/), then by rule 5, the following pseudo code can be used to compute the shape of the first 3 dimensions of the Fortran array. The shape of the remaining two ungridded dimensions can be computed according to rule 2.
do k = 1, 3
fa_shape(k) = exclusiveCount(k) +
totalUWidth(k) + totalLWidth(k))
enddo
Suppose now gridToFieldMap=(/2,3,4/) instead which says the first dimension of Grid maps to the 2nd dimension of Field (or Fortran array) and so on and so forth, we can obtain a more general form of rule 5 by introducing first_distdim_index shift when Grid to Field map (gridToFieldMap) is in the form of (/a,a+1,a+2.../).
(6) fa_shape(k+first_distdim_index-1) = exclusiveCount(k) +
totalUWidth(k) + totalLWidth(k)
k = 1...size(totalWidth)
It's obvious that first_distdim_index=a. If the first dimension of the Fortran array is distributed, then rule 6 degenerates into rule 5, which is the typical case.
Back to our example creating a 3D Field from a 2D Grid and a 3D intrinsic Fortran array, we will use the Grid created from previous example that satisfies condition 1 and 2. We'll also use a simple gridToFieldMap (1,2) which is the default mapping that satisfies condition 3. First we use rule 5 to compute the shape of distributed dimensions then we use rule 2 to compute the shape of the ungridded dimensions.
gridToFieldMap2d(1) = 1
gridToFieldMap2d(2) = 2
totalLWidth2d(1) = 3
totalLWidth2d(2) = 4
totalUWidth2d(1) = 3
totalUWidth2d(2) = 5
do k = 1, 2
fa_shape(k) = gec(k) + totalLWidth2d(k) + totalUWidth2d(k)
end do
fa_shape(3) = 7 ! 9-3+1
allocate(farray3d(fa_shape(1), fa_shape(2), fa_shape(3)))
field = ESMF_FieldCreate(grid, farray3d, ESMF_INDEX_DELOCAL, &
ungriddedLBound=(/3/), ungriddedUBound=(/9/), &
totalLWidth=totalLWidth2d, totalUWidth=totalUWidth2d, &
gridToFieldMap=gridToFieldMap2d, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_LocStream and typekind/rank. The location stream object is uniformly distributed in a 1 dimensional space on 4 DEs. The rank is 1 dimensional. Please refer to LocStream examples section for more information on LocStream creation.
locs = ESMF_LocStreamCreate(minIndex=1, maxIndex=16, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field = ESMF_FieldCreate(locs, typekind=ESMF_TYPEKIND_I4, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_LocStream and an ESMF_Arrayspec. The location stream object is uniformly distributed in a 1 dimensional space on 4 DEs. The arrayspec is 1 dimensional. Please refer to LocStream examples section for more information on LocStream creation.
locs = ESMF_LocStreamCreate(minIndex=1, maxIndex=16, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_ArraySpecSet(arrayspec, 1, ESMF_TYPEKIND_I4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field = ESMF_FieldCreate(locs, arrayspec, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_Mesh and typekind/rank. The mesh object is on a Euclidean surface that is partitioned to a 2x2 rectangular space with 4 elements and 9 nodes. The nodal space is represented by a distgrid with 9 indices. A Field is created on locally owned nodes on each PET. Therefore, the created Field has 9 data points globally. The mesh object can be represented by the picture below. For more information on Mesh creation, please see Section 33.3.1.
Mesh Ids
2.0 7 ------- 8 -------- 9
| | |
| 3 | 4 |
| | |
1.0 4 ------- 5 -------- 6
| | |
| 1 | 2 |
| | |
0.0 1 ------- 2 -------- 3
0.0 1.0 2.0
Node Ids at corners
Element Ids in centers
Mesh Owners
2.0 2 ------- 2 -------- 3
| | |
| 2 | 3 |
| | |
1.0 0 ------- 0 -------- 1
| | |
| 0 | 1 |
| | |
0.0 0 ------- 0 -------- 1
0.0 1.0 2.0
Node Owners at corners
Element Owners in centers
! Create Mesh structure in 1 step
mesh=ESMF_MeshCreate(parametricDim=2,spatialDim=2, &
nodeIds=nodeIds, nodeCoords=nodeCoords, &
nodeOwners=nodeOwners, elementIds=elemIds,&
elementTypes=elemTypes, elementConn=elemConn, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Field is created on the 1 dimensional nodal distgrid. On
! each PET, Field is created on the locally owned nodes.
field = ESMF_FieldCreate(mesh, typekind=ESMF_TYPEKIND_I4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_Mesh and an ESMF_Arrayspec. The mesh object is on a Euclidean surface that is partitioned to a 2x2 rectangular space with 4 elements and 9 nodes. The nodal space is represented by a distgrid with 9 indices. Field is created on locally owned nodes on each PET. Therefore, the created Field has 9 data points globally. The mesh object can be represented by the picture below. For more information on Mesh creation, please see Section 33.3.1.
! Create Mesh structure in 1 step
mesh=ESMF_MeshCreate(parametricDim=2,spatialDim=2, &
nodeIds=nodeIds, nodeCoords=nodeCoords, &
nodeOwners=nodeOwners, elementIds=elemIds,&
elementTypes=elemTypes, elementConn=elemConn, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_ArraySpecSet(arrayspec, 1, ESMF_TYPEKIND_I4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Field is created on the 1 dimensional nodal distgrid. On
! each PET, Field is created on the locally owned nodes.
field = ESMF_FieldCreate(mesh, arrayspec, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_Mesh and an ESMF_Array. The mesh object is created in the previous example and the array object is retrieved from the field created in the previous example too.
call ESMF_MeshGet(mesh, nodalDistgrid=distgrid, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
array = ESMF_ArrayCreate(distgrid=distgrid, arrayspec=arrayspec, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! query the array from the previous example
call ESMF_FieldGet(field, array=array, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a Field from a mesh and an array
field1 = ESMF_FieldCreate(mesh, array, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, an ESMF_Field is created from an ESMF_Mesh and an ESMF_ArraySpec. The mesh object is created in the previous example. The Field is also created with optional arguments such as ungridded dimensions and dimension mapping.
In this example, the mesh is mapped to the 2nd dimension of the ESMF_Field, with its first dimension being the ungridded dimension with bounds 1,3.
call ESMF_ArraySpecSet(arrayspec, 2, ESMF_TYPEKIND_I4, rc=rc)
field = ESMF_FieldCreate(mesh, arrayspec=arrayspec, gridToFieldMap=(/2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/3/), rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example an ESMF_Field with replicated dimension is created from an ESMF_Grid and an ESMF_Arrayspec. A user can also use other ESMF_FieldCreate() methods to create replicated dimension Field, this example illustrates the key concepts and use of a replicated dimension Field.
Normally gridToFieldMap argument in ESMF_FieldCreate() should not contain 0 value entries. However, for a Field with replicated dimension, a 0 entry in gridToFieldMap indicates the corresponding Grid dimension is replicated in the Field. In such a Field, the rank of the Field is no longer necessarily greater than its Grid rank. An example will make this clear. We will start by creating Distgrid and Grid.
! create 4D distgrid
distgrid = ESMF_DistGridCreate(minIndex=(/1,1,1,1/), &
maxIndex=(/6,4,6,4/), regDecomp=(/2,1,2,1/), rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create 4D grid on top of the 4D distgrid
grid = ESMF_GridCreate(distgrid=distgrid, name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create 3D arrayspec
call ESMF_ArraySpecSet(arrayspec, 3, ESMF_TYPEKIND_R8, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
In this example, a user creates a 3D Field with replicated dimension replicated along the 2nd and 4th dimension of its underlying 4D Grid. In addition, the 2nd dimension of the Field is ungridded (why?). The 1st and 3rd dimensions of the Field have halos.
! create field, 2nd and 4th dimensions of the Grid are replicated
field = ESMF_FieldCreate(grid, arrayspec, indexflag=ESMF_INDEX_DELOCAL, &
gridToFieldMap=(/1,0,2,0/), &
ungriddedLBound=(/1/), ungriddedUBound=(/4/), &
totalLWidth=(/1,1/), totalUWidth=(/4,5/), &
staggerloc=ESMF_STAGGERLOC_CORNER, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! get basic information from the field
call ESMF_FieldGet(field, grid=grid1, array=array, typekind=typekind, &
dimCount=dimCount, staggerloc=lstaggerloc, &
gridToFieldMap=lgridToFieldMap, ungriddedLBound=lungriddedLBound, &
ungriddedUBound=lungriddedUBound, totalLWidth=ltotalLWidth, &
totalUWidth=ltotalUWidth, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! get bounds information from the field
call ESMF_FieldGet(field, localDe=0, farrayPtr=farray, &
exclusiveLBound=felb, exclusiveUBound=feub, exclusiveCount=fec, &
computationalLBound=fclb, computationalUBound=fcub, &
computationalCount=fcc, totalLBound=ftlb, totalUBound=ftub, &
totalCount=ftc, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Next we verify that the field and array bounds agree with each other
call ESMF_ArrayGet(array, rank=arank, dimCount=adimCount, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
gridrank_repdim = 0
do i = 1, size(gridToFieldMap)
if(gridToFieldMap(i) == 0) gridrank_repdim = gridrank_repdim + 1
enddo
Number of undistributed dimension of the array X is computed from total rank of the array A, the dimension count of its underlying distgrid B and number of replicated dimension in the distgrid C. We have the following formula: X = A - (B - C)
allocate(audlb(arank-adimCount+gridrank_repdim), &
audub(arank-adimCount+gridrank_repdim))
call ESMF_ArrayGet(array, exclusiveLBound=aelb, exclusiveUBound=aeub, &
computationalLBound=aclb, computationalUBound=acub, &
totalLBound=atlb, totalUBound=atub, &
undistLBound=audlb, undistUBound=audub, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! verify the ungridded bounds from field match
! undistributed bounds from its underlying array
do i = 1, arank-adimCount
if(lungriddedLBound(i) .ne. audlb(i) ) &
rc = ESMF_FAILURE
enddo
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do i = 1, arank-adimCount
if(lungriddedUBound(i) .ne. audub(i) ) &
rc = ESMF_FAILURE
enddo
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
We then verify the data in the replicated dimension Field can be updated and accessed.
do ik = ftlb(3), ftub(3)
do ij = ftlb(2), ftub(2)
do ii = ftlb(1), ftub(1)
farray(ii,ij,ik) = ii+ij*2+ik
enddo
enddo
enddo
! access and verify
call ESMF_FieldGet(field, localDe=0, farrayPtr=farray1, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do ik = ftlb(3), ftub(3)
do ij = ftlb(2), ftub(2)
do ii = ftlb(1), ftub(1)
n = ii+ij*2+ik
if(farray1(ii,ij,ik) .ne. n ) rc = ESMF_FAILURE
enddo
enddo
enddo
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! release resources
call ESMF_FieldDestroy(field)
call ESMF_GridDestroy(grid)
call ESMF_DistGridDestroy(distgrid)
With the introduction of Field on arbitrarily distributed Grid, Field has two kinds of dimension count: one associated geometrical (or physical) dimensionality, the other one associated with its memory index space representation. Field and Grid dimCount reflect the physical index space of the objects. A new type of dimCount rank should be added to both of these entities. The rank gives the number of dimensions of the memory index space of the objects. This would be the dimension of the pointer pulled out of Field and the size of the bounds vector, for example.
For non-arbitrary Grids rank=dimCount, but for grids and fields with arbitrary dimensions rank = dimCount - (number of Arb dims) + 1 (Internally Field can use the Arb info from the grid to create the mapping from the Field Array to the DistGrid)
When creating a Field size(GridToFieldMap)=dimCount for both Arb and Non-arb grids This array specifies the mapping of Field to Grid identically for both Arb and Nonarb grids If a zero occurs in an entry corresponding to any arbitrary dimension, then a zero must occur in every entry corresponding to an arbitrary dimension (i.e. all arbitrary dimensions must either be all replicated or all not replicated, they can't be broken apart).
In this example an ESMF_Field is created from an arbitrarily distributed ESMF_Grid and an ESMF_Arrayspec. A user can also use other ESMF_FieldCreate() methods to create such a Field, this example illustrates the key concepts and use of Field on arbitrary distributed Grid.
The Grid is 3 dimensional in physics index space but the first two dimension are collapsed into a single memory index space. Thus the resulting Field is 3D in physics index space and 2D in memory index space. This is made obvious with the 2D arrayspec used to create this Field.
! create a 3D grid with the first 2 dimensions collapsed
! and arbitrarily distributed
grid3d = ESMF_GridCreateNoPeriDim(coordTypeKind=ESMF_TYPEKIND_R8, &
minIndex=(/1,1,1/), maxIndex=(/xdim, ydim,zdim/), &
arbIndexList=localArbIndex,arbIndexCount=localArbIndexCount, &
name="arb3dgrid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a 2D arrayspec
call ESMF_ArraySpecSet(arrayspec2D, rank=2, typekind=ESMF_TYPEKIND_R4, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create a 2D Field using the Grid and the arrayspec
field = ESMF_FieldCreate(grid3d, arrayspec2D, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field, rank=rank, dimCount=dimCount, &
rc=rc)
if (myPet .eq. 0) print *, 'Field rank, dimCount', &
rank, dimCount
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! verify that the dimension counts are correct
if (rank .ne. 2) correct = .false.
if (dimCount .ne. 3) correct = .false.
The next example is slightly more complicated in that the Field also contains one ungridded dimension and its gridded dimension is replicated on the arbitrarily distributed dimension of the Grid.
The same 3D Grid and 2D arrayspec in the previous example are used but a gridToFieldMap argument is supplied to the ESMF_FieldCreate() call. The first 2 entries of the map are 0, the last (3rd) entry is 1. The 3rd dimension of the Grid is mapped to the first dimension of the Field, this dimension is then replicated on the arbitrarily distributed dimensions of the Grid. In addition, the Field also has one ungridded dimension. Thus the final dimension count of the Field is 2 in both physics and memory index space.
field = ESMF_FieldCreate(grid3d, arrayspec2D,gridToFieldMap=(/0,0,1/), &
ungriddedLBound=(/1/), ungriddedUBound=(/10/),rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field, rank=rank, dimCount=dimCount, &
rc=rc)
if (myPet .eq. 0) print *, 'Field rank, dimCount', &
rank, dimCount
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
if (rank .ne. 2) correct = .false.
if (dimCount .ne. 2) correct = .false.
This section describes the Field regrid methods. For an in depth description of ESMF regridding and the options available please see Section 24.2.
The basic flow of ESMF Field regridding is as follows. First a source and destination geometry object are created, depending on the regrid method they can be either a Grid, a Mesh, an XGrid, or a LocStream. Next Fields are built on the source and destination grid objects. These Fields are then passed into ESMF_FieldRegridStore(). The user can either get a sparse matrix from this call and/or a routeHandle. If the user gets the sparse matrix then they are responsible for deallocating it, but other than that can use it as they wish. The routeHandle can be used in the ESMF_FieldRegrid() call to perform the actual interpolation of data from the source to the destination field. This interpolation can be repeated for the same set of Fields as long as the coordinates at the staggerloc involved in the regridding in the associated grid object don't change. The same routeHandle can also be used between any pair of Fields that matches the original pari in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability. However, if you want the routehandle to be the same interpolation between the grid objects upon which the Fields are built as was calculated with the original ESMF_FieldRegridStore() call, then there are additional constraints on the grid objects. To be the same interpolation, the grid objects upon which the Fields are build must contain the same coordinates at the stagger locations involved in the regridding as the original source and destination Fields used in the ESMF_FieldRegridStore() call. The routehandle represents the interpolation between the grid objects as they were during the ESMF_FieldRegridStore() call. So if the coordinates at the stagger location in the grid objects change, a new call to ESMF_FieldRegridStore() is necessary to compute the interpolation between that new set of coordinates. When finished with the routeHandle ESMF_FieldRegridRelease() should be used to free the associated memory.
The following example demonstrates doing a regrid operation between two Fields.
! (Create source Grid, Mesh, XGrid, or LocStream.)
! (Create srcField on the above.)
! (Create destination Grid, Mesh, XGrid, or LocStream.)
! (Create dstField on the above.)
! Create the routeHandle which encodes the communication and
! information necessary for the regrid sparse matrix multiply.
call ESMF_FieldRegridStore(srcField=srcField, dstField=dstField, &
routeHandle=routeHandle, rc=localrc)
! Can loop here regridding from srcField to dstField
! do i=1,....
! (Put data into srcField)
! Use the routeHandle to regrid data from srcField to dstField.
! As described above, the same routeHandle can be used to
! regrid a large class of different source and destination Fields.
call ESMF_FieldRegrid(srcField, dstField, routeHandle, rc=localrc)
! (Use data in dstField) ! enddo ! Free the buffers and data associated with the routeHandle. call ESMF_FieldRegridRelease(routeHandle, rc=localrc)
call ESMF_FieldRegridStore(srcField=srcField, srcMaskValues=(/1/), &
dstField=dstField, dstMaskValues=(/1/), &
unmappedaction=ESMF_UNMAPPEDACTION_IGNORE, &
routeHandle=routeHandle, &
regridmethod=ESMF_REGRIDMETHOD_BILINEAR, &
rc=localrc)
The ESMF_FieldRegrid and ESMF_FieldRegridRelease calls may then be applied as in the previous example.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create Source Mesh
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create the Mesh structure.
! For brevity's sake, the code to fill the Mesh creation
! arrays is omitted from this example. However, here
! is a brief description of the arrays:
! srcNodeIds - the global ids for the src nodes
! srcNodeCoords - the coordinates for the src nodes
! srcNodeOwners - which PET owns each src node
! srcElemIds - the global ids of the src elements
! srcElemTypes - the topological shape of each src element
! srcElemConn - how to connect the nodes to form the elements
! in the source mesh
! Several examples of setting up these arrays can be seen in
! the Mesh Section "Mesh Creation".
srcMesh=ESMF_MeshCreate(parametricDim=2,spatialDim=2, &
nodeIds=srcNodeIds, nodeCoords=srcNodeCoords, &
nodeOwners=srcNodeOwners, elementIds=srcElemIds,&
elementTypes=srcElemTypes, elementConn=srcElemConn, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create and Fill Source Field
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Set description of source Field
call ESMF_ArraySpecSet(arrayspec, 1, ESMF_TYPEKIND_R8, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create source Field
srcField = ESMF_FieldCreate(srcMesh, arrayspec, &
name="source", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Get source Field data pointer to put data into
call ESMF_FieldGet(srcField, 0, fptr1D, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Get number of local nodes to allocate space
! to hold local node coordinates
call ESMF_MeshGet(srcMesh, &
numOwnedNodes=numOwnedNodes, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Allocate space to hold local node coordinates
! (spatial dimension of Mesh*number of local nodes)
allocate(ownedNodeCoords(2*numOwnedNodes))
! Get local node coordinates
call ESMF_MeshGet(srcMesh, &
ownedNodeCoords=ownedNodeCoords, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Set the source Field to the function 20.0+x+y
do i=1,numOwnedNodes
! Get coordinates
x=ownedNodeCoords(2*i-1)
y=ownedNodeCoords(2*i)
! Set source function
fptr1D(i) = 20.0+x+y
enddo
! Deallocate local node coordinates
deallocate(ownedNodeCoords)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create Destination Mesh
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create the Mesh structure.
! For brevity's sake, the code to fill the Mesh creation
! arrays is omitted from this example. However, here
! is a brief description of the arrays:
! dstNodeIds - the global ids for the dst nodes
! dstNodeCoords - the coordinates for the dst nodes
! dstNodeOwners - which PET owns each dst node
! dstElemIds - the global ids of the dst elements
! dstElemTypes - the topological shape of each dst element
! dstElemConn - how to connect the nodes to form the elements
! in the destination mesh
! Several examples of setting up these arrays can be seen in
! the Mesh Section "Mesh Creation".
dstMesh=ESMF_MeshCreate(parametricDim=2,spatialDim=2, &
nodeIds=dstNodeIds, nodeCoords=dstNodeCoords, &
nodeOwners=dstNodeOwners, elementIds=dstElemIds,&
elementTypes=dstElemTypes, elementConn=dstElemConn, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Create Destination Field
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Set description of source Field
call ESMF_ArraySpecSet(arrayspec, 1, ESMF_TYPEKIND_R8, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create destination Field
dstField = ESMF_FieldCreate(dstMesh, arrayspec, &
name="destination", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Do Regrid
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Compute RouteHandle which contains the regrid operation
call ESMF_FieldRegridStore( &
srcField, &
dstField=dstField, &
routeHandle=routeHandle, &
regridmethod=ESMF_REGRIDMETHOD_BILINEAR, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Perform Regrid operation moving data from srcField to dstField
call ESMF_FieldRegrid(srcField, dstField, routeHandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! dstField now contains the interpolated data.
! If the Meshes don't change, then routeHandle
! may be used repeatedly to interpolate from
! srcField to dstField.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! User code to use the routeHandle, Fields, and
! Meshes goes here before they are freed below.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Free the objects created in the example.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Free the RouteHandle
call ESMF_FieldRegridRelease(routeHandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Free the Fields
call ESMF_FieldDestroy(srcField, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldDestroy(dstField, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Free the Meshes
call ESMF_MeshDestroy(dstMesh, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_MeshDestroy(srcMesh, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
User can use ESMF_FieldGather interface to gather Field data from multiple PETs onto a single root PET. This interface is overloaded by type, kind, and rank.
Note that the implementation of Scatter and Gather is not sequence index based. If the Field is built on arbitrarily distributed Grid, Mesh, LocStream or XGrid, Gather will not gather data to rootPet from source data points corresponding to the sequence index on the rootPet. Instead Gather will gather a contiguous memory range from source PET to rootPet. The size of the memory range is equal to the number of data elements on the source PET. Vice versa for the Scatter operation. In this case, the user should use ESMF_FieldRedist to achieve the same data operation result. For examples how to use ESMF_FieldRedist to perform Gather and Scatter, please refer to 26.3.32 and 26.3.31.
In this example, we first create a 2D Field, then use ESMF_FieldGather to collect all the data in this Field into a data pointer on PET 0.
! Get current VM and pet number
call ESMF_VMGetCurrent(vm, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_VMGet(vm, localPet=lpe, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Create a 2D Grid and use this grid to create a Field
! farray is the Fortran data array that contains data on each PET.
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/10,20/), &
regDecomp=(/2,2/), &
name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_I4, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field, farrayPtr=fptr, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!---------Initialize pet specific field data----------------
! 1 5 10
! 1 +--------+---------+
! | | |
! | 0 | 1 |
! | | |
! 10 +--------+---------+
! | | |
! | 2 | 3 |
! | | |
! 20 +--------+---------+
fptr = lpe
! allocate the Fortran data array on PET 0 to store gathered data
if(lpe .eq. 0) then
allocate (farrayDst(10,20))
else
allocate (farrayDst(0,0))
end if
call ESMF_FieldGather(field, farrayDst, rootPet=0, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! check that the values gathered on rootPet are correct
if(lpe .eq. 0) then
do i = 1, 5
do j = 1, 10
if(farrayDst(i, j) .ne. 0) localrc=ESMF_FAILURE
enddo
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do i = 6, 10
do j = 1, 10
if(farrayDst(i, j) .ne. 1) localrc=ESMF_FAILURE
enddo
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do i = 1, 5
do j = 11, 20
if(farrayDst(i, j) .ne. 2) localrc=ESMF_FAILURE
enddo
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do i = 6, 10
do j = 11, 20
if(farrayDst(i, j) .ne. 3) localrc=ESMF_FAILURE
enddo
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
! destroy all objects created in this example to prevent memory leak
call ESMF_FieldDestroy(field, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridDestroy(grid, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
if(lpe .eq. 0) deallocate(farrayDst)
User can use ESMF_FieldScatter interface to scatter Field data from root PET onto its set of joint PETs. This interface is overloaded by type, kind, and rank.
In this example, we first create a 2D Field, then use ESMF_FieldScatter to scatter the data from a data array located on PET 0 onto this Field.
! Create a 2D Grid and use this grid to create a Field
! farray is the Fortran data array that contains data on each PET.
grid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/10,20/), &
regDecomp=(/2,2/), &
name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
field = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_I4, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! initialize values to be scattered
! 1 5 10
! 1 +--------+---------+
! | | |
! | 0 | 1 |
! | | |
! 10 +--------+---------+
! | | |
! | 2 | 3 |
! | | |
! 20 +--------+---------+
if(lpe .eq. 0) then
allocate(farraySrc(10,20))
farraySrc(1:5,1:10) = 0
farraySrc(6:10,1:10) = 1
farraySrc(1:5,11:20) = 2
farraySrc(6:10,11:20) = 3
else
allocate (farraySrc(0,0))
endif
! scatter the data onto individual PETs of the Field
call ESMF_FieldScatter(field, farraySrc, rootPet=0, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(field, localDe=0, farrayPtr=fptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! verify that the scattered data is properly distributed
do i = lbound(fptr, 1), ubound(fptr, 1)
do j = lbound(fptr, 2), ubound(fptr, 2)
if(fptr(i, j) .ne. lpe) localrc = ESMF_FAILURE
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
enddo
! destroy all objects created in this example to prevent memory leak
call ESMF_FieldDestroy(field, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridDestroy(grid, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
if(lpe .eq. 0) deallocate(farraySrc)
User can use ESMF_FieldRedist interface to redistribute data from source Field to destination Field. This interface is overloaded by type and kind; In the version of ESMF_FieldRedist without factor argument, a default value of 1 is used.
In this example, we first create two 1D Fields, a source Field and a destination Field. Then we use ESMF_FieldRedist to redistribute data from source Field to destination Field.
! Get current VM and pet number
call ESMF_VMGetCurrent(vm, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_VMGet(vm, localPet=localPet, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create grid
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/16/), &
regDecomp=(/4/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
grid = ESMF_GridCreate(distgrid=distgrid, &
name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create srcField
! +--------+--------+--------+--------+
! 0 1 2 3 ! value
! 1 4 8 12 16 ! bounds
srcField = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_I4, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(srcField, farrayPtr=srcfptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
srcfptr(:) = localPet
! create dstField
! +--------+--------+--------+--------+
! 0 0 0 0 ! value
! 1 4 8 12 16 ! bounds
dstField = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_I4, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldGet(dstField, farrayPtr=dstfptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
dstfptr(:) = 0
! perform redist
! 1. setup routehandle from source Field to destination Field
call ESMF_FieldRedistStore(srcField, dstField, routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! 2. use precomputed routehandle to redistribute data
call ESMF_FieldRedist(srcfield, dstField, routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! verify redist
call ESMF_FieldGet(dstField, localDe=0, farrayPtr=fptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Verify that the redistributed data in dstField is correct.
! Before the redist op, the dst Field contains all 0.
! The redist op reset the values to the PE value, verify this is the case.
do i = lbound(fptr, 1), ubound(fptr, 1)
if(fptr(i) .ne. localPet) localrc = ESMF_FAILURE
enddo
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Field redistribution can also be performed between different Field pairs that match the original Fields in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
call ESMF_ArraySpecSet(arrayspec, typekind=ESMF_TYPEKIND_I4, rank=2, rc=rc)
Create two fields with ungridded dimensions using the Grid created previously. The new Field pair has matching number of elements. The ungridded dimension is mapped to the first dimension of either Field.
srcFieldA = ESMF_FieldCreate(grid, arrayspec, gridToFieldMap=(/2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/10/), rc=rc)
dstFieldA = ESMF_FieldCreate(grid, arrayspec, gridToFieldMap=(/2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/10/), rc=rc)
Using the previously computed routehandle, the Fields can be redistributed.
call ESMF_FieldRedist(srcfieldA, dstFieldA, routehandle, rc=rc)
call ESMF_FieldRedistRelease(routehandle, rc=rc)
User can use ESMF_FieldRedist interface to redistribute data from source Field to destination Field, where the destination Field is built on an arbitrarily distributed structure, e.g. ESMF_Mesh. The underlying mechanism is explained in section 28.2.19.
In this example, we will create 2 one dimensional Fields, the src Field has a regular decomposition and holds all its data on a single PET, in this case PET 0. The destination Field is built on a Mesh which is itself built on an arbitrarily distributed distgrid. Then we use ESMF_FieldRedist to redistribute data from source Field to destination Field, similar to a traditional scatter operation.
The src Field only has data on PET 0 where it is sequentially initialized, i.e. 1,2,3...This data will be redistributed (or scattered) from PET 0 to the destination Field arbitrarily distributed on all the PETs.
! a one dimensional grid whose elements are all located on PET 0
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/9/), &
regDecomp=(/1/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
grid = ESMF_GridCreate(distgrid=distgrid, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
srcField = ESMF_FieldCreate(grid, typekind=ESMF_TYPEKIND_I4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! initialize the source data
if (localPet == 0) then
call ESMF_FieldGet(srcField, farrayPtr=srcfptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
do i = 1, 9
srcfptr(i) = i
enddo
endif
For more information on Mesh creation, user can refer to Mesh examples section or Field creation on Mesh example for more details.
! Create Mesh structure
mesh=ESMF_MeshCreate(parametricDim=2,spatialDim=2, &
nodeIds=nodeIds, nodeCoords=nodeCoords, &
nodeOwners=nodeOwners, elementIds=elemIds,&
elementTypes=elemTypes, elementConn=elemConn, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Create the destination Field on the Mesh that is arbitrarily distributed on all the PETs.
dstField = ESMF_FieldCreate(mesh, typekind=ESMF_TYPEKIND_I4, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Perform the redistribution from source Field to destination Field.
call ESMF_FieldRedistStore(srcField, dstField, &
routehandle=routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_FieldRedist(srcField, dstField, routehandle=routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
We can now verify that the sequentially initialized source data is scattered on to the destination Field. The data has been scattered onto the destination Field with the following distribution.
4 elements on PET 0: 1 2 4 5 2 elements on PET 1: 3 6 2 elements on PET 2: 7 8 1 element on PET 3: 9Because the redistribution is index based, the elements also corresponds to the index space of Mesh in the destination Field.
call ESMF_FieldGet(dstField, farrayPtr=dstfptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
The scatter operation is successful. Since the routehandle computed with ESMF_FieldRedistStore can be reused, user can use the same routehandle to scatter multiple source Fields from a single PET to multiple destination Fields distributed on all PETs. The gathering operation is just the opposite of the demonstrated scattering operation, where a user would redist from a source Field distributed on multiple PETs to a destination Field that only has data storage on a single PET.
Now it's time to release all the resources.
call ESMF_FieldRedistRelease(routehandle=routehandle, rc=rc)
Similarly, one can use the same approach to gather the data from an arbitrary distribution to a non-arbitrary distribution. This concept is demonstrated by using the previous Fields but the data operation is reversed. This time data is gathered from the Field built on the mesh to the Field that has only data allocation on rootPet.
First a FieldRedist routehandle is created from the Field built on Mesh to the Field that has only data allocation on rootPet.
call ESMF_FieldRedistStore(dstField, srcField, routehandle=routehandle, &
rc=rc)
Perform FieldRedist, this will gather the data points from the Field built on mesh to the data pointer on the rootPet (default to 0) stored in the srcField.
call ESMF_FieldRedist(dstField, srcField, routehandle=routehandle, rc=rc)
Release the routehandle used for the gather operation.
call ESMF_FieldRedistRelease(routehandle=routehandle, rc=rc)
The ESMF_FieldSMM() interface can be used to perform sparse matrix multiplication from source Field to destination Field. This interface is overloaded by type and kind;
In this example, we first create two 1D Fields, a source Field and a destination Field. Then we use ESMF_FieldSMM to perform sparse matrix multiplication from source Field to destination Field.
The source and destination Field data are arranged such that each of the 4 PETs has 4
data elements. Moreover, the source Field has all its data elements initialized to a linear
function based on local PET number.
Then collectively on each PET, a SMM according to the following formula
is preformed:
Because source Field data are initialized to a linear function based on local PET number, the formula predicts that the result destination Field data on each PET is 1,2,3,4. This is verified in the example.
Section 28.2.18 provides a detailed discussion of the sparse matrix multiplication operation implemented in ESMF.
! Get current VM and pet number
call ESMF_VMGetCurrent(vm, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_VMGet(vm, localPet=lpe, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create distgrid and grid
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/16/), &
regDecomp=(/4/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
grid = ESMF_GridCreate(distgrid=distgrid, &
name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridGetFieldBounds(grid, localDe=0, totalCount=fa_shape, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create src\_farray, srcArray, and srcField
! +--------+--------+--------+--------+
! 1 2 3 4 ! value
! 1 4 8 12 16 ! bounds
allocate(src_farray(fa_shape(1)) )
src_farray = lpe+1
srcArray = ESMF_ArrayCreate(distgrid, src_farray, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
srcField = ESMF_FieldCreate(grid, srcArray, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! create dst_farray, dstArray, and dstField
! +--------+--------+--------+--------+
! 0 0 0 0 ! value
! 1 4 8 12 16 ! bounds
allocate(dst_farray(fa_shape(1)) )
dst_farray = 0
dstArray = ESMF_ArrayCreate(distgrid, dst_farray, &
indexflag=ESMF_INDEX_DELOCAL, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
dstField = ESMF_FieldCreate(grid, dstArray, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! perform sparse matrix multiplication
! 1. setup routehandle from source Field to destination Field
! initialize factorList and factorIndexList
allocate(factorList(4))
allocate(factorIndexList(2,4))
factorList = (/1,2,3,4/)
factorIndexList(1,:) = (/lpe*4+1,lpe*4+2,lpe*4+3,lpe*4+4/)
factorIndexList(2,:) = (/lpe*4+1,lpe*4+2,lpe*4+3,lpe*4+4/)
call ESMF_FieldSMMStore(srcField, dstField, routehandle, &
factorList, factorIndexList, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! 2. use precomputed routehandle to perform SMM
call ESMF_FieldSMM(srcfield, dstField, routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! verify sparse matrix multiplication
call ESMF_FieldGet(dstField, localDe=0, farrayPtr=fptr, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! Verify that the result data in dstField is correct.
! Before the SMM op, the dst Field contains all 0.
! The SMM op reset the values to the index value, verify this is the case.
! +--------+--------+--------+--------+
! 1 2 3 4 2 4 6 8 3 6 9 12 4 8 12 16 ! value
! 1 4 8 12 16 ! bounds
do i = lbound(fptr, 1), ubound(fptr, 1)
if(fptr(i) /= i*(lpe+1)) rc = ESMF_FAILURE
enddo
Field sparse matrix multiplication can also be applied between Fields that matche the original Fields in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability
call ESMF_ArraySpecSet(arrayspec, typekind=ESMF_TYPEKIND_I4, rank=2, rc=rc)
Create two fields with ungridded dimensions using the Grid created previously. The new Field pair has matching number of elements. The ungridded dimension is mapped to the first dimension of either Field.
srcFieldA = ESMF_FieldCreate(grid, arrayspec, gridToFieldMap=(/2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/10/), rc=rc)
dstFieldA = ESMF_FieldCreate(grid, arrayspec, gridToFieldMap=(/2/), &
ungriddedLBound=(/1/), ungriddedUBound=(/10/), rc=rc)
Using the previously computed routehandle, the sparse matrix multiplication can be performed between the Fields.
call ESMF_FieldSMM(srcfieldA, dstFieldA, routehandle, rc=rc)
! release route handle
call ESMF_FieldSMMRelease(routehandle, rc=rc)
In the following discussion, we demonstrate how to set up a SMM routehandle between a pair of Fields that are different in number of gridded dimensions and the size of those gridded dimensions. The source Field has a 1D decomposition with 16 total elements; the destination Field has a 2D decomposition with 12 total elements. For ease of understanding of the actual matrix calculation, a global indexing scheme is used.
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/16/), &
indexflag=ESMF_INDEX_GLOBAL, &
regDecomp=(/4/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
grid = ESMF_GridCreate(distgrid=distgrid, &
indexflag=ESMF_INDEX_GLOBAL, &
name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
call ESMF_GridGetFieldBounds(grid, localDe=0, totalLBound=tlb, &
totalUBound=tub, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
create 1D src_farray, srcArray, and srcField
+ PET0 + PET1 + PET2 + PET3 +
+--------+--------+--------+--------+
1 2 3 4 ! value
1 4 8 12 16 ! bounds of seq indices
allocate(src_farray2(tlb(1):tub(1)) )
src_farray2 = lpe+1
srcArray = ESMF_ArrayCreate(distgrid, src_farray2, &
indexflag=ESMF_INDEX_GLOBAL, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
!print *, lpe, '+', tlb, tub, '+', src_farray2
srcField = ESMF_FieldCreate(grid, srcArray, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Create 2D dstField on the following distribution (numbers are the sequence indices):
+ PET0 + PET1 + PET2 + PET3 + +--------+--------+--------+--------+ | | | | | | 1 | 4 | 7 | 10 | | | | | | +--------+--------+--------+--------+ | | | | | | 2 | 5 | 8 | 11 | | | | | | +--------+--------+--------+--------+ | | | | | | 3 | 6 | 9 | 12 | | | | | | +--------+--------+--------+--------+
! Create the destination Grid
dstGrid = ESMF_GridCreateNoPeriDim(minIndex=(/1,1/), maxIndex=(/3,4/), &
indexflag = ESMF_INDEX_GLOBAL, &
regDecomp = (/1,4/), &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
dstField = ESMF_FieldCreate(dstGrid, typekind=ESMF_TYPEKIND_R4, &
indexflag=ESMF_INDEX_GLOBAL, &
rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
Perform sparse matrix multiplication 
= 
* 
First setup routehandle from source Field to destination Field
with prescribed factorList and factorIndexList.
The sparse matrix is of size 12x16, however only the following entries are filled:
M(3,1) = 0.1 M(3,10) = 0.4 M(8,2) = 0.25 M(8,16) = 0.5 M(12,1) = 0.3 M(12,16) = 0.7
By the definition of matrix calculation, the 8th element on PET2 in the dstField equals to 0.25*srcField(2) + 0.5*srcField(16) = 0.25*1+0.5*4=2.25 For simplicity, we will load the factorList and factorIndexList on PET 0 and 1, the SMMStore engine will load balance the parameters on all 4 PETs internally for optimal performance.
if(lpe == 0) then
allocate(factorList(3), factorIndexList(2,3))
factorList=(/0.1,0.4,0.25/)
factorIndexList(1,:)=(/1,10,2/)
factorIndexList(2,:)=(/3,3,8/)
call ESMF_FieldSMMStore(srcField, dstField, routehandle=routehandle, &
factorList=factorList, factorIndexList=factorIndexList, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
else if(lpe == 1) then
allocate(factorList(3), factorIndexList(2,3))
factorList=(/0.5,0.3,0.7/)
factorIndexList(1,:)=(/16,1,16/)
factorIndexList(2,:)=(/8,12,12/)
call ESMF_FieldSMMStore(srcField, dstField, routehandle=routehandle, &
factorList=factorList, factorIndexList=factorIndexList, rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
else
call ESMF_FieldSMMStore(srcField, dstField, routehandle=routehandle, &
rc=localrc)
if (localrc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
! 2. use precomputed routehandle to perform SMM
call ESMF_FieldSMM(srcfield, dstField, routehandle=routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
The ESMF_FieldHalo() interface can be used to perform halo updates for a Field. This
eases communication programming from a user perspective. By definition, the user
program only needs to update locally owned exclusive region in each domain, then call
FieldHalo to communicate the values in the halo region from/to neighboring domain elements.
In this example, we solve a 1D heat transfer problem:
with the
initial condition 
and boundary conditions
.
The temperature field
is represented by a ESMF_Field. A finite difference explicit time stepping scheme is employed.
During each time step, FieldHalo update is called to communicate values in the halo region
to neighboring domain elements. The steady state (as
) solution
is a linear temperature profile along 
. The numerical solution is an approximation of
the steady state solution. It can be verified to represent a linear temperature profile.
Section 28.2.15 provides a discussion of the halo operation implemented in ESMF_Array.
! create 1D distgrid and grid decomposed according to the following diagram:
! +------------+ +----------------+ +---------------+ +--------------+
! | DE 0 | | | | DE 1 | | | | DE 2 | | | | DE 3 |
! | 1 x 16 | | | | 1 x 16 | | | | 1 x 16 | | | | 1 x 16 |
! | | 1|<->|1 | | 1|<->|1 | | 1|<->|1 | |
! | | | | | | | | | | | | | |
! +------------+ +----------------+ +---------------+ +--------------+
distgrid = ESMF_DistGridCreate(minIndex=(/1/), maxIndex=(/npx/), &
regDecomp=(/4/), rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
grid = ESMF_GridCreate(distgrid=distgrid, name="grid", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
! set up initial condition and boundary conditions of the
! temperature Field
if(lpe == 0) then
allocate(fptr(17), tmp_farray(17))
fptr = 20.
fptr(1) = 10.
tmp_farray(1) = 10.
startx = 2
endx = 16
field = ESMF_FieldCreate(grid, fptr, totalUWidth=(/1/), &
name="temperature", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
else if(lpe == 3) then
allocate(fptr(17), tmp_farray(17))
fptr = 20.
fptr(17) = 40.
tmp_farray(17) = 40.
startx = 2
endx = 16
field = ESMF_FieldCreate(grid, fptr, totalLWidth=(/1/), &
name="temperature", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
else
allocate(fptr(18), tmp_farray(18))
fptr = 20.
startx = 2
endx = 17
field = ESMF_FieldCreate(grid, fptr, &
totalLWidth=(/1/), totalUWidth=(/1/), name="temperature", rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
endif
! compute the halo update routehandle of the decomposed temperature Field
call ESMF_FieldHaloStore(field, routehandle=routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
dt = 0.01
dx = 1./npx
alpha = 0.1
! Employ explicit time stepping
! Solution converges after about 9000 steps based on apriori knowledge.
! The result is a linear temperature profile stored in field.
do iter = 1, 9000
! only elements in the exclusive region are updated locally
! in each domain
do i = startx, endx
tmp_farray(i) = &
fptr(i)+alpha*alpha*dt/dx/dx*(fptr(i+1)-2.*fptr(i)+fptr(i-1))
enddo
fptr = tmp_farray
! call halo update to communicate the values in the halo region to
! neighboring domains
call ESMF_FieldHalo(field, routehandle=routehandle, rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
enddo
! release the halo routehandle
call ESMF_FieldHaloRelease(routehandle, rc=rc)
INTERFACE:
interface assignment(=) field1 = field2ARGUMENTS:
type(ESMF_Field) :: field1 type(ESMF_Field) :: field2STATUS:
DESCRIPTION:
Assign field1 as an alias to the same ESMF Field object in memory as field2. If field2 is invalid, then field1 will be equally invalid after the assignment.
The arguments are:
INTERFACE:
interface operator(==) if (field1 == field2) then ... endif OR result = (field1 == field2)RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_Field), intent(in) :: field1 type(ESMF_Field), intent(in) :: field2STATUS:
DESCRIPTION:
Test whether field1 and field2 are valid aliases to the same ESMF Field object in memory. For a more general comparison of two ESMF Fields, going beyond the simple alias test, the ESMF_FieldMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
interface operator(/=) if (field1 /= field2) then ... endif OR result = (field1 /= field2)RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_Field), intent(in) :: field1 type(ESMF_Field), intent(in) :: field2STATUS:
DESCRIPTION:
Test whether field1 and field2 are not valid aliases to the same ESMF Field object in memory. For a more general comparison of two ESMF Fields, going beyond the simple alias test, the ESMF_FieldMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
subroutine ESMF_FieldCopy(fieldOut, fieldIn, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: fieldOut
type(ESMF_Field), intent(in) :: fieldIn
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Copy data from one ESMF_Field object to another.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateGBTKR(geom, typekind, &
gridToFieldMap, ungriddedLBound, ungriddedUBound, &
totalLWidth, totalUWidth, pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGBTKRARGUMENTS:
type(ESMF_Geom), intent(in) :: geom
type(ESMF_TypeKind_Flag),intent(in) :: typekind
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.4.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateGBArraySpec(geom, arrayspec, gridToFieldMap, &
ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, &
pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGBArraySpecARGUMENTS:
type(ESMF_Geom) :: geom
type(ESMF_ArraySpec), intent(in) :: arrayspec
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.5.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateGBData<rank><type><kind>(geom, & farray, indexflag, datacopyflag, gridToFieldMap, ungriddedLBound, & ungriddedUBound, totalLWidth, totalUWidth, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGBData<rank><type><kind>ARGUMENTS:
type(ESMF_Geom) :: geom <type> (ESMF_KIND_<kind>), dimension(<rank>), target :: farray type(ESMF_Index_Flag), intent(in) :: indexflag type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data array and ESMF_Geom. The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed. The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateGBDataPtr<rank><type><kind>(geom, & farrayPtr, datacopyflag, gridToFieldMap, & totalLWidth, totalUWidth, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGBDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_Geom) :: geom <type> (ESMF_KIND_<kind>), dimension(<rank>), pointer :: farrayPtr type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data pointer and ESMF_Geom. The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateGridTKR(grid, typekind, &
indexflag, staggerloc, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
totalLWidth, totalUWidth, pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGridTKRARGUMENTS:
type(ESMF_Grid), intent(in) :: grid
type(ESMF_TypeKind_Flag),intent(in) :: typekind
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Index_Flag), intent(in), optional :: indexflag
type(ESMF_StaggerLoc), intent(in), optional :: staggerloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.4.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateGridArraySpec(grid, arrayspec, &
indexflag, staggerloc, gridToFieldMap, ungriddedLBound, &
ungriddedUBound, totalLWidth, totalUWidth, pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGridArraySpecARGUMENTS:
type(ESMF_Grid), intent(in) :: grid
type(ESMF_ArraySpec), intent(in) :: arrayspec
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Index_Flag), intent(in), optional :: indexflag
type(ESMF_StaggerLoc), intent(in), optional :: staggerloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.5.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateGridArray(grid, array, datacopyflag, &
staggerloc, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
totalLWidth, totalUWidth, name, vm, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGridArrayARGUMENTS:
type(ESMF_Grid), intent(in) :: grid
type(ESMF_Array), intent(in) :: array
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag
type(ESMF_StaggerLoc), intent(in), optional :: staggerloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
character (len = *), intent(in), optional :: name
type(ESMF_VM), intent(in), optional :: vm
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Create an ESMF_Field. This version of creation assumes the data exists already and is being passed in through an ESMF_Array. For an example and associated documentation using this method see section 26.3.6.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateGridData<rank><type><kind>(grid, & farray, indexflag, datacopyflag, staggerloc, & gridToFieldMap, ungriddedLBound, ungriddedUBound, & totalLWidth, totalUWidth, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGridData<rank><type><kind>ARGUMENTS:
type(ESMF_Grid), intent(in) :: grid <type> (ESMF_KIND_<kind>),intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_StaggerLoc), intent(in), optional :: staggerloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Create an ESMF_Field from a Fortran data array and ESMF_Grid. The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed. For examples and associated documentation regarding this method see section 26.3.11, 26.3.13, 26.3.14, 26.3.15, and 26.3.9.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateGridDataPtr<rank><type><kind>(grid, & farrayPtr, datacopyflag, staggerloc, gridToFieldMap, & totalLWidth, totalUWidth, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateGridDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_Grid), intent(in) :: grid <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_StaggerLoc), intent(in), optional :: staggerloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Create an ESMF_Field from a Fortran data pointer and ESMF_Grid. The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
For examples and associated documentation regarding this method see section 26.3.12, 26.3.13, 26.3.14, 26.3.15, and 26.3.9.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateLSTKR(locstream, typekind, &
gridToFieldMap, ungriddedLBound, ungriddedUBound, pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateLSTKRARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream
type(ESMF_TypeKind_Flag),intent(in) :: typekind
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.16.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateLSArraySpec(locstream, arrayspec, &
gridToFieldMap, ungriddedLBound, ungriddedUBound, pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateLSArraySpecARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream
type(ESMF_ArraySpec), intent(in) :: arrayspec
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.17.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateLSArray(locstream, array, &
datacopyflag, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateLSArrayARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream
type(ESMF_Array), intent(in) :: array
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
character (len = *), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field. This version of creation assumes the data exists already and is being passed in through an ESMF_Array. For an example and associated documentation using this method see section 26.3.6.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateLSData<rank><type><kind>(locstream, farray, & indexflag, datacopyflag, gridToFieldMap, ungriddedLBound, & ungriddedUBound, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateLSData<rank><type><kind>ARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream <type> (ESMF_KIND_<kind>),intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data array and ESMF_LocStream. The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateLSDataPtr<rank><type><kind>(locstream, & farrayPtr, datacopyflag, gridToFieldMap, & name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateLSDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream <type> (ESMF_KIND_<kind>),pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data pointer and ESMF_LocStream. The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateMeshTKR(mesh, typekind, indexflag, &
meshloc, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateMeshTKRARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh
type(ESMF_TypeKind_Flag), intent(in) :: typekind
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Index_Flag), intent(in), optional :: indexflag
type(ESMF_MeshLoc), intent(in), optional :: meshloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.18.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateMeshArraySpec(mesh, arrayspec, &
indexflag, meshloc, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateMeshArraySpecARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh
type(ESMF_ArraySpec), intent(in) :: arrayspec
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Index_Flag),intent(in), optional :: indexflag
type(ESMF_MeshLoc), intent(in), optional :: meshloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.19 and 26.3.21.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateMeshArray(mesh, array, &
datacopyflag, meshloc, &
gridToFieldMap, ungriddedLBound, ungriddedUBound, &
name, vm, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateMeshArrayARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh
type(ESMF_Array), intent(in) :: array
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag
type(ESMF_MeshLoc), intent(in), optional :: meshloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
character (len = *), intent(in), optional :: name
type(ESMF_VM), intent(in), optional :: vm
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field. This version of creation assumes the data exists already and is being passed in through an ESMF_Array. For an example and associated documentation using this method see section 26.3.20.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateMeshData<rank><type><kind>(mesh, & farray, indexflag, datacopyflag, meshloc, & gridToFieldMap, ungriddedLBound, ungriddedUBound, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateMeshData<rank><type><kind>ARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh <type> (ESMF_KIND_<kind>),intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_MeshLoc), intent(in), optional :: meshloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data array and ESMF_Mesh. The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateMeshDataPtr<rank><type><kind>(mesh, & farrayPtr, datacopyflag, meshloc, gridToFieldMap, & name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateMeshDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh <type> (ESMF_KIND_<kind>),pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_MeshLoc), intent(in), optional :: meshloc integer, intent(in), optional :: gridToFieldMap(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data pointer and ESMF_Mesh. The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateXGTKR(xgrid, typekind, xgridside, &
gridindex, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateXGTKRARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid
type(ESMF_TypeKind_Flag), intent(in) :: typekind
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside
integer, intent(in), optional :: gridindex
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.16.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateXGArraySpec(xgrid, arrayspec, &
xgridside, gridindex, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
pinflag, name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateXGArraySpecARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid
type(ESMF_ArraySpec), intent(in) :: arrayspec
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_XGridSide_Flag), intent(in), optional :: xgridSide
integer, intent(in), optional :: gridIndex
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
type(ESMF_Pin_Flag), intent(in), optional :: pinflag
character (len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field and allocate space internally for an ESMF_Array. Return a new ESMF_Field. For an example and associated documentation using this method see section 26.3.17.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate()
function ESMF_FieldCreateXGArray(xgrid, array, &
datacopyflag, xgridside, gridindex, &
gridToFieldMap, ungriddedLBound, ungriddedUBound, &
name, rc)
RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateXGArrayARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid
type(ESMF_Array), intent(in) :: array
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag
type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside
integer, intent(in), optional :: gridindex
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
character (len = *), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Create an ESMF_Field. This version of creation assumes the data exists already and is being passed in through an ESMF_Array. For an example and associated documentation using this method see section 26.3.6.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateXGData<rank><type><kind>(xgrid, & farray, indexflag, datacopyflag, xgridside, gridindex, & gridToFieldMap, ungriddedLBound, ungriddedUBound, name,& rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateXGData<rank><type><kind>ARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid <type> (ESMF_KIND_<kind>), intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside integer, intent(in), optional :: gridindex integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data array and ESMF_Xgrid. The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldCreate() function ESMF_FieldCreateXGDataPtr<rank><type><kind>(xgrid, farrayPtr, & datacopyflag, xgridside, & gridindex, gridToFieldMap, name, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldCreateXGDataPtr<rank><type><kind>ARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside integer, intent(in), optional :: gridindex integer, intent(in), optional :: gridToFieldMap(:) character (len=*), intent(in), optional :: name integer, intent(out), optional :: rcDESCRIPTION:
Create an ESMF_Field from a Fortran data pointer and ESMF_Xgrid. The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
subroutine ESMF_FieldDestroy(field, noGarbage, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Destroys the ESMF_Field, releasing the resources associated with the object.
If an ESMF_Grid is associated with field, it will not be released.
By default a small remnant of the object is kept in memory in order to prevent problems with dangling aliases. The default garbage collection mechanism can be overridden with the noGarbage argument.
The arguments are:
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompAS(field, arrayspec, indexflag, & gridToFieldMap, ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, & pinflag, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_ArraySpec), intent(in) :: arrayspec -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_Index_Flag), intent(in), optional :: indexflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) type(ESMF_Pin_Flag), intent(in), optional :: pinflag integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Complete an ESMF_Field and allocate space internally for an ESMF_Array based on arrayspec. The input ESMF_Field must have a status of ESMF_FIELDSTATUS_GRIDSET. After this call the completed ESMF_Field has a status of ESMF_FIELDSTATUS_COMPLETE.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompTK(field, typekind, indexflag, & gridToFieldMap, ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, & pinflag, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_TypeKind_Flag), intent(in) :: typekind -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_Index_Flag), intent(in), optional :: indexflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) type(ESMF_Pin_Flag), intent(in), optional :: pinflag integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Complete an ESMF_Field and allocate space internally for an ESMF_Array based on typekind. The input ESMF_Field must have a status of ESMF_FIELDSTATUS_GRIDSET. After this call the completed ESMF_Field has a status of ESMF_FIELDSTATUS_COMPLETE.
For an example and associated documentation using this method see section 26.3.7.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyComp<rank><type><kind>(field, & farray, indexflag, datacopyflag, gridToFieldMap, & ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field <type> (ESMF_KIND_<kind>),intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Complete an ESMF_Field and allocate space internally for an ESMF_Array based on typekind. The input ESMF_Field must have a status of ESMF_FIELDSTATUS_GRIDSET. After this call the completed ESMF_Field has a status of ESMF_FIELDSTATUS_COMPLETE.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
For an example and associated documentation using this method see section 26.3.8.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompPtr<rank><type><kind>(field, & farrayPtr, datacopyflag, gridToFieldMap, & totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Complete an ESMF_Field and allocate space internally for an ESMF_Array based on typekind. The input ESMF_Field must have a status of ESMF_FIELDSTATUS_GRIDSET. After this call the completed ESMF_Field has a status of ESMF_FIELDSTATUS_COMPLETE.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompGB<rank><type><kind>(field, geom, & farray, indexflag, datacopyflag, gridToFieldMap, ungriddedLBound, & ungriddedUBound, totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Geom), intent(in) :: geom <type> (ESMF_KIND_<kind>), dimension(<rank>), target :: farray type(ESMF_Index_Flag), intent(in) :: indexflag type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call. For an example and associated documentation using this method see section 26.3.7.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompGBPtr<rank><type><kind>(field, geom, & farrayPtr, datacopyflag, gridToFieldMap, & totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inou) :: field type(ESMF_Geom), intent(in) :: geom <type> (ESMF_KIND_<kind>), dimension(<rank>), pointer :: farrayPtr type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call. For an example and associated documentation using this method see section 26.3.7.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompGrid<rank><type><kind>(field, grid, & farray, indexflag, datacopyflag, staggerloc, gridToFieldMap, & ungriddedLBound, ungriddedUBound, totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Grid), intent(in) :: grid <type> (ESMF_KIND_<kind>),intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_STAGGERLOC), intent(in), optional :: staggerloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompGridPtr<rank><type><kind>(field, grid, & farrayPtr, datacopyflag, staggerloc, gridToFieldMap, & totalLWidth, totalUWidth, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Grid), intent(in) :: grid <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_STAGGERLOC), intent(in), optional :: staggerloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: totalLWidth(:) integer, intent(in), optional :: totalUWidth(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management. The Fortran data pointer inside ESMF_Field can be queried and deallocated when
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompLS<rank><type><kind>(field, locstream, & farray, indexflag, datacopyflag, gridToFieldMap, & ungriddedLBound, ungriddedUBound, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_LocStream), intent(in) :: locstream <type> (ESMF_KIND_<kind>), intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompLSPtr<rank><type><kind>(field, locstream, & farrayPtr, datacopyflag, gridToFieldMap, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_LocStream), intent(in) :: locstream <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag integer, intent(in), optional :: gridToFieldMap(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompMesh<rank><type><kind>(field, mesh, & farray, indexflag, datacopyflag, meshloc, & gridToFieldMap, ungriddedLBound, ungriddedUBound, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Mesh), intent(in) :: mesh <type> (ESMF_KIND_<kind>), intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_MeshLoc), intent(in), optional :: meshloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompMeshPtr<rank><type><kind>(field, mesh, & farrayPtr, datacopyflag, meshloc, gridToFieldMap, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Mesh), intent(in) :: mesh <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_MeshLoc), intent(in), optional :: meshloc integer, intent(in), optional :: gridToFieldMap(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompXG<rank><type><kind>(field, xgrid, & farray, indexflag, datacopyflag, xgridside, gridindex, & gridToFieldMap, & ungriddedLBound, ungriddedUBound, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_XGrid), intent(in) :: xgrid <type> (ESMF_KIND_<kind>), intent(in), target :: farray(<rank>) type(ESMF_Index_Flag), intent(in) :: indexflag -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside integer, intent(in), optional :: gridindex integer, intent(in), optional :: gridToFieldMap(:) integer, intent(in), optional :: ungriddedLBound(:) integer, intent(in), optional :: ungriddedUBound(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried but deallocating the retrieved data pointer is not allowed.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptyComplete() subroutine ESMF_FieldEmptyCompXGPtr<rank><type><kind>(field, xgrid, & farrayPtr, xgridside, gridindex, & datacopyflag, gridToFieldMap, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_XGrid), intent(in) :: xgrid <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_DataCopy_Flag), intent(in), optional :: datacopyflag type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside integer, intent(in), optional :: gridindex integer, intent(in), optional :: gridToFieldMap(:) integer, intent(out), optional :: rcDESCRIPTION:
This call completes an ESMF_Field allocated with the ESMF_FieldEmptyCreate() call.
The Fortran data pointer inside ESMF_Field can be queried and deallocated when datacopyflag is ESMF_DATACOPY_REFERENCE. Note that the ESMF_FieldDestroy call does not deallocate the Fortran data pointer in this case. This gives user more flexibility over memory management.
The arguments are:
INTERFACE:
function ESMF_FieldEmptyCreate(name, vm, rc)RETURN VALUE:
type(ESMF_Field) :: ESMF_FieldEmptyCreateARGUMENTS:
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character (len = *), intent(in), optional :: name
type(ESMF_VM), intent(in), optional :: vm
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
This version of ESMF_FieldCreate builds an empty ESMF_Field and depends on later calls to add an ESMF_Grid and ESMF_Array to it. The empty ESMF_Field can be completed in one more step or two more steps by the ESMF_FieldEmptySet and ESMF_FieldEmptyComplete methods. Attributes can be added to an empty Field object. For an example and associated documentation using this method see section 26.3.8 and 26.3.7.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptySet() subroutine ESMF_FieldEmptySetGeom(field, geom, vm, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Geom), intent(in) :: geom -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_VM), intent(in), optional :: vm integer, intent(out), optional :: rcDESCRIPTION:
Set a geom in a non-completed ESMF_Field. The ESMF_Field must not be completed for this to succeed. After this operation, the ESMF_Field contains the ESMF_Geom internally but holds no data. The status of the field changes from ESMF_FIELDSTATUS_EMPTY to ESMF_FIELDSTATUS_GRIDSET or stays ESMF_FIELDSTATUS_GRIDSET.
For an example and associated documentation using this method see section 26.3.7.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptySet()
subroutine ESMF_FieldEmptySetGrid(field, grid, StaggerLoc, &
vm, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Grid), intent(in) :: grid -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_STAGGERLOC), intent(in), optional :: StaggerLoc type(ESMF_VM), intent(in), optional :: vm integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Set a grid and an optional staggerloc (default to center stagger ESMF_STAGGERLOC_CENTER) in a non-completed ESMF_Field. The ESMF_Field must not be completed for this to succeed. After this operation, the ESMF_Field contains the ESMF_Grid internally but holds no data. The status of the field changes from ESMF_FIELDSTATUS_EMPTY to ESMF_FIELDSTATUS_GRIDSET or stays ESMF_FIELDSTATUS_GRIDSET.
For an example and associated documentation using this method see section 26.3.7.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptySet() subroutine ESMF_FieldEmptySetMesh(field, mesh, indexflag, meshloc, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_Mesh), intent(in) :: mesh -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_Index_Flag),intent(in), optional :: indexflag type(ESMF_MeshLoc), intent(in), optional :: meshloc integer, intent(out), optional :: rcDESCRIPTION:
Set a mesh and an optional meshloc (default to center stagger ESMF_MESHLOC_NODE) in a non-completed ESMF_Field. The ESMF_Field must not be completed for this to succeed. After this operation, the ESMF_Field contains the ESMF_Mesh internally but holds no data. The status of the field changes from ESMF_FIELDSTATUS_EMPTY to ESMF_FIELDSTATUS_GRIDSET or stays ESMF_FIELDSTATUS_GRIDSET.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptySet()
subroutine ESMF_FieldEmptySetLocStream(field, locstream, &
vm, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_LocStream), intent(in) :: locstream -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_VM), intent(in), optional :: vm integer, intent(out), optional :: rcDESCRIPTION:
Set a ESMF_LocStream in a non-completed ESMF_Field. The ESMF_Field must not be completed for this to succeed. After this operation, the ESMF_Field contains the ESMF_LocStream internally but holds no data. The status of the field changes from ESMF_FIELDSTATUS_EMPTY to ESMF_FIELDSTATUS_GRIDSET or stays ESMF_FIELDSTATUS_GRIDSET.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldEmptySet() subroutine ESMF_FieldEmptySetXGrid(field, xgrid, xgridside, gridindex, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field type(ESMF_XGrid), intent(in) :: xgrid -- The following arguments require argument keyword syntax (e.g. rc=rc). -- type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside integer, intent(in), optional :: gridindex integer, intent(out), optional :: rcDESCRIPTION:
Set a xgrid and optional xgridside (default to balanced side ESMF_XGRIDSIDE_Balanced) and gridindex (default to 1) in a non-complete ESMF_Field. The ESMF_Field must not be completed for this to succeed. After this operation, the ESMF_Field contains the ESMF_XGrid internally but holds no data. The status of the field changes from ESMF_FIELDSTATUS_EMPTY to ESMF_FIELDSTATUS_GRIDSET or stays ESMF_FIELDSTATUS_GRIDSET.
The arguments are:
INTERFACE:
subroutine ESMF_FieldFill(field, dataFillScheme, &
const1, member, step, &
param1I4, param2I4, param3I4, &
param1R4, param2R4, param3R4, &
param1R8, param2R8, param3R8, &
rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character(len=*), intent(in), optional :: dataFillScheme
real(ESMF_KIND_R8), intent(in), optional :: const1
integer, intent(in), optional :: member
integer, intent(in), optional :: step
integer(ESMF_KIND_I4), intent(in), optional :: param1I4
integer(ESMF_KIND_I4), intent(in), optional :: param2I4
integer(ESMF_KIND_I4), intent(in), optional :: param3I4
real(ESMF_KIND_R4), intent(in), optional :: param1R4
real(ESMF_KIND_R4), intent(in), optional :: param2R4
real(ESMF_KIND_R4), intent(in), optional :: param3R4
real(ESMF_KIND_R8), intent(in), optional :: param1R8
real(ESMF_KIND_R8), intent(in), optional :: param2R8
real(ESMF_KIND_R8), intent(in), optional :: param3R8
integer, intent(out), optional :: rc
DESCRIPTION:
Fill field with data according to dataFillScheme. Depending on the chosen fill scheme, the member and step arguments are used to provide differing fill data patterns.
The arguments are:
INTERFACE:
subroutine ESMF_FieldGather<rank><type><kind>(field, farray, & rootPet, tile, vm, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field <type>(ESMF_KIND_<kind>), intent(out), target :: farray(<rank>) integer, intent(in) :: rootPet -- The following arguments require argument keyword syntax (e.g. rc=rc). -- integer, intent(in), optional :: tile type(ESMF_VM), intent(in), optional :: vm integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Gather the data of an ESMF_Field object into the farray located on rootPET. A single DistGrid tile of array must be gathered into farray. The optional tile argument allows selection of the tile. For Fields defined on a single tile DistGrid the default selection (tile 1) will be correct. The shape of farray must match the shape of the tile in Field.
If the Field contains replicating DistGrid dimensions data will be gathered from the numerically higher DEs. Replicated data elements in numericaly lower DEs will be ignored.
The implementation of Scatter and Gather is not sequence index based. If the Field is built on arbitrarily distributed Grid, Mesh, LocStream or XGrid, Gather will not gather data to rootPet from source data points corresponding to the sequence index on rootPet. Instead Gather will gather a contiguous memory range from source PET to rootPet. The size of the memory range is equal to the number of data elements on the source PET. Vice versa for the Scatter operation. In this case, the user should use ESMF_FieldRedist to achieve the same data operation result. For examples how to use ESMF_FieldRedist to perform Gather and Scatter, please refer to 26.3.32 and 26.3.31.
This version of the interface implements the PET-based blocking paradigm: Each PET of the VM must issue this call exactly once for all of its DEs. The call will block until all PET-local data objects are accessible.
For examples and associated documentation regarding this method see Section 26.3.28.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldGet()
subroutine ESMF_FieldGetDefault(field, arrayspec, &
status, geomtype, grid, mesh, locstream, xgrid, array, localarrayList, &
typekind, dimCount, rank, staggerloc, meshloc, xgridside, &
gridindex, gridToFieldMap, ungriddedLBound, ungriddedUBound, &
totalLWidth, totalUWidth, localDeCount, ssiLocalDeCount, &
localDeToDeMap, minIndex, maxIndex, elementCount, &
localMinIndex, localMaxIndex, localElementCount, isESMFAllocated, &
name, vm, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_ArraySpec), intent(out), optional :: arrayspec
type(ESMF_FieldStatus_Flag),intent(out), optional :: status
type(ESMF_GeomType_Flag), intent(out), optional :: geomtype
type(ESMF_Grid), intent(out), optional :: grid
type(ESMF_Mesh), intent(out), optional :: mesh
type(ESMF_LocStream), intent(out), optional :: locstream
type(ESMF_XGrid), intent(out), optional :: xgrid
type(ESMF_Array), intent(out), optional :: array
type(ESMF_LocalArray), target, intent(out), optional :: localarrayList(:)
type(ESMF_TypeKind_Flag), intent(out), optional :: typekind
integer, intent(out), optional :: dimCount
integer, intent(out), optional :: rank
type(ESMF_StaggerLoc), intent(out), optional :: staggerloc
type(ESMF_MeshLoc), intent(out), optional :: meshloc
type(ESMF_XGridSide_Flag), intent(out), optional :: xgridside
integer, intent(out), optional :: gridindex
integer, intent(out), optional :: gridToFieldMap(:)
integer, intent(out), optional :: ungriddedLBound(:)
integer, intent(out), optional :: ungriddedUBound(:)
integer, intent(out), optional :: totalLWidth(:,:)
integer, intent(out), optional :: totalUWidth(:,:)
integer, intent(out), optional :: localDeCount
integer, intent(out), optional :: ssiLocalDeCount
integer, intent(out), optional :: localDeToDeMap(:)
integer, intent(out), optional :: minIndex(:)
integer, intent(out), optional :: maxIndex(:)
integer, intent(out), optional :: elementCount(:)
integer, intent(out), optional :: localMinIndex(:)
integer, intent(out), optional :: localMaxIndex(:)
integer, intent(out), optional :: localElementCount(:)
logical, intent(out), optional :: isESMFAllocated
character(len=*), intent(out), optional :: name
type(ESMF_VM), intent(out), optional :: vm
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Query an ESMF_Field object for various pieces of information. All arguments after the field argument are optional. To select individual items use the named_argument=value syntax. For an example and associated documentation using this method see section 26.3.3.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldGet() subroutine ESMF_FieldGetDataPtr<rank><type><kind>(field, localDe, & farrayPtr, exclusiveLBound, exclusiveUBound, exclusiveCount, & computationalLBound, computationalUBound, computationalCount, & totalLBound, totalUBound, totalCount, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field -- The following arguments require argument keyword syntax (e.g. rc=rc). -- integer, intent(in), optional :: localDe <type> (ESMF_KIND_<kind>), pointer :: farrayPtr(<rank>) integer, intent(out), optional :: exclusiveLBound(:) integer, intent(out), optional :: exclusiveUBound(:) integer, intent(out), optional :: exclusiveCount(:) integer, intent(out), optional :: computationalLBound(:) integer, intent(out), optional :: computationalUBound(:) integer, intent(out), optional :: computationalCount(:) integer, intent(out), optional :: totalLBound(:) integer, intent(out), optional :: totalUBound(:) integer, intent(out), optional :: totalCount(:) integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Get a Fortran pointer to DE-local memory allocation within field. For convenience DE-local bounds can be queried at the same time. For an example and associated documentation using this method see section 26.3.2.
The arguments are:
INTERFACE:
! Private name; call using ESMF_FieldGetBounds()
subroutine ESMF_FieldGetBounds(field, localDe, &
exclusiveLBound, exclusiveUBound, exclusiveCount, computationalLBound, &
computationalUBound, computationalCount, totalLBound, &
totalUBound, totalCount, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: localDe
integer, intent(out), optional :: exclusiveLBound(:)
integer, intent(out), optional :: exclusiveUBound(:)
integer, intent(out), optional :: exclusiveCount(:)
integer, intent(out), optional :: computationalLBound(:)
integer, intent(out), optional :: computationalUBound(:)
integer, intent(out), optional :: computationalCount(:)
integer, intent(out), optional :: totalLBound(:)
integer, intent(out), optional :: totalUBound(:)
integer, intent(out), optional :: totalCount(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
This method returns the bounds information of a field that consists of a internal grid and a internal array. The exclusive and computational bounds are shared between the grid and the array but the total bounds are the array bounds plus the halo width. The count is the number of elements between each bound pair.
The arguments are:
INTERFACE:
subroutine ESMF_FieldHalo(field, routehandle, &
routesyncflag, finishedflag, checkflag, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_RouteSync_Flag), intent(in), optional :: routesyncflag
logical, intent(out), optional :: finishedflag
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed Field halo operation for field. The field argument must match the Field used during ESMF_FieldHaloStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
See ESMF_FieldHaloStore() on how to precompute routehandle.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_FieldHaloRelease(routehandle, noGarbage, rc)ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a Field halo operation. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
subroutine ESMF_FieldHaloStore(field, routehandle, &
startregion, haloLDepth, haloUDepth, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_StartRegion_Flag), intent(in), optional :: startregion
integer, intent(in), optional :: haloLDepth(:)
integer, intent(in), optional :: haloUDepth(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a Field halo operation over the data in field. By default, i.e. without specifying startregion, haloLDepth and haloUDepth, all elements in the total Field region that lie outside the exclusive region will be considered potential destination elements for halo. However, only those elements that have a corresponding halo source element, i.e. an exclusive element on one of the DEs, will be updated under the halo operation. Elements that have no associated source remain unchanged under halo.
Specifying startregion allows to change the shape of the effective halo region from the inside. Setting this flag to ESMF_STARTREGION_COMPUTATIONAL means that only elements outside the computational region of the Field are considered for potential destination elements for the halo operation. The default is ESMF_STARTREGION_EXCLUSIVE.
The haloLDepth and haloUDepth arguments allow to reduce the extent of the effective halo region. Starting at the region specified by startregion, the haloLDepth and haloUDepth define a halo depth in each direction. Note that the maximum halo region is limited by the total Field region, independent of the actual haloLDepth and haloUDepth setting. The total Field region is local DE specific. The haloLDepth and haloUDepth are interpreted as the maximum desired extent, reducing the potentially larger region available for the halo operation.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldHalo() on any Field that matches field in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
INTERFACE:
function ESMF_FieldIsCreated(field, rc)RETURN VALUE:
logical :: ESMF_FieldIsCreatedARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Return .true. if the field has been created. Otherwise return .false.. If an error occurs, i.e. rc /= ESMF_SUCCESS is returned, the return value of the function will also be .false..
The arguments are:
INTERFACE:
subroutine ESMF_FieldPrint(field, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Prints information about the field to stdout. This subroutine goes through the internal data members of a field data type and prints information of each data member.
The arguments are:
INTERFACE:
subroutine ESMF_FieldRead(field, fileName, &
variableName, timeslice, iofmt, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
character(*), intent(in) :: fileName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character(*), intent(in), optional :: variableName
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
DESCRIPTION:
Read Field data from a file and put it into an ESMF_Field object. For this API to be functional, the environment variable ESMF_PIO should be set to either "internal" or "external" when the ESMF library is built. Please see the section on Data I/O, 38.2.
Limitations:
The arguments are:
INTERFACE:
subroutine ESMF_FieldRedist(srcField, dstField, routehandle, &
checkflag, rc)
ARGUMENTS:
type(ESMF_Field), intent(in),optional :: srcField
type(ESMF_Field), intent(inout),optional :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed Field redistribution from srcField to dstField. Both srcField and dstField must match the respective Fields used during ESMF_FieldRedistStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcField and dstField arguments are optional in support of the situation where srcField and/or dstField are not defined on all PETs. The srcField and dstField must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
See ESMF_FieldRedistStore() on how to precompute routehandle.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.30.
INTERFACE:
subroutine ESMF_FieldRedistRelease(routehandle, noGarbage, rc)ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a Field redistribution. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldRedistStore()
subroutine ESMF_FieldRedistStore<type><kind>(srcField, dstField, &
routehandle, factor, srcToDstTransposeMap, &
ignoreUnmatchedIndices, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
<type>(ESMF_KIND_<kind>), intent(in) :: factor
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: srcToDstTransposeMap(:)
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
ESMF_FieldRedistStore() is a collective method across all PETs of the current Component. The interface of the method is overloaded, allowing - in principle - each PET to call into ESMF_FieldRedistStore() through a different entry point. Restrictions apply as to which combinations are sensible. All other combinations result in ESMF run time errors. The complete semantics of the ESMF_FieldRedistStore() method, as provided through the separate entry points shown in 26.6.63 and 26.6.64, is described in the following paragraphs as a whole.
Store a Field redistribution operation from srcField to dstField. Interface 26.6.63 allows PETs to specify a factor argument. PETs not specifying a factor argument call into interface 26.6.64. If multiple PETs specify the factor argument, its type and kind, as well as its value must match across all PETs. If none of the PETs specify a factor argument the default will be a factor of 1. The resulting factor is applied to all of the source data during redistribution, allowing scaling of the data, e.g. for unit transformation.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices.
Source Field, destination Field, and the factor may be of different <type><kind>. Further, source and destination Fields may differ in shape, however, the number of elements must match.
The default redistribution operation, when srcToDstTransposeMap is not specified, corresponds to the identity mapping: each element of the sequentialized source Field is copied to the sequentialized destination Field element in order.
If the srcToDstTransposeMap argument is provided it must be identical across all PETs. The srcToDstTransposeMap allows source and destination Field dimensions to be transposed during the redistribution. To support this option, the number of source and destination Field dimensions must be equal and the size of the associated dimensions must match. See section 28.2.17 for more details about the use of the srcToDstTransposeMap argument.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldRedist() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.30.
The arguments are:
elements in
srcToDstTransposeMap, each block of size rank is associated
with the corresponding tile (in order), and interpreted as the
tile-specific transpose map.
INTERFACE:
! Private name; call using ESMF_FieldRedistStore()
subroutine ESMF_FieldRedistStoreNF(srcField, dstField, &
routehandle, srcToDstTransposeMap, &
ignoreUnmatchedIndices, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: srcToDstTransposeMap(:)
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
ESMF_FieldRedistStore() is a collective method across all PETs of the current Component. The interface of the method is overloaded, allowing - in principle - each PET to call into ESMF_FieldRedistStore() through a different entry point. Restrictions apply as to which combinations are sensible. All other combinations result in ESMF run time errors. The complete semantics of the ESMF_FieldRedistStore() method, as provided through the separate entry points shown in 26.6.63 and 26.6.64, is described in the following paragraphs as a whole.
Store a Field redistribution operation from srcField to dstField. Interface 26.6.63 allows PETs to specify a factor argument. PETs not specifying a factor argument call into interface 26.6.64. If multiple PETs specify the factor argument, its type and kind, as well as its value must match across all PETs. If none of the PETs specify a factor argument the default will be a factor of 1. The resulting factor is applied to all of the source data during redistribution, allowing scaling of the data, e.g. for unit transformation.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices.
Source Field, destination Field, and the factor may be of different <type><kind>. Further, source and destination Fields may differ in shape, however, the number of elements must match.
The default redistribution operation, when srcToDstTransposeMap is not specified, corresponds to the identity mapping: each element of the sequentialized source Field is copied to the sequentialized destination Field element in order.
If the srcToDstTransposeMap argument is provided it must be identical across all PETs. The srcToDstTransposeMap allows source and destination Field dimensions to be transposed during the redistribution. To support this option, the number of source and destination Field dimensions must be equal and the size of the associated dimensions must match. See section 28.2.17 for more details about the use of the srcToDstTransposeMap argument.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldRedist() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.30.
The arguments are:
elements in
srcToDstTransposeMap, each block of size rank is associated
with the corresponding tile (in order), and interpreted as the
tile-specific transpose map.
INTERFACE:
subroutine ESMF_FieldRegrid(srcField, dstField, routehandle, &
zeroregion, termorderflag, checkflag, dynamicMask, rc)
ARGUMENTS:
type(ESMF_Field), intent(in), optional :: srcField
type(ESMF_Field), intent(inout), optional :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Region_Flag), intent(in), optional :: zeroregion
type(ESMF_TermOrder_Flag), intent(in), optional :: termorderflag
logical, intent(in), optional :: checkflag
type(ESMF_DynamicMask), target, intent(in), optional :: dynamicMask
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute the precomputed regrid operation stored in routehandle to interpolate from srcField to dstField. See ESMF_FieldRegridStore() on how to precompute the routehandle.
Both srcField and dstField must match the respective Fields used during ESMF_FieldRegridStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcField and dstField arguments are optional in support of the situation where srcField and/or dstField are not defined on all PETs. The srcField and dstField must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_FieldRegridRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a regrid operation. After this call routehandle becomes invalid.
The arguments are:
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldRegridStore()
subroutine ESMF_FieldRegridStoreNX(srcField, dstField, &
srcMaskValues, dstMaskValues, &
regridmethod, &
polemethod, regridPoleNPnts, &
lineType, &
normType, &
vectorRegrid, &
extrapMethod, &
extrapNumSrcPnts, &
extrapDistExponent, &
extrapNumLevels, &
unmappedaction, ignoreDegenerate, &
srcTermProcessing, &
pipeLineDepth, &
routehandle, &
factorList, factorIndexList, &
weights, indices, & ! DEPRECATED ARGUMENTS
srcFracField, dstFracField, &
dstStatusField, &
unmappedDstList, &
checkFlag, &
rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer(ESMF_KIND_I4), intent(in), optional :: srcMaskValues(:)
integer(ESMF_KIND_I4), intent(in), optional :: dstMaskValues(:)
type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod
type(ESMF_PoleMethod_Flag), intent(in), optional :: polemethod
integer, intent(in), optional :: regridPoleNPnts
type(ESMF_LineType_Flag), intent(in), optional :: lineType
type(ESMF_NormType_Flag), intent(in), optional :: normType
logical, intent(in), optional :: vectorRegrid
type(ESMF_ExtrapMethod_Flag), intent(in), optional :: extrapMethod
integer, intent(in), optional :: extrapNumSrcPnts
real(ESMF_KIND_R4), intent(in), optional :: extrapDistExponent
integer, intent(in), optional :: extrapNumLevels
type(ESMF_UnmappedAction_Flag), intent(in), optional :: unmappedaction
logical, intent(in), optional :: ignoreDegenerate
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
type(ESMF_RouteHandle), intent(inout), optional :: routehandle
real(ESMF_KIND_R8), pointer, optional :: factorList(:)
integer(ESMF_KIND_I4), pointer, optional :: factorIndexList(:,:)
real(ESMF_KIND_R8), pointer, optional :: weights(:) ! DEPRECATED ARG
integer(ESMF_KIND_I4), pointer, optional :: indices(:,:) ! DEPRECATED ARG
type(ESMF_Field), intent(inout), optional :: srcFracField
type(ESMF_Field), intent(inout), optional :: dstFracField
type(ESMF_Field), intent(inout), optional :: dstStatusField
integer(ESMF_KIND_I4), pointer, optional :: unmappedDstList(:)
logical, intent(in), optional :: checkFlag
integer, intent(out), optional :: rc
STATUS:
Added arguments extrapMethod, extrapNumSrcPnts, and extrapDistExponent. These three new extrapolation arguments allow the user to extrapolate destination points not mapped by the regrid method. extrapMethod allows the user to choose the extrapolation method. extrapNumSrcPnts and extrapDistExponent are parameters that allow the user to tune the behavior of the ESMF_EXTRAPMETHOD_NEAREST_IDAVG method.
DESCRIPTION:
Creates a sparse matrix operation (stored in routehandle) that contains the calculations and communications necessary to interpolate from srcField to dstField. The routehandle can then be used in the call ESMF_FieldRegrid() to interpolate between the Fields. The user may also get the interpolation matrix in sparse matrix form via the optional arguments factorList and factorIndexList.
The routehandle generated by this call is based just on the coordinates in the spatial class (e.g. Grid) contained in the Fields. If those coordinates don't change the routehandle can be used repeatedly to interpolate from the source Field to the destination Field. This is true even if the data in the Fields changes. The routehandle may also be used to interpolate between any source and destination Field which are created on the same location in the same Grid, LocStream, XGrid, or Mesh as the original Fields.
When it's no longer needed the routehandle should be destroyed by using ESMF_FieldRegridRelease() to free the memory it's using.
Note, as a side effect, that this call may change the data in dstField. If this is undesirable, then an easy work around is to create a second temporary field with the same structure as dstField and pass that in instead.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldRegridStore()
subroutine ESMF_FieldRegridStoreX(xgrid, srcField, dstField, &
regridmethod, &
srcTermProcessing, pipeLineDepth, &
routehandle, &
srcFracField, dstFracField, &
srcMergeFracField, dstMergeFracField, rc)
ARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_RegridMethod_Flag), intent(in), optional :: regridmethod
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
type(ESMF_RouteHandle), intent(inout), optional :: routehandle
type(ESMF_Field), intent(inout), optional :: srcFracField
type(ESMF_Field), intent(inout), optional :: dstFracField
type(ESMF_Field), intent(inout), optional :: srcMergeFracField
type(ESMF_Field), intent(inout), optional :: dstMergeFracField
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
This method creates a RouteHandle to do conservative interpolation specifically between a Field built on an XGrid and a Field build on one of the Grids or Meshes used to create that XGrid. (To do more general interpolation use the ESMF_FieldRegridStore() method in section 26.6.67.) The RouteHandle produced by this method can then be used in the call ESMF_FieldRegrid() to interpolate from the srcField to the dstField.
The RouteHandle generated by this call is based just on the coordinates in the Grids, XGrids, or Meshes contained in the Fields. If those coordinates don't change the RouteHandle can be used repeatedly to interpolate from the source Field to the destination Field. This is true even if the data in the Fields changes. The RouteHandle may also be used to interpolate between any source and destination Field which are created on the same Grid, XGrid, or Mesh as the original Fields.
When it's no longer needed the RouteHandle should be destroyed by using ESMF_FieldRegridRelease() to free the memory it's using.
Note, as a side effect, that this call may change the data in dstField. If this is undesirable, then an easy work around is to create a second temporary Field with the same structure as dstField and pass that in instead.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldRegridStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
subroutine ESMF_FieldRegridGetArea(areaField, rc)RETURN VALUE:
ARGUMENTS:
type(ESMF_Field), intent(inout) :: areaField
integer, intent(out), optional :: rc
DESCRIPTION:
This subroutine gets the area of the cells used for conservative interpolation for the grid object associated with areaField and puts them into areaField. If created on a 2D Grid, it must be built on the ESMF_STAGGERLOC_CENTER stagger location. If created on a 3D Grid, it must be built on the ESMF_STAGGERLOC_CENTER_VCENTER stagger location. If created on a Mesh, it must be built on the ESMF_MESHLOC_ELEMENT mesh location.
If the user has set the area in the Grid, Mesh, or XGrid under areaField, then that's the area that's returned in the units that the user set it in. If the user hasn't set the area, then the area is calculated and returned. If the Grid, Mesh, or XGrid is on the surface of a sphere, then the calculated area is in units of square radians. If the Grid, Mesh, or XGrid is Cartesian, then the calculated area is in square units of whatever unit the coordinates are in.
The arguments are:
INTERFACE:
subroutine ESMF_FieldScatter<rank><type><kind>(field, farray, & rootPet, tile, vm, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field mtype (ESMF_KIND_mtypekind),intent(in), target :: farray(mdim) integer, intent(in) :: rootPet -- The following arguments require argument keyword syntax (e.g. rc=rc). -- integer, intent(in), optional :: tile type(ESMF_VM), intent(in), optional :: vm integer, intent(out), optional :: rcSTATUS:
DESCRIPTION:
Scatter the data of farray located on rootPET across an ESMF_Field object. A single farray must be scattered across a single DistGrid tile in Field. The optional tile argument allows selection of the tile. For Fields defined on a single tile DistGrid the default selection (tile 1) will be correct. The shape of farray must match the shape of the tile in Field.
If the Field contains replicating DistGrid dimensions data will be scattered across all of the replicated pieces.
The implementation of Scatter and Gather is not sequence index based. If the Field is built on arbitrarily distributed Grid, Mesh, LocStream or XGrid, Scatter will not scatter data from rootPet to the destination data points corresponding to the sequence index on the rootPet. Instead Scatter will scatter a contiguous memory range from rootPet to destination PET. The size of the memory range is equal to the number of data elements on the destination PET. Vice versa for the Gather operation. In this case, the user should use ESMF_FieldRedist to achieve the same data operation result. For examples how to use ESMF_FieldRedist to perform Gather and Scatter, please refer to 26.3.32 and 26.3.31.
This version of the interface implements the PET-based blocking paradigm: Each PET of the VM must issue this call exactly once for all of its DEs. The call will block until all PET-local data objects are accessible.
For examples and associated documentation regarding this method see Section 26.3.29.
The arguments are:
INTERFACE:
subroutine ESMF_FieldSet(field, name, rc)ARGUMENTS:
type(ESMF_Field), intent(inout) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character(len = *), intent(in), optional :: name
integer, intent(out), optional :: rc
DESCRIPTION:
Sets adjustable settings in an ESMF_Field object.
The arguments are:
INTERFACE:
subroutine ESMF_FieldSync(field, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Synchronizes access to DEs across field to make sure PETs correctly access the data for read and write when DEs are shared.
The arguments are:
INTERFACE:
subroutine ESMF_FieldSMM(srcField, dstField, routehandle, &
zeroregion, termorderflag, checkflag, rc)
ARGUMENTS:
type(ESMF_Field), intent(in), optional :: srcField
type(ESMF_Field), intent(inout), optional :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Region_Flag), intent(in), optional :: zeroregion
type(ESMF_TermOrder_Flag), intent(in), optional :: termorderflag
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed Field sparse matrix multiplication from srcField to dstField. Both srcField and dstField must match the respective Fields used during ESMF_FieldSMMStore() in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
The srcField and dstField arguments are optional in support of the situation where srcField and/or dstField are not defined on all PETs. The srcField and dstField must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
See ESMF_FieldSMMStore() on how to precompute routehandle.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.33.
sparse matrix multiplication
INTERFACE:
subroutine ESMF_FieldSMMRelease(routehandle, noGarbage, rc)ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with a Field sparse matrix multiplication. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStore<type><kind>(srcField, dstField, &
routehandle, factorList, factorIndexList, &
ignoreUnmatchedIndices, srcTermProcessing, pipelineDepth, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
<type>(ESMF_KIND_<kind>), intent(in) :: factorList(:)
integer, intent(in), :: factorIndexList(:,:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a Field sparse matrix multiplication operation from srcField to dstField. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source Field vector to the destination Field vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldSMM() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.33.
The arguments are:
The second dimension of factorIndexList steps through the list of pairs, i.e. size(factorIndexList,2) == size(factorList). The first dimension of factorIndexList is either of size 2 or size 4. The second dimension of factorIndexList steps through the list of
In the size 2 format factorIndexList(1,:) specifies the sequence index of the source element in the srcField while factorIndexList(2,:) specifies the sequence index of the destination element in dstField. For this format to be a valid option source and destination Fields must have matching number of tensor elements (the product of the sizes of all Field tensor dimensions). Under this condition an identity matrix can be applied within the space of tensor elements for each sparse matrix factor.
The size 4 format is more general and does not require a matching tensor element count. Here the factorIndexList(1,:) specifies the sequence index while factorIndexList(2,:) specifies the tensor sequence index of the source element in the srcField. Further factorIndexList(3,:) specifies the sequence index and factorIndexList(4,:) specifies the tensor sequence index of the destination element in the dstField.
See section 28.2.18 for details on the definition of Field sequence indices and tensor sequence indices.
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStore<type><kind>TR(srcField, dstField, &
routehandle, transposeRoutehandle, factorList, factorIndexList, &
ignoreUnmatchedIndices, srcTermProcessing, &
pipelineDepth, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_RouteHandle), intent(inout) :: transposeRoutehandle
<type>(ESMF_KIND_<kind>), intent(in) :: factorList(:)
integer, intent(in), :: factorIndexList(:,:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
DESCRIPTION:
Store a Field sparse matrix multiplication operation from srcField to dstField. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source Field vector to the destination Field vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldSMM() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.33.
The arguments are:
The second dimension of factorIndexList steps through the list of pairs, i.e. size(factorIndexList,2) == size(factorList). The first dimension of factorIndexList is either of size 2 or size 4. The second dimension of factorIndexList steps through the list of
In the size 2 format factorIndexList(1,:) specifies the sequence index of the source element in the srcField while factorIndexList(2,:) specifies the sequence index of the destination element in dstField. For this format to be a valid option source and destination Fields must have matching number of tensor elements (the product of the sizes of all Field tensor dimensions). Under this condition an identity matrix can be applied within the space of tensor elements for each sparse matrix factor.
The size 4 format is more general and does not require a matching tensor element count. Here the factorIndexList(1,:) specifies the sequence index while factorIndexList(2,:) specifies the tensor sequence index of the source element in the srcField. Further factorIndexList(3,:) specifies the sequence index and factorIndexList(4,:) specifies the tensor sequence index of the destination element in the dstField.
See section 28.2.18 for details on the definition of Field sequence indices and tensor sequence indices.
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStoreNF(srcField, dstField, &
routehandle, ignoreUnmatchedIndices, &
srcTermProcessing, pipelineDepth, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store a Field sparse matrix multiplication operation from srcField to dstField. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source Field vector to the destination Field vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldSMM() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.33.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStoreNFTR(srcField, dstField, &
routehandle, transposeRoutehandle, ignoreUnmatchedIndices, &
srcTermProcessing, pipelineDepth, rc)
ARGUMENTS:
type(ESMF_Field), intent(inout) :: srcField
type(ESMF_Field), intent(inout) :: dstField
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_RouteHandle), intent(inout) :: transposeRoutehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
DESCRIPTION:
Store a Field sparse matrix multiplication operation from srcField to dstField. PETs that specify non-zero matrix coefficients must use the <type><kind> overloaded interface and provide the factorList and factorIndexList arguments. Providing factorList and factorIndexList arguments with size(factorList) = (/0/) and size(factorIndexList) = (/2,0/) or (/4,0/) indicates that a PET does not provide matrix elements. Alternatively, PETs that do not provide matrix elements may also call into the overloaded interface without factorList and factorIndexList arguments.
Both srcField and dstField are interpreted as sequentialized vectors. The sequence is defined by the order of DistGrid dimensions and the order of tiles within the DistGrid or by user-supplied arbitrary sequence indices. See section 28.2.18 for details on the definition of sequence indices. SMM corresponds to an identity mapping of the source Field vector to the destination Field vector.
Source and destination Fields may be of different <type><kind>. Further source and destination Fields may differ in shape, however, the number of elements must match.
It is erroneous to specify the identical Field object for srcField and dstField arguments.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_FieldSMM() on any pair of Fields that matches srcField and dstField in type, kind, and memory layout of the gridded dimensions. However, the size, number, and index order of ungridded dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
For examples and associated documentation regarding this method see Section 26.3.33.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit reproducibility of the results. However, it may affect the performance reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStoreFromFile(srcField, dstField, filename, &
routehandle, ignoreUnmatchedIndices, &
srcTermProcessing, pipelineDepth, rc)
! ARGUMENTS:
type(ESMF_Field), intent(in) :: srcField
type(ESMF_Field), intent(inout) :: dstField
character(len=*), intent(in) :: filename
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
DESCRIPTION:
Compute an ESMF_RouteHandle using factors read from file.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit
reproducibility of the results. However, it may affect the performance
reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
! Private name; call using ESMF_FieldSMMStore()
subroutine ESMF_FieldSMMStoreFromFileTR(srcField, dstField, filename, &
routehandle, transposeRoutehandle, &
ignoreUnmatchedIndices, srcTermProcessing, pipelineDepth, rc)
! ARGUMENTS:
type(ESMF_Field), intent(inout) :: srcField
type(ESMF_Field), intent(inout) :: dstField
character(len=*), intent(in) :: filename
type(ESMF_RouteHandle), intent(inout) :: routehandle
type(ESMF_RouteHandle), intent(inout) :: transposeRoutehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndices
integer, intent(inout), optional :: srcTermProcessing
integer, intent(inout), optional :: pipeLineDepth
integer, intent(out), optional :: rc
DESCRIPTION:
Compute an ESMF_RouteHandle using factors read from file.
The arguments are:
Note that partial sums may lead to bit-for-bit differences in the results. See section 37.2.1 for an in-depth discussion of all bit-for-bit reproducibility aspects related to route-based communication methods.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the srcTermProcessing parameter. The intent on the
srcTermProcessing argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
srcTermProcessing parameter, and the auto-tuning phase is skipped.
In this case the srcTermProcessing argument is not modified on
return. If the provided argument is , the srcTermProcessing
parameter is determined internally using the auto-tuning scheme. In this
case the srcTermProcessing argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
srcTermProcessing argument is omitted.
Note that the pipeline depth has no effect on the bit-for-bit
reproducibility of the results. However, it may affect the performance
reproducibility of the exchange.
The ESMF_FieldSMMStore() method implements an auto-tuning scheme
for the pipelineDepth parameter. The intent on the
pipelineDepth argument is "inout" in order to
support both overriding and accessing the auto-tuning parameter.
If an argument is specified, it is used for the
pipelineDepth parameter, and the auto-tuning phase is skipped.
In this case the pipelineDepth argument is not modified on
return. If the provided argument is , the pipelineDepth
parameter is determined internally using the auto-tuning scheme. In this
case the pipelineDepth argument is re-set to the internally
determined value on return. Auto-tuning is also used if the optional
pipelineDepth argument is omitted.
INTERFACE:
subroutine ESMF_FieldValidate(field, rc)ARGUMENTS:
type(ESMF_Field), intent(in) :: field
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Validates that the field is internally consistent. Currently this method determines if the field is uninitialized or already destroyed. It validates the contained array and grid objects. The code also checks if the array and grid sizes agree. This check compares the distgrid contained in array and grid; then it proceeds to compare the computational bounds contained in array and grid.
The method returns an error code if problems are found.
The arguments are:
INTERFACE:
subroutine ESMF_FieldWrite(field, fileName, &
variableName, convention, purpose, overwrite, status, timeslice, iofmt, rc)
ARGUMENTS:
type(ESMF_Field), intent(in) :: field
character(*), intent(in) :: fileName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
character(*), intent(in), optional :: variableName
character(*), intent(in), optional :: convention
character(*), intent(in), optional :: purpose
logical, intent(in), optional :: overwrite
type(ESMF_FileStatus_Flag), intent(in), optional :: status
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
DESCRIPTION:
Write Field data into a file. For this API to be functional, the environment variable ESMF_PIO should be set to either "internal" or "external" when the ESMF library is built. Please see the section on Data I/O, 38.2.
When convention and purpose arguments are specified, a NetCDF variable can be created with user-specified dimension labels and attributes. Dimension labels may be defined for both gridded and ungridded dimensions. Dimension labels for gridded dimensions are specified at the Grid level by attaching an ESMF Attribute package to it. The Attribute package must contain an attribute named by the pre-defined ESMF parameter ESMF_ATT_GRIDDED_DIM_LABELS. The corresponding value is an array of character strings specifying the desired names of the dimensions. Likewise, for ungridded dimensions, an Attribute package is attached at the Field level. The name of the name must be ESMF_ATT_UNGRIDDED_DIM_LABELS.
NetCDF attributes for the variable can also be specified. As with dimension labels, an Attribute package is added to the Field with the desired names and values. A value may be either a scalar character string, or a scalar or array of type integer, real, or double precision. Dimension label attributes can co-exist with variable attributes within a common Attribute package.
Limitations:
The arguments are:
INTERFACE:
subroutine ESMF_GridGetFieldBounds(grid, &
localDe, staggerloc, gridToFieldMap, &
ungriddedLBound, ungriddedUBound, &
totalLWidth, totalUWidth, &
totalLBound, totalUBound, totalCount, rc)
ARGUMENTS:
type(ESMF_Grid), intent(in) :: grid
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: localDe
type(ESMF_StaggerLoc), intent(in), optional :: staggerloc
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(in), optional :: totalLWidth(:)
integer, intent(in), optional :: totalUWidth(:)
integer, intent(out), optional :: totalLBound(:)
integer, intent(out), optional :: totalUBound(:)
integer, intent(out), optional :: totalCount(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Compute the lower and upper bounds of Fortran data array that can later be used in FieldCreate interface to create a ESMF_Field from a ESMF_Grid and the Fortran data array. For an example and associated documentation using this method see section 26.3.9.
The arguments are:
INTERFACE:
subroutine ESMF_LocStreamGetFieldBounds(locstream, &
localDe, gridToFieldMap, &
ungriddedLBound, ungriddedUBound, &
totalLBound, totalUBound, totalCount, rc)
ARGUMENTS:
type(ESMF_LocStream), intent(in) :: locstream
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(in), optional :: localDe
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(out), optional :: totalLBound(:)
integer, intent(out), optional :: totalUBound(:)
integer, intent(out), optional :: totalCount(:)
integer, intent(out), optional :: rc
DESCRIPTION:
Compute the lower and upper bounds of Fortran data array that can later be used in FieldCreate interface to create a ESMF_Field from a ESMF_LocStream and the Fortran data array. For an example and associated documentation using this method see section 26.3.9.
The arguments are:
INTERFACE:
subroutine ESMF_MeshGetFieldBounds(mesh, &
meshloc, &
localDe, gridToFieldMap, &
ungriddedLBound, ungriddedUBound, &
totalLBound, totalUBound, totalCount, rc)
ARGUMENTS:
type(ESMF_Mesh), intent(in) :: mesh
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_MeshLoc),intent(in),optional :: meshloc
integer, intent(in), optional :: localDe
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(out), optional :: totalLBound(:)
integer, intent(out), optional :: totalUBound(:)
integer, intent(out), optional :: totalCount(:)
integer, intent(out), optional :: rc
DESCRIPTION:
Compute the lower and upper bounds of Fortran data array that can later be used in FieldCreate interface to create a ESMF_Field from a ESMF_Mesh and the Fortran data array. For an example and associated documentation using this method see section 26.3.9.
The arguments are:
INTERFACE:
subroutine ESMF_XGridGetFieldBounds(xgrid, &
xgridside, gridindex, localDe, gridToFieldMap, &
ungriddedLBound, ungriddedUBound, &
totalLBound, totalUBound, totalCount, rc)
ARGUMENTS:
type(ESMF_XGrid), intent(in) :: xgrid
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_XGridSide_Flag), intent(in), optional :: xgridside
integer, intent(in), optional :: gridindex
integer, intent(in), optional :: localDe
integer, intent(in), optional :: gridToFieldMap(:)
integer, intent(in), optional :: ungriddedLBound(:)
integer, intent(in), optional :: ungriddedUBound(:)
integer, intent(out), optional :: totalLBound(:)
integer, intent(out), optional :: totalUBound(:)
integer, intent(out), optional :: totalCount(:)
integer, intent(out), optional :: rc
DESCRIPTION:
Compute the lower and upper bounds of Fortran data array that can later be used in FieldCreate interface to create a ESMF_Field from a ESMF_XGrid and the Fortran data array. For an example and associated documentation using this method see section 26.3.9.
The arguments are:
The ESMF_ArrayBundle class allows a set of Arrays to be bundled into a single object. The Arrays in an ArrayBundle may be of different type, kind, rank and distribution. Besides ease of use resulting from bundling, the ArrayBundle class offers the opportunity for performance optimization when operating on a bundle of Arrays as a single entity. Communication methods are especially good candidates for performance optimization. Best optimization results are expected for ArrayBundles that contain Arrays that share a common distribution, i.e. DistGrid, and are of same type, kind and rank.
ArrayBundles are one of the data objects that can be added to States, which are used for providing to or receiving data from other Components.
Examples of creating, destroying and accessing ArrayBundles and their constituent Arrays are provided in this section, along with some notes on ArrayBundle methods.
An ArrayBundle is created from a list of ESMF_Array objects.
call ESMF_ArraySpecSet(arrayspec, typekind=ESMF_TYPEKIND_R8, rank=2, rc=rc)
distgrid = ESMF_DistGridCreate(minIndex=(/1,1/), maxIndex=(/5,5/), &
regDecomp=(/2,3/), rc=rc)
allocate(arrayList(2))
arrayList(1) = ESMF_ArrayCreate(arrayspec=arrayspec, distgrid=distgrid, &
rc=rc)
arrayList(2) = ESMF_ArrayCreate(arrayspec=arrayspec, distgrid=distgrid, &
rc=rc)
Now arrayList is used to create an ArrayBundle object.
arraybundle = ESMF_ArrayBundleCreate(arrayList=arrayList, &
name="MyArrayBundle", rc=rc)
Here the temporary arrayList can be deallocated. This will not affect the ESMF Array objects inside the ArrayBundle. However, the Array objects must not be deallocated while the ArrayBundle references them.
deallocate(arrayList)
Individual Arrays can be added using the Fortran array constructor syntax (/ ... /). Here an ESMF_Array is created on the fly and immediately added to the ArrayBundle.
call ESMF_ArrayBundleAdd(arraybundle, arrayList=(/ &
ESMF_ArrayCreate(arrayspec=arrayspec, distgrid=distgrid, name="AonFly")/), &
rc=rc)
Items in the ArrayBundle can be replaced by items with the same name.
call ESMF_ArraySpecSet(arrayspec2, typekind=ESMF_TYPEKIND_R4, rank=2, rc=rc)
call ESMF_ArrayBundleReplace(arraybundle, arrayList=(/ &
ESMF_ArrayCreate(arrayspec=arrayspec2, distgrid=distgrid, name="AonFly")/), &
rc=rc)
Items can be removed from the ArrayBundle by providing their name.
call ESMF_ArrayBundleRemove(arraybundle, arrayNameList=(/"AonFly"/), rc=rc)
The ArrayBundle AddReplace() method can be used to conveniently add an item to the ArrayBundle, or replacing an existing item of the same name.
call ESMF_ArrayBundleAddReplace(arraybundle, arrayList=(/ &
ESMF_ArrayCreate(arrayspec=arrayspec2, distgrid=distgrid, name="AonFly")/), &
rc=rc)
The ArrayBundle object can be printed at any time to list its contents by name.
call ESMF_ArrayBundlePrint(arraybundle, rc=rc)
Individual items in the ArrayBundle can be accessed directly by their name.
call ESMF_ArrayBundleGet(arraybundle, arrayName="AonFly", array=arrayOut, &
rc=rc)
A list containing all of the Arrays in the ArrayBundle can also be requested in a single call. This requires that a large enough list argument is passed into the ESMF_ArrayBundleGet() method. The exact number of items in the ArrayBundle can be queried using the arrayCount argument first.
call ESMF_ArrayBundleGet(arraybundle, arrayCount=arrayCount, rc=rc)
Then use arrayCount to correctly allocate the arrayList variable for a second call to ESMF_ArrayBundleGet().
allocate(arrayList(arrayCount)) call ESMF_ArrayBundleGet(arraybundle, arrayList=arrayList, rc=rc)
Now the arrayList variable can be used to access the individual Arrays, e.g. to print them.
do i=1, arrayCount
call ESMF_ArrayPrint(arrayList(i), rc=rc)
if (rc /= ESMF_SUCCESS) call ESMF_Finalize(endflag=ESMF_END_ABORT)
enddo
By default the arrayList returned by ESMF_ArrayBundleGet() contains the items in alphabetical order. To instead return the items in the same order in which they were added to the ArrayBundle, the itemorderflag argument is passed with a value of ESMF_ITEMORDER_ADDORDER.
call ESMF_ArrayBundleGet(arraybundle, arrayList=arrayList, &
itemorderflag=ESMF_ITEMORDER_ADDORDER, rc=rc)
Destroying an ArrayBundle does not destroy the Arrays. In fact, it leaves the Arrays totally unchanged.
call ESMF_ArrayBundleDestroy(arraybundle, rc=rc)
The Arrays must be destroyed separately.
call ESMF_ArrayDestroy(arrayList(1), rc=rc)
call ESMF_ArrayDestroy(arrayList(2), rc=rc)
deallocate(arrayList) call ESMF_DistGridDestroy(distgrid, rc=rc)
One of the most fundamental communication pattern in domain decomposition codes is the halo operation. The ESMF Array class supports halos by allowing memory for extra elements to be allocated on each DE. See section 28.2.15 for a discussion of the Array level halo operation. The ArrayBundle level extents the Array halo operation to bundles of Arrays.
First create an ESMF_ArrayBundle object containing a set of ESMF Arrays.
arraybundle = ESMF_ArrayBundleCreate(arrayList=arrayList, &
name="MyArrayBundle", rc=rc)
The ArrayBundle object can be treated as a single entity. The ESMF_ArrayBundleHaloStore() call determines the most efficient halo exchange pattern for all Arrays that are part of arraybundle.
call ESMF_ArrayBundleHaloStore(arraybundle=arraybundle, &
routehandle=haloHandle, rc=rc)
The halo exchange pattern stored in haloHandle can now be applied to the arraybundle object, or any other ArrayBundle that is compatible to the one used during the ESMF_ArrayBundleHaloStore() call.
call ESMF_ArrayBundleHalo(arraybundle=arraybundle, routehandle=haloHandle, &
rc=rc)
Finally, when no longer needed, the resources held by haloHandle need to be returned to the system by calling ESMF_ArrayBundleHaloRelease().
call ESMF_ArrayBundleHaloRelease(routehandle=haloHandle, rc=rc)
Finally the ArrayBundle object can be destroyed.
call ESMF_ArrayBundleDestroy(arraybundle, rc=rc)
The following is a list of implementation specific details about the current ESMF ArrayBundle.
INTERFACE:
interface assignment(=)
arraybundle1 = arraybundle2
ARGUMENTS:
type(ESMF_ArrayBundle) :: arraybundle1
type(ESMF_ArrayBundle) :: arraybundle2
STATUS:
DESCRIPTION:
Assign arraybundle1 as an alias to the same ESMF ArrayBundle object in memory as arraybundle2. If arraybundle2 is invalid, then arraybundle1 will be equally invalid after the assignment.
The arguments are:
INTERFACE:
interface operator(==)
if (arraybundle1 == arraybundle2) then ... endif
OR
result = (arraybundle1 == arraybundle2)
RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle1
type(ESMF_ArrayBundle), intent(in) :: arraybundle2
STATUS:
DESCRIPTION:
Test whether arraybundle1 and arraybundle2 are valid aliases to the same ESMF ArrayBundle object in memory. For a more general comparison of two ESMF ArrayBundles, going beyond the simple alias test, the ESMF_ArrayBundleMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
interface operator(/=)
if (arraybundle1 /= arraybundle2) then ... endif
OR
result = (arraybundle1 /= arraybundle2)
RETURN VALUE:
logical :: resultARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle1
type(ESMF_ArrayBundle), intent(in) :: arraybundle2
STATUS:
DESCRIPTION:
Test whether arraybundle1 and arraybundle2 are not valid aliases to the same ESMF ArrayBundle object in memory. For a more general comparison of two ESMF ArrayBundles, going beyond the simple alias test, the ESMF_ArrayBundleMatch() function (not yet implemented) must be used.
The arguments are:
INTERFACE:
subroutine ESMF_ArrayBundleAdd(arraybundle, arrayList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
type(ESMF_Array), intent(in) :: arrayList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Add Array(s) to an ArrayBundle. It is an error if arrayList contains Arrays that match by name Arrays already contained in arraybundle.
INTERFACE:
subroutine ESMF_ArrayBundleAddReplace(arraybundle, arrayList, rc)ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
type(ESMF_Array), intent(in) :: arrayList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Arrays in arrayList that do not match any Arrays by name in arraybundle are added to the ArrayBundle. Arrays in arraybundle that match by name Arrays in arrayList are replaced by those Arrays.
INTERFACE:
function ESMF_ArrayBundleCreate(arrayList, multiflag, &
relaxedflag, name, rc)
RETURN VALUE:
type(ESMF_ArrayBundle) :: ESMF_ArrayBundleCreateARGUMENTS:
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Array), intent(in), optional :: arrayList(:)
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
character(len=*), intent(in), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Create an ESMF_ArrayBundle object from a list of existing Arrays.
The creation of an ArrayBundle leaves the bundled Arrays unchanged, they remain valid individual objects. An ArrayBundle is a light weight container of Array references. The actual data remains in place, there are no data movements or duplications associated with the creation of an ArrayBundle.
INTERFACE:
subroutine ESMF_ArrayBundleDestroy(arraybundle, noGarbage, rc)ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Destroys an ESMF_ArrayBundle object. The member Arrays are not touched by this operation and remain valid objects that need to be destroyed individually if necessary.
By default a small remnant of the object is kept in memory in order to prevent problems with dangling aliases. The default garbage collection mechanism can be overridden with the noGarbage argument.
The arguments are:
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_ArrayBundleGet()
subroutine ESMF_ArrayBundleGetListAll(arraybundle, &
itemorderflag, arrayCount, arrayList, arrayNameList, name, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_ItemOrder_Flag), intent(in), optional :: itemorderflag
integer, intent(out), optional :: arrayCount
type(ESMF_Array), intent(out), optional :: arrayList(:)
character(len=*), intent(out), optional :: arrayNameList(:)
character(len=*), intent(out), optional :: name
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get general, i.e. not Array name specific information from the ArrayBundle.
INTERFACE:
! Private name; call using ESMF_ArrayBundleGet()
subroutine ESMF_ArrayBundleGetItem(arraybundle, arrayName, &
array, arrayCount, isPresent, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
character(len=*), intent(in) :: arrayName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Array), intent(out), optional :: array
integer, intent(out), optional :: arrayCount
logical, intent(out), optional :: isPresent
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get information about items that match arrayName in ArrayBundle.
INTERFACE:
! Private name; call using ESMF_ArrayBundleGet()
subroutine ESMF_ArrayBundleGetList(arraybundle, arrayName, arrayList, &
itemorderflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
character(len=*), intent(in) :: arrayName
type(ESMF_Array), intent(out) :: arrayList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_ItemOrder_Flag), intent(in), optional :: itemorderflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Get the list of Arrays from ArrayBundle that match arrayName.
INTERFACE:
subroutine ESMF_ArrayBundleHalo(arraybundle, routehandle, &
checkflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed ArrayBundle halo operation for the Arrays in arrayBundle.
See ESMF_ArrayBundleHaloStore() on how to precompute routehandle.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_ArrayBundleHaloRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with an ArrayBundle halo operation. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
subroutine ESMF_ArrayBundleHaloStore(arraybundle, routehandle, &
startregion, haloLDepth, haloUDepth, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_StartRegion_Flag),intent(in), optional :: startregion
integer, intent(in), optional :: haloLDepth(:)
integer, intent(in), optional :: haloUDepth(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store an ArrayBundle halo operation over the data in arraybundle. By default, i.e. without specifying startregion, haloLDepth and haloUDepth, all elements in the total Array regions that lie outside the exclusive regions will be considered potential destination elements for the halo operation. However, only those elements that have a corresponding halo source element, i.e. an exclusive element on one of the DEs, will be updated under the halo operation. Elements that have no associated source remain unchanged under halo.
Specifying startregion allows to change the shape of the effective halo region from the inside. Setting this flag to ESMF_STARTREGION_COMPUTATIONAL means that only elements outside the computational region for each Array are considered for potential destination elements for the halo operation. The default is ESMF_STARTREGION_EXCLUSIVE.
The haloLDepth and haloUDepth arguments allow to reduce the extent of the effective halo region. Starting at the region specified by startregion, the haloLDepth and haloUDepth define a halo depth in each direction. Note that the maximum halo region is limited by the total region for each Array, independent of the actual haloLDepth and haloUDepth setting. The total Array regions are local DE specific. The haloLDepth and haloUDepth are interpreted as the maximum desired extent, reducing the potentially larger region available for the halo operation.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_ArrayBundleHalo() on any pair of ArrayBundles that matches srcArrayBundle and dstArrayBundle in type, kind, and memory layout of the distributed dimensions. However, the size, number, and index order of undistributed dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
INTERFACE:
function ESMF_ArrayBundleIsCreated(arraybundle, rc)RETURN VALUE:
logical :: ESMF_ArrayBundleIsCreatedARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
DESCRIPTION:
Return .true. if the arraybundle has been created. Otherwise return .false.. If an error occurs, i.e. rc /= ESMF_SUCCESS is returned, the return value of the function will also be .false..
The arguments are:
INTERFACE:
subroutine ESMF_ArrayBundlePrint(arraybundle, rc)ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: arraybundle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Print internal information of the specified ESMF_ArrayBundle
object to stdout.
The arguments are:
INTERFACE:
subroutine ESMF_ArrayBundleRead(arraybundle, fileName, &
singleFile, timeslice, iofmt, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
character(*), intent(in) :: fileName
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: singleFile
integer, intent(in), optional :: timeslice
type(ESMF_IOFmt_Flag), intent(in), optional :: iofmt
integer, intent(out), optional :: rc
DESCRIPTION:
Read Array data to an ArrayBundle object from file(s). For this API to be functional, the environment variable ESMF_PIO should be set to either "internal" or "external" when the ESMF library is built. Please see the section on Data I/O, 38.2.
Limitations:
The arguments are:
INTERFACE:
subroutine ESMF_ArrayBundleRedist(srcArrayBundle, dstArrayBundle, &
routehandle, checkflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in), optional :: srcArrayBundle
type(ESMF_ArrayBundle), intent(inout), optional :: dstArrayBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed ArrayBundle redistribution from the Arrays in srcArrayBundle to the Arrays in dstArrayBundle.
The srcArrayBundle and dstArrayBundle arguments are optional in support of the situation where srcArrayBundle and/or dstArrayBundle are not defined on all PETs. The srcArrayBundle and dstArrayBundle must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_ArrayBundleRedistRelease(routehandle, &
noGarbage, rc)
ARGUMENTS:
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: noGarbage
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Release resources associated with an ArrayBundle redistribution. After this call routehandle becomes invalid.
It is generally recommended to leave the noGarbage argument set to .FALSE. (the default), and to take advantage of the ESMF garbage collection system which will prevent problems with dangling aliases or incorrect sequences of destroy calls. However this level of support requires that a small remnant of the object is kept in memory past the destroy call. This can lead to an unexpected increase in memory consumption over the course of execution in applications that use temporary ESMF objects. For situations where the repeated creation and destruction of temporary objects leads to memory issues, it is recommended to call with noGarbage set to .TRUE., fully removing the entire temporary object from memory.
INTERFACE:
! Private name; call using ESMF_ArrayBundleRedistStore()
subroutine ESMF_ArrayBundleRedistStore<type><kind>(srcArrayBundle, &
dstArrayBundle, routehandle, factor, ignoreUnmatchedIndicesFlag, &
srcToDstTransposeMap, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: srcArrayBundle
type(ESMF_ArrayBundle), intent(inout) :: dstArrayBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
<type>(ESMF_KIND_<kind>),intent(in) :: factor
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:)
integer, intent(in), optional :: srcToDstTransposeMap(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store an ArrayBundle redistribution operation from srcArrayBundle to dstArrayBundle. The redistribution between ArrayBundles is defined as the sequence of individual Array redistributions over all source and destination Array pairs in sequence. The method requires that srcArrayBundle and dstArrayBundle reference an identical number of ESMF_Array objects.
The effect of this method on ArrayBundles that contain aliased members is undefined.
PETs that specify a factor argument must use the <type><kind> overloaded interface. Other PETs call into the interface without factor argument. If multiple PETs specify the factor argument its type and kind as well as its value must match across all PETs. If none of the PETs specifies a factor argument the default will be a factor of 1.
See the description of method ESMF_ArrayRedistStore() for the definition of the Array based operation.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_ArrayBundleRedist() on any pair of ArrayBundles that matches srcArrayBundle and dstArrayBundle in type, kind, and memory layout of the distributed dimensions. However, the size, number, and index order of undistributed dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This method is overloaded for:
ESMF_TYPEKIND_I4, ESMF_TYPEKIND_I8,
ESMF_TYPEKIND_R4, ESMF_TYPEKIND_R8.
This call is collective across the current VM.
INTERFACE:
! Private name; call using ESMF_ArrayBundleRedistStore()
subroutine ESMF_ArrayBundleRedistStoreNF(srcArrayBundle, dstArrayBundle, &
routehandle, ignoreUnmatchedIndicesFlag, &
srcToDstTransposeMap, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in) :: srcArrayBundle
type(ESMF_ArrayBundle), intent(inout) :: dstArrayBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: ignoreUnmatchedIndicesFlag(:)
integer, intent(in), optional :: srcToDstTransposeMap(:)
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Store an ArrayBundle redistribution operation from srcArrayBundle to dstArrayBundle. The redistribution between ArrayBundles is defined as the sequence of individual Array redistributions over all source and destination Array pairs in sequence. The method requires that srcArrayBundle and dstArrayBundle reference an identical number of ESMF_Array objects.
The effect of this method on ArrayBundles that contain aliased members is undefined.
PETs that specify a factor argument must use the <type><kind> overloaded interface. Other PETs call into the interface without factor argument. If multiple PETs specify the factor argument its type and kind as well as its value must match across all PETs. If none of the PETs specifies a factor argument the default will be a factor of 1.
See the description of method ESMF_ArrayRedistStore() for the definition of the Array based operation.
The routine returns an ESMF_RouteHandle that can be used to call ESMF_ArrayBundleRedist() on any pair of ArrayBundles that matches srcArrayBundle and dstArrayBundle in type, kind, and memory layout of the distributed dimensions. However, the size, number, and index order of undistributed dimensions may be different. See section 37.2.5 for a more detailed discussion of RouteHandle reusability.
This call is collective across the current VM.
INTERFACE:
subroutine ESMF_ArrayBundleRemove(arraybundle, arrayNameList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
character(len=*), intent(in) :: arrayNameList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Remove Array(s) by name from ArrayBundle. In the relaxed setting it is not an error if arrayNameList contains names that are not found in arraybundle.
INTERFACE:
subroutine ESMF_ArrayBundleReplace(arraybundle, arrayList, &
multiflag, relaxedflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(inout) :: arraybundle
type(ESMF_Array), intent(in) :: arrayList(:)
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
logical, intent(in), optional :: multiflag
logical, intent(in), optional :: relaxedflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Replace Array(s) by name in ArrayBundle. In the relaxed setting it is not an error if arrayList contains Arrays that do not match by name any item in arraybundle. These Arrays are simply ignored in this case.
INTERFACE:
subroutine ESMF_ArrayBundleSMM(srcArrayBundle, dstArrayBundle, &
routehandle, &
zeroregion, & ! DEPRECATED ARGUMENT
zeroregionflag, termorderflag, checkflag, rc)
ARGUMENTS:
type(ESMF_ArrayBundle), intent(in), optional :: srcArrayBundle
type(ESMF_ArrayBundle), intent(inout), optional :: dstArrayBundle
type(ESMF_RouteHandle), intent(inout) :: routehandle
-- The following arguments require argument keyword syntax (e.g. rc=rc). --
type(ESMF_Region_Flag), intent(in), optional :: zeroregion ! DEPRECATED ARGUMENT
type(ESMF_Region_Flag), intent(in), target, optional :: zeroregionflag(:)
type(ESMF_TermOrder_Flag), intent(in), target, optional :: termorderflag(:)
logical, intent(in), optional :: checkflag
integer, intent(out), optional :: rc
STATUS:
DESCRIPTION:
Execute a precomputed ArrayBundle sparse matrix multiplication from the Arrays in srcArrayBundle to the Arrays in dstArrayBundle.
The srcArrayBundle and dstArrayBundle arguments are optional in support of the situation where srcArrayBundle and/or dstArrayBundle are not defined on all PETs. The srcArrayBundle and dstArrayBundle must be specified on those PETs that hold source or destination DEs, respectively, but may be omitted on all other PETs. PETs that hold neither source nor destination DEs may omit both arguments.
This call is collective across the current VM.