iers 0.0.1 → 0.1.0

data/lib/iers/celestial_pole_offset.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module IERS
+  module CelestialPoleOffset
+    # @attr x [Float] dX correction in milliarcseconds
+    # @attr y [Float] dY correction in milliarcseconds
+    # @attr mjd [Float] Modified Julian Date of the query
+    # @attr data_quality [Symbol] +:observed+ or +:predicted+
+    Entry = ::Data.define(:x, :y, :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
+      )
+
+      x = interpolate_field(window, query_mjd, method) { |e| e.dx }
+      y = interpolate_field(window, query_mjd, method) { |e| e.dy }
+
+      Entry.new(
+        x: x, y: y,
+        mjd: query_mjd,
+        data_quality: derive_quality(window, :nutation_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(
+            x: e.dx,
+            y: e.dy,
+            mjd: e.mjd,
+            data_quality: EopParameter::FLAG_TO_QUALITY.fetch(e.nutation_flag, :observed)
+          )
+        end
+    end
+  end
+end

data/lib/iers/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module IERS
+  class Configuration
+    DEFAULT_CACHE_DIR = Pathname("~/.cache/iers").expand_path
+    DEFAULT_SOURCES = {
+      finals: "https://datacenter.iers.org/data/latestVersion/finals.all.iau2000.txt",
+      leap_seconds: "https://hpiers.obspm.fr/iers/bul/bulc/Leap_Second.dat"
+    }.freeze
+    DEFAULT_DOWNLOAD_TIMEOUT = 30
+    DEFAULT_INTERPOLATION = :lagrange
+    DEFAULT_LAGRANGE_ORDER = 4
+    INTERPOLATION_METHODS = %i[lagrange linear].freeze
+
+    # @return [Pathname]
+    attr_reader :cache_dir
+    # @return [Hash{Symbol => String}]
+    attr_reader :sources
+    # @return [Integer]
+    attr_reader :download_timeout
+    # @return [Pathname, nil]
+    attr_reader :finals_path
+    # @return [Pathname, nil]
+    attr_reader :leap_second_path
+    # @return [Symbol] +:lagrange+ or +:linear+
+    attr_reader :interpolation
+    # @return [Integer]
+    attr_reader :lagrange_order
+
+    def initialize
+      @cache_dir = DEFAULT_CACHE_DIR
+      @sources = DEFAULT_SOURCES.dup
+      @download_timeout = DEFAULT_DOWNLOAD_TIMEOUT
+      @finals_path = nil
+      @leap_second_path = nil
+      @interpolation = DEFAULT_INTERPOLATION
+      @lagrange_order = DEFAULT_LAGRANGE_ORDER
+    end
+
+    def cache_dir=(value)
+      @cache_dir = Pathname(value)
+    end
+
+    def sources=(value)
+      unless value.is_a?(Hash)
+        raise ConfigurationError, "sources must be a Hash"
+      end
+
+      @sources = value
+    end
+
+    def download_timeout=(value)
+      unless value.is_a?(Numeric) && value > 0
+        raise ConfigurationError, "download_timeout must be positive"
+      end
+
+      @download_timeout = value
+    end
+
+    def finals_path=(value)
+      @finals_path = value && Pathname(value)
+    end
+
+    def leap_second_path=(value)
+      @leap_second_path = value && Pathname(value)
+    end
+
+    def interpolation=(value)
+      unless INTERPOLATION_METHODS.include?(value)
+        raise ConfigurationError,
+          "interpolation must be one of: #{INTERPOLATION_METHODS.join(", ")}"
+      end
+
+      @interpolation = value
+    end
+
+    def lagrange_order=(value)
+      unless value.is_a?(Integer) && value > 0 && value.even?
+        raise ConfigurationError,
+          "lagrange_order must be a positive even integer"
+      end
+
+      @lagrange_order = value
+    end
+  end
+end

data/lib/iers/data.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module IERS
+  module Data
+    FILENAMES = {
+      finals: "finals2000A.all",
+      leap_seconds: "Leap_Second.dat"
+    }.freeze
+
+    BUNDLED_DIR = Pathname(__dir__).join("..", "..", "data").expand_path
+
+    @mutex = Mutex.new
+    @finals = nil
+    @leap_seconds = nil
+
+    module_function
+
+    # @return [Boolean]
+    def loaded?
+      !@finals.nil? || !@leap_seconds.nil?
+    end
+
+    # @param sources [Array<Symbol>] data sources to update (default: all)
+    # @return [UpdateResult]
+    def update!(*sources)
+      config = IERS.configuration
+      sources = config.sources.keys if sources.empty?
+
+      updated = []
+      errors = {}
+
+      sources.each do |source|
+        validate_source!(source, config)
+        url = config.sources[source]
+        dest = resolve_path(source, config)
+
+        begin
+          Downloader.new(timeout: config.download_timeout).fetch(url, dest)
+          updated << source
+        rescue DownloadError => e
+          errors[source] = e
+        end
+      end
+
+      UpdateResult.new(updated_files: updated, errors: errors)
+    end
+
+    # @return [DataStatus]
+    def status
+      config = IERS.configuration
+
+      if custom_paths_configured?(config)
+        DataStatus.new(source: :custom, cache_age: nil)
+      elsif cache_exists?(config)
+        age = oldest_cache_age(config)
+        DataStatus.new(source: :cached, cache_age: age)
+      else
+        DataStatus.new(source: :bundled, cache_age: nil)
+      end
+    end
+
+    # @return [void]
+    def clear_cache!
+      config = IERS.configuration
+
+      FILENAMES.each_value do |filename|
+        path = config.cache_dir.join(filename)
+        path.delete if path.exist?
+      end
+    end
+
+    # @param coverage_days_ahead [Integer, nil]
+    # @return [void]
+    # @raise [StaleDataError]
+    def ensure_fresh!(coverage_days_ahead: nil)
+      predicted_until = finals_entries.last.date
+      required_until = Date.today + (coverage_days_ahead || 0)
+
+      return if predicted_until >= required_until
+
+      raise StaleDataError.new(
+        "Predictions only extend to #{predicted_until} " \
+        "but coverage through #{required_until} is required",
+        predicted_until: predicted_until,
+        required_until: required_until
+      )
+    end
+
+    # @return [Array<Parsers::Finals::Entry>]
+    def finals_entries
+      @mutex.synchronize do
+        @finals ||= begin
+          path = resolve_read_path(:finals)
+          Parsers::Finals.parse(path).freeze
+        end
+      end
+    end
+
+    # @return [Array<Parsers::LeapSecond::Entry>]
+    def leap_second_entries
+      @mutex.synchronize do
+        @leap_seconds ||= begin
+          path = resolve_read_path(:leap_seconds)
+          Parsers::LeapSecond.parse(path).freeze
+        end
+      end
+    end
+
+    def resolve_path(source, config = IERS.configuration)
+      case source
+      when :finals
+        config.finals_path || config.cache_dir.join(FILENAMES[:finals])
+      when :leap_seconds
+        config.leap_second_path ||
+          config.cache_dir.join(FILENAMES[:leap_seconds])
+      end
+    end
+
+    def resolve_read_path(source, config = IERS.configuration)
+      path = resolve_path(source, config)
+      return path if Pathname(path).exist?
+
+      BUNDLED_DIR.join(FILENAMES[source])
+    end
+
+    def validate_source!(source, config)
+      return if config.sources.key?(source)
+
+      raise ConfigurationError,
+        "Unknown data source: #{source.inspect}. Valid sources: #{config.sources.keys.inspect}"
+    end
+
+    def custom_paths_configured?(config)
+      config.finals_path || config.leap_second_path
+    end
+
+    def cache_exists?(config)
+      FILENAMES.any? do |_, filename|
+        config.cache_dir.join(filename).exist?
+      end
+    end
+
+    def oldest_cache_age(config)
+      mtimes = FILENAMES.filter_map do |_, filename|
+        path = config.cache_dir.join(filename)
+        path.mtime if path.exist?
+      end
+
+      return nil if mtimes.empty?
+
+      (Time.now - mtimes.min).to_i
+    end
+
+    # @return [void]
+    def clear_loaded!
+      @mutex.synchronize do
+        @finals = nil
+        @leap_seconds = nil
+      end
+    end
+
+    private_class_method :resolve_path,
+      :resolve_read_path,
+      :validate_source!,
+      :custom_paths_configured?,
+      :cache_exists?,
+      :oldest_cache_age
+  end
+end

data/lib/iers/data_status.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+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
+    # @return [Boolean]
+    def cached?
+      source == :cached
+    end
+
+    # @return [Boolean]
+    def bundled?
+      source == :bundled
+    end
+
+    # @return [Boolean]
+    def custom?
+      source == :custom
+    end
+  end
+end

data/lib/iers/delta_t.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module IERS
+  module DeltaT
+    # @attr delta_t [Float] TT − UT1 in seconds
+    # @attr mjd [Float] Modified Julian Date of the query
+    # @attr source [Symbol] +:measured+ or +:estimated+
+    Entry = ::Data.define(:delta_t, :mjd, :source) do
+      # @return [Boolean]
+      def measured? = source == :measured
+
+      # @return [Boolean]
+      def estimated? = source == :estimated
+    end
+
+    EARLIEST_YEAR = 1800.0
+    PRE_1972_MJD = 41317.0
+    DAYS_PER_JULIAN_YEAR = 365.25
+    YEAR_J2000 = 2000.0
+
+    # Espenak & Meeus (2014) polynomial segments for 1800–1972.
+    # 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
+    POLYNOMIALS = [
+      [1800.0, 1860.0, 1800.0, [
+        13.72, -0.332447, 0.0068612, 0.0041116,
+        -0.00037436, 0.0000121272, -0.0000001699, 0.000000000875
+      ].freeze],
+      [1860.0, 1900.0, 1860.0, [
+        7.62, 0.5737, -0.251754, 0.01680668,
+        -0.0004473624, 1.0 / 233174
+      ].freeze],
+      [1900.0, 1920.0, 1900.0, [
+        -2.79, 1.494119, -0.0598939, 0.0061966, -0.000197
+      ].freeze],
+      [1920.0, 1941.0, 1920.0, [
+        21.20, 0.84493, -0.076100, 0.0020936
+      ].freeze],
+      [1941.0, 1961.0, 1950.0, [
+        29.07, 0.407, -1.0 / 233, 1.0 / 2547
+      ].freeze],
+      [1961.0, 1986.0, 1975.0, [
+        45.45, 1.067, -1.0 / 260, -1.0 / 718
+      ].freeze]
+    ].freeze
+
+    private_constant :EARLIEST_YEAR,
+      :PRE_1972_MJD,
+      :DAYS_PER_JULIAN_YEAR,
+      :YEAR_J2000,
+      :POLYNOMIALS
+
+    module_function
+
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @return [Entry] DeltaT (TT − UT1) in seconds with source metadata
+    # @raise [OutOfRangeError]
+    def at(input = nil, jd: nil, mjd: nil)
+      query_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+      y = mjd_to_decimal_year(query_mjd)
+
+      if y < EARLIEST_YEAR
+        raise OutOfRangeError.new(
+          "DeltaT is only available from #{EARLIEST_YEAR.to_i} onward",
+          requested_mjd: query_mjd
+        )
+      end
+
+      if query_mjd < PRE_1972_MJD
+        Entry.new(
+          delta_t: polynomial_delta_t(y),
+          mjd: query_mjd,
+          source: :estimated
+        )
+      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
+        )
+      end
+    end
+
+    def polynomial_delta_t(y)
+      segment = POLYNOMIALS.find { |s| y < s[1] } || POLYNOMIALS.last
+      t = y - segment[2]
+      segment[3].reverse.reduce { |acc, c| acc * t + c }
+    end
+
+    def mjd_to_decimal_year(mjd)
+      YEAR_J2000 + (mjd - TimeScale::MJD_J2000) / DAYS_PER_JULIAN_YEAR
+    end
+
+    private_class_method :polynomial_delta_t, :mjd_to_decimal_year
+  end
+end

data/lib/iers/downloader.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "tempfile"
+
+module IERS
+  class Downloader
+    MAX_REDIRECTS = 5
+
+    def initialize(timeout:)
+      @timeout = timeout
+    end
+
+    def fetch(url, dest_path)
+      dest_path = Pathname(dest_path)
+      dest_path.dirname.mkpath
+
+      body = http_get(url)
+      validate!(body, dest_path)
+      atomic_write(dest_path, body)
+    end
+
+    private
+
+    def http_get(url, redirect_count = 0)
+      if redirect_count > MAX_REDIRECTS
+        raise NetworkError.new(
+          "Too many redirects",
+          url: url,
+          status_code: nil
+        )
+      end
+
+      uri = URI.parse(url)
+      response = perform_request(uri)
+
+      case response
+      when Net::HTTPRedirection
+        location = response["Location"]
+        resolved = uri + location
+        http_get(resolved.to_s, redirect_count + 1)
+      when Net::HTTPSuccess
+        response.body
+      else
+        raise NetworkError.new(
+          "HTTP #{response.code}: #{response.message}",
+          url: url,
+          status_code: response.code.to_i
+        )
+      end
+    rescue SocketError,
+      Errno::ECONNRESET,
+      Errno::ECONNREFUSED,
+      Net::OpenTimeout,
+      Net::ReadTimeout => e
+      raise NetworkError.new(e.message, url: url, status_code: nil)
+    end
+
+    def perform_request(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.get(uri.request_uri)
+    end
+
+    def validate!(body, dest_path)
+      return unless body.nil? || body.empty?
+
+      raise ValidationError.new(
+        "Downloaded file is empty",
+        path: dest_path.to_s,
+        reason: "empty response body"
+      )
+    end
+
+    def atomic_write(dest_path, body)
+      tempfile = Tempfile.new("iers", dest_path.dirname.to_s)
+      tempfile.binmode
+      tempfile.write(body)
+      tempfile.close
+      File.rename(tempfile.path, dest_path.to_s)
+    rescue
+      tempfile&.close!
+      raise
+    end
+  end
+end

data/lib/iers/earth_rotation_angle.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module IERS
+  module EarthRotationAngle
+    # ERA at J2000.0 in fractional turns
+    # (IERS Conventions 2010, eq. 5.15; IAU 2000 Resolution B1.8)
+    ERA_AT_J2000 = 0.7790572732640
+
+    # Ratio of universal to sidereal time
+    # (IERS Conventions 2010, eq. 5.15; IAU 2000 Resolution B1.8)
+    ERA_RATE = 1.00273781191135448
+
+    TWO_PI = 2.0 * Math::PI
+
+    private_constant :ERA_AT_J2000, :ERA_RATE, :TWO_PI
+
+    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] Earth Rotation Angle in radians, normalized 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)
+      ut1_utc = UT1.at(mjd: query_mjd, interpolation: interpolation).ut1_utc
+
+      du = query_mjd - TimeScale::MJD_J2000 +
+        ut1_utc / TimeScale::SECONDS_PER_DAY
+
+      # IERS Conventions 2010, eq. 5.15
+      turns = ERA_AT_J2000 + ERA_RATE * du
+      era = (turns % 1.0) * TWO_PI
+      era += TWO_PI if era < 0.0
+      era
+    end
+  end
+end

