astronoby 0.9.0 → 0.11.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/horizon.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Astronoby
+  module Horizon
+    # @return [Astronoby::Angle] altitude of the centre of a point-like body at
+    #   rise and set
+    REFRACTION_ANGLE = -Angle.from_dms(0, 34, 0)
+
+    # @return [Astronoby::Angle] altitude of the Sun's centre at rise and set
+    SUN_ANGLE = -Angle.from_dms(0, 50, 0)
+
+    class << self
+      # @param body [Class] the body rising or setting
+      # @param distance [Astronoby::Distance] distance to the body, used for
+      #   the Moon's semidiameter
+      # @return [Astronoby::Angle] altitude of the body's centre at rise and set
+      def angle_for(body:, distance:)
+        if body == Sun
+          SUN_ANGLE
+        elsif body == Moon
+          REFRACTION_ANGLE - moon_semidiameter(distance)
+        else
+          REFRACTION_ANGLE
+        end
+      end
+
+      # @param distance [Astronoby::Distance] distance to the Moon
+      # @return [Astronoby::Angle] the Moon's semidiameter
+      def moon_semidiameter(distance)
+        Angle.from_radians(moon_semidiameter_radians(distance.m))
+      end
+
+      # @param distance_in_meters [Numeric] distance to the Moon in meters
+      # @return [Float] the Moon's semidiameter in radians
+      def moon_semidiameter_radians(distance_in_meters)
+        Moon::EQUATORIAL_RADIUS.m.to_f / distance_in_meters
+      end
+    end
+  end
+end

data/lib/astronoby/horizontal_transformation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Transforms equatorial coordinates at J2000.0 into horizontal coordinates
+  # for one observer at one instant.
+  #
+  # Everything that depends only on the observer and the instant is computed
+  # once at construction: the rotation from the ICRS to the true equator and
+  # equinox of date (nutation * precession, with the ICRS frame bias), and the
+  # local apparent sidereal time. Converting a point then costs a matrix
+  # product and a few trigonometric functions, instead of rebuilding the
+  # reference frame chain for each point. It is meant for converting many
+  # points for the same observer and instant, such as the stars of a catalogue
+  # for a sky chart.
+  #
+  # It plays the role of the "star-independent astrometry parameters" of SOFA
+  # and ERFA, restricted to what Astronoby applies without an ephemeris. The
+  # result is the same as
+  # `DeepSkyObject#at(instant).observed_by(observer).horizontal`, but the
+  # points are treated as fixed directions: no aberration, no proper motion and
+  # no parallax. The topocentric correction is not applied either, as it is
+  # nil for objects at stellar distances. Atmospheric refraction is optional.
+  #
+  # @example Convert the stars of a catalogue for one observer and instant
+  #   transformation = Astronoby::HorizontalTransformation.new(
+  #     observer: observer,
+  #     instant: instant
+  #   )
+  #   horizontals = catalogue.map { |star| transformation.apply(star) }
+  class HorizontalTransformation
+    # @return [Astronoby::Observer] the observer
+    attr_reader :observer
+
+    # @return [Astronoby::Instant] the instant
+    attr_reader :instant
+
+    # @param observer [Astronoby::Observer] the observer
+    # @param instant [Astronoby::Instant] the instant of the observation
+    def initialize(observer:, instant:)
+      @observer = observer
+      @instant = instant
+      @rotation_rows = (
+        Nutation.matrix_for(instant) * Precession.matrix_for(instant)
+      ).to_a.freeze
+      @local_apparent_sidereal_time = LocalApparentSiderealTime.from_utc(
+        instant.to_time,
+        longitude: observer.longitude
+      ).time
+      freeze
+    end
+
+    # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
+    #   equatorial coordinates at epoch J2000.0
+    # @param refraction [Boolean] whether to apply atmospheric refraction
+    #   correction (default: false)
+    # @return [Astronoby::Coordinates::Horizontal] horizontal coordinates
+    # @raise [Astronoby::IncompatibleArgumentsError] if the coordinates are not
+    #   referred to epoch J2000.0
+    def apply(equatorial_coordinates, refraction: false)
+      ensure_j2000!(equatorial_coordinates)
+
+      horizontal = apparent_equatorial(equatorial_coordinates).to_horizontal(
+        time: @instant.to_time,
+        observer: @observer
+      )
+
+      if refraction
+        Refraction.correct_horizontal_coordinates(coordinates: horizontal)
+      else
+        horizontal
+      end
+    end
+
+    private
+
+    # Equatorial coordinates of date, with the hour angle already known so that
+    # the sidereal time is not computed again.
+    def apparent_equatorial(coordinates)
+      declination = coordinates.declination
+      right_ascension = coordinates.right_ascension
+      cos_declination = declination.cos
+      x = cos_declination * right_ascension.cos
+      y = cos_declination * right_ascension.sin
+      z = declination.sin
+
+      row_x, row_y, row_z = @rotation_rows
+      apparent_x = row_x[0] * x + row_x[1] * y + row_x[2] * z
+      apparent_y = row_y[0] * x + row_y[1] * y + row_y[2] * z
+      apparent_z = row_z[0] * x + row_z[1] * y + row_z[2] * z
+
+      apparent_right_ascension =
+        Angle.from_radians(Math.atan2(apparent_y, apparent_x))
+
+      Coordinates::Equatorial.new(
+        right_ascension: apparent_right_ascension,
+        declination: Angle.asin(apparent_z.clamp(-1.0, 1.0)),
+        hour_angle:
+          Angle.from_hours(@local_apparent_sidereal_time) -
+            apparent_right_ascension,
+        epoch: @instant.tt
+      )
+    end
+
+    def ensure_j2000!(coordinates)
+      return if coordinates.epoch == JulianDate::J2000
+
+      raise IncompatibleArgumentsError,
+        "Expected equatorial coordinates at epoch J2000.0, got epoch " \
+        "#{coordinates.epoch}"
+    end
+  end
+end

