astronoby 0.8.0 → 0.10.0

data/lib/astronoby/distance.rb

@@ -1,87 +1,128 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents a distance with meters as its internal representation.
+  # Provides conversions between meters, kilometers, astronomical units,
+  # and parsecs.
+  #
+  # @example Create a distance from astronomical units
+  #   distance = Astronoby::Distance.from_au(1.0)
+  #   distance.km  # => 149597870.7
+  #
   class Distance
     include Comparable
 
     class << self
+      # @return [Astronoby::Distance] a zero distance
       def zero
         new(0)
       end
 
+      # @param meters [Numeric] the distance in meters
+      # @return [Astronoby::Distance] a new Distance
       def from_meters(meters)
         new(meters)
       end
       alias_method :from_m, :from_meters
 
+      # @param kilometers [Numeric] the distance in kilometers
+      # @return [Astronoby::Distance] a new Distance
       def from_kilometers(kilometers)
         meters = kilometers * Constants::KILOMETER_IN_METERS
         from_meters(meters)
       end
       alias_method :from_km, :from_kilometers
 
+      # @param astronomical_units [Numeric] the distance in AU
+      # @return [Astronoby::Distance] a new Distance
       def from_astronomical_units(astronomical_units)
         meters = astronomical_units * Constants::ASTRONOMICAL_UNIT_IN_METERS
         from_meters(meters)
       end
       alias_method :from_au, :from_astronomical_units
 
+      # @param parsecs [Numeric] the distance in parsecs
+      # @return [Astronoby::Distance] a new Distance
+      def from_parsecs(parsecs)
+        meters = parsecs * Constants::PARSEC_IN_METERS
+        from_meters(meters)
+      end
+      alias_method :from_pc, :from_parsecs
+
+      # @param array [Array<Numeric>] array of meter values
+      # @return [Astronoby::Vector<Astronoby::Distance>] a vector of Distances
       def vector_from_meters(array)
         Vector.elements(array.map { from_meters(_1) })
       end
       alias_method :vector_from_m, :vector_from_meters
     end
 
+    # @return [Numeric] the distance in meters
     attr_reader :meters
     alias_method :m, :meters
 
+    # @param meters [Numeric] the distance in meters
     def initialize(meters)
       @meters = meters
       freeze
     end
 
+    # @return [Float] the distance in kilometers
     def kilometers
       @meters / Constants::KILOMETER_IN_METERS.to_f
     end
     alias_method :km, :kilometers
 
+    # @return [Float] the distance in astronomical units
     def astronomical_units
       @meters / Constants::ASTRONOMICAL_UNIT_IN_METERS.to_f
     end
     alias_method :au, :astronomical_units
 
+    # @param other [Astronoby::Distance] distance to add
+    # @return [Astronoby::Distance] the sum
     def +(other)
       self.class.from_meters(meters + other.meters)
     end
 
+    # @param other [Astronoby::Distance] distance to subtract
+    # @return [Astronoby::Distance] the difference
     def -(other)
       self.class.from_meters(@meters - other.meters)
     end
 
+    # @return [Astronoby::Distance] the negated distance
     def -@
       self.class.from_meters(-@meters)
     end
 
+    # @return [Boolean] true if the distance is positive
     def positive?
       meters > 0
     end
 
+    # @return [Boolean] true if the distance is negative
     def negative?
       meters < 0
     end
 
+    # @return [Boolean] true if the distance is zero
     def zero?
       meters.zero?
     end
 
+    # @return [Numeric] the square of the distance in meters
     def abs2
       meters**2
     end
 
+    # @return [Integer] hash value
     def hash
       [meters, self.class].hash
     end
 
+    # @param other [Astronoby::Distance] distance to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 

