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