astronoby 0.9.0 → 0.10.0

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,99 @@
+# 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
+
+    # @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::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)
+    attr_reader :penumbral
+
+    # @return [Astronoby::EclipsePhase, nil] the partial phase, present for
+    #   partial and total eclipses
+    attr_reader :partial
+
+    # @return [Astronoby::EclipsePhase, 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
+    def initialize(
+      instant:,
+      kind:,
+      umbral_magnitude:,
+      penumbral_magnitude:,
+      gamma:,
+      shadow_axis_distance:,
+      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
+      @penumbral = penumbral
+      @partial = partial
+      @total = total
+      freeze
+    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
+  end
+end

data/lib/astronoby/events/lunar_eclipse_calculator.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes lunar eclipses over a time range.
+  #
+  # A lunar eclipse is a geocentric event, identical for every observer who can
+  # see the Moon, so no observer is involved. The geometry is built from the
+  # apparent geocentric positions of the Sun and Moon: this matches the standard
+  # reduction used by IMCCE, validated against IMCCE (Opale, INPOP19A) where the
+  # eclipse kind, greatest eclipse, magnitudes, and contact times all agree to
+  # within a second or two.
+  #
+  # Candidate full moons are seeded analytically from Events::MoonPhases, then
+  # refined against the ephemeris: full moons far from a node are skipped, the
+  # greatest eclipse is the least distance of the Moon's centre from the shadow
+  # axis, and each contact is found by bisecting between greatest eclipse (inside
+  # the shadow) and the edge of the search window (outside it).
+  #
+  # Source:
+  #  Title: Explanatory Supplement to the Astronomical Almanac
+  #  Authors: Sean E. Urban and P. Kenneth Seidelmann
+  #  Chapter: 11 - Eclipses of the Sun and Moon
+  class LunarEclipseCalculator
+    # Atmospheric enlargement of Earth's shadow (Danjon-style): Earth's radius is
+    # enlarged before the shadow cones are built, which propagates into both the
+    # umbra and the penumbra. The 1/99 factor is calibrated against IMCCE (which
+    # uses the same INPOP19A ephemeris): it reproduces IMCCE's umbra and penumbra
+    # angular radii to about 0.1 arcsecond across the 2023-2025 eclipses.
+    SHADOW_ENLARGEMENT = 1.0 + 1.0 / 99
+
+    SUN_RADIUS_KM = Sun::EQUATORIAL_RADIUS.km
+    MOON_RADIUS_KM = Moon::EQUATORIAL_RADIUS.km
+    EARTH_RADIUS_KM =
+      Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS / 1000.0
+
+    # Largest distance of the Moon's centre from the shadow axis, in Earth radii,
+    # at which any (penumbral) eclipse is still possible is about 1.57. Full moons
+    # whose seed already exceeds this margin cannot be eclipses and skip the
+    # minimum search entirely.
+    MAX_ECLIPSE_GAMMA = 1.8
+
+    # Half-window, in days, for the local greatest-eclipse search around a full
+    # moon. A lunar eclipse occurs within minutes of full moon.
+    GREATEST_HALF_WINDOW = 0.25
+
+    # Half-window, in days, for the contact search around greatest eclipse. Wide
+    # enough to bracket the longest penumbral phase (about 3 hours each side).
+    CONTACT_HALF_WINDOW = 0.21
+
+    SEARCH_SAMPLES = 48
+
+    # Bisection tolerance, in days, for a contact time. ~1e-7 day is ~8.6 ms,
+    # well below the one-second resolution the contacts are reported at.
+    CONTACT_TOLERANCE = 1e-7
+
+    # Geometry of the Sun, Moon and Earth's shadow at one instant, in kilometres
+    # in the plane perpendicular to the shadow axis at the Moon's distance.
+    class Geometry
+      # @return [Float] distance of the Moon's centre from the shadow axis (km)
+      attr_reader :axis_distance
+
+      # @return [Float] radius of the umbra at the Moon's distance (km)
+      attr_reader :umbra_radius
+
+      # @return [Float] radius of the penumbra at the Moon's distance (km)
+      attr_reader :penumbra_radius
+
+      # @return [Float] signed distance from the shadow axis, in Earth radii
+      attr_reader :gamma
+
+      def initialize(axis_distance:, umbra_radius:, penumbra_radius:, gamma:)
+        @axis_distance = axis_distance
+        @umbra_radius = umbra_radius
+        @penumbra_radius = penumbra_radius
+        @gamma = gamma
+        freeze
+      end
+
+      def umbral_magnitude
+        (umbra_radius + MOON_RADIUS_KM - axis_distance) / (2 * MOON_RADIUS_KM)
+      end
+
+      def penumbral_magnitude
+        (
+          penumbra_radius + MOON_RADIUS_KM - axis_distance
+        ) / (2 * MOON_RADIUS_KM)
+      end
+
+      def penumbral_contact_value
+        axis_distance - (penumbra_radius + MOON_RADIUS_KM)
+      end
+
+      def partial_contact_value
+        axis_distance - (umbra_radius + MOON_RADIUS_KM)
+      end
+
+      def total_contact_value
+        axis_distance - (umbra_radius - MOON_RADIUS_KM)
+      end
+    end
+
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    def initialize(ephem:)
+      @ephem = ephem
+      @geometry_cache = {}
+    end
+
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @return [Array<Astronoby::LunarEclipse>] eclipses whose greatest instant
+    #   lies in the range, sorted by time
+    def events_between(start_time, end_time)
+      full_moon_seeds(start_time, end_time)
+        .filter_map { |seed_jd| eclipse_near(seed_jd) }
+        .select do |eclipse|
+          eclipse.instant.to_time.between?(start_time, end_time)
+        end
+    end
+
+    private
+
+    # Full moons in the range, padded by a day so an eclipse near a boundary is
+    # not missed. Seeded analytically (Meeus, chapter 49) at no ephemeris cost.
+    def full_moon_seeds(start_time, end_time)
+      padded_start = start_time - Constants::SECONDS_PER_DAY
+      padded_end = end_time + Constants::SECONDS_PER_DAY
+      year_months(padded_start, padded_end)
+        .flat_map do |year, month|
+          Events::MoonPhases.phases_for(year: year, month: month)
+        end
+        .select { |phase| phase.phase == :full_moon }
+        .map(&:time)
+        .select { |time| time.between?(padded_start, padded_end) }
+        .map { |time| Instant.from_time(time).tt }
+    end
+
+    def year_months(from, to)
+      cursor = Date.new(from.to_date.year, from.to_date.month, 1)
+      last = Date.new(to.to_date.year, to.to_date.month, 1)
+      months = []
+      while cursor <= last
+        months << [cursor.year, cursor.month]
+        cursor = cursor.next_month
+      end
+      months
+    end
+
+    # Resolves the eclipse for one full-moon seed, if any.
+    def eclipse_near(seed_jd)
+      if geometry_at(seed_jd).axis_distance > MAX_ECLIPSE_GAMMA * EARTH_RADIUS_KM
+        return nil
+      end
+
+      greatest_jd = greatest_eclipse_jd(seed_jd)
+      greatest_jd && eclipse_at(greatest_jd)
+    ensure
+      @geometry_cache.clear
+    end
+
+    # Greatest eclipse: the least distance of the Moon's centre from the shadow
+    # axis, found by minimising it on a narrow window around the full moon.
+    def greatest_eclipse_jd(seed_jd)
+      ExtremumFinder
+        .new(
+          value_at: ->(jd) { geometry_at(jd).axis_distance },
+          period: 2 * GREATEST_HALF_WINDOW,
+          samples_per_period: SEARCH_SAMPLES
+        )
+        .extrema(
+          seed_jd - GREATEST_HALF_WINDOW,
+          seed_jd + GREATEST_HALF_WINDOW,
+          type: :minimum
+        )
+        .min_by { |extremum| extremum[:value] }
+        &.fetch(:jd)
+    end
+
+    def eclipse_at(greatest_jd)
+      geometry = geometry_at(greatest_jd)
+      penumbral = phase_for(greatest_jd, &:penumbral_contact_value)
+      return nil if penumbral.nil?
+
+      partial = phase_for(greatest_jd, &:partial_contact_value)
+      total = phase_for(greatest_jd, &:total_contact_value)
+
+      LunarEclipse.new(
+        instant: Instant.from_terrestrial_time(greatest_jd),
+        kind: kind_for(partial, total),
+        umbral_magnitude: geometry.umbral_magnitude,
+        penumbral_magnitude: geometry.penumbral_magnitude,
+        gamma: geometry.gamma,
+        shadow_axis_distance: Distance.from_kilometers(geometry.axis_distance),
+        penumbral: penumbral,
+        partial: partial,
+        total: total
+      )
+    end
+
+    def kind_for(partial, total)
+      if total
+        LunarEclipse::TOTAL
+      elsif partial
+        LunarEclipse::PARTIAL
+      else
+        LunarEclipse::PENUMBRAL
+      end
+    end
+
+    # Builds a phase from a contact function. The phase occurs only when the
+    # Moon is inside the boundary at greatest eclipse (contact value negative);
+    # each contact is then the single crossing between greatest eclipse and the
+    # corresponding edge of the window, found by bisection. This is robust to
+    # arbitrarily short phases (a barely-total or grazing eclipse), unlike a
+    # fixed-resolution scan that can step over a brief crossing.
+    def phase_for(greatest_jd, &contact_value)
+      value_at = ->(jd) { contact_value.call(geometry_at(jd)) }
+      return nil unless value_at.call(greatest_jd).negative?
+
+      starting = bisect_contact(
+        value_at,
+        greatest_jd - CONTACT_HALF_WINDOW,
+        greatest_jd
+      )
+      ending = bisect_contact(
+        value_at,
+        greatest_jd + CONTACT_HALF_WINDOW,
+        greatest_jd
+      )
+      return nil unless starting && ending
+
+      EclipsePhase.new(
+        starting_instant: Instant.from_terrestrial_time(starting),
+        ending_instant: Instant.from_terrestrial_time(ending)
+      )
+    end
+
+    # Bisects for the single contact between +outside_jd+ (value positive, the
+    # Moon outside the boundary) and +inside_jd+ (value negative, at greatest
+    # eclipse). Returns nil if the boundary is not crossed within the window.
+    def bisect_contact(value_at, outside_jd, inside_jd)
+      return nil unless value_at.call(outside_jd).positive?
+
+      while (inside_jd - outside_jd).abs > CONTACT_TOLERANCE
+        midpoint = (outside_jd + inside_jd) / 2.0
+        if value_at.call(midpoint).negative?
+          inside_jd = midpoint
+        else
+          outside_jd = midpoint
+        end
+      end
+      (outside_jd + inside_jd) / 2.0
+    end
+
+    # Builds the geometry at a Julian Date (TT) from the apparent geocentric
+    # positions of the Sun and Moon. Memoised so repeated evaluations during the
+    # searches reuse the same computation.
+    def geometry_at(jd)
+      @geometry_cache[jd] ||= begin
+        instant = Instant.from_terrestrial_time(jd)
+        moon = Moon.new(ephem: @ephem, instant: instant).apparent
+        sun = Sun.new(ephem: @ephem, instant: instant).apparent
+
+        moon_distance = moon.distance.km
+        sun_distance = sun.distance.km
+        axis_angle = Math::PI - sun.separation_from(moon).radians
+        axial_distance = moon_distance * Math.cos(axis_angle)
+        perpendicular_distance = moon_distance * Math.sin(axis_angle)
+
+        # Danjon enlargement: enlarge Earth's radius before building the cones.
+        earth_radius = EARTH_RADIUS_KM * SHADOW_ENLARGEMENT
+        umbra_half_angle_tangent = (SUN_RADIUS_KM - earth_radius) / sun_distance
+        penumbra_half_angle_tangent =
+          (SUN_RADIUS_KM + earth_radius) / sun_distance
+        latitude_sign = moon.ecliptic.latitude.degrees.negative? ? -1 : 1
+
+        Geometry.new(
+          axis_distance: perpendicular_distance,
+          umbra_radius: earth_radius - axial_distance * umbra_half_angle_tangent,
+          penumbra_radius: earth_radius + axial_distance * penumbra_half_angle_tangent,
+          gamma: latitude_sign * perpendicular_distance / EARTH_RADIUS_KM
+        )
+      end
+    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_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_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,

data/lib/astronoby/events/twilight_events.rb

@@ -1,14 +1,34 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Holds arrays of twilight times over a time range.
   class TwilightEvents
-    attr_reader :morning_civil_twilight_times,
-      :evening_civil_twilight_times,
-      :morning_nautical_twilight_times,
-      :evening_nautical_twilight_times,
-      :morning_astronomical_twilight_times,
-      :evening_astronomical_twilight_times
+    # @return [Array<Time>] morning civil twilight times
+    attr_reader :morning_civil_twilight_times
 
+    # @return [Array<Time>] evening civil twilight times
+    attr_reader :evening_civil_twilight_times
+
+    # @return [Array<Time>] morning nautical twilight times
+    attr_reader :morning_nautical_twilight_times
+
+    # @return [Array<Time>] evening nautical twilight times
+    attr_reader :evening_nautical_twilight_times
+
+    # @return [Array<Time>] morning astronomical twilight times
+    attr_reader :morning_astronomical_twilight_times
+
+    # @return [Array<Time>] evening astronomical twilight times
+    attr_reader :evening_astronomical_twilight_times
+
+    # @param morning_civil [Array<Time>] morning civil twilight times
+    # @param evening_civil [Array<Time>] evening civil twilight times
+    # @param morning_nautical [Array<Time>] morning nautical twilight times
+    # @param evening_nautical [Array<Time>] evening nautical twilight times
+    # @param morning_astronomical [Array<Time>] morning astronomical twilight
+    #   times
+    # @param evening_astronomical [Array<Time>] evening astronomical twilight
+    #   times
     def initialize(
       morning_civil,
       evening_civil,