astronoby 0.9.0 → 0.11.0

data/lib/astronoby/precession.rb

@@ -1,88 +1,89 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes precession matrices using the IAU 2006 Fukushima-Williams
+  # angles with ICRS frame bias. Also provides coordinate precession
+  # using the classical method.
   class Precession
+    # Computes the combined precession-bias matrix for a given instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] the 3x3 precession-bias matrix PB(t)
     def self.matrix_for(instant)
       new(instant: instant).matrix
     end
 
+    # @param instant [Astronoby::Instant] the time instant
     def initialize(instant:)
       @instant = instant
     end
 
+    # Computes the combined precession-bias matrix PB(t) = R1(-εA) R3(-ψ̄) R1(φ̄) R3(γ̄)
+    #
+    # @return [Matrix] the 3x3 precession-bias matrix
     def matrix
+      # Fukushima-Williams precession angles including frame bias.
       # Source:
-      #  IAU resolution in 2006 in favor of the P03 astronomical model
-      #  https://syrte.obspm.fr/iau2006/aa03_412_P03.pdf
-      # P(t) = R3(χA) R1(−ωA) R3(−ψA) R1(ϵ0)
+      #  IERS Conventions 2010, Section 5.6.4
+      #  Wallace & Capitaine (2006), A&A 459, 981
+      #  ERFA eraPfw06 / eraFw2m
+      # PB(t) = R1(−εA) R3(−ψ̄) R1(φ̄) R3(γ̄)
 
       cache.fetch(cache_key) do
-        # Precession in right ascension
-        psi_a = ((((
-            -0.0000000951 * t +
-            +0.000132851) * t +
-            -0.00114045) * t +
-            -1.0790069) * t +
-            +5038.481507) * t
-
-        # Precession in declination
-        omega_a = ((((
-          +0.0000003337 * t +
-          -0.000000467) * t +
-          -0.00772503) * t +
-          +0.0512623) * t +
-          -0.025754) * t +
-          eps0
-
-        # Precession of the ecliptic
-        chi_a = ((((
-          -0.0000000560 * t +
-          +0.000170663) * t +
-          -0.00121197) * t +
-          -2.3814292) * t +
-          +10.556403) * t
-
-        psi_a = Angle.from_degree_arcseconds(psi_a)
-        omega_a = Angle.from_degree_arcseconds(omega_a)
-        chi_a = Angle.from_degree_arcseconds(chi_a)
-
-        r3_psi = rotation_z(-psi_a)
-        r1_omega = rotation_x(-omega_a)
-        r3_chi = rotation_z(chi_a)
-        r1_eps0 = rotation_x(MeanObliquity.obliquity_of_reference)
-
-        r3_chi * r1_omega * r3_psi * r1_eps0
+        gamma_bar = ((((
+          +0.0000000260 * t +
+          -0.000002788) * t +
+          -0.00031238) * t +
+          +0.4932044) * t +
+          +10.556378) * t +
+          -0.052928
+
+        phi_bar = ((((
+          -0.0000000176 * t +
+          -0.000000440) * t +
+          +0.00053289) * t +
+          +0.0511268) * t +
+          -46.811016) * t +
+          +84381.412819
+
+        psi_bar = ((((
+          -0.0000000148 * t +
+          -0.000026452) * t +
+          -0.00018522) * t +
+          +1.5584175) * t +
+          +5038.481484) * t +
+          -0.041775
+
+        gamma_bar = Angle.from_degree_arcseconds(gamma_bar)
+        phi_bar = Angle.from_degree_arcseconds(phi_bar)
+        psi_bar = Angle.from_degree_arcseconds(psi_bar)
+        eps_a = MeanObliquity.at(@instant)
+
+        Rotation.about_x(-eps_a) * Rotation.about_z(-psi_bar) *
+          Rotation.about_x(phi_bar) * Rotation.about_z(gamma_bar)
       end
     end
 
-    def rotation_x(angle)
-      c, s = angle.cos, angle.sin
-      Matrix[
-        [1, 0, 0],
-        [0, c, s],
-        [0, -s, c]
-      ]
-    end
-
-    def rotation_z(angle)
-      c, s = angle.cos, angle.sin
-      Matrix[
-        [c, s, 0],
-        [-s, c, 0],
-        [0, 0, 1]
-      ]
-    end
-
     # Source:
     #  Title: Practical Astronomy with your Calculator or Spreadsheet
     #  Authors: Peter Duffett-Smith and Jonathan Zwart
     #  Edition: Cambridge University Press
     #  Chapter: 34 - Precession
 
