| 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 |
|
Parent Directory
| 
Revision Log
| 
Revision Graph