astronoby 0.8.0 → 0.10.0

data/lib/astronoby/reference_frames/apparent.rb

@@ -1,7 +1,19 @@
 # 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).
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_astrometric [Astronoby::Astrometric] target's astrometric
+    #   frame
+    # @param earth_geometric [Astronoby::Geometric] 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:,
@@ -13,46 +25,43 @@ module Astronoby
       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,
+        astrometric_position: position,
         observer_velocity: earth_geometric.velocity
       ).corrected_position
+
       # 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 [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)
-      end
-    end
-
-    def angular_diameter
-      @angular_radius ||= begin
-        return Angle.zero if @position.zero?
-
-        Angle.from_radians(
-          Math.atan(@target_body.class::EQUATORIAL_RADIUS.m / distance.m) * 2
+        equatorial.to_ecliptic(
+          instant: @instant,
+          obliquity: TrueObliquity.at(@instant)
         )
       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,13 @@ module Astronoby
         position: corrected_position,
         velocity: corrected_velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::EARTH,
+        center: Center.geocentric,
         target_body: target_body
       )
     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,153 @@
+# 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
+
+    # 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

data/lib/astronoby/reference_frames/topocentric.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Topocentric reference frame. Represents a body's position as seen from a
+  # specific observer on Earth's surface, accounting for the observer's
+  # geocentric position and Earth rotation.
   class Topocentric < ReferenceFrame
+    # Builds a topocentric frame from an apparent frame and observer.
+    #
+    # @param apparent [Astronoby::Apparent] the apparent frame
+    # @param observer [Astronoby::Observer] the observer
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::Topocentric] a new topocentric frame
     def self.build_from_apparent(
       apparent:,
       observer:,
@@ -14,7 +24,7 @@ module Astronoby
         matrix * observer.geocentric_position.map(&:m)
       )
       observer_velocity = Velocity.vector_from_mps(
-        matrix * observer.geocentric_velocity.map(&:kmps)
+        matrix * observer.geocentric_velocity.map(&:mps)
       )
 
       position = apparent.position - observer_position
@@ -24,17 +34,23 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: [observer.longitude, observer.latitude],
+        center: Center.topocentric(observer),
         target_body: target_body,
         observer: observer
       )
     end
 
+    # @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
+    # @param observer [Astronoby::Observer] the observer
     def initialize(
       position:,
       velocity:,
       instant:,
-      center_identifier:,
+      center:,
       target_body:,
       observer:
     )
@@ -42,20 +58,30 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: center_identifier,
+        center: center,
         target_body: target_body
       )
       @observer = observer
     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
 
