timemgmt_reqdoc.tex

CCSM Research Tools: Community Atmosphere Model (CAM)

% $Header: /fs/cgd/csm/models/CVS.REPOS/shared/esmf/src/Infrastructure/TimeMgmt/doc/Attic/TimeMgmt_reqdoc.tex,v 1.1.6.1 2002/04/24 03:25:49 erik Exp $
% $Name: cam2_0_brnchT_release3 $

\documentclass[english]{article}
% \usepackage[T1]{fontenc}
% \usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{theorem}
\usepackage{fancyhdr}
\usepackage{lastpage}
\usepackage{supertabular}
\usepackage{html}

\newcommand{\abbr}{TMG }
\newcommand{\docversion}{Draft1}

\pagestyle{fancy}
\lhead{\abbr Requirements: \docversion }
\chead{}
\rhead{}
\lfoot{\abbr Requirements: \docversion }
\cfoot{}
\rfoot{\thepage\ of \pageref{LastPage}}

%%

\newtheorem{requirement}{\Large \abbr REQ}
\newtheorem{subreq}{\abbr REQ}[requirement]

\newenvironment
{reqlist}
{\begin{list} {} {} \rm \item[]}
{\end{list}}

\newcommand{\req}[1]{
\begin{requirement}
\addcontentsline{toc}{section}{R\arabic{requirement}{\it\bf\ #1}}
{\Large #1}
\end{requirement}
}

\newcommand{\sreq}[1]{
\begin{subreq}
\addcontentsline{toc}{section}{  R\arabic{requirement}.\arabic{subreq}{\it\ #1}}
{#1}
\end{subreq}
}
%%



\makeatletter
\makeatother

\begin{document}

\title{ESMF Time Manager Requirements Document}


\author{Brian Eaton, Chris Hill}
\date{}

\maketitle

\tableofcontents

\newpage
\part*{Part I - Overview}
\addcontentsline{toc}{section}{Part I - Overview}


\section{Introduction}

This document lays out the detailed requirements for the ESMF Time Manager (\abbr). 
The \abbr requirements document is the mechanism by which features that will be 
included in the \abbr implementation are identified. The \abbr implementation 
will contain features that derive from the requirements laid out in Part II of the 
\abbr requirements document (this document) or from requirements laid out in 
subsequent revisions of the \abbr requirements document or from the general 
ESMF coding standards and practices documents.

\section{Document Structure}

This document contains a brief background section summarizing the overall role 
of the \abbr. The terms section lists key terms that are used in the \abbr 
requirements. The \abbr requirements section gives an itemized list of detailed 
requirements. Each requirement item is numbered using a two level numbering 
scheme. The primary number refers to a {\it broad requirement} and the 
secondary number refers to {\it sub-requirements}. The {\it sub-requirements} 
clarify and qualify the broad requirement they relate to. Background information
is given after each requirement.


\section{\abbr Background}

Many of the components that will run and interact within the ESMF
are prognostic simulation codes employing time-stepping approaches
to solve a numerical implementation of a set of mathematical equations.
Coordinating component to component interactions and coordinating interactions
between components and external systems, from which data is ingested
or to which data is exported, requires precise notions of time. The
role of the \abbr is to provide a standard set of \char`\"{}time services\char`\"{}
to components running under ESMF. The \abbr set of \char`\"{}time services\char`\"{}
will be part of the ESMF Infrastructure layer. Including these services
withing the ESMF Infrastructure layer permits

\begin{itemize}
\item Development of multiple components with compatible notions of time.
\item Development of a robust, core library of common time functions.
\end{itemize}

The \abbr is not intended to be a comprehensive set of services for
all time related operations. For example it will not include a complete
time-zone capability that supports translation between all of the
more than 300 time-zones used on the Earth today. However, the \abbr
will provide a generic foundation for developing libraries that do
provide bespoke time services. As such the \abbr is anticipated to
be a library of software that is targeted at both ESMF component 
developers and at specialized library developers.

\section{\abbr Terms}

\tablefirsthead{}
\tablehead{\Large \bf \abbr Terms cont...\vspace{2mm} \\}
\tabletail{}
\tablelasttail{}

\begin{supertabular}{ll}
{\Large \bf alarm}&
\multicolumn{1}{p{95mm}}{
The \abbr implementation will provide a concept that supports behaviors 
like the behavior of the alarm described in Part II. An alarm is an event 
that occurs at a particular time (or set of times).  It is like a real 
alarm on a real alarm clock except that, in order to determine whether 
it is "ringing", an alarm is "read" by an explicit application action.


}\\
{\Large \bf clock}&
\multicolumn{1}{p{95mm}}{
The \abbr implementation will provide a concept that supports behaviors like 
the behavior of the clock described in Part II. A clock in this document can 
be thought of as having many of the attributes of a real clock. However, most 
clocks used in ESMF components have a key difference to a real clock. Clocks 
in an ESMF component are generally stepped forward by the component, as an 
explicitly coded step within the overall component. The discussion of an 
external clock requirement is the only exception to this behavior.

}\\

{\Large \bf priority}&
\multicolumn{1}{p{95mm}}{
Requirements are given a priority in order to help the ESMF development team 
and software engineering manager schedule development work. The priority 
categories used in the requirements documents are

\vspace{1mm}

{\bf Essential Priority:} This refers to a requirement that must be 
implemented for the software to be of any practical use.

\vspace{1mm}

{\bf Very Useful Priority:} This refers to a requirement that is needed by 
many components. If a very useful requirement is not implemented, then potentially 
several groups will need to develop significant software of their own to meet 
the requirement.

\vspace{1mm}

{\bf Useful Priority:} This refers to a requirement that is needed by one or more
of the components in the ESMF test suite. If a useful priority requirement is not 
implemented, then a group will need to develop or adapt some software of their own to 
meet the requirement.

\vspace{1mm}

{\bf Optional Priority:} This refers to a requirement that is seen as valuable, but that
is either not currently employed by existing applications or that can be
implemented by application and library developers provided the appropriate
base \abbr features allow for it. If time permits, optional priority 
requirements will be implemented. Optional priority requirements are also factored into 
implementation choices for higher priority requirements. Including optional priority
requirements ensures that, as far as possible, implemented features will be compatible 
with later addition of features to support the optional requirements.
}\\

\vspace{2mm}
{}&{}\\
\vspace{2mm}

{\Large \bf \abbr} &
\multicolumn{1}{p{95mm}}{Standard abbreviation for the ESMF Time Manager.
}\\

\vspace{2mm}

{\Large \bf time instant}&
\multicolumn{1}{p{95mm}}{Generic name for an absolute time and
date specification. A time instant is made up of a time and date and an 
associated calendar and time-zone. ``Jan 3rd 1999, 03.30:24.56s, UTC'' is one 
example of a time instant. Another example of a time instant is 36.3719 seconds 
in the default calendar and time zone.
}\\

\vspace{2mm}

{\Large \bf time interval}&
\multicolumn{1}{p{95mm}}{Generic name for a time and date period. Examples of 
time intervals are 36.3719 seconds, 17 hours, 8 years and 3 days 4 hours.
The precise meaning of units and hours and years is dependent on the calendar
associated with the time interval.
}
\end{supertabular}

\newpage
\part*{Part II - \abbr Requirements}
\addcontentsline{toc}{section}{Part II - \abbr Requirements}

\req{Multiple clock and alarm support is required.}
\sreq{Components should be able to create and manipulate multiple clocks and alarms.}
\begin{reqlist}
{\bf Background:} In many numerical approaches several different time-steps are 
used for different elements of the system. Multiple clocks are important to keep
track of these different time-steps. Ensemble simulations may also require
members to proceed with different temporal trajectories, all within a single 
component.\\
{\bf Originators:} All participants.\\
{\bf Priority:} Essential.
\end{reqlist}
\sreq{Components should be able to delete their clocks and alarms.}
\begin{reqlist}
{\bf Background:}
Sometimes temporary clocks and alarms will be needed. A mechanism to both create and
destroy alarms and clocks on the fly is required.
\\
{\bf Originators:} 
All participants.
\\
{\bf Priority:} Very Useful.
\end{reqlist}
\sreq{Component should be able to get a list of their clocks and alarms.}
\begin{reqlist}
{\bf Background:}
A useful bookkeeping feature would be the ability to find out what different
clocks a component owns at any time.
\\
{\bf Originators:} 
All participants.
\\
{\bf Priority:} Useful.
\end{reqlist}

\req{Cross-component clock and alarm queries and manipulations are required.}
\begin{reqlist}
\end{reqlist}

\sreq{Components should be able to query the clock(s) or alarms of another
        component and components should be able to manipulate certain clock(s) 
        and alarms of another component.}
\begin{reqlist}
{\bf Background:}
Synchronized shutdown notifications will be sent to components through clock
and alarm settings. These notifications may be generated by a high-level control program
or a coupler component. However, components should be able to determine 
which clocks and alarms can be externally manipulated so that they can assume that
certain clocks and alarms are private.

{\bf Originators:} 
All participants.
\\
{\bf Priority:} Essential.
\end{reqlist}

\sreq{Components should be able to "label" their clocks and alarms.}
\begin{reqlist}
{\bf Background:}
When coordinating notions of time among components with several
clocks or alarms, it is important to be able to identify the role of 
each clock or alarm.
For instance, a component might want to declare a master clock that 
defines the overall time within a component, or components
might need to declare a standard alarm that can be used
by a higher-level driver layer or a coupler component to trigger 
the generation of restart information or to trigger a clean shutdown.
\\
{\bf Originators:} 
All participants.
\\
{\bf Priority:} Essential.
\end{reqlist}


\req{Multiple, widely used, schemes for specifying time instants 
and time intervals are required.}
\begin{reqlist}
{\bf Background:}
Different applications have differing needs for how time is represented.
Some idealized simulations may not require a notion of a true calendar based