astronoby 0.8.0 → 0.10.0

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

@@ -85,6 +85,7 @@ module Astronoby
     # @return [void]
     def max_size=(new_size)
       raise ArgumentError, "max_size must be positive" unless new_size > 0
+
       @mutex.synchronize do
         @max_size = new_size
         while @hash.size > @max_size

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

data/lib/astronoby/constants.rb

@@ -14,19 +14,24 @@ module Astronoby
 
     SECONDS_PER_MINUTE = 60.0
     MINUTES_PER_HOUR = 60.0
-    MINUTES_PER_DEGREE = 60.0
-
     SECONDS_PER_HOUR = SECONDS_PER_MINUTE * MINUTES_PER_HOUR
     SECONDS_PER_DAY = SECONDS_PER_HOUR * HOURS_PER_DAY
+    SECONDS_PER_JULIAN_YEAR = SECONDS_PER_DAY * DAYS_PER_JULIAN_YEAR
     RADIAN_PER_HOUR = Math::PI / 12.0
     MICROSECOND_IN_DAYS = 1.0 / SECONDS_PER_DAY / 1e6
 
+    ARCMINUTES_PER_DEGREE = 60.0
+    ARC_SECONDS_PER_ARCMINUTE = 60.0
+    ARCSECONDS_PER_DEGREE = ARC_SECONDS_PER_ARCMINUTE * ARCMINUTES_PER_DEGREE
+    MILLIARCSECONDS_PER_DEGREE = ARCSECONDS_PER_DEGREE * 1000
+
     PI_IN_DEGREES = 180.0
 
     EQUATION_OF_TIME_CONSTANT = 0.0057183
 
     KILOMETER_IN_METERS = 1_000
     ASTRONOMICAL_UNIT_IN_METERS = 149_597_870_700
+    PARSEC_IN_METERS = 3.0856775814913673e16
     EARTH_EQUATORIAL_RADIUS_IN_METERS = 6378140
 
     # WGS84 Earth Constants

data/lib/astronoby/constellation.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an IAU constellation with its full name and standard
+  # three-letter abbreviation.
   class Constellation
-    attr_reader :name, :abbreviation
+    # @return [String] the constellation name (e.g., "Orion")
+    attr_reader :name
 
+    # @return [String] the IAU three-letter abbreviation (e.g., "Ori")
+    attr_reader :abbreviation
+
+    # @param name [String] the constellation name
+    # @param abbreviation [String] the IAU abbreviation
     def initialize(name, abbreviation)
       @name = name
       @abbreviation = abbreviation

data/lib/astronoby/coordinates/ecliptic.rb

@@ -2,14 +2,23 @@
 
 module Astronoby
   module Coordinates
+    # Ecliptic coordinate system (latitude and longitude relative to the
+    # ecliptic plane).
     class Ecliptic
-      attr_reader :latitude, :longitude
+      # @return [Astronoby::Angle] ecliptic latitude
+      attr_reader :latitude
 
+      # @return [Astronoby::Angle] ecliptic longitude
+      attr_reader :longitude
+
+      # @param latitude [Astronoby::Angle] ecliptic latitude
+      # @param longitude [Astronoby::Angle] ecliptic longitude
       def initialize(latitude:, longitude:)
         @latitude = latitude
         @longitude = longitude
       end
 
+      # @return [Astronoby::Coordinates::Ecliptic] zero coordinates
       def self.zero
         new(latitude: Angle.zero, longitude: Angle.zero)
       end

data/lib/astronoby/coordinates/equatorial.rb

@@ -2,9 +2,24 @@
 
 module Astronoby
   module Coordinates
+    # Equatorial coordinate system (right ascension and declination).
     class Equatorial
-      attr_reader :declination, :right_ascension, :hour_angle, :epoch
+      # @return [Astronoby::Angle] declination
+      attr_reader :declination
 
