Julian date conversions
Project description
juliandate
Simple conversions between Julian Dates and Julian/Gregorian calendar dates, supporting ancient dates (BCE)
Installation
pip install juliandate
Usage
Converting from Julian Date to Gregorian or Julian Calendar Date
A Julian Date such as 2440423.345486
indicates the number of days
(and fractional part) since noon January 1, 4713 BCE (Julian) or
November 24, 4714 BCE (Gregorian), a system proposed by Joseph
Scaliger
in 1583. 2440423
is the number of full days, and the fractional
part, 0.345486
indicates that a little more than a third of a day
has passed (since noon).
To convert this to a Gregorian calendar date:
>>> import juliandate as jd
>>> jd.to_gregorian(2440423.345139)
(1969, 7, 20, 20, 17, 0, 9609)
The return value is tuple consisting of the year, month, day, hour (in
24-hour format) minutes, seconds, and microseconds All are integers
and the last value is rounded to the nearest microsecond. This value,
(1969, 7, 20, 20, 17, 0, 9609)
, means July 20, 1969 at 20:17 or 8:17
PM (when Apollo 11 touched down on the moon). There is some
imprecision in the seconds due to floating-point division.
For ancient dates, conversions to the Julian calendar (and prior to 8 CE the Proleptic Julian Calendar) are supported.
>>> jd.to_julian(1705426)
(-43, 3, 15, 12, 0, 0, 0)
The negative year indicates BCE. 1 BCE is 0, so -43 means 44 BCE, and this value is March 15, 44 BCE (the Ides of March)
Note that since there is no fractional part of a day in 1705426
,
this comes out to noon, the start of the Julian Day. If we add half a
day or more, we will be into the next calendar day (March 16):
>>> jd.to_julian(1705426.5)
(-43, 3, 16, 0, 0, 0.0)
Conversions to the Proleptic Gregorian Calendar work as well. The Julian calendar date March 15, 44 BCE corresponds to a Gregorian Calendar date of March 13:
>>> jd.to_gregorian(1705426)
(-43, 3, 13, 12, 0, 0)
Converting from Gregorian or Julian Calendar Date to Julian Date
The reverse functions are:
>>> jd.from_gregorian(1969, 7, 20, 20, 17, 0, 0)
2440423.345138889
>>> jd.from_julian(-43, 3, 15, 0, 0, 0, 0)
1705425.5
Hours, minutes, seconds, and microseconds are optional so that latter could be:
>>> jd.from_julian(-43, 3, 15)
1705425.5
The "Astronomical" Day
Julian dates begin at noon, the start of the astronomical day. This can lead to some confusion since a calendar day, such as March 15 44 BCE, runs from 1705425.5 (inclusive) to 1705426.5 (exclusive).
# Midnight
>>> jd.to_julian(1705425.5)
(-43, 3, 15, 0, 0, 0, 0)
# 6 AM
>>> jd.to_julian(1705425.75)
(-43, 3, 15, 6, 0, 0, 0)
# Noon
>>> jd.to_julian(1705426)
(-43, 3, 15, 12, 0, 0, 0)
# 9 PM
>>> jd.to_julian(1705426.25)
(-43, 3, 15, 18, 0, 0, 0)
# Midnight, next calendar day
>>> jd.to_julian(1705426.5)
(-43, 3, 16, 0, 0, 0, 0)
If all you care about is the calendar day, add 0.5 to the Julian Date and take the integral part. This will return noon of the calendar day. For example:
# 6 AM
>>> jd.to_julian(int(1705425.75 + 0.5))
(-43, 3, 15, 12, 0, 0)
# Noon
>>> jd.to_julian(int(1705426 + 0.5))
(-43, 3, 15, 12, 0, 0)
# 9 PM
>>> jd.to_julian(int(1705426.25 + 0.5))
(-43, 3, 15, 12, 0, 0)
No datetime
Objects
juliandate
does not use Python datetime
objects because these do
not support dates before 1 CE. Any date that can be represented as a
Python datetime
can easily be converted:
>>> import juliandate as jd
>>> from datetime import datetime
>>> datetime(*jd.to_gregorian(2440423.345139))
datetime.datetime(1969, 7, 20, 20, 17, 0, 9609)
Imprecision and Domain
As noted above, floating-point math causes some imprecision in the seconds and microseconds. This is unavoidable since 24ths and 60ths don't divide equally. This round-trip, for instance, ends up being off by 7 microseconds. Take care if this is important.
>>> jd.to_gregorian(jd.from_gregorian(1969, 7, 20, 20, 17))
(1969, 7, 20, 20, 16, 59, 999993)
You can check juliandate
's calculations against the US Naval
Observeratory's Julian Date
Converter.
The conversion formulas used by juliandate
are valid only for JDN ≥ 0. That is, juliandate
calculations cannot be considered correct for dates before Julian January 1, 4713 BCE = Gregorian November 24, 4714 BCE.
Command Line Script
juliandate
comes with a command-line script jd
for converting Juliand Days
$ jd 1705426.25
-43, 3, 13, 18, 0, 0, 0
Use jd -h
for more usage details.
Sources
The conversion formulas are taken from pages 604 and 606 of:
Seidelmann, P.K. 2006 Explanatory Supplement to the Astronomical Almanac: A Revision to the Explanatory Supplement to the Astronomical Ephemeris and the American Ephemeris and Nautical Almanac. Sausalito, University Science Books.
and pages 617–619 of:
Urban, Sean E., and P. Kenneth Seidelmann, eds. Explanatory Supplement to the Astronomical Almanac. 3. ed. Mill Valley, Calif: University Science Books, 2012.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/seanredmond/juliandate
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file juliandate-1.0.4.tar.gz
.
File metadata
- Download URL: juliandate-1.0.4.tar.gz
- Upload date:
- Size: 18.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 775a5111809940254a18d3378f107dc09e381f5cbbdf77abf6ca1d42327d6655 |
|
MD5 | 55a5adb37febd9478c8d1d634c1e941a |
|
BLAKE2b-256 | bb52ceda6ab2ae64aa8713586a49d2657a41b1523b8eb843e86ef78df190d437 |
File details
Details for the file juliandate-1.0.4-py3-none-any.whl
.
File metadata
- Download URL: juliandate-1.0.4-py3-none-any.whl
- Upload date:
- Size: 18.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e03e3dc42b4c6cd727615af5536691bd56d9591c631cc429c6643bb722b34d5 |
|
MD5 | 28a037baf9a29d7de5a8ff431037a12a |
|
BLAKE2b-256 | 6927730bd1933423229ec1769dd3d505ca0ccc67b86ce5336f62775ea62193ba |