github esmf-org/esmf v8.5.0
ESMF 8.5.0
on GitHub

latest releases: v8.8.0b04, v8.8.0b03, v8.8.0b02...
15 months ago

Overview

The 8.5.0 release of ESMF comes with a few big new developments as well as improvements of existing functionality. The highlights of the 8.5.0 release are outlined in the following paragraphs, followed by a detailed list of release notes.

One major new development available with 8.5.0 is the addition of a hierarchical configuration class: ESMF_HConfig. This class provides YAML 1.2 support through the ESMF Fortran API. The ESMF_HConfig class integrates with the existing configuration class ESMF_Config for backward compatibility, and allows ESMF user code to seamlessly access, modify, and create information in YAML format. This new capability is leveraged within ESMF and NUOPC to provide a YAML alternative when specifying ESMF_Initialize() parameters, NUOPC attribute, petList, or run sequence information.

Another area that has seen a lot of new development is the Earth System Model eXecutable (ESMX) layer. ESMX has greatly matured in many areas since it was first introduced in the previous ESMF release and we believe it is now ready to be used by early adopters for “real world” applications. To this end, several new build options were added to the ESMX build configuration, and component building is now an integrated feature. The new ESMX_Builder command line tool eliminates the need for direct user interaction with the CMake system and improves the overall usability.

ESMF 8.5.0 adds a generic geometry class (ESMF_Geom) to support user code that deals generically with the existing geometry classes: ESMF_Grid, ESMF_Mesh, ESMF_LocStream, and ESMF_XGrid. Using the ESMF_Geom type, code will function regardless of the underlying geometry class. In this release only a few ESMF operations, such as Field creation, are overloaded to support the generic Geom type. Additional support will be added in future releases as the need arises.

Progress was also made in the area of multi-tile I/O support for Fields and Arrays, eliminating one of the restrictions of the previous release. Multi-tile Fields with ungridded dimensions, and multi-tile Arrays with undistributed dimensions are now fully supported.

With respect to installation and portability of the library, support for Spack and Docker continues to be an important focus. ESMF core team members are now maintainers of the official ESMF Spack package, and automated daily testing ensures continued support of this build option. Docker images are available and maintained under the ESMF organization on Docker Hub.

Incremental progress, bug fixes, and performance improvements were made in several other areas of the framework, including the ESMF_RegridWeightGen application, Mesh creation, Regridding, RouteHandle re-use, and others. Please see the release notes below for a comprehensive list of changes.

