astronoby 0.10.0 → 0.11.0

data/lib/astronoby/events/altitude_crossing_calculator.rb

@@ -0,0 +1,511 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Finds when a body reaches a given altitude above the observer's horizon.
+  #
+  # The window is split at the body's culminations, since between a lower and
+  # the next upper culmination the altitude only goes one way. A segment whose
+  # ends lie on opposite sides of the target holds exactly one crossing, which
+  # is located on the real altitude. A segment where the target is within
+  # {GRAZING_MARGIN} of an end could hold two crossings or none, so it is
+  # sampled and bisected instead.
+  #
+  # The calculator holds no state between calls: every call searches with its
+  # own cache of evaluated positions, so one instance can be shared by threads.
+  class AltitudeCrossingCalculator
+    REFERENCES = [:center, :upper_limb, :lower_limb].freeze
+    DIRECTIONS = [:rising, :setting].freeze
+
+    TAU = Math::PI * 2
+    SIDEREAL_RATE = TAU * 1.00273790935
+
+    # A culmination is at most about 0.52 days after the previous one (the
+    # Moon's), so this much on each side of the window brackets its ends.
+    CULMINATION_PADDING_IN_DAYS = 0.6
+
+    ALTITUDE_TOLERANCE = Angle.from_degrees(1e-5).radians
+    # A Float Julian Date resolves about 47 µs, or 3.4e-9 rad of hour angle,
+    # so a tighter tolerance could never be met.
+    HOUR_ANGLE_TOLERANCE = 1e-8
+    # The ends of a segment only have to be close enough to the culminations
+    # for the altitude there to be within GRAZING_MARGIN of the extremum, which
+    # a hundred microradians of hour angle is, except for a body passing within
+    # a few thousandths of a degree of the zenith.
+    SEGMENT_HOUR_ANGLE_TOLERANCE = 1e-4
+    GRAZING_MARGIN = Angle.from_degrees(0.05).radians
+    # A Newton step from an altitude this close to the target lands within
+    # {ALTITUDE_TOLERANCE} of it, for a slope that is off by up to 2%, so the
+    # step is returned without evaluating the body there.
+    NEWTON_ACCEPT = Angle.from_degrees(5e-4).radians
+    MAX_ITERATIONS = 30
+
+    FALLBACK_SAMPLES_PER_DAY = 288
+    DIRECTION_PROBE_IN_DAYS = 60.0 / Constants::SECONDS_PER_DAY
+    DUPLICATE_THRESHOLD_IN_DAYS = 1e-6
+
+    Sample = Struct.new(:hour_angle, :declination, :altitude)
+    Culmination = Struct.new(:kind, :tt)
+    Crossing = Struct.new(:tt, :direction, :grazing)
+
+    # @param body [Class, Object] celestial body to track
+    # @param observer [Astronoby::Observer] observer location
+    # @param ephem [::Ephem::SPK, nil] ephemeris data source
+    # @param refraction [Boolean] whether to apply atmospheric refraction to
+    #   the altitude, false by default as in the twilight convention
+    # @param reference [Symbol] the point of the body that reaches the target:
+    #   +:center+, +:upper_limb+ or +:lower_limb+, the limbs using the body's
+    #   true semi-diameter
+    def initialize(
+      body:,
+      observer:,
+      ephem: nil,
+      refraction: false,
+      reference: :center
+    )
+      unless REFERENCES.include?(reference)
+        raise IncompatibleArgumentsError,
+          "Only #{REFERENCES.join(", ")} are allowed as reference, " \
+          "got #{reference}"
+      end
+
+      unless body.respond_to?(:at)
+        raise IncompatibleArgumentsError,
+          "The body must respond to #at(instant, ephem:), got #{body}"
+      end
+
+      if reference != :center && !(body.is_a?(Class) && body <= SolarSystemBody)
+        raise IncompatibleArgumentsError,
+          "A limb reference needs a body with a known size, got #{body}"
+      end
+
+      @body = body
+      @observer = observer
+      @ephem = ephem
+      @refraction = refraction
+      @reference = reference
+    end
+
+    # @param start_time [Time] start of the window
+    # @param end_time [Time] end of the window
+    # @param altitude [Astronoby::Angle] the altitude to reach, positive or
+    #   negative
+    # @return [Array<Astronoby::AltitudeCrossing>] the crossings in the window,
+    #   sorted by time
+    def crossings_between(start_time, end_time, altitude:)
+      multiple_crossings_between(start_time, end_time, altitudes: [altitude])
+        .first
+    end
+
+    # Same as {#crossings_between} for several altitudes at once, sharing the
+    # culminations and the evaluated positions between them.
+    #
+    # @param start_time [Time] start of the window
+    # @param end_time [Time] end of the window
+    # @param altitudes [Array<Astronoby::Angle>] the altitudes to reach
+    # @return [Array<Array<Astronoby::AltitudeCrossing>>] the crossings of each
+    #   altitude, in the order of +altitudes+
+    def multiple_crossings_between(start_time, end_time, altitudes:)
+      search_between(start_time, end_time).crossings(altitudes)
+    end
+
+    # @param date [Date] the day
+    # @param altitude [Astronoby::Angle] the altitude to reach
+    # @param direction [Symbol] +:rising+ or +:setting+
+    # @param utc_offset [String, Integer] UTC offset of the day, e.g.
+    #   "+02:00"
+    # @return [Astronoby::AltitudeCrossing, nil] the first crossing of that
+    #   direction from midnight to the next midnight, if any
+    def crossing_on(date, altitude:, direction:, utc_offset: 0)
+      unless DIRECTIONS.include?(direction)
+        raise IncompatibleArgumentsError,
+          "Only #{DIRECTIONS.join(" or ")} are allowed as direction, " \
+          "got #{direction}"
+      end
+
+      start_time = Time.new(date.year, date.month, date.day, 0, 0, 0, utc_offset)
+      following = date.next_day
+      end_time = Time.new(
+        following.year, following.month, following.day, 0, 0, 0, utc_offset
+      )
+
+      crossings_between(start_time, end_time, altitude: altitude)
+        .find do |crossing|
+          crossing.direction == direction &&
+            crossing.instant.to_time < end_time
+        end
+    end
+
+    # @param start_time [Time] start of the window
+    # @param end_time [Time] end of the window
+    # @return [Array<Astronoby::AltitudeExtreme>] the upper and lower
+    #   culminations in the window, sorted by time, with the altitude of the
+    #   reference point at each
+    def extremes_between(start_time, end_time)
+      search_between(start_time, end_time).extremes
+    end
+
+    private
+
+    def search_between(start_time, end_time)
+      if end_time < start_time
+        raise IncompatibleArgumentsError,
+          "The end of the window must not be before its start"
+      end
+
+      Search.new(
+        body: @body,
+        observer: @observer,
+        ephem: @ephem,
+        refraction: @refraction,
+        reference: @reference,
+        start_tt: Instant.from_time(start_time).tt.to_f,
+        end_tt: Instant.from_time(end_time).tt.to_f
+      )
+    end
+
+    class Search
+      def initialize(
+        body:,
+        observer:,
+        ephem:,
+        refraction:,
+        reference:,
+        start_tt:,
+        end_tt:
+      )
+        @body = body
+        @observer = observer
+        @ephem = ephem
+        @refraction = refraction
+        @reference = reference
+        @start_tt = start_tt
+        @end_tt = end_tt
+        @samples = {}
+      end
+
+      def crossings(altitudes)
+        overlapping = segments
+
+        altitudes.map do |altitude|
+          target = altitude.radians
+
+          overlapping
+            .flat_map { |first, last| segment_crossings(first, last, target) }
+            .sort_by(&:tt)
+            .then { |crossings| remove_duplicates(crossings) }
+            .map { |crossing| build_crossing(crossing) }
+        end
+      end
+
+      def extremes
+        culminations(@start_tt, @end_tt, HOUR_ANGLE_TOLERANCE).map do |culmination|
+          AltitudeExtreme.new(
+            kind: culmination.kind,
+            instant: Instant.from_terrestrial_time(culmination.tt),
+            altitude: Angle.from_radians(altitude_at(culmination.tt))
+          )
+        end
+      end
+
+      private
+
+      def sample_at(tt)
+        @samples[tt] ||= begin
+          instant = Instant.from_terrestrial_time(tt)
+          body = @body.at(instant, ephem: @ephem)
+          equatorial = body.observed_by(@observer).equatorial
+          hour_angle = equatorial.compute_hour_angle(
+            time: instant.to_time,
+            longitude: @observer.longitude
+          )
+          declination = equatorial.declination
+
+          Sample.new(
+            hour_angle.radians,
+            declination.radians,
+            reference_altitude(body, declination, hour_angle)
+          )
+        end
+      end
+
+      def reference_altitude(body, declination, hour_angle)
+        latitude = @observer.latitude
+        sin_altitude = latitude.sin * declination.sin +
+          latitude.cos * declination.cos * hour_angle.cos
+        altitude = Angle.asin(sin_altitude.clamp(-1.0, 1.0))
+
+        if @refraction
+          altitude += Refraction.angle(
+            coordinates: Coordinates::Horizontal.new(
+              azimuth: Angle.zero,
+              altitude: altitude,
+              observer: @observer
+            )
+          )
+        end
+
+        altitude.radians + limb_offset(body)
+      end
+
+      def limb_offset(body)
+        case @reference
+        when :upper_limb then body.angular_diameter.radians / 2
+        when :lower_limb then -body.angular_diameter.radians / 2
+        else 0.0
+        end
+      end
+
+      def altitude_at(tt)
+        sample_at(tt).altitude
+      end
+
+      def hour_angle_at(tt)
+        sample_at(tt).hour_angle
+      end
+
+      def wrap(radians)
+        (radians + Math::PI) % TAU - Math::PI
+      end
+
+      def segments
+        culminations(
+          @start_tt - CULMINATION_PADDING_IN_DAYS,
+          @end_tt + CULMINATION_PADDING_IN_DAYS,
+          SEGMENT_HOUR_ANGLE_TOLERANCE
+        ).each_cons(2).select do |first, last|
+          last.tt >= @start_tt && first.tt <= @end_tt
+        end
+      end
+
+      def culminations(start_tt, end_tt, tolerance)
+        start_hour_angle = hour_angle_at(start_tt)
+        spacing = TAU / SIDEREAL_RATE
+
+        {
+          AltitudeExtreme::UPPER_CULMINATION => 0.0,
+          AltitudeExtreme::LOWER_CULMINATION => Math::PI
+        }.flat_map do |kind, hour_angle|
+          tt = start_tt +
+            ((hour_angle - start_hour_angle) % TAU) / SIDEREAL_RATE
+          previous = nil
+          found = []
+
+          while tt <= end_tt
+            tt = refine_culmination(tt, hour_angle, tolerance)
+            found << Culmination.new(kind, tt) if tt.between?(start_tt, end_tt)
+            # Step from the refined event: a sidereal day drifts from the
+            # Moon's by about an hour per day, which would add up over a
+            # window. Once two are known their spacing, shared by both kinds,
+            # is a closer step than a sidereal day, as it changes slowly from
+            # one day to the next.
+            spacing = tt - previous if previous
+            previous = tt
+            tt += spacing
+          end
+
+          found
+        end.sort_by(&:tt)
+      end
+
+      def refine_culmination(tt, hour_angle, tolerance)
+        rate = SIDEREAL_RATE
+        previous = nil
+
+        MAX_ITERATIONS.times do
+          residual = wrap(hour_angle_at(tt) - hour_angle)
+          return tt if residual.abs < tolerance
+
+          if previous
+            measured_rate =
+              wrap(residual - previous[:residual]) / (tt - previous[:tt])
+            rate = measured_rate if measured_rate.positive?
+          end
+
+          previous = {tt: tt, residual: residual}
+          tt -= residual / rate
+        end
+
+        tt
+      end
+
+      def segment_crossings(first, last, target)
+        low = [first.tt, @start_tt].max
+        high = [last.tt, @end_tt].min
+        return [] unless low < high
+
+        f_first = altitude_at(first.tt) - target
+        f_last = altitude_at(last.tt) - target
+
+        if [f_first.abs, f_last.abs].min <= GRAZING_MARGIN
+          return scan(low, high, target, grazing: true)
+        end
+
+        f_low = (low == first.tt) ? f_first : altitude_at(low) - target
+        f_high = (high == last.tt) ? f_last : altitude_at(high) - target
+        return [] if f_low.negative? == f_high.negative?
+
+        tt = solve(Segment.new(
+          first, sample_at(first.tt), last, sample_at(last.tt)
+        ), low, f_low, high, target)
+        return scan(low, high, target, grazing: false) unless tt
+
+        [Crossing.new(tt, f_low.negative? ? :rising : :setting, false)]
+      end
+
+      # Between two consecutive culminations the hour angle goes through
+      # exactly half a turn, and the declination moves from its value at one
+      # to its value at the other. That gives the rates of both over the
+      # segment, which a sidereal day and a fixed declination only approximate:
+      # the Sun's right ascension drifts by a degree per day and the Moon's by
+      # thirteen.
+      class Segment
+        attr_reader :hour_angle_rate, :declination_rate
+
+        def initialize(first, first_sample, last, last_sample)
+          @first = first
+          @first_sample = first_sample
+          span = last.tt - first.tt
+          consecutive = first.kind != last.kind && span.positive?
+
+          @hour_angle_rate = consecutive ? Math::PI / span : SIDEREAL_RATE
+          @declination_rate = if consecutive
+            (last_sample.declination - first_sample.declination) / span
+          else
+            0.0
+          end
+          @first_hour_angle =
+            (first.kind == AltitudeExtreme::UPPER_CULMINATION) ? 0.0 : Math::PI
+          @consecutive = consecutive
+        end
+
+        def consecutive? = @consecutive
+
+        def declination_at(tt)
+          @first_sample.declination + @declination_rate * (tt - @first.tt)
+        end
+
+        def time_at_hour_angle(hour_angle)
+          @first.tt + (hour_angle - @first_hour_angle) / @hour_angle_rate
+        end
+      end
+
+      def solve(segment, low, f_low, high, target)
+        x = initial_guess(segment, low, high, f_low, target)
+        previous = nil
+
+        MAX_ITERATIONS.times do
+          f_x = altitude_at(x) - target
+          return x if f_x.abs < ALTITUDE_TOLERANCE
+
+          if f_x.negative? == f_low.negative?
+            low = x
+            f_low = f_x
+          else
+            high = x
+          end
+
+          slope = if previous
+            (f_x - previous[:f]) / (x - previous[:tt])
+          else
+            analytic_slope(x, segment)
+          end
+          previous = {tt: x, f: f_x}
+
+          step = x - f_x / slope
+          within = step > low && step < high
+          return step if within && f_x.abs < NEWTON_ACCEPT && segment.consecutive?
+
+          x = within ? step : (low + high) / 2
+        end
+
+        nil
+      end
+
+      def initial_guess(segment, low, high, f_low, target)
+        guess = if segment.consecutive?
+          guess_from_segment(segment, f_low, target, low)
+        else
+          guess_from_sample(low, f_low, target)
+        end
+
+        (guess > low && guess < high) ? guess : (low + high) / 2
+      end
+
+      def guess_from_segment(segment, f_low, target, low)
+        # The declination at the crossing depends on when it happens, so the
+        # time is refined once from the first estimate.
+        tt = low
+        2.times do
+          declination = segment.declination_at(tt)
+          half_arc = half_arc_for(target, declination)
+          needed = f_low.negative? ? TAU - half_arc : half_arc
+          tt = segment.time_at_hour_angle(needed)
+        end
+        tt
+      end
+
+      def guess_from_sample(low, f_low, target)
+        sample = sample_at(low)
+        half_arc = half_arc_for(target, sample.declination)
+        needed = f_low.negative? ? TAU - half_arc : half_arc
+
+        low + ((needed - sample.hour_angle) % TAU) / SIDEREAL_RATE
+      end
+
+      def half_arc_for(target, declination)
+        latitude = @observer.latitude
+        ratio = (Math.sin(target) - latitude.sin * Math.sin(declination)) /
+          (latitude.cos * Math.cos(declination))
+
+        Math.acos(ratio.clamp(-1.0, 1.0))
+      end
+
+      def analytic_slope(tt, segment)
+        sample = sample_at(tt)
+        latitude = @observer.latitude
+        declination = sample.declination
+        cos_hour_angle = Math.cos(sample.hour_angle)
+
+        rate_of_sine =
+          -latitude.cos * Math.cos(declination) * Math.sin(sample.hour_angle) *
+          segment.hour_angle_rate +
+          (latitude.sin * Math.cos(declination) -
+            latitude.cos * Math.sin(declination) * cos_hour_angle) *
+          segment.declination_rate
+
+        rate_of_sine / Math.cos(sample.altitude)
+      end
+
+      def scan(first_tt, last_tt, target, grazing:)
+        finder = RootFinder.new(
+          value_at: ->(tt) { altitude_at(tt) - target },
+          period: 1.0,
+          samples_per_period: FALLBACK_SAMPLES_PER_DAY
+        )
+
+        finder.roots(first_tt, last_tt).map do |tt|
+          rising = altitude_at(tt + DIRECTION_PROBE_IN_DAYS) >
+            altitude_at(tt - DIRECTION_PROBE_IN_DAYS)
+          Crossing.new(tt, rising ? :rising : :setting, grazing)
+        end
+      end
+
+      def remove_duplicates(crossings)
+        crossings.each_with_object([]) do |crossing, kept|
+          duplicate = kept.last &&
+            (crossing.tt - kept.last.tt) < DUPLICATE_THRESHOLD_IN_DAYS
+          kept << crossing unless duplicate
+        end
+      end
+
+      def build_crossing(crossing)
+        AltitudeCrossing.new(
+          instant: Instant.from_terrestrial_time(crossing.tt),
+          direction: crossing.direction,
+          grazing: crossing.grazing
+        )
+      end
+    end
+    private_constant :Search
+  end
+end

