dateclock.F

Go to the documentation of this file.

#include "cppdefs.h"
      MODULE dateclock_mod
!
!git $Id$
!================================================== Hernan G. Arango ===
!  Copyright (c) 2002-2025 The ROMS Group                              !
!    Licensed under a MIT/X style license                              !
!    See License_ROMS.md                                               !
!=======================================================================
!                                                                      !
!  This module contains several routines to manage ROMS date, clocks,  !
!  and calendars:                                                      !
!                                                                      !
!    caldate      Converts current model time (days) to calendar date. !
!                   All the returned variables require keyword syntax  !
!                   since they are optional.                           !
!                                                                      !
!    datenum      Converts requested date (year, month, day, ...) into !
!                   a serial number according to the supported calendar!
!                   options.                                           !
!                                                                      !
!    datestr      Converts date number to date string of the form:     !
!                   YYYY-MM-DD hh:mm:ss.ss                             !
!                                                                      !
!    datevec      Converts a given date number to a date vector. It is !
!                   inverse routine to "datenum".                      !
!                                                                      !
!    day_code     Given (month, day, year) it returns a numerical code !
!                   (0 to 6) for the day of the week.                  !
!                                                                      !
!    get_date     Retuns today date string of the form:                !
!                   DayOfWeak - Month day, year - hh:mm:ss ?M          !
!                                                                      !
!    ref_clock    Sets application time clock/reference and loads its  !
!                   to structure Rclock of TYPE T_CLOCK.               !
!                                                                      !
!    ROMS_clock   Given (year, month, day, hour, minutes, seconds),    !
!                   this routine returns ROMS clock time since         !
!                   initialization from the reference date. It is      !
!                   used when importing fields from coupled models.    !
!                                                                      !
!    time_iso8601 Encodes current model time to am ISO 8601 string     !
!                                                                      !
!    time_string  Encodes current model time to a string.              !
!                                                                      !
!    time_units   Decodes time attributes units.                       !
!                                                                      !
!    yearday      Given (year,month,day) this integer function returns !
!                   the day of the year.                               !
!                                                                      !
!=======================================================================
!
      USE mod_kinds
!
      implicit none
!
      PUBLIC :: caldate
      PUBLIC :: datenum
      PUBLIC :: datestr
      PUBLIC :: datevec
      PUBLIC :: day_code
      PUBLIC :: get_date
      PUBLIC :: ref_clock
      PUBLIC :: roms_clock
      PUBLIC :: time_iso8601
      PUBLIC :: time_string
      PUBLIC :: time_units
      PUBLIC :: yearday
!
      CONTAINS
!
!***********************************************************************
      SUBROUTINE caldate (CurrentTime,                                  &
     &                    yy_i, yd_i, mm_i, dd_i, h_i, m_i, s_i,        &
     &                    yd_dp, dd_dp, h_dp, m_dp, s_dp)
!***********************************************************************
!                                                                      !
!  This routine converts current model time (in days) to calendar      !
!  date. All the output arguments require keyword syntax since they    !
!  are all optional.  For Example, to get just the fractional (real)   !
!  day-of-year:                                                        !
!                                                                      !
!     CALL caldate (tdays(ng), yd_dp=yday)                             !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     CurrentTime   Model current time (real; days)                    !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     yy_i          Year including century (integer; OPTIONAL)         !
!     yd_i          Day of the year (integer; OPTIONAL)                !
!     mm_i          Month of the year, 1=Jan, ... (integer; OPTIONAL)  !
!     dd_i          Day of the month (integer; OPTIONAL)               !
!     h_i           Hour of the day (integer; OPTIONAL)                !
!     m_i           Minutes of the hour, 0 - 59 (integer; OPTIONAL)    !
!     s_i           Seconds of the minute (integer; OPTIONAL)          !
!                                                                      !
!     yd_dp         Day of the year (real, fraction; OPTIONAL)         !
!     dd_dp         Day of the month (real, fraction; OPTIONAL)        !
!     h_dp          Hour of the day (real, fraction; OPTION)           !
!     m_dp          Minutes of the hour (real, fraction; OPTION)       !
!     s_dp          Seconds of the minute (real, fraction; OPTIONAL)   !
!                                                                      !
!  Notice that a calendar obtained by extending backward in time from  !
!  its invention or implementation is called the Proleptic version of  !
!  the calendar.                                                       !
!                                                                      !
!***********************************************************************
!
      USE mod_param
      USE mod_scalars
!
      USE round_mod, ONLY : round
!
!  Imported variable declarations.
!
      real(dp), intent(in)  :: currenttime
!
      integer,  intent(out), optional :: yy_i
      integer,  intent(out), optional :: yd_i
      integer,  intent(out), optional :: mm_i
      integer,  intent(out), optional :: dd_i
      integer,  intent(out), optional :: h_i
      integer,  intent(out), optional :: m_i
      integer,  intent(out), optional :: s_i
!
      real(dp), intent(out), optional :: yd_dp
      real(dp), intent(out), optional :: dd_dp
      real(dp), intent(out), optional :: h_dp
      real(dp), intent(out), optional :: m_dp
      real(dp), intent(out), optional :: s_dp
!
!  Local variable declarations.
!
      logical :: isdayunits
 
      integer :: myday, myhour, myminutes, myseconds
      integer :: mymonth, myyday, myyear
 
      real(dp) :: datenumber, dayfraction, refdatenumber
      real(dp) :: hour, minutes, seconds
!
!-----------------------------------------------------------------------
!  Get calendar date from model current time (days).
!-----------------------------------------------------------------------
!
      refdatenumber=rclock%DateNumber(1)              ! fractional days
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since YYYY-MM-DD hh:mm:ss'.  It is called the Gregorian
!  Calendar or Gregorian Proleptic Calendar.
!
      calendar : IF (int(time_ref).gt.0) THEN
        datenumber=refdatenumber+currenttime          ! fractional days
        dayfraction=abs(datenumber-aint(datenumber))
!
        isdayunits=.true.
        CALL datevec (datenumber, isdayunits, myyear, mymonth, myday,   &
     &                myhour, myminutes, seconds, minutes, hour)
        myyday=yearday(myyear, mymonth, myday)
        myseconds=int(seconds)
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 0001-01-01 00:00:00'.  It is used in analytical
!  test cases. It has a year length of 365.2425 days (adapted on
!  15 October 1582 by Gregorian Calendar). It is called the Proleptic
!  Gregorian Calendar.
!
      ELSE IF (int(time_ref).eq.0) THEN
        datenumber=refdatenumber+currenttime          ! fractional days
        dayfraction=abs(datenumber-aint(datenumber))
