Foreground docs explaining B.C. versus negative years

[reza-ghazi]

from skyfield.api import load, GREGORIAN_START
ts = load.timescale()
ts.julian_calendar_cutoff = GREGORIAN_START
t = ts.utc(-7450, 2, 24, 11, 59, 17.8148)
print(f'TDB Julian date {t.tdb:.10f}')
print(f'calendar date: {ts.tdb_jd(-1000000).utc_jpl()}')
print(f'calendar date: {ts.tdb_jd(-1000000).utc}')

Result:

TDB Julian date -1000000.0000000000
calendar date: B.C. 7451-Feb-24 11:59:17.8148 UTC
calendar date: CalendarTuple(year=-7450, month=2, day=24, hour=11, minute=59, second=17.814798951707594)

Why do utc_jpl() and utc show different years for negative years? It seems utc_jpl handles the year right before year 1 as year -1, but utc takes it as year 0.

Isn't it better to make both the same so that they handle the year before year 1 as year -1 and not 0?

[brandon-rhodes]

The Skyfield documentation explains that here:

https://rhodesmill.org/skyfield/time.html#uniform-time-scales-tai-tt-and-tdb

Since it's hard to discover that bit of explanation, I'll plan to turn it into its own little section, and maybe move it up next to the "Ancient and modern dates" section nearer to the top so it's easier to find.

[reza-ghazi]

So, you mean that intentionally you kept utc_jpl to handle calendrical logic and utc to take as the arithmetical year counter.

In other words:

Year 0 (UTC) == Year 1 BC (UTC_JPL)

[brandon-rhodes]

I would put it this way — and will try putting language like this into the documentation:

Python integers are positive or negative, not AD or BC; there is no way to return a Python integer and have it know its value is 4 BC. Instead, -3 must be returned, because Python integers don't have a BC flag.

If the incorrect value -4 was returned when what's really meant is 4 BC, then math would break: the user would ask the question ‘how many years passed between 4 BC and AD 4?’ and instead of getting the correct response 7, they would subtract 4 - -4 and get the value 8.

It is not Skyfield's decision to represent years this way, but it's the astronomy community's decision about how to represent years when using the integer number line:

https://en.wikipedia.org/wiki/Astronomical_year_numbering

Let's leave this issue open until I've updated all documentation that returns integer years, so that it's mentioned that negative years don't mean BC!