iers 0.0.1 → 0.1.0

data/lib/iers/polar_motion.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module IERS
+  module PolarMotion
+    # TIO locator rate in arcseconds per Julian century
+    # (IERS Conventions 2010, eq. 5.13)
+    S_PRIME_RATE = -0.000047
+
+    # @attr x [Float] pole x-coordinate in arcseconds
+    # @attr y [Float] pole y-coordinate in arcseconds
+    # @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
+
+      # Polar motion rotation matrix W per IERS Conventions 2010, Section 5.4.1:
+      # W = R3(-s') * R2(xp) * R1(yp)
+      #
+      # All elements use exact trigonometry — no small-angle approximation.
+      #
+      # @return [Array<Array<Float>>] 3x3 rotation matrix
+      def rotation_matrix
+        xp = x * TimeScale::ARCSEC_TO_RAD
+        yp = y * TimeScale::ARCSEC_TO_RAD
+        t = (mjd - TimeScale::MJD_J2000) / TimeScale::DAYS_PER_JULIAN_CENTURY
+        sp = S_PRIME_RATE * t * TimeScale::ARCSEC_TO_RAD
+
+        cx, sx = Math.cos(xp), Math.sin(xp)
+        cy, sy = Math.cos(yp), Math.sin(yp)
+        cs, ss = Math.cos(sp), Math.sin(sp)
+
+        [
+          [cx * cs, cx * ss, sx],
+          [sy * sx * cs - cy * ss, cy * cs + sy * sx * ss, -sy * cx],
+          [-sy * ss - cy * sx * cs, sy * cs - cy * sx * ss, cy * cx]
+        ]
+      end
+    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| best_pm(e, :x) }
+      y = interpolate_field(window, query_mjd, method) { |e| best_pm(e, :y) }
+
+      Entry.new(
+        x: x, y: y,
+        mjd: query_mjd,
+        data_quality: derive_quality(window, :pm_flag)
+      )
+    end
+
+    # @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 [Array<Array<Float>>] 3x3 polar motion rotation matrix
+    # @raise [OutOfRangeError]
+    def rotation_matrix_at(input = nil, jd: nil, mjd: nil, interpolation: nil)
+      at(input, jd: jd, mjd: mjd, interpolation: interpolation)
+        .rotation_matrix
+    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: best_pm(e, :x),
+            y: best_pm(e, :y),
+            mjd: e.mjd,
+            data_quality: EopParameter::FLAG_TO_QUALITY.fetch(
+              e.pm_flag, :observed
+            )
+          )
+        end
+    end
+
+    def best_pm(entry, component)
+      case component
+      when :x
+        entry.bulletin_b_pm_x || entry.pm_x
+      when :y
+        entry.bulletin_b_pm_y || entry.pm_y
+      end
+    end
+
+    private_class_method :best_pm
+  end
+end

data/lib/iers/tai.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module IERS
+  module TAI
+    module_function
+
+    # Convert a UTC instant to TAI.
+    #
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @return [Float] Modified Julian Date in TAI scale
+    # @raise [OutOfRangeError]
+    def utc_to_tai(input = nil, jd: nil, mjd: nil)
+      utc_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+      tai_utc = LeapSecond.at(mjd: utc_mjd)
+      utc_mjd + tai_utc / TimeScale::SECONDS_PER_DAY
+    end
+
+    # Convert a TAI instant to UTC.
+    #
+    # Uses the TAI instant for an initial leap second lookup, then
+    # verifies the offset at the derived UTC. If TAI and UTC straddle
+    # a leap second boundary the first lookup may be off by one second;
+    # the verification step corrects this exactly.
+    #
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @return [Float] Modified Julian Date in UTC scale
+    # @raise [OutOfRangeError]
+    def tai_to_utc(input = nil, jd: nil, mjd: nil)
+      tai_mjd = TimeScale.to_mjd(input, jd: jd, mjd: mjd)
+
+      initial_offset = LeapSecond.at(mjd: tai_mjd)
+      utc_mjd = tai_mjd - initial_offset / TimeScale::SECONDS_PER_DAY
+
+      verified_offset = LeapSecond.at(mjd: utc_mjd)
+      return utc_mjd if verified_offset == initial_offset
+
+      tai_mjd - verified_offset / TimeScale::SECONDS_PER_DAY
+    end
+  end
+end