data/lib/astronoby/duration.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Duration
+    include Comparable
+
+    class << self
+      # @return [Astronoby::Duration] a zero duration
+      def zero
+        new(0)
+      end
+
+      # @param seconds [Numeric] the duration in seconds
+      # @return [Astronoby::Duration] a new Duration
+      def from_seconds(seconds)
+        new(seconds)
+      end
+
+      # @param minutes [Numeric] the duration in minutes
+      # @return [Astronoby::Duration] a new Duration
+      def from_minutes(minutes)
+        seconds = minutes * Constants::SECONDS_PER_MINUTE
+        from_seconds(seconds)
+      end
+
+      # @param hours [Numeric] the duration in hours
+      # @return [Astronoby::Duration] a new Duration
+      def from_hours(hours)
+        seconds = hours * Constants::SECONDS_PER_HOUR
+        from_seconds(seconds)
+      end
+
+      # @param days [Numeric] the duration in days
+      # @return [Astronoby::Duration] a new Duration
+      def from_days(days)
+        seconds = days * Constants::SECONDS_PER_DAY
+        from_seconds(seconds)
+      end
+    end
+
+    # @return [Numeric] the duration in seconds
+    attr_reader :seconds
+
+    # @param seconds [Numeric] the duration in seconds
+    def initialize(seconds)
+      @seconds = seconds
+      freeze
+    end
+
+    # @return [Float] the duration in minutes
+    def minutes
+      @seconds / Constants::SECONDS_PER_MINUTE
+    end
+
+    # @return [Float] the duration in hours
+    def hours
+      @seconds / Constants::SECONDS_PER_HOUR
+    end
+
+    # @return [Float] the duration in days
+    def days
+      @seconds / Constants::SECONDS_PER_DAY
+    end
+
+    # @param other [Astronoby::Duration] duration to add
+    # @return [Astronoby::Duration] the sum
+    def +(other)
+      self.class.from_seconds(@seconds + other.seconds)
+    end
+
+    # @param other [Astronoby::Duration] duration to subtract
+    # @return [Astronoby::Duration] the difference
+    def -(other)
+      self.class.from_seconds(@seconds - other.seconds)
+    end
+
+    # @return [Astronoby::Duration] the negated duration
+    def -@
+      self.class.from_seconds(-@seconds)
+    end
+
+    # @return [Astronoby::Duration] the absolute duration
+    def abs
+      self.class.from_seconds(@seconds.abs)
+    end
+
+    # @return [Boolean] true if the duration is positive
+    def positive?
+      @seconds > 0
+    end
+
+    # @return [Boolean] true if the duration is negative
+    def negative?
+      @seconds < 0
+    end
+
+    # @return [Boolean] true if the duration is zero
+    def zero?
+      @seconds.zero?
+    end
+
+    # @return [Integer] hash value
+    def hash
+      [@seconds, self.class].hash
+    end
+
+    # @param other [Astronoby::Duration] duration to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      seconds <=> other.seconds
+    end
+    alias_method :eql?, :==
+  end
+end

data/lib/astronoby/earth_rotation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes Earth rotation matrices using Greenwich Sidereal Time.
+  # Provides both apparent (GAST-based) and mean (GMST-based) rotation
+  # matrices for transforming between Earth-fixed and celestial frames.
+  class EarthRotation
+    # Computes the apparent Earth rotation matrix R₃(GAST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 Earth rotation matrix
+    def self.matrix_for(instant)
+      new(instant: instant).matrix
+    end
+
+    # Computes the mean Earth rotation matrix R₃(GMST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 mean Earth rotation matrix
+    def self.mean_matrix_for(instant)
+      new(instant: instant).mean_matrix
+    end
+
+    # @param instant [Astronoby::Instant] the time instant
+    def initialize(instant:)
+      @instant = instant
+    end
+
+    # Computes R₃(GAST), the apparent Earth rotation matrix.
+    # GAST = GMST + equation of the equinoxes (Δψ cos ε₀).
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def matrix
+      rotation_matrix_for(gast)
+    end
+
+    # Computes R₃(GMST), the mean Earth rotation matrix.
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def mean_matrix
+      rotation_matrix_for(gmst)
+    end
+
+    private
+
+    def gmst
+      Angle.from_hours(@instant.gmst)
+    end
+
+    def gast
+      nutation = Nutation.new(instant: @instant)
+      dpsi = nutation.nutation_in_longitude
+      mean_obliquity = MeanObliquity.at(@instant)
+      Angle.from_radians(
+        gmst.radians + dpsi.radians * mean_obliquity.cos
+      )
+    end
+
+    def rotation_matrix_for(angle)
+      c, s = angle.cos, angle.sin
+      Matrix[
+        [c, -s, 0],
+        [s, c, 0],
+        [0, 0, 1]
+      ]
+    end
+  end
+end

data/lib/astronoby/equinox_solstice.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes the time of equinoxes and solstices for a given year.
+  #
+  # Source:
+  #  Title: Astronomical Algorithms
+  #  Author: Jean Meeus
+  #  Edition: 2nd edition
+  #  Chapter: 27 - Equinoxes and Soltices
   class EquinoxSolstice
