Next: 6 References Up: ESMC_crefdoc Previous: 4 Infrastructure: Fields and Grids Contents
The ESMF utilities are a set of tools for quickly assembling modeling applications.
The Time Management Library provides utilities for time and time interval representation, as well as a higher-level utility, a clock, that controls model time stepping.
The ESMF Config class provides configuration management based on NASA DAO's Inpak package, a collection of methods for accessing files containing input parameters stored in an ASCII format.
The ESMF LogErr class consists of a method for writing error, warning, and informational messages to a default Log file that is created during ESMF initialization.
The ESMF VM (Virtual Machine) class provides methods for querying information about a VM. A VM is a generic representation of hardware and system software resources. There is exactly one VM object per ESMF Component, providing the execution environment for the Component code. The VM class handles all resource management tasks for the Component class and provides a description of the underlying configuration of the compute resources used by a Component. In addition to resource description and management, the VM class offers the lowest level of ESMF communication methods.
The ESMF Time Manager utility includes software for time and time interval representation, as well as model time advancement. Since multi-component geophysical applications often require synchronization across the time management schemes of the individual components, the Time Manager's standard calendars and consistent time representation promote component interoperability.
|
Key Features |
| Drift-free timekeeping through an integer-based internal time representation. Both integers and reals can be specified at the interface. |
| Support for many calendar kinds. |
| Support for both concurrent and sequential modes of component execution. |
The Calendar class represents the standard calendars used in geophysical modeling: Gregorian, Julian, Julian Day, Modified Julian Day, no-leap, 360-day, and no-calendar. Brief descriptions are provided for each calendar below.
DESCRIPTION:
Supported calendar kinds.
The type of this flag is:
type(ESMF_CalKind_Flag)
The valid values are:
MJD = JD - 2400000.5
The half day is subtracted so that the day starts at midnight.
A Time represents a specific point in time.
There are Time methods defined for setting and getting a Time.
A Time that is specified in hours does not need to be associated with a standard calendar; use ESMC_CALKIND_NOCALENDAR. A Time whose specification includes time units of a year must be associated with a standard calendar. The ESMF representation of a calendar, the Calendar class, is described in Section 26.1. The ESMC_TimeSet method is used to initialize a Time as well as associate it with a Calendar. If a Time method is invoked in which a Calendar is necessary and one has not been set, the ESMF method will return an error condition.
In the ESMF the TimeInterval class is used to represent time periods. This class is frequently used in combination with the Time class. The Clock class, for example, advances model time by incrementing a Time with a TimeInterval.
A TimeInterval represents a period between time instants. It can be either positive or negative.
There are TimeInterval methods defined for setting and getting a TimeInterval, for printing the contents of a TimeInterval.
The class used to represent time instants in ESMF is Time, and this class is frequently used in operations along with TimeIntervals. The Clock class, for example, advances model time by incrementing a Time with a TimeInterval.
TimeIntervals are used by other parts of the ESMF timekeeping system, such as Clocks; see Section 29.1.
The Clock class advances model time and tracks its associated date on a specified Calendar. It stores start time, stop time, current time, and a time step.
There are methods for setting and getting the Times associated with a Clock. Methods are defined for advancing the Clock's current time and printing a Clock's contents.
ESMF Configuration Management is based on NASA DAO's
Inpak 90 package, a Fortran 90 collection of routines/functions
for accessing Resource Files in ASCII format.The package
is optimized for minimizing formatted I/O, performing all of its
string operations in memory using Fortran intrinsic functions.
The ESMF Configuration Management Package was evolved by Leonid Zaslavsky and Arlindo da Silva from Ipack90 package created by Arlindo da Silva at NASA DAO.
Back in the 70's Eli Isaacson wrote IOPACK in Fortran 66. In June of 1987 Arlindo da Silva wrote Inpak77 using Fortran 77 string functions; Inpak 77 is a vastly simplified IOPACK, but has its own goodies not found in IOPACK. Inpak 90 removes some obsolete functionality in Inpak77, and parses the whole resource file in memory for performance.
The Log class consists of a variety of methods for writing error, warning, and informational messages to files. A default Log is created at ESMF initialization.
When ESMF is started with ESMC_Initialize(), multiple Log files will be created by PET number. The PET number (in the format PETx.) will be prepended to each file name where x is the PET number. The ESMC_LogWrite() call is used to issue messages to the log. As part of the call, a message can be tagged as either an informational, warning, or error message.
The messages may be buffered within ESMF before appearing in the log. All messages will be properly flushed to the log files when ESMC_Finalize() is called.
DESCRIPTION:
Specifies a single log file, multiple log files (one per PET), or no log files.
The valid values are:
DESCRIPTION:
Specifies a message level.
The valid values are:
The ESMF VM (Virtual Machine) class is a generic representation of hardware and system software resources. There is exactly one VM object per ESMF Component, providing the execution environment for the Component code. The VM class handles all resource management tasks for the Component class and provides a description of the underlying configuration of the compute resources used by a Component.
In addition to resource description and management, the VM class offers the lowest level of ESMF communication methods. The VM communication calls are very similar to MPI. Data references in VM communication calls must be provided as raw, language-specific, one-dimensional, contiguous data arrays. The similarity between VM and MPI communication calls is striking and there are many equivalent point-to-point and collective communication calls. However, unlike MPI, the VM communication calls support communication between threaded PETs in a completely transparent fashion.
Many ESMF applications do not interact with the VM class directly very much. The resource management aspect is wrapped completely transparent into the ESMF Component concept. Often the only reason that user code queries a Component object for the associated VM object is to inquire about resource information, such as the localPet or the petCount. Further, for most applications the use of higher level communication APIs, such as provided by Array and Field, are much more convenient than using the low level VM communication calls.
The basic elements of a VM are called PETs, which stands for Persistent Execution Threads. These are equivalent to OS threads with a lifetime of at least that of the associated component. All VM functionality is expressed in terms of PETs. In the simplest, and most common case, a PET is equivalent to an MPI process. However, ESMF also supports multi-threading, where multiple PETs run as Pthreads inside the same virtual address space (VAS).
ESMF's built in profiling capability collects runtime statistics of an executing ESMF application through both automatic and manual code instrumentation. Timing information for all phases of all ESMF components executing in an application can be automatically collected using the ESMF_RUNTIME_PROFILE environment variable (see below for settings). Additionally, arbitrary user-defined code regions can be timed by manually instrumenting code with special API calls. Timing profiles of component phases and user-defined regions can be output in several different formats:
The following table lists important environment variables that control aspects of ESMF profiling.
| Environment Variable | Description | Example Values | Default |
| ESMF_RUNTIME_PROFILE | Enable/disables all profiling functions | ON or OFF | OFF |
| ESMF_RUNTIME_PROFILE_PETLIST | Limits profiling to an explicit list of PETs | “0-9 50 99” | profile all PETs |
| ESMF_RUNTIME_PROFILE_OUTPUT | Controls output format of profiles; multiple can be specified in a space separated list | TEXT, SUMMARY, BINARY | TEXT |
Whereas profiling collects summary information from an application, tracing records a more detailed set of events for later analysis. Trace analysis can be used to understand what happened during a program's execution and is often used for diagnosing problems, debugging, and performance analysis.
ESMF has a built-in tracing capability that records events into special binary log files. Unlike log files written by the ESMF_Log class, which are primarily for human consumption (see Section 31.1), the trace output files are recorded in a compact binary representation and are processed by tools to produce various analyses. ESMF event streams are recorded in the Common Trace Format (CTF). CTF traces include one or more event streams, as well as a metadata file describing the events in the streams.
Several tools are available for reading in the CTF traces output by ESMF. Of the tools listed below, the first one is designed specifically for analyzing ESMF applications and the second two are general purpose tools for working with all CTF traces.
Events that can be captured by the ESMF tracer include the following. Events are recorded with a high-precision timestamp to allow timing analyses.
The following table lists important environment variables that control aspects of ESMF tracing.
| Environment Variable | Description | Example Values | Default |
| ESMF_RUNTIME_TRACE | Enable/disables all tracing functions | ON or OFF | OFF |
| ESMF_RUNTIME_TRACE_CLOCK | Sets the type of clock for timestamping events (see Section ![[*]](crossref.png) ). |
REALTIME or MONOTONIC or MONOTONIC_SYNC | REALTIME |
| ESMF_RUNTIME_TRACE_PETLIST | Limits tracing to an explicit list of PETs | “0-9 50 99” | trace all PETs |
| ESMF_RUNTIME_TRACE_COMPONENT | Enables/disable tracing of Component phase_enter and phase_exit events | ON or OFF | ON |
| ESMF_RUNTIME_TRACE_FLUSH | Controls frequency of event stream flushing to file | DEFAULT or EAGER | DEFAULT |
.