astronoby 0.9.0 → 0.11.0

data/lib/astronoby/bodies/solar_system_body.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Base class for solar system bodies. Provides the reference frame chain
+  # (geometric -> astrometric -> mean-of-date -> apparent -> topocentric)
+  # and common observational properties (phase angle, magnitude, etc.).
   class SolarSystemBody
+    include Position
+    extend Body
+
     SOLAR_SYSTEM_BARYCENTER = 0
     SUN = 10
     MERCURY_BARYCENTER = 1
@@ -17,16 +23,37 @@ module Astronoby
     URANUS_BARYCENTER = 7
     NEPTUNE_BARYCENTER = 8
 
-    attr_reader :geometric, :instant
+    # @return [Astronoby::Instant] the time instant
+    attr_reader :instant
+
+    # @return [::Ephem::SPK] the ephemeris data source
+    attr_reader :ephem
 
-    def self.at(instant, ephem:)
-      new(ephem: ephem, instant: instant)
+    # @return [Astronoby::Orientation, nil] the orientation kernel, if provided
+    attr_reader :orientation
+
+    # Creates a new body instance at the given instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param orientation [Astronoby::Orientation, nil] orientation kernel
+    # @return [Astronoby::SolarSystemBody] a new body instance
+    def self.at(instant, ephem:, orientation: nil)
+      new(ephem: ephem, instant: instant, orientation: orientation)
     end
 
+    # Computes the geometric reference frame for this body.
+    #
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Astronoby::Geometric] the geometric frame
     def self.geometric(ephem:, instant:)
       compute_geometric(ephem: ephem, instant: instant)
     end
 
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Astronoby::Geometric] the geometric frame
     def self.compute_geometric(ephem:, instant:)
       segments = ephemeris_segments(ephem.type)
       segment1 = segments[0]
@@ -66,63 +93,196 @@ module Astronoby
       end
     end
 
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
+    # @raise [NotImplementedError] must be implemented by subclasses
     def self.ephemeris_segments(_ephem_source)
       raise NotImplementedError
     end
 
+    # @return [Float, nil] absolute magnitude of the body
     def self.absolute_magnitude
       nil
     end
 
-    def initialize(ephem:, instant:)
+    # @return [Boolean] true for an inferior planet (Mercury, Venus)
+    def self.inferior_planet?
+      false
+    end
+
+    # @return [Boolean] true for a superior planet (Mars through Neptune)
+    def self.superior_planet?
+      false
+    end
+
+    # @return [Boolean] true for a planet (excludes the Sun, Earth and Moon)
+    def self.planet?
+      inferior_planet? || superior_planet?
+    end
+
+    # @param observer [Astronoby::Observer] Observer for whom to calculate rise,
+    #   transit, and set events
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param date [Date] Date for which to calculate rise, transit, and set
+    #   events (optional)
+    # @param start_time [Time] Start time for rise, transit, and set event
+    #   calculation (optional)
+    # @param end_time [Time] End time for rise, transit, and set event
+    #   calculation (optional)
+    # @param utc_offset [String] UTC offset for the given date (e.g., "+02:00")
+    # @return [Astronoby::RiseTransitSetEvent,
+    #   Array<Astronoby::RiseTransitSetEvent>] Rise, transit, and set events for
+    #   the given date or time range.
+    def self.rise_transit_set_events(
+      observer:,
+      ephem:,
+      date: nil,
+      start_time: nil,
+      end_time: nil,
+      utc_offset: 0
+    )
+      calculator = RiseTransitSetCalculator.new(
+        body: self,
+        observer: observer,
+        ephem: ephem
+      )
+      if date
+        calculator.events_on(date, utc_offset: utc_offset)
+      else
+        calculator.events_between(start_time, end_time)
+      end
+    end
+
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @param samples_per_period [Integer] number of samples per synodic period
+    # @return [Array<Astronoby::Conjunction>] conjunctions with the Sun
+    # @raise [Astronoby::UnsupportedEventError] unless the body is a planet
+    def self.conjunction_events(
+      ephem:,
+      start_time:,
+      end_time:,
+      samples_per_period: 60
+    )
+      unless planet?
+        raise UnsupportedEventError, "#{self} has no conjunctions with the Sun"
+      end
+
+      ConjunctionOppositionCalculator.new(
+        body: self,
+        ephem: ephem,
+        samples_per_period: samples_per_period
+      ).conjunction_events_between(start_time, end_time)
+    end
+
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @param samples_per_period [Integer] number of samples per synodic period
+    # @return [Array<Astronoby::Opposition>] oppositions with the Sun
+    # @raise [Astronoby::UnsupportedEventError] unless the body is a superior
+    #   planet
+    def self.opposition_events(
+      ephem:,
+      start_time:,
+      end_time:,
+      samples_per_period: 60
+    )
+      unless superior_planet?
+        raise UnsupportedEventError, "#{self} has no oppositions with the Sun"
+      end
+
+      ConjunctionOppositionCalculator.new(
+        body: self,
+        ephem: ephem,
+        samples_per_period: samples_per_period
+      ).opposition_events_between(start_time, end_time)
+    end
+
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @param start_time [Time] start time
+    # @param end_time [Time] end time
+    # @param samples_per_period [Integer] number of samples per synodic period
+    # @return [Array<Astronoby::GreatestElongation>] greatest elongations
+    # @raise [Astronoby::UnsupportedEventError] unless the body is an inferior
+    #   planet
+    def self.greatest_elongation_events(
+      ephem:,
+      start_time:,
+      end_time:,
+      samples_per_period: 60
+    )
+      unless inferior_planet?
+        raise UnsupportedEventError,
+          "#{self} has no greatest elongations from the Sun"
+      end
+
+      GreatestElongationCalculator.new(
+        body: self,
+        ephem: ephem,
+        samples_per_period: samples_per_period
+      ).greatest_elongation_events_between(start_time, end_time)
+    end
+
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param instant [Astronoby::Instant] Instant for which to calculate the
+    #   phase angle
+    # @param orientation [Astronoby::Orientation, nil] Orientation kernel,
+    #   enabling arcsecond-accurate lunar libration and axis position angle
+    def initialize(ephem:, instant:, orientation: nil)
+      @ephem = ephem
       @instant = instant
