astronoby 0.9.0 → 0.11.0

data/lib/astronoby/events/lunar_eclipse_visibility.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class LunarEclipseVisibility
+    NOT_VISIBLE = :not_visible
+    ENTIRELY_VISIBLE = :entirely_visible
+    BEGINS_BEFORE_MOONRISE = :begins_before_moonrise
+    ENDS_AFTER_MOONSET = :ends_after_moonset
+    PARTIALLY_VISIBLE = :partially_visible
+
+    PHASES = [
+      LunarEclipse::PENUMBRAL,
+      LunarEclipse::PARTIAL,
+      LunarEclipse::TOTAL
+    ].freeze
+
+    SAMPLING_INTERVAL_IN_DAYS =
+      3.0 / Constants::HOURS_PER_DAY / Constants::MINUTES_PER_HOUR
+
+    RADIANS_PER_HOUR =
+      Constants::RADIANS_PER_CIRCLE / Constants::HOURS_PER_DAY
+
+    private_constant :SAMPLING_INTERVAL_IN_DAYS
+    private_constant :RADIANS_PER_HOUR
+
+    # @return [Astronoby::LunarEclipse] the eclipse
+    attr_reader :eclipse
+
+    # @return [Astronoby::Observer] the observer
+    attr_reader :observer
+
+    # @param eclipse [Astronoby::LunarEclipse] the eclipse
+    # @param observer [Astronoby::Observer] the observer
+    def initialize(eclipse:, observer:)
+      @eclipse = eclipse
+      @observer = observer
+
+      nodes = interpolation_nodes(eclipse)
+      @node_times = nodes.map { |node| node[:jd] }
+      @node_declinations = nodes.map { |node| node[:declination] }
+      @node_distances = nodes.map { |node| node[:distance] }
+      @node_right_ascensions = unwrapped(
+        nodes.map { |node| node[:right_ascension] }
+      )
+
+      @window_start = eclipse.penumbral.starting_instant.tt
+      @window_end = eclipse.penumbral.ending_instant.tt
+
+      @anchor = eclipse.instant.tt
+      @anchor_sidereal_hours = eclipse.instant.gast
+
+      @sin_latitude = observer.latitude.sin
+      @cos_latitude = observer.latitude.cos
+      @longitude = observer.longitude.radians
+
+      position = observer.geocentric_position
+      @observer_x = position.x.m
+      @observer_y = position.y.m
+      @observer_z = position.z.m
+
+      @memo = {}
+      freeze
+    end
+
+    # @return [Boolean] true if any part of the eclipse happens with the Moon
+    #   above the horizon
+    def visible?
+      !observable_windows.empty?
+    end
+
+    # @return [Boolean] true if the Moon is above the horizon from the first to
+    #   the last penumbral contact
+    def entirely_visible?
+      observable_windows.one? &&
+        above_horizon?(@window_start) &&
+        above_horizon?(@window_end)
+    end
+
+    # @return [Symbol] +NOT_VISIBLE+, +ENTIRELY_VISIBLE+,
+    #   +BEGINS_BEFORE_MOONRISE+, +ENDS_AFTER_MOONSET+ or +PARTIALLY_VISIBLE+
+    def circumstance
+      return NOT_VISIBLE unless visible?
+      return ENTIRELY_VISIBLE if entirely_visible?
+      return PARTIALLY_VISIBLE unless observable_windows.one?
+
+      if above_horizon?(@window_end)
+        BEGINS_BEFORE_MOONRISE
+      elsif above_horizon?(@window_start)
+        ENDS_AFTER_MOONSET
+      else
+        PARTIALLY_VISIBLE
+      end
+    end
+
+    # @param phase [Symbol] +LunarEclipse::PENUMBRAL+,
+    #   +LunarEclipse::PARTIAL+ or +LunarEclipse::TOTAL+
+    # @return [Symbol, nil] +ENTIRELY_VISIBLE+, +PARTIALLY_VISIBLE+ or
+    #   +NOT_VISIBLE+, and nil when the eclipse has no such phase
+    # @raise [Astronoby::UnsupportedEventError] if the phase is not a phase of
+    #   a lunar eclipse
+    def coverage(phase)
+      unless PHASES.include?(phase)
+        raise UnsupportedEventError,
+          "phase must be one of #{PHASES.join(", ")}, got #{phase.inspect}"
+      end
+
+      eclipse_phase = @eclipse.public_send(phase)
+      return nil if eclipse_phase.nil?
+
+      starting = eclipse_phase.starting_instant.tt
+      ending = eclipse_phase.ending_instant.tt
+      crossed_within = horizon_crossing_times.any? do |time|
+        time > starting && time < ending
+      end
+      starts_up = above_horizon?(starting)
+      ends_up = above_horizon?(ending)
+
+      if crossed_within
+        PARTIALLY_VISIBLE
+      elsif starts_up && ends_up
+        ENTIRELY_VISIBLE
+      elsif starts_up || ends_up
+        PARTIALLY_VISIBLE
+      else
+        NOT_VISIBLE
+      end
+    end
+
+    # @param instant [Astronoby::Instant] an instant of the eclipse
+    # @return [Boolean] true if the Moon is above the horizon then
+    # @raise [ArgumentError] if the instant is outside the eclipse
+    def above_horizon_at?(instant)
+      above_horizon?(within_eclipse(instant))
+    end
+
+    # @return [Array<Astronoby::Instant>] the instants of the eclipse at which
+    #   the Moon rises or sets, in time order
+    def horizon_crossings
+      @memo[:horizon_crossings] ||= horizon_crossing_times
+        .map { |time| Instant.from_terrestrial_time(time) }
+        .freeze
+    end
+
+    # @return [Array<Range<Astronoby::Instant>>] the observable stretches, in
+    #   time order
+    def observable_windows
+      @memo[:observable_windows] ||= begin
+        boundaries = [@window_start, *horizon_crossing_times, @window_end]
+        boundaries.each_cons(2).filter_map do |starting, ending|
+          next unless above_horizon?((starting + ending) / 2.0)
+
+          Range.new(
+            Instant.from_terrestrial_time(starting),
+            Instant.from_terrestrial_time(ending)
+          )
+        end.freeze
+      end
+    end
+
+    private
+
+    def interpolation_nodes(eclipse)
+      phases = [eclipse.partial, eclipse.total].compact
+      contacts = [
+        [eclipse.penumbral.starting_instant, eclipse.penumbral.starting_geometry],
+        [eclipse.penumbral.ending_instant, eclipse.penumbral.ending_geometry],
+        [eclipse.instant, eclipse.geometry],
+        *phases.flat_map do |phase|
+          [
+            [phase.starting_instant, phase.starting_geometry],
+            [phase.ending_instant, phase.ending_geometry]
+          ]
+        end
+      ]
+
+      contacts.sort_by { |instant, _| instant.tt }.map do |instant, geometry|
+        coordinates = geometry.moon_coordinates
+
+        {
+          jd: instant.tt,
+          right_ascension: coordinates.right_ascension.radians,
+          declination: coordinates.declination.radians,
+          distance: geometry.moon_distance.m
+        }
+      end
+    end
+
+    def unwrapped(right_ascensions)
+      right_ascensions.each_with_object([]) do |value, unwrapped|
+        previous = unwrapped.last
+        if previous.nil?
+          unwrapped << value
+        else
+          turns = ((value - previous) / Constants::RADIANS_PER_CIRCLE).round
+          unwrapped << value - turns * Constants::RADIANS_PER_CIRCLE
+        end
+      end
+    end
+
+    def above_horizon?(time)
+      clearance(time).positive?
+    end
+
+    def clearance(time)
+      right_ascension, declination, distance = place(time)
+      horizon = Horizon::REFRACTION_ANGLE.radians -
+        Horizon.moon_semidiameter_radians(distance)
+
+      altitude_of(right_ascension, declination, distance, time) - horizon
+    end
+
+    def altitude_of(right_ascension, declination, distance, time)
+      sidereal = sidereal_radians_at(time)
+      cos_declination = Math.cos(declination)
+      moon_x = distance * cos_declination * Math.cos(right_ascension)
+      moon_y = distance * cos_declination * Math.sin(right_ascension)
+      moon_z = distance * Math.sin(declination)
+
+      cos_sidereal = Math.cos(sidereal)
+      sin_sidereal = Math.sin(sidereal)
+      observer_x = @observer_x * cos_sidereal - @observer_y * sin_sidereal
+      observer_y = @observer_x * sin_sidereal + @observer_y * cos_sidereal
+
+      x = moon_x - observer_x
+      y = moon_y - observer_y
+      z = moon_z - @observer_z
+
+      local_sidereal = sidereal + @longitude
+      up_x = @cos_latitude * Math.cos(local_sidereal)
+      up_y = @cos_latitude * Math.sin(local_sidereal)
+      up_z = @sin_latitude
+
+      cosine = (x * up_x + y * up_y + z * up_z) /
+        Math.sqrt(x * x + y * y + z * z)
+
+      Math.asin(cosine.clamp(-1.0, 1.0))
+    end
+
+    def sidereal_radians_at(time)
+      sidereal_hours = @anchor_sidereal_hours +
+        (time - @anchor) *
+          Constants::HOURS_PER_DAY *
+          GreenwichMeanSiderealTime::UT_TO_SIDEREAL_RATIO
+
+      sidereal_hours * RADIANS_PER_HOUR
+    end
+
+    def place(time)
+      first, second, third = interpolation_window(time)
+      x0 = @node_times[first]
+      x1 = @node_times[second]
+      x2 = @node_times[third]
+      w0 = (time - x1) * (time - x2) / ((x0 - x1) * (x0 - x2))
+      w1 = (time - x0) * (time - x2) / ((x1 - x0) * (x1 - x2))
+      w2 = (time - x0) * (time - x1) / ((x2 - x0) * (x2 - x1))
+
+      [
+        @node_right_ascensions,
+        @node_declinations,
+        @node_distances
+      ].map do |values|
+        values[first] * w0 + values[second] * w1 + values[third] * w2
+      end
+    end
+
+    def interpolation_window(time)
+      nearest = @node_times
+        .each_index
+        .min_by { |index| (@node_times[index] - time).abs }
+      middle = nearest.clamp(1, @node_times.length - 2)
+
+      [middle - 1, middle, middle + 1]
+    end
+
+    def horizon_crossing_times
+      @memo[:horizon_crossing_times] ||= RootFinder
+        .new(
+          value_at: ->(time) { clearance(time) },
+          period: SAMPLING_INTERVAL_IN_DAYS,
+          samples_per_period: 1
+        )
+        .roots(@window_start, @window_end)
+        .freeze
+    end
+
+    def within_eclipse(instant)
+      time = instant.tt
+      unless time.between?(@window_start, @window_end)
+        raise ArgumentError,
+          "the instant must be between the first and last penumbral contact"
+      end
+
+      time
+    end
+  end
+end

