astronoby 0.9.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/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/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,6 +61,11 @@ 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:)
         last = LocalApparentSiderealTime.from_utc(time.utc, longitude: longitude)
         ha = (last.time - @right_ascension.hours)
@@ -49,6 +74,11 @@ module Astronoby
         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
@@ -74,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(
@@ -100,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:,

data/lib/astronoby/distance.rb

@@ -1,93 +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)