-      @geometric = compute_geometric(ephem)
-      @earth_geometric = Earth.geometric(ephem: ephem, instant: instant)
-      @light_time_corrected_position,
-        @light_time_corrected_velocity =
-        Correction::LightTimeDelay.compute(
-          center: @earth_geometric,
-          target: @geometric,
-          ephem: ephem
-        )
-      compute_sun(ephem) if requires_sun_data?
+      @orientation = orientation
+    end
+
+    # @return [Astronoby::Geometric] the geometric reference frame (BCRS)
+    def geometric
+      @geometric ||= self.class.compute_geometric(
+        ephem: @ephem,
+        instant: @instant
+      )
+    end
+
+    # @return [Astronoby::Geometric] Earth's geometric reference frame
+    def earth_geometric
+      @earth_geometric ||= Earth.geometric(ephem: @ephem, instant: @instant)
     end
 
+    # @return [Astronoby::Astrometric] the astrometric reference frame (GCRS)
     def astrometric
       @astrometric ||= Astrometric.build_from_geometric(
         instant: @instant,
-        earth_geometric: @earth_geometric,
-        light_time_corrected_position: @light_time_corrected_position,
-        light_time_corrected_velocity: @light_time_corrected_velocity,
-        target_body: self
+        earth_geometric: earth_geometric,
+        light_time_corrected_position: light_time_corrected_position,
+        light_time_corrected_velocity: light_time_corrected_velocity,
+        target_body: body
       )
     end
 
+    # @return [Astronoby::MeanOfDate] the mean-of-date reference frame
     def mean_of_date
       @mean_of_date ||= MeanOfDate.build_from_geometric(
         instant: @instant,
-        target_geometric: @geometric,
-        earth_geometric: @earth_geometric,
-        target_body: self
+        target_geometric: geometric,
+        earth_geometric: earth_geometric,
+        target_body: body
       )
     end
 
+    # @return [Astronoby::Apparent] the apparent reference frame
     def apparent
       @apparent ||= Apparent.build_from_astrometric(
         instant: @instant,
         target_astrometric: astrometric,
-        earth_geometric: @earth_geometric,
-        target_body: self
+        earth_geometric: earth_geometric,
+        target_body: body
       )
     end
 
