How to update leap seconds

The current version of MATLAB has a function to give you the leap second information that it is using. E.g.,

[T,vers] = leapseconds

T = 27×2 timetable
       Date        Type    CumulativeAdjustment
    ___________    ____    ____________________

    30-Jun-1972     +              1 sec       
    31-Dec-1972     +              2 sec       
    31-Dec-1973     +              3 sec       
    31-Dec-1974     +              4 sec       
    31-Dec-1975     +              5 sec       
    31-Dec-1976     +              6 sec       
    31-Dec-1977     +              7 sec       
    31-Dec-1978     +              8 sec       
    31-Dec-1979     +              9 sec       
    30-Jun-1981     +             10 sec       
    30-Jun-1982     +             11 sec       
    30-Jun-1983     +             12 sec       
    30-Jun-1985     +             13 sec       
    31-Dec-1987     +             14 sec       
    31-Dec-1989     +             15 sec       
    31-Dec-1990     +             16 sec       

vers = 65

But suppose you have a version of MATLAB that is not up to date with the latest leap second data. E.g., an older version of MATLAB, or maybe a recent version of MATLAB but there is a leap second announced that your version doesn't know about. I know there is a proposal to abolish leap seconds (programmers in multiple s/w packages never could seem to get this coded correctly), but what if there is another leap second announced before they officially become abolished or you have an older version of MATLAB? This link doesn't mention how to update MATLAB for this:

https://www.mathworks.com/help/matlab/ref/leapseconds.html?searchHighlight=leap%20seconds&s_tid=srchtitle_support_results_2_leap%20seconds

Is there a way for the user to update their version of MATLAB by downloading new files or updating current files or ...?

[Walter Roberson]

It looks like it is getting the information from https://www.iers.org/IERS/EN/Publications/Bulletins/bulletins.html

My suspicion is that when each version of MATLAB is built, that the xml files are pre-processed into a resource that is built-in. The individual files do not have enough information for the entire table, and I cannot find a copy of the .xml files anywhere in R2023b

[James Tursa]

Hmmm. I am writing some time scale conversion code (e.g., UTC to/from GPS), and my code has some internal tables that are easy to update for leap second info. But I also use the datetime UTCLeapSeconds time zone for this. It is easy enough to detect when my tables don't match UTCLeapSeconds and alert the user that there is a problem, but now how to update MATLAB if a problem is detected? That is the issue.

E.g., here is an easy way to convert UTC (or any time zone) to GPS:

format longg
dt = datetime('now','TimeZone',datetime.SystemTimeZone) % arbitrary sample input

dt = datetime
   15-Sep-2023 21:00:02

GPS_epoch = datetime(1980,1,6,'TimeZone','UTCLeapSeconds');
if( ~isequal(dt.TimeZone,'UTCLeapSeconds') ) % needed to avoid MATLAB bug
    dt = datetime(dt,'TimeZone','UTCLeapSeconds');
end
gps_time = seconds(dt - GPS_epoch)

gps_time = 
          1378846820.45726

And of course you can turn the duration into weeks and seconds_of_week if you want.

But this won't work if the internal UTCLeapSeconds does not know about all of the leap seconds, hence the desire to find some way to update MATLAB. I presume that if you executed this code in e.g. R2015a you will get a wrong answer because it is missing leap second info from 2016.

Answer 1

[Peter Perkins]

James, there's no way for customers to update MATLAB with new leap seconds. The IERS data is built into a binary file.

The last leap second was 31-Dec-2016. R2016b came out a bit before that, but was "frozen" before the IERS declared that leap second in July 2016. I can't recall if we posted a patch, but if 16b is the version that matters, I can look to see if there's a patch. I know that many of our large customers validate a particular release and standardize on that for years at a time.

These days, we would incorporate a new leap second via MATLAB Updates. That process began sometime around R2018b, I forget exactly when. But in any case, 18b would have that most recent leap second, and no new ones have been declared, and it's anyone's guess whether or not any new ones will ever be declared (this was my guess).

Walter: "datetime() has more leap-second handling than I expected" Is there any leap-second handling that you were looking for that's not there?

[Steven Lord]

There's a bug report, 1448069, for this issue. That bug report includes attachments for release R2016a and R2016b on each of the three platforms supported at that time and indicates that release R2017a has this change incorporated in it.

[James Tursa]

Well, this is all an unfortunate design shortcoming. There should have been a text file for this. So e.g. if I am writing code that converts between GPS and UTC, I can't rely on using datetime( ) UTCLeapSeconds for this because there is no way to ensure that UTCLeapSeconds is up-to-date for the MATLAB version the user happens to be using without consulting a secondary table that I would have to embed within my code. And if my table is up-to-date but detects MATLAB isn't, the only remedy I am hearing is to either discontinue using UTCLeapSeconds entirely or put in manual fix-up code for invalid dates everywhere I use UTCLeapSeconds. I'm writing code that will be distributed to multiple users running various versions of MATLAB and now I need to figure out how to robustly code this. Not fun. (Maybe if I can figure out how to get the Earth to spin just a little bit faster that will solve my coding problems ...)

