Subsections

5 Infrastructure: Utilities

24 Overview of Infrastructure Utility Classes

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.

25 Time Manager Utility

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.

25.1 Time Manager Classes

There are four ESMF classes that represent time concepts:

25.2 Calendar

The set of supported calendars includes:
Gregorian
The standard Gregorian calendar.
no-leap
The Gregorian calendar with no leap years.
Julian
The standard Julian date calendar.
Julian Day
The standard Julian days calendar.
Modified Julian Day
The Modified Julian days calendar.
360-day
A 30-day-per-month, 12-month-per-year calendar.
no calendar
Tracks only elapsed model time in hours, minutes, seconds.
See Section 26.1 for more details on supported standard calendars, and how to create a customized ESMF Calendar.


25.3 Time Instants and TimeIntervals

TimeIntervals and Time instants (simply called Times) are the computational building blocks of the Time Manager utility. Times support different queries for values of individual Time components such as year and hour. See Sections 27.1 and 28.1, respectively, for use of Times and TimeIntervals.

25.4 Clocks

It is useful to identify a higher-level concept to repeatedly step a Time forward by a TimeInterval. We refer to this capability as a Clock, and include in its required features the ability to store the start and stop times of a model run, and to query the value of quantities such as the current time and the number of time steps taken. Applications may contain temporary or multiple Clocks. Section 29.1 describes the use of Clocks in detail.

26 Calendar Class

26.1 Description

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.

26.2 Constants


26.2.1 ESMC_CALKIND

DESCRIPTION:
Supported calendar kinds.

The type of this flag is:

type(ESMF_CalKind_Flag)

The valid values are:

ESMC_CALKIND_360DAY
Valid range: machine limits
In the 360-day calendar, there are 12 months, each of which has 30 days. Like the no-leap calendar, this is a simple approximation to the Gregorian calendar sometimes used by modelers.

ESMC_CALKIND_GREGORIAN
Valid range: 3/1/4801 BC to 10/29/292,277,019,914
The Gregorian calendar is the calendar currently in use throughout Western countries. Named after Pope Gregory XIII, it is a minor correction to the older Julian calendar. In the Gregorian calendar every fourth year is a leap year in which February has 29 and not 28 days; however, years divisible by 100 are not leap years unless they are also divisible by 400. As in the Julian calendar, days begin at midnight.

ESMC_CALKIND_JULIAN
Valid range: 3/1/4713 BC to 4/24/292,271,018,333
The Julian calendar was introduced by Julius Caesar in 46 B.C., and reached its final form in 4 A.D. The Julian calendar differs from the Gregorian only in the determination of leap years, lacking the correction for years divisible by 100 and 400 in the Gregorian calendar. In the Julian calendar, any year is a leap year if divisible by 4. Days are considered to begin at midnight.

ESMC_CALKIND_JULIANDAY
Valid range: +/- 1x10$^{14}$
Julian days simply enumerate the days and fraction of a day which have elapsed since the start of the Julian era, defined as beginning at noon on Monday, 1st January of year 4713 B.C. in the Julian calendar. Julian days, unlike the dates in the Julian and Gregorian calendars, begin at noon.

ESMC_CALKIND_MODJULIANDAY
Valid range: +/- 1x10$^{14}$
The Modified Julian Day (MJD) was introduced by space scientists in the late 1950's. It is defined as an offset from the Julian Day (JD):

MJD = JD - 2400000.5

The half day is subtracted so that the day starts at midnight.

ESMC_CALKIND_NOCALENDAR
Valid range: machine limits
The no-calendar option simply tracks the elapsed model time in seconds.

ESMC_CALKIND_NOLEAP
Valid range: machine limits
The no-leap calendar is the Gregorian calendar with no leap years - February is always assumed to have 28 days. Modelers sometimes use this calendar as a simple, close approximation to the Gregorian calendar.

26.3 Class API

26.3.1 ESMC_CalendarCreate - Create a Calendar


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:

[name]
The name for the newly created Calendar. If not specified, i.e. NULL, a default unique name will be generated: "CalendarNNN" where NNN is a unique sequence number from 001 to 999.
calkindflag
The built-in ESMC_CalKind_Flag. Valid values are:
ESMC_CALKIND_360DAY,
ESMC_CALKIND_GREGORIAN,
ESMC_CALKIND_JULIAN,
ESMC_CALKIND_JULIANDAY,
ESMC_CALKIND_MODJULIANDAY,
ESMC_CALKIND_NOCALENDAR,
and ESMC_CALKIND_NOLEAP.
See Section 26.2 for a description of each calendar kind.
[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

26.3.2 ESMC_CalendarDestroy - Destroy a Calendar


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:

calendar
Destroy contents of this ESMC_Calendar.

26.3.3 ESMC_CalendarPrint - Print a Calendar


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:

calendar
ESMC_Calendar object to be printed.

27 Time Class

27.1 Description

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.

27.2 Class API

27.2.1 ESMC_TimeGet - Get a Time value


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:

time
ESMC_Time object to be queried.
[yy]
Integer year (>= 32-bit).
[h]
Integer hours.
[calendar]
Associated ESMC_Calendar.
[calkindflag]
Associated ESMC_CalKind_Flag.

27.2.2 ESMC_TimePrint - Print a Time


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:

time
ESMC_Time object to be printed.

27.2.3 ESMC_TimeSet - Initialize or set a Time


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:

time
ESMC_Time object to initialize or set.
yy
Integer year (>= 32-bit).
h
Integer hours.
calendar
Associated ESMC_Calendar. If not created, defaults to calendar ESMC_CALKIND_NOCALENDAR or default specified in ESMC_Initialize(). If created, has precedence over calkindflag below.
calkindflag
Specifies associated ESMC_Calendar if calendar argument above not created. More convenient way of specifying a built-in calendar kind.

28 TimeInterval Class

28.1 Description

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.

28.2 Class API

28.2.1 ESMC_TimeIntervalGet - Get a TimeInterval value


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:

timeinterval
ESMC_TimeInterval object to be queried.
[s_i8]
Integer seconds (large, >= 64-bit).
[h_r8]
Double precision hours.

28.2.2 ESMC_TimeIntervalPrint - Print a TimeInterval


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:

timeinterval
ESMC_TimeInterval object to be printed.

28.2.3 ESMC_TimeIntervalSet - Initialize or set a TimeInterval


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:

timeinterval
ESMC_TimeInterval object to initialize or set.
h
Integer hours.

29 Clock Class

29.1 Description

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.

29.2 Class API

29.2.1 ESMC_ClockAdvance - Advance a Clock's current time by one time step


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:

clock
ESMC_Clock object to be advanced.

29.2.2 ESMC_ClockCreate - Create a Clock


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:

[name]
The name for the newly created Clock. If not specified, i.e. NULL, a default unique name will be generated: "ClockNNN" where NNN is a unique sequence number from 001 to 999.
timeStep
The ESMC_Clock's time step interval, which can be positive or negative.
startTime
The ESMC_Clock's starting time. Can be less than or or greater than stopTime, depending on a positive or negative timeStep, respectively, and whether a stopTime is specified; see below.
stopTime
The ESMC_Clock's stopping time. Can be greater than or less than the startTime, depending on a positive or negative timeStep, respectively.
[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

29.2.3 ESMC_ClockDestroy - Destroy a Clock


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:

clock
Destroy contents of this ESMC_Clock.

29.2.4 ESMC_ClockGet - Get a Clock's properties


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:

clock
ESMC_Clock object to be queried.
[currSimTime]
The current simulation time.
[advanceCount]
The number of times the ESMC_Clock has been advanced.

29.2.5 ESMC_ClockPrint - Print the contents of a Clock


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:

clock
ESMC_Clock object to be printed.

30 Config Class

30.1 Description

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.

30.1.1 Package history

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.

30.2 Class API

30.2.1 ESMC_ConfigCreate - Create a Config object


INTERFACE:

 ESMC_Config ESMC_ConfigCreate(
   int* rc                    // out
 );
RETURN VALUE:
    ESMC_Config*  to newly allocated ESMC_Config
DESCRIPTION:

Creates an ESMC_Config for use in subsequent calls.

The arguments are:

[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

30.2.2 ESMC_ConfigDestroy - Destroy a Config object


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:

config
Already created ESMC_Config object to destroy.

30.2.3 ESMC_ConfigCreate - Create a Config object from a section of an existing Config object


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_Config
DESCRIPTION:

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:

config
The input ESMC_Config object.
openlabel
Label marking the beginning of a section in config.
closelabel
Label marking the end of a section in config.

30.2.4 ESMC_ConfigFindLabel - Find a label


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:

config
Already created ESMC_Config object.
label
Identifying label.
[isPresent]
Label presence flag. (optional). If non-NULL, the target is set to 1 when the label is found; otherwise set to 0.

30.2.5 ESMC_ConfigFindNextLabel - Find a label


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:

config
Already created ESMC_Config object.
label
Identifying label.
isPresent
If non-NULL, the address specified is given a value of 1 if the label is found, and 0 when the label is not found.

30.2.6 ESMC_ConfigGetDim - Get table sizes


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:

config
Already created ESMC_Config object.
lineCount
Returned number of lines in the table.
columnCount
Returned maximum number of words in a table line.
[label]
Identifying label (optional).

Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.

30.2.7 ESMC_ConfigGetLen - Get the length of the line in words


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:

config
Already created ESMC_Config object.
wordCount
Returned number of words in the line.
[label]
Identifying label. If not specified, use the current line (optional).

Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.

30.2.8 ESMC_ConfigLoadFile - Load resource file into memory


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:

config
Already created ESMC_Config object.
file
Configuration file name.
[delayout]
ESMC_DELayout associated with this config object. **NOTE: This argument is not currently supported.
[unique]
If specified as true, uniqueness of labels are checked and error code set if duplicates found (optional).

Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.

30.2.9 ESMC_ConfigNextLine - Find next line


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:

config
Already created ESMC_Config object.
[tableEnd]
End of table mark (::) found flag. Returns 1 when found, and 0 when not found.

30.2.10 ESMC_ConfigPrint - Write content of config object to standard output


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:

config
Already created ESMC_Config object.

30.2.11 ESMC_ConfigValidate - Validate a Config object


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:

config
Already created ESMC_Config object.
[options]
If none specified: simply check that the buffer is not full and the pointers are within range (optional). "unusedAttributes" - Report to the default logfile all attributes not retrieved via a call to ESMC_ConfigGetAttribute() or ESMC_ConfigGetChar(). The attribute name (label) will be logged via ESMC_LogErr with the WARNING log message type. For an array-valued attribute, retrieving at least one value via ESMC_ConfigGetAttribute() or ESMC_ConfigGetChar() constitutes being "used."

Due to this method accepting optional arguments, the final argument must be ESMC_ArgLast.

31 Log Class

31.1 Description

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.

31.2 Constants


31.2.1 ESMC_LOGKIND

DESCRIPTION:
Specifies a single log file, multiple log files (one per PET), or no log files.

The valid values are:

ESMC_LOGKIND_SINGLE
Use a single log file, combining messages from all of the PETs. Not supported on some platforms.
ESMC_LOGKIND_MULTI
Use multiple log files -- one per PET.
ESMC_LOGKIND_NONE
Do not issue messages to a log file.


31.2.2 ESMC_LOGMSG

DESCRIPTION:
Specifies a message level.

The valid values are:

ESMC_LOGMSG_INFO
Informational messages
ESMC_LOGMSG_WARNING
Warning messages
ESMC_LOGMSG_ERROR
Error messages
ESMC_LOGMSG_TRACE
Trace messages
ESMC_LOGMSG_DEBUG
Debug messages
ESMC_LOGMSG_JSON
JSON format messages

31.3 Class API

31.3.1 ESMC_LogWrite - Write an entry into the Log file


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:

msg
The message to be written.
msgtype
The message type. This flag is documented in section 31.2.2

31.3.2 ESMC_LogSet - Set Log properties


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:

flush
If set to ESMF_TRUE, flush log messages immediately, rather than buffering them. Default is to flush after 10 messages.

32 VM Class

32.1 Description

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).

32.2 Class API

32.2.1 ESMC_VMBarrier - block calling PETs until all PETS called


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:

vm
Queried ESMC_VM object.
[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

32.2.2 ESMC_VMBroadcast - Broadcast data across the VM


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:

vm
ESMC_VM object.
bcstData
Contiguous data array. On rootPet bcstData holds data that is to be broadcasted to all other PETs. On all other PETs bcstData is used to receive the broadcasted data.
count
Number of elements in bcstData. Must be the same on all PETs.
typekind
The typekind of the data to be reduced. See section 34.18 for a list of valid typekind options.
rootPet
PET that holds data that is being broadcast.

32.2.3 ESMC_VMGet - Get VM internals


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:

vm
Queried ESMC_VM object.
[localPet]
Upon return this holds the id of the PET that issued this call.
[petCount]
Upon return this holds the number of PETs in the specified ESMC_VM object.
[peCount]
Upon return this holds the number of PEs referenced by the specified ESMC_VM object.
[mpiCommunicator]
Upon return this holds the MPI intra-communicator used by the specified ESMC_VM object. This communicator may be used for user-level MPI communications. It is recommended that the user duplicates the communicator via MPI_Comm_Dup() in order to prevent any interference with ESMC communications.
[pthreadsEnabledFlag]
A return value of '1' indicates that the ESMF library was compiled with Pthreads enabled. A return value of '0' indicates that Pthreads are disabled in the ESMF library.
[openMPEnabledFlag]
A return value of '1' indicates that the ESMF library was compiled with OpenMP enabled. A return value of '0' indicates that OpenMP is disabled in the ESMF library.
[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

32.2.4 ESMC_VMGetCurrent - Get current VM


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:

[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

32.2.5 ESMC_VMGetGlobal - Get global VM


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:

[rc]
Return code; equals ESMF_SUCCESS if there are no errors.

32.2.6 ESMC_VMLogMemInfo - Log memory measurements to file


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:

prefix
String value to indicate the location of the memory measurement

32.2.7 ESMC_VMPrint - Print a VM


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:

vm
ESMC_VM object to be printed.

32.2.8 ESMC_VMReduce - Reduce data from across the VM


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:

vm
ESMC_VM object.
sendData
Contiguous data array holding data to be sent. All PETs must specify a valid source array.
recvData
Contiguous data array for data to be received. Only the recvData array specified by the rootPet will be used by this method.
count
Number of elements in sendData and recvData. Must be the same on all PETs.
typekind
The typekind of the data to be reduced. See section 34.18 for a list of valid typekind options.
reduceflag
Reduction operation. See section 34.14 for a list of valid reduce operations.
rootPet
PET on which reduced data is returned.

33 Profiling and Tracing

33.1 Description


33.1.1 Profiling

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


33.1.2 Tracing

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.

phase_enter
indicates entry into an initialize, run, or finalize ESMF component routine
phase_exit
indicates exit from an initialize, run, or finalize ESMF component routine
region_enter
indicates entry into a user-defined code region
region_exit
indicates exit from a user-defined code region

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 [*]). 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

33.2 Restrictions and Future Work

  1. Limited types of trace events. Currently only a few trace event types are available. The tracer may be extended in the future to record additional types of events.
  2. MPI call profing not available for statically linked executables on Darwin. Currently the linker on Darwin systems does not support the wrapping of symbols during static linking. In order to access MPI call profiling on Darwin, executables should be linked dynamically in combination with the procedure described in section [*].

33.3 Class API

33.3.1 ESMC_TraceRegionEnter - Enter a trace region


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:

name
Name of the trace region.

33.3.2 ESMC_TraceRegionExit - Exit a trace region


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:

name
Name of the trace region.

esmf_support@ucar.edu