data/lib/iers/eop.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module IERS
+  module EOP
+    # @attr polar_motion_x [Float] pole x-coordinate in arcseconds
+    # @attr polar_motion_y [Float] pole y-coordinate in arcseconds
+    # @attr ut1_utc [Float] UT1−UTC in seconds
+    # @attr length_of_day [Float] excess LOD in seconds
+    # @attr celestial_pole_x [Float] dX correction in milliarcseconds
+    # @attr celestial_pole_y [Float] dY correction in milliarcseconds
+    # @attr mjd [Float] Modified Julian Date of the query
+    # @attr data_quality [Symbol] +:observed+ or +:predicted+
+    Entry = ::Data.define(
+      :polar_motion_x,
+      :polar_motion_y,
+      :ut1_utc,
+      :length_of_day,
+      :celestial_pole_x,
+      :celestial_pole_y,
+      :mjd,
+      :data_quality
+    ) do
+      include HasDate
+      include HasDataQuality
+    end
+
+    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 = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+      interp = interpolation ? {interpolation: interpolation} : {}
+
+      pm = PolarMotion.at(mjd: query_mjd, **interp)
+      ut1 = UT1.at(mjd: query_mjd, **interp)
+      cpo = CelestialPoleOffset.at(mjd: query_mjd, **interp)
+      lod = LengthOfDay.at(mjd: query_mjd, **interp)
+
+      quality = if [pm, ut1, cpo, lod].any?(&:predicted?)
+        :predicted
+      else
+        :observed
+      end
+
+      Entry.new(
+        polar_motion_x: pm.x,
+        polar_motion_y: pm.y,
+        ut1_utc: ut1.ut1_utc,
+        length_of_day: lod.length_of_day,
+        celestial_pole_x: cpo.x,
+        celestial_pole_y: cpo.y,
+        mjd: query_mjd,
+        data_quality: quality
+      )
+    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 { |e| entry_from_parser(e) }
+    end
+
+    def entry_from_parser(e)
+      Entry.new(
+        polar_motion_x: e.bulletin_b_pm_x || e.pm_x,
+        polar_motion_y: e.bulletin_b_pm_y || e.pm_y,
+        ut1_utc: e.bulletin_b_ut1_utc || e.ut1_utc,
+        length_of_day: e.lod / 1000.0,
+        celestial_pole_x: e.dx,
+        celestial_pole_y: e.dy,
+        mjd: e.mjd,
+        data_quality: derive_quality(e)
+      )
+    end
+
+    def derive_quality(entry)
+      flags = [
+        entry.pm_flag,
+        entry.ut1_flag,
+        entry.nutation_flag
+      ]
+      if flags.include?("P")
+        :predicted
+      else
+        :observed
+      end
+    end
+
+    private_class_method :entry_from_parser, :derive_quality
+  end
+end