space::time

Reform-aware, not proleptic. Dates on or after the Gregorian reform use the Gregorian rule; earlier dates use the JULIAN rule, which is what they were actually recorded in. This differs deliberately from civil.hpp, which is proleptic Gregorian throughout because that is what the CDF format specifies — the two conventions disagree by ten days at the reform and by a growing amount before it, so they are separate functions rather than one with a flag.

Which convention a caller wants depends on what the date MEANS: a CDF timestamp is proleptic by definition, whereas a historical observation is in the calendar its observer used. Geomagnetic work reaches back to the 19th century and IGRF to 1900, both comfortably post-reform, so in practice the two agree everywhere this module is used — but agreeing by accident is not the same as agreeing by construction, and a silent ten-day error is exactly the kind that survives review.

Integer arithmetic throughout (Fliegel & Van Flandern 1968 for the Gregorian branch), so there is no floating-point intermediate and no rounding, valid into negative years under astronomical numbering: JDN 0 is -4712-01-01 in the Julian calendar.

yyyy.0 is January 1 at 00:00 UT and the year's own length is the denominator, so the fraction is the elapsed portion of that year: a mid-year instant is .5 in a leap year and in a common year alike. This is the form IGRF coefficient interpolation consumes.

Everything above the final division is integer, so the only rounding in the whole routine is the one unavoidable division — and when the fraction is exactly representable the result is exact. decimal_year(2000, 7, 2, 0, 0, 0) is 2000.5 bit-for-bit, because 183 of 366 days is one half.

The fraction is converted to an integer count of microseconds of year and then snapped to the millisecond before anything is split off it — see detail::decimal_year_resolution_us for the derivation. That snap is the whole point of this routine: a decimal year near 2000 resolves to only about 7 microseconds, so a whole hour recovered from one lands a few microseconds short and a plain truncation reports the previous second. Measured against the shipped IRBEM library, that defect fires on roughly one round trip in six across a sweep of the year 2000; this routine returns the instant it was given, exactly, for every input decimal_year can produce.

Exists because a .purr caller cannot write a C++ aggregate initializer; from C++ prefer CivilDate{y, m, d} directly. No validation is performed — see is_valid_civil().

import io
import space.time as st

let d = st.civil_date(2026, 8, 28)
io.print(d.year, d.month, d.day)   # 2026 8 28

Howard Hinnant's days_from_civil, which is exact for every year representable in int and is the inverse of civil_from_days(). Shifting the year to start in March is what makes the leap day fall at the end of the year, so no special case for February is needed.

import io
import space.time as st

io.print(st.days_from_civil(1970, 1, 1))   # 0
io.print(st.days_from_civil(2000, 1, 1))   # 10957 — the J2000 day

The exact inverse of days_from_civil() over the whole representable range.

import io
import space.time as st

let d = st.civil_from_days(10957)
io.print(d.year, d.month, d.day)   # 2000 1 1

A literal transcription of the _JulianDay formula in NASA's CDF distribution, truncating integer division and all. It is here so our CDF epoch conversions can be shown to agree with NASA's rather than merely be believed to: the unit tests assert this equals days_from_civil(...) + 2440588 for every day in the TT2000 range, which retires the whole class of off-by-one calendar bugs in one loop.

Prefer days_from_civil() for new code. This exists for provenance, not for use.

import io
import space.time as st

# J2000: 2000-01-01 has Julian Day 2451545 at noon.
io.print(st.nasa_julian_day_at_noon(2000, 1, 1))   # 2451545

Feeds space.cdf epoch variables directly. CDF_TT2000 (ns since J2000 with leap seconds) needs a leap-second table and lands with space.cdf — see the cdf roadmap.

import io
import space.time as st

# J2000 as a CDF_EPOCH — ready to write into a CDF epoch variable.
io.print(st.unix_to_cdf_epoch(946728000.0))        # 63113947200000.0

It defaults to false; when cheatah::datetime defines its broken-down datetime type, this is specialized to true for it (here or there), which lights up DatetimeScalar / DatetimeArray and the datetime overloads — without this header taking a dependency on that type today.