!
        isdayunits=.true.
        CALL datevec (datenumber, isdayunits, myyear, mymonth, myday,   &
     &                myhour, myminutes, seconds, minutes, hour)
        myyday=yearday(myyear, mymonth, myday)
        myseconds=int(seconds)
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 0001-01-01 00:00:00'.  It can be used for
!  climatological solutions. It has a year length of 360 days and
!  every month has 30 days.  It is called the 360_day calendar by
!  numerical modelers.
!
      ELSE IF (int(time_ref).eq.-1) THEN
        datenumber=refdatenumber+currenttime          ! fractional days
        dayfraction=abs(datenumber-aint(datenumber))
!
        isdayunits=.true.
        CALL datevec (datenumber, isdayunits, myyear, mymonth, myday,   &
     &                myhour, myminutes, seconds, minutes, hour)
        myyday=int(datenumber-real(myyear*360,dp)+1)
        myseconds=int(seconds)
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 1968-05-23 00:00:00 GMT'. It is a Truncated Julian
!  day introduced by NASA and primarily used by Astronomers. It has
!  a year length of 365.25 days. It is less used nowadays since the length
!  of the year is 648 seconds less (365.2425) resulting in too many leap
!  years.  So it was corrected after 15 October 1582 and it is now called
!  the Gregorian Calendar.
!
      ELSE IF (int(time_ref).eq.-2) THEN
        IF (currenttime.ge.refdatenumber) THEN        ! fractional day
          datenumber=currenttime                      ! from origin
        ELSE
          datenumber=refdatenumber+currenttime        ! fractional days
        END IF                                        ! plus truncation
        dayfraction=abs(datenumber-aint(datenumber))
!
        isdayunits=.true.
        CALL datevec (datenumber, isdayunits, myyear, mymonth, myday,   &
     &                myhour, myminutes, seconds, minutes, hour)
        myyday=yearday(myyear, mymonth, myday)
        myseconds=int(seconds)
      END IF calendar
!
!-----------------------------------------------------------------------
!  Load requested time clock values.
!-----------------------------------------------------------------------
!
      IF (PRESENT(yd_i))  yd_i=myyday
      IF (PRESENT(yy_i))  yy_i=myyear
      IF (PRESENT(mm_i))  mm_i=mymonth
      IF (PRESENT(dd_i))  dd_i=myday
      IF (PRESENT(h_i ))  h_i =myhour
      IF (PRESENT(m_i ))  m_i =myminutes
      IF (PRESENT(s_i ))  s_i =myseconds
!
      IF (PRESENT(yd_dp)) yd_dp=real(myyday,dp)+dayfraction
      IF (PRESENT(dd_dp)) dd_dp=real(myday,dp)+dayfraction
      IF (PRESENT(h_dp )) h_dp =hour
      IF (PRESENT(m_dp )) m_dp =minutes
      IF (PRESENT(s_dp )) s_dp =seconds
!
      RETURN
      END SUBROUTINE caldate
!
!***********************************************************************
      SUBROUTINE datenum (DateNumber,                                   &
     &                    year, month, day, hour, minutes, seconds)
!***********************************************************************
!                                                                      !
!  Converts requested date (year, month, day, ...) into a serial date  !
!  number according to the supported calendars options:                !
!                                                                      !
!  time_ref = -2            Truncated Julian number (Julian/Gregorian) !
!                             'time-units since 1968-05-23 00:00:00'   !
!  time_ref = -1            360_day calendar (Proleptic Gregorian)     !
!                             'time-units since 0000-12-30 00:00:00'   !
!  time_ref = 0             Proleptic Gregorian calendar               !
!                             'time-units since 0001-01-01 00:00:00'   !
!  time_ref = YYYYMMDD.dd   Gregorian or Proleptic Gregorian calendar  !
!                             'time-units since YYYY-MM-DD hh:mm:ss'   !
!                                                                      !
!  For the Proletic Gregogian calendar, the equations are similar to   !
!  the Matlab function "datenum":                                      !
!                                                                      !
!     Matlab:  datenum(0000,00,00)=0       reference date              !
!              datenum(0000,01,01)=1                                   !
!                                                                      !
!  but for simplicity, the equations coded here have have a different  !
!  origin date (Mar 1, 0000) to facilitate the manipulation of leap    !
!  years (adapted from Gary Katch code, Concordia University, Canada)  !
!  yielding:                                                           !
!                                                                      !
!              datenum(0000,03,01)=0       refecence date: Mar 1, 0000 !
!              datenum(0000,01,01)=-59                                 !
!                                                                      !
!  However, to avoid confusion, an offset of 61 days is added to match !
!  Matlab "datenum" function.  The difference between 0000-00-00 and   !
!  0000-03-01 is 61 days.                                              !
!                                                                      !
!  On 15 October 1582, the Gregorian calendar was introduced with a    !
!  year length of 365.2425 days. This is coded as:                     !
!                                                                      !
!     365 + 1/4 - 1/100 + 1/400   or   365 + 0.25 - 0.01 + 0.0025      !
!                                                                      !
!  which is used to account for leap years.  The base of Mar 1, 0000   !
!  is taken for simplicity since the length of february is not fixed.  !
!                                                                      !
!  Notice that a calendar obtained by extending backward in time from  !
!  its invention or implementation is called the Proleptic version of  !
!  the calendar. For example, the Proleptic Gregorian Calendar extends !
!  backwards the date preceding 15 October 1582 with a year length of  !
!  365.2425 days.                                                      !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     year         Year including the century (integer)                !
!     month        Month of the year: 1=January, ... (integer)         !
!     day          Day of the month (integer)                          !
!     hour         Hour of the day, 0, ... 23 (integer, OPTIONAL)      !
!     minutes      Minutes of the hour (integer, OPTIONAL)             !
!     seconds      Seconds of the minute (real, OPTIONAL)              !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     DateNumber   Date number (real 1D array),                        !
!                    DateValue(1) => fractional days                   !
!                    DateValue(2) => fractional seconds                !
!                                                                      !
!=======================================================================
!
      USE mod_scalars, ONLY : time_ref
!
!  Imported variable declarations.
!
      integer, intent(in) :: year, month, day
 
      integer,  intent(in), optional :: hour
      integer,  intent(in), optional :: minutes
 
      real(dp), intent(in), optional :: seconds
 
      real(dp), intent(out), dimension(2) :: datenumber
!
!  Local variable declarations.
!
      integer, parameter :: offset = 61
 
      integer :: myday, myhour, myminutes, mymonth, myyear, y01
 
      real(dp) :: myseconds
!
!-----------------------------------------------------------------------
!  Initialize optional arguments.
!-----------------------------------------------------------------------
!
      IF (PRESENT(hour)) THEN
        myhour=hour
      ELSE
        myhour=0
      END IF
!
      IF (PRESENT(minutes)) THEN
        myminutes=minutes
      ELSE
        myminutes=0
      END IF
!
      IF (PRESENT(seconds)) THEN
        myseconds=seconds
      ELSE
        myseconds=0.0_dp
      END IF
