Time API

TAIView(jd1, jd2, time)

Bases: TimeView

TAI view of a :class:Time object.

TAI is a continuous atomic timescale. In DiffOrb it mainly serves as the intermediate timescale between UTC and TT.

TDBView(jd1, jd2, time)

Bases: TimeView

TDB view of a :class:Time object.

TDB is the barycentric relativistic timescale used for solar-system dynamics and ephemeris access.

TTView(jd1, jd2, time)

Bases: TimeView

TT view of a :class:Time object.

TT is the proper time of an Earth-based observer and is directly related to the atomic timescale TAI. In DiffOrb it is the bridge between Earth-rotation timescales such as UTC and UT1, and the dynamical timescale TDB.

Time(tt_jd1, tt_jd2, *, eop, gregorian_start=GREGORIAN_START_JD)

Bases: BatchableObject

Class for time representations.

This class stores each epoch internally as a normalized TT epoch. To preserve precision in time arithmetic and time-scale conversion, the internal TT epoch is stored as a split Julian date, with the large Julian-day part and the small fractional part kept separately.

Parameters:

Name	Type	Description	Default
_tt_jd1	Float[ArrayLike, ...]	Large component of the Julian date in TT.	required
_tt_jd2	Float[ArrayLike, ...]	Small remainder component of the Julian date in TT.	required
gregorian_start	Float[ArrayLike, '']	Julian date at which computed calendar fields switch from the Julian calendar to the Gregorian calendar.	GREGORIAN_START_JD

Initialize a time container from a TT split Julian date.

shape property

Return the broadcast batch shape carried by the time object.

tt property

View the stored epoch in TT.

TT is the proper time of an Earth-based observer and is directly related to the atomic timescale TAI. In DiffOrb it is the bridge between Earth-rotation timescales such as UTC and UT1, and the dynamical timescale TDB.

tai property

View the stored epoch in TAI.

TAI is a continuous atomic timescale. In DiffOrb it mainly serves as the intermediate timescale between UTC and TT.

ut1 property

View the stored epoch in UT1.

UT1 is the Earth-rotation timescale that follows the actual rotation angle of the Earth.

utc property

View the stored epoch in UTC.

DiffOrb only defines UTC for epochs on and after 1962-01-01. Earlier epochs should use UT1 instead. Mixed batches that cross the 1962 boundary should use :class:UTView which could be accessed by .ut property method.

ut property

View the stored epoch in mixed UT.

It represents UT1 before 1962-01-01 and UTC on and after 1962-01-01.

xpole property

Polar-motion coordinate xp from the Earth Orientation Parameter (EOP) file, in radians.

Notes

For epochs before the covered EOP range, xpole is zero. For future epochs beyond the EOP-file coverage, xpole stays at the final predicted value.

ypole property

Polar-motion coordinate yp from the Earth Orientation Parameter (EOP) file, in radians.

Notes

For epochs before the covered EOP range, ypole is zero. For future epochs beyond the EOP-file coverage, ypole stays at the final predicted value.

cor_delta_longitude property

Return the additive dPsi correction to model nutation in longitude from the Earth Orientation Parameter (EOP) file, in radians.

Notes

For epochs before the covered EOP range, cor_delta_longitude is zero. For future epochs beyond the EOP-file coverage, cor_delta_longitude stays at the final predicted value.

cor_delta_obliquity property

Return the additive dEps correction to model nutation in obliquity from the Earth Orientation Parameter (EOP) file, in radians.

Notes

For epochs before the covered EOP range, cor_delta_obliquity is zero. For future epochs beyond the EOP-file coverage, cor_delta_obliquity stays at the final predicted value.

precession_bias_matrix property

Return the unified precession-bias rotation matrix from GCRS to the mean equator and equinox of date for equinox-based transformation.

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the GCRS to the mean equator and equinox of date.

Notes

The IAU precession-bias model is used from 1799-01-01 through 2202-01-01, and the Vondrak et al. (2011) long-term precession model is used outside that interval.

References

1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq. 6.26.
2. Vondrák, J., et al. (2011). New precession expressions, valid for long time intervals. Appendix A.4.

nutation_matrix property

Return the unified nutation rotation matrix from the mean equator and equinox of date to the true equator and equinox of date for equinox-based transformation.

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the mean equator and equinox of date to the true equator and equinox of date.

Notes

Within 1799-01-01 to 2202-01-01, it returns the IAU 2000A nutation matrix with the implemented IAU 2006-compatible adjustments. Outside that interval it only returns the identity matrix.

References

Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq. 6.39-6.41.

polar_motion_matrix property

