Time manipulation and other numerical routines. More...

Detailed Description

Time manipulation and other numerical routines.

This module implements various simple numerical algorithms, such as partial sorting, time manipulation or fraction-to-date conversions. It also contains two array-like classes that take datetime objects as indices.

Classes
class	partial_ordering
	Sorts a pre-determined list of objects, placing unknown items at a specified location. More...

class	TimeArray
	A time-indexed array that can only handle equally spaced times. More...

class	TimeContainer
	Abstract base class that maps from time to objects. More...

class	TimeMapping
	Maps from an ordered list of times to arbitrary data. More...

Functions
def	great_arc_dist (xlon1, ylat1, xlon2, ylat2)
	Great arc distance between two points on Earth. More...

def	fcst_hr_min (time, start)
	Return forecast time in hours and minutes. More...

def	randint_zeromean
	Generates "count" numbers uniformly distributed between -imax and imax, inclusive, with a mean of zero. More...

def	split_fraction (f)
	Splits a fraction into components. More...

def	within_dt_epsilon (time1, time2, epsilon)
	Returns True if time1 is within epsilon of time2, and False otherwise. More...

def	timedelta_epsilon
	Decides a reasonable epsilon for time equality comparisons. More...

def	to_fraction
	Converts an object or two to a fraction. More...

def	to_datetime_rel (d, rel)
	Converts objects to a datetime relative to another datetime. More...

def	to_datetime (d)
	Converts the argument to a datetime. More...

def	to_timedelta
	Converts an object to a datetime.timedelta. More...

def	minutes_seconds_rest (fraction)
	Splits the given fractions.Fraction of seconds into integer minutes, seconds and fractional remainder <=0. More...

def	nearest_datetime (start, target, timestep)
	Return the nearest datetime.datetime to a target. More...

def	is_at_timestep (start, target, timestep)
	Returns True if the target time lies exactly on a timestep, and False otherwise. More...

def	str_timedelta (dt)
	Converts a timedelta to a string. More...

Variables
list	__all__
	The symbols exported by "from hwrf.numerics import *". More...

Function Documentation

def hwrf.numerics.fcst_hr_min	(	time,
		start
	)

Return forecast time in hours and minutes.

Given a forecast datetime.datetime and an analysis datetime.datetime, this returns a tuple containing the forecast hour and minute, rounded to the nearest integer minute.

Parameters

time	forecast time as a datetime.datetime
start	analysis time as a datetime.datetime

Returns: a tuple (ihours,iminutes)

Definition at line 126 of file numerics.py.

Referenced by hwrf.config.ConfTimeFormatter.get_value().

def hwrf.numerics.great_arc_dist	(	xlon1,
		ylat1,
		xlon2,
		ylat2
	)

Great arc distance between two points on Earth.

Calculates the great arc distance in meters between two points using the Haversine method. Uses the local Earth radius at the latitude half-way between the two points.

Parameters

xlon1,ylat1	first point, degrees
xlon2,ylat2	second point, degrees

Returns: distance in meters

Definition at line 99 of file numerics.py.

def hwrf.numerics.is_at_timestep	(	start,
		target,
		timestep
	)

Returns True if the target time lies exactly on a timestep, and False otherwise.

Parameters

start	the fixed start time of allowed return values
target	the time desired
timestep	the times between allowed return values

Definition at line 454 of file numerics.py.

def hwrf.numerics.minutes_seconds_rest ( fraction )

Splits the given fractions.Fraction of seconds into integer minutes, seconds and fractional remainder <=0.

Parameters

fraction the fraction to convert, assumed to be in seconds

Returns: a tuple (minutes,seconds,rest) as integers

Definition at line 420 of file numerics.py.

def hwrf.numerics.nearest_datetime	(	start,
		target,
		timestep
	)

Return the nearest datetime.datetime to a target.

Given a start time, a target time and a timestep, determine the nearest time not earlier than the target that lies exactly on a timestep. Input start and target can be anything understood by to_datetime, and the timestep can be anything understood by to_fraction. Return value is a datetime.datetime object.

Parameters

start	the fixed start time of allowed return values
target	the time desired
timestep	the times between allowed return values

Definition at line 434 of file numerics.py.