!
!-----------------------------------------------------------------------
!  Date number for the Julian plus Gregorian correction calendar.
!-----------------------------------------------------------------------
!
!  The origin of the Proleptic Julian Calendar is January 1, 4713 BC
!  (November 24, 4713 BC, in the Proleptic Gregorian Calendar).
!  Although the formal definition of Julian day numbers starts and
!  ends at noon, here Julian day starts and ends at midnight. So it
!  is 12 hours faster (substract 12 hours to agree with formal
!  definition).
!
!     datenum(-4713,11,24) = 0              ! Origin: Nov 24, 4713 BC
!     datenum( 1968,05,23) = 2440000        ! Truncated reference (NASA)
!     datenum( 0000,01,01) = 1721060
!
      calendar : IF (int(time_ref).eq.-2) THEN
        IF (month.gt.2) THEN
          myyear=year
          mymonth=month-3
        ELSE
          myyear=year-1
          mymonth=month+9
        END IF
        y01=myyear/100
        myyear=myyear-y01*100
        myday=(146097*y01/4) + (1461*myyear/4) + ((153*mymonth+2)/5) +  &
     &        day + 1721119
!
!-----------------------------------------------------------------------
!  Date mumber for the 360_day Calendar: the year has a length of 360
!  days and every month has 30 days.
!-----------------------------------------------------------------------
!
!     datenum(0000,01,01) = 0
!     datenum(0001,01,01) = 360
!
      ELSE IF (int(time_ref).eq.-1) THEN
        myday=year*360+(month-1)*30+(day-1)
!
!-----------------------------------------------------------------------
!  Date number for the Gregorian and Gregorian Proleptic Calendar. It
!  has a year length of 365.2425 days (correspoding to the Gregorian
!  Calendar introduced in 15 October 1582).
!-----------------------------------------------------------------------
!
!     datenum(0000,01,01) = 1
!     datenum(0001,01,01) = 367
!
      ELSE
        mymonth=mod(month+9, 12)                  ! Mar=0, ..., Feb=11
        myyear=year-int(0.1_dp*real(mymonth,dp))  ! if Jan or Feb,
!                                                   substract 1
        myday=int(365.0_dp*real(myyear,dp))+                            &
     &        int(0.25_dp*real(myyear,dp))-                             &
     &        int(0.01_dp*real(myyear,dp))+                             &
     &        int(0.0025_dp*real(myyear,dp))+                           &
     &        int(0.1_dp*(real(mymonth,dp)*306.0_dp + 5.0_dp))+         &
     &        (day - 1)
!
!  Adjust for Matlab origin 0000-00-00 00:00:00, so we get the same
!  value as their function "datenum". The offset is 61 days.
!
!     datenum(0000,00,00) = 0
!
        IF ((year.eq.0).and.(month.eq.0).and.(day.eq.0)) THEN
          myday=0;
        ELSE
          IF (myday.lt.0) THEN
            myday=myday+offset-1
          ELSE
            myday=myday+offset
          END IF
        END IF
      END IF calendar
!
!-----------------------------------------------------------------------
!  Add fractional day to serial day number (day and seconds).
!-----------------------------------------------------------------------
!
!  Fractional date number (units=day).
!
      datenumber(1)=real(myday,dp)+                                     &
     &              real(myhour,dp)/24.0_dp+                            &
     &              real(myminutes,dp)/1440.0_dp+                       &
     &              myseconds/86400.0_dp
!
!  Fractional date number (units=second).
!
      datenumber(2)=real(myday,dp)*86400.0_dp+                          &
     &              real(myhour,dp)*3600.0_dp+                          &
     &              real(myminutes,dp)*60.0_dp+                         &
     &              myseconds
 
      RETURN
      END SUBROUTINE datenum
!
!***********************************************************************
      SUBROUTINE datestr (DateNumber, IsDayUnits, DateString)
!***********************************************************************
!                                                                      !
!  Converts a given date number as computed by "datenum" to a date     !
!  string. Matlab has similar function.                                !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     DateNumber   Date number (real; scalar) as computed by           !
!                    by "datenum":                                     !
!     IsDayUnits   Date number units (logical):                        !
!                    IsDayUnits = .TRUE.   fractional days             !
!                    IsDayUnits = .FALSE.  frational seconds           !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     DateSring    Date string (YYYY-MM-DD hh:mm:ss.ss)                !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      logical,  intent(in) :: isdayunits
 
      real(dp), intent(in) :: datenumber
 
      character (len=*), intent(out) :: datestring
!
!  Local variable declarations.
!
      integer :: i, year, month, day, hour, minutes
 
      real(dp):: f_hour, f_minutes, seconds
 
      character (len= 5) :: sec_string
      character (len=22) :: string
!
!-----------------------------------------------------------------------
!  Compute date vector from serial date number.
!-----------------------------------------------------------------------
!
      CALL datevec (datenumber, isdayunits, year, month, day, hour,     &
     &              minutes, seconds, f_minutes, f_hour)
!
!-----------------------------------------------------------------------
!  Set date string.
!-----------------------------------------------------------------------
!
!  Encode fractional seconds to a string. Round to one digit.
!
      WRITE (sec_string, '(f5.2)') seconds
      DO i=1,len(sec_string)                        ! replace leading
        IF (sec_string(i:i).eq.char(32)) THEN       ! space(s) with
          sec_string(i:i)='0'                       ! zeros(s)
        END IF
      END DO
!
!  Encode date string.
!
      WRITE (string,10) year, month, day, hour, minutes, sec_string
 10   FORMAT (i4.4,'-',i2.2,'-',i2.2,1x,i2.2,':',i2.2,':',a)
!
      datestring=trim(string)
!
      RETURN
      END SUBROUTINE datestr
!
!***********************************************************************
      SUBROUTINE datevec (DateNumber, IsDayUnits,                       &
     &                    year, month, day, hour, minutes, seconds,     &
     &                    F_minutes, F_hour)
!***********************************************************************
!                                                                      !
!  Converts a given date number as computed by "datenum" to a date     !
!  vector (year, month, day, hour, minutes, seconds).  It is the       !
!  inverse routine for "datenum" above.                                !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     DateNumber   Date number (real; scalar) as computed by           !
!                    by "datenum":                                     !
!     IsDayUnits   Date number units (logical):                        !
!                    IsDayUnits = .TRUE.   fractional days             !
!                    IsDayUnits = .FALSE.  frational seconds           !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     year         Year including the century (integer; YYYY)          !
!     month        Month of the year: 1=January, ... (integer)         !
!     day          Day of the month (integer)                          !
!     hour         Hour of the day, 0, ... 23 (integer)                !
!     minutes      Minutes of the hour (integer)                       !
!     seconds      Seconds of the minute (real)                        !
!                                                                      !
!     F_minutes    Fractional minutes (real)                           !
!     F_hour       Fractional hours (real)                             !
!                                                                      !
!***********************************************************************
!
      USE mod_scalars, ONLY : rclock, time_ref
      USE round_mod,   ONLY : round