+    # Precesses equatorial coordinates from their current epoch to a new epoch.
+    #
+    # @param coordinates [Astronoby::Coordinates::Equatorial] coordinates to
+    #   precess
+    # @param epoch [Numeric] the target Julian Date epoch
+    # @return [Astronoby::Coordinates::Equatorial] precessed coordinates
     def self.for_equatorial_coordinates(coordinates:, epoch:)
       precess(coordinates, epoch)
     end
 
+    # @param coordinates [Astronoby::Coordinates::Equatorial] coordinates to
+    #   precess
+    # @param epoch [Numeric] the target Julian Date epoch
+    # @return [Astronoby::Coordinates::Equatorial] precessed coordinates
     def self.precess(coordinates, epoch)
       matrix_a = matrix_for_epoch(coordinates.epoch)
       matrix_b = matrix_for_epoch(epoch).transpose
@@ -107,6 +108,10 @@ module Astronoby
       )
     end
 
+    # Computes the classical precession matrix for a given epoch.
+    #
+    # @param epoch [Numeric] a Julian Date epoch
+    # @return [Matrix] 3x3 precession matrix
     def self.matrix_for_epoch(epoch)
       t = (epoch - JulianDate::DEFAULT_EPOCH) / Constants::DAYS_PER_JULIAN_CENTURY
 
@@ -158,13 +163,9 @@ module Astronoby
 
     def t
       @t ||= Rational(
-        @instant.tdb - JulianDate::DEFAULT_EPOCH,
+        @instant.tt - JulianDate::DEFAULT_EPOCH,
         Constants::DAYS_PER_JULIAN_CENTURY
       )
     end
-
-    def eps0
-      @eps0 ||= MeanObliquity.obliquity_of_reference_in_arcseconds
-    end
   end
 end

data/lib/astronoby/reference_frame.rb

@@ -1,35 +1,61 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Base class for reference frames in the astronomical reference frame chain.
+  # Each frame represents a body's position and velocity relative to a center,
+  # at a specific instant.
   class ReferenceFrame
-    attr_reader :position,
-      :velocity,
-      :instant,
-      :center_identifier,
-      :target_body
+    # @return [Astronoby::Vector<Astronoby::Distance>] position vector
+    attr_reader :position
 
+    # @return [Astronoby::Vector<Astronoby::Velocity>] velocity vector
+    attr_reader :velocity
+
+    # @return [Astronoby::Instant] the time instant
+    attr_reader :instant
+
+    # @return [Astronoby::Center] the center of the frame
+    attr_reader :center
+
+    # @return [Astronoby::Body, nil] the target body
+    attr_reader :target_body
+
+    # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] velocity vector
+    # @param instant [Astronoby::Instant] the time instant
+    # @param center [Astronoby::Center] the center of the frame
+    # @param target_body [Astronoby::Body, nil] the target body
     def initialize(
       position:,
       velocity:,
       instant:,
-      center_identifier:,
+      center:,
       target_body:
     )
       @position = position
       @velocity = velocity
       @instant = instant
-      @center_identifier = center_identifier
+      @center = center
       @target_body = target_body
     end
 
+    # @return [Numeric] Julian Date epoch
+    def epoch
+      JulianDate::DEFAULT_EPOCH
+    end
+
+    # @return [Astronoby::Coordinates::Equatorial] equatorial coordinates
+    #   derived from the position vector, referred to the frame's epoch
     def equatorial
       @equatorial ||= begin
-        return Coordinates::Equatorial.zero if distance.zero?
+        return Coordinates::Equatorial.zero(epoch: epoch) if distance.zero?
 
-        Coordinates::Equatorial.from_position_vector(@position)
+        Coordinates::Equatorial.from_position_vector(@position, epoch: epoch)
       end
     end
 
+    # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates derived
+    #   from the equatorial coordinates at J2000.0
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
@@ -39,6 +65,7 @@ module Astronoby
       end
     end
 
