1 |
c $Header: /u/gcmpack/development/heimbach/ecco_env/pkg/cal/README,v 1.3 2000/10/23 16:32:12 heimbach Exp $ |
2 |
c |
3 |
c |
4 |
c ================================= |
5 |
c Calendar Package for the MITgcmUV |
6 |
c ================================= |
7 |
c |
8 |
c |
9 |
c This calendar tool was originally intended to enable the use of |
10 |
c absolute dates (Gregorian Calendar dates) in the ocean general |
11 |
c circulation model MITgcmuv. There is, however, a fair amount of |
12 |
c routines that can be used independently of the MITgcmuv. After |
13 |
c some minor modifications the whole package can be used either |
14 |
c as a stand-alone calendar or in connection with any dynamical |
15 |
c model that needs calendar dates. Some straightforward extensions |
16 |
c are still pending e.g. the availability of the Julian Calendar, |
17 |
c to be able to resolve fractions of a second, and to have a time- |
18 |
c step that is longer than one day. |
19 |
c |
20 |
c Current version: 0.2.0 |
21 |
c |
22 |
c I'm grateful to any suggestions made by users of this tool in |
23 |
c order to improve it. Please report bugs and suggestions to: |
24 |
c |
25 |
c Christian Eckert: eckert@mit.edu |
26 |
c Patrick Heimbach: heimbach@mit.edu |
27 |
c |
28 |
c |
29 |
c Here, you find a documentation of the general architecture of this |
30 |
c calendar tool and a short description of individual routines. For |
31 |
c specific questions on the individual routines please have a look |
32 |
c at their headers and of course at their code. |
33 |
c |
34 |
c |
35 |
c ========= |
36 |
c Contents. |
37 |
c ========= |
38 |
c |
39 |
c (0) Basic assumptions for this version of the calendar tool. |
40 |
c (1) Format of calendar dates. |
41 |
c (2) Calendar dates and time intervals. |
42 |
c (3) Using the calendar tool together with the MITgcmUV. |
43 |
c (4) Using the calendar tool as a stand-alone program. |
44 |
c (5) The individual calendars. |
45 |
c (6) The individual calendar routines. |
46 |
c (7) Short Description of the routines. |
47 |
c (8) How to get started. |
48 |
c (9) History. |
49 |
c |
50 |
c |
51 |
c (0) Basic assumptions for this version of the calendar tool. |
52 |
c ============================================================ |
53 |
c |
54 |
c It is assumed that the SMALLEST TIME INTERVAL to be resolved is |
55 |
c ONE SECOND. |
56 |
c |
57 |
c Further assumptions are that there is an INTEGER NUMBER OF |
58 |
c MODEL STEPS EACH DAY, and that AT LEAST ONE STEP EACH DAY is |
59 |
c made. |
60 |
c |
61 |
c Not each individual routine depends on these assumptions; there |
62 |
c are only a few places where they enter. |
63 |
c |
64 |
c I plan to get rid of these assumptions as soon as possible in |
65 |
c an adequate way. |
66 |
c |
67 |
c |
68 |
c (1) Format of calendar dates. |
69 |
c ============================= |
70 |
c |
71 |
c In this calendar tool a complete date specification is defined |
72 |
c as the following integer array: |
73 |
c |
74 |
c integer date(4) |
75 |
c |
76 |
c ( yyyymmdd, hhmmss, leap_year, dayofweek ) |
77 |
c |
78 |
c date(1) = yyyymmdd <-- Year-Month-Day |
79 |
c date(2) = hhmmss <-- Hours-Minutes-Seconds |
80 |
c date(3) = leap_year <-- Leap Year/No Leap Year |
81 |
c date(4) = dayofweek <-- Day of the Week |
82 |
c |
83 |
c leap_year is either equal to 1 (normal year) |
84 |
c or equal to 2 (leap year) |
85 |
c |
86 |
c dayofweek has a range of 1 to 7. |
87 |
c |
88 |
c In case the Gregorian Calendar is used, the first |
89 |
c day of the week is Friday, since day of the Gregorian |
90 |
c Calendar was Friday, 15 Oct. 1582. As a date array |
91 |
c this date would be specified as |
92 |
c |
93 |
c refdate(1) = 15821015 |
94 |
c refdate(2) = 0 |
95 |
c refdate(3) = 1 |
96 |
c refdate(4) = 1 |
97 |
c |
98 |
c |
99 |
c (2) Calendar dates and time intervals. |
100 |
c ====================================== |
101 |
c |
102 |
c Subtracting calendar dates yields time intervals. |
103 |
c Time intervals have the following format: |
104 |
c |
105 |
c integer datediff(4) |
106 |
c |
107 |
c datediff(1) = # Days |
108 |
c datediff(2) = hhmmss |
109 |
c datediff(3) = 0 |
110 |
c datediff(4) = -1 |
111 |
c |
112 |
c Such time intervals can be added to or can be subtracted from |
113 |
c calendar dates. Time intervals can be added to and be |
114 |
c subtracted from each other. |
115 |
c |
116 |
c |
117 |
c (3) Using the calendar tool together with the MITgcmUV. |
118 |
c ======================================================= |
119 |
c |
120 |
c Each routine has as an argument the thread number that it is |
121 |
c belonging to, even if this number is not used in the routine |
122 |
c itself. |
123 |
c |
124 |
c In order to include the calendar tool into the MITgcmUV |
125 |
c setup the MITgcmUV subroutine "initialise.F" or the routine |
126 |
c "initilise_fixed.F", depending on the MITgcmUV release, has |
127 |
c to be modified in the following way: |
128 |
c |
129 |
c #ifdef ALLOW_CALENDAR |
130 |
c C-- Initialise the calendar package. |
131 |
c #ifdef USE_CAL_NENDITER |
132 |
c CALL cal_Init( |
133 |
c I startTime, |
134 |
c I endTime, |
135 |
c I deltaTclock, |
136 |
c I nIter0, |
137 |
c I nEndIter, |
138 |
c I nTimeSteps, |
139 |
c I myThid |
140 |
c & ) |
141 |
c #else |
142 |
c CALL cal_Init( |
143 |
c I startTime, |
144 |
c I endTime, |
145 |
c I deltaTclock, |
146 |
c I nIter0, |
147 |
c I nTimeSteps, |
148 |
c I myThid |
149 |
c & ) |
150 |
c #endif |
151 |
c _BARRIER |
152 |
c #endif |
153 |
c |
154 |
c It is useful to have the CPP flag ALLOW_CALENDAR in |
155 |
c order to switch from the usual MITgcmUV setup to the |
156 |
c one that includes the calendar tool. The CPP flag |
157 |
c USE_CAL_NENDITER has been introduced in order to enable |
158 |
c the use of the calendar for MITgcmUV releases earlier |
159 |
c than checkpoint 25 which do not have the global variable |
160 |
c *nEndIter*. |
161 |
c |
162 |
c |
163 |
c (4) Using the calendar tool as a stand-alone program. |
164 |
c ===================================================== |
165 |
c |
166 |
c |
167 |
c This will sometime be available. |
168 |
c |
169 |
c |
170 |
c (5) The individual calendars |
171 |
c ============================ |
172 |
c |
173 |
c (a) Simple Model Calendar |
174 |
c |
175 |
c This calendar can be used by defining |
176 |
c |
177 |
c TheCalendar='model' |
178 |
c |
179 |
c in the calendar's data file "data.cal". |
180 |
c |
181 |
c In this case a year is assumed to have 360 days. The |
182 |
c model year is divided into 12 months with 30 days each. |
183 |
c |
184 |
c (b) Gregorian Calendar |
185 |
c |
186 |
c This calendar can be used by defining |
187 |
c |
188 |
c TheCalendar='gregorian' |
189 |
c |
190 |
c in the calendar's data file "data.cal". |
191 |
c |
192 |
c (c) Julian Calendar |
193 |
c |
194 |
c Not implemented yet. |
195 |
c |
196 |
c (d) Julian Days |
197 |
c |
198 |
c Not implemented yet. |
199 |
c |
200 |
c (e) Just the Model's Timestep |
201 |
c |
202 |
c Not implemented yet. |
203 |
c |
204 |
c |
205 |
c (6) The individual calendar routines |
206 |
c ==================================== |
207 |
c |
208 |
c The numbering of the routines is used in the error codes |
209 |
c that are used to print error messages. See the routine |
210 |
c "cal_PrintError" for details. |
211 |
c |
212 |
c ( 0) cal_Init (sub) version 0.1.0 |
213 |
c ( 1) cal_Set (sub) version 0.1.0 |
214 |
c ( 2) cal_GetDate (sub) version 0.1.0 |
215 |
c ( 3) cal_FullDate (sub) version 0.1.0 |
216 |
c ( 4) cal_IsLeap (integer fun) version 0.1.0 |
217 |
c ( 5) cal_TimePassed (sub) version 0.1.0 |
218 |
c ( 6) cal_AddTime (sub) version 0.1.0 |
219 |
c ( 7) cal_TimeInterval (sub) version 0.1.0 |
220 |
c ( 8) cal_SubDates (sub) version 0.1.0 |
221 |
c ( 9) cal_ConvDate (sub) version 0.1.0 |
222 |
c (10) cal_ToSeconds (sub) version 0.1.0 |
223 |
c (11) cal_StepsPerDay (sub) version 0.1.0 |
224 |
c (12) cal_DaysPerMonth (sub) version 0.1.0 |
225 |
c (13) cal_MonthsPerYear (sub) version 0.1.0 |
226 |
c (14) cal_IntYears (integer fun) version 0.1.0 |
227 |
c (15) cal_IntMonths (integer fun) version 0.1.0 |
228 |
c (16) cal_IntDays (integer fun) version 0.1.0 |
229 |
c (17) cal_nStepDay (integer fun) version 0.1.0 |
230 |
c (18) cal_CheckDate (sub) version 0.1.0 |
231 |
c (19) cal_PrintError (sub) version 0.1.0 |
232 |
c (20) cal_PrintDate (sub) version 0.1.0 |
233 |
c (21) cal_Summary (sub) version 0.1.0 |
234 |
c (22) cal_CopyDate (sub) version 0.1.1 |
235 |
c (23) cal_WeekDay (sub) version 0.1.3 |
236 |
c (24) cal_CompDates (logical fun) version 0.1.4 |
237 |
c (25) cal_NumInts (integer fun) version 0.1.4 |
238 |
c (26) cal_StepsForDay (sub) version 0.1.6 |
239 |
c (27) cal_DaysForMonth (sub) version 0.1.6 |
240 |
c (28) cal_MonthsForYear (sub) version 0.1.6 |
241 |
c (29) cal_GetMonthsRec (sub) version 0.1.6 |
242 |
c (30 cal_IntSteps (integer fun) version 0.1.7 |
243 |
c (31) cal_TimeStamp (sub) version 0.1.7 |
244 |
c |
245 |
c |
246 |
c (7) Short Description of the routines. |
247 |
c ====================================== |
248 |
c |
249 |
c o cal_Init - Initialise the calendar. This is the interface |
250 |
c to the MITgcmUV. |
251 |
c |
252 |
c o cal_Set - Sets the calendar according to the user |
253 |
c specifications. |
254 |
c |
255 |
c o cal_GetDate - Given the model's current timestep or the |
256 |
c model's current time return the corresponding |
257 |
c calendar date. |
258 |
c |
259 |
c o cal_FullDate - Complete a date specification (leap year and |
260 |
c day of the week). |
261 |
c |
262 |
c o cal_IsLeap - Determine whether a given year is a leap year. |
263 |
c |
264 |
c o cal_TimePassed - Determine the time passed between two dates. |
265 |
c |
266 |
c o cal_AddTime - Add a time interval either to a time interval |
267 |
c or to a date. |
268 |
c |
269 |
c o cal_TimeInterval - Given a time interval return the corresponding |
270 |
c date array. |
271 |
c |
272 |
c o cal_SubDates - Determine the time interval between two dates |
273 |
c or between two time intervals. |
274 |
c |
275 |
c o cal_ConvDate - Decompose a date array or a time interval |
276 |
c array into its components. |
277 |
c |
278 |
c o cal_CopyDate - Copy a date array or a time interval array to |
279 |
c another array. |
280 |
c |
281 |
c o cal_CompDates - Compare two calendar dates or time intervals. |
282 |
c |
283 |
c o cal_ToSeconds - Given a time interval array return the number |
284 |
c of seconds. |
285 |
c |
286 |
c o cal_WeekDay - Return the weekday as a string given the |
287 |
c calendar date. |
288 |
c |
289 |
c o cal_NumInts - Return the number of time intervals between two |
290 |
c given dates. |
291 |
c |
292 |
c o cal_StepsPerDay - Given an iteration number or the current |
293 |
c integration time return the number of time |
294 |
c steps to integrate in the current calendar day. |
295 |
c |
296 |
c o cal_DaysPerMonth - Given an iteration number or the current |
297 |
c integration time return the number of days |
298 |
c to integrate in this calendar month. |
299 |
c |
300 |
c o cal_MonthsPerYear - Given an iteration number or the current |
301 |
c integration time return the number of months |
302 |
c to integrate in the current calendar year. |
303 |
c |
304 |
c o cal_StepsForDay - Given the integration day return the number |
305 |
c of steps to be integrated, the first step, |
306 |
c and the last step in the day specified. The |
307 |
c first and the last step refer to the total |
308 |
c number of steps (1, ... , cal_IntSteps). |
309 |
c |
310 |
c o cal_DaysForMonth - Given the integration month return the number |
311 |
c of days to be integrated, the first day, |
312 |
c and the last day in the month specified. The |
313 |
c first and the last day refer to the total |
314 |
c number of steps (1, ... , cal_IntDays). |
315 |
c |
316 |
c o cal_MonthsForYear - Given the integration year return the number |
317 |
c of months to be integrated, the first month, |
318 |
c and the last month in the year specified. The |
319 |
c first and the last step refer to the total |
320 |
c number of steps (1, ... , cal_IntMonths). |
321 |
c |
322 |
c o cal_Intsteps - Return the number of calendar years that are |
323 |
c affected by the current integration. |
324 |
c |
325 |
c o cal_IntDays - Return the number of calendar days that are |
326 |
c affected by the current integration. |
327 |
c |
328 |
c o cal_IntMonths - Return the number of calendar months that are |
329 |
c affected by the current integration. |
330 |
c |
331 |
c o cal_IntYears - Return the number of calendar years that are |
332 |
c affected by the current integration. |
333 |
c |
334 |
c o cal_nStepDay - Return the number of time steps that can be |
335 |
c performed during one calendar day. |
336 |
c |
337 |
c o cal_CheckDate - Do some simple checks on a date array or on a |
338 |
c time interval array. |
339 |
c |
340 |
c o cal_PrintError - Print error messages according to the flags |
341 |
c raised by the calendar routines. |
342 |
c |
343 |
c o cal_PrintDate - Print a date array in some format suitable for |
344 |
c the MITgcmuv's protocol output. |
345 |
c |
346 |
c o cal_TimeStamp - Given the time and the iteration number return |
347 |
c the date and print all the above numbers. |
348 |
c |
349 |
c o cal_Summary - List all the setttings of the calendar tool. |
350 |
c |
351 |
c |
352 |
c |
353 |
c (8) How to get started. |
354 |
c ======================= |
355 |
c |
356 |
c Copy all the routines and headers to the distribution |
357 |
c after you have installed the latter. |
358 |
c |
359 |
c cal_<name>.F --> cNN/model/src/cal_<name>.F |
360 |
c cal.h --> cNN/model/inc/cal.h |
361 |
c CAL_CPPOPTIONS.h --> cNN/model/inc/CAL_CPPOPTIONS.h |
362 |
c data.cal --> cNN/exe/data.cal |
363 |
c |
364 |
c Add the line |
365 |
c |
366 |
c #include "CAL_CPPOPTIONS.h" |
367 |
c |
368 |
c to the routine that calls "cal_Init". |
369 |
c |
370 |
c Set the parameters in "data.cal" approriately. The |
371 |
c Set *nTimeSteps* in the MITgcmUV "data" file to the |
372 |
c number od time steps you would like to integrate. |
373 |
c |
374 |
c CAUTION: Be aware of the current limitations of the |
375 |
c calendar (see above). |
376 |
c |
377 |
c To specify the integration interval in "data.cal" |
378 |
c |
379 |
c startdate1=YYYYMMDD, |
380 |
c startdate2=HHMMSS, |
381 |
c |
382 |
c |
383 |
c (9) History |
384 |
c =========== |
385 |
c |
386 |
c started: Christian Eckert eckert@mit.edu 30-Jun-1999 |
387 |
c |
388 |
c changed: Christian Eckert eckert@mit.edu 19-Jan-2000 |
389 |
c |
390 |
c Christian Eckert eckert@mit.edu 03-Feb-2000 |
391 |
c |
392 |
c - Introduced new routine and function names, cal_<NAME>, |
393 |
c for verion 0.1.3. |
394 |
c |
395 |
c Christian Eckert eckert@mit.edu 24-Feb-2000 |
396 |
c |
397 |
c - Added routine cal_CompDates. |
398 |
c |
399 |
c Christian Eckert eckert@mit.edu 22-Mar-2000 |
400 |
c |
401 |
c - Added CPP flag to support different checkpoints of |
402 |
c the MITgcmUV, namely c24 and c25. |
403 |
c |
404 |
c Christian Eckert eckert@mit.edu 21-Apr-2000 |
405 |
c |
406 |
c - Added routines *cal_StepsForDay*, *cal_DaysForMonth*, |
407 |
c *cal_MonthsForYear*, and *cal_GetMonthsRec*. |
408 |
c |
409 |
c Christian Eckert eckert@mit.edu 01-May-2000 |
410 |
c |
411 |
c - Added routine cal_IntSteps. |
412 |
c |
413 |
c Christian Eckert eckert@mit.edu 04-May-2000 |
414 |
c |
415 |
c - Added routine cal_TimeStamp. This routine |
416 |
c used to be called ecco_TimeStamp. |
417 |
c |
418 |
c Patrick Heimbach heimbach@mit.edu 20-Jun-2000 |
419 |
c - Bug fixes in: |
420 |
c * cal_addtime.F (computation of datesecs) |
421 |
c * cal_getmonthsrec.F (computation of count1) |
422 |
c * cal_subdates.F (72 line length) |
423 |
c * cal_summary.F (replaced write_1d_r8 by |
424 |
c write_0d_r8) |
425 |
c |
426 |
c ================================================================== |