Return the IAU polar-motion rotation matrix from the Terrestrial Intermediate Reference System (TIRS) to ITRS.

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the TIRS to ITRS.

References

1. Kaplan, G. H. (2005). The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models. Eq.7.77.

inversed_polar_motion_matrix property

Return the inverse IAU polar-motion rotation matrix from ITRS to the Terrestrial Intermediate Reference System (TIRS).

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the ITRS to TIRS.

References

1. Kaplan, G. H. (2005). The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models. Eq.7.138.

ERA property

Return the Earth rotation angle in radians.

References

1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq.6.59.

gcrs_to_cirs_matrix property

Return the rotation matrix from GCRS to the Celestial Intermediate Reference System (CIRS) for CIO-based transformation.

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the GCRS to the CIRS.

Notes

Within 1799-01-01 to 2202-01-01, it uses the IAU 2006/2000A CIP and CIO models. Outside that interval, it switches to the Vondrak et al. (2011) long-term model.

References

1. Urban, S. E., & Seidelmann, P. K. (2012). Explanatory Supplement to the Astronomical Almanac. Eq.7.73, 7.75.

cirs_to_gcrs_matrix property

Return the rotation matrix from the Celestial Intermediate Reference System (CIRS) to GCRS for CIO-based transformation.

Returns:

Type	Description
Float[Array, '... 3 3']	Orthogonal (..., 3 x 3) rotation matrix from the CIRS to the GCRS.

Notes

Within 1799-01-01 to 2202-01-01, it uses the IAU 2006/2000A CIP and CIO models. Outside that interval, it switches to the Vondrak et al. (2011) long-term model.

References

1. Kaplan, G. H. (2005). The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models. Eq.6.18.

__add__(other)

Shift the epoch forward by a uniform time interval.

Parameters:

Name	Type	Description	Default
other	TimeDelta or ArrayLike	Interval added to the epoch. Numeric inputs are interpreted as day offsets and are internally converted to :class:difforb.core.time.timedelta.TimeDelta.	required

Returns:

Type	Description
Time	Time container shifted by the requested uniform interval.

Notes

The addition is performed on the internally stored TT split Julian date. Numeric inputs therefore represent uniform day offsets, with 1 day = 86400 SI seconds.

__radd__(other)

Shift the epoch forward when the numeric day offset appears on the left.

__sub__(other)

Subtract an epoch or a uniform time interval.

Parameters:

Name	Type	Description	Default
other	Time, TimeDelta, or ArrayLike	Operand subtracted from the epoch. If other is a :class:Time, the result is a :class:difforb.core.time.timedelta.TimeDelta. Numeric inputs are interpreted as day offsets and are internally converted to :class:difforb.core.time.timedelta.TimeDelta.	required

Returns:

Type	Description
Time or TimeDelta	Shifted epoch when subtracting a uniform interval, or a uniform interval when subtracting another epoch.

Notes

The subtraction is performed on the internally stored TT split Julian date. Numeric inputs therefore represent uniform day offsets, with 1 day = 86400 SI seconds.

__eq__(other)

Compare whether two time containers represent the same epoch.

__ne__(other)

Compare whether two time containers represent different epochs.

__lt__(other)

Compare whether this epoch is earlier than another epoch.

__le__(other)

Compare whether this epoch is earlier than or equal to another epoch.

__gt__(other)

Compare whether this epoch is later than another epoch.

__ge__(other)

Compare whether this epoch is later than or equal to another epoch.

__repr__()

Return a compact summary of the internally stored TT epoch.