+    # @return [Astronoby::Distance] the Euclidean distance from the center
     def distance
       @distance ||= begin
         return Distance.zero if @position.zero?
@@ -46,5 +73,49 @@ module Astronoby
         @position.magnitude
       end
     end
+
+    # @param other [Astronoby::ReferenceFrame] another frame at the same stage
+    #   and instant
+    # @return [Astronoby::Angle] the angular separation, between 0° and 180°
+    # @raise [Astronoby::IncompatibleArgumentsError] if the frames cannot be
+    #   meaningfully compared
+    def separation_from(other)
+      ensure_comparable!(other)
+      return Angle.zero if @position.zero? || other.position.zero?
+
+      position_vector = @position.map(&:m)
+      other_position_vector = other.position.map(&:m)
+      cross = Util::Maths.cross_product(position_vector, other_position_vector)
+      cross_magnitude = Math.sqrt(Util::Maths.dot_product(cross, cross))
+      dot = Util::Maths.dot_product(position_vector, other_position_vector)
+
+      Angle.from_radians(Math.atan2(cross_magnitude, dot))
+    end
+
+    private
+
+    def ensure_comparable!(other)
+      unless other.is_a?(ReferenceFrame)
+        raise IncompatibleArgumentsError,
+          "Expected an Astronoby::ReferenceFrame, got #{other.class}"
+      end
+
+      unless instance_of?(other.class)
+        raise IncompatibleArgumentsError,
+          "Cannot compute the separation between different reference frames " \
+          "(#{self.class} and #{other.class}); both frames must be at the " \
+          "same stage of the reference frame chain"
+      end
+
+      unless instant == other.instant
+        raise IncompatibleArgumentsError,
+          "Cannot compute the separation between frames at different instants"
+      end
+
+      unless center == other.center
+        raise IncompatibleArgumentsError,
+          "Cannot compute the separation between frames with different centers"
+      end
+    end
   end
 end

data/lib/astronoby/reference_frames/apparent.rb

@@ -1,49 +1,80 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Apparent reference frame. Represents a body's geocentric position as it
+  # appears from Earth, corrected for aberration, precession, and nutation.
   class Apparent < ReferenceFrame
+    # Builds an apparent frame from an astrometric frame by applying
+    # aberration in GCRS, then rotating by nutation * precession (with ICRS
+    # frame bias). Without Earth's geometric frame there is no observer
+    # velocity to derive the aberration from, so only the rotation is applied.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_astrometric [Astronoby::Astrometric] target's astrometric
+    #   frame
+    # @param earth_geometric [Astronoby::Geometric, nil] Earth's geometric
+    #   frame
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::Apparent] a new apparent frame
     def self.build_from_astrometric(
       instant:,
       target_astrometric:,
-      earth_geometric:,
-      target_body:
+      target_body:,
+      earth_geometric: nil
     )
       position = target_astrometric.position
       velocity = target_astrometric.velocity
       precession_matrix = Precession.matrix_for(instant)
       nutation_matrix = Nutation.matrix_for(instant)
 
-      corrected_position = Distance.vector_from_meters(
-        precession_matrix * nutation_matrix * position.map(&:m)
-      )
-      corrected_position = Aberration.new(
-        astrometric_position: corrected_position,
-        observer_velocity: earth_geometric.velocity
-      ).corrected_position
+      corrected_position = if earth_geometric
+        Aberration.new(
+          astrometric_position: position,
+          observer_velocity: earth_geometric.velocity
+        ).corrected_position
+      else
+        position
+      end
+
       # In theory, here we should also apply light deflection. However, so far
       # the deflection algorithm hasn't shown any significant changes to the
       # apparent position. Therefore, for now, we are saving some computation
       # time by not applying it, and we will investigate if the algorithm is
       # correct or if the deflection is indeed negligible.
 
+      corrected_position = Distance.vector_from_meters(
+        nutation_matrix * precession_matrix * corrected_position.map(&:m)
+      )
+
       corrected_velocity = Velocity.vector_from_mps(
-        precession_matrix * nutation_matrix * velocity.map(&:mps)
+        nutation_matrix * precession_matrix * velocity.map(&:mps)
       )
 
       new(
         position: corrected_position,
         velocity: corrected_velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::EARTH,
+        center: Center.geocentric,
         target_body: target_body
       )
     end
 
