astronoby 0.8.0 → 0.10.0

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,

data/lib/astronoby/extremum_finder.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class ExtremumFinder
+    PHI = (1 + Math.sqrt(5)) / 2
+    INVPHI = 1 / PHI
+    GOLDEN_SECTION_TOLERANCE = 1e-5
+
+    MIN_SAMPLES_PER_PERIOD = 20
+    DUPLICATE_THRESHOLD_DAYS = 0.5
+    BOUNDARY_BUFFER_DAYS = 0.01
+
+    # @param value_at [#call] callable mapping a Julian Date (Terrestrial Time)
+    #   to a comparable value
+    # @param period [Float] the characteristic period of the quantity in days,
+    #   used to scale the sampling density
+    # @param samples_per_period [Integer] number of samples per period
+    def initialize(value_at:, period:, samples_per_period: 60)
+      @value_at = value_at
+      @period = period
+      @samples_per_period = samples_per_period
+    end
+
+    # @param start_jd [Float] start time in Julian Date (Terrestrial Time)
+    # @param end_jd [Float] end time in Julian Date (Terrestrial Time)
+    # @param type [Symbol] +:maximum+ or +:minimum+
+    # @return [Array<Hash>] extrema as +{jd: Float, value: Comparable}+, sorted
+    #   by time
+    def extrema(start_jd, end_jd, type: :maximum)
+      candidates = find_candidates(start_jd, end_jd, type)
+      refined = candidates.map { |candidate| refine(candidate, type) }.compact
+      refined = remove_duplicates(refined)
+      filter_boundary_artifacts(refined, start_jd, end_jd)
+    end
+
+    private
+
+    def find_candidates(start_jd, end_jd, type)
+      samples = collect_samples(start_jd, end_jd)
+      find_local_extrema(samples, type)
+    end
+
+    def collect_samples(start_jd, end_jd)
+      duration = end_jd - start_jd
+      sample_count = sample_count_for(duration)
+      step = duration / sample_count
+
+      (0..sample_count).map do |i|
+        jd = start_jd + (i * step)
+        {jd: jd, value: @value_at.call(jd)}
+      end
+    end
+
+    def sample_count_for(duration)
+      periods_in_range = duration / @period
+      base_samples = (periods_in_range * @samples_per_period).to_i
+      [base_samples, MIN_SAMPLES_PER_PERIOD].max
+    end
+
+    def find_local_extrema(samples, type)
+      candidates = []
+
+      (1...samples.length - 1).each do |i|
+        next unless local_extremum?(samples, i, type)
+
+        candidates << {
+          start_jd: samples[i - 1][:jd],
+          end_jd: samples[i + 1][:jd]
+        }
+      end
+
+      candidates
+    end
+
+    def local_extremum?(samples, index, type)
+      current = samples[index][:value]
+      previous = samples[index - 1][:value]
+      following = samples[index + 1][:value]
+
+      if type == :maximum
+        current > previous && current > following
+      else
+        current < previous && current < following
+      end
+    end
+
+    def refine(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
+
+      x1 = a + (1 - INVPHI) * (b - a)
+      x2 = a + INVPHI * (b - a)
+      f1 = @value_at.call(x1)
+      f2 = @value_at.call(x2)
+
+      while (b - a).abs > tol
+        keep_left = (type == :maximum) ? (f1 > f2) : (f1 < f2)
+
+        if keep_left
+          b = x2
+          x2 = x1
+          f2 = f1
+          x1 = a + (1 - INVPHI) * (b - a)
+          f1 = @value_at.call(x1)
+        else
+          a = x1
+          x1 = x2
+          f1 = f2
+          x2 = a + INVPHI * (b - a)
+          f2 = @value_at.call(x2)
+        end
+      end
+
+      mid = (a + b) / 2
+      {jd: mid, value: @value_at.call(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|
+          (current[:jd] - existing[:jd]).abs < 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|
+        (extreme[:jd] - start_jd).abs < BOUNDARY_BUFFER_DAYS ||
+          (extreme[:jd] - end_jd).abs < BOUNDARY_BUFFER_DAYS
+      end
+    end
+  end
+end

data/lib/astronoby/instant.rb

@@ -62,6 +62,7 @@ module Astronoby
       end
     end
 
+    # @return [Numeric] the Terrestrial Time as a Julian Date
     attr_reader :terrestrial_time
     alias_method :tt, :terrestrial_time
     alias_method :julian_date, :terrestrial_time
@@ -77,6 +78,7 @@ module Astronoby
       end
 
       @terrestrial_time = terrestrial_time
+      @memo = {}
       freeze
     end
 
@@ -92,9 +94,9 @@ module Astronoby
     #
     # @return [DateTime] the UTC time as DateTime
     def to_datetime
-      DateTime.jd(
+      @memo[:to_datetime] ||= DateTime.jd(
         @terrestrial_time -
-          Rational(delta_t / Constants::SECONDS_PER_DAY) +
+          Rational(delta_t, Constants::SECONDS_PER_DAY) +
           DATETIME_JD_EPOCH_ADJUSTMENT
       )
     end
@@ -110,7 +112,7 @@ module Astronoby
     #
     # @return [Time] the UTC time
     def to_time
-      to_datetime.to_time.utc
+      @memo[:to_time] ||= to_datetime.to_time.utc
     end
 
     # Get the ΔT (Delta T) value for this instant
@@ -118,21 +120,45 @@ module Astronoby
     #
     # @return [Numeric] Delta T in seconds
     def delta_t
-      Util::Time.terrestrial_universal_time_delta(@terrestrial_time)
+      @memo[:delta_t] ||=
+        Util::Time.terrestrial_universal_time_delta(@terrestrial_time)
     end
 
     # Get the Greenwich Mean Sidereal Time
     #
-    # @return [Numeric] the sidereal time in radians
+    # @return [Numeric] the sidereal time in hours
     def gmst
-      GreenwichSiderealTime.from_utc(to_time).time
+      @memo[:gmst] ||= GreenwichMeanSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Greenwich Apparent Sidereal Time
+    #
+    # @return [Numeric] the sidereal time in hours
+    def gast
+      @memo[:gast] ||= GreenwichApparentSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Local Mean Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def lmst(longitude:)
+      LocalMeanSiderealTime.from_utc(to_time, longitude: longitude).time
+    end
+
+    # Get the Local Apparent Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def last(longitude:)
+      LocalApparentSiderealTime.from_utc(to_time, longitude: longitude).time
     end
 
     # Get the International Atomic Time (TAI)
     #
     # @return [Numeric] TAI as Julian Date
     def tai
-      @terrestrial_time -
+      @memo[:tai] ||= @terrestrial_time -
         Rational(Constants::TAI_TT_OFFSET, Constants::SECONDS_PER_DAY)
     end
 
@@ -144,14 +170,14 @@ module Astronoby
       # This is technically false, there is a slight difference between TT and
       # TDB. However, this difference is so small that currenly Astronoby
       # doesn't support it and consider they are the same value.
-      @terrestrial_time
+      @memo[:tdb] ||= @terrestrial_time
     end
 
     # Get the offset between TT and UTC for this instant
     #
     # @return [Numeric] the offset in days
     def utc_offset
-      @terrestrial_time - to_time.utc.to_datetime.ajd
+      Rational(delta_t / Constants::SECONDS_PER_DAY)
     end
 
     # Calculate hash value for the instant

data/lib/astronoby/libration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Geocentric libration of the Moon: the small oscillations that let an
+  # observer on Earth see slightly more than half of the lunar surface over
+  # time. Holds the total (optical + physical) libration in longitude and
+  # latitude.
+  class Libration
+    # @return [Astronoby::Angle] libration in longitude (l), positive towards
+    #   the Moon's Mare Crisium (east limb)
+    attr_reader :longitude
+
+    # @return [Astronoby::Angle] libration in latitude (b), positive towards
+    #   the Moon's north pole
+    attr_reader :latitude
+
+    # @param longitude [Astronoby::Angle] libration in longitude
+    # @param latitude [Astronoby::Angle] libration in latitude
+    def initialize(longitude:, latitude:)
+      @longitude = longitude
+      @latitude = latitude
+      freeze
+    end
+  end
+end

data/lib/astronoby/mean_obliquity.rb

@@ -4,6 +4,7 @@
 # as these coefficients work with TT (Terrestrial Time).
 
 module Astronoby
+  # Computes the mean obliquity of the ecliptic using the IAU 2006 P03 model.
   class MeanObliquity
     # Source:
     #  IAU resolution in 2006 in favor of the P03 astronomical model
@@ -12,6 +13,10 @@ module Astronoby
     EPOCH_OF_REFERENCE = JulianDate::DEFAULT_EPOCH
     OBLIQUITY_OF_REFERENCE = 23.4392794
 
+    # Computes the mean obliquity of the ecliptic at the given instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Astronoby::Angle] the mean obliquity
     def self.at(instant)
       return obliquity_of_reference if instant.julian_date == EPOCH_OF_REFERENCE
 
@@ -32,10 +37,13 @@ module Astronoby
       )
     end
 
+    # @return [Astronoby::Angle] the mean obliquity at the reference epoch
+    #   (J2000.0)
     def self.obliquity_of_reference
       Angle.from_degree_arcseconds(obliquity_of_reference_in_arcseconds)
     end
 
+    # @return [Float] the mean obliquity at J2000.0 in arcseconds
     def self.obliquity_of_reference_in_arcseconds
       84381.406
     end

data/lib/astronoby/moon_orientation_ephemeris.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes the Moon's libration and the position angle of its axis from a
+  # binary PCK lunar orientation kernel, as the arcsecond-accurate counterpart
+  # to the analytic Meeus series in MoonPhysicalEphemeris.
+  #
+  # The libration is the selenographic longitude and latitude of the sub-Earth
+  # point, expressed in the Moon's mean-Earth body-fixed frame.
+  class MoonOrientationEphemeris
+    # @param moon [Astronoby::Moon] the Moon, carrying an orientation kernel
+    def initialize(moon)
+      @moon = moon
+      @instant = moon.instant
+      @orientation = moon.orientation
+    end
+
+    # @return [Astronoby::Libration] the libration in longitude and latitude
+    def libration
+      sub_earth = rotation * moon_to_earth
+      Libration.new(
+        longitude: Angle.from_radians(Math.atan2(sub_earth[1], sub_earth[0])),
+        latitude: Angle.from_radians(
+          Math.asin(sub_earth[2] / sub_earth.magnitude)
+        )
+      )
+    end
+
+    # Position angle of the Moon's axis of rotation, measured eastward from the
+    # north point of the disk.
+    # @return [Astronoby::Angle] the position angle of the axis
+    def position_angle_of_axis
+      @moon.apparent.equatorial.position_angle_to(north_pole)
+    end
+
+    private
+
+    def rotation
+      @rotation ||= @orientation.rotation_for(retarded_instant)
+    end
+
+    def retarded_instant
+      Instant.from_terrestrial_time(
+        @instant.terrestrial_time - light_time_in_days
+      )
+    end
+
+    def light_time_in_days
+      @moon.astrometric.distance.km /
+        Velocity.light_speed.kmps /
+        Constants::SECONDS_PER_DAY
+    end
+
+    def moon_to_earth
+      x, y, z = @moon.astrometric.position.map(&:m).to_a
+      ::Vector[-x, -y, -z]
+    end
+
+    def north_pole
+      @north_pole ||= Coordinates::Equatorial.from_position_vector(
+        Distance.vector_from_meters(
+          Nutation.matrix_for(@instant) *
+            Precession.matrix_for(@instant) *
+            (rotation.transpose * ::Vector[0, 0, 1])
+        )
+      )
+    end
+  end
+end

data/lib/astronoby/moon_physical_ephemeris.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes the ephemeris for physical observations of the Moon: the total
+  # (optical + physical) libration in longitude and latitude, and the position
+  # angle of the Moon's axis of rotation.
+  #
+  # Source:
+  #  Title: Astronomical Algorithms
+  #  Author: Jean Meeus
+  #  Edition: 2nd edition
+  #  Chapter: 53 - Ephemeris for Physical Observations of the Moon
+  class MoonPhysicalEphemeris
+    # Inclination of the mean lunar equator to the ecliptic
+    INCLINATION = Angle.from_degrees(1.54242)
+
+    # @param moon [Astronoby::Moon] the Moon at the desired instant
+    def initialize(moon)
+      @moon = moon
+      @instant = moon.instant
+    end
+
+    # @return [Astronoby::Libration] the total libration in longitude and
+    #   latitude
+    def libration
+      Libration.new(
+        longitude: Angle.from_degrees(libration_in_longitude),
+        latitude: Angle.from_degrees(libration_in_latitude)
+      )
+    end
+
+    # @return [Astronoby::Angle] the position angle of the Moon's axis of
+    #   rotation, measured eastward from the north point of the disk
+    def position_angle_of_axis
+      i_rho = INCLINATION + Angle.from_degrees(rho)
+      v = ascending_node +
+        nutation_in_longitude +
+        Angle.from_degrees(sigma / INCLINATION.sin)
+
+      x = i_rho.sin * v.sin
+      y = i_rho.sin * v.cos * obliquity.cos - i_rho.cos * obliquity.sin
+      omega = Math.atan2(x, y)
+
+      Angle.from_radians(
+        Math.asin(
+          Math.sqrt(x * x + y * y) *
+            Math.cos(right_ascension.radians - omega) /
+            Angle.from_degrees(libration_in_latitude).cos
+        )
+      )
+    end
+
+    private
+
+    # @return [Float] total libration in longitude, in degrees, in (-180, 180]
+    def libration_in_longitude
+      l = optical_longitude + physical_longitude
+      ((l + 180) % 360) - 180
+    end
+
+    # @return [Float] total libration in latitude, in degrees
+    def libration_in_latitude
+      optical_latitude + physical_latitude
+    end
+
+    # Optical libration in longitude, l' = A - F (Meeus 53.1)
+    # @return [Float] in degrees
+    def optical_longitude
+      argument_a.degrees - argument_of_latitude.degrees
+    end
+
+    # Optical libration in latitude (Meeus 53.1)
+    # @return [Float] in degrees
+    def optical_latitude
+      Angle.from_radians(optical_latitude_radians).degrees
+    end
+
+    # Physical libration in longitude (Meeus 53.2)
+    # @return [Float] in degrees
+    def physical_longitude
+      -tau +
+        (rho * argument_a.cos + sigma * argument_a.sin) *
+          Math.tan(optical_latitude_radians)
+    end
+
+    # Physical libration in latitude (Meeus 53.2)
+    # @return [Float] in degrees
+    def physical_latitude
+      sigma * argument_a.cos - rho * argument_a.sin
+    end
+
+    # The argument "A" of the optical libration (Meeus 53.1)
+    def argument_a
+      @argument_a ||= Angle.from_radians(
+        Math.atan2(
+          w.sin * latitude.cos * INCLINATION.cos -
+            latitude.sin * INCLINATION.sin,
+          w.cos * latitude.cos
+        )
+      )
+    end
+
+    def optical_latitude_radians
+      @optical_latitude_radians ||= Math.asin(
+        -w.sin * latitude.cos * INCLINATION.sin - latitude.sin * INCLINATION.cos
+      )
+    end
+
+    # W = λ - Δψ - Ω, the Moon's longitude referred to the mean equinox of
+    # date, measured from the ascending node of the mean lunar equator
+    def w
+      @w ||= longitude - nutation_in_longitude - ascending_node
+    end
+
+    # @return [Float] periodic terms ρ, in degrees (Meeus 53)
+    def rho
+      @rho ||= trig_series([
+        [-0.02752, mp.radians, :cos],
+        [-0.02245, f.radians, :sin],
+        [0.00684, (mp - f - f).radians, :cos],
+        [-0.00293, (f + f).radians, :cos],
+        [-0.00085, (f + f - d - d).radians, :cos],
+        [-0.00054, (mp - d - d).radians, :cos],
+        [-0.00020, (mp + f).radians, :sin],
+        [-0.00020, (mp + f + f).radians, :cos],
+        [-0.00020, (mp - f).radians, :cos],
+        [0.00014, (mp + f + f - d - d).radians, :cos]
+      ])
+    end
+
+    # @return [Float] periodic terms σ, in degrees (Meeus 53)
+    def sigma
+      @sigma ||= trig_series([
+        [-0.02816, mp.radians, :sin],
+        [0.02244, f.radians, :cos],
+        [-0.00682, (mp - f - f).radians, :sin],
+        [-0.00279, (f + f).radians, :sin],
+        [-0.00083, (f + f - d - d).radians, :sin],
+        [0.00069, (mp - d - d).radians, :sin],
+        [0.00040, (mp + f).radians, :cos],
+        [-0.00025, (mp + mp).radians, :sin],
+        [-0.00023, (mp + f + f).radians, :sin],
+        [0.00020, (mp - f).radians, :cos],
+        [0.00019, (mp - f).radians, :sin],
+        [0.00013, (mp + f + f - d - d).radians, :sin],
+        [-0.00010, (mp - f - f - f).radians, :cos]
+      ])
+    end
+
+    # @return [Float] periodic terms τ, in degrees (Meeus 53)
+    def tau
+      @tau ||= trig_series([
+        [0.02520 * eccentricity, m.radians, :sin],
+        [0.00473, (mp + mp - f - f).radians, :sin],
+        [-0.00467, mp.radians, :sin],
+        [0.00396, k1.radians, :sin],
+        [0.00276, (mp + mp - d - d).radians, :sin],
+        [0.00196, ascending_node.radians, :sin],
+        [-0.00183, (mp - f).radians, :cos],
+        [0.00115, (mp - d - d).radians, :sin],
+        [-0.00096, (mp - d).radians, :sin],
+        [0.00046, (f + f - d - d).radians, :sin],
+        [-0.00039, (mp - f).radians, :sin],
+        [-0.00032, (mp - m - d).radians, :sin],
+        [0.00027, (mp + mp - m - d - d).radians, :sin],
+        [0.00023, k2.radians, :sin],
+        [-0.00014, (d + d).radians, :sin],
+        [0.00014, (mp + mp - f - f).radians, :cos],
+        [-0.00012, (mp - f - f).radians, :sin],
+        [-0.00012, (mp + mp).radians, :sin],
+        [0.00011, (mp + mp - m - m - d - d).radians, :sin]
+      ])
+    end
+
+    def trig_series(terms)
+      terms.sum do |coefficient, argument, fn|
+        coefficient * Math.send(fn, argument)
+      end
+    end
+
+    # Apparent geocentric ecliptic longitude (true equinox of date, λ)
+    def longitude
+      @longitude ||= @moon.apparent.ecliptic.longitude
+    end
+
+    # Apparent geocentric ecliptic latitude (β)
+    def latitude
+      @latitude ||= @moon.apparent.ecliptic.latitude
+    end
+
+    # Apparent geocentric right ascension (α)
+    def right_ascension
+      @right_ascension ||= @moon.apparent.equatorial.right_ascension
+    end
+
+    def obliquity
+      @obliquity ||= TrueObliquity.at(@instant)
+    end
+
+    def nutation_in_longitude
+      @nutation_in_longitude ||=
+        Nutation.new(instant: @instant).nutation_in_longitude
+    end
+
+    def t
+      @t ||=
+        (@instant.tt - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
+    end
+
+    # Mean elongation of the Moon (D), Meeus 47.5
+    def d
+      @d ||= Angle.from_degrees(
+        297.8501921 + 445267.1114034 * t - 0.0018819 * t**2 +
+          t**3 / 545868 - t**4 / 113065000
+      )
+    end
+
+    # Sun's mean anomaly (M), Meeus 47.3
+    def m
+      @m ||= Angle.from_degrees(
+        357.5291092 + 35999.0502909 * t - 0.0001536 * t**2 + t**3 / 24490000
+      )
+    end
+
+    # Moon's mean anomaly (M'), Meeus 47.4
+    def mp
+      @mp ||= Angle.from_degrees(
+        134.9633964 + 477198.8675055 * t + 0.0087414 * t**2 +
+          t**3 / 69699 - t**4 / 14712000
+      )
+    end
+
+    # Moon's argument of latitude (F), Meeus 47.5
+    def f
+      @f ||= Angle.from_degrees(
+        93.2720950 + 483202.0175233 * t - 0.0036539 * t**2 -
+          t**3 / 3526000 + t**4 / 863310000
+      )
+    end
+    alias_method :argument_of_latitude, :f
+
+    # Longitude of the mean ascending node (Ω), Meeus 47.7
+    def ascending_node
+      @ascending_node ||= Angle.from_degrees(
+        125.0445479 - 1934.1362891 * t + 0.0020754 * t**2 +
+          t**3 / 467441 - t**4 / 60616000
+      )
+    end
+
+    # Eccentricity correction (E), Meeus 47.6
+    def eccentricity
+      @eccentricity ||= 1 - 0.002516 * t - 0.0000074 * t**2
+    end
+
+    def k1
+      @k1 ||= Angle.from_degrees(119.75 + 131.849 * t)
+    end
+
+    def k2
+      @k2 ||= Angle.from_degrees(72.56 + 20.186 * t)
+    end
+  end
+end