+      # @return [Astronoby::Angle] right ascension
+      attr_reader :right_ascension
+
+      # @return [Astronoby::Angle, nil] hour angle, if set
+      attr_reader :hour_angle
+
+      # @return [Numeric] the Julian Date epoch
+      attr_reader :epoch
+
+      # @param declination [Astronoby::Angle] declination
+      # @param right_ascension [Astronoby::Angle] right ascension
+      # @param hour_angle [Astronoby::Angle, nil] hour angle
+      # @param epoch [Numeric] Julian Date epoch (default: J2000.0 = 2451545.0)
       def initialize(
         declination:,
         right_ascension:,
@@ -17,10 +32,15 @@ module Astronoby
         @epoch = epoch
       end
 
+      # @return [Astronoby::Coordinates::Equatorial] zero coordinates
       def self.zero
         new(declination: Angle.zero, right_ascension: Angle.zero)
       end
 
+      # Derives equatorial coordinates from a position vector.
+      #
+      # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+      # @return [Astronoby::Coordinates::Equatorial] equatorial coordinates
       def self.from_position_vector(position)
         return zero if position.zero?
 
@@ -41,17 +61,24 @@ module Astronoby
         new(declination: declination, right_ascension: right_ascension)
       end
 
+      # Computes the hour angle for a given time and observer longitude.
+      #
+      # @param time [Time] the UTC time
+      # @param longitude [Astronoby::Angle] the observer's longitude
+      # @return [Astronoby::Angle] the hour angle
       def compute_hour_angle(time:, longitude:)
-        lst = GreenwichSiderealTime
-          .from_utc(time.utc)
-          .to_lst(longitude: longitude)
-
-        ha = (lst.time - @right_ascension.hours)
+        last = LocalApparentSiderealTime.from_utc(time.utc, longitude: longitude)
+        ha = (last.time - @right_ascension.hours)
         ha += Constants::HOURS_PER_DAY if ha.negative?
 
         Angle.from_hours(ha)
       end
 
+      # Converts to horizontal coordinates for a given observer and time.
+      #
+      # @param time [Time] the UTC time
+      # @param observer [Astronoby::Observer] the observer
+      # @return [Astronoby::Coordinates::Horizontal] horizontal coordinates
       def to_horizontal(time:, observer:)
         latitude = observer.latitude
         longitude = observer.longitude
@@ -77,25 +104,32 @@ module Astronoby
         )
       end
 
+      # Converts to ecliptic coordinates.
+      #
       # Source:
       #  Title: Celestial Calculations
       #  Author: J. L. Lawrence
       #  Edition: MIT Press
       #  Chapter: 4 - Orbits and Coordinate Systems
-      def to_ecliptic(instant:)
-        mean_obliquity = MeanObliquity.at(instant)
-
+      #
+      # @param instant [Astronoby::Instant] the time instant for the obliquity
+      # @param obliquity [Astronoby::Angle] the obliquity of the ecliptic to
+      #   rotate by. Defaults to the mean obliquity of date; pass the true
+      #   obliquity when the equatorial coordinates already include nutation
+      #   (true-of-date apparent and topocentric places).
+      # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates
+      def to_ecliptic(instant:, obliquity: MeanObliquity.at(instant))
         y = Angle.from_radians(
-          @right_ascension.sin * mean_obliquity.cos +
-          @declination.tan * mean_obliquity.sin
+          @right_ascension.sin * obliquity.cos +
+          @declination.tan * obliquity.sin
         )
         x = Angle.from_radians(@right_ascension.cos)
         r = Angle.atan(y.radians / x.radians)
         longitude = Util::Trigonometry.adjustement_for_arctangent(y, x, r)
 
         latitude = Angle.asin(
-          @declination.sin * mean_obliquity.cos -
-          @declination.cos * mean_obliquity.sin * @right_ascension.sin
+          @declination.sin * obliquity.cos -
+          @declination.cos * obliquity.sin * @right_ascension.sin
         )
 
         Ecliptic.new(
@@ -103,6 +137,25 @@ module Astronoby
           longitude: longitude
         )
       end
+
+      # Position angle of another point as seen from this one, measured
+      # eastward (counterclockwise) from the direction of the north celestial
+      # pole. Both points must be expressed in the same frame.
+      #
+      # @param other [Astronoby::Coordinates::Equatorial] the target point
+      # @return [Astronoby::Angle] position angle, between -180 and 180 degrees
+      def position_angle_to(other)
+        delta_right_ascension = other.right_ascension - @right_ascension
+
+        Angle.from_radians(
+          Math.atan2(
+            other.declination.cos * delta_right_ascension.sin,
+            other.declination.sin * @declination.cos -
+              other.declination.cos * @declination.sin *
+                delta_right_ascension.cos
+          )
+        )
+      end
     end
   end
 end