-    def observed_by(observer)
-      Topocentric.build_from_apparent(
-        apparent: apparent,
-        observer: observer,
-        instant: @instant,
-        target_body: self
-      )
+    # @return [Astronoby::Body] the body definition (the class itself)
+    def body
+      self.class
     end
 
     # Returns the constellation of the body
@@ -136,6 +296,25 @@ module Astronoby
       )
     end
 
+    # Apparent geocentric Sun-Earth-body angle
+    # @return [Astronoby::Angle, nil] Elongation of the body
+    def elongation
+      return unless sun
+
+      @elongation ||= sun.apparent.separation_from(apparent)
+    end
+
+    # @return [Boolean] true when the body is east of the Sun
+    def eastern?
+      (apparent.ecliptic.longitude - sun.apparent.ecliptic.longitude)
+        .sin.positive?
+    end
+
+    # @return [Boolean] true when the body is west of the Sun
+    def western?
+      !eastern?
+    end
+
     # Source:
     #  Title: Astronomical Algorithms
     #  Author: Jean Meeus
@@ -143,23 +322,12 @@ module Astronoby
     #  Chapter: 48 - Illuminated Fraction of the Moon's Disk
     # @return [Astronoby::Angle, nil] Phase angle of the body
     def phase_angle
-      return unless @sun
+      return unless sun
 
       @phase_angle ||= begin
-        geocentric_elongation = Angle.acos(
-          @sun.apparent.equatorial.declination.sin *
-          apparent.equatorial.declination.sin +
-          @sun.apparent.equatorial.declination.cos *
-          apparent.equatorial.declination.cos *
-          (
-            @sun.apparent.equatorial.right_ascension -
-              apparent.equatorial.right_ascension
-          ).cos
-        )
-
-        term1 = @sun.astrometric.distance.km * geocentric_elongation.sin
+        term1 = sun.astrometric.distance.km * elongation.sin
         term2 = astrometric.distance.km -
-          @sun.astrometric.distance.km * geocentric_elongation.cos
+          sun.astrometric.distance.km * elongation.cos
         angle = Angle.atan(term1 / term2)
         Astronoby::Util::Trigonometry
           .adjustement_for_arctangent(term1, term2, angle)
@@ -186,7 +354,7 @@ module Astronoby
 
       @apparent_magnitude ||= begin
         body_sun_distance =
-          (astrometric.position - @sun.astrometric.position).magnitude
+          (astrometric.position - sun.astrometric.position).magnitude
         self.class.absolute_magnitude +
           5 * Math.log10(body_sun_distance.au * astrometric.distance.au) +
           magnitude_correction_term
@@ -206,13 +374,13 @@ module Astronoby
       end
     end
 
-    # @return [Boolean] True if the body is approaching the primary
-    #   body (Sun), false otherwise.
+    # @return [Boolean] True if the body is approaching its primary
+    #   body, false otherwise.
     def approaching_primary?
       relative_position =
-        (geometric.position - @sun.geometric.position).map(&:m)
+        (geometric.position - primary_body_geometric.position).map(&:m)
       relative_velocity =
-        (geometric.velocity - @sun.geometric.velocity).map(&:mps)
+        (geometric.velocity - primary_body_geometric.velocity).map(&:mps)
       radial_velocity_component = Astronoby::Util::Maths
         .dot_product(relative_position, relative_velocity)
       distance = Math.sqrt(
@@ -221,28 +389,39 @@ module Astronoby
       radial_velocity_component / distance < 0
     end
 
-    # @return [Boolean] True if the body is receding from the primary
-    #   body (Sun), false otherwise.
+    # @return [Boolean] True if the body is receding from its primary
+    #   body, false otherwise.
     def receding_from_primary?
       !approaching_primary?
     end
 
     private
 
-    # By default, Solar System bodies expose attributes that are dependent on
-    # the Sun's position, such as phase angle and illuminated fraction.
-    # If a body does not require Sun data, it should override this method to
-    # return false.
-    def requires_sun_data?
-      true
+    def sun
+      @sun ||= Sun.new(instant: @instant, ephem: @ephem)
     end
 
-    def compute_geometric(ephem)
-      self.class.compute_geometric(ephem: ephem, instant: @instant)
+    def primary_body_geometric
+      sun.geometric
     end
 
-    def compute_sun(ephem)
-      @sun ||= Sun.new(instant: @instant, ephem: ephem)
+    def light_time_corrected_position
+      compute_light_time_correction unless @light_time_corrected_position
+      @light_time_corrected_position
+    end
+
+    def light_time_corrected_velocity
+      compute_light_time_correction unless @light_time_corrected_velocity
+      @light_time_corrected_velocity
+    end
+
+    def compute_light_time_correction
+      @light_time_corrected_position, @light_time_corrected_velocity =
+        Correction::LightTimeDelay.compute(
+          center: earth_geometric,
+          target: geometric,
+          ephem: @ephem
+        )
     end
 
     # Source:

data/lib/astronoby/bodies/sun.rb

@@ -1,18 +1,77 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the Sun. Provides twilight events, equinox/solstice
+  # calculations, and equation of time.
   class Sun < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(695_700_000)
     ABSOLUTE_MAGNITUDE = -26.74
 
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, SUN]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end
 