from_tt_jd(tt_jd1, tt_jd2, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TT split Julian date.

from_tt_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TT calendar date.

from_tai_jd(tai_jd1, tai_jd2, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TAI split Julian date.

from_tai_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TAI calendar date.

from_utc_jd(utc_jd1, utc_jd2, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a UTC split quasi-Julian date.

from_utc_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a UTC calendar date.

from_ut_jd(ut_jd1, ut_jd2, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a mixed UT split Julian date.

Parameters:

Name	Type	Description	Default
ut_jd1	Float[ArrayLike, ...]	Split Julian date of the mixed UT epoch. Epochs before 1962-01-01 are interpreted as UT1. Epochs on and after 1962-01-01 are interpreted as UTC quasi-Julian dates.	required
ut_jd2	Float[ArrayLike, ...]	Split Julian date of the mixed UT epoch. Epochs before 1962-01-01 are interpreted as UT1. Epochs on and after 1962-01-01 are interpreted as UTC quasi-Julian dates.	required
eop	EarthOrientationData	Earth orientation data used when the input epoch is interpreted as UT1.	None
gregorian_start	Float[ArrayLike, '']	Julian date at which the calendar fields switch from the Julian calendar to the Gregorian calendar.	GREGORIAN_START_JD

Returns:

Type	Description
Time	Time container that stores the matching epoch internally in TT.

Notes

Mixed UT follows the legacy DiffOrb convention: it represents UT1 before 1962-01-01 and UTC on and after 1962-01-01. The boundary test uses the mixed-UT Julian date itself and is independent of the coverage range of the loaded EOP file.

from_ut_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a mixed UT calendar date.

Parameters:

Name	Type	Description	Default
year	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
month	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
day	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
hour	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
min	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
sec	Float[ArrayLike, ...]	Calendar fields of the mixed UT epoch. Inputs that overflow one nominal day are allowed. Epochs before 1962-01-01 are interpreted as UT1 calendar dates. Epochs on and after 1962-01-01 are interpreted as UTC calendar dates.	required
eop	EarthOrientationData	Earth orientation data used when the input epoch is interpreted as UT1.	None
gregorian_start	Float[ArrayLike, '']	Julian date at which the calendar fields switch from the Julian calendar to the Gregorian calendar.	GREGORIAN_START_JD

Returns:

Type	Description
Time	Time container that stores the matching epoch internally in TT.

Notes

The 1962-01-01 split is a civil-calendar convention, so the branch selection is evaluated with the Gregorian calendar regardless of gregorian_start. Once the branch is chosen, the UT1 path uses :func:difforb.core.time.utils.julian_date with the requested gregorian_start, while the UTC path uses :func:difforb.core.time.utc.julian_date_for_utc.

from_ut1_jd(ut1_jd1, ut1_jd2, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a UT1 split Julian date.

from_ut1_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a UT1 calendar date.

from_tdb_jd(tdb_jd1, tdb_jd2, eop=None, location=None, grid=False, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TDB split Julian date.

Parameters:

Name	Type	Description	Default
tdb_jd1	Float[ArrayLike, ...]	Split Julian date of the TDB epoch.	required
tdb_jd2	Float[ArrayLike, ...]	Split Julian date of the TDB epoch.	required
eop	EarthOrientationData	Earth orientation data used during the TDB to TT inversion.	None
location	``ITRS`` or None	Observer location used by the topocentric TDB - TT correction. If omitted, use the geocenter.	None
grid	bool	If False, pair location and time inputs point-wise using normal broadcasting. If True, use the Cartesian product of the location and time batches, following :func:difforb.core.time.tdb.tdb_to_tt.	False
gregorian_start	Float[ArrayLike, '']	Julian date at which derived calendar fields switch from the Julian calendar to the Gregorian calendar.	GREGORIAN_START_JD

from_tdb_date(year, month, day, hour=0.0, min=0.0, sec=0.0, eop=None, location=None, grid=False, gregorian_start=GREGORIAN_START_JD) classmethod

Build a time container from a TDB calendar date.

Parameters:

Name	Type	Description	Default
year	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
month	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
day	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
hour	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
min	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
sec	Float[ArrayLike, ...]	Calendar fields of the TDB epoch.	required
eop	EarthOrientationData	Earth orientation data used during the TDB to TT inversion.	None
location	``ITRS`` or None	Observer location used by the topocentric TDB - TT correction. If omitted, use the geocenter.	None
grid	bool	If False, pair location and time inputs point-wise using normal broadcasting. If True, use the Cartesian product of the location and time batches, following :func:difforb.core.time.tdb.tdb_to_tt.	False
gregorian_start	Float[ArrayLike, '']	Julian date at which the calendar fields switch from the Julian calendar to the Gregorian calendar.	GREGORIAN_START_JD

tdb(location=None, grid=False)

View the stored epoch in TDB.

TDB is the barycentric relativistic timescale used for solar-system dynamics and ephemeris access.

Parameters:

Name	Type	Description	Default
location	``ITRS`` or None	Observer location used by the topocentric TDB - TT correction. If omitted, use the geocenter.	None
grid	bool	If False, pair location and time inputs point-wise using normal broadcasting. If True, use the Cartesian product of the location and time batches, following :func:difforb.core.time.tdb.tt_to_tdb.	False

TimeDelta(jd1, jd2=0.0)

Bases: BatchableObject

Split-Julian-date container for uniform time intervals.

TimeDelta represents a uniform duration rather than a civil calendar offset. The stored value is jd1 + jd2 in day units, where 1 day is exactly 86400 SI seconds.

Parameters:

Name	Type	Description	Default
jd1	Float[ArrayLike, ...]	Large component of the split day interval.	required
jd2	Float[ArrayLike, ...]	Small remainder component of the split day interval.	0.0

Initialize a time-interval container from a split day interval.

shape property

Return the broadcast batch shape carried by the interval.

jd1 property

Return the large component of the split day interval.

jd2 property

Return the small remainder component of the split day interval.

jd property

Return the total interval in day units.

days property

Return the total interval in day units.

seconds property

Return the total interval in SI seconds.

from_days(days) classmethod

Build a time interval from durations in day units.

Parameters:

Name	Type	Description	Default
days	Float[ArrayLike, ...]	Interval length in day units.	required

Returns:

Type	Description
TimeDelta	Time interval that represents the requested duration.

from_seconds(seconds) classmethod

Build a time interval from durations in SI seconds.

Parameters:

Name	Type	Description	Default
seconds	Float[ArrayLike, ...]	Interval length in SI seconds.	required

Returns:

Type	Description
TimeDelta	Time interval that represents the requested duration.

__add__(other)

Add two time intervals.

__sub__(other)

Subtract one time interval from another.

__neg__()

Negate the time interval.

TimeView(jd1, jd2, time)

Bases: BatchableObject

Read-only time-scale view built from a :class:Time object.

Each view stores one split Julian date pair in its own timescale and keeps a pointer to the parent :class:Time object for shared configuration such as EOP and the Gregorian switch epoch.

Initialize a time-scale view.

jd property

Return the full Julian date in this timescale.

ymdhms property

Return calendar fields computed from the split Julian date.

year property

Return the calendar year computed from the stored epoch.

month property

Return the calendar month computed from the stored epoch.

day property

Return the calendar day-of-month computed from the stored epoch.

hour property

Return the hour-of-day computed from the stored epoch.

min property

Return the minute-of-hour computed from the stored epoch.

sec property

Return the second-of-minute computed from the stored epoch.

iso_string property

Return the default ISO-like timestamp view for display.

Returns:

Type	Description
str or list[str]	Scalar strings for scalar epochs, or nested lists of strings that match the batch shape of the time object.

Notes

This property is equivalent to format_string("{YYYY}-{MM}-{DD} {hh}:{mm}:{ss.3}"). The strings are built from calendar fields computed from the stored split Julian date and therefore preserve the configured hybrid Julian/Gregorian convention.

shape property

Return the broadcast batch shape carried by the time object.

format_string(template=_DEFAULT_STRING_TEMPLATE)

Format epochs from calendar fields derived from the stored split Julian date.

Parameters:

Name	Type	Description	Default
template	str	Output template. Supported placeholders are: {YYYY}: 4-digit year. Pad with leading zeros if needed. {Y}: year without zero padding. {MM}: 2-digit month. Pad with a leading zero if needed. {M}: month without zero padding. {DD}: 2-digit day of month. Pad with a leading zero if needed. {D}: day of month without zero padding. {hh}: 2-digit hour. Pad with a leading zero if needed. {h}: hour without zero padding. {mm}: 2-digit minute. Pad with a leading zero if needed. {m}: minute without zero padding. {ss}: seconds with a 2-digit integer part. Pad with a leading zero if needed. {s}: seconds without zero padding in the integer part. {ss.N}: seconds with fixed fractional precision N >= 1 and a 2-digit integer part. Pad the integer part with a leading zero if needed. {s.N}: seconds with fixed fractional precision N >= 1 and no zero padding in the integer part.	"{YYYY}-{MM}-{DD} {hh}:{mm}:{ss.3}"

Returns:

Type	Description
str or list[str]	Scalar strings for scalar epochs, or nested lists of strings that match the batch shape of the time object.

Raises:

Type	Description
ValueError	If template contains unmatched braces, unknown placeholders, or malformed {ss.N} fields.

Notes

Formatting computes the calendar fields once from the stored split Julian date. This preserves the hybrid Julian/Gregorian calendar convention associated with gregorian_start. Fractional seconds are truncated rather than rounded.

UT1View(jd1, jd2, time)

Bases: TimeView

UT1 view of a :class:Time object.

UT1 is the Earth-rotation timescale that follows the actual rotation angle of the Earth.

UTCView(jd1, jd2, time)

Bases: TimeView

UTC view of a :class:Time object.

DiffOrb only defines UTC for epochs on and after 1962-01-01. Earlier epochs should use UT1 instead. Mixed batches that cross the 1962 boundary should use :class:UTView.

UTView(jd1, jd2, time)

Bases: TimeView

Mixed UT view of a :class:Time object.

Mixed UT represents UT1 before 1962-01-01 and UTC on and after 1962-01-01.