data/lib/astronoby/events/altitude_extreme.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # A culmination of a body, when it crosses the observer's meridian above or
+  # below the pole.
+  class AltitudeExtreme
+    KINDS = [
+      UPPER_CULMINATION = :upper_culmination,
+      LOWER_CULMINATION = :lower_culmination
+    ].freeze
+
+    # @return [Symbol] +:upper_culmination+ (highest altitude) or
+    #   +:lower_culmination+ (lowest altitude)
+    attr_reader :kind
+
+    # @return [Astronoby::Instant] when the body crosses the meridian
+    attr_reader :instant
+
+    # @return [Astronoby::Angle] the altitude at that instant
+    attr_reader :altitude
+
+    # @param kind [Symbol] +:upper_culmination+ or +:lower_culmination+
+    # @param instant [Astronoby::Instant] when the body crosses the meridian
+    # @param altitude [Astronoby::Angle] the altitude at that instant
+    def initialize(kind:, instant:, altitude:)
+      @kind = kind
+      @instant = instant
+      @altitude = altitude
+    end
+  end
+end

data/lib/astronoby/events/lunar_eclipse.rb

@@ -14,73 +14,79 @@ module Astronoby
     # @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
+    alias_method :greatest_eclipse_instant, :instant
 
     # @return [Symbol] +PENUMBRAL+, +PARTIAL+ or +TOTAL+
     attr_reader :kind
 
