astra.jdutil module¶

Julian date ↔ UTC datetime conversions (stdlib only; avoids import cycles).

Public API¶

jd_utc_to_datetime / datetime_utc_to_jd — canonical UTC-aware implementations. jd_to_datetime / datetime_to_jd — short-form aliases (used by ocm.py etc.).

Timezone note¶

np.datetime64 has no concept of time-zones (it stores a UTC integer count). Constructing it from a timezone-aware datetime object emits:

UserWarning: no explicit representation of timezones available for np.datetime64

This is silenced by anchoring the J2000 reference on an ISO string (timezone- naive, implicitly UTC) so numpy never needs to round-trip through a tzinfo object. Timezone-awareness is re-attached explicitly on the Python side before returning.

astra.jdutil.jd_utc_to_datetime(jd)[source]¶

Convert UTC Julian Date(s) to timezone-aware UTC datetime(s).

Parameters:: jd – Julian Date scalar or numpy array.
Returns:: timezone-aware datetime (UTC). Array: object-dtype numpy array of timezone-aware datetime values.
Return type:: Scalar

Example:

from astra.jdutil import jd_utc_to_datetime
dt = jd_utc_to_datetime(2451545.0)
# -> datetime(2000, 1, 1, 12, 0, tzinfo=timezone.utc)

astra.jdutil.datetime_utc_to_jd(dt)[source]¶

Convert UTC-aware datetime(s) to Julian Date.

Parameters:: dt – Single timezone-aware datetime, or numpy array of datetimes. Naive datetimes are assumed to be UTC.
Returns:: Julian Date as float (scalar) or np.ndarray (array input).

Example:

from astra.jdutil import datetime_utc_to_jd
from datetime import datetime, timezone
jd = datetime_utc_to_jd(datetime(2000, 1, 1, 12, tzinfo=timezone.utc))
# -> 2451545.0

astra.jdutil.jd_to_datetime(jd)[source]¶

Alias for jd_utc_to_datetime — convert UTC Julian Date(s) to datetime(s).

Parameters:: jd – Julian Date scalar or array.
Returns:: Timezone-aware UTC datetime, or object array of datetimes.

Example:

from astra.jdutil import jd_to_datetime
dt = jd_to_datetime(2451545.0)   # 2000-01-01 12:00:00+00:00

astra.jdutil.datetime_to_jd(dt)[source]¶

Alias for datetime_utc_to_jd — convert UTC datetime(s) to Julian Date.

Parameters:: dt – Timezone-aware datetime, or numpy array of datetimes. Naive datetimes are assumed UTC.
Returns:: Julian Date float, or numpy array of floats.

Example:

from astra.jdutil import datetime_to_jd
from datetime import datetime, timezone
jd = datetime_to_jd(datetime(2000, 1, 1, 12, tzinfo=timezone.utc))
# -> 2451545.0