!
!  Imported variable declarations.
!
      logical,  intent(in) :: isdayunits
 
      real(dp), intent(in) :: datenumber
 
      integer,  intent(out) :: year, month, day, hour, minutes
 
      real(dp), intent(out) :: f_hour, f_minutes, seconds
!
!  Local variable declarations.
!
      logical :: prolepticjulian = .false.
 
      integer :: myday, mymonth, myyear, yday
      integer :: ja, jalpha, jb, jc, jd, jday, je
 
      integer, parameter :: gregorian = 2299161  ! 15 Oct, 1582 A.D.
 
      real(dp), parameter :: offset = 61.0_dp
 
      real(dp) :: ct, dayfraction, mydatenumber
      real(dp) :: dd, jr, js, mo, yy
!
!-----------------------------------------------------------------------
!  Compute date vector from date number for the Julian with Gregorian
!  Calendar correction.
!-----------------------------------------------------------------------
!
!  If truncated, add reference date number (2440000 days). The origin
!  of the Proleptic Julian Calendar is Jan 1, 4713 BC (that is,
!  Nov 24, 4713 BC in the Proleptic Gregorian Calendar).
!
!  Although the formal definition holds that Julian day starts and ends
!  at noon, here Julian day starts and ends at midnight.
!
!  It is assumed that if input DateNumber is greater or equal to the
!  Gregorian Calendar start, its value is full and not Reduced,
!  Modified, or Truncated.
!
      calendar : IF (int(time_ref).eq.-2) THEN
        IF (isdayunits) THEN
          IF (datenumber.ge.real(gregorian,dp)) THEN
            mydatenumber=datenumber
          ELSE
            mydatenumber=datenumber+rclock%DateNumber(1)
          END IF
        ELSE
          IF (datenumber.ge.(real(gregorian,dp)*86400.0_dp)) THEN
            mydatenumber=datenumber/86400.0_dp
          ELSE
            mydatenumber=(datenumber+rclock%DateNumber(2))/86400.0_dp
          END IF
        END IF
        dayfraction=abs(mydatenumber-aint(mydatenumber))
!
        IF (prolepticjulian) THEN            ! Proleptic Julian Calendar
          jday=int(mydatenumber)             ! origin: Jan 1, 4713 BC
          IF (jday.ge.gregorian) THEN
            jalpha=int(((jday-1867216)-0.25_dp)/36524.25_dp)! Gregorian
            ja=jday+1+jalpha-int(0.25_dp*real(jalpha,dp))   ! correction
          ELSE
            ja=jday
          END IF
          jb=ja+1524
          jc=int(6680.0_dp+(real(jb-2439870,dp)-122.1_dp)/365.25_dp)
          jd=365*jc+int(0.25_dp*real(jc,dp))
          je=int(real(jb-jd,dp)/30.6001_dp)
          day=jb-jd-int(30.6001_dp*real(je,dp))
          month=je-1
          IF (month.gt.12) month=month-12
          year=jc-4715
          IF (month.gt.2) year=year-1
          IF (year .le.0) year=year-1
        ELSE                                    ! Proleptic Gregorian
          jr=floor(mydatenumber)-1721119.0_dp   ! Calendar, origin:
          js=4.0_dp*jr-1.0_dp                   ! Nov 24, 4713 BC
          yy=floor(js/146097.0_dp)
          jr=js-146097.0_dp*yy
          js=floor(jr*0.25_dp)
          js=4.0_dp*js+3.0_dp
          jr=floor(js/1461.0_dp)
          dd=floor(((js-1461.0_dp*jr)+4.0_dp)*0.25_dp)
          js=5.0_dp*dd-3.0_dp
          mo=floor(js/153.0_dp)
          yy=yy*100.0_dp+jr
!
          IF (mo.lt.10.0_dp) THEN
            year =int(yy)
            month=int(mo+3)
          ELSE
            year =int(yy+1)
            month=int(mo-9)
          END IF
          day=int(((js-153.0_dp*mo)+5.0_dp)*0.2_dp)
        END IF
!
        seconds=dayfraction*86400.0_dp
        ct=3.0_dp*epsilon(seconds)           ! comparison tolerance
        seconds=round(seconds, ct)           ! tolerant round function
        f_hour=seconds/3600.0_dp
        hour=int(f_hour)
        seconds=abs(seconds-real(hour*3600,dp))
        f_minutes=seconds/60.0_dp
        minutes=int(f_minutes)
        seconds=abs(seconds-real(minutes*60,dp))
!
!-----------------------------------------------------------------------
!  Compute date vector from date mumber for the 360_day calendar: the
!  year has a length of 360 days and every month has 30 day.
!-----------------------------------------------------------------------
!
      ELSE IF (int(time_ref).eq.-1) THEN
        dayfraction=abs(datenumber-aint(datenumber))
!
        IF (isdayunits) THEN
          year=int(datenumber/360.0_dp)
          yday=int(datenumber-real(year*360,dp)+1)
        ELSE
          year=int(datenumber/31104000.0_dp)              ! 360*86400
          yday=int((datenumber-real(year*31104000,dp)+1)/86400.0_dp)
        END IF
        month=((yday-1)/30)+1
        day=mod(yday-1,30)+1
!
        seconds=dayfraction*86400.0_dp
        ct=3.0_dp*epsilon(seconds)           ! comparison tolerance
        seconds=round(seconds, ct)           ! tolerant round function
        f_hour=seconds/3600.0_dp
        hour=int(f_hour)
        seconds=abs(seconds-real(hour*3600,dp))
        f_minutes=seconds/60.0_dp
        minutes=int(f_minutes)
        seconds=abs(seconds-real(f_minutes*60,dp))
!
!-----------------------------------------------------------------------
!  Compute date vector from date number for the Gregorian and Gregorian
!  Proleptic Calendar.
!-----------------------------------------------------------------------
!
      ELSE
        IF (isdayunits) THEN                        ! fractional days
          mydatenumber=datenumber
        ELSE                                        ! fractional seconds
          mydatenumber=datenumber/86400.0_dp
        END IF
        dayfraction=abs(mydatenumber-aint(mydatenumber))
!
        IF (mydatenumber.lt.offset) THEN            ! adjust for Matlab
          mydatenumber=mydatenumber-offset+1.0_dp   ! zero origin,
        ELSE                                        ! datenum(0,0,0)=0,
          mydatenumber=mydatenumber-offset          ! 61 days offset
        ENDIF