data/lib/astronoby/instant.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
+require "horologium"
 
 module Astronoby
   # Represents a specific instant in time using Terrestrial Time (TT) as its
@@ -8,9 +9,15 @@ module Astronoby
   # time scales commonly used in astronomy:
   # - Terrestrial Time (TT)
   # - International Atomic Time (TAI)
+  # - Barycentric Dynamical Time (TDB)
   # - Universal Time Coordinated (UTC)
   # - Greenwich Mean Sidereal Time (GMST)
   #
+  # TAI and TDB are delegated to the horologium gem, which owns the scales
+  # that convert by definition or by model. UT1 is not: it rests on
+  # observations of the rotation of the Earth, and comes from
+  # {Astronoby::DeltaT}.
+  #
   # @example Create an instant from the current time
   #   instant = Astronoby::Instant.from_time(Time.now)
   #   instant.tai  # Get International Atomic Time
@@ -28,6 +35,16 @@ module Astronoby
     # midnight. This constant adds 0.5 days (12 hours) to make the conversion.
     DATETIME_JD_EPOCH_ADJUSTMENT = 0.5
 
+    # Astronoby pins the precision it asks horologium for rather than reading
+    # horologium's global default, so a host application configuring
+    # horologium for itself cannot change what Astronoby computes.
+    #
+    # Exact rather than standard: standard would round the Julian Date into a
+    # two-part float on the way in, and TAI is a fixed offset from TT, so
+    # there is nothing to round it for. It is also the cheaper of the two
+    # here, having no conversion to make in either direction.
+    PRECISION = :exact
+
     class << self
       # Creates a new Instant from a Terrestrial Time value
       #
@@ -44,7 +61,7 @@ module Astronoby
       # @param time [Time] a Time object to convert
       # @return [Astronoby::Instant] a new Instant object
       def from_time(time)
