astrix.time module¶

class Time(unix, backend=None)[source]¶

Bases: TimeLike

One or more time instances.

Represents time using seconds since Unix epoch (1970-01-01 00:00:00 UTC). Can handle single time instances or arrays of times with consistent backend support for JAX/NumPy compatibility.

Parameters:

unix (Array | list of float | float) – Time values in seconds since Unix epoch (1970-01-01 UTC)
backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

Examples

Single time instance:

>>> t = Time(1609459200.0)  # 2021-01-01 00:00:00 UTC

Multiple times:

>>> times = Time([1609459200.0, 1609545600.0])  # Jan 1-2, 2021

From datetime:

>>> from datetime import datetime, timezone
>>> dt = datetime(2021, 1, 1, tzinfo=timezone.utc)
>>> t = Time.from_datetime(dt)
>>> dt_list = [
...     datetime(2021, 1, 1, tzinfo=timezone.utc),
...     datetime(2021, 1, 2, tzinfo=timezone.utc),
... ]
>>> times = Time.from_datetime(dt_list)

Notes

All datetime objects must be timezone-aware to avoid ambiguity.

classmethod from_datetime(time, backend=None)[source]¶

Create a Time object from a single or list of datetime objects. Will not accept timezone-unaware datetime obejects due to ambiguity.

Return type:

Time

Parameters:

time (datetime | list[datetime])
backend (str | Any | None)

convert_to(backend)[source]¶

Convert the Time object to a different backend.

Return type:: Time
Parameters:: backend (str | Any | None)

copy()[source]¶

Return type:: Time

in_bounds(time)[source]¶

Check if the given time(s) are within the bounds of this Time object.

Return type:: bool
Parameters:: time (Time)

nearest_idx(time)[source]¶

Find the index of the nearest time in this Time object for each time in the input Time object.

Parameters:: time (Time) – Time object containing times to find nearest indices for.
Returns:: Array of indices corresponding to the nearest times in this Time object.
Return type:: Array

Examples

>>> from astrix.primitives import Time
>>> from datetime import datetime, timezone
>>> t1 = Time.from_datetime([
...     datetime(2021, 1, 1, tzinfo=timezone.utc),
...     datetime(2021, 1, 2, tzinfo=timezone.utc),
...     datetime(2021, 1, 3, tzinfo=timezone.utc)
... ])
>>> t2 = Time.from_datetime([
...     datetime(2021, 1, 1, 12, tzinfo=timezone.utc),
...     datetime(2021, 1, 2, 12, tzinfo=timezone.utc)
... ])
>>> idx = t1.nearest_idx(t2)
>>> idx.tolist()
[0, 1]

offset(offset)[source]¶

Return a new Time object with offset (seconds) added to all time values.

Return type:: Time
Parameters:: offset (float)

return_in_bounds(time)[source]¶

Return a new Time object containing only the times within the bounds of this Time object.

Return type:: Time
Parameters:: time (Time)

property backend: str¶: Get the name of the array backend in use (e.g., ‘numpy’, ‘jax.numpy’).

property datetime: list[datetime]¶

property duration: float | Any¶: Get the duration between the first and last time in seconds.

property end_sec: float | Any¶: Get the end time in seconds since epoch.

property is_increasing: bool¶: Check if the time values are strictly increasing.

property start_sec: float | Any¶: Get the start time in seconds since epoch.

property unix: Any¶: Get the time values in seconds since epoch.

class TimeGroup(times, backend=None)[source]¶

Bases: object

A group of TimeLike objects (Time, TimeInvariant, TimeGroup). Used to manage multiple time instances and determine overlapping time bounds.

Parameters:

times (list of TimeLike) – List of TimeLike objects (Time, TimeInvariant, TimeGroup)
backend (BackendArg, optional) – Array backend to use (numpy, jax, etc.). Defaults to numpy.

Examples

