Module_Time_Procedures¶

This file is part of statpack.

statpack is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

statpack is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You can find a copy of the GNU Lesser General Public License in the statpack/doc directory.

Authors: Pascal Terray (LOCEAN/IPSL, Paris, France)

MODULE EXPORTING TIME AND DATE UTILITIES.

LATEST REVISION : 19/02/2024

`function leapyr ( iyr )`¶

Purpose¶

Check for a leap year. LEAPYR is returned as “true” if IYR is a leap year, and “false” otherwise.

Arguments¶

IYR (INPUT) integer(i4b)

The year to test.

Further Details¶

This function uses the Gregorian calendar adopted the Oct. 15, 1582.

Leap years are years that are evenly divisible by 4, except years that are evenly divisible by 100 must be divisible by 400.

The result is a logical of kind lgl.

`function daynum ( iyr, imon, iday )`¶

Purpose¶

Compute a day number. One of the more useful applications for this routine is to compute the number of days between two dates.

Arguments¶

IYR, IMON , IDAY (INPUT) integer(i4b)

Year (iyr), month (imon), and day (iday).

Further Details¶

This function uses the Gregorian calendar adopted the Oct. 15, 1582.

In other words, Oct. 15, 1582 will return a day number of unity and hence this algorithm will not work properly for dates early than 10-15-1582.

The result is an integer of kind i4b.

`function day_of_week ( iyr, imon, iday )`¶

Purpose¶

This function returns the day of the week (e.g., Mon, Tue,…) as an index (Mon=1 to Sun=7) for a given year, month, and day.

Arguments¶

IYR, IMON , IDAY (INPUT) integer(i4b)

Year (IYR), month (IMON), and day (IDAY).

Further Details¶

This routine assumes a valid day, month and year are input.

The result is an integer of kind i4b.

The algorithm is adapted from:

Larson, K., 1995:

Computing the Day of the Week. Dr Dobb’s Journal, p. 125-126, April.

`subroutine daynum_to_ymd ( jdaynum, iyr, imon, iday )`¶

Purpose¶

Converts a Julian Day Number (JDAYNUM) to Gregorian year (IYR), month (IMON) and day (IDAY).

Arguments¶

JDAYNUM (INPUT) integer(i4b)

The Julian day number to convert. See further details.

IYR, IMON , IDAY (OUTPUT) integer(i4b)

The year (IYR), month (IMON), and day (IDAY) in the Gregorian calendar corresponding to the Julian day number JDAYNUM.

Further Details¶

This subroutine converts the integer JDAYNUM to three integers IYR, IMON and IDAY standing for year, month, day in the Gregorian calendar promulgated by Gregory XIII, starting with JDAYNUM=1 on Friday, 15 October 1582.

To keep Pope Gregory’s calendar synchronized with the seasons for the next 16000 years or so, a small correction has been introduced; millennial years divisible by 4000 are not considered leap-years.

Note the Gregorian calendar was adopted in Oct. 15, 1582, and hence this algorithm will not work properly for dates early than 10-15-1582, e.g. if JDAYNUM < 1.

Note that England and its possessions remained 10 or 11 days behind this Gregorian calendar until 14 September 1752, e.g. if JDAYNUM < 62062.

Note that no consensus has been reached yet about dates beyond Monday, 28 February, 4000 (e.g. if JDAYNUM > 882928), and dates after 18000 A.D. are extremely speculative at best.

This subroutine is adapted from a MATLAB M-file written by W. Kahan available on the WEB.

`function ymd_to_daynum ( iyr, imon, iday )`¶

Purpose¶

Converts Gregorian year (IYR), month (IMON) and day (IDAY) to Julian day Number. See further details.

Arguments¶

IYR, IMON , IDAY (INPUT) integer(i4b)

The year (IYR), month (IMON), and day (IDAY) in the Gregorian calendar to convert.

Further Details¶

This function converts the three integers IYR, IMON and IDAY standing for year, month, day in the Gregorian calendar promulgated by Gregory XIII on Friday, 15 October 1582, in the corresponding Julian day number starting with YMD_TO_DAYNUM=1 on Friday, 15 October 1582.

Note the Gregorian calendar was adopted in Oct. 15, 1582, and hence this algorithm will not work properly for dates early than 10-15-1582. Dates are checked for validity by using DAYNUM_TO_YMD subroutine.

The number of days between two dates is the difference between their Julian day.

The result is an integer of kind i4b.

This subroutine is adapted from a MATLAB M-file written by W. Kahan available on the WEB.

`function ymd_to_dayweek ( iyr, imon, iday )`¶

Purpose¶

Computes the day of the week from Gregorian year (IYR), month (IMON) and day (IDAY). See further details.

Arguments¶

IYR, IMON , IDAY (INPUT) integer(i4b)

The year (IYR), month (IMON), and day (IDAY) in the Gregorian calendar to convert.

Further Details¶

