iers 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe885be7911b137f1052c4671b28d5ed63ec1f0a887745fbeede898e1d15eb68
-  data.tar.gz: 42763ecd8056ee961e489b666e6445553726c8dbe0d1606f1857eea6a427ba38
+  metadata.gz: 4132b4709810d88306f0ea6bde33b1664d1fdbfeef985e0191cba65c98c01f8a
+  data.tar.gz: 5e3bef64e668f1320bc9c3876e571bf4bb452ea2df52cd09539303bafbf03ea0
 SHA512:
-  metadata.gz: c2282980b523a94f9befbaf3146cb70bbe3284d73305cebf6073826bd60280da002b5a82dc9228fc6552d7db31c5ad38f6f05e9d6150aded290425aad2e47f56
-  data.tar.gz: b0579c1cfb2b2ef069e649ad80df7fddfe1d3828e360e28a6626a42f0a6d03ba1d563e622ee1e861e81bde0c4bc1a2373e112b5980ea2d1f8679bf66cd7e800e
+  metadata.gz: c2bd5f8b1d3a088bc9aa8d822013a9c04570cea94c6036f080eb4d34d8ad53ac0346e6547092f5ce95fe61f95df6de32006e59371894e3b77768565be15354a1
+  data.tar.gz: 8b32049edecc0955026664f02cbf89a1af9d518050374538cbf1b1c3b08d572509b971d522a1d368490d6d07bcbd90bb807bd9fd5c4223d074431a60583244f5

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.2.0 - 2026-07-25
+
+### Added
+
+- `LeapSecond.expires_on`, `LeapSecond.expired?` and
+  `LeapSecond.updated_through` expose the expiry date and IERS bulletin that
+  `Leap_Second.dat` states in its header. Both were previously discarded with
+  the rest of the comment lines. Unlike `Data.status.cache_age`, which measures
+  when a file was downloaded, these describe how long the data itself stays
+  authoritative.
+- `LeapSecond.at` now answers 1961-01-01 through 1972-01-01, the era when UTC
+  was steered by rate adjustments rather than whole leap seconds. It returns
+  those values as exact `Rational`s. The coefficients come from the USNO
+  `tai-utc.dat` file and are bundled in source, since they are fixed. The
+  change is additive: the pre-1972 range previously raised, so no successful
+  call returns anything different. `TAI.utc_to_tai` and `TAI.tai_to_utc` gain
+  the same range for free.
+
+### Changed
+
+- `Parsers::LeapSecond.parse` returns a `Table` of `entries` and `metadata`
+  instead of an array of entries. `Parsers` is internal; the public API is
+  unaffected.
+- `Parsers::LeapSecond.parse` no longer raises `Encoding::CompatibilityError`
+  on a file containing invalid UTF-8. Header metadata is read on a best-effort
+  basis and an unreadable data row raises `ParseError` as before.
+
 ## 0.1.1 - 2026-06-27
 
 ### Changed

data/README.md

