time

Utilities for calculating time operations

Can convert delta time from seconds since an epoch to time since a different epoch

Can calculate the time in days since epoch from calendar dates

Calculates the difference between dynamic time and universal time (TT - UT1) following Richard Ray’s PERTH3 algorithms

Can count the number of leap seconds between a given GPS time and UTC

Syncs leap second files with NIST servers

Updates differences between universal time (UT) and dynamic time (TT)

Calling Sequence

Count the number of leap seconds between a GPS time and UTC

import pyTMD.time
leap_seconds = pyTMD.time.count_leap_seconds(gps_seconds)

Convert a time from seconds since 1980-01-06T00:00:00 to Modified Julian Days (MJD)

import pyTMD.time
MJD = pyTMD.time.convert_delta_time(delta_time, epoch1=(1980,1,6,0,0,0),
    epoch2=(1858,11,17,0,0,0), scale=1.0/86400.0)

Convert a calendar date into Modified Julian Days

import pyTMD.time
MJD = pyTMD.time.convert_calendar_dates(YEAR,MONTH,DAY,hour=HOUR,
    minute=MINUTE,second=SECOND,epoch=(1858,11,17,0,0,0))

Source code

General Methods

pyTMD.time.parse(date_string: str)[source]

Parse a date string and convert to a naive datetime object in UTC

Parameters

date_string: str: formatted time string

Returns

date: obj: output datetime object

pyTMD.time.parse_date_string(date_string: str)[source]

Parse a date string of the form

time-units since yyyy-mm-dd hh:mm:ss
yyyy-mm-dd hh:mm:ss for exact calendar dates

Parameters

date_string: str: time-units since yyyy-mm-dd hh:mm:ss

Returns

epoch: list: epoch of delta_time
conversion_factor: float: multiplication factor to convert to seconds

pyTMD.time.split_date_string(date_string: str)[source]

Split a date string into units and epoch

Parameters

date_string: str: time-units since yyyy-mm-dd hh:mm:ss

pyTMD.time.datetime_to_list(date)[source]

Convert a datetime object into a list

Parameters

date: obj: Input datetime object to convert

Returns

date: list: [year,month,day,hour,minute,second]

pyTMD.time.calendar_days(year: int | float | numpy.ndarray) → ndarray[source]

Calculates the number of days per month for a given year

Parameters

year: int, float or np.ndarray: calendar year

Returns

dpm: np.ndarray: number of days for each month

pyTMD.time.convert_datetime(date: float | numpy.ndarray, epoch: str | tuple | list | numpy.datetime64 = (1970, 1, 1, 0, 0, 0))[source]

Convert a numpy datetime array to seconds since epoch

Parameters

date: np.ndarray: numpy datetime array
epoch: str, tuple, list, np.ndarray, default (1970,1,1,0,0,0): epoch for output delta_time

Returns

delta_time: float: seconds since epoch

Convert delta time from seconds since epoch1 to time since epoch2

Parameters

delta_time: np.ndarray: seconds since epoch1
epoch1: str, tuple, list or NoneType, default None: epoch for input delta_time
epoch2: str, tuple, list or NoneType, default None: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

pyTMD.time.convert_calendar_dates(year: ndarray, month: ndarray, day: ndarray, hour: numpy.ndarray | float = 0.0, minute: numpy.ndarray | float = 0.0, second: numpy.ndarray | float = 0.0, epoch: tuple | list | numpy.datetime64 = (1992, 1, 1, 0, 0, 0), scale: float = 1.0) → ndarray[source]

Calculate the time in units since epoch from calendar dates

Parameters

year: np.ndarray: calendar year
month: np.ndarray: month of the year
day: np.ndarray: day of the month
hour: np.ndarray or float, default 0.0: hour of the day
minute: np.ndarray or float, default 0.0: minute of the hour
second: np.ndarray or float, default 0.0: second of the minute
epoch: tuple or list, default pyTMD.time._tide_epoch: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

Returns

delta_time: np.ndarray: time since epoch

Converts from calendar date into decimal years taking into account leap years

Parameters

year: np.ndarray: calendar year
month: np.ndarray: calendar month
day: np.ndarray, float or NoneType, default None: day of the month
hour: np.ndarray, float or NoneType, default None: hour of the day
minute: np.ndarray, float or NoneType, default None: minute of the hour
second: np.ndarray, float or NoneType, default None: second of the minute
DofY: np.ndarray, float or NoneType, default None: day of the year

Returns

t_date: np.ndarray: date in decimal-year format

References

1: N. Dershowitz, and E. M. Reingold. Calendrical Calculations, Cambridge: Cambridge University Press, (2008).

pyTMD.time.convert_julian(JD: ndarray, **kwargs)[source]

Converts from Julian day to calendar date and time

Parameters

JD: np.ndarray

Julian Day (days since 01-01-4713 BCE at 12:00:00)

astype: str or NoneType, default None

convert output to variable type

format: str, default ‘dict’

format of output variables

'dict': dictionary with variable keys

'tuple': tuple in most-to-least-significant order

'zip': aggregated variable sets

Returns

year: np.ndarray: calendar year
month: np.ndarray: calendar month
day: np.ndarray: day of the month
hour: np.ndarray: hour of the day
minute: np.ndarray: minute of the hour
second: np.ndarray: second of the minute

References

1: W. H. Press, Numerical Recipes in C, Brian P. Flannery, Saul A. Teukolsky, and William T. Vetterling. Cambridge University Press, (1988).
2: D. A. Hatcher, “Simple Formulae for Julian Day Numbers and Calendar Dates”, Quarterly Journal of the Royal Astronomical Society, 25(1), 1984.

class pyTMD.time.timescale(MJD=None)[source]

Class for converting between time scales

Attributes

leaps: np.ndarray: Number of leap seconds
MJD: np.ndarray: Modified Julian Days

from_deltatime(delta_time: ndarray, epoch: str | tuple | list | numpy.ndarray, standard: str = 'UTC')[source]

Converts a delta time array and into a timescale object

Parameters

delta_time: np.ndarray: seconds since epoch
epoch: str, uuple, list or np.ndarray: epoch for input delta_time
standard: str, default ‘UTC’: time standard for input delta_time

from_datetime(dtime: ndarray)[source]

Reads a datetime array and converts into a timescale object

Parameters

dtime: np.ndarray: numpy.datetime64 array

to_deltatime(epoch: str | tuple | list | numpy.ndarray, scale: float = 1.0)[source]

Convert a timescale object to a delta time array

Parameters

epoch: str, tuple, list, or np.ndarray: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

Returns

delta_time: np.ndarray: time since epoch

to_datetime()[source]

Convert a timescale object to a datetime array

Returns

dtime: np.ndarray: numpy.datetime64 array

to_string(unit: str = 's', **kwargs)[source]

Convert a timescale object to a formatted string array

Parameters

unit: str, default ‘s’: datetime unit for output string array
**kwargs: dict: keyword arguments for datetime formatting

polynomial_sum(coefficients: list | numpy.ndarray, t: ndarray)[source]

Calculates the sum of a polynomial function of time

Parameters

coefficients: list or np.ndarray: leading coefficient of polynomials of increasing order
t: np.ndarray: delta time in units for a given astronomical longitudes calculation

era: Earth Rotation Angle (ERA) in degrees

gha: Greenwich Hour Angle (GHA) in degrees

gmst: Greenwich Mean Sidereal Time (GMST) in fractions of day

J2000: Seconds since 2000-01-01T12:00:00

st: Greenwich Mean Sidereal Time (GMST) in fractions of a day from the Equinox Method

tide: Days since 1992-01-01T00:00:00

tt: Dynamic Time (TT) as Julian Days

tt_ut1: Difference between universal time (UT) and dynamical time (TT)

T: Centuries since 2000-01-01T12:00:00

ut1: Universal Time (UT) as Julian Days

property turnasec: Arcseconds in a full turn

property asec2rad: Arcseconds to radians

property masec2rad: Microarcseconds to radians

property dtype: Main data type of timescale object

property shape: Dimensions of timescale object

property ndim: Number of dimensions in timescale object

pyTMD.time.interpolate_delta_time(delta_file: str | pathlib.Path | None, idays: ndarray)[source]

Calculates the difference between universal time (UT) and dynamical time (TT)

Parameters

delta_file: str or Pathlib.Path: file containing the delta times
idays: float: input times to interpolate (days since 1992-01-01T00:00:00)

Returns

deltat: float: delta time at the input time

References

1

Meeus, Astronomical Algorithms, 2nd edition, 477 pp., (1998).

pyTMD.time.count_leap_seconds(GPS_Time: numpy.ndarray | float, truncate: bool = True)[source]

Counts the number of leap seconds between a given GPS time and UTC

Parameters

GPS_Time: np.ndarray or float: seconds since January 6, 1980 at 00:00:00
truncate: bool, default True: Reduce list of leap seconds to positive GPS times

Returns

n_leaps: float: number of elapsed leap seconds

pyTMD.time.get_leap_seconds(truncate: bool = True)[source]

Gets a list of GPS times for when leap seconds occurred

Parameters

truncate: bool, default True: Reduce list of leap seconds to positive GPS times

Returns

GPS time: float: GPS seconds when leap seconds occurred

pyTMD.time.update_leap_seconds(timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to servers to download leap-seconds.list files from NIST servers

https://www.nist.gov/pml/time-and-frequency-division/leap-seconds-faqs

Servers and Mirrors

Parameters

timeout: int or None, default 20: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

pyTMD.time.merge_delta_time(username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Connects to servers to download historic_deltat.data and deltat.data files

Reads IERS Bulletin-A produced iers_deltat.data files

Creates a merged file combining the historic, monthly and daily files

Long-term Delta T

https://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term

Parameters

username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.append_delta_time(verbose: bool = False, mode: oct = 509)[source]

Appends merged delta time file with values from latest Bulletin-A file

Parameters

verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.merge_bulletin_a_files(username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Attempt to connects to the IERS server and the CDDIS Earthdata server to download and merge Bulletin-A files

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

Parameters

username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.iers_ftp_delta_time(daily_file: str | pathlib.Path, timeout: int | None = 120, verbose: bool = False, mode: oct = 509)[source]

Connects to the IERS ftp server to download Bulletin-A files

https://datacenter.iers.org/productMetadata.php?id=6

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

ftp://ftp.iers.org/products/eop/rapid/bulletina/

Parameters

daily_file: str or pathlib.Path: output daily delta time file from merged Bulletin-A files
timeout: int, default 120: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.iers_delta_time(daily_file: str | pathlib.Path, timeout: int | None = 120, verbose: bool = False, mode: oct = 509)[source]

Connects to the IERS server to download Bulletin-A files

https://datacenter.iers.org/productMetadata.php?id=6

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

https://datacenter.iers.org/availableVersions.php?id=6

Parameters

daily_file: str or pathlib.Path: output daily delta time file from merged Bulletin-A files
timeout: int, default 120: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.cddis_delta_time(daily_file: str | pathlib.Path, username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Connects to the CDDIS Earthdata server to download Bulletin-A files

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

https://cddis.nasa.gov/archive/products/iers/iers_bulletins/bulletin_a/

Parameters

daily_file: str: output daily delta time file from merged Bulletin-A files
username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.read_iers_bulletin_a(fileID)[source]

Read a weekly IERS Bulletin-A file and calculate the delta times (TT - UT1)

Parameters

fileID: obj: open file object for Bulletin-A file

Returns

Y: float,: calendar year
M: float: calendar month
D: float: day of the month
DELTAT: float: difference between universal time and dynamical time

Notes

Delta times are the difference between universal time and dynamical time

pyTMD.time.update_bulletin_a(timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to IERS Rapid Service/Prediction Center (RS/PC) and downloads latest Bulletin-A file

https://maia.usno.navy.mil/ser7/readme.bulla

Servers and Mirrors

https://maia.usno.navy.mil/ser7/ser7.dat

Parameters

timeout: int or NoneType, default 20: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

pyTMD.time.pull_deltat_file(FILE: str, username: str | None = None, password: str | None = None, timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to servers and downloads delta time files

Servers and Mirrors

Parameters

FILE: str

delta time file to download from remote servers

deltat.data: monthly deltat file

historic_deltat.data: historic deltat file

username: str or NoneType, default None

NASA Earthdata username

password: str or NoneType, default None

NASA Earthdata password

timeout: int or NoneType, default 20

timeout in seconds for blocking operations

verbose: bool, default False

print file information about output file

mode: oct, default 0o775

permissions mode of output file

Notes

Delta times are the difference between universal time and dynamical time