This function returns the day of the week (e.g., Mon, Tue,…) as an integer index (Mon=1 to Sun=7) for the given year, month, and day in the Gregorian calendar promulgated by Gregory XIII on Friday, 15 October 1582.

Note that the Gregorian calendar was adopted in Oct. 15, 1582, and hence this algorithm will not work properly for dates early than 10-15-1582. Dates are checked for validity by using DAYNUM_TO_YMD subroutine.

The result is an integer of kind i4b.

This subroutine is adapted from a MATLAB M-file written by W. Kahan available on the WEB.

`function daynum_to_dayweek ( jdaynum )`¶

Purpose¶

Computes the day of the week from Julian day number JDAYNUM. See further details.

Arguments¶

JDAYNUM (INPUT) integer(i4b)

The Julian day number to convert.

Further Details¶

This function returns the day of the week (e.g., Mon, Tue,…) as an integer index (Mon=1 to Sun=7) for the given Julian day number JDAYNUM starting with JDAYNUM=1 on Friday, 15 October 1582.

The result is an integer of kind i4b.

`function rtsw ()`¶

Purpose¶

RTSW is a Real-Time Stop Watch.

This routine can be used to compute the time lapse between functions calls according to the system (wall) clock.

Arguments¶

None.

Further Details¶

RTSW is a unique numeric identifier derived from the current system time and date.

This function works across month and year boundaries, but is not thread-safe and cannot be called in parallel by different threads.

Since this routine uses the system clock, the elapsed time computed with this routine may not (probably won’t be in a multi-tasking OS) an accurate reflection of the number of cpu cycles required to perform a calculation. Therefore care should be exercised when using this to profile a code.

The result is a real of kind extd.

The calling procedure for this function is as follow:

tim1 = rtsw()

[perform calculations]

tim2 = rtsw()

write(,) ‘Elapsed Time (s): ‘,tim2-tim1

`function elapsed_time ( t1, t0 )`¶

Purpose¶

Computes elapsed time between two invocations of the intrinsic function DATE_AND_TIME. ELAPSED_TIME( T1, T0 ) returns the time in seconds that has elapsed between the vectors T0 and T1. Each vector must have at least seven elements in the format returned by DATE_AND_TIME for the optional argument VALUES; namely

T = (/ year, month, day, x, hour, minute, second /)

This routine can be used to compute the elapsed time between DATE_AND_TIME calls according to the system (wall) clock.

Arguments¶

T1, T0 (INPUT) integer, dimension(:)

The two vectors which give the starting and ending dates and times as returned by DATE_AND_TIME.

Further Details¶

Since this routine uses the system clock, the elapsed time computed with this routine may not (probably won’t be in a multi-tasking OS) an accurate reflection of the number of cpu cycles required to perform a calculation. Therefore care should be exercised when using this to profile a code.

This function works across month and year boundaries but does not check the validity of its arguments, which are expected to be obtained as in the following example that shows how to time some operation by using ELAPSED_TIME.

The result is an integer of kind i4b.

The calling procedure for this subroutine is as follow:

call date_and_time( values=t0(:) )

[perform calculations]

call date_and_time( values=t1(:) )

write(,) ‘Elapsed Time (s): ‘, elapsed_time( t1(:), t0(:) )

This subroutine is adapted from a MATLAB M-file written by W. Kahan available on the WEB.

`function cpusecs ()`¶

Purpose¶

This function obtains, from the intrinsic routine SYSTEM_CLOCK, the current value of the system CPU usage clock. This value is then converted to seconds and returned as an extended precision real value.

Arguments¶

None.

Further Details¶

This functions assumes that the number of CPU cycles (clock counts) between two calls is less than COUNT_MAX, the maximum possible value of clock counts as returned by the intrinsic routine SYSTEM_CLOCK.

The result is a real of kind extd.

The calling procedure for this function is as follow:

tim1 = cpusecs()

[perform calculations]

tim2 = cpusecs()

write(,) ‘CPU Time (s): ‘,tim2-tim1

`subroutine time_to_hmsms ( time, hmsms )`¶

Purpose¶

Convert time to hours, minutes, seconds, milliseconds format.

Arguments¶

TIME (INPUT) real(extd)

The time in seconds.

HMSMS (OUTPUT) integer(i4b), dimension(4)

On exit, an integer array with:

HMSMS(1) = the hours as an integer number

HMSMS(2) = the minutes as an integer number from 0 to 59

HMSMS(3) = the seconds as an integer number from 0 to 59

HMSMS(4) = the milliseconds as an integer number from 0 to 999

`function time_to_string ( time )`¶

Purpose¶

Convert TIME to a string format for printing as

‘hours.minutes.seconds.milliseconds’

Arguments¶

TIME (INPUT) real(extd)

The time in seconds.

Further Details¶

The result is a string of (at least) 13 characters.

`subroutine get_date ( iyr, imon, iday, date )`¶

Purpose¶

Get a given date in a “nice” format.

Arguments¶

IYR, IMON , IDAY (INPUT) integer(i4b)

