Julian Date converter

This submodule is to convert from Gregorian calenderdates or Julian Calender dates to the julian date format. This is done using

About

Simple conversions between Julian Dates and Julian/Gregorian calendar dates, supporting ancient dates (BCE). You can check juliandate's calculations against the US Naval Observeratory's Julian Date Converter.

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).

juliandate: Provide several conversions functions from gregorian date to julian and back.

`from_gregorian(year, month, day, hour=0, minute=0, seconds=0)`

Convert a Gregorian calendar date to a Julian Day Number. The algorithm is valid for all (possibly proleptic) Gregorian calendar dates after November 23, −4713. Divisions are integer divisions towards zero; fractional parts are ignored.

Examples:

>>> from_gregorian(-4713, 11, 24, 12, 0, 0)
0
>>> from_gregorian(1969, 7, 20)
2440422.5
>>> from_gregorian(1969, 7, 20, 20, 17, 30)
2440423.345486111
>>> to_gregorian(from_gregorian(1969, 7, 20, 20, 17, 58.4),is_int=False)
(1969, 7, 20, 20, 17, 58.4)

Parameters:

Name	Type	Description	Default
`year`	`int`	Year.	required
`month`	`int`	Month.	required
`day`	`int`	Day.	required
`hour`	`int`	Hour.	`0`
`minute`	`int`	Minute.	`0`
`seconds`	`int \| float`	Seconds get rounded to the closest tenth of a second.	`0`

Returns:

Type	Description
`float`	The Julian Day Number.

Source code in src/pyshic/juliandate/juliandate.py

def from_gregorian(year:int, month:int, day:int, hour:int=0, minute:int=0, seconds:Union[float,int]=0):
    """
    Convert a Gregorian calendar date to a Julian Day Number. The algorithm 
    is valid for all (possibly proleptic) Gregorian calendar dates after 
    November 23, −4713. Divisions are integer divisions towards zero; 
    fractional parts are ignored.

    Examples:
        >>> from_gregorian(-4713, 11, 24, 12, 0, 0)
        0
        >>> from_gregorian(1969, 7, 20)
        2440422.5
        >>> from_gregorian(1969, 7, 20, 20, 17, 30)
        2440423.345486111
        >>> to_gregorian(from_gregorian(1969, 7, 20, 20, 17, 58.4),is_int=False)
        (1969, 7, 20, 20, 17, 58.4)

    Args:
        year (int): Year.
        month (int): Month.
        day (int): Day.
        hour (int): Hour.
        minute (int): Minute.
        seconds (int|float): Seconds get rounded to the closest tenth of a second.

    Returns:
        (float): The Julian Day Number.
    """
    tmp = (
        int((1461 * (year + 4800 + int((month - 14) / 12))) / 4)
        + int((367 * (month - 2 - 12 * int((month - 14) / 12))) / 12)
        - int((3 * int((year + 4900 + int((month - 14) / 12)) / 100)) / 4)
        + day
        - 32075
    ) 

    seconds = round(seconds,1)
    return tmp + __day_pct(hour, minute, seconds)

`from_julian(year, month, day, hour=0, minute=0, second=0)`

Convert a Julian calendar date to a Julian Day Number. The algorithm is valid for all (possibly proleptic) Julian calendar years ≥ −4712, that is, for all JDN ≥ 0. Divisions are integer divisions, fractional parts are ignored.

Examples:

>>> from_julian(-43, 3, 15)
1705425.5
>>> from_julian(-43, 3, 15, 15)
1705426.125
>>> from_julian(-4712, 1, 1, 12, 0, 0)
0

Parameters:

Name	Type	Description	Default
`year`	`int`	Year.	required
`month`	`int`	Month.	required
`day`	`int`	Day.	required
`hour`	`int`	Hour.	`0`
`minute`	`int`	Minute.	`0`
`second`	`int \| float`	Seconds get rounded to the closest tenth of a second.	`0`

Returns:

Type	Description
`float`	The Julian Day Number.

Source code in src/pyshic/juliandate/juliandate.py

def from_julian(year:int, month:int, day:int, hour:int=0, minute:int=0, second:Union[int,float]=0):
    """
    Convert a Julian calendar date to a Julian Day Number. The algorithm 
    is valid for all (possibly proleptic) Julian calendar years ≥ −4712, 
    that is, for all JDN ≥ 0. Divisions are integer divisions, 
    fractional parts are ignored.

    Examples:
        >>> from_julian(-43, 3, 15)
        1705425.5
        >>> from_julian(-43, 3, 15, 15)
        1705426.125
        >>> from_julian(-4712, 1, 1, 12, 0, 0)
        0

    Args:
        year (int): Year.
        month (int): Month.
        day (int): Day.
        hour (int): Hour.
        minute (int): Minute.
        second (int|float): Seconds get rounded to the closest tenth of a second.

    Returns:
        (float): The Julian Day Number.
    """
    second = round(second, 1)
    return (
        367 * year
        - int((7 * (year + 5001 + int((month - 9) / 7))) / 4)
        + int((275 * month) / 9)
        + day
        + 1729777
        + __day_pct(hour, minute, second)
    )

