astronoby 0.9.0 → 0.10.0

data/lib/astronoby/duration.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Duration
+    include Comparable
+
+    class << self
+      # @return [Astronoby::Duration] a zero duration
+      def zero
+        new(0)
+      end
+
+      # @param seconds [Numeric] the duration in seconds
+      # @return [Astronoby::Duration] a new Duration
+      def from_seconds(seconds)
+        new(seconds)
+      end
+
+      # @param minutes [Numeric] the duration in minutes
+      # @return [Astronoby::Duration] a new Duration
+      def from_minutes(minutes)
+        seconds = minutes * Constants::SECONDS_PER_MINUTE
+        from_seconds(seconds)
+      end
+
+      # @param hours [Numeric] the duration in hours
+      # @return [Astronoby::Duration] a new Duration
+      def from_hours(hours)
+        seconds = hours * Constants::SECONDS_PER_HOUR
+        from_seconds(seconds)
+      end
+
+      # @param days [Numeric] the duration in days
+      # @return [Astronoby::Duration] a new Duration
+      def from_days(days)
+        seconds = days * Constants::SECONDS_PER_DAY
+        from_seconds(seconds)
+      end
+    end
+
+    # @return [Numeric] the duration in seconds
+    attr_reader :seconds
+
+    # @param seconds [Numeric] the duration in seconds
+    def initialize(seconds)
+      @seconds = seconds
+      freeze
+    end
+
+    # @return [Float] the duration in minutes
+    def minutes
+      @seconds / Constants::SECONDS_PER_MINUTE
+    end
+
+    # @return [Float] the duration in hours
+    def hours
+      @seconds / Constants::SECONDS_PER_HOUR
+    end
+
+    # @return [Float] the duration in days
+    def days
+      @seconds / Constants::SECONDS_PER_DAY
+    end
+
+    # @param other [Astronoby::Duration] duration to add
+    # @return [Astronoby::Duration] the sum
+    def +(other)
+      self.class.from_seconds(@seconds + other.seconds)
+    end
+
+    # @param other [Astronoby::Duration] duration to subtract
+    # @return [Astronoby::Duration] the difference
+    def -(other)
+      self.class.from_seconds(@seconds - other.seconds)
+    end
+
+    # @return [Astronoby::Duration] the negated duration
+    def -@
+      self.class.from_seconds(-@seconds)
+    end
+
+    # @return [Astronoby::Duration] the absolute duration
+    def abs
+      self.class.from_seconds(@seconds.abs)
+    end
+
+    # @return [Boolean] true if the duration is positive
+    def positive?
+      @seconds > 0
+    end
+
+    # @return [Boolean] true if the duration is negative
+    def negative?
+      @seconds < 0
+    end
+
+    # @return [Boolean] true if the duration is zero
+    def zero?
+      @seconds.zero?
+    end
+
+    # @return [Integer] hash value
+    def hash
+      [@seconds, self.class].hash
+    end
+
+    # @param other [Astronoby::Duration] duration to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      seconds <=> other.seconds
+    end
+    alias_method :eql?, :==
+  end
+end

data/lib/astronoby/earth_rotation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes Earth rotation matrices using Greenwich Sidereal Time.
+  # Provides both apparent (GAST-based) and mean (GMST-based) rotation
+  # matrices for transforming between Earth-fixed and celestial frames.
+  class EarthRotation
+    # Computes the apparent Earth rotation matrix R₃(GAST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 Earth rotation matrix
+    def self.matrix_for(instant)
+      new(instant: instant).matrix
+    end
+
+    # Computes the mean Earth rotation matrix R₃(GMST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 mean Earth rotation matrix
+    def self.mean_matrix_for(instant)
+      new(instant: instant).mean_matrix
+    end
+
+    # @param instant [Astronoby::Instant] the time instant
+    def initialize(instant:)
+      @instant = instant
+    end
+
+    # Computes R₃(GAST), the apparent Earth rotation matrix.
+    # GAST = GMST + equation of the equinoxes (Δψ cos ε₀).
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def matrix
+      rotation_matrix_for(gast)
+    end
+
+    # Computes R₃(GMST), the mean Earth rotation matrix.
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def mean_matrix
+      rotation_matrix_for(gmst)
+    end
+
+    private
+
+    def gmst
+      Angle.from_hours(@instant.gmst)
+    end
+
+    def gast
+      nutation = Nutation.new(instant: @instant)
+      dpsi = nutation.nutation_in_longitude
+      mean_obliquity = MeanObliquity.at(@instant)
+      Angle.from_radians(
+        gmst.radians + dpsi.radians * mean_obliquity.cos
+      )
+    end
+
+    def rotation_matrix_for(angle)
+      c, s = angle.cos, angle.sin
+      Matrix[
+        [c, -s, 0],
+        [s, c, 0],
+        [0, 0, 1]
+      ]
+    end
+  end
+end

