| 1 |
c $Header: /u/gcmpack/MITgcm/pkg/cal/README,v 1.1 2001/05/14 22:07:26 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_OPTIONS.h --> cNN/model/inc/CAL_OPTIONS.h |
| 362 |
c data.cal --> cNN/exe/data.cal |
| 363 |
c |
| 364 |
c Add the line |
| 365 |
c |
| 366 |
c #include "CAL_OPTIONS.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 ================================================================== |
Parent Directory
| 
Revision Log
| 
Revision Graph