data/lib/iers/terrestrial_rotation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module IERS
+  module TerrestrialRotation
+    module_function
+
+    # Compute R(ERA) × W, the rotation from ITRS to TIRS
+    # (IERS Conventions 2010, eq. 5.1), combining the Earth Rotation
+    # Angle and polar motion matrices.
+    #
+    # @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 [Array<Array<Float>>] 3×3 rotation matrix (row-major)
+    # @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)
+      w = PolarMotion.rotation_matrix_at(
+        mjd: query_mjd, interpolation: interpolation
+      )
+
+      multiply(r3_matrix(era), w)
+    end
+
+    def r3_matrix(angle)
+      c = Math.cos(angle)
+      s = Math.sin(angle)
+
+      [
+        [c, s, 0.0],
+        [-s, c, 0.0],
+        [0.0, 0.0, 1.0]
+      ]
+    end
+
+    def multiply(a, b)
+      Array.new(3) { |i|
+        Array.new(3) { |j|
+          a[i].zip(b.map { |r| r[j] }).sum { |x, y| x * y }
+        }
+      }
+    end
+
+    private_class_method :r3_matrix, :multiply
+  end
+end

data/lib/iers/time_scale.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "date"
+
+module IERS
+  # @api private
+  module TimeScale
+    JD_MJD_OFFSET = 2_400_000.5
+    JD_J2000 = 2_451_545.0
+    MJD_J2000 = 51_544.5
+    DAYS_PER_JULIAN_CENTURY = 36_525.0
+    SECONDS_PER_DAY = 86_400.0
+    ARCSEC_TO_RAD = Math::PI / 648_000.0
+    TT_TAI = 32.184 # seconds
+
+    module_function
+
+    # @param mjd [Float] Modified Julian Date
+    # @return [Date]
+    def to_date(mjd)
+      Date.jd((mjd.floor + JD_MJD_OFFSET).ceil)
+    end
+
+    # @param input [Time, Date, DateTime, nil]
+    # @param jd [Float, nil] Julian Date
+    # @param mjd [Float, nil] Modified Julian Date
+    # @return [Float] Modified Julian Date
+    # @raise [ArgumentError] if no valid input is provided
+    def to_mjd(input = nil, jd: nil, mjd: nil)
+      if mjd
+        Float(mjd)
+      elsif jd
+        Float(jd) - JD_MJD_OFFSET
+      elsif input.is_a?(Time)
+        input.to_datetime.ajd.to_f - JD_MJD_OFFSET
+      elsif input.is_a?(Date)
+        input.ajd.to_f - JD_MJD_OFFSET
+      else
+        raise ArgumentError,
+          "Expected Time, Date, DateTime, jd: or mjd: keyword, " \
+          "got #{input.inspect}"
+      end
+    end
+  end
+end

data/lib/iers/update_result.rb

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