+    # @param observer [Astronoby::Observer] Observer for whom to calculate
+    #   twilight events
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param date [Date] Date for which to calculate twilight events (optional)
+    # @param start_time [Time] Start time for twilight event calculation
+    #   (optional)
+    # @param end_time [Time] End time for twilight event calculation (optional)
+    # @param utc_offset [String] UTC offset for the given date (e.g., "+02:00")
+    # @return [Astronoby::TwilightEvent, Array<Astronoby::TwilightEvent>]
+    #   Twilight events for the given date or time range.
+    def self.twilight_events(
+      observer:,
+      ephem:,
+      date: nil,
+      start_time: nil,
+      end_time: nil,
+      utc_offset: 0
+    )
+      calculator = TwilightCalculator.new(observer: observer, ephem: ephem)
+      if date
+        calculator.event_on(date, utc_offset: utc_offset)
+      else
+        calculator.events_between(start_time, end_time)
+      end
+    end
+
+    # @param year [Integer] Year for which to calculate equinoxes and solstices
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @return [Time] Time of the March equinox for the given year.
+    def self.march_equinox(year, ephem:)
+      EquinoxSolstice.march_equinox(year, ephem)
+    end
+
+    # @param year [Integer] Year for which to calculate equinoxes and solstices
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @return [Time] Time of the June solstice for the given year.
+    def self.june_solstice(year, ephem:)
+      EquinoxSolstice.june_solstice(year, ephem)
+    end
+
+    # @param year [Integer] Year for which to calculate equinoxes and solstices
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @return [Time] Time of the September equinox for the given year.
+    def self.september_equinox(year, ephem:)
+      EquinoxSolstice.september_equinox(year, ephem)
+    end
+
+    # @param year [Integer] Year for which to calculate equinoxes and solstices
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @return [Time] Time of the December solstice for the given year.
+    def self.december_solstice(year, ephem:)
+      EquinoxSolstice.december_solstice(year, ephem)
+    end
+
     # Source:
     #  Title: Explanatory Supplement to the Astronomical Almanac
     #  Authors: Sean E. Urban and P. Kenneth Seidelmann
@@ -31,7 +90,7 @@ module Astronoby
     #  Edition: 2nd edition
     #  Chapter: 28 - Equation of Time
 
