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, May2000} 
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 standalone 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 < YearMonthDay 
43 
c date(2) = hhmmss < HoursMinutesSeconds 
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 
