1 |
heimbach |
1.1 |
\section{The calendar package \texttt{cal} |
2 |
|
|
\label{sectioncal}} |
3 |
edhill |
1.2 |
\begin{rawhtml} |
4 |
|
|
<!-- CMIREDIR:sectioncal: --> |
5 |
|
|
\end{rawhtml} |
6 |
heimbach |
1.1 |
|
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 |
|
|
|