astronoby 0.8.0 → 0.10.0

data/lib/astronoby/angle.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle with radians as its internal representation.
+  # Provides conversions between radians, degrees, hours, and sexagesimal
+  # formats (DMS and HMS), as well as trigonometric operations.
+  #
+  # @example Create an angle from degrees
+  #   angle = Astronoby::Angle.from_degrees(180)
+  #   angle.radians  # => Math::PI
+  #
+  # @example Create an angle from hours, minutes, seconds
+  #   angle = Astronoby::Angle.from_hms(12, 30, 0)
+  #
   class Angle
     include Comparable
 
@@ -8,29 +19,42 @@ module Astronoby
     FORMATS = %i[dms hms].freeze
 
     class << self
+      # @return [Astronoby::Angle] a zero angle
       def zero
         new(0)
       end
 
+      # @param radians [Numeric] the angle in radians
+      # @return [Astronoby::Angle] a new Angle, normalized to (-2π, 2π)
       def from_radians(radians)
         normalized_radians = radians.remainder(Constants::RADIANS_PER_CIRCLE)
         new(normalized_radians)
       end
 
+      # @param degrees [Numeric] the angle in degrees
+      # @return [Astronoby::Angle] a new Angle
       def from_degrees(degrees)
         radians = degrees / Constants::PI_IN_DEGREES * Math::PI
         from_radians(radians)
       end
 
+      # @param arcseconds [Numeric] the angle in arcseconds
+      # @return [Astronoby::Angle] a new Angle
       def from_degree_arcseconds(arcseconds)
         from_dms(0, 0, arcseconds)
       end
 
+      # @param hours [Numeric] the angle in hour-angle hours
+      # @return [Astronoby::Angle] a new Angle
       def from_hours(hours)
         radians = hours * Constants::RADIAN_PER_HOUR
         from_radians(radians)
       end
 
+      # @param hour [Numeric] hours component
+      # @param minute [Numeric] minutes component
+      # @param second [Numeric] seconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_hms(hour, minute, second)
         hours = hour +
           minute / Constants::MINUTES_PER_HOUR +
@@ -38,85 +62,118 @@ module Astronoby
         from_hours(hours)
       end
 
+      # @param degree [Numeric] degrees component (sign determines overall sign)
+      # @param minute [Numeric] arcminutes component
+      # @param second [Numeric] arcseconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_dms(degree, minute, second)
         sign = degree.negative? ? -1 : 1
         degrees = degree.abs +
-          minute / Constants::MINUTES_PER_HOUR +
-          second / Constants::SECONDS_PER_HOUR
+          minute / Constants::ARCMINUTES_PER_DEGREE +
+          second / Constants::ARCSECONDS_PER_DEGREE
         from_degrees(sign * degrees)
       end
 
