iers 0.1.0 → 0.2.0

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.0"
+  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.0
+  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