Release Notes

  • The public Fortran API in this release is backward compatible with the last release of ESMF, 8.4.0, and patch releases 8.4.1 and 8.4.2. There were a few minor API changes, most of which do not require user code changes. The exception is a change to the Read() and Write() methods for multi-tile Arrays or Fields, where the tile number placeholder character in the fileName argument was changed from “#” to “*”. A number of new interfaces were added. The complete list of API changes is summarized in a table showing interface changes since ESMF 8.4.0, including the rationale and impact for each change.
  • Some bit-for-bit changes are expected for this release compared to ESMF 8.4.0, and patch releases 8.4.1 and 8.4.2. This is based on test runs with the Intel compiler suite using options “-O2 -fp-model precise”, and due to the following changes:
    • Fixed a problem in the first-order conservative weight calculation that might occur in some situations when a destination cell is a concave quadrilateral. The fix was made to both the 2D Cartesian and 2D spherical weight conservative calculation. Expected bit-for-bit changes:
      • Small changes to first-order conservative weights for destination cells that are concave. These changes can occur for either 2D Cartesian or 2D spherical Grids or Meshes.
    • Updated the ESMF cubed sphere coordinate generation algorithm to use R8 reals. This makes the algorithm more accurate and also aligns it better with the same algorithm used by NASA. Expected bit-for-bit changes:
      • Small changes to the coordinate values produced by ESMF_GridCreateCubedSphere() or ESMF_MeshCreateCubedSphere(), and also changes to anything which depends on those values (e.g. regridding weights to/from an ESMF generated cube sphere Grid).
  • No changes that affect regridding status were made to the ESMF regrid weight generation methods and applications. The ESMF tables summarizing the ESMF regridding status are unchanged.
  • All of the fixes and improvements released with patches 8.4.1 and 8.4.2 are included in release 8.5.0.
  • Significant improvements have been made to the Earth System Model eXecutable (ESMX) layer:
    • Component building has been integrated into the ESMX build system.
    • The build configuration has been enhanced through new build options.
    • The ESMX_Builder script has been added to simplify building ESMX applications.
    • The ESMX run configuration file has been updated to YAML formatting.
    • The names of the ESMX build and run configuration files can be customized.
    • The ESMX Data Component, which allows users to define import/export fields and prescribe data, has been added to the ESMX Layer.
  • A hierarchical configuration class (ESMF_HConfig) with Fortran API was implemented. ESMF_HConfig covers the YAML 1.2 standard and integrates with the existing configuration class ESMF_Config for backward compatibility.
  • The ESMF_Initialize() method now supports reading startup configurations from a YAML file.
  • The ESMF_InfoSet() interface was overloaded to allow setting ESMF_Info key value pairs from an ESMF_HConfig object.
  • The NUOPC methods that implement ingestion of PetList, RunSequence and Attribute information have been overloaded to support the YAML format through the ESMF_HConfig class.
  • A new named constant, ESMF_STATEINTENT_INTERNAL, for type(ESMF_StateIntent_Flag) was added. This new option allows a state to be marked exclusively for component internal access.
  • A generic geometry class (ESMF_Geom) was added to ESMF. A Geom object can be created from any object of the existing geometry classes (ESMF_Grid, ESMF_Mesh, ESMF_LocStream, and ESMF_XGrid). Having this class allows a user to pass a generic geometry object through a coupled system without knowing its exact type. To support greater flexibility in coupled systems, some ESMF operations are now supported on Geom (e.g. Field creation). More will be added as the need arises.
  • Creating a Mesh, or adding nodes to an existing Mesh, without specifying the nodeOwners argument now works, even if there are PETs with zero nodes. Previously this condition led to a hang inside the respective ESMF method.
  • Creating a Mesh without specifying node information now works, even if there are PETs with zero elements. Previously this condition led to a hang inside the respective ESMF method.
  • Grids that contain DEs of zero width are now supported in regridding. Previously using a Grid of this type with some regridding methods (e.g. ESMF_REGRIDMETHOD_CONSERVE) would result in an error.
  • The srcTermProcessing argument was added to the version of ESMF_FieldRegridStore() that operates on an XGrid. This fixes the issue where in some cases bit-for-bit reproducibility wasn’t available in that version of ESMF_FieldRegridStore().
  • The RouteHandle reuse optimization in ESMF_FieldBundleRegridStore() was extended to include the Grid-to/from-Mesh and Mesh-to/from-Mesh combinations. This optimization is leveraged by the NUOPC_Connector and results in a significant reduction of cost (both time and memory) during model initialization when Fields on Meshes are present in the import- and/or exportStates.
  • All of the RedistStore() methods that take the optional srcToDstTransposeMap argument now support negative entries. The order of elements along each negative dimension entry is reversed.
  • Two new dataFillScheme options, “nan” and “snan”, have been added to the ESMF_FieldFill() method. These options fill a Field with IEEE quiet and signaling NaN ("Not a Number") values, respectively.
  • An optional logical flag (isESMFAllocated) was added to the ESMF_FieldGet(), ESMF_ArrayGet(), and ESMF_LocalArrayGet() methods to allow the user to query whether the respective data allocation is held by ESMF.
  • A bug in the auto-detection of file type in the ESMF_RegridWeightGen application was fixed. Previously SCRIP grid files could sometimes be incorrectly identified as GRIDSPEC files.
  • The -t, --src_type, and --dst_type arguments of the ESMF_RegridWeightGen application that allow grid file types to be specified explicitly, have been re-enabled.
  • The Read and Write operations for multi-tile Arrays and Fields (e.g., for representing a cubed sphere grid as a six-tile grid) have been extended to permit I/O for Arrays / Fields with undistributed / ungridded dimensions. This change applies to the ESMF_ArrayRead(), ESMF_ArrayWrite(), ESMF_ArrayBundleRead(), ESMF_ArrayBundleWrite(), ESMF_FieldRead(), ESMF_FieldWrite(), ESMF_FieldBundleRead(), and ESMF_FieldBundleWrite() methods.
  • For Read() and Write() operations for multi-tile Arrays and Fields (e.g., for representing a cubed sphere grid as a six-tile grid), the file name placeholder character in the fileName string that stands for the tile number has been changed from “#” to “*”. This change was needed to support obtaining the fileName string from ESMF Config file, where the “#” character is interpreted as the start of a comment.
  • Creating a cubed sphere grid under ESMPy with corner stagger by calling ESMF.Grid() with add_corner_stagger=True now works correctly. Previously this condition would lead to a run-time error.
  • ESMF is available through Spack, a popular package manager for High Performance Computing. A user can build ESMF, and its dependencies, in a convenient and standard way using the Spack tools. ESMF core team members are now maintainers of the official ESMF Spack package. To ensure a robust integration, the ESMF build procedure through Spack is automatically tested using GitHub Actions.
  • Intel oneAPI compiler support was improved and additional test combinations were added. A new ESMF User’s Guide section discussing Intel compiler support was added to provide guidance with the classic to oneAPI transition.
  • Fujitsu compiler support was added under ESMF_OS=Linux. Use ESMF_COMPILER=fujitsu to access the option.

