Description

The celestial.time package contains basic utilities for time conversion. Additional tools are available in the convert class.

Julian days

To convert date to Julian day (JD):

% JD UTC now
JD = celestial.time.julday

% JD at midinight UTC
% JD = celestial.time.julday([D M Y])
JD = celestial.time.julday([1 12 2023; 31 12 2023])
% or you can add the UTC time H, M, S 
JD = celestial.time.julday(31 1 2023 22 30 0]);
% alternatively use strings:
celestial.time.julday('2023-12-01T10:10:10.1')
% or cell array of strings:
celestial.time.julday({'2023-12-01T10:10:10.1','2023-01-01T22:10:59.1'})

and from JD to date:

% the output is D M Y Fraction_Of_Day
celestial.time.jd2date(2451545+[0:1:3]')
% or in D M Y H M S
celestial.time.jd2date(2451545+[0:1:3]','H')

Barycentric JD

You can calculate the Barycentric JD and barycentric velocity for a geocentric or topocentric observer using the celestial.time.barycentricJD functions. This function uses the INPOP Solar System ephemeris implemented in the celestial.INPOP class.

% Barycentric JD for Geocentric observer:
[BJD, BVel] = celestial.time.barycentricJD(2451545,1,1)  % vel. units is cm/s
% change velocity units to au/day
[BJD, BVel] = celestial.time.barycentricJD(2451545,1,1,'VelOutUnits','au/day')

% Barycentric JD for topocentric observer:
RAD = 180./pi;
[BJD, BVel] = celestial.time.barycentricJD(2451545,1,1,'GeoPos',[35./RAD 30./RAD, 415])

Additional JD functions

Other related functions:

• celestial.time.date2jd - like julday, bu in which the input is [Y M D ...]
• celestial.time.julday1 - faster function for date range 1900 to 2100
• celestial.time.jd2mjd - JD to MJD (=JD-2400000.5)
• celestial.time.mjd2jd - MJD to JD
• celestial.time.easter_date - Calculate the date of Easter for any Gregorian year
• celestial.time.jd2year - JD to Julian or Besselian years
• celestial.time.year2jd - Return the Julian day at Jan 1 st of a given list of years.
• celestial.time.date_str2vec - Convert a string or a cell array of strings containing date and time
• celestia.time.days_in_month - Return the number of days in month.
• celestial.time.str2date - Convert a date string (using datevec) to date vector
• month_name - Minth number to name.

Local Sidereal Time

Given the UT1 time (see below) you can calculate the Local Sidereal Time (LST):

LST=celestial.time.lst(2451545+[0:1:5]',0);  % LST at Greenwhich 0 UT1

RAD = 180./pi;
EastLong = 35./RAD
celestial.time.lst(2451565, EastLong)

% by default the lst function calculates the mean LST
% to calculate the apparent LST, using the IAU1976 nutation, use:
celestial.time.lst(2451565, EastLong, 'a')

Time and clocks

To convert between different time scales (e.g., TT, TDB, UTC, UT1, TAI, etc.) and to find the Earth rotational parameters you can use the following functionality.

The first step is to download from the International Earth Rotation Service (IERS) the most updated Earth rotation files

% generate an Installer object
I = Installer;
% Download most recent time files from the IERS website
% and store them in ~matlab/data/SolarSystem/Time
I.install('Time');

Next, you can use the following functions to read, download, and calculate some time parameters:

% Return UT1-TAI [s] and Earth Orientation Parameters:
[UT1mTAI,EOP]=celestial.time.ut1_tai(2451545);

% Return UT1-UTC and earth Orientation Parameters in Table format:
[UT1mUTC,EOP_Table]=celestial.time.ut1_utc(2451545);

% for values between 1962 to 1992, use:
[UT1mUTC]=celestial.time.ut1_utc(2451545,'SourceFile','1962')   % [s]

% TDB - TDT:
Diff=celestial.time.tdb_tdt(celestial.time.julday([1 1 2000])) % [s]

% TT-UTC, TT-UT1, UT1-TAI, UT1-UTC [s]:
% including predictions into the near future:
[TTmUTC, TTmUT1, UT1mTAI, UT1mUTC]=celestial.time.tt_utc([0;2451545;celestial.time.julday+10]);

% Calculate Delta T (=TT-UT1; or ET-UT prior to 1984):
celestial.time.delta_t(celestial.time.julday([1 1 2000; 1 1 2023]))  % [s]