data/lib/astronoby/events/opposition.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Opposition
+    # @return [Astronoby::Instant] when the opposition occurs
+    attr_reader :instant
+
+    # @return [Astronoby::Body] the body in opposition with the Sun
+    attr_reader :body
+
+    # @param instant [Astronoby::Instant] when the opposition occurs
+    # @param body [Astronoby::Body] the body in opposition with the Sun
+    def initialize(instant:, body:)
+      @instant = instant
+      @body = body
+      freeze
+    end
+  end
+end

data/lib/astronoby/events/rise_transit_set_calculator.rb

@@ -18,9 +18,9 @@ module Astronoby
     TAU = Math::PI * 2
     SAMPLE_THRESHOLD = 0.8
     REFINEMENT_ITERATIONS = 3
-    MIN_TIME_ADJUSTMENT = Constants::MICROSECOND_IN_DAYS
-    STANDARD_REFRACTION_ANGLE = -Angle.from_dms(0, 34, 0)
-    SUN_REFRACTION_ANGLE = -Angle.from_dms(0, 50, 0)
+    CONVERGENCE_TOLERANCE_IN_DAYS = 0.5 / Constants::SECONDS_PER_DAY
+    STANDARD_REFRACTION_ANGLE = Horizon::REFRACTION_ANGLE
+    SUN_REFRACTION_ANGLE = Horizon::SUN_ANGLE
     EVENT_TYPES = [:rising, :transit, :setting].freeze
 
     # @param body [Astronoby::SolarSystemBody, Astronoby::DeepSkyObject]