!
        myyear=int((10000.0_dp*aint(mydatenumber)+14780.0_dp)/          &
     &             3652425.0_dp)
        myday=int(mydatenumber)-                                        &
     &        (int(365.0_dp*real(myyear,dp))+                           &
     &         int(0.25_dp*real(myyear,dp))-                            &
     &         int(0.01_dp*real(myyear,dp))+                            &
     &         int(0.0025_dp*real(myyear,dp)))
        IF (myday.lt.0) THEN                        ! if less than Mar 1
          myyear=myyear-1                           ! easy on leap-years
          myday=int(mydatenumber)-                                      &
     &          (int(365.0_dp*real(myyear,dp))+                         &
     &           int(0.25_dp*real(myyear,dp))-                          &
     &           int(0.01_dp*real(myyear,dp))+                          &
     &           int(0.0025_dp*real(myyear,dp)))
        END IF
        mymonth=int((100.0_dp*real(myday,dp)+ 52.0_dp)/3060.0_dp)
        month=mod(mymonth+2, 12) + 1
        year=myyear+                                                    &
     &       int((real(mymonth,dp)+2.0_dp)/12.0_dp)
        day=myday-                                                      &
     &      int(0.1_dp*(real(mymonth,dp)*306.0_dp + 5.0_dp)) + 1
!
!  Fix to match Matlab "datestr" function values with the origin at
!  0000-00-00 00:00:00
!
        IF (datenumber.eq.0.0_dp) THEN
          year=0
          month=1
          day=0
        END IF
!
!  Convert fraction of a day.
!
        seconds=dayfraction*86400.0_dp
        ct=3.0_dp*epsilon(seconds)           ! comparison tolerance
        seconds=round(seconds, ct)           ! tolerant round function
!
        f_hour=seconds/3600.0_dp
        hour=int(f_hour)
        seconds=abs(seconds-real(hour*3600,dp))
        f_minutes=seconds/60.0_dp
        minutes=int(f_minutes)
        seconds=abs(seconds-real(minutes*60,dp))
      END IF calendar
!
      RETURN
      END SUBROUTINE datevec
!
!***********************************************************************
      SUBROUTINE day_code (month, day, year, code)
!***********************************************************************
!                                                                      !
!  This subroutine computes a code for the day of the week, given      !
!  the date. This code is good for dates after:                        !
!                                                                      !
!                              January 1, 1752 AD                      !
!                                                                      !
!  the year the Gregorian calander was adopted in Britian and the      !
!  American colonies.                                                  !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     month     The month, 1=January, 2=February, ... (integer).       !
!     day       The day of the month (integer).                        !
!     year      The year, including the century (integer).             !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     code      A code for the corresponding day of the week           !
!                 (integer):                                           !
!                 code = 0  =>  Sunday                                 !
!                 code = 1  =>  Monday                                 !
!                 code = 2  =>  Tuesday                                !
!                 code = 3  =>  Wednesday                              !
!                 code = 4  =>  Thursday                               !
!                 code = 5  =>  Friday                                 !
!                 code = 6  =>  Saturday                               !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      integer, intent(in) :: month, day, year
 
      integer, intent(out) :: code
!
!  Local variable declarations.
!
      logical :: leap_flag
 
      integer, parameter :: base_cen = 1700
      integer, parameter :: base_qcen = 1600
      integer, parameter :: base_qyear = 1748
      integer, parameter :: base_year = 1752
      integer, parameter :: bym1_dec31 = 5
      integer, parameter :: feb_end = 59
 
      integer :: i, leap, no_day, no_yr, nqy, nyc, nyqc
 
      integer, dimension(12) :: month_day =                             &
     &         (/ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 /)
!
!-----------------------------------------------------------------------
!  Compute the number of years since the base year, the number of
!  years since the beginning of the base century and the number of
!  years since the beginning of the base 400 year.
!-----------------------------------------------------------------------
!
      no_yr=year-base_year
      nqy=year-base_qyear
      nyc=year-base_cen
      nyqc=year-base_qcen
!
!-----------------------------------------------------------------------
!  Compute the number of leapdays in that time.  Determine if this
!  is a leap year.
!-----------------------------------------------------------------------
!
      leap=nqy/4-nyc/100+nyqc/400
      leap_flag=((mod(nqy,4).eq.0).and.(mod(nyc,100).ne.0)).or.         &
     &           (mod(nyqc,400).eq.0)
!
!-----------------------------------------------------------------------
!  Compute the number of days this year.  The leap year corrections
!  are:
!        Jan. 1 - Feb. 28   Have not had the leap day counted above.
!        Feb.29             Counting leap day twice.
!-----------------------------------------------------------------------
!
      no_day=day
      DO i=1,month-1
        no_day=no_day+month_day(i)
      END DO
      IF (leap_flag.and.(no_day.le.feb_end))  no_day=no_day-1
      IF (leap_flag.and.(month.eq.2).and.(day.eq.29)) no_day=no_day-1
!
!-----------------------------------------------------------------------
!  Compute the total number of days since Jan. 1 of the base year,
!  exclusive of the 364 day per year which represent an even 52
!  weeks.  Actually, only need to do the addition mod 7.
!-----------------------------------------------------------------------
!
      no_day=mod(no_day,7)+mod(leap,7)+mod(no_yr,7)+bym1_dec31
!
!-----------------------------------------------------------------------
!  Get the day of the week code.
!-----------------------------------------------------------------------
!
      code=mod(no_day,7)
      RETURN
      END SUBROUTINE day_code
!
!***********************************************************************
      SUBROUTINE get_date (date_str)
!***********************************************************************
!                                                                      !
!   This routine gets today's date string. It uses intrinsic fortran   !
!   function "date_and_time" and a 12 hour clock.   The string is of   !
!   the form:                                                          !
!                                                                      !
!                DayOfWeak - Month day, year - hh:mm:ss ?M             !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     date_str   Today date string, for example:                       !
!                                                                      !
!                  Friday - February 3, 2017 -  3:40:25 PM             !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      character (len=*), intent(out) :: date_str
!
!  Local variable declarations.
!
      integer :: iyear, imonth, iday, ihour, iminute, isecond
      integer :: dindex, i, half, len1, len2, len3
 
      integer, dimension(8) :: values
 
      integer, dimension(31) :: lday =                                  &
     &          (/ (1,i=1,9), (2,i=1,22) /)
 
      integer, dimension(12) :: lmonth =                                &
     &          (/ 7, 8, 5, 5, 3, 4, 4, 6, 9, 7, 8, 8 /)
 
      character (len= 5) :: czone
      character (len= 8) :: cdate
      character (len=10) :: ctime
      character (len=11) :: tstring
      character (len=18) :: today
      character (len=20) :: fmt
      character (len=44) :: dstring
 
      character (len=3), dimension(0:1) :: ampm =                       &
     &                   (/' AM',' PM'/)
 
      character (len=9), dimension(0:6) :: day =                        &
     &                   (/ 'Sunday   ','Monday   ','Tuesday  ',        &
     &                      'Wednesday','Thursday ','Friday   ',        &
     &                      'Saturday ' /)
 
      character (len=9), dimension(12) :: month =                       &
     &                   (/ 'January  ','February ','March    ',        &
     &                      'April    ','May      ','June     ',        &
     &                      'July     ','August   ','September',        &
     &                      'October  ','November ','December ' /)