`to_gregorian(julian_day, is_int=True)`

Convert a Julian Day Number to a Gregorian calendar date including hour, minute, and second.

Examples:

>>> to_gregorian(1566223.56309468)
(-424, 1, 28, 1, 30, 51)
>>> to_julian(0)
(-4712, 1, 1, 12, 0, 0)

Tip

Datetime usage

If you want to convert it to a datetime format use the to_gregorian method togeher with the * operator to unpack the values into a datetime object.

    from datetime import datetime
    datetime(*to_gregorian(2440423.345139, is_int=True))

Parameters:

Name	Type	Description	Default
`julian_day`	`(float, int)`	The Julian Day Number.	required

Returns:

Type	Description
`Tuple[int, int, int, int, int, int]`	A tuple containing year, month, day, hour, minute, and second.

Source code in src/pyshic/juliandate/juliandate.py

def to_gregorian(julian_day: Union[int,float], is_int:bool=True) -> Tuple[int, int, int, int, int, int]:
    """
    Convert a Julian Day Number to a Gregorian calendar date including hour, minute, and second.

    Examples:
        >>> to_gregorian(1566223.56309468)
        (-424, 1, 28, 1, 30, 51)
        >>> to_julian(0)
        (-4712, 1, 1, 12, 0, 0)

    !!! tip 
        ## Datetime usage
        If you want to convert it to a datetime format use the **to_gregorian** method togeher 
        with the * operator to unpack the values into a datetime object.

        ``` py
            from datetime import datetime
            datetime(*to_gregorian(2440423.345139, is_int=True))
        ```


    Args:
        julian_day (float, int): The Julian Day Number.

    Returns:
        A tuple containing year, month, day, hour, minute, and second.
    """
    return __jd_to_date(julian_day, True) + __h_m_s(julian_day, is_int)

`to_julian(julian_day, is_int=True)`

Convert a Julian Day Number to a Julian calendar date including hour, minute, and seconds.

Examples:

>>> to_julian(1566223.56309468)
(-424, 2, 2, 1, 30, 51)
>>> to_julian(1566223.56309468, is_int=False)
(-424, 2, 2, 1, 30, 51.4)
>>> to_julian(1566223.563096, is_int=False)
(-424, 2, 2, 1, 30, 51.5)
>>> to_julian(0)
(-4712, 1, 1, 12, 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). >>> to_julian(1705426) (-43, 3, 15, 12, 0, 0, 0)

Parameters:

Name	Type	Description	Default
`julian_day`	`(float, int)`	The Julian Day Number as float or int.	required

Returns:

Type	Description
`Tuple[int, int, int, int, int, Union[int, float]]`	A tuple containing year, month, day, hour, minute, and second.

Source code in src/pyshic/juliandate/juliandate.py

def to_julian(julian_day: Union[int,float], is_int:bool=True) -> Tuple[int, int, int, int, int, Union[int,float]]:
    """
    Convert a Julian Day Number to a Julian calendar date including hour, minute, and seconds. 

    Examples:
        >>> to_julian(1566223.56309468)
        (-424, 2, 2, 1, 30, 51)
        >>> to_julian(1566223.56309468, is_int=False)
        (-424, 2, 2, 1, 30, 51.4)
        >>> to_julian(1566223.563096, is_int=False)
        (-424, 2, 2, 1, 30, 51.5)
        >>> to_julian(0)
        (-4712, 1, 1, 12, 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).
        >>> to_julian(1705426)
        (-43, 3, 15, 12, 0, 0, 0)


    Args:
        julian_day (float, int): The Julian Day Number as float or int.

    Returns:
        A tuple containing year, month, day, hour, minute, and second.
    """
    return __jd_to_date(julian_day) + __h_m_s(julian_day, is_int)

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.

Math

Converting Julian calendar date to Julian Day Number

To convert a Gregorian calendar date \(\mathbf{D/M/Y}\) we use the formula from wikipedia. The algorithm is valid for all (possibly proleptic) Gregorian calendar dates after November 23, −4713. Divisions are integer divisions towards zero; fractional parts are ignored.

\[ \mathbf{JDN} = (1461 \cdot (\mathbf{Y} + 4800 + (\mathbf{M} − 14)/12))/4 +(367 \cdot (\mathbf{M} − 2 − 12 \cdot ((\mathbf{M} − 14)/12)))/12 − (3 \cdot ((\mathbf{Y} + 4900 + (\mathbf{M} - 14)/12)/100))/4 + \mathbf{D} − 32075 \]

Converting Julian calendar date to Julian Day Number

The algorithm is valid for all (possibly proleptic) Julian calendar years ≥ −4712, that is, for all JDN ≥ 0. Divisions are integer divisions, fractional parts are ignored.

\[ \mathbf{JDN} = 367 \cdot \mathbf{Y} − (7 \cdot (\mathbf{Y} + 5001 + (\mathbf{M} − 9)/7))/4 + (275 \cdot \mathbf{M})/9 + \mathbf{D} + 1729777 \]

Aknowledgement

This tool is based on modified source code originally available at a public repository https://github.com/seanredmond/juliandate from the user Sean Redmond. We thank the original contributors for their foundational work!