>>> t1 = Time.from_datetime(
...     [
...         datetime(2021, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
...         datetime(2021, 1, 1, 13, 0, 0, tzinfo=timezone.utc),
...     ]
... )
>>> t2 = Time.from_datetime(
...     [
...         datetime(2021, 1, 1, 12, 30, 0, tzinfo=timezone.utc),
...         datetime(2021, 1, 1, 14, 0, 0, tzinfo=timezone.utc),
...     ]
... )
>>> tg = TimeGroup([t1, t2])
>>> tg.duration  # Duration of overlap in seconds
1800.0

>>> overlap = tg.overlap_bounds  # Overlapping time range
>>> assert overlap[0].datetime[0] == datetime(
...     2021, 1, 1, 12, 30, 0, tzinfo=timezone.utc
... )
>>> assert overlap[1].datetime[0] == datetime(
...     2021, 1, 1, 13, 0, 0, tzinfo=timezone.utc
... )

>>> tg.in_bounds(
...     Time.from_datetime(datetime(2021, 1, 1, 12, 45, 0, tzinfo=timezone.utc))
... )
True

convert_to(backend)[source]¶

Convert the TimeGroup object to a different backend.

Return type:: TimeGroup
Parameters:: backend (str | Any | None)

in_bounds(time)[source]¶

Check if the given time(s) are within the overlap bounds of this TimeGroup.

Return type:: bool
Parameters:: time (Time)

property backend: str¶

property duration: float | Any¶: Get the duration of the overlap bounds in seconds.

property extreme_bounds: tuple[TimeLike, TimeLike]¶: Get the extreme bounds of the TimeGroup as Time objects.

property is_invariant: bool¶

property overlap_bounds: tuple[TimeLike, TimeLike]¶: Get the overlap bounds of the TimeGroup as Time objects.

property times: tuple[TimeLike, ...]¶

class TimeInvariant[source]¶

Bases: TimeLike

Class for static time-like objects (static Time). ‘in_bounds’ function is required for integration with other modules.

convert_to(backend)[source]¶

Return type:: TimeInvariant
Parameters:: backend (str | Any | None)

copy()[source]¶

Return type:: TimeInvariant

datetime()[source]¶

Return type:: list[str]

in_bounds(time)[source]¶

Return type:: bool
Parameters:: time (Time)

class TimeLike[source]¶

Bases: ABC

Abstract base class for time-like objects (Time, TimeSequence). ‘in_bounds’ function is required for integration with other modules.

abstractmethod convert_to(backend)[source]¶

Return type:: TimeLike
Parameters:: backend (str | Any | None)

abstractmethod copy()[source]¶

Return type:: TimeLike

abstractmethod in_bounds(time)[source]¶

Return type:: bool
Parameters:: time (Time)

property is_singular: bool¶: Check if the TimeLike object represents a single time instance. Override if not singular

time_linspace(t1, t2, num)[source]¶

Create a Time object with linearly spaced times between two Time objects. If t1 and t2 are non-singular, uses t1[0] and t2[-1].

Parameters:

t1 (Time) – Start time.
t2 (Time) – End time.
num (int) – Number of time points to generate.

Returns:

Time object with linearly spaced times.

Return type:

Time

Examples

>>> from astrix.primitives import Time
>>> from datetime import datetime, timezone
>>> t_start = Time.from_datetime(datetime(2021, 1, 1, tzinfo=timezone.utc))
>>> t_end = Time.from_datetime(datetime(2021, 1, 2, tzinfo=timezone.utc))
>>> t_lin = time_linspace(t_start, t_end, num=5)
>>> t_lin.datetime
[datetime.datetime(2021, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
 datetime.datetime(2021, 1, 1, 6, 0, tzinfo=datetime.timezone.utc),
 datetime.datetime(2021, 1, 1, 12, 0, tzinfo=datetime.timezone.utc),
 datetime.datetime(2021, 1, 1, 18, 0, tzinfo=datetime.timezone.utc),
 datetime.datetime(2021, 1, 2, 0, 0, tzinfo=datetime.timezone.utc)]