Next: 6 References Up: ESMC_crefdoc Previous: 4 Infrastructure: Fields and 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.
INTERFACE:
ESMC_Calendar ESMC_CalendarCreate( const char *name, // in enum ESMC_CalKind_Flag calkindflag, // in int *rc // out );RETURN VALUE:
Newly created ESMC_Calendar object.DESCRIPTION:
Creates and sets a ESMC_Calendar object to the given built-in ESMC_CalKind_Flag.
The arguments are:
INTERFACE:
int ESMC_CalendarDestroy( ESMC_Calendar *calendar // inout );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Releases all resources associated with this ESMC_Calendar.
The arguments are:
INTERFACE:
int ESMC_CalendarPrint( ESMC_Calendar calendar // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Prints out an ESMC_Calendar's properties to stdio, in support of testing and debugging.
The arguments are:
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.
INTERFACE:
int ESMC_TimeGet( ESMC_Time time, // in ESMC_I4 *yy, // out ESMC_I4 *h, // out ESMC_Calendar *calendar, // out enum ESMC_CalKind_Flag *calkindflag, // out int *timeZone // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Gets the value of an ESMC_Time in units specified by the user.
The arguments are:
INTERFACE:
int ESMC_TimePrint( ESMC_Time time // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Prints out an ESMC_Time's properties to stdio, in support of testing and debugging.
The arguments are:
INTERFACE:
int ESMC_TimeSet( ESMC_Time *time, // inout ESMC_I4 yy, // in ESMC_I4 h, // in ESMC_Calendar calendar, // in enum ESMC_CalKind_Flag calkindflag, // in int timeZone // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Initializes an ESMC_Time with a set of user-specified units.
The arguments are:
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.
INTERFACE:
int ESMC_TimeIntervalGet( ESMC_TimeInterval timeinterval, // in ESMC_I8 *s_i8, // out ESMC_R8 *h_r8 // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Gets the value of an ESMC_TimeInteval in units specified by the user.
The arguments are:
INTERFACE:
int ESMC_TimeIntervalPrint( ESMC_TimeInterval timeinterval // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Prints out an ESMC_TimeInterval's properties to stdio, in support of testing and debugging.
The arguments are:
INTERFACE:
int ESMC_TimeIntervalSet( ESMC_TimeInterval *timeinterval, // inout ESMC_I4 h // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Sets the value of the ESMC_TimeInterval in units specified by the user.
The arguments are:
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.
INTERFACE:
int ESMC_ClockAdvance( ESMC_Clock clock // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Advances the ESMC_Clock's current time by one time step.
The arguments are:
INTERFACE:
ESMC_Clock ESMC_ClockCreate( const char *name, // in ESMC_TimeInterval timeStep, // in ESMC_Time startTime, // in ESMC_Time stopTime, // in int *rc // out );RETURN VALUE:
Newly created ESMC_Clock object.DESCRIPTION:
Creates and sets the initial values in a new ESMC_Clock object.
The arguments are:
INTERFACE:
int ESMC_ClockDestroy( ESMC_Clock *clock // inout );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Releases all resources associated with this ESMC_Clock.
The arguments are:
INTERFACE:
int ESMC_ClockGet( ESMC_Clock clock, // in ESMC_TimeInterval *currSimTime, // out ESMC_I8 *advanceCount // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Gets one or more of the properties of an ESMC_Clock.
The arguments are:
INTERFACE:
int ESMC_ClockPrint( ESMC_Clock clock // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Prints out an ESMC_Clock's properties to stdio, in support of testing and debugging.
The arguments are:
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.
INTERFACE:
ESMC_Config ESMC_ConfigCreate( int* rc // out );RETURN VALUE:
ESMC_Config* to newly allocated ESMC_ConfigDESCRIPTION:
Creates an ESMC_Config for use in subsequent calls.
The arguments are:
INTERFACE:
int ESMC_ConfigDestroy( ESMC_Config* config // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Destroys the config object.
The arguments are:
INTERFACE:
ESMC_Config ESMC_ConfigCreateFromSection( ESMC_Config config, // in const char* olabel, // in const char* clabel, // in int* rc // out );RETURN VALUE:
ESMC_Config* to newly allocated ESMC_ConfigDESCRIPTION:
Instantiates an ESMC_Config object from a section of an existing ESMC_Config object delimited by openlabel and closelabel. An error is returned if neither of the input labels is found in input config.
Note that a section is intended as the content of a given ESMC_Config object delimited by two distinct labels. Such content, as well as each of the surrounding labels, are still within the scope of the parent ESMC_Config object. Therefore, including in a section labels used outside that section should be done carefully to prevent parsing conflicts.
The arguments are:
INTERFACE:
int ESMC_ConfigFindLabel( ESMC_Config config, // in const char* label, // in int *isPresent // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.
If label not found, and the {\tt isPresent} pointer is {\tt NULL},
an error will be returned.
DESCRIPTION:
Finds the label (key) in the config file.
Since the search is done by looking for a word in the whole resource file, it is important to use special conventions to distinguish labels from other words in the resource files. The DAO convention is to finish line labels by : and table labels by ::.
The arguments are:
INTERFACE:
int ESMC_ConfigFindNextLabel( ESMC_Config config, // in const char* label, // in int *isPresent // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.
If label not found, and the {\tt isPresent} pointer is {\tt NULL},
an error will be returned.
DESCRIPTION:
Finds the label (key) string in the config object, starting from the current position pointer.
This method is equivalent to ESMC_ConfigFindLabel, but the search is performed starting from the current position pointer.
The arguments are:
INTERFACE:
int ESMC_ConfigGetDim( ESMC_Config config, // in int* lineCount, // out int* columnCount, // out ... // optional argument list );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Returns the number of lines in the table in lineCount and the maximum number of words in a table line in columnCount.
The arguments are:
Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.
INTERFACE:
int ESMC_ConfigGetLen( ESMC_Config config, // in int* wordCount, // out ... // optional argument list );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Gets the length of the line in words by counting words disregarding types. Returns the word count as an integer.
The arguments are:
Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.
INTERFACE:
int ESMC_ConfigLoadFile( ESMC_Config config, // in const char* file, // in ... // optional argument list );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Resource file with filename is loaded into memory.
The arguments are:
Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.
INTERFACE:
int ESMC_ConfigNextLine( ESMC_Config config, // in int *tableEnd // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Selects the next line (for tables).
The arguments are:
INTERFACE:
int ESMC_ConfigPrint( ESMC_Config config // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Write content of a ESMC_Config object to standard output.
The arguments are:
INTERFACE:
int ESMC_ConfigValidate( ESMC_Config config, // in ... // optional argument list );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.
Equals ESMF_RC_ATTR_UNUSED if any unused attributes are found
with option "unusedAttributes" below.
DESCRIPTION:
Checks whether a config object is valid.
The arguments are:
Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.
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:
INTERFACE:
int ESMC_LogWrite( const char msg[], // in int msgtype // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Write an entry into the Log file.
The arguments are:
INTERFACE:
int ESMC_LogSet( int flush // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Set Log properties.
The arguments 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).
INTERFACE:
int ESMC_VMBarrier( ESMC_VM vm // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Collective ESMC_VM communication call that blocks calling PET until all PETs of the VM context have issued the call.
The arguments are:
INTERFACE:
int ESMC_VMBroadcast(ESMC_VM vm,
void *bcstData,
int count,
enum ESMC_TypeKind_Flag *typekind,
int rootPet);
RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Collective ESMC_VM communication call that broadcasts a contiguous data array from rootPet to all other PETs of the ESMC_VM object.
This method is overloaded for: ESMC_TYPEKIND_I4, ESMC_TYPEKIND_I8, ESMC_TYPEKIND_R4, ESMC_TYPEKIND_R8, ESMC_TYPEKIND_LOGICAL.
The arguments are:
INTERFACE:
int ESMC_VMGet( ESMC_VM vm, // in int *localPet, // out int *petCount, // out int *peCount, // out MPI_Comm *mpiCommunicator, // out int *pthreadsEnabledFlag, // out int *openMPEnabledFlag // out );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Get internal information about the specified ESMC_VM object.
The arguments are:
INTERFACE:
ESMC_VM ESMC_VMGetCurrent( int *rc // out );RETURN VALUE:
VM object of the current execution context.DESCRIPTION:
Get the ESMC_VM object of the current execution context. Calling ESMC_VMGetCurrent() within an ESMC Component, will return the same VM object as ESMC_GridCompGet(..., vm=vm, ...) or ESMC_CplCompGet(..., vm=vm, ...).
The main purpose of providing ESMC_VMGetCurrent() is to simplify ESMF adoption in legacy code. Specifically, code that uses MPI_COMM_WORLD deep within its calling tree can easily be modified to use the correct MPI communicator of the current ESMF execution context. The advantage is that these modifications are very local, and do not require wide reaching interface changes in the legacy code to pass down the ESMF component object, or the MPI communicator.
The use of ESMC_VMGetCurrent() is strongly discouraged in newly written Component code. Instead, the ESMF Component object should be used as the appropriate container of ESMF context information. This object should be passed between the subroutines of a Component, and be queried for any Component specific information.
Outside of a Component context, i.e. within the driver context, the call
to ESMC_VMGetCurrent() is identical to ESMC_VMGetGlobal().
The arguments are:
INTERFACE:
ESMC_VM ESMC_VMGetGlobal( int *rc // out );RETURN VALUE:
VM object of the global execution context.DESCRIPTION:
Get the global ESMC_VM object. This is the VM object that is created during ESMC_Initialize() and is the ultimate parent of all VM objects in an ESMF application. It is identical to the VM object returned by ESMC_Initialize(..., vm=vm, ...).
The ESMC_VMGetGlobal() call provides access to information about the global execution context via the global VM. This call is necessary because ESMF does not create a global ESMF Component during ESMC_Initialize() that could be queried for information about the global execution context of an ESMF application.
Usage of ESMC_VMGetGlobal() from within Component code is
strongly discouraged. ESMF Components should only access their own VM
objects through Component methods. Global information, if required by
the Component user code, should be passed down to the Component from the
driver through the Component calling interface.
The arguments are:
INTERFACE:
int ESMC_VMLogMemInfo( const char *prefix // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Write memory info to the log file.
The arguments are:
INTERFACE:
int ESMC_VMPrint( ESMC_VM vm // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Print internal information of the specified ESMC_VM object.
The arguments are:
INTERFACE:
int ESMC_VMReduce(ESMC_VM vm,
void *sendData,
void *recvData,
int count,
enum ESMC_TypeKind_Flag *typekind,
enum ESMC_Reduce_Flag *reduceflag,
int rootPet);
RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Collective ESMC_VM communication call that reduces a contiguous data array across the ESMC_VM object into a contiguous data array of the same <type><kind>. The result array is returned on rootPet. Different reduction operations can be specified.
This method is overloaded for: ESMC_TYPEKIND_I4, ESMC_TYPEKIND_I8, ESMC_TYPEKIND_R4, ESMC_TYPEKIND_R8.
The arguments are:
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 |
INTERFACE:
int ESMC_TraceRegionEnter( const char* name // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Enter a named trace region.
The arguments are:
INTERFACE:
int ESMC_TraceRegionExit( const char* name // in );RETURN VALUE:
Return code; equals ESMF_SUCCESS if there are no errors.DESCRIPTION:
Exit a named trace region.
The arguments are:
esmf_support@ucar.edu