-    # @return [Float] fraction of the Moon's diameter immersed in the umbra at
-    #   greatest eclipse (negative when the Moon misses the umbra)
-    attr_reader :umbral_magnitude
-
-    # @return [Float] fraction of the Moon's diameter immersed in the penumbra
-    #   at greatest eclipse
-    attr_reader :penumbral_magnitude
-
-    # @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
-    attr_reader :gamma
+    # @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::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.
-    attr_reader :shadow_axis_distance
-
-    # @return [Astronoby::EclipsePhase] the penumbral phase (always present)
+    # @return [Astronoby::LunarEclipsePhase] the penumbral phase (always present)
     attr_reader :penumbral
 
-    # @return [Astronoby::EclipsePhase, nil] the partial phase, present for
+    # @return [Astronoby::LunarEclipsePhase, nil] the partial phase, present for
     #   partial and total eclipses
     attr_reader :partial
 
-    # @return [Astronoby::EclipsePhase, nil] the total phase (totality),
+    # @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 umbral_magnitude [Float] umbral magnitude at greatest eclipse
-    # @param penumbral_magnitude [Float] penumbral magnitude at greatest eclipse
-    # @param gamma [Float] least distance from the shadow axis, in Earth radii
-    # @param shadow_axis_distance [Astronoby::Distance] least distance from the
-    #   shadow axis
-    # @param penumbral [Astronoby::EclipsePhase] the penumbral phase
-    # @param partial [Astronoby::EclipsePhase, nil] the partial phase
-    # @param total [Astronoby::EclipsePhase, nil] the total phase
+    # @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:,
-      umbral_magnitude:,
-      penumbral_magnitude:,
-      gamma:,
-      shadow_axis_distance:,
+      geometry:,
       penumbral:,
       partial: nil,
       total: nil
     )
       @instant = instant
       @kind = kind
-      @umbral_magnitude = umbral_magnitude
-      @penumbral_magnitude = penumbral_magnitude
-      @gamma = gamma
-      @shadow_axis_distance = shadow_axis_distance
+      @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
@@ -95,5 +101,11 @@ module Astronoby
     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