PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

## Module time_interp_mod

Contact: Bruce Wyman
Reviewers:
Change History: WebCVS Log

#### OVERVIEW

Computes a weight and dates/indices for linearly interpolating between two dates.

A time type is converted into two consecutive dates plus a fraction representing the distance between the dates. This information can be used to interpolate between the dates. The dates may be expressed as years, months, or days or as indices in an array.

#### OTHER MODULES USED

    time_manager_mod
             fms_mod

#### PUBLIC INTERFACE

Description summarizing public interface.

time_interp:
  Returns a weight and dates or indices for interpolating between two dates. The interface fraction_of_year is provided for backward compatibility with the previous version.
fraction_of_year:
  Wrapper for backward compatibility

#### PUBLIC DATA

None.

#### PUBLIC ROUTINES

1. #### time_interp

       1. call time_interp ( Time, weight )

       2. call time_interp ( Time, weight, year1, year2 )

       3. call time_interp ( Time, weight, year1, year2, month1, month2 )

       4. call time_interp ( Time, weight, year1, year2, month1, month2, day1, day2 )

       5. call time_interp ( Time, Timelist, weight, index1, index2 [, modtime] )

       6. call time_interp ( Time, Time_beg, Time_end, Timelist, weight, index1, index2 [,correct_leap_year_inconsistency])

   DESCRIPTION
     Returns weight by interpolating Time between Time1 and Time2. i.e. weight = (Time-Time1)/(Time2-Time1) Time1 and Time2 may be specified by any of several different ways, which is the reason for multiple interfaces. If Time1 and Time2 are the begining and end of the year in which Time falls, use first interface. If Time1 and Time2 fall on year boundaries, use second interface. If Time1 and Time2 fall on month boundaries, use third. If Time1 and Time2 fall on day boundaries, use fourth. If Time1 and Time2 are consecutive elements of an assending list, use fifth. The fifth also returns the indices of Timelist between which Time falls. The sixth interface is for cyclical data. Time_beg and Time_end specify the begining and end of a repeating period. In this case: weight = (Time_adjusted - Time1) / (Time2 - Time1) Where: Time1 = Timelist(index1) Time2 = Timelist(index2) Time_adjusted = Time - N*Period Period = Time_end-Time_beg N is between (Time-Time_end)/Period and (Time-Time_beg)/Period That is, N is the integer that results in Time_adjusted that is between Time_beg and Time_end.
   INPUT

     `Time` | The time at which the the weight is computed. [time_type] [time_type] [time_type] [time_type] [time_type] [time_type]
     `Time_beg` | For cyclical interpolation: Time_beg specifies the begining time of a cycle. [time_type]
     `Time_end` | For cyclical interpolation: Time_end specifies the ending time of a cycle. [time_type]
     `Timelist` | For cyclical interpolation: Timelist is an array of times between Time_beg and Time_end. Must be monotonically increasing. [time_type, dimension(:)] [time_type, dimension(:)]
     `modtime` | [integer]
     `index1` | Timelist(index1) = The largest value of Timelist which is less than mod(Time,Time_end-Time_beg)
     `index2` | Timelist(index2) = The smallest value of Timelist which is greater than mod(Time,Time_end-Time_beg)
     `correct_leap_year_inconsistency` | Turns on a kluge for an inconsistency which may occur in a special case. When the modulo time period (i.e. Time_end - Time_beg) is a whole number of years and is not a multiple of 4, and the calendar in use has leap years, then it is likely that the interpolation will involve mapping a common year onto a leap year. In this case it is often desirable, but not absolutely necessary, to use data for Feb 28 of the leap year when it is mapped onto a common year. To turn this on, set correct_leap_year_inconsistency=.true. [logical, optional]

   OUTPUT

     `weight` | weight = (mod(Time,Time_end-Time_beg) - Timelist(index1)) / (Timelist(index2) - Timelist(index1)) [real] [real] [real] [real] [real] [real]
     `year1` | [integer] [integer] [integer]
     `year2` | [integer] [integer] [integer]
     `month1` | [integer] [integer]
     `month2` | [integer] [integer]
     `day1` | [integer]
     `day2` | [integer]
     `index1` | [real] [real]
     `index2` | [real] [real]

   NOTE
     Examples:

                Time: Jan 01 00z    weight = 0.0
                Time: Jul 01        weight ~ 0.5
                Time: Dec 31 23z    weight ~ 1.0

2. #### fraction_of_year

   DESCRIPTION

#### DATA SETS

None.

#### ERROR MESSAGES

ERROR in time_interp
  input time list not ascending order
  The list of input time types must have ascending dates.
ERROR in time_interp
  modulo months must have same length
  The length of the current month for input Time and Time_list must be the same when using the modulo month option. The modulo month option is available but not supported.
ERROR in time_interp
  invalid value for argument modtime
  The optional argument modtime must have a value set by one of the public parameters: NONE, YEAR, MONTH, DAY. The MONTH and DAY options are available but not supported.
ERROR in time_interp
  period of list exceeds modulo period
  The difference between the last and first values in the input Time list/array exceeds the length of the modulo period.
ERROR in time_interp
  time before range of list or time after range of list
  The difference between the last and first values in the input These errors occur when you are not using a modulo axis and the input Time occurs before the first value in the Time list/array or after the last value in the Time list/array.
error during execution of module time_interp_mod
  input time list not ascending order
  The list of input time types must have ascending dates.
error during execution of module time_interp_mod
  modulo months must have same length
  The length of the current month for input Time and Time_list must be the same when using the modulo month option. The modulo month option is available but not supported.
error during execution of module time_interp_mod
  invalid value for argument modtime
  The optional argument modtime must have a value set by one of the public parameters: NONE, YEAR, MONTH, DAY. The MONTH and DAY options are available but not supported.
error during execution of module time_interp_mod
  period of list exceeds modulo period
  The difference between the last and first values in the input Time list/array exceeds the length of the modulo period.
error during execution of module time_interp_mod
  time before range of list or time after range of list
  These errors occur when you are not using a modulo axis and the input Time occurs before the first value in the Time list/array or after the last value in the Time list/array.

#### REFERENCES

None.

#### COMPILER SPECIFICS

None.

#### PRECOMPILER OPTIONS

None.

#### LOADER OPTIONS

None.

#### TEST PROGRAM

None.

#### KNOWN BUGS

None.

#### NOTES

For all routines in this module the calendar type in module time_manager must be set.
The following private parameters are set by this module:

               seconds per minute = 60
               minutes per hour   = 60
               hours   per day    = 24
               months  per year   = 12

#### FUTURE PLANS

None.

top