iers 0.0.1 → 0.1.0

data/lib/iers/eop_lookup.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module IERS
+  # @api private
+  module EopLookup
+    module_function
+
+    # @param entries [Array] sorted finals entries
+    # @param mjd [Float]
+    # @param order [Integer] number of points in the window
+    # @return [Array]
+    # @raise [OutOfRangeError]
+    def window(entries, mjd, order: 4)
+      validate_range!(entries, mjd)
+
+      index = entries.bsearch_index { |e| e.mjd > mjd } || entries.size
+      center = index - 1
+
+      half = order / 2
+      start = center - half + 1
+      start = start.clamp(0, entries.size - order)
+
+      entries[start, order]
+    end
+
+    # @param entries [Array] sorted finals entries
+    # @param start_mjd [Float]
+    # @param end_mjd [Float]
+    # @return [Array] entries within the MJD range (inclusive)
+    def range(entries, start_mjd, end_mjd)
+      first = entries.bsearch_index { |e| e.mjd >= start_mjd } || entries.size
+      last = entries.bsearch_index { |e| e.mjd > end_mjd } || entries.size
+      entries[first...last]
+    end
+
+    # @param entries [Array] sorted finals entries
+    # @param mjd [Float]
+    # @return [Array] two-element array bracketing the query point
+    # @raise [OutOfRangeError]
+    def bracket(entries, mjd)
+      validate_range!(entries, mjd)
+
+      index = entries.bsearch_index { |e| e.mjd > mjd }
+
+      if index.nil? || index == 0
+        raise OutOfRangeError.new(
+          "No bracket available for MJD #{mjd}",
+          requested_mjd: mjd,
+          available_range: entries.first.mjd..entries.last.mjd
+        )
+      end
+
+      [entries[index - 1], entries[index]]
+    end
+
+    def validate_range!(entries, mjd)
+      first_mjd = entries.first.mjd
+      last_mjd = entries.last.mjd
+
+      return if mjd.between?(first_mjd, last_mjd)
+
+      raise OutOfRangeError.new(
+        "Requested MJD #{mjd} is outside available data " \
+        "(#{first_mjd}..#{last_mjd})",
+        requested_mjd: mjd,
+        available_range: first_mjd..last_mjd
+      )
+    end
+
+    private_class_method :validate_range!
+  end
+end

data/lib/iers/eop_parameter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module IERS
+  # @api private
+  module EopParameter
+    FLAG_TO_QUALITY = {"I" => :observed, "P" => :predicted}.freeze
+
+    def resolve(input, jd:, mjd:, interpolation:)
+      query_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+      entries = Data.finals_entries
+      method = interpolation || IERS.configuration.interpolation
+
+      window = case method
+      when :lagrange
+        order = IERS.configuration.lagrange_order
+        EopLookup.window(entries, query_mjd, order: order)
+      when :linear
+        EopLookup.bracket(entries, query_mjd)
+      end
+
+      [query_mjd, window, method]
+    end
+
+    def interpolate_field(window, query_mjd, method)
+      xs = window.map(&:mjd)
+      ys = window.map { |e| yield e }
+
+      case method
+      when :lagrange then Interpolation.lagrange(xs, ys, query_mjd)
+      when :linear then Interpolation.linear(xs, ys, query_mjd)
+      end
+    end
+
+    def derive_quality(window, flag)
+      if window.any? { |e| e.public_send(flag) == "P" }
+        :predicted
+      else
+        :observed
+      end
+    end
+  end
+end

