[](https://github.com/SETI/rms-julian/releases)
[](https://github.com/SETI/rms-julian/releases)
[](https://github.com/SETI/rms-julian/actions)
[](https://codecov.io/gh/SETI/rms-julian)
<br />
[](https://pypi.org/project/rms-julian)
[](https://pypi.org/project/rms-julian)
[](https://pypi.org/project/rms-julian)
[](https://pypi.org/project/rms-julian)
<br />
[](https://github.com/SETI/rms-julian/commits/main/)
[](https://github.com/SETI/rms-julian/commits/main/)
[](https://github.com/SETI/rms-julian/commits/main/)
<br />
[](https://github.com/SETI/rms-julian/issues)
[](https://github.com/SETI/rms-julian/issues)
[](https://github.com/SETI/rms-julian/pulls)
[](https://github.com/SETI/rms-julian/pulls)
<br />
[](https://github.com/SETI/rms-julian/stargazers)
# rms-julian
Supported versions: Python >= 3.7
# PDS Ring-Moon Systems Node, SETI Institute
# Julian Library, version 2.0
This is a large set of routines for handing date and time conversions. Compared to other
date/time libraries in Python, including CSPYCE, it has these features:
- It handles the time systems Coordinated Universal Time (UTC), International Atomic Time
(TAI), Barycentric Dynamical Time (TDB), and Terrestrial Time (TT, previously called
Terrestrial Dynamical Time or TDT), 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](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](https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html).
The numerical details are here:
[https://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html](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 "scrape" occurrences of 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_ym()
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. Internally, TAI times serve as the intermediary between the different
time systems (TAI, UTC, TDB, and TT). 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.
### 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.
### PARSING
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 "scrape" dates and times from almost 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()
time_pyparser()
Raw data
{
"_id": null,
"home_page": null,
"name": "rms-julian",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Robert S. French\" <rfrench@seti.org>",
"keywords": "julian",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/14/ba/2c6e3d081e03b0dd403cad21d2cf04690045636293fc69b59c3c73fea084/rms_julian-2.0.2.tar.gz",
"platform": null,
"description": "[](https://github.com/SETI/rms-julian/releases)\n[](https://github.com/SETI/rms-julian/releases)\n[](https://github.com/SETI/rms-julian/actions)\n[](https://codecov.io/gh/SETI/rms-julian)\n<br />\n[](https://pypi.org/project/rms-julian)\n[](https://pypi.org/project/rms-julian)\n[](https://pypi.org/project/rms-julian)\n[](https://pypi.org/project/rms-julian)\n<br />\n[](https://github.com/SETI/rms-julian/commits/main/)\n[](https://github.com/SETI/rms-julian/commits/main/)\n[](https://github.com/SETI/rms-julian/commits/main/)\n<br />\n[](https://github.com/SETI/rms-julian/issues)\n[](https://github.com/SETI/rms-julian/issues)\n[](https://github.com/SETI/rms-julian/pulls)\n[](https://github.com/SETI/rms-julian/pulls)\n<br />\n\n[](https://github.com/SETI/rms-julian/stargazers)\n\n\n# rms-julian\n\nSupported versions: Python >= 3.7\n\n# PDS Ring-Moon Systems Node, SETI Institute\n# Julian Library, version 2.0\n\nThis is a large set of routines for handing date and time conversions. Compared to other\ndate/time libraries in Python, including CSPYCE, it has these features:\n\n- It handles the time systems Coordinated Universal Time (UTC), International Atomic Time\n (TAI), Barycentric Dynamical Time (TDB), and Terrestrial Time (TT, previously called\n Terrestrial Dynamical Time or TDT), properly accounting for leap seconds.\n\n- Any time can be expressed as a running count of elapsed seconds from a defined epoch, as\n a calendar date, using Julian Date (JD), or using Modified Julian Date (MJD).\n\n- Nearly all functions can process arrays of dates and times all at once, not just as\n individual values. This can provide a substantial performance boost compared to using\n iteration, especially when parsing or formatting columns of dates for a table file.\n\n- It provides options for how to interpret times before 1972, when the current version of\n the UTC time system was first implemented. Since 1972, leap seconds have been used to\n keep TAI in sync with UTC, ensuring that the UTC time never differs from UT1, the time\n system defined by the Earth's rotation, by more than ~ 1 second. Between 1958 and 1972,\n the UTC second was redefined as a \"rubber second\", which would stretch or shrink as\n necessary to ensure that every mean solar day contained exactly 86,400 UT seconds; see\n [https://hpiers.obspm.fr/eop-pc/index.php?index=TAI-UTC_tab](https://hpiers.obspm.fr/eop-pc/index.php?index=TAI-UTC_tab).\n\n Before 1958, we use UT1 in place of UTC, employing a model for the long-term variations\n in Earth's rotation as documented for the \"Five Millennium Canon of Solar Eclipses:\n -1999 to +3000; see\n [https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html](https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html).\n\n The numerical details are here:\n [https://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html](https://eclipse.gsfc.nasa.gov/SEcat5/deltatpoly.html).\n\n This model can also be applied to future dates.\n\n- It supports both the modern (Gregorian) calendar and the older Julian calendar. The\n transition date can be defined by the user, or else the Julian calendar can be\n suppressed entirely.\n\n- A general parser is able to interpret almost arbitrary date-time strings correctly. This\n parser can also be used to \"scrape\" occurrences of dates and times from arbitrary text.\n\n\n### CALENDAR OPERATIONS\n\nEvery date is represented by an integer \"day\" value, where day = 0 on January 1, 2000.\nVarious functions are provided to convert between day values and year, month, day, or day\nof year:\n\n day_from_ymd()\n day_from_yd()\n ymd_from_day()\n yd_from_day()\n\nYears prior to 1 CE are specified using the \"astronomical year\", which includes a year\nzero. As a result, 1 BCE is specified as year 0, 2 BCE as year -1, 4713 BCE as year -4712,\netc. Note that there is some historical uncertainty about which years were recognized as\nleap years in Rome between the adoption of the Julian calendar in 46 BCE and about 8 CE.\nFor simplicity, we follow the convention that the Julian calendar extended backward\nindefinitely, so all all years divisible by four, including 4 CE, 0 (1 BCE), -4 (5 BCE),\n-8 (9 BCE), etc., were leap years.\n\nMonths are referred to by integers 1-12, 1 for January and 12 for December.\n\nDay numbers within months are 1-31; day numbers within years are 1-366.\n\nFunctions are provided to determine the number of days in a specified month or year:\n\n days_in_year()\n days_in_ym()\n\nUse the function `set_gregorian_start()` to specify the (Gregorian) year, month, and day for\nthe transition from the earlier Julian calendar to the modern Gregorian calendar. The\ndefault start date of the Gregorian calendar is October 15, 1582, when this calendar was\nfirst adopted in much of Europe. However, the user is free to modify this date; for\nexample, Britain adopted the Gregorian calendar on September 14, 1752.\n\nNote that most calendar functions support an input parameter \"proleptic\", taking a value\nof `True` or `False`. If True, all calendar dates are proleptic (extrapolated backward\nassuming the modern calendar), regardless of which calendar was in effect at the time.\n\n\n### TIME SYSTEMS\n\nAll times are represented by numbers representing seconds past a specified epoch on\nJanuary 1, 2000. Internally, TAI times serve as the intermediary between the different\ntime systems (TAI, UTC, TDB, and TT). Conversions are straightforward, using:\n\n tai_from_utc()\n utc_from_tai()\n tai_from_tdb()\n tdb_from_tai()\n tai_from_tt()\n tt_from_tai()\n\nAlternatively, the more general function `time_from_time()` lets you specify the initial and\nfinal time systems of the conversion.\n\nYou can also specify a time using an integer day plus the number of elapsed seconds on\nthat day, and then convert between these values and any time system:\n\n day_sec_from_utc()\n day_sec_from_tai()\n tai_from_day()\n tai_from_day_sec()\n utc_from_day()\n utc_from_day_sec()\n\nAlternatively, the more general functions `day_sec_from_time()` and `time_from_day_sec()`\nlet you specify the initial and final time systems.\n\n\n### JULIAN DATES\n\nSimilarly, Julian dates and Modified Julian Dates can be converted to times using any time\nsystem:\n\n jd_from_time()\n time_from_jd()\n mjd_from_time()\n time_from_mjd()\n jd_from_day_sec()\n day_sec_from_jd()\n mjd_from_day_sec()\n day_sec_from_mjd()\n\nYou can also convert directly between integer MJD and integer day numbers using:\n\n mjd_from_day()\n day_from_mjd()\n\n\n### LEAP SECOND HANDLING\n\nIn 1972, the UTC time system began using leap seconds to keep TAI times in sync with mean\nsolar time to a precision of ~ 1 second. We provide several methods to allow the user to\nkeep the leap second list up to date.\n\nIf the environment variable `SPICE_LSK_FILEPATH` is defined, then this SPICE leapseconds\nkernel is read at startup. Otherwise, leap seconds through 2020 are always included, as\ndefined in SPICE kernel file \"`naif0012.tls`\". You can also call the function `load_lsk()`\ndirectly.\n\nAlternatively, use `insert_leap_second()` to augment the list with additional leap seconds\n(positive or negative).\n\nUse `seconds_on_day()` to determine the length in seconds of a given day; use\n`leapsecs_on_day()` or `leapsecs_from_ymd()` to determine the cumulative number of leap\nseconds on a given date.\n\nUse `set_ut_model()` to define how to handle times before 1972 and into the future, outside\nthe duration of the current UTC leap second system.\n\n\n### FORMATTING\n\nSeveral functions are provided to express dates or times as formatted character strings:\n\n format_day()\n format_day_sec()\n format_sec()\n format_tai()\n iso_from_tai()\n\nMost variations of the ISO 8601:1988 format are supported.\n\nNote that these functions can produce strings, bytestrings, or arbitrary arrays thereof.\nThe functions operate on the entire array all at once, and can therefore be much faster\nthan making individual calls over and over. For example, note that one could provide a\nNumPy memmap as input to these functions and it would write content directly into a large\nASCII table, avoiding any conversion to/from Unicode.\n\n\n### PARSING\n\nWe provide functions for the very fast parsing of identically-formatted strings or\nbytestrings that represent dates, times or both:\n\n day_from_iso()\n day_sec_from_iso()\n sec_from_iso()\n tai_from_iso()\n tdb_from_iso()\n time_from_iso()\n\nThese functions recognize most variations of the ISO 8601:1988 format, and are ideal for\ninterpreting date and time columns from large ASCII tables.\n\nMore general parsers are provided for interpreting individual dates and times in almost\narbitrary formats:\n\n day_from_string()\n day_sec_from_string()\n sec_from_string()\n\nThese same parsers can also be invoked to \"scrape\" dates and times from almost arbitrary\ntext:\n\n days_in_strings()\n day_sec_in_strings()\n secs_in_strings()\n\nTime zones are recognized, including most standard abbreviations.\n\nFor users familiar with the pyparsing module, we provide functions that generate parsers\nfor a wide variety of special requirements. See:\n\n date_pyparser()\n datetime_pyparser()\n time_pyparser()\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Routines for converting to and from Julian dates",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/SETI/rms-julian",
"Issues": "https://github.com/SETI/rms-julian/issues",
"Repository": "https://github.com/SETI/rms-julian",
"Source": "https://github.com/SETI/rms-julian"
},
"split_keywords": [
"julian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e9e927cea0c5220d6eade2bd2840ee141a1abae866ebc8d8d762ae335810d6ee",
"md5": "4e3238078914f81ef0692e3028e72bd2",
"sha256": "0819dbc0b058a208f676e960cc795bb864a8e0d809aca13b3ad9d01d88e4bb5c"
},
"downloads": -1,
"filename": "rms_julian-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e3238078914f81ef0692e3028e72bd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74773,
"upload_time": "2024-05-14T19:21:07",
"upload_time_iso_8601": "2024-05-14T19:21:07.159169Z",
"url": "https://files.pythonhosted.org/packages/e9/e9/27cea0c5220d6eade2bd2840ee141a1abae866ebc8d8d762ae335810d6ee/rms_julian-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "14ba2c6e3d081e03b0dd403cad21d2cf04690045636293fc69b59c3c73fea084",
"md5": "1ab6f68f4bc933bad2ca933888101987",
"sha256": "5b05fabec7e389bf2c763b1136481766ed0f5e02873a2af1e20bd21f729eca8f"
},
"downloads": -1,
"filename": "rms_julian-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1ab6f68f4bc933bad2ca933888101987",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 176334,
"upload_time": "2024-05-14T19:21:08",
"upload_time_iso_8601": "2024-05-14T19:21:08.500773Z",
"url": "https://files.pythonhosted.org/packages/14/ba/2c6e3d081e03b0dd403cad21d2cf04690045636293fc69b59c3c73fea084/rms_julian-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-14 19:21:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SETI",
"github_project": "rms-julian",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "coverage",
"specs": []
},
{
"name": "cspyce",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "pyparsing",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "rms-textkernel",
"specs": []
}
],
"lcname": "rms-julian"
}
JSON