+    # @return [Numeric] Julian Date epoch of the frame's coordinates, which
+    #   are referred to the true equator and equinox of date
+    def epoch
+      instant.tt
+    end
+
+    # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates at the
+    #   current instant (true ecliptic and equinox of date)
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(instant: @instant)
+        equatorial.to_ecliptic(
+          instant: @instant,
+          obliquity: TrueObliquity.at(@instant)
+        )
       end
     end
   end

data/lib/astronoby/reference_frames/astrometric.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Astrometric reference frame (GCRS). Represents a body's position relative
+  # to the Earth, corrected for light-time delay.
   class Astrometric < ReferenceFrame
+    # Builds an astrometric frame from geometric frames with light-time
+    # correction.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param earth_geometric [Astronoby::Geometric] Earth's geometric frame
+    # @param light_time_corrected_position [Astronoby::Vector<Astronoby::Distance>]
+    #   target position corrected for light-time delay
+    # @param light_time_corrected_velocity [Astronoby::Vector<Astronoby::Velocity>]
+    #   target velocity corrected for light-time delay
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::Astrometric] a new astrometric frame
     def self.build_from_geometric(
       instant:,
       earth_geometric:,
@@ -13,7 +26,7 @@ module Astronoby
         position: light_time_corrected_position - earth_geometric.position,
         velocity: light_time_corrected_velocity - earth_geometric.velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::EARTH,
+        center: Center.geocentric,
         target_body: target_body
       )
     end

data/lib/astronoby/reference_frames/geometric.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Geometric reference frame (BCRS). Represents a body's position relative
+  # to the Solar System Barycenter, without any corrections applied.
   class Geometric < ReferenceFrame
+    # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] velocity vector
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_body [Astronoby::Body, nil] the target body
     def initialize(
       position:,
       velocity:,
@@ -12,7 +18,7 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::SOLAR_SYSTEM_BARYCENTER,
+        center: Center.barycentric,
         target_body: target_body
       )
     end

data/lib/astronoby/reference_frames/mean_of_date.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Mean-of-date reference frame. Represents a body's geocentric position
+  # corrected for precession only (no nutation or aberration).
   class MeanOfDate < ReferenceFrame
+    # Builds a mean-of-date frame from geometric frames by applying
+    # precession.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_geometric [Astronoby::Geometric] target's geometric frame
+    # @param earth_geometric [Astronoby::Geometric] Earth's geometric frame
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::MeanOfDate] a new mean-of-date frame
     def self.build_from_geometric(
       instant:,
       target_geometric:,
@@ -22,11 +32,19 @@ module Astronoby
         position: corrected_position,
         velocity: corrected_velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::EARTH,
+        center: Center.geocentric,
         target_body: target_body
       )
     end
 
+    # @return [Numeric] Julian Date epoch of the frame's coordinates, which
+    #   are referred to the mean equator and equinox of date
+    def epoch
+      instant.tt
+    end
+
+    # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates at the
+    #   current instant (mean equinox of date)
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?

