astronoby 0.9.0 → 0.11.0

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

data/lib/astronoby/events/greatest_elongation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class GreatestElongation
+    EASTERN = :eastern
+    WESTERN = :western
+
+    # @param instant [Astronoby::Instant] when the greatest elongation occurs
+    # @param body [Astronoby::Body] the body reaching greatest elongation
+    # @param angle [Astronoby::Angle] the Sun-Earth-body angle at that instant
+    # @return [Astronoby::GreatestElongation] a greatest eastern elongation
+    def self.eastern(instant:, body:, angle:)
+      new(instant: instant, body: body, angle: angle, direction: EASTERN)
+    end
+
+    # @param instant [Astronoby::Instant] when the greatest elongation occurs
+    # @param body [Astronoby::Body] the body reaching greatest elongation
+    # @param angle [Astronoby::Angle] the Sun-Earth-body angle at that instant
+    # @return [Astronoby::GreatestElongation] a greatest western elongation
+    def self.western(instant:, body:, angle:)
+      new(instant: instant, body: body, angle: angle, direction: WESTERN)
+    end
+
+    # @return [Astronoby::Instant] when the greatest elongation occurs
+    attr_reader :instant
+
+    # @return [Astronoby::Body] the body reaching greatest elongation
+    attr_reader :body
+
+    # @return [Astronoby::Angle] the Sun-Earth-body angle at that instant
+    attr_reader :angle
+
+    # @return [Symbol] +EASTERN+ or +WESTERN+
+    attr_reader :direction
+
+    # @param instant [Astronoby::Instant] when the greatest elongation occurs
+    # @param body [Astronoby::Body] the body reaching greatest elongation
+    # @param angle [Astronoby::Angle] the Sun-Earth-body angle at that instant
+    # @param direction [Symbol] +EASTERN+ or +WESTERN+
+    def initialize(instant:, body:, angle:, direction:)
+      @instant = instant
+      @body = body
+      @angle = angle
+      @direction = direction
+      freeze
+    end
+
+    # @return [Boolean] true for a greatest eastern elongation
+    def eastern?
+      @direction == EASTERN
+    end
+
+    # @return [Boolean] true for a greatest western elongation
+    def western?
+      @direction == WESTERN
+    end
+  end
+end

data/lib/astronoby/events/greatest_elongation_calculator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class GreatestElongationCalculator
+    # @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::GreatestElongation>] greatest elongations in
+    #   the range
+    def greatest_elongation_events_between(start_time, end_time)
+      finder.extrema(
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
+        type: :maximum
+      ).map { |extremum| build_event(extremum) }
+    end
+
+    private
+
+    def finder
+      @finder ||= ExtremumFinder.new(
+        value_at: ->(jd) { planet_at(jd).elongation },
+        period: synodic_period,
+        samples_per_period: @samples_per_period
+      )
+    end
+
+    def build_event(extremum)
+      instant = Instant.from_terrestrial_time(extremum[:jd])
+      angle = extremum[:value]
+
+      if planet_at(instant.tt).eastern?
+        GreatestElongation.eastern(instant: instant, body: @body, angle: angle)
+      else
+        GreatestElongation.western(instant: instant, body: @body, angle: angle)
+      end
+    end
+
+    def planet_at(jd)
+      @body.new(instant: Instant.from_terrestrial_time(jd), ephem: @ephem)
+    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/lunar_eclipse.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # A lunar eclipse: a geocentric passage of the Moon through Earth's shadow.
+  # Immutable; built by LunarEclipseCalculator.
+  #
+  # The penumbral phase is always present. The partial phase is present for
+  # partial and total eclipses, and the total phase only for total eclipses.
+  class LunarEclipse
+    PENUMBRAL = :penumbral
+    PARTIAL = :partial
+    TOTAL = :total
+
+    # @return [Astronoby::Instant] greatest eclipse, when the Moon's centre is
+    #   least distant from the axis of Earth's shadow
+    attr_reader :instant
+    alias_method :greatest_eclipse_instant, :instant
+
+    # @return [Symbol] +PENUMBRAL+, +PARTIAL+ or +TOTAL+
+    attr_reader :kind
+
+    # @return [Astronoby::LunarEclipseGeometry] the geometry of Earth's shadow
+    #   and the Moon's place in it at greatest eclipse. The geometry at each
+    #   contact is on the phases.
+    attr_reader :geometry
+
+    # @return [Astronoby::LunarEclipsePhase] the penumbral phase (always present)
+    attr_reader :penumbral
+
+    # @return [Astronoby::LunarEclipsePhase, nil] the partial phase, present for
+    #   partial and total eclipses
+    attr_reader :partial
+
+    # @return [Astronoby::LunarEclipsePhase, nil] the total phase (totality),
+    #   present only for total eclipses
+    attr_reader :total
+
+    # @param instant [Astronoby::Instant] greatest eclipse
+    # @param kind [Symbol] +PENUMBRAL+, +PARTIAL+ or +TOTAL+
+    # @param geometry [Astronoby::LunarEclipseGeometry] the shadow geometry at
+    #   greatest eclipse
+    # @param penumbral [Astronoby::LunarEclipsePhase] the penumbral phase
+    # @param partial [Astronoby::LunarEclipsePhase, nil] the partial phase
+    # @param total [Astronoby::LunarEclipsePhase, nil] the total phase
+    def initialize(
+      instant:,
+      kind:,
+      geometry:,
+      penumbral:,
+      partial: nil,
+      total: nil
+    )
+      @instant = instant
+      @kind = kind
+      @geometry = geometry
+      @penumbral = penumbral
+      @partial = partial
+      @total = total
+      freeze
+    end
+
+    # @return [Float] least distance of the Moon's centre from the axis of
+    #   Earth's shadow at greatest eclipse, in Earth radii, positive when the
+    #   Moon passes north of the axis
+    def gamma
+      sign = @geometry.north_of_axis? ? 1 : -1
+      sign * @geometry.axis_distance.m /
+        Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS
+    end
+
+    # @return [Float] fraction of the Moon's diameter immersed in the umbra at
+    #   greatest eclipse (negative when the Moon misses the umbra)
+    def umbral_magnitude
+      @geometry.umbral_magnitude
+    end
+
+    # @return [Float] fraction of the Moon's diameter immersed in the penumbra
+    #   at greatest eclipse
+    def penumbral_magnitude
+      @geometry.penumbral_magnitude
+    end
+
+    # @return [Astronoby::Distance] least distance of the Moon's centre from the
+    #   axis of Earth's shadow at greatest eclipse. This is the unsigned length
+    #   of which gamma is the value in Earth radii.
+    def shadow_axis_distance
+      @geometry.axis_distance
+    end
+
+    # @return [Boolean] true for a penumbral eclipse (the Moon misses the umbra)
+    def penumbral?
+      @kind == PENUMBRAL
+    end
+
+    # @return [Boolean] true for a partial eclipse
+    def partial?
+      @kind == PARTIAL
+    end
+
+    # @return [Boolean] true for a total eclipse
+    def total?
+      @kind == TOTAL
+    end
+
+    # @param observer [Astronoby::Observer] the observer
+    # @return [Astronoby::LunarEclipseVisibility] the local circumstances
+    def visibility_from(observer)
+      LunarEclipseVisibility.new(eclipse: self, observer: observer)
+    end
+  end
+end