pygplates.GeoTimeInstant

class pygplates.GeoTimeInstant

Bases: Boost.Python.instance

Represents an instant in geological time. This class is able to represent:

time-instants with a specific time-position relative to the present-day
time-instants in the distant past (time-position of +infinity)
time-instants in the distant future (time-position of -infinity)

Note that positive values represent times in the past and negative values represent times in the future. This can be confusing at first, but the reason for this is geological times are represented by how far in the past to go back compared to present day.

All comparison operators (==, !=, <, <=, >, >=) are supported (but GeoTimeInstant is not hashable - cannot be used as a key in a dict). The comparisons are such that times further in the past are greater than more recent times. Note that this is the opposite how we normally think of time (where future time values are greater than past values).

So far this is the same as the native float type which can represent distant past as float('inf') and distant future as float('-inf') (and support all comparisons with +/- infinity). The advantage with GeoTimeInstant is comparisons use a numerical tolerance such that they compare equal when close enough to each other, and there are explicit methods to create and test distant past and distant future. Note that due to the numerical tolerance in comparisons, a GeoTimeInstant is not hashable and hence cannot be used as a key in a dict - however the float returned by get_value() can be.

Comparisons can also be made between a GeoTimeInstant and a float (or int, etc).

print 'Time instant is distant past: %s' % pygplates.GeoTimeInstant(float_time).is_distant_past()
time10Ma = pygplates.GeoTimeInstant(10)
time20Ma = pygplates.GeoTimeInstant(20)
# assert(time20Ma > time10Ma)
# assert(20 > time10Ma)
# assert(20 > time10Ma.get_value()
# assert(time20Ma > 10)
# assert(time20Ma.get_value() > 10)
# assert(time20Ma.get_value() > time10Ma.get_value())
# assert(time20Ma > time10Ma.get_value())
# assert(time20Ma.get_value() > time10Ma)
# assert(time20Ma < pygplates.GeoTimeInstant.create_distant_past())
# assert(time20Ma.get_value() < pygplates.GeoTimeInstant.create_distant_past())
# assert(20 < pygplates.GeoTimeInstant.create_distant_past())

__init__(time_value)

Create a GeoTimeInstant instance from time_value.

Parameters: time_value (float or GeoTimeInstant) – the time position - positive values represent times in the past

Note that if time_value is +infinity then is_distant_past() will subsequently return true. And if time_value is -infinity then is_distant_future() will subsequently return true.

time_instant = pygplates.GeoTimeInstant(time_value)

Methods

`__init__`(time_value)	Create a GeoTimeInstant instance from time_value.
`create_distant_future`()	[staticmethod] Create a GeoTimeInstant instance for the distant future.
`create_distant_past`()	[staticmethod] Create a GeoTimeInstant instance for the distant past.
`get_value`()	Access the floating-point representation of the time-position of this instance.
`is_distant_future`()	Returns `True` if this instance is a time-instant in the distant future.
`is_distant_past`()	Returns `True` if this instance is a time-instant in the distant past.
`is_real`()	Returns `True` if this instance is a time-instant whose time-position may be expressed as a real floating-point number.

static create_distant_future()

[staticmethod] Create a GeoTimeInstant instance for the distant future.

Return type: GeoTimeInstant

distant_future = pygplates.GeoTimeInstant.create_distant_future()

This is basically creating a time-instant which is infinitely far in the future.

Subsequent calls to get_value() will return a value of -infinity.

All distant-future time-instants will compare less than all non-distant-future time-instants.

static create_distant_past()

[staticmethod] Create a GeoTimeInstant instance for the distant past.

Return type: GeoTimeInstant

distant_past = pygplates.GeoTimeInstant.create_distant_past()

This is basically creating a time-instant which is infinitely far in the past.

Subsequent calls to get_value() will return a value of +infinity.

All distant-past time-instants will compare greater than all non-distant-past time-instants.

get_value()

Access the floating-point representation of the time-position of this instance. Units are in Ma (millions of year ago).

Return type: float

If is_distant_past() is True then get_value returns float('inf') and if is_distant_future() is True then get_value returns float('-inf').

Note that positive values represent times in the past and negative values represent times in the future.

is_distant_future()

Returns True if this instance is a time-instant in the distant future.

Return type: bool

is_distant_past()

Returns True if this instance is a time-instant in the distant past.

Return type: bool

is_real()

Returns True if this instance is a time-instant whose time-position may be expressed as a real floating-point number.

Return type: bool

If is_real() is True then both is_distant_past() and is_distant_future() will be False.