@@ -260,14 +260,17 @@ module Astronoby
           .each_with_index
           .map do |angle, i|
             ratio = angle.radians / hour_angle_rates[i]
-            time_adjustment = (ratio.nan? || ratio.infinite?) ? 0 : ratio
-            [time_adjustment, MIN_TIME_ADJUSTMENT].max
+            (ratio.nan? || ratio.infinite?) ? 0.0 : ratio
           end
 
         # Apply time adjustments
         new_instants = new_instants.each_with_index.map do |instant, i|
           Instant.from_terrestrial_time(instant.tt + time_adjustments[i])
         end
+
+        break if time_adjustments.all? do |adjustment|
+          adjustment.abs < CONVERGENCE_TOLERANCE_IN_DAYS
+        end
       end
 
       new_instants.map { _1.to_time.round }
@@ -356,14 +359,7 @@ module Astronoby
     end
 
     def horizon_angle(distance)
-      if @body == Astronoby::Sun
-        SUN_REFRACTION_ANGLE
-      elsif @body == Astronoby::Moon
-        STANDARD_REFRACTION_ANGLE -
-          Angle.from_radians(Moon::EQUATORIAL_RADIUS.m / distance.m)
-      else
-        STANDARD_REFRACTION_ANGLE
-      end
+      Horizon.angle_for(body: @body, distance: distance)
     end
 
     def reset_state