Year (IYR), month (IMON), and day (IDAY).

DATE (OUTPUT) character(len=*)

The date in the form dd-mmm-yyyy as in 18-Mar-1992.

Should be at least 11 chars long to hold the full string.

Further Details¶

If DATE is more than 11 characters in length, DATE is padded with blanks. If it is less than 11 characters in length, only the leftmost characters of the date will be returned.

If there is an error, GET_DATE returns a string filled with ‘*’.

`subroutine get_date_time ( date, time )`¶

Purpose¶

Get system date and time in “nice” formats. This routine just reformats the output from the standard DATE_AND_TIME intrinsic.

Arguments¶

DATE (OUTPUT,OPTIONAL) character(len=*)

The date in the form dd-mmm-yyyy as in 18-Mar-1992.

Should be at least 11 chars long to hold full string.

TIME (OUTPUT,OPTIONAL) character(len=*)

The time in the form hh:mm:ss.

Should be at least 8 chars long to hold full string.

Further Details¶

If DATE is more than 11 characters in length, DATE is padded with blanks. If it is less than 11 characters in length, only the leftmost characters of the date will be returned.

If TIME is more than 8 characters in length, TIME is padded with blanks. If it is less than 8 characters in length, only the leftmost characters of the time will be returned.

`subroutine system_date_time ( chdate )`¶

Purpose¶

Retrieve the current system time and date and transfer them to CHDATE in a “pretty” format, i.e.,

“DATE: DD-MMM-YYYY TIME: HH:MM:SS”

Arguments¶

CHDATE (OUTPUT) character(len=*)

The string to hold the time and the date.

Should be at least 33 chars long to hold full string.

Further Details¶

If CHDATE is more than 33 characters in length, CHDATE is padded with blanks. If it is less than 33 in length, only the leftmost characters of the date will be returned.

`subroutine my_date_time ( chdate )`¶

Purpose¶

This routine returns in CHDATE a 41-character date of the form given in model (below). It uses the time and date as obtained from the intrinsic routine DATE_AND_TIME and converts them to the form of the model given below:

‘00:00 a.m., Wednesday, September 00, 1999’

Arguments¶

CHDATE (OUTPUT) character(len=*)

The string to hold the time and the date. Should be at least 41 chars long to hold full string.

Further Details¶

Note that excess blanks in the date are eliminated. If CHDATE is more than 41 characters in length, CHDATE is padded with blanks. If it is less than 41 in length, only the leftmost characters of the date will be returned.

Module_Time_Procedures¶

function leapyr ( iyr )¶

Purpose¶

Arguments¶

Further Details¶

function daynum ( iyr, imon, iday )¶

Purpose¶

Arguments¶

Further Details¶

function day_of_week ( iyr, imon, iday )¶

Purpose¶

Arguments¶

Further Details¶

subroutine daynum_to_ymd ( jdaynum, iyr, imon, iday )¶

Purpose¶

Arguments¶

Further Details¶

function ymd_to_daynum ( iyr, imon, iday )¶

Purpose¶

Arguments¶

Further Details¶

function ymd_to_dayweek ( iyr, imon, iday )¶

Purpose¶

Arguments¶

Further Details¶

function daynum_to_dayweek ( jdaynum )¶

Purpose¶

Arguments¶

Further Details¶

function rtsw ()¶

Purpose¶

Arguments¶

Further Details¶

function elapsed_time ( t1, t0 )¶

Purpose¶

Arguments¶

Further Details¶

function cpusecs ()¶

Purpose¶

Arguments¶

Further Details¶

subroutine time_to_hmsms ( time, hmsms )¶

Purpose¶

Arguments¶

function time_to_string ( time )¶

Purpose¶

Arguments¶

Further Details¶

subroutine get_date ( iyr, imon, iday, date )¶

Purpose¶

Arguments¶

Further Details¶

subroutine get_date_time ( date, time )¶

Purpose¶

Arguments¶

Further Details¶

subroutine system_date_time ( chdate )¶

Purpose¶

Arguments¶

Further Details¶

subroutine my_date_time ( chdate )¶

Purpose¶

Arguments¶

Further Details¶

`function leapyr ( iyr )`¶

`function daynum ( iyr, imon, iday )`¶

`function day_of_week ( iyr, imon, iday )`¶

`subroutine daynum_to_ymd ( jdaynum, iyr, imon, iday )`¶

`function ymd_to_daynum ( iyr, imon, iday )`¶

`function ymd_to_dayweek ( iyr, imon, iday )`¶

`function daynum_to_dayweek ( jdaynum )`¶

`function rtsw ()`¶

`function elapsed_time ( t1, t0 )`¶

`function cpusecs ()`¶

`subroutine time_to_hmsms ( time, hmsms )`¶

`function time_to_string ( time )`¶

`subroutine get_date ( iyr, imon, iday, date )`¶

`subroutine get_date_time ( date, time )`¶

`subroutine system_date_time ( chdate )`¶

`subroutine my_date_time ( chdate )`¶