Known Issues

Platform-specific issues:

  • The GNU and Intel compilers require GCC>=4.8 for C++11 support (Intel uses the GCC headers). By default, ESMF uses the C++11 standard and cannot be downgraded. If you run into build issues due to the C++11 dependency, you must make sure a GCC>=4.8 is loaded.
  • Compiling ESMF with GCC version 8.1.0 triggers an internal compiler error in ESMF_HConfig.F90 due to the use of allocatable character variables. Earlier and later versions of GCC do not have this issue.
  • On Darwin, with the GNU gfortran+gcc combination, when building MPICH3 from source, it is important to specify the "--enable-two-level-namespace" configure option. By default, i.e. without this option, on Darwin, the produced MPICH compiler wrappers include a linker flag (-flat_namespace) that causes issues with C++ exception handling. Building and linking ESMF applications with MPICH compiler wrappers that specify this linker option leads to “mysterious” application aborts during execution.
  • On Darwin, with the Intel Fortran compiler, command line arguments cannot be accessed from ESMF applications when linked against the shared library version of libesmf. There is no issue when linked against the static libesmf.a version. Setting the environment variable ESMF_SHARED_LIB_BUILD=OFF, during the ESMF build, can be used as a work around for this issue.
  • There is an issue with intercepting the MPI calls for profiling on some of the supported platforms. This results in a single FAIL reported for ESMF_TraceMPIUTest.F90. The affected platforms are:
    • Catania: Darwin+GNU+mpich
    • Green: Darwin+gfortranclang+mpich/openmpi
    • Gaea: Unicos+GNU+cray-mpich
  • There is an issue with loading the libesmftrace_preload.so library on some of the supported platforms. This results in a reported CRASH for ESMF_TraceIOUTest.F90 and ESMF_TraceMPIUTest.F90. The affected platforms are:
    • Discover: Linux+GNU+intelmpi
    • Gaea: Unicos+Intel+cray-mpich
    • Gaea: Unicos+Intel+mpiuni

Documentation

Tables

Check out latest releases or
releases around esmf-org/esmf v8.5.0

Don't miss a new esmf release

NewReleases is sending notifications on new releases.

Get notifications