@@ -242,14 +242,28 @@ entries = IERS::EOP.between(
 Look up TAI−UTC at a given date:
 
 ```ruby
-IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37.0 (seconds)
+IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37 (seconds)
 ```
 
+`at` covers 1961-01-01 onward. From 1972 it returns a whole number of seconds
+as an `Integer`. Between 1961 and 1972, UTC was steered by small rate
+adjustments rather than whole leap seconds, so TAI−UTC was a fraction of a
+second that changed daily. `at` returns those values as exact `Rational`s:
+
+```ruby
+IERS::LeapSecond.at(mjd: 38_900)       # => (1910137/500000)
+IERS::LeapSecond.at(mjd: 38_900).to_f  # => 3.820274 (seconds, 1965-05-20)
+```
+
+The coefficients for that era are fixed and will never change, so they are
+bundled in the gem rather than downloaded. Anything before 1961-01-01 has no
+published UTC and raises `OutOfRangeError`.
+
 List all leap seconds:
 
 ```ruby
 IERS::LeapSecond.all
-# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10.0>, ...]
+# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10>, ...]
 ```
 
 Check for a future scheduled leap second:
@@ -258,6 +272,27 @@ Check for a future scheduled leap second:
 IERS::LeapSecond.next_scheduled  # => #<data IERS::LeapSecond::Entry ...> or nil
 ```
 
+#### Leap second file validity
+
+`Leap_Second.dat` states when it stops being authoritative and which IERS
+bulletin it was updated through. Both are read from the file that is actually
+loaded, so a custom or cached file reports its own header:
+
+```ruby
+IERS::LeapSecond.expires_on       # => #<Date: 2026-12-28> or nil
+IERS::LeapSecond.expired?         # => false
+IERS::LeapSecond.updated_through  # => "IERS Bulletin 71 issued in January 2026"
+```
+
+The stated date is itself still valid, so a file expiring on 28 December 2026
+is expired on the 29th. An expired file is not wrong: it means the IERS has
+published a newer one and a leap second may have been announced since.
+
+This is unrelated to `Data.status.cache_age`, which measures when the file was
+downloaded rather than how long it stays valid. A bundled snapshot can be a year
+old and still valid while a file downloaded this morning can be a week from
+expiry.
+
 ### TAI
 
 Convert between UTC and TAI time scales:
@@ -295,6 +330,10 @@ end
 
 Without `coverage_days_ahead`, the check ensures predictions cover today.
 
+`ensure_fresh!` is about prediction coverage in `finals2000A.all` only. Leap
+second file validity is a separate question, answered by
+`IERS::LeapSecond.expired?`.
+
 ### Data status and cache management
 
 ```ruby
@@ -358,6 +397,9 @@ release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and the created tag, and push the `.gem` file to [rubygems.org].
 
+To refresh the bundled snapshot in `data/`, run `bundle exec rake data:update`.
+A monthly workflow runs this and opens a pull request automatically.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License].

data/Rakefile

@@ -10,3 +10,31 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]
+
+namespace :data do
+  desc "Download the latest IERS data"
+  task :update do
+    require "iers"
+
+    data_dir = File.expand_path("data", __dir__)
+    IERS.configure do |config|
+      config.finals_path = File.join(data_dir, "finals2000A.all")
+      config.leap_second_path = File.join(data_dir, "Leap_Second.dat")
+    end
+
+    result = IERS::Data.update!
+
+    unless result.success?
+      result.errors.each do |source, error|
+        warn "#{source}: #{error.class} - #{error.message}"
+      end
+      abort "IERS data update failed"
+    end
+
+    IERS::Data.clear_loaded!
+    IERS::Data.ensure_fresh!(coverage_days_ahead: 90)
+    IERS::Data.leap_second_entries
+
+    puts "Updated: #{result.updated_files.join(", ")}"
+  end
+end

data/lib/iers/data.rb

@@ -11,13 +11,13 @@ module IERS
 
     @mutex = Mutex.new
     @finals = nil
-    @leap_seconds = nil
+    @leap_second_table = nil
 
     module_function
 
     # @return [Boolean]
     def loaded?
-      !@finals.nil? || !@leap_seconds.nil?
+      !@finals.nil? || !@leap_second_table.nil?
     end
 
     # @param sources [Array<Symbol>] data sources to update (default: all)
@@ -96,16 +96,26 @@ module IERS
       end
     end
 
-    # @return [Array<Parsers::LeapSecond::Entry>]
-    def leap_second_entries
+    # @return [Parsers::LeapSecond::Table]
+    def leap_second_table
       @mutex.synchronize do
-        @leap_seconds ||= begin
+        @leap_second_table ||= begin
           path = resolve_read_path(:leap_seconds)
-          Parsers::LeapSecond.parse(path).freeze
+          Parsers::LeapSecond.parse(path)
         end
       end
     end
 