data/lib/iers/errors.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module IERS
+  class Error < StandardError; end
+
+  class DataError < Error; end
+
+  class ParseError < DataError
+    # @return [Pathname, nil]
+    attr_reader :path
+    # @return [Integer, nil]
+    attr_reader :line_number
+
+    def initialize(message = nil, path: nil, line_number: nil)
+      @path = path
+      @line_number = line_number
+      super(message)
+    end
+  end
+
+  class FileNotFoundError < DataError
+    # @return [Pathname, nil]
+    attr_reader :path
+
+    def initialize(message = nil, path: nil)
+      @path = path
+      super(message)
+    end
+  end
+
+  class DownloadError < Error; end
+
+  class NetworkError < DownloadError
+    # @return [String, nil]
+    attr_reader :url
+    # @return [Integer, nil]
+    attr_reader :status_code
+
+    def initialize(message = nil, url: nil, status_code: nil)
+      @url = url
+      @status_code = status_code
+      super(message)
+    end
+  end
+
+  class ValidationError < DownloadError
+    # @return [Pathname, nil]
+    attr_reader :path
+    # @return [String, nil]
+    attr_reader :reason
+
+    def initialize(message = nil, path: nil, reason: nil)
+      @path = path
+      @reason = reason
+      super(message)
+    end
+  end
+
+  class StaleDataError < DataError
+    # @return [Date, nil]
+    attr_reader :predicted_until
+    # @return [Date, nil]
+    attr_reader :required_until
+
+    def initialize(message = nil, predicted_until: nil, required_until: nil)
+      @predicted_until = predicted_until
+      @required_until = required_until
+      super(message)
+    end
+  end
+
+  class ConfigurationError < Error; end
+
+  class OutOfRangeError < Error
+    # @return [Float, nil]
+    attr_reader :requested_mjd
+    # @return [Range<Float>, nil]
+    attr_reader :available_range
+
+    def initialize(message = nil, requested_mjd: nil, available_range: nil)
+      @requested_mjd = requested_mjd
+      @available_range = available_range
+      super(message)
+    end
+  end
+end

data/lib/iers/gmst.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module IERS
+  module GMST
+    TWO_PI = 2.0 * Math::PI
+
+    # IERS Conventions 2010, eq. 5.32 (arcseconds)
+    POLYNOMIAL = [
+      0.014506,
+      4612.156534,
+      1.3915817,
+      -0.00000044,
+      -0.000029956,
+      -0.0000000368
+    ].freeze
+
+    private_constant :TWO_PI, :POLYNOMIAL
+
+    module_function
+
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @param interpolation [Symbol, nil] +:lagrange+ or +:linear+
+    # @return [Float] Greenwich Mean Sidereal Time in radians, norm. to [0, 2π)
+    # @raise [OutOfRangeError]
+    def at(input = nil, jd: nil, mjd: nil, interpolation: nil)
+      query_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+      era = EarthRotationAngle.at(mjd: query_mjd, interpolation: interpolation)
+
+      tai_utc = LeapSecond.at(mjd: query_mjd)
+      tt_mjd = query_mjd +
+        (tai_utc + TimeScale::TT_TAI) / TimeScale::SECONDS_PER_DAY
+      t = (tt_mjd - TimeScale::MJD_J2000) / TimeScale::DAYS_PER_JULIAN_CENTURY
+
+      poly = POLYNOMIAL.reverse.reduce { |acc, c| acc * t + c }
+      gmst = (era + poly * TimeScale::ARCSEC_TO_RAD) % TWO_PI
+      gmst += TWO_PI if gmst < 0.0
+      gmst
+    end
+  end
+end

data/lib/iers/has_data_quality.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IERS
+  # @api private
+  module HasDataQuality
+    # @return [Boolean]
+    def observed?
+      data_quality == :observed
+    end
+
+    # @return [Boolean]
+    def predicted?
+      data_quality == :predicted
+    end
+  end
+end

data/lib/iers/has_date.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module IERS
+  # @api private
+  module HasDate
+    # @return [Date]
+    def date
+      TimeScale.to_date(mjd)
+    end
+  end
+end

data/lib/iers/interpolation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module IERS
+  # @api private
+  module Interpolation
+    module_function
+
+    # @param xs [Array<Float>] x-coordinates (exactly 2)
+    # @param ys [Array<Float>] y-coordinates (exactly 2)
+    # @param x [Float] interpolation point
+    # @return [Float]
+    def linear(xs, ys, x)
+      unless xs.size == 2 && ys.size == 2
+        raise ArgumentError, "linear interpolation requires exactly 2 points"
+      end
+
+      x0, x1 = xs
+      y0, y1 = ys
+      t = (x - x0) / (x1 - x0)
+      y0 + t * (y1 - y0)
+    end
+
+    # @param xs [Array<Float>] x-coordinates
+    # @param ys [Array<Float>] y-coordinates
+    # @param x [Float] interpolation point
+    # @return [Float]
+    def lagrange(xs, ys, x)
+      n = xs.size
+
+      unless n == ys.size
+        raise ArgumentError, "xs and ys must have the same size"
+      end
+
+      unless n >= 2
+        raise ArgumentError, "lagrange interpolation requires at least 2 points"
+      end
+
+      result = 0.0
+      n.times do |i|
+        basis = 1.0
+        n.times do |j|
+          next if i == j
+          basis *= (x - xs[j]) / (xs[i] - xs[j])
+        end
+        result += ys[i] * basis
+      end
+      result
+    end
+  end
+end