-    # Source:
-    #  Title: Astronomical Algorithms
-    #  Author: Jean Meeus
-    #  Edition: 2nd edition
-    #  Chapter: 27 - Equinoxes and Soltices
-
     EVENTS = [
       MARCH_EQUINOX = 0,
       JUNE_SOLSTICE = 1,
@@ -73,22 +74,39 @@ module Astronoby
       [8, 15.45, 16859.074]
     ].freeze
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the March equinox
     def self.march_equinox(year, ephem)
       new(year, MARCH_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the June solstice
     def self.june_solstice(year, ephem)
       new(year, JUNE_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the September equinox
     def self.september_equinox(year, ephem)
       new(year, SEPTEMBER_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the December solstice
     def self.december_solstice(year, ephem)
       new(year, DECEMBER_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param event [Integer] one of MARCH_EQUINOX, JUNE_SOLSTICE,
+    #   SEPTEMBER_EQUINOX, or DECEMBER_SOLSTICE
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @raise [Astronoby::UnsupportedEventError] if event is invalid
     def initialize(year, event, ephem)
       unless EVENTS.include?(event)
         raise UnsupportedEventError.new(
@@ -97,12 +115,13 @@ module Astronoby
       end
 
       @event = event
+      @ephem = ephem
       @year = (year.to_i - 2000) / 1000.0
       uncorrected_time = compute
       @instant = Instant.from_time(uncorrected_time)
-      @sun = Sun.new(ephem: ephem, instant: @instant)
     end
 
+    # @return [Time] the corrected UTC time of the event
     def time
       Instant.from_terrestrial_time(@instant.tt + corrected).to_time.round
     end
@@ -135,8 +154,12 @@ module Astronoby
         component[4] * @year**4
     end
 
+    def sun
+      @sun ||= Sun.new(ephem: @ephem, instant: @instant)
+    end
+
     def corrected
-      longitude = @sun.apparent.ecliptic.longitude
+      longitude = sun.apparent.ecliptic.longitude
       58 * Angle.from_degrees(@event * 90 - longitude.degrees).sin
     end
   end

data/lib/astronoby/errors.rb

@@ -1,11 +1,22 @@
 module Astronoby
+  # Raised when arguments are mutually incompatible.
   class IncompatibleArgumentsError < ArgumentError; end
 
+  # Raised when an unsupported format is requested.
   class UnsupportedFormatError < ArgumentError; end
 
+  # Raised when an unsupported event type is requested.
   class UnsupportedEventError < ArgumentError; end
 
+  # Raised when an astronomical calculation fails.
   class CalculationError < StandardError; end
 
+  # Raised when there is an error with ephemeris data.
   class EphemerisError < StandardError; end
+
+  # Raised when an orientation kernel is not a supported orientation source.
+  class OrientationError < StandardError; end
+
+  # Raised when an orientation kernel does not cover the requested instant.
+  class OrientationOutOfRangeError < StandardError; end
 end

data/lib/astronoby/events/conjunction.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Conjunction
+    INFERIOR = :inferior
+    SUPERIOR = :superior
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @return [Astronoby::Conjunction] an inferior conjunction
+    def self.inferior(instant:, body:)
+      new(instant: instant, body: body, subtype: INFERIOR)
+    end
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @return [Astronoby::Conjunction] a superior conjunction
+    def self.superior(instant:, body:)
+      new(instant: instant, body: body, subtype: SUPERIOR)
+    end
+
+    # @return [Astronoby::Instant] when the conjunction occurs
+    attr_reader :instant
+
+    # @return [Astronoby::Body] the body in conjunction with the Sun
+    attr_reader :body
+
+    # @return [Symbol] +INFERIOR+ or +SUPERIOR+
+    attr_reader :subtype
+
+    # @param instant [Astronoby::Instant] when the conjunction occurs
+    # @param body [Astronoby::Body] the body in conjunction with the Sun
+    # @param subtype [Symbol] +INFERIOR+ or +SUPERIOR+
+    def initialize(instant:, body:, subtype:)
+      @instant = instant
+      @body = body
+      @subtype = subtype
+      freeze
+    end
+
+    # @return [Boolean] true for an inferior conjunction
+    def inferior?
+      @subtype == INFERIOR
+    end
+
+    # @return [Boolean] true for a superior conjunction
+    def superior?
+      @subtype == SUPERIOR
+    end
+  end
+end

data/lib/astronoby/events/conjunction_opposition_calculator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class ConjunctionOppositionCalculator
+    # @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::Conjunction>] conjunctions in the range
+    def conjunction_events_between(start_time, end_time)
+      roots_between(start_time, end_time, accept: method(:conjunction?))
+        .map { |jd| conjunction_at(Instant.from_terrestrial_time(jd)) }
+    end
+
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @return [Array<Astronoby::Opposition>] oppositions in the range
+    def opposition_events_between(start_time, end_time)
+      roots_between(start_time, end_time, accept: method(:opposition?))
+        .map do |jd|
+          Opposition.new(
+            instant: Instant.from_terrestrial_time(jd),
+            body: @body
+          )
+        end
+    end
+
+    private
+
+    def roots_between(start_time, end_time, accept:)
+      finder.roots(
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
+        accept: accept
+      )
+    end
+
+    def finder
+      @finder ||= RootFinder.new(
+        value_at: ->(jd) { delta_longitude_at(jd).sin },
+        period: synodic_period,
+        samples_per_period: @samples_per_period
+      )
+    end
+
+    def conjunction?(jd)
+      delta_longitude_at(jd).cos.positive?
+    end
+
+    def opposition?(jd)
+      delta_longitude_at(jd).cos.negative?
+    end
+
+    def delta_longitude_at(jd)
+      instant = Instant.from_terrestrial_time(jd)
+      planet = @body.new(instant: instant, ephem: @ephem)
+      sun = Sun.new(instant: instant, ephem: @ephem)
+      planet.apparent.ecliptic.longitude - sun.apparent.ecliptic.longitude
+    end
+
+    def conjunction_at(instant)
+      planet = @body.new(instant: instant, ephem: @ephem)
+      sun = Sun.new(instant: instant, ephem: @ephem)
+
+      if planet.apparent.distance < sun.apparent.distance
+        Conjunction.inferior(instant: instant, body: @body)
+      else
+        Conjunction.superior(instant: instant, body: @body)
+      end
+    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/eclipse_phase.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # A bounded phase of an eclipse, delimited by its two boundary instants.
+  class EclipsePhase
+    # @return [Astronoby::Instant] when the phase begins
+    attr_reader :starting_instant
+
+    # @return [Astronoby::Instant] when the phase ends
+    attr_reader :ending_instant
+
+    # @param starting_instant [Astronoby::Instant] when the phase begins
+    # @param ending_instant [Astronoby::Instant] when the phase ends
+    def initialize(starting_instant:, ending_instant:)
+      @starting_instant = starting_instant
+      @ending_instant = ending_instant
+      freeze
+    end
+
+    # @return [Astronoby::Duration] phase duration
+    def duration
+      Duration.from_seconds(
+        (@ending_instant.to_time - @starting_instant.to_time).round
+      )
+    end
+  end
+end

data/lib/astronoby/events/extremum_calculator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class ExtremumCalculator
+    # @param body [Astronoby::SolarSystemBody] the celestial body to track
+    # @param primary_body [Astronoby::SolarSystemBody] the reference body
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param samples_per_period [Integer] number of samples per orbital period
+    def initialize(
+      body:,
+      primary_body:,
+      ephem:,
+      samples_per_period: 60
+    )
+      @body = body
+      @primary_body = primary_body
+      @ephem = ephem
+      @samples_per_period = samples_per_period
+    end
+
+    # Finds all apoapsis events between two times
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of apoapsis events
+    def apoapsis_events_between(start_time, end_time)
+      find_extrema(
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
+        type: :maximum
+      )
+    end
+
+    # Finds all periapsis events between two times
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of periapsis events
+    def periapsis_events_between(start_time, end_time)
+      find_extrema(
+        Instant.from_time(start_time).tt,
+        Instant.from_time(end_time).tt,
+        type: :minimum
+      )
+    end
+
+    # Finds extrema (minima or maxima) in the distance between bodies within
+    #   a time range
+    # @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<Astronoby::ExtremumEvent>] Array of extrema events
+    def find_extrema(start_jd, end_jd, type: :maximum)
+      finder.extrema(start_jd, end_jd, type: type).map do |extremum|
+        ExtremumEvent.new(
+          Instant.from_terrestrial_time(extremum[:jd]),
+          extremum[:value]
+        )
+      end
+    end
+
+    private
+
+    def finder
+      @finder ||= ExtremumFinder.new(
+        value_at: method(:distance_at),
+        period: @body::ORBITAL_PERIOD,
+        samples_per_period: @samples_per_period
+      )
+    end
+
+    def distance_at(jd)
+      instant = Instant.from_terrestrial_time(jd)
+      body_geometric = @body.geometric(ephem: @ephem, instant: instant)
+      primary_geometric = @primary_body
+        .geometric(ephem: @ephem, instant: instant)
+
+      distance_vector = body_geometric.position - primary_geometric.position
+      distance_vector.magnitude
+    end
+  end
+end

data/lib/astronoby/events/extremum_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Represents an extremum event with its timing and value
+  class ExtremumEvent
+    attr_reader :instant, :value
+
+    # @param instant [Astronoby::Instant] When the event occurs
+    # @param value [Object] The extreme value
+    def initialize(instant, value)
+      @instant = instant
+      @value = value
+    end
+  end
+end