def hwrf.numerics.randint_zeromean	(	count,
		imax,
		randomizer = `None`
	)

Generates "count" numbers uniformly distributed between -imax and imax, inclusive, with a mean of zero.

Parameters

count	number of numbers to return
imax	maximum value of any number
randomizer	the random module, or something that looks like it

Definition at line 146 of file numerics.py.

Referenced by hwrf.launcher.HWRFLauncher.gen_vitals().

def hwrf.numerics.split_fraction ( f )

Splits a fraction into components.

Splits a fraction.Fraction into integer, numerator and denominator parts. For example, split_fraction(Fraction(13,7)) will return (1,6,7) since 1+6/7=13/7.

Returns: a tuple (integer,numerator,denominator)

Definition at line 184 of file numerics.py.

Referenced by hwrf.numerics.str_timedelta().

def hwrf.numerics.str_timedelta ( dt )

Converts a timedelta to a string.

Converts dt to a string of the format "DD:HH:MM:SS+num/den"

DD - number of days
HH - number of hours
MM - minutes
SS - seconds
num/den - fractional part The to_fraction is used to get the fractional part.

Parameters

dt	anything convertible to a datetime.timedelta.

Definition at line 467 of file numerics.py.

def hwrf.numerics.timedelta_epsilon	(	times,
		rel = `None`,
		default = `None`,
		sort = `False`,
		numerator = `10`
	)

Decides a reasonable epsilon for time equality comparisons.

Given an iterable of datetime objects (or anything accepted by to_datetime_rel), computes the minimum time difference between any two adjacent times and divides it by "numerator" (default: 10). The "rel" argument is the relative time when calling to_datetime_rel. If unspecified, it will be the first time seen (in which case that time must be acceptable to to_datetime). The "default" is the return value when all elements in "times" are identical, or when there is only one element. If the default is unspecified and it is needed, then NoTimespan is raised. If sort is specified and True, then the times will be sorted before anything is done (it is False by default).

Parameters

times	a list of example times for comparison
rel	a reference time to which the times will be compared
default	if too few unique times are found, this is returned If that happens and no default is provided, an exception is raised
sort	if True, sort times
numerator	A measure of how close times should be. The least time difference will be at least numerator times the epsilon

Returns: an epsilon value

Definition at line 220 of file numerics.py.

def hwrf.numerics.to_datetime ( d )

Converts the argument to a datetime.

If the argument is already a datetime, it is simply returned. Otherwise it must be a string of the format YYYYMMDDHH, YYYYMMDDHHMM, or YYYY-MM-DD HH:MM:SS.

Parameters

d	the object being converted

Returns: the resulting datetime.datetime object

Definition at line 346 of file numerics.py.

Referenced by hwrf.ww3.WW3Init.__init__(), setup_hurricane.StormCurses.__init__(), hwrf.ensda.FromPriorCycle.__init__(), hwrf.numerics.TimeArray.__init__(), hwrf.numerics.TimeMapping.__init__(), hwrf.storminfo.find_tcvitals_for(), hwrf.numerics.TimeContainer.get(), hwrf.ensda.FromPriorCycle.get_product(), hwrf.storminfo.StormInfo.hwrf_domain_center(), hwrf.numerics.TimeMapping.index_of(), hwrf.numerics.is_at_timestep(), hwrf.launcher.multistorm_parse_args(), hwrf.numerics.nearest_datetime(), hwrf.prelaunch.prelaunch_ungrib(), setup_hurricane.StormCurses.setup(), hwrf.numerics.timedelta_epsilon(), hwrf.config.HWRFConfig.timestrinterp(), hwrf.numerics.to_datetime_rel(), and hwrf.numerics.within_dt_epsilon().

def hwrf.numerics.to_datetime_rel	(	d,
		rel
	)

Converts objects to a datetime relative to another datetime.

Given a datetime object "rel", converts "d" to a datetime. Object "d" can be anything accepted by to_datetime, or anything accepted as a single argument by to_timedelta. If it is a timedelta, it is added to "rel" to get the final time.

Parameters

d	the object being converted
rel	the datetime.datetime to which it is to be converted

Definition at line 319 of file numerics.py.