!
!-----------------------------------------------------------------------
!  Get weekday, date and time in short format, then extract its
!  information.
!-----------------------------------------------------------------------
!
      CALL date_and_time (cdate, ctime, czone, values)
!
      iyear=values(1)            ! 4-digit year
      imonth=values(2)           ! month of the year
      iday=values(3)             ! day of the month
      ihour=values(5)            ! hour of the day, local time
      iminute=values(6)          ! minutes of the hour, local time
      isecond=values(7)          ! seconds of the minute, local time
!
!-----------------------------------------------------------------------
!  Convert from 24 hour clock to 12 hour AM/PM clock.
!-----------------------------------------------------------------------
!
      half=ihour/12
      ihour=ihour-half*12
      IF (ihour.eq.0) ihour=12
      IF (half.eq.2) half=0
!
!-----------------------------------------------------------------------
!  Get index for the day of the week.
!-----------------------------------------------------------------------
!
      CALL day_code (imonth, iday, iyear, dindex)
!
!-----------------------------------------------------------------------
!  Construct date, time and day of the week output string.
!-----------------------------------------------------------------------
!
      WRITE (fmt,10) lmonth(imonth), lday(iday)
 10   FORMAT ('(a',i1,',1x,i',i1,',1h,,1x,i4)')
      WRITE (today,fmt) month(imonth), iday, iyear
      dstring=day(dindex)
      WRITE (tstring,20) ihour, iminute, isecond, ampm(half)
 20   FORMAT (i2,':',i2.2,':',i2.2,a3)
!
!  Concatenate date string.
!
      len1=len_trim(dstring)
      len2=len_trim(today)
      len3=len_trim(tstring)
      date_str=trim(adjustl(dstring(1:len1)))
      IF (len2.gt.0) THEN
        len1=len_trim(date_str)
        WRITE (date_str,'(a," - ",a)') trim(date_str(1:len1)),          &
     &                                 trim(today(1:len2))
      END IF
      IF (len3.gt.0) THEN
        len1=len_trim(date_str)
        WRITE (date_str,'(a," - ",a)') trim(date_str(1:len1)),          &
     &                                 trim(tstring(1:len3))
      END IF
      RETURN
      END SUBROUTINE get_date
!
!***********************************************************************
      SUBROUTINE ref_clock (r_time)
!***********************************************************************
!                                                                      !
!  This routine encodes the relative time attribute that gives the     !
!  elapsed interval since a specified reference time.  The "units"     !
!  attribute takes the form "time-unit since reference-time".          !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     r_time     Time-reference (real; YYYYMMDD.dd; for example,       !
!                  20020115.5 for 15 Jan 2002, 12:0:0).                !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     Rclock     The time clock base/reference is loaded into module   !
!                  (mod_scalars.F)  structure:                         !
!                                                                      !
!                  Rclock%yday       => day of the year                !
!                  Rclock%year       => year including century (YYYY)  !
!                  Rclock%month      => month of the year              !
!                  Rclock%day        => day of the month               !
!                  Rclock%hour       => hour of the day (0,...,23)     !
!                  Rclock%minutes    => minutes of the hour            !
!                  Rclock%seconds    => seconds of the minute          !
!                  Rclock%base       => reference date (YYYYMMDD.dd)   !
!                  Rclock%DateNumber => date number, 1: days 2: seconds!
!                  Rclock%string     => attribute (YYYY-MM-DD hh:ss:mm)!
!                  Rclock%calendar   => date calendar                  !
!                                                                      !
!***********************************************************************
!
      USE mod_param
      USE mod_scalars
!
!  Imported variable declarations.
!
      real(dp), intent(in) :: r_time
!
!  Local variable declarations.
!
      integer :: ifac
      integer :: iday, ihour, isec, iyear, leap, minute, month, yday
 
      real(dp) :: day, sec
 
      real(dp), dimension(2) :: datenumber
 
      character (len=19) :: string
      character (len=20) :: calendar
!
!-----------------------------------------------------------------------
!  Decode reference time.
!-----------------------------------------------------------------------
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since YYYY-MM-DD hh:mm:ss'.
!
      IF (int(r_time).gt.0) THEN                 ! day 0: Mar 1, 0000
        calendar='proleptic_gregorian'
        iyear=max(1,int(r_time*0.0001_dp))
        month=min(12,max(1,int((r_time-real(iyear*10000,dp))*0.01_dp)))
        day=r_time-aint(r_time*0.01_dp)*100.0_dp
        iday=max(1,int(day))
        sec=(day-aint(day))*86400.0_dp
        ihour=int(sec/3600.0_dp)
        minute=int(mod(sec,3600.0_dp)/60.0_dp)
        isec=int(mod(sec,60.0_dp))
        yday=yearday(iyear, month, iday)
        CALL datenum (datenumber, iyear, month, iday, ihour, minute,    &
     &                real(isec,dp))
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 0001-01-01 00:00:00'. It has a year length of
!  365.2425 days
!
      ELSE IF (int(r_time).eq.0) THEN            ! day 0: Mar 1, 0000
        calendar='proleptic_gregorian'
        iyear=1
        month=1
        iday=1
        ihour=0
        minute=0
        isec=0
        yday=1
        yday=yearday(iyear, month, iday)
        CALL datenum (datenumber, iyear, month, iday, ihour, minute,    &
     &                real(isec,dp))
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 0001-01-01 00:00:00'.  It has a year length of
!  360 days.
!
!  In this calendar, the time in days is simply:
!
!    Time = year * 360 + (month - 1) * 30 + (day - 1)
!
!  And its inverse
!
!    year  = INT(Time / 360)
!    yday  = INT((Time - year * 360) + 1)
!    month = INT(((yday - 1) / 30) + 1)
!    day   = MOD(yday - 1, 30) + 1
!
!  It assumes that the origin (DayNumber=0) corresponds to 01-Jan-0000.
!  However, historically ROMS assumed that DayNumber=1 corresponded to
!  01-Jan-0000 instead. So, there is one day shift. The equations
!  can be manipulated to give either origin, but it is confusing. The
!  above equations are cleaner and now effective (HGA: 30-Jan-2018). The
!  origin (DayNumber=0) occurs on 01-Jan-0000.
!
!  To guarantee compatibility with previous ROMS solutions with this
!  climatological calendar, the reference date is changed to
!
!  'time-units since 0000-12-30 00:00:00'
!
!  to fix the one date shift because DayNumber=0 on 01-Jan-0000. Anyway,
!  it is a highly idealized calendar used in analytical test cases or
!  climatological solutions.
!
      ELSE IF (int(r_time).eq.-1) THEN           ! day 0: Jan 1, 0000
        calendar='360_day'
        iyear=0
        month=12
        iday=30
        ihour=0
        minute=0
        isec=0
        yday=360
        datenumber(1)=359.0_dp
        datenumber(2)=datenumber(1)*86400.0_dp
