`Julian` Module

Julian Library

PDS Ring-Moon Systems Node, SETI Institute

This is a large set of routines for handing date and time conversions. Compared to other date/time libraries in Python, including CSPYCE, The Julian Library has these features:

It handles the time systems Coordinated Universal Time (UTC), International Atomic Time (TAI), Barycentric Dynamical Time (TDB), and Terrestrial Time (TT), properly accounting for leap seconds.
Any time can be expressed as a running count of elapsed seconds from a defined epoch, as a calendar date, using Julian Date (JD), or using Modified Julian Date (MJD).
Nearly all functions can process arrays of dates and times all at once, not just as individual values. This can provide a substantial performance boost compared to using iteration, especially when parsing or formatting columns of dates for a table file.
It provides options for how to interpret times before 1972, when the current version of the UTC time system was first implemented. Since 1972, leap seconds have been used to keep TAI in sync with UTC, ensuring that the UTC time never differs from UT1, the time system defined by the Earth’s rotation, by more than ~ 1 second. Between 1958 and 1972, the UTC second was redefined as a “rubber second”, which would stretch or shrink as necessary to ensure that every mean solar day contained exactly 86,400 UT seconds; see https://hpiers.obspm.fr/eop-pc/index.php?index=TAI-UTC_tab Before 1958, we use UT1 in place of UTC, employing a model for the long-term variations in Earth’s rotation as documented for the “Five Millennium Canon of Solar Eclipses: -1999 to +3000; see https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html The numerical details are here: https://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html This model can also be applied to future dates.
It supports both the modern (Gregorian) calendar and the older Julian calendar. The transition date can be defined by the user, or else the Julian calendar can be suppressed entirely.
A general parser is able to interpret almost arbitrary date-time strings correctly. This parser can also be used to search for and extract and dates and times from arbitrary text.

Calendar Operations

Every date is represented by an integer “day” value, where day = 0 on January 1, 2000. Various functions are provided to convert between day values and year, month, day, or day of year: day_from_ymd(), day_from_yd(), ymd_from_day(), yd_from_day().

Years prior to 1 CE are specified using the “astronomical year”, which includes a year zero. As a result, 1 BCE is specified as year 0, 2 BCE as year -1, 4713 BCE as year -4712, etc. Note that there is some historical uncertainty about which years were recognized as leap years in Rome between the adoption of the Julian calendar in 46 BCE and about 8 CE. For simplicity, we follow the convention that the Julian calendar extended backward indefinitely, so all all years divisible by four, including 4 CE, 0 (1 BCE), -4 (5 BCE), -8 (9 BCE), etc., were leap years.

Months are referred to by integers 1-12, 1 for January and 12 for December.

Day numbers within months are 1-31; day numbers within years are 1-366.

Functions are provided to determine the number of days in a specified month or year: days_in_year(), days_in_month().

Use the function set_gregorian_start() to specify the (Gregorian) year, month, and day for the transition from the earlier Julian calendar to the modern Gregorian calendar. The default start date of the Gregorian calendar is October 15, 1582, when this calendar was first adopted in much of Europe. However, the user is free to modify this date; for example, Britain adopted the Gregorian calendar on September 14, 1752.

Note that most calendar functions support an input parameter “proleptic”, taking a value of True or False. If True, all calendar dates are proleptic (extrapolated backward assuming the modern calendar), regardless of which calendar was in effect at the time.

Time Systems

All times are represented by numbers representing seconds past a specified epoch on January 1, 2000. Four time systems are supported:

International Atomic Time (TAI)
Universal Coordinated Time (UTC)
Barycentric Dynamical Time (TDB)
Terrestrial Time (TT, previously called Terrestrial Dynamical Time or TDT)

Internally, TAI serves as the intermediary between the other time systems. Conversions are straightforward, using: tai_from_utc(), utc_from_tai(), tai_from_tdb(), tdb_from_tai(), tai_from_tt(), tt_from_tai(). Alternatively, the more general function time_from_time() lets you specify the initial and final time systems of the conversion.

You can also specify a time using an integer day plus the number of elapsed seconds on that day, and then convert between these values and any time system: day_sec_from_utc(), day_sec_from_tai(), tai_from_day(), tai_from_day_sec(), utc_from_day(), utc_from_day_sec(). Alternatively, the more general functions day_sec_from_time() and time_from_day_sec() let you specify the initial and final time systems.

Julian Dates

Similarly, Julian dates and Modified Julian Dates can be converted to times using any time system: jd_from_time(), time_from_jd(), mjd_from_time(), time_from_mjd(), jd_from_day_sec(), day_sec_from_jd(), mjd_from_day_sec(), day_sec_from_mjd().

You can also convert directly between integer MJD and integer day numbers using: ` mjd_from_day()`, day_from_mjd().

Leap Second Handling

In 1972, the UTC time system began using leap seconds to keep TAI times in sync with mean solar time to a precision of ~ 1 second. We provide several methods to allow the user to keep the leap second list up to date.

If the environment variable SPICE_LSK_FILEPATH is defined, then this SPICE leapseconds kernel is read at startup. Otherwise, leap seconds through 2020 are always included, as defined in SPICE kernel file “naif0012.tls”. You can also call the function load_lsk() directly.

Alternatively, use insert_leap_second() to augment the list with additional leap seconds (positive or negative).

Use seconds_on_day() to determine the length in seconds of a given day; use leapsecs_on_day() or leapsecs_from_ymd() to determine the cumulative number of leap seconds on a given date.

Use set_ut_model() to define how to handle times before 1972 and into the future, outside the duration of the current UTC leap second system.

Date/Time Formatting

Several functions are provided to express dates or times as formatted character strings: format_day(), format_day_sec(), format_sec(), format_tai(), iso_from_tai(). Most variations of the ISO 8601:1988 format are supported.

Note that these functions can produce strings, bytestrings, or arbitrary arrays thereof. The functions operate on the entire array all at once, and can therefore be much faster than making individual calls over and over. For example, note that one could provide a NumPy memmap as input to these functions and it would write content directly into a large ASCII table, avoiding any conversion to/from Unicode.

String Parsing and Searching

We provide functions for the very fast parsing of identically-formatted strings or bytestrings that represent dates, times or both: day_from_iso(), day_sec_from_iso(), sec_from_iso(), tai_from_iso(), tdb_from_iso(), time_from_iso(). These functions recognize most variations of the ISO 8601:1988 format, and are ideal for interpreting date and time columns from large ASCII tables.

More general parsers are provided for interpreting individual dates and times in almost arbitrary formats: day_from_string(), day_sec_from_string(), sec_from_string(). These same parsers can also be invoked to search for dates and times embedded in arbitrary text: days_in_strings(), day_sec_in_strings(), secs_in_strings(). Time zones are recognized, including most standard abbreviations.

For users familiar with the pyparsing module, we provide functions that generate parsers for a wide variety of special requirements. See: date_pyparser(), datetime_pyparser(), mjd_pyparser(), time_pyparser().

Calendar functions

julian.calendar.day_from_yd(y, d, *, validate=False, proleptic=False)[source]

Day number from year and day-of-year.

Parameters:

y (int or array-like) – Year number. Note that 1 BCE corresponds to year 0, 2 BCE to -1, etc.
d (int, float, or array-like) – Day of year, 1-366.
validate (bool, optional) – True to confirm that day numbers are in range.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Raises:

JulianValidateFailure – If validate is True and a number is out of range.

Returns:

Day number relative to January 1, 2000. Values are floating-point if d is given as floating-point; otherwise they are integral.

Return type:

int, float, or array

julian.calendar.day_from_ymd(y, m, d, *, validate=False, proleptic=False)[source]

Number of elapsed days after January 1, 2000, given a year, month, and day.

Parameters:

y (int or array-like) – Year number. Note that 1 BCE corresponds to year 0, 2 BCE to -1, etc.
m (int or array-like) – Month number, 1-12.
d (int, float or array-like) – Day number, 1-31.
validate (bool, optional) – True to raise JulianValidateFailure (a ValueError subclass) for year, month, or day numbers out of range; default is False.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Days number relative to January 1, 2000. Values are floating-point if d is floating-point; otherwise they are integral.