data/lib/astronoby/events/rise_transit_set_event.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Holds the rising, transit, and setting times for a single day.
   class RiseTransitSetEvent
-    attr_reader :rising_time, :transit_time, :setting_time
+    # @return [Time, nil] the rising time
+    attr_reader :rising_time
 
+    # @return [Time, nil] the transit (culmination) time
+    attr_reader :transit_time
+
+    # @return [Time, nil] the setting time
+    attr_reader :setting_time
+
+    # @param rising [Time, nil] the rising time
+    # @param transit [Time, nil] the transit time
+    # @param setting [Time, nil] the setting time
     def initialize(rising, transit, setting)
       @rising_time = rising
       @transit_time = transit

data/lib/astronoby/events/rise_transit_set_events.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Holds arrays of rising, transit, and setting times over a time range.
   class RiseTransitSetEvents
-    attr_reader :rising_times, :transit_times, :setting_times
+    # @return [Array<Time>] rising times
+    attr_reader :rising_times
 
+    # @return [Array<Time>] transit (culmination) times
+    attr_reader :transit_times
+
+    # @return [Array<Time>] setting times
+    attr_reader :setting_times
+
+    # @param risings [Array<Time>] rising times
+    # @param transits [Array<Time>] transit times
+    # @param settings [Array<Time>] setting times
     def initialize(risings, transits, settings)
       @rising_times = risings
       @transit_times = transits

data/lib/astronoby/events/twilight_calculator.rb

@@ -22,13 +22,22 @@ module Astronoby
     def initialize(observer:, ephem:)
       @observer = observer
       @ephem = ephem
+      @crossing_calculator = AltitudeCrossingCalculator.new(
+        body: Sun,
+        observer: observer,
+        ephem: ephem
+      )
     end
 
     def event_on(date, utc_offset: 0)
       start_time = Time
         .new(date.year, date.month, date.day, 0, 0, 0, utc_offset)
