iers 0.1.1 → 0.3.0

data/lib/iers/configuration.rb

@@ -39,6 +39,7 @@ module IERS
 
     def cache_dir=(value)
       @cache_dir = Pathname(value)
+      invalidate
     end
 
     def sources=(value)
@@ -59,10 +60,12 @@ module IERS
 
     def finals_path=(value)
       @finals_path = value && Pathname(value)
+      invalidate(:finals)
     end
 
     def leap_second_path=(value)
       @leap_second_path = value && Pathname(value)
+      invalidate(:leap_seconds)
     end
 
     def interpolation=(value)
@@ -82,5 +85,15 @@ module IERS
 
       @lagrange_order = value
     end
+
+    private
+
+    # Settings staged on a detached Configuration govern nothing, so they must
+    # not reach into the parse the gem is actually serving.
+    def invalidate(*sources)
+      return unless IERS.active_configuration?(self)
+
+      Data.clear_loaded!(*sources)
+    end
   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)
@@ -37,6 +37,7 @@ module IERS
         begin
           Downloader.new(timeout: config.download_timeout).fetch(url, dest)
           updated << source
+          clear_loaded!(source)
         rescue DownloadError => e
           errors[source] = e
         end
@@ -67,6 +68,8 @@ module IERS
         path = config.cache_dir.join(filename)
         path.delete if path.exist?
       end
+
+      clear_loaded!
     end
 
     # @param coverage_days_ahead [Integer, nil]
@@ -96,16 +99,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
@@ -151,15 +164,33 @@ module IERS
       (Time.now - mtimes.min).to_i
     end
 
+    # @param sources [Array<Symbol>] data sources to drop (default: all)
     # @return [void]
-    def clear_loaded!
+    def clear_loaded!(*sources)
+      sources = FILENAMES.keys if sources.empty?
+      validate_sources!(sources)
+
       @mutex.synchronize do
-        @finals = nil
-        @leap_seconds = nil
+        @finals = nil if sources.include?(:finals)
+        @leap_second_table = nil if sources.include?(:leap_seconds)
       end
+
+      # Outside the mutex above: LeapSecond takes its own lock before calling
+      # back into Data, so taking them in that order here would invert it.
+      LeapSecond.clear_cached! if sources.include?(:leap_seconds)
+    end
+
+    def validate_sources!(sources)
+      unknown = sources - FILENAMES.keys
+      return if unknown.empty?
+
+      raise ConfigurationError,
+        "Unknown data source: #{unknown.map(&:inspect).join(", ")}. " \
+        "Valid sources: #{FILENAMES.keys.inspect}"
     end
 
-    private_class_method :resolve_path,
+    private_class_method :validate_sources!,
+      :resolve_path,
       :resolve_read_path,
       :validate_source!,
       :custom_paths_configured?,

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/delta_t.rb

@@ -14,11 +14,11 @@ module IERS
     end
 
     EARLIEST_YEAR = 1800.0
-    PRE_1972_MJD = 41317.0
+    LATEST_POLYNOMIAL_YEAR = 1986.0
     DAYS_PER_JULIAN_YEAR = 365.25
     YEAR_J2000 = 2000.0
 
-    # Espenak & Meeus (2014) polynomial segments for 1800–1972.
+    # Espenak & Meeus (2014) polynomial segments for 1800–1986.
     # Each segment: [year_start, year_end, epoch, coefficients]
     # ΔT = c₀ + c₁·t + c₂·t² + ... where t = y − epoch
     # Reference: https://eclipsewise.com/help/deltatpoly2014.html
@@ -46,7 +46,7 @@ module IERS
     ].freeze
 
     private_constant :EARLIEST_YEAR,
-      :PRE_1972_MJD,
+      :LATEST_POLYNOMIAL_YEAR,
       :DAYS_PER_JULIAN_YEAR,
       :YEAR_J2000,
       :POLYNOMIALS
@@ -69,24 +69,62 @@ module IERS
         )
       end
 
-      if query_mjd < PRE_1972_MJD
-        Entry.new(
-          delta_t: polynomial_delta_t(y),
-          mjd: query_mjd,
-          source: :estimated
-        )
+      if series_covers?(query_mjd)
+        measured_entry(query_mjd)
+      elsif y <= LATEST_POLYNOMIAL_YEAR
+        estimated_entry(query_mjd, y)
       else
-        tai_utc = LeapSecond.at(mjd: query_mjd)
-        ut1_utc = UT1.at(mjd: query_mjd).ut1_utc
-
-        Entry.new(
-          delta_t: tai_utc + TimeScale::TT_TAI - ut1_utc,
-          mjd: query_mjd,
-          source: :measured
-        )
+        raise_uncovered!(query_mjd)
       end
     end
 
+    # The EOP series is the better source wherever it reaches, so it is asked
+    # first; the polynomial covers whatever is left within its own validity.
+    def series_covers?(mjd)
+      entries = Data.finals_entries
+      return false if entries.empty?
+
+      mjd.between?(entries.first.mjd, entries.last.mjd)
+    end
+
+    def estimated_entry(query_mjd, y)
+      Entry.new(
+        delta_t: polynomial_delta_t(y),
+        mjd: query_mjd,
+        source: :estimated
+      )
+    end
+
+    def raise_uncovered!(query_mjd)
+      entries = Data.finals_entries
+      series =
+        if entries.empty?
+          "is empty"
+        else
+          "covers #{entries.first.mjd}..#{entries.last.mjd}"
+        end
+
+      # No `available_range`: what DeltaT can answer is two disjoint spans, and
+      # naming either one alone is what made the old message misleading.
+      raise OutOfRangeError.new(
+        "No DeltaT available for MJD #{query_mjd}: the polynomial covers " \
+        "#{EARLIEST_YEAR.to_i}–#{LATEST_POLYNOMIAL_YEAR.to_i} and the EOP " \
+        "series #{series}",
+        requested_mjd: query_mjd
+      )
+    end
+
+    def measured_entry(query_mjd)
+      tai_utc = LeapSecond.at(mjd: query_mjd)
+      ut1_utc = UT1.at(mjd: query_mjd).ut1_utc
+
+      Entry.new(
+        delta_t: tai_utc + TimeScale::TT_TAI - ut1_utc,
+        mjd: query_mjd,
+        source: :measured
+      )
+    end
+
     def polynomial_delta_t(y)
       segment = POLYNOMIALS.find { |s| y < s[1] } || POLYNOMIALS.last
       t = y - segment[2]
@@ -97,6 +135,11 @@ module IERS
       YEAR_J2000 + (mjd - TimeScale::MJD_J2000) / DAYS_PER_JULIAN_YEAR
     end
 
-    private_class_method :polynomial_delta_t, :mjd_to_decimal_year
+    private_class_method :series_covers?,
+      :estimated_entry,
+      :raise_uncovered!,
+      :measured_entry,
+      :polynomial_delta_t,
+      :mjd_to_decimal_year
   end
 end

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.3.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"
@@ -39,11 +40,17 @@ module IERS
       yield configuration
     end
 
+    # @api private
+    # @param candidate [Configuration]
+    # @return [Boolean] whether the gem reads its data through this object
+    def active_configuration?(candidate)
+      @configuration.equal?(candidate)
+    end
+
     # @return [void]
     def reset_configuration!
       @configuration = nil
       Data.clear_loaded!
-      LeapSecond.clear_cached!
     end
 
     # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.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