data/lib/iers/leap_second.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module IERS
+  module LeapSecond
+    # @attr effective_date [Date]
+    # @attr tai_utc [Integer] cumulative TAI−UTC offset in seconds
+    Entry = ::Data.define(:effective_date, :tai_utc)
+
+    @mutex = Mutex.new
+    @all = nil
+
+    module_function
+
+    # @return [Array<Entry>]
+    def all
+      @mutex.synchronize do
+        @all ||= IERS::Data.leap_second_entries.map do |parser_entry|
+          Entry.new(
+            effective_date: parser_entry.date,
+            tai_utc: parser_entry.tai_utc
+          )
+        end.freeze
+      end
+    end
+
+    # @return [void]
+    def clear_cached!
+      @mutex.synchronize do
+        @all = nil
+      end
+    end
+
+    # @return [Entry, nil]
+    def next_scheduled
+      today = Date.today
+      all.find { |entry| entry.effective_date > today }
+    end
+
+    # @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]
+    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
+
+      first_mjd = parser_entries.first.mjd
+      last_mjd = parser_entries.last.mjd
+
+      if query_mjd < first_mjd
+        raise OutOfRangeError.new(
+          "Requested MJD #{query_mjd} is before the first leap second " \
+          "entry (MJD #{first_mjd})",
+          requested_mjd: query_mjd,
+          available_range: first_mjd..last_mjd
+        )
+      end
+
+      index = parser_entries.bsearch_index { |e| e.mjd > query_mjd }
+
+      if index.nil?
+        parser_entries.last.tai_utc
+      else
+        parser_entries[index - 1].tai_utc
+      end
+    end
+  end
+end

data/lib/iers/length_of_day.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module IERS
+  module LengthOfDay
+    # @attr length_of_day [Float] excess LOD in seconds
+    # @attr mjd [Float] Modified Julian Date of the query
+    # @attr data_quality [Symbol] +:observed+ or +:predicted+
+    Entry = ::Data.define(:length_of_day, :mjd, :data_quality) do
+      include HasDate
+      include HasDataQuality
+    end
+
+    extend EopParameter
+
+    module_function
+
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @param interpolation [Symbol, nil] +:lagrange+ or +:linear+
+    # @return [Entry]
+    # @raise [OutOfRangeError]
+    def at(input = nil, jd: nil, mjd: nil, interpolation: nil)
+      query_mjd, window, method = resolve(
+        input,
+        jd: jd,
+        mjd: mjd,
+        interpolation: interpolation
+      )
+
+      lod = interpolate_field(window, query_mjd, method) { |e| e.lod / 1000.0 }
+
+      Entry.new(
+        length_of_day: lod,
+        mjd: query_mjd,
+        data_quality: derive_quality(window, :ut1_flag)
+      )
+    end
+
+    # @param start_date [Date]
+    # @param end_date [Date]
+    # @return [Enumerator::Lazy<Entry>]
+    def between(start_date, end_date)
+      start_mjd = TimeScale.to_mjd(start_date)
+      end_mjd = TimeScale.to_mjd(end_date)
+      entries = Data.finals_entries
+
+      EopLookup
+        .range(entries, start_mjd, end_mjd)
+        .lazy
+        .map do |e|
+          Entry.new(
+            length_of_day: e.lod / 1000.0,
+            mjd: e.mjd,
+            data_quality: EopParameter::FLAG_TO_QUALITY.fetch(e.ut1_flag, :observed)
+          )
+        end
+    end
+  end
+end