-      end_time = Time
-        .new(date.year, date.month, date.day, 23, 59, 59, utc_offset)
+      following = date.next_day
+      end_time = Time.new(
+        following.year, following.month, following.day,
+        0, 0, 0,
+        utc_offset
+      ) - 1e-6
       events = events_between(start_time, end_time)
 
       TwilightEvent.new(
@@ -48,73 +57,26 @@ module Astronoby
     end
 
     def events_between(start_time, end_time)
-      rts_events = Astronoby::RiseTransitSetCalculator.new(
-        body: Sun,
-        observer: @observer,
-        ephem: @ephem
-      ).events_between(start_time, end_time)
-
-      equatorial_by_time = {}
-
-      (rts_events.rising_times + rts_events.setting_times)
-        .compact
-        .each do |event_time|
-          rounded_time = event_time.round
-          next if equatorial_by_time.key?(rounded_time)
-
-          instant = Instant.from_time(rounded_time)
-          sun_at_time = Sun.new(instant: instant, ephem: @ephem)
-          equatorial_by_time[rounded_time] = sun_at_time.apparent.equatorial
-        end
-
-      morning_civil = []
-      evening_civil = []
-      morning_nautical = []
-      evening_nautical = []
-      morning_astronomical = []
-      evening_astronomical = []
-
-      arrays_by_period = {
-        MORNING => {
-          CIVIL => morning_civil,
-          NAUTICAL => morning_nautical,
-          ASTRONOMICAL => morning_astronomical
-        },
-        EVENING => {
-          CIVIL => evening_civil,
-          NAUTICAL => evening_nautical,
-          ASTRONOMICAL => evening_astronomical
-        }
-      }
-
-      [
-        [rts_events.rising_times, MORNING],
-        [rts_events.setting_times, EVENING]
-      ].each do |times, period|
-        times.each do |event_time|
-          next unless event_time
-
-          equatorial_coordinates = equatorial_by_time[event_time.round]
-          TWILIGHT_ANGLES.each do |twilight, angle|
-            arrays_by_period[period][twilight] << compute_twilight_time_from(
-              period,
-              angle,
-              event_time,
-              equatorial_coordinates
-            )
-          end
-        end
+      crossings = @crossing_calculator.multiple_crossings_between(
+        start_time,
+        end_time,
+        altitudes: TWILIGHT_ANGLES.values.map { |angle| altitude_for(angle) }
+      )
+      times = TWILIGHT_ANGLES.keys.zip(crossings).to_h do |twilight, found|
+        [twilight, [:rising, :setting].map do |direction|
+          found
+            .select { |crossing| crossing.direction == direction }
+            .map { |crossing| crossing.instant.to_time.round }
+        end]
       end
 
-      within_range = ->(time) { time && time >= start_time && time <= end_time }
-
       TwilightEvents.new(
-        morning_civil.select(&within_range),
-        evening_civil.select(&within_range),
-        morning_nautical.select(&within_range),
-        evening_nautical.select(&within_range),
-        morning_astronomical.select(&within_range),
-        evening_astronomical.select(&within_range)
+        times[CIVIL][0],
+        times[CIVIL][1],
+        times[NAUTICAL][0],
+        times[NAUTICAL][1],
+        times[ASTRONOMICAL][0],
+        times[ASTRONOMICAL][1]
       )
     end
 
@@ -130,92 +92,20 @@ module Astronoby
           "period_of_the_day, got #{period_of_the_day}"
       end
 
-      observation_events = get_observation_events(date, utc_offset: utc_offset)
-      midday_instant = create_midday_instant(date, utc_offset: utc_offset)
-      sun_at_midday = Sun.new(instant: midday_instant, ephem: @ephem)
-      equatorial_coordinates = sun_at_midday.apparent.equatorial
-
-      compute_twilight_time(
-        period_of_the_day,
-        zenith_angle,
-        observation_events,
-        equatorial_coordinates
+      crossing = @crossing_calculator.crossing_on(
+        date,
+        altitude: altitude_for(zenith_angle),
+        direction: (period_of_the_day == MORNING) ? :rising : :setting,
+        utc_offset: utc_offset
       )
-    end
-
-    private
-
-    def create_midday_instant(date, utc_offset: 0)
-      time = Time.new(date.year, date.month, date.day, 12, 0, 0, utc_offset)
-      Instant.from_time(time)
-    end
 
-    def get_observation_events(date, utc_offset: 0)
-      Astronoby::RiseTransitSetCalculator.new(
-        body: Sun,
-        observer: @observer,
-        ephem: @ephem
-      ).event_on(date, utc_offset: utc_offset)
+      crossing&.instant&.to_time&.round
     end
 
-    def compute_twilight_time(
-      period_of_the_day,
-      zenith_angle,
-      observation_events,
-      equatorial_coordinates
-    )
-      period_time = if period_of_the_day == MORNING
-        observation_events.rising_time
-      else
-        observation_events.setting_time
-      end
-
-      compute_twilight_time_from(
-        period_of_the_day,
-        zenith_angle,
-        period_time,
-        equatorial_coordinates
-      )
-    end
-
-    def compute_twilight_time_from(
-      period_of_the_day,
-      zenith_angle,
-      period_time,
-      equatorial_coordinates
-    )
-      # If the sun doesn't rise or set on this day, we can't calculate twilight
-      return nil unless period_time
-
-      hour_angle_at_period = equatorial_coordinates
-        .compute_hour_angle(time: period_time, longitude: @observer.longitude)
-
-      term1 = zenith_angle.cos -
-        @observer.latitude.sin * equatorial_coordinates.declination.sin
-      term2 = @observer.latitude.cos * equatorial_coordinates.declination.cos
-      hour_angle_ratio_at_twilight = term1 / term2
-
-      # Check if twilight occurs at this location and date
-      return nil unless hour_angle_ratio_at_twilight.between?(-1, 1)
-
-      hour_angle_at_twilight = Angle.acos(hour_angle_ratio_at_twilight)
-      time_sign = -1
-
-      if period_of_the_day == MORNING
-        hour_angle_at_twilight = Angle.from_degrees(
-          Constants::DEGREES_PER_CIRCLE - hour_angle_at_twilight.degrees
-        )
-        time_sign = 1
-      end
-
-      twilight_in_hours =
-        time_sign * (hour_angle_at_twilight - hour_angle_at_period).hours *
-        GreenwichMeanSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
-      twilight_in_seconds = time_sign *
-        twilight_in_hours *
-        Constants::SECONDS_PER_HOUR
+    private
 
-      (period_time + twilight_in_seconds).round
+    def altitude_for(zenith_angle)
+      Angle.from_degrees(90) - zenith_angle
     end
   end
 end

data/lib/astronoby/events/twilight_event.rb

@@ -1,14 +1,32 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Holds twilight times (civil, nautical, astronomical) for a single day.
   class TwilightEvent
-    attr_reader :morning_civil_twilight_time,
-      :evening_civil_twilight_time,
-      :morning_nautical_twilight_time,
-      :evening_nautical_twilight_time,
-      :morning_astronomical_twilight_time,
-      :evening_astronomical_twilight_time
+    # @return [Time, nil] morning civil twilight time
+    attr_reader :morning_civil_twilight_time
 
+    # @return [Time, nil] evening civil twilight time
+    attr_reader :evening_civil_twilight_time
+
+    # @return [Time, nil] morning nautical twilight time
+    attr_reader :morning_nautical_twilight_time
+
+    # @return [Time, nil] evening nautical twilight time
+    attr_reader :evening_nautical_twilight_time
+
+    # @return [Time, nil] morning astronomical twilight time
+    attr_reader :morning_astronomical_twilight_time
+
+    # @return [Time, nil] evening astronomical twilight time
+    attr_reader :evening_astronomical_twilight_time
+
+    # @param morning_civil_twilight_time [Time, nil]
+    # @param evening_civil_twilight_time [Time, nil]
+    # @param morning_nautical_twilight_time [Time, nil]
+    # @param evening_nautical_twilight_time [Time, nil]
+    # @param morning_astronomical_twilight_time [Time, nil]
+    # @param evening_astronomical_twilight_time [Time, nil]
     def initialize(
       morning_civil_twilight_time: nil,
       evening_civil_twilight_time: nil,