!
!  The model clock is the elapsed time since reference time of the form
!  'time-units since 1968-05-23 00:00:00 GMT'. It is a Truncated Julian
!  day. It has a year length of 365.25 days.
!
!  The one here is known as the Gregorian Calendar.  Although, it is a
!  minor correction to the Julian Calendar after 15 Oct 1582 with a
!  year length of 365.2425.
!
      ELSE IF (int(r_time).eq.-2) THEN          ! day 0: Nov 24, 4713 BC
        calendar='proleptic_julian'
        iyear=1968
        month=5
        iday=23
        ihour=0
        minute=0
        isec=0
        yday=yearday(iyear, month, iday)
        datenumber(1)=2440000.0_dp              ! Truncated offset
        datenumber(2)=datenumber(1)*86400.0_dp
      END IF
!
!-----------------------------------------------------------------------
!  Set reference-time string, YYYY-MM-DD hh:mm:ss
!-----------------------------------------------------------------------
!
      WRITE (string,10) iyear, month, iday, ihour, minute, isec
 10   FORMAT (i4.4,'-',i2.2,'-',i2.2,1x,i2.2,':',i2.2,':',i2.2)
!
!-----------------------------------------------------------------------
!  Load time reference clock information into structure.
!-----------------------------------------------------------------------
!
      rclock%yday         =yday
      rclock%year         =iyear
      rclock%month        =month
      rclock%day          =iday
      rclock%hour         =ihour
      rclock%minutes      =minute
      rclock%seconds      =isec
      rclock%base         =r_time
      rclock%DateNumber(1)=datenumber(1)
      rclock%DateNumber(2)=datenumber(2)
      rclock%string       =string
      rclock%calendar     =trim(calendar)
!
      RETURN
      END SUBROUTINE ref_clock
!
!**********************************************************************
      SUBROUTINE roms_clock (year, month, day, hour, minutes, seconds,  &
     &                       ClockTime)
!***********************************************************************
!                                                                      !
!  Given any date (year, month, day, hour, minute, second), this       !
!  this routine returns ROMS clock time since initialization in        !
!  seconds from reference date.                                        !
!                                                                      !
!  This clock time is used when importing fields from coupled models.  !
!  It is assumed that coupling applications use Gregorian calendar,    !
!  INT(time_ref) .ge. 0.                                               !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     year       The year, including the century (integer)             !
!     month      The month, 1=January, 2=February, ... (integer)       !
!     day        The day of the month (integer)                        !
!     hour       The hour of the day (integer)                         !
!     minute     The minute of the hour (integer)                      !
!     seconds    The seconds of the minute (real)                      !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     ClockTime  ROMS clock time since initialization in seconds       !
!                  from reference time (real)                          !
!                                                                      !
!***********************************************************************
!
      USE mod_param
      USE mod_scalars
!
!  Imported variable declarations.
!
      integer, intent(in) :: year, month, day, hour, minutes
 
      real(dp), intent(in)  :: seconds
      real(dp), intent(out) :: clocktime
!
!  Local variable declarations.
!
      real(dp), dimension(2) :: datenumber
!
!-----------------------------------------------------------------------
!  Compute ROMS clock elapsed time since intialization in seconds from
!  reference time.
!-----------------------------------------------------------------------
!
!  Convert requested date into date number.
!
      CALL datenum (datenumber, year, month, day,                       &
     &              hour, minutes, seconds)
!
!  Compute ROMS clock elapsed time in seconds.
!
      clocktime=datenumber(2)-rclock%DateNumber(2)
!
      RETURN
      END SUBROUTINE roms_clock
!
!***********************************************************************
      SUBROUTINE time_iso8601 (MyTime, date_string)
!***********************************************************************
!                                                                      !
!  This routine encodes current model time in seconds to a date        !
!  string of the form:                                                 !
!                                                                      !
!       YYYY-MM-DDThh:mm:ssZ                                           !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     MyTime        Current model time (seconds)                       !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     date_string  Current model time date string (20 charactes).      !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      real(dp), intent(in) :: mytime
 
      character (len=20), intent(out) :: date_string
!
!  Local variable declarations.
!
      integer :: day, hour, minutes, month, year, seconds
      integer :: i
!
      real(dp) :: currenttime
!
      character (len=20) :: string
!
!-----------------------------------------------------------------------
!  Encode current model time.
!-----------------------------------------------------------------------
!
!  Convert current model time to calendar date.
!
      currenttime=mytime/86400.0_dp                  ! seconds to days
!
      CALL caldate (currenttime,                                        &
     &              yy_i=year,                                          &
     &              mm_i=month,                                         &
     &              dd_i=day,                                           &
     &              h_i=hour,                                           &
     &              m_i=minutes,                                        &
     &              s_i=seconds)
!
!  Encode calendar date into a string.
!
      WRITE (string,10) year, month, day, hour, minutes, seconds
 10   FORMAT (i4.4,'-',i2.2,'-',i2.2,'T',i2.2,':',i2.2,':',i2.2,'Z')
!
      date_string=trim(string)
!
      RETURN
      END SUBROUTINE time_iso8601
!
!***********************************************************************
      SUBROUTINE time_string (MyTime, date_string)
!***********************************************************************
!                                                                      !
!  This routine encodes current model time in seconds to a date        !
!  string of the form:                                                 !
!                                                                      !
!       YYYY-MM-DD hh:mm:ss.ss                                         !
!                                                                      !
!  The decimal seconds (ss.s) are rounded to the next digit. This      !
!  encoding allows an easy to read reporting time.                     !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     MyTime        Current model time (seconds)                       !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     date_string  Current model time date string (22 charactes).      !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      real(dp), intent(in) :: mytime
 
      character (len=22), intent(out) :: date_string
!
!  Local variable declarations.
!
      integer :: day, hour, minutes, month, year
      integer :: i
 
      real(dp) :: currenttime, seconds
 
      character (len= 5) :: sec_string
      character (len=22) :: string
!
!-----------------------------------------------------------------------
!  Encode current model time.
!-----------------------------------------------------------------------
!
!  Convert current model time to calendar date.
!
      currenttime=mytime/86400.0_dp                  ! seconds to days
!
      CALL caldate (currenttime,                                        &
     &              yy_i=year,                                          &
     &              mm_i=month,                                         &
     &              dd_i=day,                                           &
     &              h_i=hour,                                           &
     &              m_i=minutes,                                        &
     &              s_dp=seconds)
 