data/lib/iers/parsers/finals.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "date"
+
+module IERS
+  module Parsers
+    module Finals
+      Entry = Data.define(
+        :date, :mjd,
+        :pm_flag, :pm_x, :pm_x_error, :pm_y, :pm_y_error,
+        :ut1_flag, :ut1_utc, :ut1_utc_error,
+        :lod, :lod_error,
+        :nutation_flag, :dx, :dx_error, :dy, :dy_error,
+        :bulletin_b_pm_x, :bulletin_b_pm_y, :bulletin_b_ut1_utc,
+        :bulletin_b_dx, :bulletin_b_dy
+      )
+
+      MJD_Y2K_PIVOT = 51544.0
+
+      module_function
+
+      def parse(path)
+        path = Pathname(path)
+
+        unless path.exist?
+          raise FileNotFoundError.new(
+            "File not found: #{path}",
+            path: path.to_s
+          )
+        end
+
+        entries = []
+
+        path.each_line.with_index(1) do |line, line_number|
+          next if line.strip.empty?
+          next if no_eop_data?(line)
+
+          entries << parse_line(line, path, line_number)
+        end
+
+        entries.freeze
+      end
+
+      def parse_line(line, path, line_number)
+        mjd = parse_float(line, 7, 8)
+        yy = parse_int(line, 0, 2)
+        month = parse_int(line, 2, 2)
+        day = parse_int(line, 4, 2)
+        year = (mjd < MJD_Y2K_PIVOT) ? 1900 + yy : 2000 + yy
+
+        Entry.new(
+          date: Date.new(year, month, day),
+          mjd: mjd,
+          pm_flag: parse_flag(line, 16),
+          pm_x: parse_float(line, 18, 9),
+          pm_x_error: parse_float(line, 27, 9),
+          pm_y: parse_float(line, 37, 9),
+          pm_y_error: parse_float(line, 46, 9),
+          ut1_flag: parse_flag(line, 57),
+          ut1_utc: parse_float(line, 58, 10),
+          ut1_utc_error: parse_float(line, 68, 10),
+          lod: parse_optional_float(line, 79, 7),
+          lod_error: parse_optional_float(line, 86, 7),
+          nutation_flag: parse_optional_flag(line, 95),
+          dx: parse_optional_float(line, 97, 9),
+          dx_error: parse_optional_float(line, 106, 9),
+          dy: parse_optional_float(line, 116, 9),
+          dy_error: parse_optional_float(line, 125, 9),
+          bulletin_b_pm_x: parse_optional_float(line, 134, 10),
+          bulletin_b_pm_y: parse_optional_float(line, 144, 10),
+          bulletin_b_ut1_utc: parse_optional_float(line, 154, 11),
+          bulletin_b_dx: parse_optional_float(line, 165, 10),
+          bulletin_b_dy: parse_optional_float(line, 175, 10)
+        )
+      rescue ArgumentError, TypeError => e
+        raise ParseError.new(
+          "Failed to parse line #{line_number}: #{e.message}",
+          path: path.to_s,
+          line_number: line_number
+        )
+      end
+
+      def parse_float(line, offset, length)
+        Float(line[offset, length])
+      end
+
+      def parse_int(line, offset, length)
+        Integer(line[offset, length])
+      end
+
+      def parse_flag(line, offset)
+        line[offset, 1].strip
+      end
+
+      def parse_optional_float(line, offset, length)
+        raw = line[offset, length]
+        return nil if raw.nil? || raw.strip.empty?
+
+        Float(raw)
+      end
+
+      def parse_optional_flag(line, offset)
+        raw = line[offset, 1]
+        return nil if raw.nil? || raw.strip.empty?
+
+        raw.strip
+      end
+
+      def no_eop_data?(line)
+        flag = line[16, 1]
+        flag.nil? || flag.strip.empty?
+      end
+
+      private_class_method :parse_line,
+        :no_eop_data?,
+        :parse_float,
+        :parse_int,
+        :parse_flag,
+        :parse_optional_float,
+        :parse_optional_flag
+    end
+  end
+end

data/lib/iers/parsers/leap_second.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "date"
+
+module IERS
+  module Parsers
+    module LeapSecond
+      Entry = Data.define(:mjd, :date, :tai_utc)
+
+      module_function
+
+      def parse(path)
+        path = Pathname(path)
+
+        unless path.exist?
+          raise FileNotFoundError.new(
+            "File not found: #{path}",
+            path: path.to_s
+          )
+        end
+
+        entries = []
+
+        path.each_line.with_index(1) do |line, line_number|
+          next if line.strip.empty? || line.strip.start_with?("#")
+
+          entries << parse_line(line, path, line_number)
+        end
+
+        entries.freeze
+      end
+
+      def parse_line(line, path, line_number)
+        parts = line.split
+
+        Entry.new(
+          mjd: Float(parts[0]),
+          date: Date.new(
+            Integer(parts[3]),
+            Integer(parts[2]),
+            Integer(parts[1])
+          ),
+          tai_utc: Integer(parts[4])
+        )
+      rescue ArgumentError, TypeError => e
+        raise ParseError.new(
+          "Failed to parse line #{line_number}: #{e.message}",
+          path: path.to_s,
+          line_number: line_number
+        )
+      end
+
+      private_class_method :parse_line
+    end
+  end
+end

data/lib/iers/parsers.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "parsers/finals"
+require_relative "parsers/leap_second"