manual/s_ecco/cal.tex

\section{The calendar package \texttt{cal}
\label{sectioncal}}

\textit{Christian Eckert, MIT/EAPS, May-2000}

This calendar tool was originally intended to enable the use of
absolute dates (Gregorian Calendar dates) in the ocean general
circulation model MITgcmuv. There is, however, a fair amount of
routines that can be used independently of the MITgcmuv. After
some minor modifications the whole package can be used either
as a stand-alone calendar or in connection with any dynamical
model that needs calendar dates. Some straightforward extensions
are still pending e.g. the availability of the Julian Calendar,
to be able to resolve fractions of a second, and to have a time-
step that is longer than one day.

\subsection{Basic assumptions for the calendar tool}

    It is assumed that the SMALLEST TIME INTERVAL to be resolved is
    ONE SECOND.

    Further assumptions are that there is an INTEGER NUMBER OF
    MODEL STEPS EACH DAY, and that AT LEAST ONE STEP EACH DAY is
    made.

    Not each individual routine depends on these assumptions; there
    are only a few places where they enter.

\subsection{Format of calendar dates}

    In this calendar tool a complete date specification is defined
    as the following integer array:

\begin{verbatim}
c           integer date(4)
c
c           ( yyyymmdd, hhmmss, leap_year, dayofweek )
c
c             date(1) = yyyymmdd    <-- Year-Month-Day
c             date(2) =   hhmmss    <-- Hours-Minutes-Seconds
c             date(3) = leap_year   <-- Leap Year/No Leap Year
c             date(4) = dayofweek   <-- Day of the Week
c
c             leap_year is either equal to 1 (normal year)
c                              or equal to 2 (leap year)
c
c             dayofweek has a range of 1 to 7.
\end{verbatim}

          In case the Gregorian Calendar is used, the first
          day of the week is Friday, since day of the Gregorian
          Calendar was Friday, 15 Oct. 1582. As a date array
          this date would be specified as

\begin{verbatim}
c               refdate(1) = 15821015
c               refdate(2) =        0
c               refdate(3) =        1
c               refdate(4) =        1
\end{verbatim}

\subsection{Calendar dates and time intervals}

    Subtracting calendar dates yields time intervals.
    Time intervals have the following format:

\begin{verbatim}
c         integer datediff(4)
c
c           datediff(1) = # Days
c           datediff(2) = hhmmss
c           datediff(3) =      0
c           datediff(4) =     -1
\end{verbatim}

    Such time intervals can be added to or can be subtracted from
    calendar dates. Time intervals can be added to and be
    subtracted from each other.

\subsection{Using the calendar together with MITgcm}

    Each routine has as an argument the thread number that it is
    belonging to, even if this number is not used in the routine
    itself.

    In order to include the calendar tool into the MITgcm
    setup the MITgcm subroutine "initialise.F" or the routine
    "initilise\_fixed.F", depending on the MITgcm release, has
    to be modified in the following way:

{\footnotesize
\begin{verbatim}
c         #ifdef ALLOW_CALENDAR
c         C--   Initialise the calendar package.
c         #ifdef USE_CAL_NENDITER
c               CALL cal_Init(
c              I               startTime,
c              I               endTime,
c              I               deltaTclock,
c              I               nIter0,
c              I               nEndIter,
c              I               nTimeSteps,
c              I               myThid
c              &             )
c         #else
c               CALL cal_Init(
c              I               startTime,
c              I               endTime,
c              I               deltaTclock,
c              I               nIter0,
c              I               nTimeSteps,
c              I               myThid
c              &             )
c         #endif
c               _BARRIER
c         #endif
\end{verbatim}
}

    It is useful to have the CPP flag ALLOW\_CALENDAR in
    order to switch from the usual MITgcm setup to the
    one that includes the calendar tool. The CPP flag
    USE\_CAL\_NENDITER has been introduced in order to enable
    the use of the calendar for MITgcm releases earlier
    than checkpoint 25 which do not have the global variable
    *nEndIter*.

\subsection{The individual calendars}

\subsubsection{Simple model calendar}

          This calendar can be used by defining

\begin{verbatim}
c                  TheCalendar='model'
\end{verbatim}

          in the calendar's data file "data.cal".

          In this case a year is assumed to have 360 days. The
          model year is divided into 12 months with 30 days each.

