github esmf-org/esmf v8.9.0
ESMF 8.9.0
on GitHub

latest release: v9.0.0b02
21 days ago

Overview

The 8.9.0 release of ESMF is backward compatible with ESMF 8.8.1 for all the interfaces that are marked as backward compatible in the Reference Manual. ESMF 8.9.0 introduces feature enhancements, better troubleshooting tools, and 8 bug fixes in different areas of the framework and interface layers. Below are some highlights of the change:

Regarding feature enhancements within the framework, an ESMF_InternalState API was added that allows user code to attach private data allocations to ESMF components, and later retrieve them. The output of stdout and stderr streams of the ESMF component classes can now be redirected into user specified files. Lastly, to help with debugging ESMF errors, two new ESMF runtime settings, ESMF_RUNTIME_ABORT_LOGMSG_TYPES and ESMF_RUNTIME_ABORT_ACTION have been added.

The NUOPC layer is also enhanced with the addition of a HierarchyConnectors attribute, allowing users to manually define hierarchy connections and have more control over the connections made between levels of component hierarchies.

Although there are some API changes to add more options for users, in general this release requires no user code changes. There are some notable feature enhancements in the interface layer such as supporting multiple decomposition elements (DEs) on a single Persistent Execution Thread (PET) in ESMPy, adding an optional grid_to_field_map argument in ESMPy, and supporting vector regridding in both the C and ESMPy APIs.

Lastly, ESMF 8.9.0 introduced some roundoff level bit-for-bit changes compared with ESMF 8.8.0 and 8.8.1 due to modifications to the mesh dual algorithm. These changes could occur in bilinear or patch regridding weights when the source Field is built on the ESMF_MESHLOC_ELEMENT location.