data/lib/astronoby/coordinates/geodetic.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Astronoby
+  module Coordinates
+    # Geodetic coordinate system (WGS-84 latitude, longitude, and elevation).
+    #
+    # Geodetic coordinates describe a position on or above the Earth's surface
+    # using the WGS-84 reference ellipsoid, the same system used by GPS.
+    #
+    # The reverse conversion from ECEF (Earth-Centered Earth-Fixed) Cartesian
+    # coordinates uses Bowring's iterative method, which converges in 2-3
+    # iterations for typical satellite altitudes.
+    class Geodetic
+      SEMI_MINOR_AXIS =
+        Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS *
+        (1 - Constants::WGS84_FLATTENING)
+      SECOND_ECCENTRICITY_SQUARED =
+        (Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS**2 -
+          SEMI_MINOR_AXIS**2) /
+        SEMI_MINOR_AXIS**2
+      MAX_ITERATIONS = 10
+      CONVERGENCE_THRESHOLD = 1e-12
+
+      # @return [Astronoby::Angle] geodetic latitude
+      attr_reader :latitude
+
+      # @return [Astronoby::Angle] geodetic longitude
+      attr_reader :longitude
+
+      # @return [Astronoby::Distance] elevation above the WGS-84 ellipsoid
+      attr_reader :elevation
+
+      # @param latitude [Astronoby::Angle] geodetic latitude
+      # @param longitude [Astronoby::Angle] geodetic longitude
+      # @param elevation [Astronoby::Distance] elevation above the WGS-84
+      #   ellipsoid
+      def initialize(latitude:, longitude:, elevation:)
+        @latitude = latitude
+        @longitude = longitude
+        @elevation = elevation
+      end
+
+      # Converts ECEF Cartesian coordinates to geodetic coordinates using
+      # Bowring's iterative method.
+      #
+      # Source:
+      #  Title: Transformation from Spatial to Geographical Coordinates
+      #  Author: B. R. Bowring
+      #  Edition: Survey Review, Vol. 23, No. 181, 1976
+      #
+      # @param position [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      # @return [Astronoby::Coordinates::Geodetic] geodetic coordinates
+      def self.from_ecef(position)
+        x = position.x.m
+        y = position.y.m
+        z = position.z.m
+
+        a = Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS
+        e2 = Constants::WGS84_ECCENTICITY_SQUARED
+
+        p = Math.sqrt(x * x + y * y)
+        longitude = Math.atan2(y, x)
+
+        theta = Math.atan2(z * a, p * SEMI_MINOR_AXIS)
+        latitude = Math.atan2(
+          z + SECOND_ECCENTRICITY_SQUARED * SEMI_MINOR_AXIS *
+            Math.sin(theta)**3,
+          p - e2 * a * Math.cos(theta)**3
+        )
+
+        MAX_ITERATIONS.times do
+          prev_latitude = latitude
+          theta = Math.atan2(
+            (1 - Constants::WGS84_FLATTENING) * Math.sin(latitude),
+            Math.cos(latitude)
+          )
+          latitude = Math.atan2(
+            z + SECOND_ECCENTRICITY_SQUARED * SEMI_MINOR_AXIS *
+              Math.sin(theta)**3,
+            p - e2 * a * Math.cos(theta)**3
+          )
+          break if (latitude - prev_latitude).abs < CONVERGENCE_THRESHOLD
+        end
+
+        sin_lat = Math.sin(latitude)
+        n = a / Math.sqrt(1 - e2 * sin_lat * sin_lat)
+
+        elevation = if Math.cos(latitude).abs > 1e-10
+          p / Math.cos(latitude) - n
+        else
+          z / sin_lat - n * (1 - e2)
+        end
+
+        new(
+          latitude: Angle.from_radians(latitude),
+          longitude: Angle.from_radians(longitude),
+          elevation: Distance.from_meters(elevation)
+        )
+      end
+    end
+  end
+end

data/lib/astronoby/coordinates/horizontal.rb

@@ -2,9 +2,21 @@
 
 module Astronoby
   module Coordinates
+    # Horizontal coordinate system (azimuth and altitude) for a specific
+    # observer.
     class Horizontal
-      attr_reader :azimuth, :altitude, :observer
+      # @return [Astronoby::Angle] azimuth (measured from north, clockwise)
+      attr_reader :azimuth
 
+      # @return [Astronoby::Angle] altitude above the horizon
+      attr_reader :altitude
+
+      # @return [Astronoby::Observer] the observer
+      attr_reader :observer
+
+      # @param azimuth [Astronoby::Angle] azimuth
+      # @param altitude [Astronoby::Angle] altitude
+      # @param observer [Astronoby::Observer] the observer
       def initialize(
         azimuth:,
         altitude:,