data/lib/astronoby/equinox_solstice.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes the time of equinoxes and solstices for a given year.
+  #
+  # Source:
+  #  Title: Astronomical Algorithms
+  #  Author: Jean Meeus
+  #  Edition: 2nd edition
+  #  Chapter: 27 - Equinoxes and Soltices
   class EquinoxSolstice
-    # Source:
-    #  Title: Astronomical Algorithms
-    #  Author: Jean Meeus
-    #  Edition: 2nd edition
-    #  Chapter: 27 - Equinoxes and Soltices
-
     EVENTS = [
       MARCH_EQUINOX = 0,
       JUNE_SOLSTICE = 1,
@@ -73,22 +74,39 @@ module Astronoby
       [8, 15.45, 16859.074]
     ].freeze
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the March equinox
     def self.march_equinox(year, ephem)
       new(year, MARCH_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the June solstice
     def self.june_solstice(year, ephem)
       new(year, JUNE_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the September equinox
     def self.september_equinox(year, ephem)
       new(year, SEPTEMBER_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the December solstice
     def self.december_solstice(year, ephem)
       new(year, DECEMBER_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param event [Integer] one of MARCH_EQUINOX, JUNE_SOLSTICE,
+    #   SEPTEMBER_EQUINOX, or DECEMBER_SOLSTICE
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @raise [Astronoby::UnsupportedEventError] if event is invalid
     def initialize(year, event, ephem)
       unless EVENTS.include?(event)
         raise UnsupportedEventError.new(
@@ -97,12 +115,13 @@ module Astronoby
       end
 
       @event = event
+      @ephem = ephem
       @year = (year.to_i - 2000) / 1000.0
       uncorrected_time = compute
       @instant = Instant.from_time(uncorrected_time)
-      @sun = Sun.new(ephem: ephem, instant: @instant)
     end
 
+    # @return [Time] the corrected UTC time of the event
     def time
       Instant.from_terrestrial_time(@instant.tt + corrected).to_time.round
     end
@@ -135,8 +154,12 @@ module Astronoby
         component[4] * @year**4
     end
 
+    def sun
+      @sun ||= Sun.new(ephem: @ephem, instant: @instant)
+    end
+
     def corrected
-      longitude = @sun.apparent.ecliptic.longitude
+      longitude = sun.apparent.ecliptic.longitude
       58 * Angle.from_degrees(@event * 90 - longitude.degrees).sin
     end
   end

data/lib/astronoby/errors.rb

@@ -1,11 +1,22 @@
 module Astronoby
+  # Raised when arguments are mutually incompatible.
   class IncompatibleArgumentsError < ArgumentError; end
 
+  # Raised when an unsupported format is requested.
   class UnsupportedFormatError < ArgumentError; end
 
+  # Raised when an unsupported event type is requested.
   class UnsupportedEventError < ArgumentError; end
 
+  # Raised when an astronomical calculation fails.
   class CalculationError < StandardError; end
 
+  # Raised when there is an error with ephemeris data.
   class EphemerisError < StandardError; end
+
+  # Raised when an orientation kernel is not a supported orientation source.
+  class OrientationError < StandardError; end
+
+  # Raised when an orientation kernel does not cover the requested instant.
+  class OrientationOutOfRangeError < StandardError; end
 end

data/lib/astronoby/events/conjunction.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Conjunction
+    INFERIOR = :inferior
+    SUPERIOR = :superior
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @return [Astronoby::Conjunction] an inferior conjunction
+    def self.inferior(instant:, body:)
+      new(instant: instant, body: body, subtype: INFERIOR)
+    end
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @return [Astronoby::Conjunction] a superior conjunction
+    def self.superior(instant:, body:)
+      new(instant: instant, body: body, subtype: SUPERIOR)
+    end
+
+    # @return [Astronoby::Instant] when the conjunction occurs
+    attr_reader :instant
+
+    # @return [Astronoby::Body] the body in conjunction with the Sun
+    attr_reader :body
+
+    # @return [Symbol] +INFERIOR+ or +SUPERIOR+
+    attr_reader :subtype
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @param subtype [Symbol] +INFERIOR+ or +SUPERIOR+
+    def initialize(instant:, body:, subtype:)
+      @instant = instant
+      @body = body
+      @subtype = subtype
+      freeze
+    end
+
+    # @return [Boolean] true for an inferior conjunction
+    def inferior?
+      @subtype == INFERIOR
+    end
+
+    # @return [Boolean] true for a superior conjunction
+    def superior?
+      @subtype == SUPERIOR
+    end
+  end
+end

data/lib/astronoby/events/conjunction_opposition_calculator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class ConjunctionOppositionCalculator
+    # @param body [Astronoby::SolarSystemBody] the planet to track
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param samples_per_period [Integer] number of samples per synodic period
+    def initialize(body:, ephem:, samples_per_period: 60)
+      @body = body
+      @ephem = ephem
+      @samples_per_period = samples_per_period
+    end
+
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @return [Array<Astronoby::Conjunction>] conjunctions in the range
+    def conjunction_events_between(start_time, end_time)
+      roots_between(start_time, end_time, accept: method(:conjunction?))
+        .map { |jd| conjunction_at(Instant.from_terrestrial_time(jd)) }
+    end
+
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @return [Array<Astronoby::Opposition>] oppositions in the range
+    def opposition_events_between(start_time, end_time)
+      roots_between(start_time, end_time, accept: method(:opposition?))
+        .map do |jd|
+          Opposition.new(
+            instant: Instant.from_terrestrial_time(jd),
+            body: @body
+          )
+        end
+    end
+
+    private
+
+    def roots_between(start_time, end_time, accept:)
+      finder.roots(
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
+        accept: accept
+      )
+    end
+
+    def finder
+      @finder ||= RootFinder.new(
+        value_at: ->(jd) { delta_longitude_at(jd).sin },
+        period: synodic_period,
+        samples_per_period: @samples_per_period
+      )
+    end
+
+    def conjunction?(jd)
+      delta_longitude_at(jd).cos.positive?
+    end
+
+    def opposition?(jd)
+      delta_longitude_at(jd).cos.negative?
+    end
+
+    def delta_longitude_at(jd)
+      instant = Instant.from_terrestrial_time(jd)
+      planet = @body.new(instant: instant, ephem: @ephem)
+      sun = Sun.new(instant: instant, ephem: @ephem)
+      planet.apparent.ecliptic.longitude - sun.apparent.ecliptic.longitude
+    end
+
+    def conjunction_at(instant)
+      planet = @body.new(instant: instant, ephem: @ephem)
+      sun = Sun.new(instant: instant, ephem: @ephem)
+
+      if planet.apparent.distance < sun.apparent.distance
+        Conjunction.inferior(instant: instant, body: @body)
+      else
+        Conjunction.superior(instant: instant, body: @body)
+      end
+    end
+
+    def synodic_period
+      @synodic_period ||=
+        1.0 / ((1.0 / @body::ORBITAL_PERIOD) - (1.0 / Earth::ORBITAL_PERIOD)).abs
+    end
+  end
+end

data/lib/astronoby/events/eclipse_phase.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # A bounded phase of an eclipse, delimited by its two boundary instants.
+  class EclipsePhase
+    # @return [Astronoby::Instant] when the phase begins
+    attr_reader :starting_instant
+
+    # @return [Astronoby::Instant] when the phase ends
+    attr_reader :ending_instant
+
+    # @param starting_instant [Astronoby::Instant] when the phase begins
+    # @param ending_instant [Astronoby::Instant] when the phase ends
+    def initialize(starting_instant:, ending_instant:)
+      @starting_instant = starting_instant
+      @ending_instant = ending_instant
+      freeze
+    end
+
+    # @return [Astronoby::Duration] phase duration
+    def duration
+      Duration.from_seconds(
+        (@ending_instant.to_time - @starting_instant.to_time).round
+      )
+    end
+  end
+end

data/lib/astronoby/events/extremum_calculator.rb

@@ -1,49 +1,20 @@
 # frozen_string_literal: true
 
 module Astronoby
-  # Calculates extrema (minima and maxima) in the distance between two
-  # celestial bodies over a given time range using adaptive sampling and golden
-  # section search refinement.
   class ExtremumCalculator
-    # Mathematical constants
-    PHI = (1 + Math.sqrt(5)) / 2
-    INVPHI = 1 / PHI
-    GOLDEN_SECTION_TOLERANCE = 1e-5
-
-    # Algorithm parameters
-    MIN_SAMPLES_PER_PERIOD = 20
-    DUPLICATE_THRESHOLD_DAYS = 0.5
-    BOUNDARY_BUFFER_DAYS = 0.01
-
-    # Orbital periods
-    ORBITAL_PERIODS = {
-      "Astronoby::Moon" => 27.504339,
-      "Astronoby::Mercury" => 87.969,
-      "Astronoby::Venus" => 224.701,
-      "Astronoby::Earth" => 365.256,
-      "Astronoby::Mars" => 686.98,
-      "Astronoby::Jupiter" => 4332.59,
-      "Astronoby::Saturn" => 10759.22,
-      "Astronoby::Uranus" => 30688.5,
-      "Astronoby::Neptune" => 60182.0
-    }.freeze
-
-    # @param ephem [::Ephem::SPK] Ephemeris data source
-    # @param body [Astronoby::SolarSystemBody] The celestial body to track
-    # @param primary_body [Astronoby::SolarSystemBody] The reference body
-    #   (e.g., Sun for planetary orbits)
-    # @param samples_per_period [Integer] Number of samples to take per orbital
-    #   period
+    # @param body [Astronoby::SolarSystemBody] the celestial body to track
+    # @param primary_body [Astronoby::SolarSystemBody] the reference body
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param samples_per_period [Integer] number of samples per orbital period
     def initialize(
       body:,
       primary_body:,
       ephem:,
       samples_per_period: 60
     )
-      @ephem = ephem
       @body = body
       @primary_body = primary_body
-      @orbital_period = ORBITAL_PERIODS.fetch(body.name)
+      @ephem = ephem
       @samples_per_period = samples_per_period
     end
 
@@ -53,8 +24,8 @@ module Astronoby
     # @return [Array<Astronoby::ExtremumEvent>] Array of apoapsis events
     def apoapsis_events_between(start_time, end_time)
       find_extrema(
-        Astronoby::Instant.from_time(start_time).tt,
-        Astronoby::Instant.from_time(end_time).tt,
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
         type: :maximum
       )
     end
@@ -65,8 +36,8 @@ module Astronoby
     # @return [Array<Astronoby::ExtremumEvent>] Array of periapsis events
     def periapsis_events_between(start_time, end_time)
       find_extrema(
-        Astronoby::Instant.from_time(start_time).tt,
-        Astronoby::Instant.from_time(end_time).tt,
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
         type: :minimum
       )
     end
@@ -78,21 +49,24 @@ module Astronoby
     # @param type [Symbol] :maximum or :minimum
     # @return [Array<Astronoby::ExtremumEvent>] Array of extrema events
     def find_extrema(start_jd, end_jd, type: :maximum)
-      # 1: Find extrema candidates through adaptive sampling
-      candidates = find_extrema_candidates(start_jd, end_jd, type)
-
-      # 2: Refine each candidate using golden section search
-      refined_extrema = candidates
-        .map { |candidate| refine_extremum(candidate, type) }
-        .compact
-
-      # 3: Remove duplicates and boundary artifacts
-      refined_extrema = remove_duplicates(refined_extrema)
-      filter_boundary_artifacts(refined_extrema, start_jd, end_jd)
+      finder.extrema(start_jd, end_jd, type: type).map do |extremum|
+        ExtremumEvent.new(
+          Instant.from_terrestrial_time(extremum[:jd]),
+          extremum[:value]
+        )
+      end
     end
 
     private
 
+    def finder
+      @finder ||= ExtremumFinder.new(
+        value_at: method(:distance_at),
+        period: @body::ORBITAL_PERIOD,
+        samples_per_period: @samples_per_period
+      )
+    end
+
     def distance_at(jd)
       instant = Instant.from_terrestrial_time(jd)
       body_geometric = @body.geometric(ephem: @ephem, instant: instant)
@@ -102,132 +76,5 @@ module Astronoby
       distance_vector = body_geometric.position - primary_geometric.position
       distance_vector.magnitude
     end
-
-    def find_extrema_candidates(start_jd, end_jd, type)
-      samples = collect_samples(start_jd, end_jd)
-      find_local_extrema_in_samples(samples, type)
-    end
-
-    def collect_samples(start_jd, end_jd)
-      duration = end_jd - start_jd
-      sample_count = calculate_sample_count(duration)
-      step = duration / sample_count
-
-      (0..sample_count).map do |i|
-        jd = start_jd + (i * step)
-        {jd: jd, value: distance_at(jd)}
-      end
-    end
-
-    def calculate_sample_count(duration)
-      # Adaptive sampling: scale with duration and orbital period
-      periods_in_range = duration / @orbital_period
-      base_samples = (periods_in_range * @samples_per_period).to_i
-
-      # Ensure minimum sample density for short ranges
-      [base_samples, MIN_SAMPLES_PER_PERIOD].max
-    end
-
-    def find_local_extrema_in_samples(samples, type)
-      candidates = []
-
-      # Check each interior point for local extrema
-      (1...samples.length - 1).each do |i|
-        if local_extremum?(samples, i, type)
-          candidates << {
-            start_jd: samples[i - 1][:jd],
-            end_jd: samples[i + 1][:jd],
-            center_jd: samples[i][:jd]
-          }
-        end
-      end
-
-      candidates
-    end
-
-    def local_extremum?(samples, index, type)
-      current_val = samples[index][:value].m
-      prev_val = samples[index - 1][:value].m
-      next_val = samples[index + 1][:value].m
-
-      if type == :maximum
-        current_val > prev_val && current_val > next_val
-      else
-        current_val < prev_val && current_val < next_val
-      end
-    end
-
-    def refine_extremum(candidate, type)
-      golden_section_search(candidate[:start_jd], candidate[:end_jd], type)
-    end
-
-    def golden_section_search(a, b, type)
-      return nil if b <= a
-
-      tol = GOLDEN_SECTION_TOLERANCE * (b - a).abs
-
-      # Initial points using golden ratio
-      x1 = a + (1 - INVPHI) * (b - a)
-      x2 = a + INVPHI * (b - a)
-
-      f1 = distance_at(x1).m
-      f2 = distance_at(x2).m
-
-      while (b - a).abs > tol
-        should_keep_left = (type == :maximum) ? (f1 > f2) : (f1 < f2)
-
-        if should_keep_left
-          b = x2
-          x2 = x1
-          f2 = f1
-          x1 = a + (1 - INVPHI) * (b - a)
-          f1 = distance_at(x1).m
-        else
-          a = x1
-          x1 = x2
-          f1 = f2
-          x2 = a + INVPHI * (b - a)
-          f2 = distance_at(x2).m
-        end
-      end
-
-      mid = (a + b) / 2
-      ExtremumEvent.new(
-        Instant.from_terrestrial_time(mid),
-        distance_at(mid)
-      )
-    end
-
-    def remove_duplicates(extrema)
-      return extrema if extrema.length <= 1
-
-      cleaned = [extrema.first]
-
-      extrema.each_with_index do |current, i|
-        next if i == 0
-
-        is_duplicate = cleaned.any? do |existing|
-          time_diff = (
-            current.instant.tt - existing.instant.tt
-          ).abs
-          time_diff < DUPLICATE_THRESHOLD_DAYS
-        end
-
-        cleaned << current unless is_duplicate
-      end
-
-      cleaned
-    end
-
-    def filter_boundary_artifacts(extrema, start_jd, end_jd)
-      extrema.reject do |extreme|
-        start_diff = (extreme.instant.tt - start_jd).abs
-        end_diff = (extreme.instant.tt - end_jd).abs
-
-        too_close_to_start = start_diff < BOUNDARY_BUFFER_DAYS
-        too_close_to_end = end_diff < BOUNDARY_BUFFER_DAYS
-        too_close_to_start || too_close_to_end
-      end
-    end
   end
 end