[James Tursa]

Follow up questions:

• When was UTCLeapSeconds introduced?
• Are there early versions of MATLAB that have UTCLeapSeconds but don't have patches available to fix the internal leap second table (e.g., maybe R2015a for the 2016 leap second)? Or do all versions of MATLAB that have UTCLeapSeconds have patches available for this?
• What was the first version of MATLAB that uses MATLAB Updates?
• Are there versions of MATLAB that incorporate all current leap seconds through 2016, but do not use MATLAB Updates so they would not be able to use this method if a future leap second is announced? E.g., does R2017a use MATLAB Updates?

I'm trying to figure out what my s/w should do. Tell the user to get a patch, or tell the user they are out of luck and need to get a later version of MATLAB to use my s/w.

[Steven Lord]

What was the first version of MATLAB that uses MATLAB Updates?

I believe release R2015a SP1 was the first release that had an Update release, based on selecting "I WANT TO: Get Updates" on the downloads page.

Searching the Support site for "leap second" and filtering to only show Bug Reports lists three bug reports:

• Bug Report 1191139
• The Bug Report I linked previously, 1448069
• Bug Report 1192415

That last links to another Bug Report (1196109) related to datetime arrays that doesn't specifically include the term "leap second".

I'm not sure of the answers to your other questions.

[James Tursa]

Here is a function to see if your version of MATLAB is up-to-date for UTCLeapSeconds. Of course, for any version of MATLAB later than R2016b there shouldn't be any problem as no new leap seconds have been announced since the end of 2016. But for 2016 and earlier versions of MATLAB this should tell you if you have a problem.

% LEAPSECONDCHECK checks MATLAB datetime UTCLeapSeconds for up-to-dateness
% Programmer: James Tursa
function lstable = leapsecondcheck

try % For later versions of MATLAB, just use leapseconds function
    ls = leapseconds;
    ls_MATLAB = ls.Date;
catch % For earlier versions of MATLAB, build a list from scratch
    dv = datevec(now);
    yr = dv(1) + 2;
    ls_MATLAB = datetime([],[],[]);
    k = 0;
    for y = 1972:yr
        for m = 1:12 % historically only 6 or 12, but check all just in case
            dt = datetime(y,m,1,'TimeZone','UTCLeapSeconds');
            if( second(dt - seconds(1)) ~= 59 )
                k = k + 1;
                ls_MATLAB(k) = datetime(y,m,1) - 1; % online tables use day-of, not day-after
            end
        end
    end
    ls_MATLAB = ls_MATLAB(:);
end

% Go get the latest data file for tai-utc.dat which has leap seconds info (this is a small file)
str = urlread('https://maia.usno.navy.mil/ser7/tai-utc.dat'); % Using urlread to accommodate older versions of MATLAB

% Construct the leap second date list from this file
f = strfind(str,'=JD');
ls_USNO = repmat(datetime(nan,nan,nan),numel(f),1);
for k=1:numel(f)
    ls_USNO(k) = datetime(str(f(k)-12:f(k)-1),'Format','uuuu MMM dd') - 1; % online tables use day-of, not day-after
end

% Clip out Old UTC dates and Modern UTC epoch
ls_USNO(ls_USNO <= datetime(1972,1,1)) = [];

% Construct comparison table, where missing dates show up as NaT
ls_UNIQUE = unique([ls_MATLAB;ls_USNO]);
USNO = ls_UNIQUE;
MATLAB = ls_UNIQUE;
NaT = datetime(nan,nan,nan);
USNO(~ismember(USNO,ls_USNO)) = NaT;
MATLAB(~ismember(MATLAB,ls_MATLAB)) = NaT;
lst = table(USNO,MATLAB);

% If user just wants to display the result
if( nargout == 0 )
    if( isequal(ls_MATLAB,ls_USNO) )
        disp('All MATLAB leap seconds match USNO file.')
    else
        warning('MATLAB is missing leap seconds! (shown as NaT in the following table)');
        disp('Check here for complete list of leap seconds:')
        disp('https://www.nist.gov/pml/time-and-frequency-division/time-realization/leap-seconds') % day-of
        disp(lst)
    end
    
    % If user wants the comparison table returned in a variable
else
    lstable = lst;
end
end

Answer 2

[the cyclist]

The file leapseconds.m calls a built-in file to get the list of leap seconds, but you can edit that file to add additional ones.

In fact, that file contains (commented-out) instructions on how to add leap seconds by "brute force".

[Walter Roberson]

The commented-out instructions are for determining the list of leap seconds based upon what datetime() returns -- which implies that datetime() has been configured to already know the leapsecond rules.

datetime() has more leap-second handling than I expected, but in most places it is not clear to me what is taking care of determining leap seconds. I do see it calls upon matlab.internal.datetime.addLeapSeconds and matlab.internal.datetime.removeLeapSeconds which can tell you whether the time was within a leap second or not... but those are compiled in.

[James Tursa]

Thanks. I will take a look at that. I wonder if that same file is used by older MATLAB versions that don't have the leapseconds function (e.g., for their UTCLeapSeconds time zone calculations).