+    # @return [Array<Parsers::LeapSecond::Entry>]
+    def leap_second_entries
+      leap_second_table.entries
+    end
+
+    # @return [Parsers::LeapSecond::Metadata]
+    def leap_second_metadata
+      leap_second_table.metadata
+    end
+
     def resolve_path(source, config = IERS.configuration)
       case source
       when :finals
@@ -155,7 +165,7 @@ module IERS
     def clear_loaded!
       @mutex.synchronize do
         @finals = nil
-        @leap_seconds = nil
+        @leap_second_table = nil
       end
     end
 

data/lib/iers/data_status.rb

@@ -3,7 +3,7 @@
 module IERS
   # @attr source [Symbol] +:cached+, +:custom+, or +:bundled+
   # @attr cache_age [Integer, nil] age in seconds, or +nil+
-  DataStatus = Data.define(:source, :cache_age) do
+  DataStatus = ::Data.define(:source, :cache_age) do
     # @return [Boolean]
     def cached?
       source == :cached

data/lib/iers/leap_second.rb

@@ -30,17 +30,41 @@ module IERS
       end
     end
 
+    # @return [Date, nil]
+    def expires_on
+      IERS::Data.leap_second_metadata.expires_on
+    end
+
+    # @param as_of [Date]
+    # @return [Boolean]
+    def expired?(as_of: Date.today)
+      expiry = expires_on
+      return false if expiry.nil?
+
+      as_of > expiry
+    end
+
+    # @return [String, nil]
+    def updated_through
+      IERS::Data.leap_second_metadata.updated_through
+    end
+
     # @return [Entry, nil]
     def next_scheduled
       today = Date.today
       all.find { |entry| entry.effective_date > today }
     end
 
+    # TAI−UTC covers 1961-01-01 onward. From 1972 the value is a whole number
+    # of seconds read from Leap_Second.dat and returned as an Integer. Between
+    # 1961 and 1972 UTC was steered by rate adjustments rather than whole leap
+    # seconds, so the value is a fraction of a second returned as a Rational.
+    #
     # @param input [Time, Date, DateTime, nil]
     # @param jd [Float, nil] Julian Date
     # @param mjd [Float, nil] Modified Julian Date
-    # @return [Integer] TAI−UTC in seconds
-    # @raise [OutOfRangeError]
+    # @return [Integer, Rational] TAI−UTC in seconds
+    # @raise [OutOfRangeError] before 1961-01-01
     def at(input = nil, jd: nil, mjd: nil)
       query_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
       parser_entries = IERS::Data.leap_second_entries
@@ -49,11 +73,14 @@ module IERS
       last_mjd = parser_entries.last.mjd
 
       if query_mjd < first_mjd
+        return TaiUtcDrift.at(query_mjd) if TaiUtcDrift.covers?(query_mjd)
+
         raise OutOfRangeError.new(
-          "Requested MJD #{query_mjd} is before the first leap second " \
-          "entry (MJD #{first_mjd})",
+          "Requested MJD #{query_mjd} is before TAI−UTC was defined " \
+          "(MJD #{TaiUtcDrift::FIRST_MJD}, 1961-01-01; no published UTC " \
+          "before then)",
           requested_mjd: query_mjd,
-          available_range: first_mjd..last_mjd
+          available_range: TaiUtcDrift::FIRST_MJD..last_mjd
         )
       end
 

data/lib/iers/parsers/finals.rb

@@ -5,7 +5,7 @@ require "date"
 module IERS
   module Parsers
     module Finals
