[mpas-developers] proposed date/time manager

Michael Duda duda at ucar.edu
Thu Apr 21 14:30:53 MDT 2011


Hi, All.

I've updated the time manager document. I removed the requirement that
the time manager be able to choose a time step automatically based on
the model resolution, since this choice may be highly dependent on the
particular core and would be best left to the user; I also removed the
requirements concerning notifications based on wall-clock time. I added
Phil's suggestion below to the requirements, and the new design chapter
is essentially an interface specification.

One question that came to my mind is whether the requirement that the
time manager support simulations of 100,000 years without round-off
imply the need to support a millenium in addition to a four-digit year?

Any comments or other contributions would be welcomed.

Cheers,
Michael


On Fri, Feb 18, 2011 at 11:39:40AM -0700, Jones, Philip W wrote:
> 
> Of course, as soon as I sent that, I remembered another requirement.  It's often useful for both alarms/notification and queries to be based on previous or next intervals (e.g. Was the last step a coupling step or is the next step...).
> 
> Phil
> ---
> Correspondence/TSPA/DUSA EARTH
> ------------------------------------------------------------
> Philip Jones                                pwjones at lanl.gov
> Climate, Ocean and Sea Ice Modeling
> Los Alamos National Laboratory
> T-3 MS B216                                 Ph: 505-500-2699
> PO Box 1663                                Fax: 505-665-5926
> Los Alamos, NM 87545-1663
> 
> 
> 
-------------- next part --------------
\documentclass[11pt]{report}

\usepackage{epsf,amsmath,amsfonts}
\usepackage{graphicx}
\usepackage{hyperref}

\setlength{\topmargin}{0in}
\setlength{\headheight}{0in}
\setlength{\headsep}{0in}
\setlength{\textheight}{9.0in}
\setlength{\textwidth}{6.5in}
\setlength{\evensidemargin}{0in}
\setlength{\oddsidemargin}{0in}

\newlength{\hangfunction}