-    # @return [Integer] Equation of time in seconds
+    # @return [Astronoby::Duration] Equation of time
     def equation_of_time
       right_ascension = apparent.equatorial.right_ascension
       t = (@instant.julian_date - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_MILLENIA
@@ -44,7 +103,7 @@ module Astronoby
       nutation = Nutation.new(instant: instant).nutation_in_longitude
       obliquity = TrueObliquity.at(@instant)
 
-      (
+      seconds = (
         Angle
           .from_degrees(
             l0 -
@@ -53,12 +112,28 @@ module Astronoby
               nutation.degrees * obliquity.cos
           ).hours * Constants::SECONDS_PER_HOUR
       ).round
+      Duration.from_seconds(seconds)
     end
 
-    private
+    # @return [nil] the Sun has no phase angle as seen from Earth
+    def phase_angle
+      nil
+    end
+
+    # @return [Boolean] always false; the Sun has no primary body
+    def approaching_primary?
+      false
+    end
 
-    def requires_sun_data?
+    # @return [Boolean] always false; the Sun has no primary body
+    def receding_from_primary?
       false
     end
+
+    private
+
+    def primary_body_geometric
+      nil
+    end
   end
 end

data/lib/astronoby/bodies/uranus.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Uranus.
   class Uranus < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(25_559_000)
     ABSOLUTE_MAGNITUDE = -7.11
+    ORBITAL_PERIOD = 30688.5
 
+    # @return [Boolean] true; Uranus is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, URANUS_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/venus.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Venus.
   class Venus < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(6_051_800)
     ABSOLUTE_MAGNITUDE = -4.384
+    ORBITAL_PERIOD = 224.701
 
+    # @return [Boolean] true; Venus is an inferior planet
+    def self.inferior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, VENUS_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/body.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Astronoby
+  module Body
+  end
+end

data/lib/astronoby/cache.rb

@@ -175,6 +175,19 @@ module Astronoby
         [type, rounded_tt, *components]
       end
 
+      # Generate a cache key for a UTC time, without rounding. Sidereal time
+      # moves by about 15 arcseconds per second, so unlike nutation it can't
+      # share an entry with a nearby instant.
+      # @param type [Symbol] The calculation type (e.g., :gmst)
+      # @param utc [Time] The UTC time
+      # @param components [Array] Additional components for the key
+      # @return [Array, nil] The complete cache key, nil if cache is disabled
+      def generate_for_utc(type, utc, *components)
+        return nil unless Astronoby.configuration.cache_enabled?
+
+        [type, utc.to_r, *components]
+      end
+
       # Round terrestrial time to specified precision
       # @param tt [Numeric] Terrestrial time value
       # @param precision [Numeric] Precision in seconds

data/lib/astronoby/center.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Center
+    BARYCENTRIC = :barycentric
+    GEOCENTRIC = :geocentric
+    TOPOCENTRIC = :topocentric
+
+    class << self
+      # @return [Astronoby::Center] the Solar System barycenter
+      def barycentric
+        @barycentric ||= new(kind: BARYCENTRIC)
+      end
+
+      # @return [Astronoby::Center] the Earth's center
+      def geocentric
+        @geocentric ||= new(kind: GEOCENTRIC)
+      end
+
+      # @param observer [Astronoby::Observer] the observer
+      # @return [Astronoby::Center] a center at the observer's location
+      def topocentric(observer)
+        new(kind: TOPOCENTRIC, observer: observer)
+      end
+    end
+
+    # @return [Symbol] the kind of center
+    attr_reader :kind
+
+    # @return [Astronoby::Observer, nil] the observer, for topocentric centers
+    attr_reader :observer
+
+    # @param kind [Symbol] one of BARYCENTRIC, GEOCENTRIC, TOPOCENTRIC
+    # @param observer [Astronoby::Observer, nil] the observer, for topocentric
+    def initialize(kind:, observer: nil)
+      @kind = kind
+      @observer = observer
+      freeze
+    end
+
+    # @return [Boolean] true if the center is the Solar System barycenter
+    def barycentric?
+      @kind == BARYCENTRIC
+    end
+
+    # @return [Boolean] true if the center is the Earth's center
+    def geocentric?
+      @kind == GEOCENTRIC
+    end
+
+    # @return [Boolean] true if the center is at an observer's location
+    def topocentric?
+      @kind == TOPOCENTRIC
+    end
+
+    # @return [Boolean] true if the center depends on a specific observer
+    def observer_dependent?
+      topocentric?
+    end
+
+    # @param other [Astronoby::Center] center to compare with
+    # @return [Boolean] true if both centers are equivalent
+    def ==(other)
+      other.is_a?(self.class) &&
+        kind == other.kind &&
+        location_key == other.location_key
+    end
+    alias_method :eql?, :==
+
+    # @return [Integer] hash value
+    def hash
+      [self.class, @kind, location_key].hash
+    end
+
+    protected
+
+    # @return [Array, nil] the geometric location key, or nil if not topocentric
+    def location_key
+      return unless @observer
+
+      [@observer.latitude, @observer.longitude, @observer.elevation]
+    end
+  end
+end