Referenced by hwrf.storminfo.StormInfo.__add__(), hwrf.numerics.TimeArray.__init__(), hwrf.launcher.HWRFLauncher.gen_vitals(), hwrf.numerics.TimeArray.index_of(), hwrf.hycom.HYCOMIniter.link_coupled_inputs(), hwrf.numerics.nearest_datetime(), setup_hurricane.StormCurses.setup(), hwrf.numerics.timedelta_epsilon(), and hwrf.config.HWRFConfig.timestrinterp().

def hwrf.numerics.to_fraction	(	a,
		b = `None`,
		negok = `False`
	)

Converts an object or two to a fraction.

This routine is a wrapper around fraction.Fraction() which accepts additional inputs. Fractions are needed to provide higher precision in time and resolution calculations (and also to match the WRF behavior). The arguments are the same as for the fractions.Fraction constructor, but additional calling conventions are accepted: a single float argument, a single datetime.timedelta object, or a string containing an integer and a fraction. If a float is provided, its denominator is restricted to be no more than 1000000. If the resulting fraction is not larger than 0, then InvalidTimestep is thrown unless negok=True.

Examples:

 to_fraction(0.855)            # 0.855 seconds
 to_fraction(33)               # 33 seconds
 to_fraction('12/5')           # 2.4 seconds
 to_fraction('7+1/2')          # 7.5 seconds
 to_fraction(0.0000001) # ERROR! Value of the float() is less
                        # than 1e-6
 to_fraction(1,10000000) # Valid as a fraction, even though value
                         # is less than 1e-6

Parameters

a,b	the objects to convert
negok	if True, negative numbers are okay.

Definition at line 269 of file numerics.py.

Referenced by hwrf.storminfo.StormInfo.__add__(), hwrf.numerics.TimeArray.__init__(), hwrf.numerics.TimeArray.index_of(), hwrf.numerics.is_at_timestep(), hwrf.numerics.minutes_seconds_rest(), hwrf.numerics.nearest_datetime(), hwrf.numerics.TimeContainer.neartime(), hwrf.launcher.HWRFLauncher.sanity_check_coupling(), hwrf.numerics.str_timedelta(), hwrf.numerics.timedelta_epsilon(), hwrf.numerics.to_timedelta(), and hwrf.numerics.within_dt_epsilon().

def hwrf.numerics.to_timedelta	(	a,
		b = `None`,
		negok = `True`
	)

Converts an object to a datetime.timedelta.

Returns a datetime.timedelta object. If "a" is a timedelta, then that value is returned. If "a" is a string of the format 08:13 or 08:13:12, optionally preceded by a "-" then it is interpreted as HH:MM or HH:MM:SS, respectively (where a "-" negates). Otherwise, the arguments are sent to the to_fraction() function, and the result is converted into a timedelta.

Parameters

a	object being converted
b	second object, if a time range is sent
negok	if True, negative timespans are allowed

Returns: a datetime.timedelta

Definition at line 371 of file numerics.py.

Referenced by hwrf.storminfo.StormInfo.__add__(), hwrf.numerics.TimeArray.__init__(), hwrf_expt.init_module(), hwrf.numerics.str_timedelta(), hwrf.numerics.timedelta_epsilon(), and hwrf.numerics.to_datetime_rel().

def hwrf.numerics.within_dt_epsilon	(	time1,
		time2,
		epsilon
	)

Returns True if time1 is within epsilon of time2, and False otherwise.

Parameters

time1,time2	the times being compared
epsilon	how close they need to be in order to be considered equal.

Returns: True if the times are within epsilon of each other, False if not

Definition at line 198 of file numerics.py.

Referenced by hwrf.prep.PrepHybrid.input_at(), and hwrf.prep.PrepHybrid.inputiter().

Variable Documentation

hwrf.numerics.__all__

Initial value:

 = [ 'partial_ordering','fcst_hr_min','split_fraction','to_fraction',
             'to_datetime_rel','to_datetime','to_timedelta','TimeArray',
             'minutes_seconds_rest','nearest_datetime','is_at_timestep',
             'great_arc_dist', 'timedelta_epsilon', 'TimeMapping',
             'within_dt_epsilon', 'randint_zeromean']

The symbols exported by "from hwrf.numerics import *".

Definition at line 10 of file numerics.py.

Detailed Description

Classes

Functions

Variables

Function Documentation

Variable Documentation