\newenvironment{routine}{\vspace{12pt}\hrule\par\vspace{12pt}}{\vspace{24pt}}
\newenvironment{inputs}{\vspace{12pt} \par \noindent{\large \textbf{Input}\par\vspace{6pt}\par}}{}
\newenvironment{outputs}{\vspace{12pt} \par \noindent{\large \textbf{Output}\par\vspace{6pt}\par}}{}
\newcommand{\function}[2]{\phantomsection\addcontentsline{toc}{subsection}{#1}\noindent{\large function}\par\vspace{-8pt}\settowidth{\hangfunction}{{\Large #1(}}\begin{flushleft}\hangindent=\hangfunction \Large #1(#2)\end{flushleft}\vspace{0pt}}
\newcommand{\subroutine}[2]{\phantomsection\addcontentsline{toc}{subsection}{#1}\noindent{\large subroutine}\par\vspace{-8pt}\settowidth{\hangfunction}{{\Large #1(}}\begin{flushleft}\hangindent=\hangfunction \Large #1(#2)\end{flushleft}\vspace{0pt}}
\newcommand{\summary}[1]{\noindent #1}
\newcommand{\argument}[3]{\hangindent=0.75in #2 :: {\large #1} --- \emph{#3}\par\vspace{4pt}}
\newcommand{\returnvalue}[1]{\vspace{12pt} \par \noindent{\large \textbf{Return value}\par\vspace{6pt}\par}{#1}\par}

\begin{document}

\title{A time manager for MPAS}
\author{MPAS Development Team}

\maketitle
\tableofcontents

%--------------------------------------------------------------------------------------------
% Summary
%--------------------------------------------------------------------------------------------

\chapter{Summary}

In the current MPAS code, time is simply tracked as the number of time steps since the beginning of the simulation; with the time step length also known, the code can multiply the time step length by the number of steps taken to find the elapsed time. However, because there is no calendar date and time associated with the start of the model simulation, there is no concept of `real time' in a simulation --- that is, a  simulation has no way of distinguishing whether it is currently, say, January or July.

When performing real-data simulations of the atmosphere (and perhaps of other physical domains, too), certain physics schemes must know the calendar date and time at each step in the model integration. For example, a short-wave radiation scheme needs to know the solar zenith angle, which it computes from the date and time of day. To someone looking at model output, it would also be important to know the date and time for which a particular set of fields is valid; without such information, validating model simulations becomes nearly impossible.

Besides lacking the date and time at any point in a model simulation, the current MPAS time-keeping method provides no unified mechanism for identifying when arbitrarily defined points in the simulation have been reached, at which time some action may be taken. For example, the work of determining whether it is time to perform I/O currently falls on the driver code, which uses the current time step modulo some output interval specified in time steps; adjustments to the model time step are therefore usually accompanied by changes to the output interval. Using a sophisticated, future I/O subsystem in MPAS, we may like to perform I/O on multiple streams (e.g., files) at different intervals specified in natural time units rather than model time steps; in such cases, the simple-minded approach that is currently used becomes cumbersome, especially if the future I/O implementation is to be run-time configurable in terms of the number of streams.

To permit progress on the addition of physics schemes and the re-implementation of the MPAS I/O sub-system in a more general and robust way, this document proposes the addition of a new time management system, which will be general enough to be used throughout the MPAS code. This new system should be useful for tracking the date and time, providing notifications when pre-specified points in time have been reached, and tracking the progress through time of a model simulation (i.e., model time-stepping).


%--------------------------------------------------------------------------------------------
% Requirements
%--------------------------------------------------------------------------------------------

\chapter{Requirements}

Date last modified: 2011/03/28 \\
Contributors: Michael Duda, Phil Jones

\section{General date/time tracking}

The most fundamental requirement for the new MPAS time management system is the ability to track the current date/time through the course of a model simulation.

\subsection{Set the starting and ending date/time}

Recognizing that there is always a finite amount of wallclock time that can be devoted to any simulation, it follows that every simulation is associated with a starting and ending \emph{simulation} date/time. The MPAS time manager is required to maintain these two points explicitly, since their relation to the current simulation time determines whether a simulation has completed or not. In the case of `cycled' simulations, which in principle could be extended indefinitely given an infinite amount of computer time, the ending date/time represents the end of the simulation cycle currently being run. It must be possible for the user to reset the starting or ending time at any point during the model simulation. 

\subsection{Determine whether the starting or ending time has been reached}

Determining whether the ending time has been reached or exceeded is a requirement for knowing when integration should stop in MPAS. For integration backward in time, the same requirement holds, except the role of the ending time is fulfilled by the starting time.

\subsection{Set the default time increment}

An MPAS simulation generally makes use of a fixed, default time step length, and the time manager must be able to record this time step so that the date/time can be incremented without the need to specify the increment explicitly each time step. It must also be possible for the user to reset the default time step at any point during the model simulation.  The user must be able to specify this default time increment as a time interval in any supported unit (see Units).

\subsection{Advance the date/time by an arbitrary time increment}

In future, we may like to implement the ability in MPAS to vary the time step over the course of a simulation, according to criteria such as the maximum Courant number in the previous time step; therefore, the time manager must be able to advance the date/time by an arbitrary time increment in addition to incrementing by the default time step.

\subsection{Handle both forward and backward time increments}

The ability to `advance' the date/time by a negative time increment --- that is, to step backward through time --- may be useful for further model development. For example, the addition of a digital filtering initialization scheme would require the ability to integrate both forward and backward in time, and, therefore, to increment the date/time with both positive and negative increments. The MPAS time manager must support both forward and backward increments.

\subsection{Perform time computation with no round-off using exact arithmetic}

The ability of the time manager to track time using exact arithmetic is necessary so that, for example, events take place at the proper time, and not at the time step before or after due to rounding errors in the date/time computation.  Simulations of up to 100,000 years without roundoff accumulation are required.

\section{Notifications}

Upcoming developments in MPAS will require the ability to determine when pre-specified points in the model simulation have been reached. For example, we may want to update tendencies from physics parameterizations periodically at an interval longer than the time step. Another planned development that would require the ability to perform actions at pre-determined points is in the I/O system, where we may want to read (in the case of boundary conditions, for example) or write fields to any of several I/O streams periodically. In general, we require the time manager to have the ability to provide notifications to code when specified points in time have been reached.

\subsection{Add notifications}

Clearly, the ability to specify the instants in time where notifications are to be provided is required of the time manager. It must be possible to add notifications at any point in program execution, so that not all notifications need to be added at initialization time.

\subsection{One-time notification}

The time manager will support notifications that only ring once for a particular time.

\subsection{Recurring notification}

The time manager must support the setting of notifications which will recur with a fixed period, since some events (e.g., boundary updates, diagnostics, I/O) occur periodically. 

\subsection{Query for notifications}

The user must be able to query whether a notification or alarm is ``ringing''. It should be possible to query whether any alarms are currently ringing, or whether any alarms will begin to ring within a specified time interval from the current time.

\subsection{Clear a notification}

In order that a particular notification not be provided by the time manager in subsequent queries, it must be possible to clear a notification. Clearing an instance of a periodically recurring notification will only clear that particular instance.

\subsection{Remove a notification}

For both periodic and `one-off' notifications, it must be possible to remove those notifications from the time manager to prevent them from being provided in future queries for notifications.


\section{Time instants and time intervals}

The concepts of `time instants' and 'time intervals' are fundamental to the task of tracking time and providing notifications, so it is necessary that the MPAS time manager be able to perform basic manipulation of them.

\subsection{Time arithmetic}

The time manager will be able to:
\begin{itemize}
\item compute a new time instant given a time instant and a time interval (either negative or positive);
\item compute a new time interval as the sum or difference of two other time intervals;
\item compute the (positive or negative) time interval between two time instants;
\item multiply a time interval by an integer constant;
\item divide a time interval by an integer constant; and
\item compute the remainder (as a time interval) when dividing one time interval by another.
\end{itemize}


\section{Calendars and units}

The time manager must be able to track time in a variety of units and calendars.

\subsection{Calendars}

The time manager must, at minimum, support a Gregorian calendar, and must support the ability to enable or disable leap years.  Other calendars that may need to be supported are 360-day (30-day equal month) calendars or Julian Day calendars.

\subsection{Units}

The time manager must support time intervals and time instants in units of hours, minutes, seconds, days, months and years (and fractions thereof).  The underlying representation can be in arbitrary units (to support the roundoff requirements above), but user queries and arguments must support these units.

\subsection{Unit conversion}

A set of utilities must be available to convert units for time-related quantities (e.g. days to seconds, etc.).  Some conversions may require knowledge of the calendar choice.



%--------------------------------------------------------------------------------------------
% Design
%--------------------------------------------------------------------------------------------

\chapter{Design}

In order to make the MPAS time manager as re-usable as possible, and to facilitate incremental implementation of the time manager in various parts of the MPAS code, we envision the MPAS time manager as a stand-alone module that provides opaque data types for clocks (instantiations of the time manager), time instants, and time intervals; additionally, the module will provide a set of routines for manipulating these types. Since the internal representation of clocks, time instants, and time intervals should remain unknown to code outside the module, we only describe the routines to be provided by the module.


\section{General date/time tracking}
Date last modified: 2011/04/21 \\
Contributors: Michael Duda \\

The routines used to create, destroy, and manipulate instantiations of the MPAS time manager (clocks) are described below. There is no limit to the number of concurrent clocks that can be created and used by code that employs the MPAS time manager.
\vspace{0.25in}

\begin{routine}
\subroutine{MPAS\_createClock}{clock, calendar, startTime, timeStep, stopTime, runDuration, ierr}
\summary{Creates a clock object given a calendar type, a starting time, a default time step, and either a stop time or a run duration.}
\begin{inputs}
\argument{calendar}{integer}{The calendar to use for the clock, either GREGORIAN or GREGORIAN\_NOLEAP}
\argument{startTime}{MPAS\_Time\_type}{The start time of the clock}
\argument{timeStep}{MPAS\_TimeInterval\_type}{The default time step of the clock}
\argument{stopTime}{MPAS\_Time\_type, optional}{The end time of the clock, which equals (startTime + runDuration)}
\argument{runDuration}{MPAS\_TimeInterval\_type, optional}{The run duration of the clock, defined as (stopTime - startTime)}
\end{inputs}
\begin{outputs}
\argument{clock}{MPAS\_Clock\_type}{An initialized MPAS clock}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_destroyClock}{clock, ierr}
\summary{Destroys a clock object.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock to be destroyed}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\function{MPAS\_isClockStartTime}{clock, ierr}
\summary{Tells whether the current time on the clock is at or before the clock's start time.}
\returnvalue{A logical TRUE if the current time is at or before the start time, and FALSE otherwise.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock to be queried}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\function{MPAS\_isClockEndTime}{clock, ierr}
\summary{Tells whether the current time on the clock is at or past the clock's stop time.}
\returnvalue{A logical TRUE if the current time is at or past the stop time, and FALSE otherwise.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock to be queried}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_setClockDirection}{clock, direction, ierr}
\summary{Sets the clock's direction of advance to be either positive/forward or negative/backward.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock whose direction is to be set}
\argument{direction}{integer}{Either of the module-defined constants FORWARD or BACKWARD}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getClockDirection}{clock, direction, ierr}
\summary{Retrieves the clock's direction of advance, either positive/forward or negative/backward.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{A clock}
\end{inputs}
\begin{outputs}
\argument{direction}{integer}{Either of the module-defined constants FORWARD or BACKWARD}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_setClockTimeStep}{clock, timeStep, ierr}
\summary{Sets the clock's default time step.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock whose time step is to be set}
\argument{timeStep}{MPAS\_TimeInterval\_type}{The new default time increment for the clock}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getClockTimeStep}{clock, timeStep, ierr}
\summary{Retrieves the clock's default time step.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{A clock}
\end{inputs}
\begin{outputs}
\argument{timeStep}{MPAS\_TimeInterval\_type}{The clock's default time increment}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_advanceClock}{clock, timeStep, ierr}
\summary{Advances the clock's current time by the specified time step, or by the clock's default time step if no explicit step is specified.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock to be advanced}
\argument{timeStep}{MPAS\_TimeInterval\_type, optional}{A time increment to be used in place of the clock's default increment}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_setClockTime}{clock, clock\_time, whichTime, ierr}
\summary{Sets the clock's start, stop, or current time depending on the whichTime argument.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock whose time is to be set}
\argument{clock\_time}{MPAS\_Time\_type}{The time instant to become the start, stop, or current time of the clock}
\argument{whichTime}{integer}{Which time to set, either START\_TIME, STOP\_TIME, or NOW}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getClockTime}{clock, whichTime, clock\_time, ierr}
\summary{Gets the clock's start, stop, or current time, depending on the whichTime argument.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock whose time is to be retrieved}
\argument{whichTime}{integer}{Which time to get, either START\_TIME, STOP\_TIME, or NOW}
\end{inputs}
\begin{outputs}
\argument{clock\_time}{MPAS\_Time\_type}{The start, stop, or current time of the clock}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}


\section{Notifications}
Date last modified: 2011/04/21 \\
Contributors: Michael Duda \\

Rather than using non-intrinsic data types to represent notifications, the MPAS time manager will identify notifications as user-specified integer ID numbers relative to clocks (i.e., the same ID can refer to different notifications in different clocks).
\vspace{0.25in}

\begin{routine}
\subroutine{MPAS\_addClockAlarm}{clock, alarmID, alarmTime, alarmTimeInterval, relativeToTime, recurring, ierr}
\summary{Adds an alarm to the clock, with the nature of the alarm --- either `one-off' or recurring --- depending on the combination of arguments.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock to which the alarm will be added}
\argument{alarmID}{integer}{The alarmID that will be used to identify the alarm}
\argument{alarmTime}{MPAS\_Time\_type}{The time of the alarm}
\argument{alarmTimeInterval}{MPAS\_TimeInterval\_type}{The interval of the alarm}
\argument{relativeToTime}{MPAS\_Time\_type}{The the base time that the interval is relative to}
\argument{recurring}{logical}{Whether or not the alarm is a recurring alarm}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\function{MPAS\_isAlarmRinging}{clock, alarmID, interval, ierr}
\summary{Tells whether the specified alarm is ringing on the clock, or whether it will begin ringing within the optional time interval from the present.}
\returnvalue{A logical TRUE if the alarm is ringing and FALSE otherwise.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock holding the alarm to be queried}
\argument{alarmID}{integer}{The alarmID to be queried}
\argument{interval}{MPAS\_TimeInterval\_type, optional}{The interval over which to consider the alarm}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_removeClockAlarm}{clock, alarmID, ierr}
\summary{Removes the specified alarm from the clock.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock from which the alarm will be removed}
\argument{alarmID}{integer}{The alarmID to remove from the clock}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_resetClockAlarm}{clock, alarmID, ierr}
\summary{Resets the specified alarm if it is ringing.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{The clock holding the alarm to be reset}
\argument{alarmID}{integer}{The alarmID to be reset}
\end{inputs}
\begin{outputs}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getClockRingingAlarms}{clock, nAlarms, alarmList, interval, ierr}
\summary{Returns a list of all the alarms that are currently ringing, or will begin ringing within the optional time interval, including those that were ringing before the current time but had not been reset.}
\begin{inputs}
\argument{clock}{MPAS\_Clock\_type}{A clock}
\argument{interval}{MPAS\_TimeInterval\_type}{The interval over which to consider alarms}
\end{inputs}
\begin{outputs}
\argument{nAlarms}{integer}{The number of alarms returned in the alarmList}
\argument{alarmList}{integer, dimension(MAX\_ALARMS)}{A list of IDs for alarms that are ringing}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}


\section{Time instants and time intervals}
Date last modified: 2011/03/28 \\
Contributors: Michael Duda \\

Time intervals and time instants in the MPAS time manager are `shallow' types, and require no \emph{create} or \emph{destroy} routines. In this section, the routines used to set, get, and format time instants and time intervals are described. 
\vspace{0.25in}

\begin{routine}
\subroutine{MPAS\_setTime}{curr\_time, YYYY, MM, DD, H, M, S, S\_n, S\_d, dateString, ierr}
\summary{Sets the date and time of a time instant. If a dateString is given, the integer arguments are ignored.}
\begin{inputs}
\argument{YYYY}{integer, optional}{The year}
\argument{MM}{integer, optional}{The month}
\argument{DD}{integer, optional}{The day}
\argument{H}{integer, optional}{The hour}
\argument{M}{integer, optional}{The minute}
\argument{S}{integer, optional}{The second}
\argument{S\_n}{integer, optional}{The numerator of a rational fraction of a second}
\argument{S\_d}{integer, optional}{The denominator of a rational fraction of a second}
\argument{dateString}{character(len=*), optional}{The date/time in the form YYYY-MM-DD[\_H[:M[:S]]]}
\end{inputs}
\begin{outputs}
\argument{curr\_time}{MPAS\_Time\_type}{The time instant described by the input arguments}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getTime}{curr\_time, YYYY, MM, DD, H, M, S, S\_n, S\_d, dateString, ierr}
\summary{Gets the date and time of a time instant. If a dateString is given, none of the integer arguments will be set.}
\begin{inputs}
\argument{curr\_time}{MPAS\_Time\_type}{A time instant}
\end{inputs}
\begin{outputs}
\argument{YYYY}{integer, optional}{The year}
\argument{MM}{integer, optional}{The month}
\argument{DD}{integer, optional}{The day}
\argument{H}{integer, optional}{The hour}
\argument{M}{integer, optional}{The minute}
\argument{S}{integer, optional}{The second}
\argument{S\_n}{integer, optional}{The numerator of a rational fraction of a second}
\argument{S\_d}{integer, optional}{The denominator of a rational fraction of a second}
\argument{dateString}{character(len=*), optional}{The date/time in the form YYYY-MM-DD\_H:M:S.SSS}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_setTimeInterval}{interval, YYYY, MM, DD, H, M, S, S\_n, S\_d, dateString, ierr}
\summary{Sets the length of a time interval. The integer arguments are cumulative; if a date string is given, the integer arguments are ignored.}
\begin{inputs}
\argument{YYYY}{integer, optional}{The number of years in the interval}
\argument{MM}{integer, optional}{The number of months}
\argument{DD}{integer, optional}{The number of days}
\argument{H}{integer, optional}{The number of hours}
\argument{M}{integer, optional}{The number of minutes}
\argument{S}{integer, optional}{The number of whole seconds}
\argument{S\_n}{integer, optional}{The numerator of a rational fraction of a seconds}
\argument{S\_d}{integer, optional}{The denominator of a rational fraction of a seconds}
\argument{dateString}{character(len=*), optional}{The time interval in the form YYYY-MM-DD[\_H[:M[:S]]]}
\end{inputs}
\begin{outputs}
\argument{interval}{MPAS\_TimeInterval\_type}{The time interval described by the input arguments}
\argument{ierr}{integer}{The return error code}
\end{outputs}
\end{routine}

\begin{routine}
\subroutine{MPAS\_getTimeInterval}{interval, YYYY, MM, DD, H, M, S, S\_n, S\_d, dateString, ierr}
\summary{Gets the length of a time interval. If a dateString is given, none of the integer arguments will be set.}
\begin{inputs}
\argument{interval}{MPAS\_TimeInterval\_type}{A time interval}
\end{inputs}
\begin{outputs}
\argument{YYYY}{integer, optional}{The number of years in the interval}
\argument{MM}{integer, optional}{The number of months}
\argument{DD}{integer, optional}{The number of days}
\argument{H}{integer, optional}{The number of hours}
\argument{M}{integer, optional}{The number of minutes}
\argument{S}{integer, optional}{The number of whole seconds}
\argument{S\_n}{integer, optional}{The numerator of a rational fraction of a seconds}
\argument{S\_d}{integer, optional}{The denominator of a rational fraction of a seconds}
\argument{dateString}{character(len=*), optional}{The time interval in the form YYYY-MM-DD\_H:M:S.SSS}
\argument{ierr}{integer}{The return error code}
\end{outputs}

\end{routine}

In addition to the above routines, operators will be defined for the following operations:

\begin{itemize}
\item time = time + interval
\item time = time - interval
\item interval = interval + interval
\item interval = interval - interval
\item interval = interval \% interval
\item interval = time - time
\item interval = interval * n
\item interval = interval / n
\item interval = -interval
\end{itemize}


\section{Calendars and units}
Date last modified: 2011/03/28 \\
Contributors: Michael Duda \\

Perhaps there is nothing much to say about units?

Unit conversions are handled by the design of the interfaces for setting and getting time instants and time intervals.


%--------------------------------------------------------------------------------------------
% Implementation
%--------------------------------------------------------------------------------------------

\chapter{Proposed Plan for Implementation}

Date last modified: 2011/04/21 \\
Contributors: Michael Duda \\

Roughly speaking, the implementation of the time manager will follow these steps: 

\begin{enumerate}
\item Implement the routines and operators described in Chapter 3 in a single, independent module to be located in the framework directory.
\item Add the necessary code throughout the framework so that a `master' clock for a simulation will be initialized based on namelist parameters
for the starting time, ending time, and time step.
\item Add code so that the master clock is updated during the course of model simulation by the mpas\_run() routines of individual MPAS cores.
\item Write and read date/time information from the clock to input, output, and restart files in the same way as the current xtime variable.
\end{enumerate}

%--------------------------------------------------------------------------------------------
% Testing and Validation
%--------------------------------------------------------------------------------------------

\chapter{Testing and Validation}

\section{Testing and Validation: XXX}
Date last modified: 2011/01/05 \\
Contributors: (add your name to this list if it does not appear) \\

TBD


%-----------------------------------------------------------------------

\end{document}
-------------- next part --------------
A non-text attachment was scrubbed...
Name: time_manager_reqts.pdf
Type: application/pdf
Size: 139447 bytes
Desc: not available
Url : http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20110421/ff21ed38/attachment-0001.pdf 


More information about the mpas-developers mailing list