-      Entry = Data.define(
+      Entry = ::Data.define(
         :date, :mjd,
         :pm_flag, :pm_x, :pm_x_error, :pm_y, :pm_y_error,
         :ut1_flag, :ut1_utc, :ut1_utc_error,

data/lib/iers/parsers/leap_second.rb

@@ -5,10 +5,23 @@ require "date"
 module IERS
   module Parsers
     module LeapSecond
-      Entry = Data.define(:mjd, :date, :tai_utc)
+      Entry = ::Data.define(:mjd, :date, :tai_utc)
+
+      # @attr expires_on [Date, nil]
+      # @attr updated_through [String, nil]
+      Metadata = ::Data.define(:expires_on, :updated_through)
+
+      # @attr entries [Array<Entry>]
+      # @attr metadata [Metadata]
+      Table = ::Data.define(:entries, :metadata)
+
+      EXPIRES_ON = /File expires on\s+(\d{1,2})\s+([A-Za-z]+)\s+(\d{4})/i
+      UPDATED_THROUGH = /\AUpdated through\s+(.+?)\s*\z/i
+      COMMENT_PREFIX = /\A#+\s*/
 
       module_function
 
+      # @return [Table]
       def parse(path)
         path = Pathname(path)
 
@@ -20,14 +33,30 @@ module IERS
         end
 
         entries = []
+        expires_on = nil
+        updated_through = nil
 
         path.each_line.with_index(1) do |line, line_number|
-          next if line.strip.empty? || line.strip.start_with?("#")
+          stripped = line.scrub.strip
+          next if stripped.empty?
+
+          if stripped.start_with?("#")
+            comment = stripped.sub(COMMENT_PREFIX, "")
+            expires_on ||= parse_expiry(comment)
+            updated_through ||= parse_updated_through(comment)
+            next
+          end
 
           entries << parse_line(line, path, line_number)
         end
 
-        entries.freeze
+        Table.new(
+          entries: entries.freeze,
+          metadata: Metadata.new(
+            expires_on: expires_on,
+            updated_through: updated_through
+          )
+        )
       end
 
       def parse_line(line, path, line_number)
@@ -50,7 +79,28 @@ module IERS
         )
       end
 
-      private_class_method :parse_line
+      # @return [Date, nil]
+      def parse_expiry(comment)
+        match = EXPIRES_ON.match(comment)
+        return nil if match.nil?
+
+        month = Date::MONTHNAMES.index do |name|
+          name&.casecmp?(match[2])
+        end
+        return nil if month.nil?
+
+        Date.new(Integer(match[3], 10), month, Integer(match[1], 10))
+      rescue ArgumentError
+        nil
+      end
+
+      # @return [String, nil]
+      def parse_updated_through(comment)
+        match = UPDATED_THROUGH.match(comment)
+        match && match[1]
+      end
+
+      private_class_method :parse_line, :parse_expiry, :parse_updated_through
     end
   end
 end

data/lib/iers/tai_utc_drift.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module IERS
+  # TAI-UTC from 1961-01-01 to 1972-01-01, when UTC was steered by rate
+  # adjustments instead of whole leap seconds. In this era TAI-UTC is a linear
+  # function of MJD, restarting at each published step, so a value is
+  # +offset + (mjd - reference_mjd) * rate+.
+  #
+  # The table is closed: the last segment ends where Leap_Second.dat begins and
+  # no new segment can ever be added.
+  #
+  # Coefficients from the USNO tai-utc.dat file, the same values ERFA carries in
+  # dat.c. They are exact decimals, so they are stored as rationals rather than
+  # floats.
+  #
+  # @api private
+  module TaiUtcDrift
+    # @attr start_mjd [Integer] first MJD the segment applies to
+    # @attr offset [Rational] TAI-UTC in seconds at reference_mjd (not at
+    #   start_mjd: several segments measure their rate from an earlier MJD)
+    # @attr reference_mjd [Integer] the MJD the rate is measured from
+    # @attr rate [Rational] seconds of TAI-UTC per day of MJD
+    Segment = ::Data.define(:start_mjd, :offset, :reference_mjd, :rate)
+
+    # 1961-01-01. Below this there is no published UTC, so TAI-UTC is undefined.
+    FIRST_MJD = 37_300
+
+    # 1972-01-01, where Leap_Second.dat takes over. The drift era stops here.
+    LAST_MJD = 41_317
+
+    module_function
+
+    # @param mjd [Numeric]
+    # @return [Rational] TAI-UTC in seconds
+    def at(mjd)
+      segment = SEGMENTS.reverse_each.find { |s| mjd >= s.start_mjd }
+
+      segment.offset +
+        (Rational(mjd) - segment.reference_mjd) * segment.rate
+    end
+
+    # Whether +at+ has a value for this MJD: 1961-01-01 up to but not including
+    # 1972-01-01, where Leap_Second.dat takes over. A caller with a custom leap
+    # second file starting after 1972 relies on the upper bound to fall through
+    # to its own error rather than reading a stale drift value.
+    #
+    # @param mjd [Numeric]
+    # @return [Boolean]
+    def covers?(mjd)
+      mjd >= FIRST_MJD && mjd < LAST_MJD
+    end
+
+    SEGMENTS = [
+      Segment.new(
+        start_mjd: 37_300,
+        offset: Rational(14_228_180, 10_000_000),
+        reference_mjd: 37_300,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 37_512,
+        offset: Rational(13_728_180, 10_000_000),
+        reference_mjd: 37_300,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 37_665,
+        offset: Rational(18_458_580, 10_000_000),
+        reference_mjd: 37_665,
+        rate: Rational(11_232, 10_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_334,
+        offset: Rational(19_458_580, 10_000_000),
+        reference_mjd: 37_665,
+        rate: Rational(11_232, 10_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_395,
+        offset: Rational(32_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_486,
+        offset: Rational(33_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_639,
+        offset: Rational(34_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_761,
+        offset: Rational(35_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_820,
+        offset: Rational(36_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 38_942,
+        offset: Rational(37_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 39_004,
+        offset: Rational(38_401_300, 10_000_000),
+        reference_mjd: 38_761,
+        rate: Rational(1_296, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 39_126,
+        offset: Rational(43_131_700, 10_000_000),
+        reference_mjd: 39_126,
+        rate: Rational(2_592, 1_000_000)
+      ),
+      Segment.new(
+        start_mjd: 39_887,
+        offset: Rational(42_131_700, 10_000_000),
+        reference_mjd: 39_126,
+        rate: Rational(2_592, 1_000_000)
+      ),
+      # Reached only by a direct TaiUtcDrift.at(41_317): LeapSecond.at's drift
+      # branch requires query_mjd < 41_317. It pins the join to exactly 10,
+      # matching Leap_Second.dat's first row; without it the 1968 segment would
+      # give ~9.8922 here. Do not remove.
+      Segment.new(
+        start_mjd: 41_317,
+        offset: Rational(10),
+        reference_mjd: 41_317,
+        rate: Rational(0)
+      )
+    ].freeze
+  end
+end

data/lib/iers/update_result.rb

@@ -3,7 +3,7 @@
 module IERS
   # @attr updated_files [Array<Symbol>]
   # @attr errors [Hash{Symbol => Error}]
-  UpdateResult = Data.define(:updated_files, :errors) do
+  UpdateResult = ::Data.define(:updated_files, :errors) do
     # @return [Boolean]
     def success?
       errors.empty?

data/lib/iers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IERS
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/iers.rb

@@ -14,6 +14,7 @@ require_relative "iers/has_data_quality"
 require_relative "iers/interpolation"
 require_relative "iers/eop_lookup"
 require_relative "iers/eop_parameter"
+require_relative "iers/tai_utc_drift"
 require_relative "iers/leap_second"
 require_relative "iers/tai"
 require_relative "iers/ut1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Rémy Hannequin
@@ -174,6 +174,7 @@ files:
 - lib/iers/parsers/leap_second.rb
 - lib/iers/polar_motion.rb
 - lib/iers/tai.rb
+- lib/iers/tai_utc_drift.rb
 - lib/iers/terrestrial_rotation.rb
 - lib/iers/time_scale.rb
 - lib/iers/update_result.rb