\subsubsection{Gregorian Calendar}

          This calendar can be used by defining

\begin{verbatim}
c                  TheCalendar='gregorian'
\end{verbatim}

          in the calendar's data file "data.cal".

\subsection{Short routine description}

{\footnotesize
\begin{verbatim}
c      o  cal_Init          - Initialise the calendar. This is the interface
c                             to the MITgcm.
c
c      o  cal_Set           - Sets the calendar according to the user
c                             specifications.
c
c      o  cal_GetDate       - Given the model's current timestep or the
c                             model's current time return the corresponding
c                             calendar date.
c
c      o  cal_FullDate      - Complete a date specification (leap year and
c                             day of the week).
c
c      o  cal_IsLeap        - Determine whether a given year is a leap year.
c
c      o  cal_TimePassed    - Determine the time passed between two dates.
c
c      o  cal_AddTime       - Add a time interval either to a time interval
c                             or to a date.
c
c      o  cal_TimeInterval  - Given a time interval return the corresponding
c                             date array.
c
c      o  cal_SubDates      - Determine the time interval between two dates
c                             or between two time intervals.
c
c      o  cal_ConvDate      - Decompose a date array or a time interval
c                             array into its components.
c
c      o  cal_CopyDate      - Copy a date array or a time interval array to
c                             another array.
c
c      o  cal_CompDates     - Compare two calendar dates or time intervals. 
c
c      o  cal_ToSeconds     - Given a time interval array return the number
c                             of seconds.
c
c      o  cal_WeekDay       - Return the weekday as a string given the
c                             calendar date.
c
c      o  cal_NumInts       - Return the number of time intervals between two
c                             given dates.
c
c      o  cal_StepsPerDay   - Given an iteration number or the current
c                             integration time return the number of time
c                             steps to integrate in the current calendar day.
c
c      o  cal_DaysPerMonth  - Given an iteration number or the current
c                             integration time return the number of days
c                             to integrate in this calendar month.
c
c      o  cal_MonthsPerYear - Given an iteration number or the current
c                             integration time return the number of months
c                             to integrate in the current calendar year.
c
c      o  cal_StepsForDay   - Given the integration day return the number
c                             of steps to be integrated, the first step,
c                             and the last step in the day specified. The
c                             first and the last step refer to the total
c                             number of steps (1, ... , cal_IntSteps).
c
c      o  cal_DaysForMonth  - Given the integration month return the number
c                             of days to be integrated, the first day,
c                             and the last day in the month specified. The
c                             first and the last day refer to the total
c                             number of steps (1, ... , cal_IntDays).
c
c      o  cal_MonthsForYear - Given the integration year return the number
c                             of months to be integrated, the first month,
c                             and the last month in the year specified. The
c                             first and the last step refer to the total
c                             number of steps (1, ... , cal_IntMonths).
c
c      o  cal_Intsteps      - Return the number of calendar years that are
c                             affected by the current integration.
c
c      o  cal_IntDays       - Return the number of calendar days that are
c                             affected by the current integration.
c
c      o  cal_IntMonths     - Return the number of calendar months that are
c                             affected by the current integration.
c
c      o  cal_IntYears      - Return the number of calendar years that are
c                             affected by the current integration.
c
c      o  cal_nStepDay      - Return the number of time steps that can be
c                             performed during one calendar day.
c
c      o  cal_CheckDate     - Do some simple checks on a date array or on a
c                             time interval array.
c
c      o  cal_PrintError    - Print error messages according to the flags
c                             raised by the calendar routines.
c
c      o  cal_PrintDate     - Print a date array in some format suitable for
c                             the MITgcmuv's protocol output.
c
c      o  cal_TimeStamp     - Given the time and the iteration number return
c                             the date and print all the above numbers.
c
c      o  cal_Summary       - List all the setttings of the calendar tool.
\end{verbatim}
}