!
!  Encode fractional seconds to a string. Round to one digit.
!
      WRITE (sec_string, '(f5.2)') seconds
      DO i=1,len(sec_string)                        ! replace leading
        IF (sec_string(i:i).eq.char(32)) THEN       ! space(s) with
          sec_string(i:i)='0'                       ! zeros(s)
        END IF
      END DO
!
!  Encode calendar date into a string.
!
      WRITE (string,10) year, month, day, hour, minutes, sec_string
 10   FORMAT (i4.4,'-',i2.2,'-',i2.2,1x,i2.2,':',i2.2,':',a)
!
      date_string=trim(string)
!
      RETURN
      END SUBROUTINE time_string
!
!***********************************************************************
      SUBROUTINE time_units (Ustring, year, month, day,                 &
     &                       hour, minutes, seconds)
!***********************************************************************
!                                                                      !
!  This routine decodes the time units attribute of the form:          !
!                                                                      !
!    'time-units since YYYY-MM-DD hh:mm:ss'                            !
!    'time-units since YYYY-MM-DD hh:mm:ss.ss'                         !
!                                                                      !
!  and various CF compliant variants.                                  !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     U             Time attribute (string)                            !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     year          Year including century (integer)                   !
!     month         Month of the year, 1=Jan, ..., 12=Dec (integer)    !
!     day           Day of the month (integer)                         !
!     hour          Hour of the day (integer)                          !
!     minutes       Minutes of the hour, 0 - 59 (integer)              !
!     seconds       Seconds of the minute (real)                       !
!                                                                      !
!  Examples of valid unit attributes:                                  !
!                                                                      !
!     'days since 1900-01-01 00:00:00'                                 !
!     'seconds since 1992-10-8 15:15:42.5 -6'                          !
!     'hours since 1990-1-1 0:0:0'                                     !
!     'days since 1582-10-15 1:30:15'                                  !
!     'days since 1-1-1 0:0:0'                                         !
!     'hour since 1997-4-30 1:5:30.5'                                  !
!     'second since 1961-1-1'                                          !
!     'years since -2000-02-29 00:00:0.000Z'                           !
!     'days since 1-07-15 0:0:0'                                       !
!     'days since 0000-01-01 0:0:0'                                    !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      integer,  intent(out) :: year, month, day, hour, minutes
!
      real(dp), intent(out) :: seconds
!
      character (len=*), intent(in) :: ustring
!
!  Exported variable declarations.
!
      logical :: decode
      integer :: i, iblank, ie, is, iscale, lstr, lvar, nval
      integer :: schar
 
      real(dp) :: rval(10)
 
      character (len=20)       :: vstring
      character (LEN(Ustring)) :: tstring
!
!-----------------------------------------------------------------------
!  Decode time string attribute.
!-----------------------------------------------------------------------
!
!  Initialize.
!
      year=0
      month=0
      day=0
      hour=0
      minutes=0
      seconds=0.0_dp
!
      DO i=1,len(tstring)
        tstring(i:i)=char(32)                            ! blank space
      END DO
!
!  Replace non-numeric characters with blanks.
!
      tstring=adjustl(trim(ustring))
      lstr=len_trim(tstring)
!
!  Only the following ASCII charactes are unchanged:
!
!    Char  Dec  Control Action
!    ------------------------------
!    SP    32   Space
!    +     43   Plus
!    -     45   Hyphen, dash, minus
!    .     46   Period
!    0     48   Zero
!    1     49   One
!    2     50   Two
!    3     51   Three
!    4     52   Four
!    5     53   Five
!    6     54   Six
!    7     55   Seven
!    8     56   Eight
!    9     57   Nine
!
      DO i=1,lstr
        schar=ichar(tstring(i:i))
        IF (.not.(((48.le.schar).and.(schar.le.57)).or.                 &
     &            (schar.eq.32).or.(schar.eq.46))) THEN
           tstring(i:i)=char(32)                          ! blank space
        END IF
      END DO
      tstring=adjustl(trim(tstring))
      lstr=len_trim(tstring)
!
!  Check for negative year indicating CE, BC or BCE (Common Era, Before
!  Christ or Before Common Era).
!
      IF (index(ustring, 'since -').gt.0) THEN
        iscale=-1
      ELSE
        iscale=1
      END IF
!
!  Process numrical values.  Since CHAR(45) is retained, take the
!  absolute value except for the first number representing the year.
!  The year is the only numerical value that can be negative (BC or
!  BCE.
!
      is=1
      ie=lstr
      iblank=0
      nval=0
      decode=.false.
      DO i=1,lstr
        IF (tstring(i:i).eq.char(32)) THEN
          IF (tstring(i+1:i+1).ne.char(32)) decode=.true.
          iblank=i
        ELSE
          ie=i
        END IF
        IF (decode.or.(i.eq.lstr)) THEN
          nval=nval+1
          vstring=tstring(is:ie)
          lvar=len_trim(vstring)
          READ (vstring(1:lvar),*) rval(nval)
          is=iblank+1
          ie=lvar
          decode=.false.
        END IF
      END DO
!
!  Load values.
!
      DO i=1,nval
        SELECT CASE (i)
          CASE (1)
            year=int(rval(i))*iscale
          CASE (2)
            month=int(rval(i))
          CASE (3)
            day=int(rval(i))
          CASE (4)
            hour=int(rval(i))
          CASE (5)
            minutes=int(rval(i))
          CASE (6)
            seconds=rval(i)
        END SELECT
      END DO
      RETURN
      END SUBROUTINE time_units
!
!***********************************************************************
      INTEGER FUNCTION yearday (year, month, day) RESULT (yday)
!***********************************************************************
!                                                                      !
!  Given any date year, month, and day, this function returns the      !
!  day of the year.                                                    !
!                                                                      !
!  On Input:                                                           !
!                                                                      !
!     year       Year including the century (integer; YYYY)            !
!     month      Month of the year: 1=January, ... (integer)           !
!     day        Day of the month (integer)                            !
!                                                                      !
!  On Output:                                                          !
!                                                                      !
!     yday       Day of the year (integer)                             !
!                                                                      !
!***********************************************************************
!
!  Imported variable declarations.
!
      integer, intent(in) :: year, month, day
!
!  Local variable declarations.
!
      integer :: fac
!
!-----------------------------------------------------------------------
!  Compute day of the year.
!-----------------------------------------------------------------------
!
      IF (((mod(year,4).eq.0).and.(mod(year,100).ne.0)).or.             &
     &    (mod(year,400).eq.0)) THEN
        fac=1                                               ! leap year
      ELSE
        fac=2
      END IF
      yday=int((275.0*month)/9) - fac*int((month+9)/12) + day - 30
 
      RETURN
      END FUNCTION yearday
!
      END MODULE dateclock_mod