Release Notes

  • The public Fortran API in this release is backward compatible with the previous releases, ESMF 8.8.0 and ESMF 8.8.1, for all the interfaces that are marked as backward compatible in the Reference Manual. There were API changes to a few unmarked methods that may require minor modifications to user code that uses these methods. The complete list of API changes is summarized in a table showing interface changes since ESMF 8.8.0. The table includes the rationale and impact for each change.
  • Some bit-for-bit changes are expected for this release compared with ESMF 8.8.0 and 8.8.1. This is based on test runs with the Intel compiler suite using options “-O2 -fp-model precise”, and due to the following change:
    • The mesh dual algorithm used by the ESMF regrid weight generation methods and applications was modified to support some previously unsupported element configurations. This change might affect node ordering for similar element configurations in supported Meshes, slightly changing weight calculation results.
    • Expected bit-for-bit changes: Possible roundoff level changes when the source Field is built on the ESMF_MESHLOC_ELEMENT location of a Mesh and the bilinear or patch regrid methods are used.
  • ESMPy has been updated to support multiple decomposition elements (DEs) on a single Persistent Execution Thread (PET). The main use case for this is working with multi-tile cubed-sphere grids with fewer than 6 processors. This is described in more detail in the ESMPy documentation. Partly connected to this but also useful in other contexts, functions were added to the C API to retrieve the local DE count of a Grid, Array, or Field (ESMC_GridGetLocalDECount(), ESMC_ArrayGetLocalDECount(), and ESMC_FieldGetLocalDECount())
  • The C and ESMPy APIs have been updated to support the vectorRegrid flag.
  • The ESMPy Field API has been updated to include a grid_to_field_map argument.
  • The ESMPy version retrieval and check have been made more robust:
    • The ESMPy version retrieval method has been changed to a method that works even when no git information is present (e.g., when obtaining a tarball of ESMF).
    • An exception is now raised if even the patch version differs between ESMPy and ESMF (previously, only the major and minor versions were checked).
    • An exception is now raised if one of ESMPy / ESMF is a development/beta version while the other is a release version.
  • The internal version of the ParallelIO library (used when building with ESMF_PIO=internal) has been updated from version 2.6.2 to version 2.6.6, fixing a number of issues. Bug fixes most relevant to ESMF are:
    • A fix needed for recent versions of NetCDF (4.9.3 or later) to avoid build errors with undeclared use of “_FillValue”
    • A fix needed for CMake version 4
  • Two new ESMF runtime settings have been added for debugging ESMF errors. The ESMF_RUNTIME_ABORT_LOGMSG_TYPES setting will abort directly after an ESMF log message is written for specified log message type(s): ESMF_LOGMSG_ERROR, ESMF_LOGMSG_WARNING, etc. This eliminates the need to pass return codes up the call stack. The ESMF_RUNTIME_ABORT_ACTION setting will configure the ESMF abort handler. The default is to call MPI_ABORT but this can be changed to SIGABRT, which is capable of outputting a core dump from the abort location.
  • ESMX now integrates seamlessly with user maintained CMake build systems for simplified support of complex applications. This is in addition to the ESMX_Builder and direct CMake build options. All of the available options are discussed under the Unified Driver Executable section of the ESMX documentation.
  • The ESMF_COMM build setting for MVAPICH has been reworked to simplify its usage. The ESMF_COMM=mvapich setting now covers all of the available MVAPICH versions. The mvapich2 option is still supported for backward compatibility, but triggers a WARNING, advising the user to switch to the more general mvapich option.
  • ESMF support for the LLVM Compiler Infrastructure is still experimental, with LLVM Fortran support through Flang under active development. In this release, ESMF is able to build with recent LLVM versions 20, 21, and 22.
  • A public ESMF_InternalState API was added that allows user code to attach private data allocations to ESMF components, and later retrieve them. While the “internal state” concept has been part of ESMF for a long time, most of the API has not been public due to a lack of Fortran support. The new ESMF_InternalState API leverages the Fortran 2018 deferred type(*) language feature and provides a consistent public API to the user.
  • The NUOPC attribute HierarchyConnectors was introduced to provide more control over the connections made between levels of component hierarchies. It is now possible to manually define hierarchy connections, while the automatic generation of all hierarchy connections is still the default. The new feature is discussed under the Component Hierarchy section of the NUOPC reference document.
  • Functionality was added to the ESMF component classes to redirect the stdout and stderr streams. This allows information written to these streams by user code from within standard component methods (Initialize/Run/Finalize) to be piped into custom files. This feature is available on the ESMF level (ESMF_GridCompSetVMStdRedirect, ESMF_CplCompSetVMStdRedirect), the NUOPC level (Redirection Hints), and the ESMX level (Component Label Options).
  • The behavior of the ESMF garbage collection can now be controlled via run time settings ESMF_RUNTIME_GARBAGE and ESMF_RUNTIME_GARBAGE_LOG. Either can be set as an environment variable or via configuration file read by ESMF_Initialize(), or alternatively set as ESMX/App Options.
  • The MPI thread support level used by ESMF can now be controlled via environment variable ESMF_RUNTIME_MPI_THREAD_SUPPORT. The default is MPI_THREAD_MULTIPLE, the highest MPI thread support level, as before. Any of the standard MPI thread support levels (MPI_THREAD_SINGLE, MPI_THREAD_FUNNELED, MPI_THREAD_SERIALIZED, MPI_THREAD_MULTIPLE) are supported. ESMF automatically limits internal functionality to the requested MPI thread support level.
  • A new section that documents building ESMF with Spack was added to the ESMF user’s guide.
  • The mesh dual algorithm used by the ESMF regrid weight generation methods and applications has been upgraded to support some previously unsupported element configurations that can occur in complex Meshes. This broadens the range of Meshes that can be used as a source when using the bilinear or patch methods on a Field built on the ESMF_MESHLOC_ELEMENT location.
  • The capability to retrieve the generic geometry class (Geom) from a FieldBundle has been added to the ESMF_FieldBundleGet() method.
  • The version of ESMF_FieldRegridStore() that operates through an XGrid has been upgraded to allow the user to retrieve the sparse matrix representation (i.e. factorList and factorIndexList) of a regridding.

Known Issues

  • Attempting to write weight files from the ESMPy Regrid object when using filemode=FileMode.WITHAUX currently crashes.
  • ESMPy installation fails with pip versions earlier than 21.3. (With pip versions 21.1 and 21.2 a workaround is to add --use-feature=in-tree-build to the pip install line.)

Platform-specific issues:

  • It has been found that running ESMF applications on Infiniband based clusters using IntelMPI requires setting environment variable FI_MLX_INJECT_LIMIT=0 to prevent the application from hanging. This recommendation was made by Intel support staff when looking at larger ESMF applications that would hang inside MPI calls on such hardware for no apparent reason.
  • 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 version 15 of the clang C compiler, when building under Rosetta, it is sometimes necessary to add “-Wl,-ld_classic” to environment variables ESMF_CXXLINKOPTS, ESMF_CLINKOPTS, and ESMF_F90LINKOPTS to work around link errors. (For more details, see the related GitHub issue.)
  • The Cray (cce) compiler currently has problems running PIO with mpiuni, at least for some versions of this compiler (tested with version 15.0.1).
  • The Cray (cce) compiler version 19 in optimized mode (ESMF_BOPT=O) seems to get confused when generating object files for some Fortran test programs with optimization level 2 (ESMF_OPTLEVEL=2), the default. The recommended work-around if encountering this problem is to use optimization level 1.
  • There is an issue with intercepting the MPI calls for profiling on one of the supported platforms (hearhear: Darwin+gfortran+mpich set up via spack). This results in a single FAIL reported for ESMF_TraceMPIUTest.F90.

Documentation

Tables

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

Don't miss a new esmf release

NewReleases is sending notifications on new releases.

Get notifications