data/lib/astronoby/reference_frames/teme.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # TEME (True Equator, Mean Equinox) reference frame. This is the output
+  # frame of the SGP4/SDP4 satellite orbit propagators. Provides conversions
+  # to ECEF, GCRS, and topocentric frames.
+  class Teme < ReferenceFrame
+    # ECEF position and velocity vectors.
+    class EcefCoordinates
+      # @return [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      attr_reader :position
+
+      # @return [Astronoby::Vector<Astronoby::Velocity>] ECEF velocity
+      attr_reader :velocity
+
+      # @param position [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      # @param velocity [Astronoby::Vector<Astronoby::Velocity>] ECEF velocity
+      def initialize(position:, velocity:)
+        @position = position
+        @velocity = velocity
+        freeze
+      end
+
+      # Converts the ECEF position to WGS-84 geodetic coordinates using
+      # Bowring's iterative method.
+      #
+      # @return [Astronoby::Coordinates::Geodetic] geodetic coordinates
+      def geodetic
+        Coordinates::Geodetic.from_ecef(@position)
+      end
+    end
+
+    # @param position [Astronoby::Vector<Astronoby::Distance>] TEME position
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] TEME velocity
+    # @param instant [Astronoby::Instant] the time instant
+    def initialize(position:, velocity:, instant:)
+      super(
+        position: position,
+        velocity: velocity,
+        instant: instant,
+        center: Center.geocentric,
+        target_body: nil
+      )
+    end
+
+    # @return [Numeric] Julian Date epoch of the frame's coordinates, which
+    #   are referred to the true equator and mean equinox of date
+    def epoch
+      instant.tt
+    end
+
+    # Converts TEME position and velocity to ECEF using the canonical
+    # Vallado formulation with R₃(GMST).
+    #
+    # Velocity includes the ω×r transport term to account for Earth
+    # rotation.
+    #
+    # @return [Astronoby::Teme::EcefCoordinates] ECEF position and velocity
+    def to_ecef
+      mean_rotation_matrix = EarthRotation.mean_matrix_for(@instant).transpose
+
+      position = mean_rotation_matrix * @position.map(&:m)
+      velocity_mps = mean_rotation_matrix * @velocity.map(&:mps)
+
+      omega = Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S
+      corrected_vel = ::Vector[
+        velocity_mps[0] + omega * position[1],
+        velocity_mps[1] - omega * position[0],
+        velocity_mps[2]
+      ]
+
+      EcefCoordinates.new(
+        position: Distance.vector_from_meters(position),
+        velocity: Velocity.vector_from_mps(corrected_vel)
+      )
+    end
+
+    # Converts TEME to GCRS using the pragmatic approach: reuse existing
+    # IAU 2006/2000B precession and nutation matrices transposed.
+    #
+    # The transformation chain is: r_GCRS = PBᵀ * Nᵀ * R₃(EoE) * r_TEME
+    #
+    # @return [Astronoby::Astrometric] GCRS Earth-centered frame
+    def to_gcrs
+      Astrometric.new(
+        position: Distance.vector_from_meters(
+          gcrs_rotation_matrix * @position.map(&:m)
+        ),
+        velocity: Velocity.vector_from_mps(
+          gcrs_rotation_matrix * @velocity.map(&:mps)
+        ),
+        instant: @instant,
+        center: Center.geocentric,
+        target_body: nil
+      )
+    end
+
+    # Converts TEME to topocentric coordinates as seen from an observer.
+    #
+    # Both satellite (via equation of equinoxes) and observer (via
+    # R₃(GAST) * W) are placed in the TOD frame, then subtracted.
+    #
+    # @param observer [Astronoby::Observer] the observer
+    # @return [Astronoby::Topocentric] topocentric frame
+    def observed_by(observer)
+      satellite_position = Distance.vector_from_meters(
+        equation_of_equinoxes_matrix * @position.map(&:m)
+      )
+      satellite_velocity = Velocity.vector_from_mps(
+        equation_of_equinoxes_matrix * @velocity.map(&:mps)
+      )
+
+      matrix = observer.earth_fixed_rotation_matrix_for(@instant)
+      observer_position = Distance.vector_from_meters(
+        matrix * observer.geocentric_position.map(&:m)
+      )
+      observer_velocity = Velocity.vector_from_mps(
+        matrix * observer.geocentric_velocity.map(&:mps)
+      )
+
+      Topocentric.new(
+        position: satellite_position - observer_position,
+        velocity: satellite_velocity - observer_velocity,
+        instant: @instant,
+        center: Center.topocentric(observer),
+        target_body: nil,
+        observer: observer
+      )
+    end
+
+    private
+
+    def gcrs_rotation_matrix
+      @gcrs_rotation_matrix ||= begin
+        precession_matrix = Precession.matrix_for(@instant)
+        nutation_matrix = Nutation.matrix_for(@instant)
+        precession_matrix.transpose *
+          nutation_matrix.transpose *
+          equation_of_equinoxes_matrix
+      end
+    end
+
+    def equation_of_equinoxes_matrix
+      @equation_of_equinoxes_matrix ||= begin
+        nutation = Nutation.new(instant: @instant)
+        dpsi = nutation.nutation_in_longitude
+        mean_obliquity = MeanObliquity.at(@instant)
+        eoe = dpsi.radians * mean_obliquity.cos
+
+        c, s = Math.cos(eoe), Math.sin(eoe)
+        Matrix[
+          [c, -s, 0],
+          [s, c, 0],
+          [0, 0, 1]
+        ]
+      end
+    end
+  end
+end