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