+    # Converts to horizontal coordinates (azimuth/altitude).
+    #
+    # @param refraction [Boolean] whether to apply atmospheric refraction
+    #   correction (default: false)
+    # @return [Astronoby::Coordinates::Horizontal] horizontal coordinates
     def horizontal(refraction: false)
       horizontal = equatorial.to_horizontal(
         time: @instant.to_time,

data/lib/astronoby/refraction.rb

@@ -1,27 +1,44 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes atmospheric refraction corrections for horizontal coordinates.
+  #
+  # Source:
+  #  Title: Practical Astronomy with your Calculator or Spreadsheet
+  #  Authors: Peter Duffett-Smith and Jonathan Zwart
+  #  Edition: Cambridge University Press
+  #  Chapter: 37 - Refraction
   class Refraction
     LOW_ALTITUDE_BODY_ANGLE = Angle.from_degrees(15)
     ZENITH = Angle.from_degrees(90)
 
+    # Computes the refraction angle for the given horizontal coordinates.
+    #
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
+    # @return [Astronoby::Angle] the refraction angle
     def self.angle(coordinates:)
       new(coordinates).refraction_angle
     end
 
+    # Returns horizontal coordinates corrected for atmospheric refraction.
+    #
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
+    # @return [Astronoby::Coordinates::Horizontal] corrected coordinates
     def self.correct_horizontal_coordinates(coordinates:)
       new(coordinates).refract
     end
 
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
     def initialize(coordinates)
       @coordinates = coordinates
     end
 
-    # Source:
-    #  Title: Practical Astronomy with your Calculator or Spreadsheet
-    #  Authors: Peter Duffett-Smith and Jonathan Zwart
-    #  Edition: Cambridge University Press
-    #  Chapter: 37 - Refraction
+    # Returns horizontal coordinates with refraction applied to the altitude.
+    #
+    # @return [Astronoby::Coordinates::Horizontal] corrected coordinates
     def refract
       Coordinates::Horizontal.new(
         azimuth: @coordinates.azimuth,
@@ -30,6 +47,10 @@ module Astronoby
       )
     end
 
+    # Computes the refraction angle based on the observer's atmospheric
+    # conditions and the body's altitude.
+    #
+    # @return [Astronoby::Angle] the refraction angle
     def refraction_angle
       if @coordinates.altitude > LOW_ALTITUDE_BODY_ANGLE
         high_altitude_angle

data/lib/astronoby/root_finder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RootFinder
+    MIN_SAMPLES_PER_PERIOD = 20
+    BISECTION_TOLERANCE_DAYS = 1e-5
+
+    # @param value_at [#call] callable mapping a Julian Date (Terrestrial Time)
+    #   to a Float
+    # @param period [Float] the characteristic period of the quantity in days
+    # @param samples_per_period [Integer] number of samples per period
+    def initialize(value_at:, period:, samples_per_period: 60)
+      @value_at = value_at
+      @period = period
+      @samples_per_period = samples_per_period
+    end
+
+    # @param start_jd [Float] start time in Julian Date (Terrestrial Time)
+    # @param end_jd [Float] end time in Julian Date (Terrestrial Time)
+    # @param accept [#call, nil] optional predicate on a located root (a Julian
+    #   Date)
+    # @return [Array<Float>] root times in Julian Date (Terrestrial Time),
+    #   sorted by time
+    def roots(start_jd, end_jd, accept: nil)
+      brackets = find_brackets(start_jd, end_jd)
+      located = brackets.map { |a, b| bisect(a, b) }
+      located.select { |jd| accept.nil? || accept.call(jd) }
+    end
+
+    private
+
+    def find_brackets(start_jd, end_jd)
+      samples = collect_samples(start_jd, end_jd)
+
+      (0...samples.length - 1).filter_map do |i|
+        current = samples[i]
+        following = samples[i + 1]
+
+        [current[:jd], following[:jd]] if sign_change?(current, following)
+      end
+    end
+
+    def sign_change?(current, following)
+      current[:value] * following[:value] < 0
+    end
+
+    def collect_samples(start_jd, end_jd)
+      duration = end_jd - start_jd
+      sample_count = sample_count_for(duration)
+      step = duration / sample_count
+
+      (0..sample_count).map do |i|
+        jd = start_jd + (i * step)
+        {jd: jd, value: @value_at.call(jd)}
+      end
+    end
+
+    def sample_count_for(duration)
+      periods_in_range = duration / @period
+      base_samples = (periods_in_range * @samples_per_period).to_i
+      [base_samples, MIN_SAMPLES_PER_PERIOD].max
+    end
+
+    def bisect(a, b)
+      f_a = @value_at.call(a)
+
+      while (b - a).abs > BISECTION_TOLERANCE_DAYS
+        midpoint = (a + b) / 2
+        f_midpoint = @value_at.call(midpoint)
+        return midpoint if f_midpoint.zero?
+
+        if f_a.negative? == f_midpoint.negative?
+          a = midpoint
+          f_a = f_midpoint
+        else
+          b = midpoint
+        end
+      end
+
+      (a + b) / 2
+    end
+  end
+end

data/lib/astronoby/rotation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "matrix"
+
+module Astronoby
+  # Builds elementary rotation matrices about the coordinate axes from an
+  # +Astronoby::Angle+.
+  #
+  # These use the passive (frame) convention: the matrix expresses a fixed
+  # vector in a frame rotated by +angle+ about the axis. This is the convention
+  # used throughout the reference-frame chain (precession, nutation, body
+  # orientation).
+  module Rotation
+    module_function
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the x-axis
+    def about_x(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [1, 0, 0],
+        [0, cosine, sine],
+        [0, -sine, cosine]
+      ]
+    end
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the y-axis
+    def about_y(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [cosine, 0, -sine],
+        [0, 1, 0],
+        [sine, 0, cosine]
+      ]
+    end
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the z-axis
+    def about_z(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [cosine, sine, 0],
+        [-sine, cosine, 0],
+        [0, 0, 1]
+      ]
+    end
+  end
+end