data/lib/iers/ut1.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module IERS
+  module UT1
+    # @attr ut1_utc [Float] UT1−UTC in seconds
+    # @attr mjd [Float] Modified Julian Date of the query
+    # @attr data_quality [Symbol] +:observed+ or +:predicted+
+    Entry = ::Data.define(:ut1_utc, :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
+      )
+
+      ut1_utc = interpolate_ut1(window, query_mjd, method)
+
+      Entry.new(
+        ut1_utc: ut1_utc,
+        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(
+            ut1_utc: best_ut1_utc(e),
+            mjd: e.mjd,
+            data_quality: EopParameter::FLAG_TO_QUALITY.fetch(e.ut1_flag, :observed)
+          )
+        end
+    end
+
+    def interpolate_ut1(window, query_mjd, method)
+      leap_entries = Data.leap_second_entries
+      tai_utc_at_query = tai_utc_for(leap_entries, query_mjd)
+
+      ut1_tai = interpolate_field(window, query_mjd, method) do |e|
+        best_ut1_utc(e) - tai_utc_for(leap_entries, e.mjd)
+      end
+
+      ut1_tai + tai_utc_at_query
+    end
+
+    def tai_utc_for(entries, mjd)
+      index = entries.bsearch_index { |e| e.mjd > mjd }
+      index.nil? ? entries.last.tai_utc : entries[index - 1].tai_utc
+    end
+
+    def best_ut1_utc(entry)
+      entry.bulletin_b_ut1_utc || entry.ut1_utc
+    end
+
+    private_class_method :interpolate_ut1,
+      :tai_utc_for,
+      :best_ut1_utc
+  end
+end

data/lib/iers/version.rb

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

data/lib/iers.rb

@@ -1,6 +1,54 @@
 # frozen_string_literal: true
 
 require_relative "iers/version"
+require_relative "iers/errors"
+require_relative "iers/configuration"
+require_relative "iers/update_result"
+require_relative "iers/data_status"
+require_relative "iers/downloader"
+require_relative "iers/parsers"
+require_relative "iers/data"
+require_relative "iers/time_scale"
+require_relative "iers/has_date"
+require_relative "iers/has_data_quality"
+require_relative "iers/interpolation"
+require_relative "iers/eop_lookup"
+require_relative "iers/eop_parameter"
+require_relative "iers/leap_second"
+require_relative "iers/tai"
+require_relative "iers/ut1"
+require_relative "iers/polar_motion"
+require_relative "iers/celestial_pole_offset"
+require_relative "iers/length_of_day"
+require_relative "iers/delta_t"
+require_relative "iers/earth_rotation_angle"
+require_relative "iers/gmst"
+require_relative "iers/terrestrial_rotation"
+require_relative "iers/eop"
 
 module IERS
+  class << self
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @yield [Configuration]
+    # @return [void]
+    def configure
+      yield configuration
+    end
+
+    # @return [void]
+    def reset_configuration!
+      @configuration = nil
+      Data.clear_loaded!
+      LeapSecond.clear_cached!
+    end
+
+    # @return [void]
+    def reset!
+      reset_configuration!
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iers
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Rémy Hannequin
@@ -107,6 +107,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Access to Earth orientation parameters and time scale values from the
   International Earth Rotation and Reference Systems Service (IERS).
 email:
@@ -115,12 +143,41 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- data/Leap_Second.dat
+- data/finals2000A.all
 - lib/iers.rb
+- lib/iers/celestial_pole_offset.rb
+- lib/iers/configuration.rb
+- lib/iers/data.rb
+- lib/iers/data_status.rb
+- lib/iers/delta_t.rb
+- lib/iers/downloader.rb
+- lib/iers/earth_rotation_angle.rb
+- lib/iers/eop.rb
+- lib/iers/eop_lookup.rb
+- lib/iers/eop_parameter.rb
+- lib/iers/errors.rb
+- lib/iers/gmst.rb
+- lib/iers/has_data_quality.rb
+- lib/iers/has_date.rb
+- lib/iers/interpolation.rb
+- lib/iers/leap_second.rb
+- lib/iers/length_of_day.rb
+- lib/iers/parsers.rb
+- lib/iers/parsers/finals.rb
+- lib/iers/parsers/leap_second.rb
+- lib/iers/polar_motion.rb
+- lib/iers/tai.rb
+- lib/iers/terrestrial_rotation.rb
+- lib/iers/time_scale.rb
+- lib/iers/update_result.rb
+- lib/iers/ut1.rb
 - lib/iers/version.rb
 homepage: https://github.com/rhannequin/iers
 licenses: