nexosim.time

Time-related types.

This module defines a custom duration type and timestamp. While superficially similar to the standard Python timedelta and datetime types, they do differ from the latter in a number of ways.

Unlike the standard datetime type, MonotonicTime is a monotonic timestamp that specifies a TAI point in time. It is represented as a signed number of seconds and a positive number of nanoseconds, relative to 1970-01-01 00:00:00 TAI.

Note that for most simulation models, the absolute time reference is irrelevant. If no model makes use of absolute time, the difference between UTC and TAI can be ignored and the simulation bench can be initialized with an arbitrary timestamp.

Duration and MonotonicTime objects can be directly deserialized/serialized from/to their counterparts from the Rust world. It must be noted, however, that unlike Rust's std::time::Duration type, Duration also supports negative durations.

Mixed addition and subtraction involving Duration and MonotonicTime types are supported. The Duration type also supports multiplication and division by a scalar.

Example usage

Basic usage:

from nexosim.time import MonotonicTime

# A timestamp dated 2009-02-13 23:31:30.987654321 TAI.
t0 = MonotonicTime(1_234_567_890, 987_654_321)

# The current TAI time.
t1 = MonotonicTime.now(leap_secs=37)

print(f"current TAI time: {t1}")
print(f"t1 - t0 = {t1 - t0}") # t1 - t0 is a `Duration`

Construction from time components and formatting:

from nexosim.time import Duration, MonotonicTime

# Set the time to 2222-11-11 12:34:56.789 TAI.
t = MonotonicTime.create(2222, 11, 11, 12, 34, 56, 789000000)

# Shift it back by 10 days and forth by 1ms.
shift = Duration.create(days=-10, milliseconds=1)
t += shift

print(t)         # prints '2222-11-01 12:34:56.79'
print(f"{t:.0}") # prints '2222-11-01 12:34:56'
print(f"{t:.6}") # prints '2222-11-01 12:34:56.790000'

Construction from Python datetime and timedelta objects:

from datetime import datetime, timedelta
from nexosim.time import Duration, MonotonicTime

# Set a naive date-time to 1987-06-05 04:32:10.123456.
dt = datetime(1987, 6, 5, 4, 32, 10, 123456)

# Interpret it as a TAI timestamp.
t = MonotonicTime.fromdatetime(dt)

print(t) # prints "1987-06-05 04:32:10.123456".

# Create a `Duration` from a `timedelta`.
delta = timedelta(hours=52, milliseconds=11)
duration = Duration.fromtimedelta(delta)

print(duration) # prints '2 days, 4:00:00.011'

Duration

A nanosecond-precision signed duration.

Attributes:

Name	Type	Description
secs	int	The largest second boundary that isn't greater than the duration. Always strictly negative for strictly negative durations.
nanos	int	The positive sub-second number of nanoseconds to be added to the number of seconds specified by secs to obtain the duration.

create(days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0, nanoseconds=0) classmethod

Creates a duration using one or several time units.

This is a convenience constructor which sums all parameters and normalizes the duration to a signed number of seconds and a positive number of nanoseconds.

All parameters are allowed to be negative and may have arbitrary magnitudes.

Parameters:

Name	Type	Description	Default
days	int	A number of days.	0
hours	int	A number of hours.	0
minutes	int	A number of minutes.	0
seconds	int	A number of seconds.	0
milliseconds	int	A number of milliseconds.	0
microseconds	int	A number of microseconds.	0
nanoseconds	int	A number of nanoseconds.	0

fromtimedelta(dt) classmethod

Creates a duration from a datetime.timedelta object

Parameters:

Name	Type	Description	Default
dt	timedelta	A time interval.	required

MonotonicTime

A nanosecond-precision monotonic clock timestamp.

A timestamp specifies a TAI point in time. It is represented as a signed number of seconds and a positive number of nanoseconds, counted with reference to 1970-01-01 00:00:00 TAI.

Attributes:

Name	Type	Description
secs	int	The number of whole seconds in the future (if positive) or in the past (if negative) of 1970-01-01 00:00:00 TAI.
nanos	int	The sub-second number of nanoseconds in the future of the point in time defined by secs.

create(year=1970, month=1, day=1, hour=0, minute=0, second=0, nanosecond=0, leap_secs=0) classmethod

Creates a timestamp from a date-time representation.

The first argument is the proleptic Gregorian year, which must be at least equal to 1. The month and day follow the usual calendar convention and start at 1.

If the date is provided as UTC rather than TAI, the number of leap seconds can be specified to allow conversion to TAI. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Parameters:

Name	Type	Description	Default
year	int	The year (1 ≤ year ≤ 9999).	1970
month	int	The month (1 ≤ month ≤ 12).	1
day	int	The day of the month (1 ≤ day ≤ 28/29/30/31).	1
hour	int	The hour (0 ≤ hour < 24).	0
minute	int	The minute (0 ≤ minute < 60).	0
second	int	The second (0 ≤ second < 60).	0
nanosecond	int	The nanosecond (0 ≤ nanosecond < 1'000'000'000).	0
leap_secs	int	Difference between TAI and UTC time in seconds applicable at the date represented by the timestamp.	0

Raises:

Type	Description
ValueError	An exception is thrown if one or several parameters are invalid or not supported.

fromdatetime(dt, leap_secs=0) classmethod

Creates a timestamp from a Python datetime object.

If the date-time is provided as UTC-based, timezone-aware object rather than a naive TAI date-time, the number of leap seconds can be specified to allow conversion to TAI. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Parameters:

Name	Type	Description	Default
dt	datetime	A date-time object, which may be specified as a TAI naive date-time (tzinfo=None) or as a timezone-aware date-time.	required
leap_secs	int	Difference between TAI and UTC time in seconds applicable at the date represented by the timestamp.	0

now(leap_secs=0) classmethod

Creates a timestamp corresponding to the current time.

Note that this method uses the system clock, which is based on UTC. The number of leap seconds can be specified to allow conversion to TAI. For reference, this offset has been +37s since 2017-01-01, a value which is to remain valid until at least 2024-12-28. See the official IERS bulletin C for leap second announcements or the IERS table for current and historical values.

Parameters:

Name	Type	Description	Default
leap_secs	int	Difference between TAI and UTC time in seconds applicable at the date represented by the timestamp.	0