-        delta_t = Util::Time.terrestrial_universal_time_delta(time)
+        delta_t = DeltaT.at(time)
         terrestrial_time = time.utc.to_datetime.ajd +
           Rational(delta_t, Constants::SECONDS_PER_DAY)
         from_terrestrial_time(terrestrial_time)
@@ -55,13 +72,14 @@ module Astronoby
       # @param julian_date [Numeric] the Julian Date in UTC
       # @return [Astronoby::Instant] a new Instant object
       def from_utc_julian_date(julian_date)
-        delta_t = Util::Time.terrestrial_universal_time_delta(julian_date)
+        delta_t = DeltaT.at(julian_date)
         terrestrial_time = julian_date +
           Rational(delta_t, Constants::SECONDS_PER_DAY)
         from_terrestrial_time(terrestrial_time)
       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 +95,7 @@ module Astronoby
       end
 
       @terrestrial_time = terrestrial_time
+      @memo = {}
       freeze
     end
 
@@ -92,7 +111,7 @@ 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) +
           DATETIME_JD_EPOCH_ADJUSTMENT
@@ -110,7 +129,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 +137,21 @@ module Astronoby
     #
     # @return [Numeric] Delta T in seconds
     def delta_t
-      Util::Time.terrestrial_universal_time_delta(@terrestrial_time)
+      @memo[:delta_t] ||= DeltaT.at(@terrestrial_time)
     end
 
     # Get the Greenwich Mean Sidereal Time
     #
     # @return [Numeric] the sidereal time in hours
     def gmst
-      GreenwichMeanSiderealTime.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
-      GreenwichApparentSiderealTime.from_utc(to_time).time
+      @memo[:gast] ||= GreenwichApparentSiderealTime.from_utc(to_time).time
     end
 
     # Get the Local Mean Sidereal Time
@@ -153,21 +172,26 @@ module Astronoby
 
     # Get the International Atomic Time (TAI)
     #
-    # @return [Numeric] TAI as Julian Date
+    # Read as a Rational rather than a Float. A Julian Date is around 2.46
+    # million, so a single Float rounds to about 47 microseconds of the day,
+    # which would coarsen an instant that TT carries exactly.
+    #
+    # @return [Rational] TAI as Julian Date
     def tai
-      @terrestrial_time -
-        Rational(Constants::TAI_TT_OFFSET, Constants::SECONDS_PER_DAY)
+      @memo[:tai] ||= scale_free_instant
+        .as(:julian_date, scale: :tai, as: :rational)
     end
 
     # Get the Barycentric Dynamical Time (TDB)
-    # Note: Currently approximated as equal to TT
     #
-    # @return [Numeric] TDB as Julian Date
+    # TDB - TT comes from the Fairhead and Bretagnon series ERFA uses. It
+    # peaks around 1.7 milliseconds, so a Float Julian Date would quantise
+    # most of the correction away; see {#tai} on the shape.
+    #
+    # @return [Rational] TDB as Julian Date
     def tdb
-      # 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] ||= scale_free_instant
+        .as(:julian_date, scale: :tdb, as: :rational)
     end
 
     # Get the offset between TT and UTC for this instant
@@ -195,5 +219,21 @@ module Astronoby
       @terrestrial_time <=> other.terrestrial_time
     end
     alias_method :eql?, :==
+
+    private
+
+    # The instant as horologium holds it: a point on the timeline with no
+    # scale of its own. Building it costs more than reading a Julian Date back
+    # out of it, so it is built on the first scale conversion that needs it
+    # and never on the paths that only want TT.
+    #
+    # @return [Horologium::Instant]
+    def scale_free_instant
+      @memo[:scale_free_instant] ||= Horologium::Instant.from_julian_date(
+        @terrestrial_time,
+        scale: :tt,
+        precision: PRECISION
+      )
+    end
   end
 end

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