Return type:

int, float, or array

julian.calendar.days_in_month(y, m, *, validate=False, proleptic=False)[source]

Number of days in month.

Parameters:

y (int or array-like) – Year number. Note that 1 BCE corresponds to year 0, 2 BCE to -1, etc.
m (int or array-like) – Month number, 1-12.
validate (bool, optional) – True to confirm that month numbers are in range.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Number of days in month.

Return type:

int or array-like

Raises:

JulianValidateFailure – If validate is True and a number is out of range.

Notes

This is the number of days from the first of one month to the first of the next. If proleptic is False, this number will be less than the last valid calendar day during the month of transition from the Julian to Gregorian calendar.

julian.calendar.days_in_year(year, *, proleptic=False)[source]

Number of days in year.

Parameters:

y (int or array-like) – Year number. Note that 1 BCE corresponds to year 0, 2 BCE to -1, etc.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Number of days in year.

Return type:

int or array

Notes

This is the number of days from the first of one year to the first of the next. If proleptic is False, this number will be less than 365 during the year of transition from the Julian to Gregorian calendar.

julian.calendar.days_in_ym(y, m, *, validate=False, proleptic=False)[source]

Number of days in month.

DEPRECATED name for days_in_month().

Parameters:

y (int or array-like) – Year number. Note that 1 BCE corresponds to year 0, 2 BCE to -1, etc.
m (int or array-like) – Month number, 1-12.
validate (bool, optional) – True to confirm that month numbers are in range.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Number of days in month.

Return type:

int or array-like

Raises:

JulianValidateFailure – If validate is True and a number is out of range.

Notes

This is the number of days from the first of one month to the first of the next. If proleptic is False, this number will be less than the last valid calendar day during the month of transition from the Julian to Gregorian calendar.

julian.calendar.set_gregorian_start(y=1582, m=10, d=15)[source]

Set the first day of the Gregorian calendar as a year, month, and day.

Parameters:

y (int) – The year number at the start of the modern Gregorian calendar. Use None to suppress the Julian calendar, using the Gregorian calendar exclusively, even where proleptic=False is specified.
m (int) – The month number (1-12) at the start of the Gregorian calendar.
d (int) – The day number (1-31) at the start of the Gregorian calendar.

Notes

This calendar was introduced by Pope Gregoary XIII to correct the drift between the pre-existing Julian calendar and the actual solar year. In Europe, it began on October 15, 1582. However, the Julian calendar was not adopted in England until September 14, 1752.

This is a global setting of the Julian Library.

julian.calendar.yd_from_day(day, *, proleptic=False)[source]

Year and day-of-year from day number.

Parameters:

day (int, float, or array-like) – Day number of relative to January 1, 2000.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

y (int or array): Year.
d (int, float, or array): Day of year (1-366). Values are floating-point if day is given as floating-point; otherwise they are integral.

Return type:

tuple (y, d)

julian.calendar.ymd_from_day(day, *, proleptic=False)[source]

Year, month and day from day number.

Parameters:

day (int, float, or array-like) – Day number of relative to January 1, 2000.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

y (int or array): Year.
m (int or array): Month (1-12).
d (int, float, or array): Day of month (1-31). Values are floating-point if day is floating-point; otherwise, they are integral.

Return type:

tuple (y, m, d)

Date Parsers

julian.date_parsers.day_from_string(string, order='YMD', *, doy=True, mjd=False, weekdays=False, extended=False, proleptic=False)[source]

Day number based on the parsing of a free-form string.

Parameters:

string (str) – String to interpret.
order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Day number relative to January 1, 2000.

Return type:

int

Raises:

JulianParseException – If string was not recognized as a valid date expression.
JulianValidateFailure – If the date string contains invalid or contradictory information.

julian.date_parsers.days_in_strings(strings, order='YMD', *, doy=False, mjd=False, weekdays=False, extended=False, proleptic=False, substrings=False, first=False)[source]

List of day numbers obtained by searching one or more strings for patterns that look like formatted dates.

Parameters:

strings (str, list, tuple, or array) – Strings to interpret.
order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
substrings (bool, optional) – True to also return the substring containing each identified date.
first (bool, optional) – True to return the first date found rather than a list of dates. In this case, None is returned if no date is found rather than an empty list.

Returns:

If first=False, a list of dates is returned; otherwise, a single date is returned or None if no date was found. If substrings is False, each date is represented by a day number relative to January 1, 2000. If substrings is True, each date is represented by a tuple, where the first element is the day number and the second is the substring found that defines this date.

Return type:

int, tuple (day, substring), list[int or tuple], or None

Raises:

JulianValidateFailure – If a matched date string contains invalid or contradictory information.

Date pyparsing Grammars

julian.date_pyparser.date_pyparser(order='YMD', *, strict=False, doy=False, mjd=False, weekdays=False, floating=False, floating_only=False, extended=False, iso_only=False, padding=True, embedded=False)[source]

A date parser.

Parameters:

order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
strict (bool, optional) – True for a stricter parser, which is less likely to match strings that might not actually represent dates.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
floating (bool, optional) – True to allow fractional days. If False, the mjd option only supports integer MJD dates.
floating_only (bool, optional) – True to require the date to contain a decimal point.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
iso_only (bool, optional) – Require an ISO 8601:1988-compatible date string; ignore order, strict, mjd, and weekdays options.
padding (bool, optional) – True to ignore leading or trailing white space.
embedded (bool, optional) – True to allow the time to be followed by additional text.

Returns:

A parser for the selected syntax. Calling the as_list() method on the returned ParseResult object returns a list containing some but not all of these tuples, depending on what appears in the parsed string:

(“YEAR”, year): Year if specified; two-digit years are converted to 1970-2069. Alternatively, “MJD” or “JD” if the day number is to be interpreted as a Julian or Modified Julian date.
(“MONTH”, month): Month if specified, 1-12.
(“DAY”, day); Day number: 1-31 if a month was specified; 1-366 if a day of year was specified; otherwise, the MJD or JD day value.
(“WEEKDAY”, abbrev): Day of the week if provided, as an abbreviated uppercase name: “MON”, “TUE”, etc.
(“TIMESYS”, name): “UTC” for an MJD or JD date; “TDB” for an MJED or JED date; “TT” for an MJTD or JTD date.
(“~”, number): The last occurrence of this tuple in the list contains the number of characters matched.

Return type:

pyparsing.ParserElement

Date-Time Parsers

julian.datetime_parsers.day_sec_from_string(string, order='YMD', *, doy=True, mjd=True, weekdays=False, extended=False, proleptic=False, treq=False, leapsecs=True, ampm=True, timezones=False, timesys=False, floating=False)[source]

Day and second values based on the parsing of a free-form string.

Parameters:

string (str) – String to interpret.
order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
treq (bool, optional) – True if a time field is required; False to recognize date strings that do not include a time.
leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
timesys (bool, optional) – True to recognize an embedded time system such as “UTC”, “TAI”, etc.
floating (bool, optional) – True to recognize time specified using floating-point hours or minutes.

Returns:

day (int): Integer day number, converted to UTC if a time zone was identified.
sec (int or float): Seconds into day, converted to UTC if a time zone was identified.
tsys (str): Name of the time system, included if timesys is True.

Return type:

tuple (day, sec[, tsys])

Raises:

JulianParseException – If string was not recognized as a valid date-time expression.
JulianValidateFailure – If the date-time string contains invalid or contradictory information.

julian.datetime_parsers.day_sec_in_strings(strings, order='YMD', *, doy=False, mjd=False, weekdays=False, extended=False, proleptic=False, treq=False, leapsecs=True, ampm=False, timezones=False, timesys=False, floating=False, substrings=False, first=False)[source]

List of day and second values representing date/time strings found by searching one or more strings for patterns that look like formatted dates and times.

Parameters:

strings (list, tuple, or array) – Strings to interpret.
order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
treq (bool, optional) – True if a time field is required; False to recognize date strings that do not include a time.
leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
timesys (bool, optional) – True to recognize an embedded time system such as “UTC”, “TAI”, etc.
floating (bool, optional) – True to recognize time specified using floating-point hours or minutes.
substrings (bool, optional) – True to also return the substring containing each identified date-time value.
first (bool, optional) – True to return the first date-time value found rather than a list of values. In this case, None is returned if no date-time is found rather than an empty list.

Returns:

If first is False, a list of tuples containing information about each date-time is returned; otherwise, a single tuple is returned or None if no date-time value was found. Within this tuple:

day (int): Day number, converted to UTC if a time zone was identified.
sec (int or float): Seconds into day, converted to UTC if a time zone was identified.
tsys (str): The name of each associated time system, with “UTC” the default; included if timesys is True.
substring (str): The substring containing the text that was interpreted to represent this date and time; included if substrings is True.

Return type:

tuple (day, sec[, tsys][, substring]), list[tuple], or None

Raises:

JulianValidateFailure – If a matched date-time string contains invalid or contradictory information.

Date-Time pyparsing Grammars

julian.datetime_pyparser.datetime_pyparser(order='YMD', *, treq=False, strict=False, doy=False, mjd=False, weekdays=False, extended=False, leapsecs=False, ampm=False, timezones=False, timesys=False, floating=False, iso_only=False, padding=True, embedded=False)[source]

A date-time pyparser.

Parameters:

order (str) – One of “YMD”, “MDY”, or “DMY”, defining the default order for day month, and year in situations where it might be ambiguous.
treq (bool, optional) – True if a time field is required; False to recognize date strings that do not include a time.
strict (bool, optional) – True for a stricter parser, which is less likely to match strings that might not actually represent dates.
doy (bool, optional) – True to recognize dates specified as year and day-of-year.
mjd (bool, optional) – True to recognize Modified Julian Dates.
weekdays (bool, optional) – True to allow dates including weekdays.
extended (bool, optional) – True to support extended year values: signed (with at least four digits) and those involving “CE”, “BCE”, “AD”, “BC”.
leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
timesys (bool, optional) – True to recognize an embedded time system such as “UTC”, “TAI”, etc.
floating (bool, optional) – True to allow date-times specified using floating-point days, hours, or minutes.
iso_only (bool, optional) – Require an ISO 8601:1988-compatible date string; ignore order, strict, mjd, `ampm, and timesys options.
padding (bool, optional) – True to ignore leading or trailing white space.
embedded (bool, optional) – True to allow the time to be followed by additional text.

Returns:

A parser for the selected syntax. Calling the as_list() method on the returned ParseResult object returns a list containing some but not all of these tuples, depending on what appears in the parsed string:

(“YEAR”, year): Year if specified; two-digit years are converted to 1970-2069. Alternatively, “MJD” or “JD” if the day number is to be interpreted as a Julian or Modified Julian date.
(“MONTH”, month): Month if specified, 1-12.
(“DAY”, day); Day number: 1-31 if a month was specified; 1-366 if a day of year was specified; otherwise, the MJD or JD day value.
(“WEEKDAY”, abbrev): Day of the week if provided, as an abbreviated uppercase name: “MON”, “TUE”, etc.
(“HOUR”, hour): Hour if specified, 0-23, an int or possibly a float. Hours am/pm are converted to the range 0-23 automatically.
(“MINUTE”, minute): Minute if specified, integer or float.
(“SECOND”, second): Second if specified, integer or float.
(“TZ”, tz_name): Name of the time zone if specified.
(“TZMIN”, tzmin): Ooffset of the time zone in minutes.
(“TIMESYS”, name): “UTC” for an MJD or JD date; “TDB” for an MJED or JED date; “TT” for an MJTD or JTD date.
(“~”, number): The last occurrence of this tuple in the list contains the number of characters matched.

Return type:

pyparsing.ParserElement

Formatters

julian.formatters.format_day(day, order='YMD', *, ydigits=4, dash='-', ddigits=None, proleptic=False, buffer=None, kind='U')[source]

Format a date or array of dates.

Parameters:

day (int, float, or array-like) – Day number of relative to January 1, 2000.
order (str) – The order of the year, optional month, and day fields, one of “YMD”, “MDY”, “DMY”, “YD”, or “DY”.
ydigits (int, optional) – Number of year digits to include in year, 2 or 4.
dash (str) – Character(s) to include between fields, if any. Default is “-”. Use “” for no separators; any other string can also be used in place of the dashes.
ddigits (int, optional) – Decimal digits to include in day values; use -1 or None to suppress the decimal point; ignored if day values are integers.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
buffer (array[str or bytes]) – An optional array of strings or byte strings into which to write the results. Must have sufficient dimensions. This can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”); if the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.
kind (str) – “U” to return strings, “S” to return bytes. Ignored if buffer is provided.

Returns:

The formatted date(s).

Return type:

str or array

julian.formatters.format_day_sec(day, sec, order='YMDT', *, ydigits=4, dash='-', sep='T', colon=':', digits=None, suffix='', proleptic=False, buffer=None, kind='U')[source]

Format a date and time.

This function supports scalar or array-like inputs. If array-like inputs are provided, an array of strings or ASCII byte strings is returned.

Note that the optional output buffer can be either strings (dtype “U”) or bytes (dtype “S”). If the latter, you can define it as a NumPy memmap and write content directly into an ASCII table file.

Parameters:

day (int, float, or array-like) – Day number of relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds into day.
order (str) – The order of the year, optional month, day, and time fields. Can be any of “YMD”, “MDY”, “DMY”, “YD”, or “DY”. Add “T” at the beginning or end to indicate whether times come before or after the date.
ydigits (int, optional) – Number of year digits to include in year, 2 or 4.
dash (str) – Character(s) to include between fields, if any. Default is “-”. Use “” for no separators; any other string can also be used in place of the dashes.
sep (str) – Character(s) to appear between the date and the time.
colon (str) – Character(s) to include between fields, if any. Default is “:”. Use “” for no separators; any other string can also be used in place of the colons.
digits (int, optional) – Decimal digits to include second values; use -1 or None to suppress the decimal point; ignored if sec values are integers.
suffix (str, optional) – “Z” to include the Zulu time zone indicator.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
buffer (array[str or bytes]) – An optional array of strings or byte strings into which to write the results. Must have sufficient dimensions. This can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”); if the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.
kind (str) – “U” to return strings, “S” to return bytes. Ignored if buffer is provided.

Returns:

The formatted date-time value(s).

Return type:

str or array

julian.formatters.format_sec(sec, digits=None, *, colon=':', suffix='', buffer=None, kind='U')[source]

A time of day in seconds converted to “hh:mm:ss[.fff][Z]” or similar formats.

This function supports scalar or array-like inputs. If the latter, an array of strings or ASCII bytes is returned.

Note that the optional output buffer can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”). If the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.

Parameters:

sec (int, float, or array-like) – Elapsed seconds into day. Each value should be >= 0 and < 86410.
digits (int, optional) – Decimal digits to include; use -1 or None to suppress the decimal point; ignored if sec values are integers.
colon (str) – Character(s) to include between fields, if any. Default is “:”. Use “” for no separators; any other string can also be used in place of the colons.
suffix (str, optional) – “Z” to include the Zulu time zone indicator.
buffer (array[str or bytes]) – An optional array of strings or byte strings into which to write the results. Must have sufficient dimensions. This can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”); if the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.
kind (str) – “U” to return strings, “S” to return bytes. Ignored if buffer is provided.

Returns:

The formatted time(s).

Return type:

str or array

julian.formatters.format_tai(tai, order='YMDT', *, ydigits=4, dash='-', sep='T', colon=':', digits=None, suffix='', proleptic=False, buffer=None, kind='U')[source]

Format a date and time given a time in seconds TAI.

This function supports scalar or array-like inputs. If array-like inputs are provided, an array of strings or ASCII byte strings is returned.

Note that the optional output buffer can be either strings (dtype “U”) or bytes (dtype “S”). If the latter, you can define it as a NumPy memmap and write content directly into an ASCII table file.

Parameters:

tai (int, float, or array) – Time value in seconds TAI.
order (str) – The order of the year, optional month, day, and time fields. Can be any of “YMD”, “MDY”, “DMY”, “YD”, or “DY”. Add “T” at the beginning or end to indicate whether times come before or after the date.
ydigits (int, optional) – Number of year digits to include in year, 2 or 4.
dash (str) – Character(s) to include between fields, if any. Default is “-”. Use “” for no separators; any other string can also be used in place of the dashes.
sep (str) – Character(s) to appear between the date and the time.
colon (str) – Character(s) to include between fields, if any. Default is “:”. Use “” for no separators; any other string can also be used in place of the colons.
digits (int, optional) – Decimal digits to include second values; use -1 or None to suppress the decimal point; ignored if sec values are integers.
suffix (str, optional) – “Z” to include the Zulu time zone indicator.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
buffer (array[str or bytes]) – An optional array of strings or byte strings into which to write the results. Must have sufficient dimensions. This can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”); if the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.
kind (str) – “U” to return strings, “S” to return bytes. Ignored if buffer is provided.

Returns:

The formatted date-time value(s).

Return type:

str or array

julian.formatters.iso_from_tai(tai, ymd=True, digits=None, *, suffix='', proleptic=False, buffer=None, kind='U')[source]

Date and time in ISO format given seconds TAI.

This function supports scalar or array-like inputs. If array-like inputs are provided, an array of strings or ASCII byte strings is returned.

Note that the optional output buffer can be either strings (dtype “U”) or bytes (dtype “S”). If the latter, you can define it as a NumPy memmap and write content directly into an ASCII table file.

Note that this function is a variant of format_day_sec() but with a reduced set of options.

Parameters:

tai (int, float, or array) – Time value in seconds TAI.
ymd (bool, optional) – True for year-month-day format; False for year plus day-of-year format.
digits (int, optional) – Decimal digits to include second values; use -1 or None to suppress the decimal point; ignored if sec values are integers.
suffix (str, optional) – “Z” to include the Zulu time zone indicator.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.
buffer (array[str or bytes]) – An optional array of strings or byte strings into which to write the results. Must have sufficient dimensions. This can be either strings (dtype.kind = “U”) or bytes (dtype.kind = “S”); if the latter, you can provide a NumPy memmap as input and this function will write content directly into an ASCII table file.
kind (str) – “U” to return strings, “S” to return bytes. Ignored if buffer is provided.

Returns:

The formatted date-time value(s).

Return type:

str or array

ISO Parsers

julian.iso_parsers.day_from_iso(strings, *, validate=True, syntax=False, strip=False, proleptic=False)[source]

Day number based on a parsing of a date string in the ISO 8601:1988 format.

Recognized calendar date formats are “yyyy-mm-dd”, “yyyymmdd”, “yy-mm-dd”, and “yymmdd”. Supported ordinal date formats are “yyyy-ddd”, “yyyyddd”, “yy-ddd”, and “yyddd”. A fractional day following a decimal point is also permitted.

This parser is much faster than the more general date parsing routines. It can also process lists or arrays of date strings of arbitrary shape, provided that every element uses the exact same format.

Because it can handle arrays of bytestrings, it is very efficient at processing raw data extracted from a column of an ASCII table.

Parameters:

strings (str, bytes, or array-like) – String(s) to interpret.
validate (bool, optional) – True to validate the year/month/day values.
syntax (bool, optional) – True to check the string values more closely for conformance to the ISO standard; raise JulianParseException (a ValueError subclass) on error.
strip (bool, optional) – True to skip over leading and trailing blanks.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Day number(s) relative to January 1, 2000.

Return type:

int or array

Raises:

JulianValidateFailure – If validate is True and a year, month, or day value is out of range.

julian.iso_parsers.day_sec_from_iso(strings, *, validate=True, syntax=False, strip=False, proleptic=False)[source]

Day and second based on a parsing of the string in ISO date-time format.

This function parses date-time strings in the fixed ISO format, using “yyyy-mm-dd” or “yyyy-ddd” for the date, a single space or “T”, and a time as “hh:mm:ss[.s…][Z]”. It is much faster than the more general date parsing routines. It can also process lists or arrays of date strings of arbitrary shape, provided that every element uses the exact same format.

Because it can handle arrays of bytestrings, it is very efficient at processing raw data extracted from a column of an ASCII table.

Parameters:

(str (strings) – Strings to interpret. If an array is provided, all values must use the same format.
bytes – Strings to interpret. If an array is provided, all values must use the same format.
array-like (or) – Strings to interpret. If an array is provided, all values must use the same format.
validate (bool, optional) – True to validate the ranges of the year, month, and day values.
syntax (bool, optional) – True to check the string values more closely for conformance to the ISO standard; raise JulianParseException (a ValueError subclass) on error.
strip (bool, optional) – True to skip over leading and trailing blanks.
leapsecs (bool, optional) – True to tolerate leap second values during validation.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

day (int or array): Day number(s) relative to January 1, 2000.
sec (int, float, or array): Elapsed seconds since beginning of day. Values are integral the seconds value is integral.

Return type:

tuple (day, sec)

Raises:

JulianValidateFailure – If validate is True and any numeric value is out of range.

julian.iso_parsers.sec_from_iso(strings, *, validate=True, leapsecs=True, strip=False, syntax=False)[source]

Accumulated number of seconds into a day, based on a parsing of a time string in ISO 8601:1988 “extended” format (but using a decimal point for fractional seconds rather than a comma).

The format required is “hh:mm:ss[.s…][Z]”. This parser is much faster than the more general time parsing routines. It can also process lists or arrays of date strings of arbitrary shape, provided that every element uses the exact same format.

Because it can handle arrays of bytestrings, it is very efficient at processing raw data extracted from a column of an ASCII table.

Parameters:

strings (str, bytes, or array-like[str or bytes]) – Strings to interpret. If an array is provided, all values must use the same format.
validate (bool, optional) – True to check the year/month/day values more carefully; raise JulianValidateFailure (a ValueError subclass) on error.
syntax (bool, optional) – True to check the string values more closely for conformance to the ISO standard; raise JulianParseException (a ValueError subclass) on error.
strip (bool, optional) – True to skip over leading and trailing blanks.
leapsecs (bool, optional) – True to tolerate leap second values during validation.

Returns:

Elapsed seconds since beginning of day. Values are integral the seconds value is integral.

Return type:

int, float, or array

Raises:

JulianValidateFailure – If validate is True and an hour, minute, or second value is out of range.

julian.iso_parsers.tai_from_iso(strings, *, validate=True, strip=False, proleptic=False)[source]

TAI time given an ISO date or date-time string.

This is a shortcut for time_from_iso() with timesys=’TAI’.

Parameters:

strings (str, bytes, or array-like) – Strings to interpret. If an array is provided, all values must use the same format.
validate (bool, optional) – True to validate the date and time values.
strip (bool, optional) – True to skip over leading and trailing blanks.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Time in seconds TAI.

Return type:

int, float, or array

Raises:

JulianValidateFailure – If a value embedded in the date or time is out of range.

julian.iso_parsers.tdb_from_iso(strings, *, validate=True, strip=False, proleptic=False)[source]

TDB time given an ISO date or date-time string.

This is a shortcut for time_from_iso() with timesys=’TDB’.

Parameters:

strings (str, bytes, or array-like) – Strings to interpret. If an array is provided, all values must use the same format.
validate (bool, optional) – True to validate the date and time values.
strip (bool, optional) – True to skip over leading and trailing blanks.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Time in seconds TDB.

Return type:

int, float, or array

Raises:

JulianValidateFailure – If a value embedded in the date or time is out of range.

julian.iso_parsers.time_from_iso(strings, timesys='TAI', *, validate=True, strip=False, proleptic=False)[source]

Time in a specified time system given an ISO date or date-time string.

Parameters:

strings (str, bytes, or array-like[str or bytes]) – Strings to interpret. If an array is provided, all values must use the same format.
timesys (str) – Name of the time system, “UTC”, “TAI”, “TDB”, or “TT”.
validate (bool, optional) – True to validate the date and time values.
strip (bool, optional) – True to skip over leading and trailing blanks.
proleptic (bool, optional) – True to interpret all dates according to the modern Gregorian calendar, even those that occurred prior to the transition from the Julian calendar. False to use the Julian calendar for earlier dates.

Returns:

Time in seconds in the specified time system.

Return type:

int, float, or array

Raises:

JulianValidateFailure – If a value embedded in the date or time is out of range.

Leap Seconds Support

julian.leap_seconds.delta_t_from_day(day)[source]

The difference between TAI seconds and UT seconds for the given day number.

Parameters:: day (int, float, or array-like) – Day number relative to January 1, 2000.
Returns:: TAI-UT in seconds. If values are exclusively defined as integral values of leap seconds, returned values are integral; if any “rubber seconds” are involved, they are floats.
Return type:: int, float or array

julian.leap_seconds.delta_t_from_ymd(y, m, d=1)[source]

The difference between TAI seconds and UT seconds for the given date, expressed as a calendar year, month, and optional day.

Parameters:

y (int or array-like) – Year.
m (int or array-like) – Month, 1-12.
d (int, float, or array-like) – Day of month, 1-31.

Returns:

TAI-UT in seconds. If values are exclusively defined as integral values of leap seconds, returned values are integral; if any “rubber seconds” are involved, they are floats.

Return type:

int, float or array

julian.leap_seconds.insert_leap_second(y, m, offset=1)[source]

Insert a new (positive or negative) leap second.

Parameters:

y (int) – Year of the new leap second.
m (int) – Month of the new leap second.
offset (int) – The change in TAI - UT. The default is 1; use -1 for a negative leap second.

Notes

The new leap second must occur after any previously defined leap seconds.

The list of leap seconds is a global setting of the Julian Library.

julian.leap_seconds.leapsecs_from_day(day)[source]

The cumulative difference between TAI and UT for the given day number.

This differs from the function tai_minus_utc_from_day() in that it ignores UT “rubber seconds” and therefore always returns integers, typically 86400 or 86401.

Alternative name for leapsecs_on_day().

Parameters:: day (int, float, or array-like) – Day number of relative to January 1, 2000.
Returns:: TAI-UT as integer seconds.
Return type:: int or array

julian.leap_seconds.leapsecs_from_ym(y, m, d=1)[source]

The number of leap seconds on the given date, where the date is expressed as a calendar year, month, and optional day.

Alternative name for leapsecs_from_ymd().

Parameters:

y (int or array-like) – Year.
m (int or array-like) – Month, 1-12.
d (int, float, or array-like) – Day of month, 1-31.

Returns:

TAI-UT as integer seconds.

Return type:

int or array

julian.leap_seconds.leapsecs_from_ymd(y, m, d=1)[source]

The number of leap seconds on the given date, where the date is expressed as a calendar year, month, and optional day.

Parameters:

y (int or array-like) – Year.
m (int or array-like) – Month, 1-12.
d (int, float, or array-like) – Day of month, 1-31.

Returns:

TAI-UT as integer seconds.

Return type:

int or array[int]

julian.leap_seconds.leapsecs_on_day(day)[source]

The cumulative difference between TAI and UT for the given day number.

This differs from the function tai_minus_utc_from_day() in that it ignores UT “rubber seconds” and therefore always returns integers, typically 86400 or 86401.

Parameters:: day (int, float, or array-like) – Day number of relative to January 1, 2000.
Returns:: TAI-UT as integer seconds.
Return type:: int or array

julian.leap_seconds.load_lsk(lsk_path='')[source]

Load a specified SPICE leap seconds kernel.

Any previously defined leap seconds are replaced by the new list. If additional leap seconds were previously inserted via insert_leap_second(), they must be inserted again.

Parameters:: lsk_path (str, pathlib, of filecache.FCPath, optional) – The path to an LSK kernel file. If this is blank or None, the default LSK kernel is re-loaded.

Notes

The currently selected UTC model is preserved.

The list of leap seconds is a global setting of the Julian Library.

julian.leap_seconds.seconds_on_day(day, leapsecs=True, timesys='UTC')[source]

Number of seconds on a given day number.

Parameters:

day (int, float, or array-like) – Day number of relative to January 1, 2000.
leapsecs (bool, optional) – If False, values of 86400 are returned regardless of the input.
timesys (str, optional) – The time system, “UTC” or “TAI”.

Returns:

Number of seconds on the day, 86400 unless there is a leap second.

Return type:

int or array

Notes

If timesys equals “UTC”, the values returned are in units of UTC “rubber seconds”, which are adjusted relative to TAI seconds in order to ensure that every day prior to 1972 contains exactly 86400 seconds. If timesys equals “TAI”, then the values returned are in fixed units of TAI seconds, meaning that days prior to 1972 may not have integral durations.

julian.leap_seconds.set_ut_model(model='LEAPS', future=None)[source]

Define how to handle the differences between TAI and UT for years prior to 1972 and for years into the future.

This is a global setting of the Julian Library, although it can be changed at will.

Parameters:

model (str, optional) – One of “LEAPS”, “SPICE”, “PRE-1972”, or “CANON”. See Notes.
future (int, optional) – The future year at which to use the “CANON” model, if it is selected. Use None or np.inf to suppress the CANON model for all future dates. Ignored if the “CANON” model is not in use.

Notes

The following models are supported:

“LEAPS”: This is the default model including leap seconds. It assumes that TAI-UTC equals 10 prior to 1972 and will hold its current fixed value into the future.
“SPICE”: Replicate the behavior of the SPICE Toolkit, in which TAI-UTC=9 before 1972. In this system, December 31, 1971 incorrectly contained a leap second.
“PRE-1972”: In addition to the “LEAPS” model, include the full model for UTC widely used during the period 1958-1972. In these years, the UTC time system was defined in terms of a “rubber second”, which could expand or shrink as necessary to ensure that every UTC day had exactly 86,400 seconds. In addition, several fractional leap seconds were added during the 1960s. See https://hpiers.obspm.fr/eop-pc/index.php?index=TAI-UTC_tab.
“CANON”: In addition to the “PRE-1972” model, include the model for UT1 “rubber seconds” based on the Five Millennium Canon of Solar Eclipses for the years -1999 to 3000. See https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html. When selected, this model will apply for all years before 1958. Use the input parameter “future” to specify the future year in which this model overrides the UTC leap second model; otherwise, by default, the leap second model will apply to all future years.

MJD/JD Conversions

julian.mjd_jd.day_from_mjd(mjd)[source]

UTC day number for a given UTC Modified Julian Date.

Parameters:: mjd (int, float, or array-like) – MJD day number.
Returns:: Day number, starting from midnight on January 1, 2000. If mjd is integral, integers are returned.
Return type:: int, float, or array

julian.mjd_jd.day_sec_from_jd(jd)[source]

UTC day number and seconds for a given UTC Julian Date.

Parameters:

jd (int, float, or array-like) – Julian date.

Returns:

day (int or array): Day number, starting from midnight on January 1, 2000.
sec (int, float, or array): Elapsed seconds within that day, allowing for leap seconds. If mjd is integral, integers are returned.

Return type:

tuple (day, sec)

Notes

The JD time system has day-length “ticks”, which means that it interacts in a peculiar way with leap seconds. When allowing for leap seconds, some days are longer than others. Nevertheless, this time system is defined such that the value of JD always increases by one frome the end of one day to the end of the next. On days that contain leap seconds, the fractional rate must therefore be a bit slower.

julian.mjd_jd.day_sec_from_mjd(mjd)[source]

UTC day number and seconds for a given UTC Modified Julian Date.

Parameters:

mjd (int, float, or array-like) – MJD day number.

Returns:

day (int or array): Day number, starting from midnight on January 1, 2000.
sec (int, float, or array): Elapsed seconds within that day, allowing for leap seconds. If mjd is integral, integers are returned.

Return type:

tuple (day, sec)

Notes

The MJD time system has day-length “ticks”, which means that it interacts in a peculiar way with leap seconds. When allowing for leap seconds, some days are longer than others. Nevertheless, this time system is defined such that the value of MJD always increases by one from the end of one day to the end of the next. On days that contain leap seconds, the fractional rate must therefore be a bit slower.

julian.mjd_jd.jd_from_day_sec(day, sec=0)[source]

UTC Julian Date for a given UTC day number and seconds.

Parameters:

day (int, float, or array-like) – Day number relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds within that day, allowing for leap seconds.

Returns:

The Julian Date.

Return type:

float or array

Notes

The JD time system has day-length “ticks”, which means that it interacts in a peculiar way with leap seconds. When allowing for leap seconds, some days are longer than others. Nevertheless, this time system is defined such that the value of JD always increases by one frome the end of one day to the end of the next. On days that contain leap seconds, the fractional rate must therefore be a bit slower.

julian.mjd_jd.jd_from_tai(tai)[source]

Julian Date fram TAI seconds.

Parameters:: tai (int, float, or array-like) – Time in seconds TAI.
Returns:: The Julian Date.
Return type:: float or array

julian.mjd_jd.jd_from_time(time, timesys='TAI', jdsys=None)[source]

Julian Date for a given time, allowing for time system conversions.

Parameters:

time (int, float, or array-like) – Time in seconds within the selected time system.
timesys (str, optional) – Name of the current time system, one of “UTC”, “TAI”, “TDB”, or “TT”.
jdsys (str, optional) – Name of the time system for JD, one of “UTC”, “TAI”, “TDB”, or “TT”. Leap seconds are included if mjdsys=”UTC”; otherwise, they are ignored. If not specified, jdsys equals timesys.

Returns:

The Julian Date in the jdsys time system.

Return type:

float or array

julian.mjd_jd.mjd_from_day(day)[source]

Modified Julian Date for a given UTC day number.

Parameters:: day (int, float, or array-like) – Day number relative to January 1, 2000.
Returns:: The Modified Julian Date. If day is integral, integers are returned.
Return type:: int, float, or array

julian.mjd_jd.mjd_from_day_sec(day, sec=0)[source]

UTC Modified Julian Date for a given UTC day number and seconds.

Parameters:

day (int, float, or array-like) – Day number relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds within that day, allowing for leap seconds.

Returns:

The Modified Julian Date. If sec is zero, integers are returned.

Return type:

int, float, or array

Notes

The MJD time system has day-length “ticks”, which means that it interacts in a peculiar way with leap seconds. When allowing for leap seconds, some days are longer than others. Nevertheless, this time system is defined such that the value of MJD always increases by one from the end of one day to the end of the next. On days that contain leap seconds, the fractional rate must therefore be a bit slower.

julian.mjd_jd.mjd_from_tai(tai)[source]

Modified Julian Date from TAI seconds.

Parameters:: tai (int, float, or array-like) – Time in seconds TAI.
Returns:: The Modified Julian Date.
Return type:: float or array

julian.mjd_jd.mjd_from_time(time, timesys='TAI', mjdsys=None)[source]

Modified Julian Date for a given time, allowing for time system conversions.

Parameters:

time (int, float, or array-like) – Time in seconds within the selected time system.
timesys (str, optional) – Name of the current time system, one of “UTC”, “TAI”, “TDB”, or “TT”.
mjdsys (str, optional) – Name of the time system for MJD, one of “UTC”, “TAI”, “TDB”, or “TT”. Leap seconds are included if mjdsys=”UTC”; otherwise, they are ignored. If not specified, mjdsys equals timesys.

Returns:

The Modified Julian Date in the mjdsys time system.

Return type:

float or array

julian.mjd_jd.tai_from_jd(jd)[source]

TAI seconds from Julian Date.

Parameters:: jd (int, float, or array) – The Julian Date.
Returns:: Time in seconds TAI.
Return type:: float or array

julian.mjd_jd.tai_from_mjd(mjd)[source]

TAI seconds from Modified Julian Date.

Parameters:: mjd (int, float, or array) – The Modified Julian Date.
Returns:: Time in seconds TAI.
Return type:: float or array

julian.mjd_jd.time_from_jd(jd, timesys='TAI', jdsys=None)[source]

Time in the seconds for a specified JD, allowing for time system conversions.

Parameters:

jd (int, float, or array) – Time in seconds within the specified time system.
timesys (str, optional) – Name of the current time system, one of “UTC”, “TAI”, “TDB”, or “TT”.
jdsys (str, optional) – Name of the time system for MJD, one of “UTC”, “TAI”, “TDB”, or “TT”. Leap seconds are included if mjdsys=”UTC”; otherwise, they are ignored. If not specified, mjdsys equals timesys.

Returns:

Time in seconds in the jdsys time system.

Return type:

float or array

julian.mjd_jd.time_from_mjd(mjd, timesys='TAI', mjdsys=None)[source]

Time in the seconds for a specified MJD, allowing for time system conversions.

Parameters:

mjd (int, float, or array) – Time in seconds within the specified time system.
timesys (str, optional) – Name of the current time system, one of “UTC”, “TAI”, “TDB”, or “TT”.
mjdsys (str, optional) – Name of the time system for MJD, one of “UTC”, “TAI”, “TDB”, or “TT”. Leap seconds are included if mjdsys=”UTC”; otherwise, they are ignored. If not specified, mjdsys equals timesys.

Returns:

Time in seconds in the mjdsys time system.

Return type:

float or array

MJD/JD pyparsing Grammars

julian.mjd_pyparser.mjd_pyparser(*, floating=True, timesys=True, padding=True, embedded=False)[source]

A date parser using MJD, JD, MJED, or JED.

Parameters:

floating (bool, optional) – True to allow fractional days. If false, only an MJD integer date is permitted.
timesys (str, optional) – True to allow an explicit time system in the string via a values such as “MJD”, “MJED”, “JD”, or JED”.
padding (bool, optional) – True to ignore leading or trailing white space.
embedded (bool, optional) – True to allow the time to be followed by additional text.

Returns:

A parser for the selected syntax. Calling the as_list() method on the returned ParseResult object returns a list containing some but not all of these tuples, depending on what appears in the parsed string:

(“YEAR”, type): Either “MJD” or “JD”, indicating that the day value is not part of an actual year.
(“TIMESYS”, name): Time system, either “UTC” or “TDB”.
(“DAY”, day); Day number as either an int or a float.
(“~”, number): The last occurrence of this tuple in the list contains the number of characters matched.

Return type:

pyparsing.ParserElement

Time of Day Functions

julian.time_of_day.hms_from_sec(sec, *, validate=False, leapsecs=True)[source]

Hour, minute and second from seconds into day.

Parameters:

sec (int, float, or array-like) – Elapsed seconds into a day. Values must be between 0 and 86410, where numbers above 86400 are treated as leap seconds.
validate (bool, optional) – True to check that the input values all fall within their valid range.
leapsecs (bool, optional) – True to tolerate leap second values during validation.

Returns:

h (int or array): Hours (0-23).
m (int or array): Minutes (0-59).
s (int, float, or array): Seconds. Values are integral if sec is integral.

Return type:

tuple (h, m, s)

Raises:

JulianValidateFailure – If validate is True and any value of sec is outside the valid range.

julian.time_of_day.hms_microsec_from_sec(sec, *, validate=False, leapsecs=True)[source]

Hour, minute, second, and microsecond from seconds into day.

This function is provided to simplify conversions to datetime objects, where fractional seconds are defined by an integer value of microseconds. All returned values are integral, with the number of microseconds rounded if necessary.

Parameters:

sec (int, float, or array-like) – Elapsed seconds into a day. Values must be between 0 and 86410, where numbers above 86400 are treated as leap seconds.
validate (bool, optional) – True to check that the input values all fall within their valid range.
leapsecs (bool, optional) – True to tolerate leap second values during validation.

Returns:

h (int or array): Hours (0-23).
m (int or array): Minutes (0-59).
s (int or array): Seconds (0-69).
microsec (int or array): Microseconds (0-999999).

Return type:

tuple (h, m, s, microsec)

Raises:

JulianValidateFailure – If validate is True and any value of sec is outside the valid range.

Notes

To construct a datetime.time, use:

datetime.time(*hms_microsec_from_sec(sec))

To construct a datetime.datetime from a day number and seconds value, use:

datetime.datetime(*ymd_from_day(day), *hms_microsec_from_sec(sec))

julian.time_of_day.sec_from_hms(h, m, s, microsec=0, *, validate=False, leapsecs=True)[source]

Seconds into day from hour, minute and second.

Parameters:

h (int, float, or array-like) – Hour (0-23).
m (int, float, or array-like) – Minute (0-59).
s (int, float, or array-like) – Second (0-69), with values > 59 implying leap seconds (if leapsecs is True).
microsec (int, float, or array-like, optional) – Microseconds (0-999999), provided as an alternative to specifying fractional seconds and to simplify conversions from datetime objects.
validate (bool, optional) – True to check that the input values all fall within their valid range.
leapsecs (bool, optional) – True to tolerate leap second values during validation.

Returns:

Elapsed seconds. Values are integral if h, m, and s are all integral.

Return type:

int, float, or array

Raises:

JulianValidateFailure – If validate is True and any input values are out of range.

NotesL

Time Parsers

julian.time_parsers.sec_from_string(string, leapsecs=True, ampm=True, timezones=False, floating=False)[source]

Time of day in seconds, based on the parsing of a free-form string.

Parameters:

string (str) – String to interpret.
leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
floating (bool, optional) – True to recognize time specified using floating-point hours or minutes.

Returns:

sec (int or float): Elapsed seconds since the beginning of the day, after any time zone offset has been applied.
dday (int): An offset in days due to the possible presence of the time zone, included if timezones is True.

Return type:

sec or tuple (sec, dday)

Raises:

JulianParseException – If string was not recognized as a valid time expression.
JulianParseException – If the time string contains invalid or contradictory information.

julian.time_parsers.secs_in_strings(strings, leapsecs=True, ampm=True, timezones=False, floating=False, substrings=False, first=False)[source]

List of second counts representing times of day, obtained by searching one or more strings for patterns that look like formatted times.

Parameters:

strings (list, tuple, or array) – Strings to interpret.
leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
floating (bool, optional) – True to recognize time specified using floating-point hours or minutes.
substrings (bool, optional) – True to also return the substring containing each identified time.
first (bool, optional) – True to return the first time value found rather than a list of values. In this case, None is returned if no time is found rather than an empty list.

Returns:

If first is False, a list of tuples is returned; otherwise, a single tuple is returned or None if no time was found. Within this tuple:

sec (int or float): Elapsed seconds since the beginning of the day, after any time zone offset has been applied.
dday (int): An offset in days due to the possible presence of a time zone, included if timezones is True.
substring (str): The substring containing the text that was interpreted to represent this time; included if substrings is True.

Return type:

tuple (sec[, dday][, substring]), list[tuple], or None

Raises:

JulianValidateFailure – If a matched time string contains invalid or contradictory information.

Time pyparsing Grammars

julian.time_pyparser.time_pyparser(*, leapsecs=False, ampm=False, timezones=False, timesys=False, floating=False, iso_only=False, padding=True, embedded=False)[source]

A time pyparser.

Parameters:

leapsecs (bool, optional) – True to recognize leap seconds.
ampm (bool, optional) – True to recognize “am” and “pm” suffixes.
timezones (bool, optional) – True to recognize and interpret time zones. If True, returned values are adjusted to UTC.
timesys (bool, optional) – True to recognize an embedded time system such as “UTC”, “TAI”, etc.
floating (bool, optional) – True to allow times specified using floating-point values of hours or minutes.
iso_only (bool, optional) – Require an ISO 8601:1988-compatible time string; ignore ampm, timesys, and floating options.
padding (bool, optional) – True to ignore leading or trailing white space.
embedded (bool, optional) – True to allow the time to be followed by additional text.

Returns:

A parser for the selected syntax. Calling the as_list() method on the returned ParseResult object returns a list containing some but not all of these tuples:

(“HOUR”, hour): Hour if specified, 0-23, as an int or possibly a float. Hours am/pm are converted to the range 0-23 automatically.
(“MINUTE”, minute): Minute if specified, integer or float.
(“SECOND”, second): Second if specified, integer or float.
(“LEAPSEC”, True): Present and True if this is a leap second.
(“TZ”, tz_name): Name of the time zone if specified.
(“TZMIN”, tzmin): Offset of the time zone in minutes.
(“TIMESYS”, name): Time system if specified: “UTC”, “TAI”, “TDB”, or “TDT”.
(“~”, number): The last occurrence of this tuple in the list contains the number of characters matched.

Return type:

pyparsing.ParserElement

UTC/TAI/TDB/TT Conversions

julian.utc_tai_tdb_tt.day_sec_from_tai(tai)[source]

Convert time in seconds TAI to day number and elapsed seconds into that day.

Parameters:

tai (int, float, or array-like) – Time in seconds TAI.

Returns:

day (int or array): Day number relative to January 1, 2000 UTC.
sec (int, float, or array): Elapsed seconds since beginning of day, including possible leap seconds.

Return type:

tuple (day, sec)

julian.utc_tai_tdb_tt.day_sec_from_time(time, timesys='TAI', *, leapsecs=True)[source]

Convert a time in any time system, to UTC day number and seconds.

Parameters:

time (int, float, or array-like) – Time in seconds.
timesys (str) – Name of the current time system, “UTC”, “TAI”, “TDB”, or “TT”.
leapsecs (bool, optional) – If True, UTC day and second values are returned. Otherwise, the day and seconds are calculated without regard to leap seconds and without any time system conversion. This can be useful for situations where a date is referred to as, for example, an “ephemeris date” rather than as a calendar date.

Returns:

day (int or array): Day number relative to January 1, 2000 UTC.
sec (int, float, or array): Elapsed seconds since beginning of day, including possible leap seconds.

Return type:

tuple (day, sec)

julian.utc_tai_tdb_tt.day_sec_from_utc(utc)[source]

Convert cumulative time in seconds UTC to day number and elapsed seconds.

Parameters:

utc (int, float, or array-like) – Time in seconds UTC.

Returns:

day (int or array): Day number relative to January 1, 2000.
sec (int, float, or array): Elapsed seconds since beginning of day, including possible leap seconds. Values will be integral if utc is integral.

Return type:

tuple (day, sec)

Notes

The UTC time system is defined to equal zero at noon on January 1, 2000. It differs from TAI by a fixed offset of 32 seconds for all dates after the adoption of the leap second system in 1972. For earlier dates, when using the “PRE-1972” or “CANON” models, UTC uses “rubber seconds”, which can expand or shrink as necessary relative to TAI in order to ensure that every day before 1972 contained exactly 86,400 seconds.

julian.utc_tai_tdb_tt.set_tai_origin(origin='NOON')[source]

Set the zeros of the TAI and UTC time system to either noon or midnight on January 1, 2000.

DEPRECATED feature.

Parameters:: origin (str) – Origin of the TAI and UTC time systems, either “NOON” or “MIDNIGHT”. If “NOON”, UTC=0 and TAI=32 at noon on January 1, 2000 UTC. This is consistent with the definition of TAI within the SPICE toolkit. If “MIDNIGHT”, UTC=0 and TAI=32 at midnight on January 1, 2000 UTC.

Notes

The earlier version of this module measured UTC and TAI from ~ midnight on January 1, 2000. The preferred origin for the time systems is 12 hours later. Use this function to reproduce earlier behavior if you are concerned about the matching values of TAI or UTC from an earlier version of the Julian Library.

The TDB and TT time systems have always use the “NOON” origin exclusively.

julian.utc_tai_tdb_tt.tai_from_day(day, sec=0)[source]

Convert day number to TAI seconds.

This is an alternative name for tai_from_day_sec().

Parameters:

day (int or array-like) – Day number relative to January 1, 2000 UTC.
sec (int, float, or array-like) – Elapsed seconds since beginning of day, including possible leap seconds.

Returns:

Time in seconds TAI. If sec is integral and “rubber seconds” are not in use, this will also be integral.

Return type:

int, float, or array

julian.utc_tai_tdb_tt.tai_from_day_sec(day, sec=0)[source]

Convert day number and elapsed seconds to TAI time.

Parameters:

day (int or array-like) – Day number relative to January 1, 2000 UTC.
sec (int, float, or array-like) – Elapsed seconds since beginning of day, including possible leap seconds.

Returns:

Time in seconds TAI. If sec is integral and “rubber seconds” are not in use, this will also be integral.

Return type:

int, float, or array

julian.utc_tai_tdb_tt.tai_from_tdb(tdb)[source]

Convert time in seconds TDB to TAI.

Parameters:: tdb (float or array-like) – Time in seconds TDB.
Returns:: Time in seconds TAI.
Return type:: tai (float or array)

julian.utc_tai_tdb_tt.tai_from_tdt(tt)[source]

“DEPRECATED function name; use tai_from_tt.

Parameters:: tt (int, float or array-like) – Time in seconds TT.
Returns:: Time in seconds TAI.
Return type:: tai (float or array)

julian.utc_tai_tdb_tt.tai_from_tt(tt)[source]

Convert time in seconds TT to TAI.

Parameters:: tt (int, float or array-like) – Time in seconds TT.
Returns:: Time in seconds TAI.
Return type:: tai (float or array)

julian.utc_tai_tdb_tt.tai_from_utc(utc)[source]

Convert time in seconds UTC to TAI.

Parameters:: utc (int, float, or array-like) – Time in seconds UTC.
Returns:: Time in seconds TAI. If utc is integral and UTC “rubber seconds” are not in use, this will also be integral.
Return type:: int, float, or array

Notes

The UTC time system is defined to equal zero at noon on January 1, 2000. It differs from TAI by a fixed offset of 32 seconds for all dates after the adoption of the leap second system in 1972. For earlier dates, when using the “PRE-1972” or “CANON” models, UTC uses “rubber seconds”, which can expand or shrink as necessary relative to TAI in order to ensure that every day before 1972 contained exactly 86,400 seconds.

julian.utc_tai_tdb_tt.tdb_from_tai(tai, *, iters=2)[source]

Convert time in seconds TAI to TDB.

Parameters:

tai (int, float, or array-like) – Time in seconds tai.
iters (int, optional) – Number of iterations to achieve desired precision. A value of 2 provides complete floating-point convergence.

Returns:

Time in seconds TDB.

Return type:

tdb (float or array)

julian.utc_tai_tdb_tt.tdt_from_tai(tai)[source]

DEPRECATED function name; use tt_from_tai.

Parameters:: tai (int, float or array-like) – Time in seconds TAI.
Returns:: Time in seconds TT.
Return type:: tt (float or array)

julian.utc_tai_tdb_tt.time_from_day_sec(day, sec, timesys='TAI', *, leapsecs=True)[source]

Convert UTC day number and elapsed seconds to time in seconds in the specified time system.

Parameters:

day (int or array-like) – Day number relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds since beginning of day, including possible leap seconds.
timesys (str) – Name of the current time system, “UTC”, “TAI”, “TDB”, or “TT”.
leapsecs (bool, optional) – If True, day and sec values are interpreted as UTC values. Otherwise, the day and seconds are converted to time without regard to leap seconds, and no time system conversion is performed. This can be useful for situations where a date is referred to as, for example, an “ephemeris date” rather than as a calendar date.

Returns:

Time in seconds in the specified time system.

Return type:

int, float, or array

julian.utc_tai_tdb_tt.time_from_time(time, timesys, newsys='TAI')[source]

Convert a time from one time system to another.

Parameters:

time (int, float, or array-like) – Time in seconds.
timesys (str) – Name of the current time system, “UTC”, “TAI”, “TDB”, or “TT”.
newsys (str) – Name of the desired time system, “UTC”, “TAI”, “TDB”, or “TT”.

Returns:

Time in seconds in the specified time system.

Return type:

int, float, or array

julian.utc_tai_tdb_tt.tt_from_tai(tai)[source]

Convert time in seconds TAI to TT.

Parameters:: tai (int, float or array-like) – Time in seconds TAI.
Returns:: Time in seconds TT.
Return type:: tt (float or array)

julian.utc_tai_tdb_tt.utc_from_day(day, sec=0)[source]

Convert UTC day number to cumulative elapsed UTC seconds.

This is an alternative name for utc_from_day_sec().

Parameters:

day (int or array-like) – Day number relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds since beginning of day, including possible leap seconds.

Returns:

Time in seconds UTC. If sec is integral, this will also be integral.

Return type:

int, float, or array

Notes

The UTC time system is defined to equal zero at noon on January 1, 2000. It differs from TAI by a fixed offset of 32 seconds for all dates after the adoption of the leap second system in 1972. For earlier dates, when using the “PRE-1972” or “CANON” models, UTC uses “rubber seconds”, which can expand or shrink as necessary relative to TAI in order to ensure that every day before 1972 contained exactly 86,400 seconds.

julian.utc_tai_tdb_tt.utc_from_day_sec(day, sec=0)[source]

Convert UTC day number and elapsed seconds to cumulative elapsed UTC seconds.

Parameters:

day (int or array-like) – Day number relative to January 1, 2000.
sec (int, float, or array-like) – Elapsed seconds since beginning of day, including possible leap seconds.

Returns:

Time in elapsed seconds. If sec is integral, this will also be integral.

Return type:

int, float, or array

Notes

The UTC time system is defined to equal zero at noon on January 1, 2000. It differs from TAI by a fixed offset of 32 seconds for all dates after the adoption of the leap second system in 1972. For earlier dates, when using the “PRE-1972” or “CANON” models, UTC uses “rubber seconds”, which can expand or shrink as necessary relative to TAI in order to ensure that every day before 1972 contained exactly 86,400 seconds.

julian.utc_tai_tdb_tt.utc_from_tai(tai)[source]

Convert time in seconds TAI to UTC.

Parameters:: tai (int, float, or array-like) – Time in seconds TAI.
Returns:: Time in seconds UTC. If tai is integral and “rubber seconds” are not in use, this will also be integral.
Return type:: int, float, or array

Notes

The UTC time system is defined to equal zero at noon on January 1, 2000. It differs from TAI by a fixed offset of 32 seconds for all dates after the adoption of the leap second system in 1972. For earlier dates, when using the “PRE-1972” or “CANON” models, UTC uses “rubber seconds”, which can expand or shrink as necessary relative to TAI in order to ensure that every day before 1972 contained exactly 86,400 seconds.

Exceptions

exception julian._exceptions.JulianParseException[source]: A subclass of ValueError, raised when a string cannot be parsed.

exception julian._exceptions.JulianValidateFailure[source]: A subclass of ValueError, raised when a numeric value is invalid.

Julian Module

Julian Library

Calendar Operations

Time Systems

Julian Dates

Leap Second Handling

Date/Time Formatting

String Parsing and Searching

Calendar functions

Date Parsers

Date pyparsing Grammars

Date-Time Parsers

Date-Time pyparsing Grammars

Formatters

ISO Parsers

Leap Seconds Support

MJD/JD Conversions

MJD/JD pyparsing Grammars

Time of Day Functions

Time Parsers

Time pyparsing Grammars

UTC/TAI/TDB/TT Conversions

Exceptions

`Julian` Module