1	heimbach	1.1	\section{The calendar package \texttt{cal}
2			\label{sectioncal}}
3
4			\textit{Christian Eckert, MIT/EAPS, May-2000}
5
6			This calendar tool was originally intended to enable the use of
7			absolute dates (Gregorian Calendar dates) in the ocean general
8			circulation model MITgcmuv. There is, however, a fair amount of
9			routines that can be used independently of the MITgcmuv. After
10			some minor modifications the whole package can be used either
11			as a stand-alone calendar or in connection with any dynamical
12			model that needs calendar dates. Some straightforward extensions
13			are still pending e.g. the availability of the Julian Calendar,
14			to be able to resolve fractions of a second, and to have a time-
15			step that is longer than one day.
16
17			\subsection{Basic assumptions for the calendar tool}
18
19			It is assumed that the SMALLEST TIME INTERVAL to be resolved is
20			ONE SECOND.
21
22			Further assumptions are that there is an INTEGER NUMBER OF
23			MODEL STEPS EACH DAY, and that AT LEAST ONE STEP EACH DAY is
24			made.
25
26			Not each individual routine depends on these assumptions; there
27			are only a few places where they enter.
28
29			\subsection{Format of calendar dates}
30
31			In this calendar tool a complete date specification is defined
32			as the following integer array:
33
34			\begin{verbatim}
35			c integer date(4)
36			c
37			c ( yyyymmdd, hhmmss, leap_year, dayofweek )
38			c
39			c date(1) = yyyymmdd <-- Year-Month-Day
40			c date(2) = hhmmss <-- Hours-Minutes-Seconds
41			c date(3) = leap_year <-- Leap Year/No Leap Year
42			c date(4) = dayofweek <-- Day of the Week
43			c
44			c leap_year is either equal to 1 (normal year)
45			c or equal to 2 (leap year)
46			c
47			c dayofweek has a range of 1 to 7.
48			\end{verbatim}
49
50			In case the Gregorian Calendar is used, the first
51			day of the week is Friday, since day of the Gregorian
52			Calendar was Friday, 15 Oct. 1582. As a date array
53			this date would be specified as
54
55			\begin{verbatim}
56			c refdate(1) = 15821015
57			c refdate(2) = 0
58			c refdate(3) = 1
59			c refdate(4) = 1
60			\end{verbatim}
61
62			\subsection{Calendar dates and time intervals}
63
64			Subtracting calendar dates yields time intervals.
65			Time intervals have the following format:
66
67			\begin{verbatim}
68			c integer datediff(4)
69			c
70			c datediff(1) = # Days
71			c datediff(2) = hhmmss
72			c datediff(3) = 0
73			c datediff(4) = -1
74			\end{verbatim}
75
76			Such time intervals can be added to or can be subtracted from
77			calendar dates. Time intervals can be added to and be
78			subtracted from each other.
79
80			\subsection{Using the calendar together with MITgcm}
81
82			Each routine has as an argument the thread number that it is
83			belonging to, even if this number is not used in the routine
84			itself.
85
86			In order to include the calendar tool into the MITgcm
87			setup the MITgcm subroutine "initialise.F" or the routine
88			"initilise\_fixed.F", depending on the MITgcm release, has
89			to be modified in the following way:
90
91			{\footnotesize
92			\begin{verbatim}
93			c #ifdef ALLOW_CALENDAR
94			c C-- Initialise the calendar package.
95			c #ifdef USE_CAL_NENDITER
96			c CALL cal_Init(
97			c I startTime,
98			c I endTime,
99			c I deltaTclock,
100			c I nIter0,
101			c I nEndIter,
102			c I nTimeSteps,
103			c I myThid
104			c & )
105			c #else
106			c CALL cal_Init(
107			c I startTime,
108			c I endTime,
109			c I deltaTclock,
110			c I nIter0,
111			c I nTimeSteps,
112			c I myThid
113			c & )
114			c #endif
115			c _BARRIER
116			c #endif
117			\end{verbatim}
118			}
119
120			It is useful to have the CPP flag ALLOW\_CALENDAR in
121			order to switch from the usual MITgcm setup to the
122			one that includes the calendar tool. The CPP flag
123			USE\_CAL\_NENDITER has been introduced in order to enable
124			the use of the calendar for MITgcm releases earlier
125			than checkpoint 25 which do not have the global variable
126			nEndIter.
127
128			\subsection{The individual calendars}
129
130			\subsubsection{Simple model calendar}
131
132			This calendar can be used by defining
133
134			\begin{verbatim}
135			c TheCalendar='model'
136			\end{verbatim}
137
138			in the calendar's data file "data.cal".
139
140			In this case a year is assumed to have 360 days. The
141			model year is divided into 12 months with 30 days each.
142
143			\subsubsection{Gregorian Calendar}
144
145			This calendar can be used by defining
146
147			\begin{verbatim}
148			c TheCalendar='gregorian'
149			\end{verbatim}
150
151			in the calendar's data file "data.cal".
152
153			\subsection{Short routine description}
154
155			{\footnotesize
156			\begin{verbatim}
157			c o cal_Init - Initialise the calendar. This is the interface
158			c to the MITgcm.
159			c
160			c o cal_Set - Sets the calendar according to the user
161			c specifications.
162			c
163			c o cal_GetDate - Given the model's current timestep or the
164			c model's current time return the corresponding
165			c calendar date.
166			c
167			c o cal_FullDate - Complete a date specification (leap year and
168			c day of the week).
169			c
170			c o cal_IsLeap - Determine whether a given year is a leap year.
171			c
172			c o cal_TimePassed - Determine the time passed between two dates.
173			c
174			c o cal_AddTime - Add a time interval either to a time interval
175			c or to a date.
176			c
177			c o cal_TimeInterval - Given a time interval return the corresponding
178			c date array.
179			c
180			c o cal_SubDates - Determine the time interval between two dates
181			c or between two time intervals.
182			c
183			c o cal_ConvDate - Decompose a date array or a time interval
184			c array into its components.
185			c
186			c o cal_CopyDate - Copy a date array or a time interval array to
187			c another array.
188			c
189			c o cal_CompDates - Compare two calendar dates or time intervals.
190			c
191			c o cal_ToSeconds - Given a time interval array return the number
192			c of seconds.
193			c
194			c o cal_WeekDay - Return the weekday as a string given the
195			c calendar date.
196			c
197			c o cal_NumInts - Return the number of time intervals between two
198			c given dates.
199			c
200			c o cal_StepsPerDay - Given an iteration number or the current
201			c integration time return the number of time
202			c steps to integrate in the current calendar day.
203			c
204			c o cal_DaysPerMonth - Given an iteration number or the current
205			c integration time return the number of days
206			c to integrate in this calendar month.
207			c
208			c o cal_MonthsPerYear - Given an iteration number or the current
209			c integration time return the number of months
210			c to integrate in the current calendar year.
211			c
212			c o cal_StepsForDay - Given the integration day return the number
213			c of steps to be integrated, the first step,
214			c and the last step in the day specified. The
215			c first and the last step refer to the total
216			c number of steps (1, ... , cal_IntSteps).
217			c
218			c o cal_DaysForMonth - Given the integration month return the number
219			c of days to be integrated, the first day,
220			c and the last day in the month specified. The
221			c first and the last day refer to the total
222			c number of steps (1, ... , cal_IntDays).
223			c
224			c o cal_MonthsForYear - Given the integration year return the number
225			c of months to be integrated, the first month,
226			c and the last month in the year specified. The
227			c first and the last step refer to the total
228			c number of steps (1, ... , cal_IntMonths).
229			c
230			c o cal_Intsteps - Return the number of calendar years that are
231			c affected by the current integration.
232			c
233			c o cal_IntDays - Return the number of calendar days that are
234			c affected by the current integration.
235			c
236			c o cal_IntMonths - Return the number of calendar months that are
237			c affected by the current integration.
238			c
239			c o cal_IntYears - Return the number of calendar years that are
240			c affected by the current integration.
241			c
242			c o cal_nStepDay - Return the number of time steps that can be
243			c performed during one calendar day.
244			c
245			c o cal_CheckDate - Do some simple checks on a date array or on a
246			c time interval array.
247			c
248			c o cal_PrintError - Print error messages according to the flags
249			c raised by the calendar routines.
250			c
251			c o cal_PrintDate - Print a date array in some format suitable for
252			c the MITgcmuv's protocol output.
253			c
254			c o cal_TimeStamp - Given the time and the iteration number return
255			c the date and print all the above numbers.
256			c
257			c o cal_Summary - List all the setttings of the calendar tool.
258			\end{verbatim}
259			}
260