[mpas-developers] proposed date/time manager

[Michael Duda]

Hi, All.

Todd and several of us at NCAR had the chance to meet earlier this
week to discuss MPAS developments, and one of the items that
appeared at the top of the list of needs in MPAS is a date/time
manager. To begin the requirements and design process for this new
module, I've written a first draft of a summary and requirements
list based on the MPAS design template that was circulated in
January; I've attached this draft herewith as a PDF document and
LaTeX source. 

Since I've not consulted with anyone on the requirements in the
document, I expect that others may have additional items to add,
or may like to modify the requirements that I've written;
essentially, I claim no particular ownership of the document, so
anyone should feel free to comment, modify, or update as
necessary.

Once we are all satisfied that the stated requirements will meet
our needs in MPAS, perhaps we could then come up with a design and
implementation plan to meet those requirements. Also, it occurred
to me that the time manager might also serve as a test of our
requirements and design process to see, e.g., whether it is too
heavy or too light-weight.

Any contributions or comments on the attached document would be
greatly welcomed!
 
Cheers,
Michael
-------------- next part --------------
\documentclass[11pt]{report}

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

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


\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/02/17 \\
Contributors: Michael Duda

\section{Requirement: 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.

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

\vspace{12pt}
\emph{Should we also require the ability to operate according to different calendars, e.g., both a Gregorian and a no-leap-year calendar?}


\section{Requirement: 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 of the user to specify the points in time where notifications are to be provided is required of the time manager. In addition to `one-off' notifications, the time manager must also support the setting of notifications which will recur with a fixed period, since some events (e.g., boundary updates) occur periodically. 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{Query for notifications}

Rather than requiring the time manager to actively notify code when a specified date/time has been reached, we instead require that the time manager be capable of providing a list of notifications associated with times that have been reached since the last query to the time manager. Providing active notifications implies a significant change in programming paradigm from what is currently used in MPAS, so the passive approach required here is preferable.

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


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

\chapter{Design}

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

TBD


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

\chapter{Proposed Plan for Implementation}

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

TBD

%--------------------------------------------------------------------------------------------
% 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: 70787 bytes
Desc: not available
Url : http://mailman.ucar.edu/pipermail/mpas-developers/attachments/20110217/94f765c1/attachment-0001.pdf