+      # @param ratio [Numeric] the sine value (-1..1)
+      # @return [Astronoby::Angle] the arcsine
       def asin(ratio)
         radians = Math.asin(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the cosine value (-1..1)
+      # @return [Astronoby::Angle] the arccosine
       def acos(ratio)
         radians = Math.acos(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the tangent value
+      # @return [Astronoby::Angle] the arctangent
       def atan(ratio)
         radians = Math.atan(ratio)
         from_radians(radians)
       end
     end
 
+    # @return [Numeric] the angle in radians
     attr_reader :radians
 
+    # @param radians [Numeric] the angle in radians
     def initialize(radians)
       @radians = radians
       freeze
     end
 
+    # @return [Float] the angle in degrees
     def degrees
       @radians * Constants::PI_IN_DEGREES / Math::PI
     end
 
+    # @return [Float] the angle in milliarcseconds
+    def degree_milliarcseconds
+      degrees * Constants::MILLIARCSECONDS_PER_DEGREE
+    end
+
+    # @return [Float] the angle in hour-angle hours
     def hours
       @radians / Constants::RADIAN_PER_HOUR
     end
 
+    # @param other [Astronoby::Angle] angle to add
+    # @return [Astronoby::Angle] the sum
     def +(other)
       self.class.from_radians(radians + other.radians)
     end
 
+    # @param other [Astronoby::Angle] angle to subtract
+    # @return [Astronoby::Angle] the difference
     def -(other)
       self.class.from_radians(@radians - other.radians)
     end
 
+    # @return [Astronoby::Angle] the negated angle
     def -@
       self.class.from_radians(-@radians)
     end
 
+    # @return [Float] the sine of the angle
     def sin
       Math.sin(radians)
     end
 
+    # @return [Float] the cosine of the angle
     def cos
       Math.cos(radians)
     end
 
+    # @return [Float] the tangent of the angle
     def tan
       Math.tan(radians)
     end
 
+    # @return [Boolean] true if the angle is positive
     def positive?
       radians > 0
     end
 
+    # @return [Boolean] true if the angle is negative
     def negative?
       radians < 0
     end
 
+    # @return [Boolean] true if the angle is zero
     def zero?
       radians.zero?
     end
 
+    # @return [Integer] hash value
     def hash
       [radians, self.class].hash
     end
 
+    # @param other [Astronoby::Angle] angle to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 
@@ -124,6 +181,12 @@ module Astronoby
     end
     alias_method :eql?, :==
 
+    # Formats the angle as a string in the given format.
+    #
+    # @param format [Symbol] :dms or :hms
+    # @param precision [Integer] decimal places for seconds
+    # @return [String] the formatted angle
+    # @raise [Astronoby::UnsupportedFormatError] if format is not :dms or :hms
     def str(format, precision: 4)
       case format
       when :dms then to_dms.format(precision: precision)
@@ -135,14 +198,15 @@ module Astronoby
       end
     end
 
+    # @return [Astronoby::Dms] the angle in degrees, arcminutes, arcseconds
     def to_dms
       sign = degrees.negative? ? "-" : "+"
       absolute_degrees = degrees.abs
       deg = absolute_degrees.floor
-      decimal_minutes = Constants::MINUTES_PER_DEGREE *
+      decimal_minutes = Constants::ARCMINUTES_PER_DEGREE *
         (absolute_degrees - deg)
       absolute_decimal_minutes = (
-        Constants::MINUTES_PER_DEGREE * (absolute_degrees - deg)
+        Constants::ARCMINUTES_PER_DEGREE * (absolute_degrees - deg)
       ).abs
       minutes = decimal_minutes.floor
       seconds = Constants::SECONDS_PER_MINUTE * (
@@ -152,6 +216,7 @@ module Astronoby
       Dms.new(sign, deg, minutes, seconds)
     end
 
+    # @return [Astronoby::Hms] the angle in hours, minutes, seconds
     def to_hms
       absolute_hours = hours.abs
       hrs = absolute_hours.floor

data/lib/astronoby/angles/dms.rb

@@ -1,9 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in degrees, arcminutes, arcseconds (DMS) notation.
   class Dms
-    attr_reader :sign, :degrees, :minutes, :seconds
+    # @return [String] "+" or "-"
+    attr_reader :sign
 
+    # @return [Integer] degrees component
+    attr_reader :degrees
+
+    # @return [Integer] arcminutes component
+    attr_reader :minutes
+
+    # @return [Float] arcseconds component
+    attr_reader :seconds
+
+    # @param sign [String] "+" or "-"
+    # @param degrees [Integer] degrees component
+    # @param minutes [Integer] arcminutes component
+    # @param seconds [Float] arcseconds component
     def initialize(sign, degrees, minutes, seconds)
       @sign = sign
       @degrees = degrees
@@ -11,6 +26,8 @@ module Astronoby
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted DMS string (e.g., "+45° 30′ 15.0000″")
     def format(precision: 4)
       "#{sign}#{degrees}° #{minutes}′ #{seconds.floor(precision)}″"
     end

data/lib/astronoby/angles/hms.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in hours, minutes, seconds (HMS) notation.
   class Hms
-    attr_reader :hours, :minutes, :seconds
+    # @return [Integer] hours component
+    attr_reader :hours
 
+    # @return [Integer] minutes component
+    attr_reader :minutes
+
+    # @return [Float] seconds component
+    attr_reader :seconds
+
+    # @param hours [Integer] hours component
+    # @param minutes [Integer] minutes component
+    # @param seconds [Float] seconds component
     def initialize(hours, minutes, seconds)
       @hours = hours
       @minutes = minutes
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted HMS string (e.g., "12h 30m 45.0000s")
     def format(precision: 4)
       "#{hours}h #{minutes}m #{seconds.floor(precision)}s"
     end

data/lib/astronoby/angular_velocity.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Represents an angular velocity with radians per second as its internal
+  # representation. Used primarily for stellar proper motion.
+  class AngularVelocity
+    include Comparable
+
+    class << self
+      # @return [Astronoby::AngularVelocity] a zero angular velocity
+      def zero
+        new(0)
+      end
+
+      # @param radians_per_second [Numeric] the angular velocity in rad/s
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
+      def from_radians_per_second(radians_per_second)
+        new(radians_per_second)
+      end
+
+      # @param mas_per_year [Numeric] the angular velocity in mas/yr
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
+      def from_milliarcseconds_per_year(mas_per_year)
+        angle = Angle.from_degree_arcseconds(mas_per_year / 1000.0)
+        radians_per_second = angle.radians / Constants::SECONDS_PER_JULIAN_YEAR
+        new(radians_per_second)
+      end
+    end
+
+    # @return [Numeric] the angular velocity in radians per second
+    attr_reader :radians_per_second
+    alias_method :rps, :radians_per_second
+
+    # @param radians_per_second [Numeric] the angular velocity in rad/s
+    def initialize(radians_per_second)
+      @radians_per_second = radians_per_second
+      freeze
+    end
+
+    # @return [Float] the angular velocity in milliarcseconds per year
+    def milliarcseconds_per_year
+      angle = Angle.from_radians(@radians_per_second)
+      angle.degree_milliarcseconds * Constants::SECONDS_PER_JULIAN_YEAR
+    end
+    alias_method :mas_per_year, :milliarcseconds_per_year
+
+    # @param other [Astronoby::AngularVelocity] angular velocity to add
+    # @return [Astronoby::AngularVelocity] the sum
+    def +(other)
+      self.class.from_radians_per_second(
+        @radians_per_second + other.radians_per_second
+      )
+    end
+
+    # @param other [Astronoby::AngularVelocity] angular velocity to subtract
+    # @return [Astronoby::AngularVelocity] the difference
+    def -(other)
+      self.class.from_radians_per_second(
+        @radians_per_second - other.radians_per_second
+      )
+    end
+
+    # @return [Astronoby::AngularVelocity] the negated angular velocity
+    def -@
+      self.class.from_radians_per_second(-@radians_per_second)
+    end
+
+    # @return [Boolean] true if the angular velocity is positive
+    def positive?
+      @radians_per_second > 0
+    end
+
+    # @return [Boolean] true if the angular velocity is negative
+    def negative?
+      @radians_per_second < 0
+    end
+
+    # @return [Boolean] true if the angular velocity is zero
+    def zero?
+      @radians_per_second.zero?
+    end
+
+    # @return [Integer] hash value
+    def hash
+      [@radians_per_second, self.class].hash
+    end
+
+    # @param other [Astronoby::AngularVelocity] angular velocity to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      @radians_per_second <=> other.radians_per_second
+    end
+    alias_method :eql?, :==
+  end
+end

data/lib/astronoby/bodies/deep_sky_object.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Represents a deep-sky object (star, galaxy, nebula, etc.) with optional
+  # proper motion and parallax data.
+  class DeepSkyObject
+    include Body
+
+    # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
+    #   Equatorial coordinates at epoch J2000.0
+    # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
+    #   right ascension
+    # @param proper_motion_dec [Astronoby::AngularVelocity, nil] Proper motion
+    #   in declination
+    # @param parallax [Astronoby::Angle, nil] Parallax angle
+    # @param radial_velocity [Astronoby::Velocity, nil] Radial velocity
+    def initialize(
+      equatorial_coordinates:,
+      proper_motion_ra: nil,
+      proper_motion_dec: nil,
+      parallax: nil,
+      radial_velocity: nil
+    )
+      @initial_equatorial_coordinates = equatorial_coordinates
+      @proper_motion_ra = proper_motion_ra
+      @proper_motion_dec = proper_motion_dec
+      @parallax = parallax
+      @radial_velocity = radial_velocity
+    end
+
+    # @param instant [Astronoby::Instant] Instant of the observation
+    # @param ephem [Astronoby::Ephemeris, nil] Ephemeris to use for Earth
+    #   position calculation
+    # @return [Astronoby::DeepSkyObjectPosition] Position of the deep-sky object
+    #   at the given instant
+    def at(instant, ephem: nil)
+      DeepSkyObjectPosition.new(
+        instant: instant,
+        equatorial_coordinates: @initial_equatorial_coordinates,
+        ephem: ephem,
+        proper_motion_ra: @proper_motion_ra,
+        proper_motion_dec: @proper_motion_dec,
+        parallax: @parallax,
+        radial_velocity: @radial_velocity,
+        deep_sky_object: self
+      )
+    end
+  end
+end

data/lib/astronoby/bodies/deep_sky_object_position.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Represents the computed position of a deep-sky object at a specific
+  # instant, providing astrometric, apparent, and topocentric reference frames.
+  class DeepSkyObjectPosition
+    include Position
+
+    DEFAULT_DISTANCE = Distance.from_parsecs(1e9)
+
+    # @return [Astronoby::Instant] the time instant
+    attr_reader :instant
+
+    # @return [Astronoby::Apparent] the apparent reference frame
+    attr_reader :apparent
+
+    # @return [Astronoby::DeepSkyObject, nil] the body definition
+    attr_reader :body
+
+    # @param instant [Astronoby::Instant] Instant of the observation
+    # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
+    #   Equatorial coordinates at epoch J2000.0
+    # @param ephem [::Ephem::SPK, nil] Ephemeris data source for Earth position
+    # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
+    #   right ascension
+    # @param proper_motion_dec [Astronoby::AngularVelocity, nil] Proper motion
+    #   in declination
+    # @param parallax [Astronoby::Angle, nil] Parallax angle
+    # @param radial_velocity [Astronoby::Velocity, nil] Radial velocity
+    # @param deep_sky_object [Astronoby::DeepSkyObject, nil] the body definition
+    def initialize(
+      instant:,
+      equatorial_coordinates:,
+      ephem: nil,
+      proper_motion_ra: nil,
+      proper_motion_dec: nil,
+      parallax: nil,
+      radial_velocity: nil,
+      deep_sky_object: nil
+    )
+      @instant = instant
+      @initial_equatorial_coordinates = equatorial_coordinates
+      @proper_motion_ra = proper_motion_ra
+      @proper_motion_dec = proper_motion_dec
+      @parallax = parallax
+      @radial_velocity = radial_velocity
+      @body = deep_sky_object
+      if ephem
+        @earth_geometric = Earth.geometric(ephem: ephem, instant: @instant)
+      end
+      compute_apparent
+    end
+
+    # @return [Astronoby::Astrometric] Astrometric position of the object
+    def astrometric
+      @astrometric ||= Astrometric.new(
+        instant: @instant,
+        position: astrometric_position,
+        velocity: astrometric_velocity,
+        center: Center.geocentric,
+        target_body: body
+      )
+    end
+
+    private
+
+    def astrometric_position
+      @astrometric_position ||=
+        if @earth_geometric
+          barycentric_position - @earth_geometric.position
+        else
+          barycentric_position
+        end
+    end
+
+    def barycentric_position
+      if use_stellar_propagation?
+        stellar_propagation.position
+      else
+        astronomical_distance = DEFAULT_DISTANCE.meters
+        right_ascension = @initial_equatorial_coordinates.right_ascension
+        declination = @initial_equatorial_coordinates.declination
+        Distance.vector_from_meters([
+          declination.cos * right_ascension.cos * astronomical_distance,
+          declination.cos * right_ascension.sin * astronomical_distance,
+          declination.sin * astronomical_distance
+        ])
+      end
+    end
+
+    def astrometric_velocity
+      @astrometric_velocity ||= if use_stellar_propagation?
+        stellar_propagation.velocity_vector
+      else
+        Velocity.vector_from_meters_per_second([0.0, 0.0, 0.0])
+      end
+    end
+
+    def use_stellar_propagation?
+      @proper_motion_ra && @proper_motion_dec && @parallax && @radial_velocity
+    end
+
+    def stellar_propagation
+      @stellar_propagation ||= StellarPropagation.new(
+        equatorial_coordinates: @initial_equatorial_coordinates,
+        proper_motion_ra: @proper_motion_ra,
+        proper_motion_dec: @proper_motion_dec,
+        parallax: @parallax,
+        radial_velocity: @radial_velocity,
+        instant: @instant,
+        earth_geometric: @earth_geometric
+      )
+    end
+
+    def compute_apparent
+      @apparent = if @earth_geometric
+        Apparent.build_from_astrometric(
+          instant: @instant,
+          target_astrometric: astrometric,
+          earth_geometric: @earth_geometric,
+          target_body: body
+        )
+      else
+        precession_matrix = Precession.matrix_for(@instant)
+        nutation_matrix = Nutation.matrix_for(@instant)
+        corrected_position = Distance.vector_from_meters(
+          precession_matrix * nutation_matrix * astrometric.position.map(&:m)
+        )
+        corrected_velocity = Velocity.vector_from_mps(
+          precession_matrix * nutation_matrix * astrometric.velocity.map(&:mps)
+        )
+        Apparent.new(
+          position: corrected_position,
+          velocity: corrected_velocity,
+          instant: @instant,
+          center: Center.geocentric,
+          target_body: body
+        )
+      end
+    end
+  end
+end

data/lib/astronoby/bodies/earth.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the Earth. Provides ephemeris segments for computing Earth's
+  # geometric position.
   class Earth < SolarSystemBody
+    ORBITAL_PERIOD = 365.256
+
+    # @param ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(ephem_source)
       if ephem_source == ::Ephem::SPK::JPL_DE
         [
@@ -15,48 +21,9 @@ module Astronoby
       end
     end
 
-    private
-
-    # Attributes that require Sun data like phase angle or magnitude are not
-    # applicable for Earth.
-    def requires_sun_data?
-      false
-    end
-
-    def compute_astrometric(_ephem)
-      Astrometric.new(
-        position: Vector[
-          Distance.zero,
-          Distance.zero,
-          Distance.zero
-        ],
-        velocity: Vector[
-          Velocity.zero,
-          Velocity.zero,
-          Velocity.zero
-        ],
-        instant: @instant,
-        center_identifier: EARTH,
-        target_body: self.class
-      )
-    end
-
-    def compute_mean_of_date(_ephem)
-      MeanOfDate.new(
-        position: Vector[
-          Distance.zero,
-          Distance.zero,
-          Distance.zero
-        ],
-        velocity: Vector[
-          Velocity.zero,
-          Velocity.zero,
-          Velocity.zero
-        ],
-        instant: @instant,
-        center_identifier: EARTH,
-        target_body: self.class
-      )
+    # @return [nil] Earth has no phase angle as seen from itself
+    def phase_angle
+      nil
     end
   end
 end

data/lib/astronoby/bodies/jupiter.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Jupiter.
   class Jupiter < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(71_492_000)
     ABSOLUTE_MAGNITUDE = -9.395
+    ORBITAL_PERIOD = 4332.59
 
+    # @return [Boolean] true; Jupiter 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, JUPITER_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/mars.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Mars.
   class Mars < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(3_396_200)
     ABSOLUTE_MAGNITUDE = -1.601
+    ORBITAL_PERIOD = 686.98
 
+    # @return [Boolean] true; Mars 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, MARS_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end