astronoby 0.8.0 → 0.9.0

data/lib/astronoby/bodies/earth.rb

@@ -15,12 +15,16 @@ module Astronoby
       end
     end
 
+    def phase_angle
+      nil
+    end
+
     private
 
     # Attributes that require Sun data like phase angle or magnitude are not
     # applicable for Earth.
     def requires_sun_data?
-      false
+      true
     end
 
     def compute_astrometric(_ephem)

data/lib/astronoby/bodies/moon.rb

@@ -42,6 +42,27 @@ module Astronoby
       mean_elongation.degrees / Constants::DEGREES_PER_CIRCLE
     end
 
+    # @return [Boolean] True if the body is approaching the primary
+    #   body (Earth), false otherwise.
+    def approaching_primary?
+      relative_position =
+        (geometric.position - @earth_geometric.position).map(&:m)
+      relative_velocity =
+        (geometric.velocity - @earth_geometric.velocity).map(&:mps)
+      radial_velocity_component = Astronoby::Util::Maths
+        .dot_product(relative_position, relative_velocity)
+      distance = Math.sqrt(
+        Astronoby::Util::Maths.dot_product(relative_position, relative_position)
+      )
+      radial_velocity_component / distance < 0
+    end
+
+    # @return [Boolean] True if the body is receding from the primary
+    #   body (Earth), false otherwise.
+    def receding_from_primary?
+      !approaching_primary?
+    end
+
     private
 
     # Source:

data/lib/astronoby/bodies/solar_system_body.rb

@@ -19,6 +19,10 @@ module Astronoby
 
     attr_reader :geometric, :instant
 
+    def self.at(instant, ephem:)
+      new(ephem: ephem, instant: instant)
+    end
+
     def self.geometric(ephem:, instant:)
       compute_geometric(ephem: ephem, instant: instant)
     end
@@ -202,6 +206,27 @@ module Astronoby
       end
     end
 
+    # @return [Boolean] True if the body is approaching the primary
+    #   body (Sun), false otherwise.
+    def approaching_primary?
+      relative_position =
+        (geometric.position - @sun.geometric.position).map(&:m)
+      relative_velocity =
+        (geometric.velocity - @sun.geometric.velocity).map(&:mps)
+      radial_velocity_component = Astronoby::Util::Maths
+        .dot_product(relative_position, relative_velocity)
+      distance = Math.sqrt(
+        Astronoby::Util::Maths.dot_product(relative_position, relative_position)
+      )
+      radial_velocity_component / distance < 0
+    end
+
+    # @return [Boolean] True if the body is receding from the primary
+    #   body (Sun), false otherwise.
+    def receding_from_primary?
+      !approaching_primary?
+    end
+
     private
 
     # By default, Solar System bodies expose attributes that are dependent on

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/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/coordinates/equatorial.rb

@@ -42,11 +42,8 @@ module Astronoby
       end
 
       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)

data/lib/astronoby/distance.rb

@@ -26,6 +26,12 @@ module Astronoby
       end
       alias_method :from_au, :from_astronomical_units
 
+      def from_parsecs(parsecs)
+        meters = parsecs * Constants::PARSEC_IN_METERS
+        from_meters(meters)
+      end
+      alias_method :from_pc, :from_parsecs
+
       def vector_from_meters(array)
         Vector.elements(array.map { from_meters(_1) })
       end

data/lib/astronoby/events/extremum_calculator.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Calculates extrema (minima and maxima) in the distance between two
+  # celestial bodies over a given time range using adaptive sampling and golden
+  # section search refinement.
+  class ExtremumCalculator
+    # Mathematical constants
+    PHI = (1 + Math.sqrt(5)) / 2
+    INVPHI = 1 / PHI
+    GOLDEN_SECTION_TOLERANCE = 1e-5
+
+    # Algorithm parameters
+    MIN_SAMPLES_PER_PERIOD = 20
+    DUPLICATE_THRESHOLD_DAYS = 0.5
+    BOUNDARY_BUFFER_DAYS = 0.01
+
+    # Orbital periods
+    ORBITAL_PERIODS = {
+      "Astronoby::Moon" => 27.504339,
+      "Astronoby::Mercury" => 87.969,
+      "Astronoby::Venus" => 224.701,
+      "Astronoby::Earth" => 365.256,
+      "Astronoby::Mars" => 686.98,
+      "Astronoby::Jupiter" => 4332.59,
+      "Astronoby::Saturn" => 10759.22,
+      "Astronoby::Uranus" => 30688.5,
+      "Astronoby::Neptune" => 60182.0
+    }.freeze
+
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param body [Astronoby::SolarSystemBody] The celestial body to track
+    # @param primary_body [Astronoby::SolarSystemBody] The reference body
+    #   (e.g., Sun for planetary orbits)
+    # @param samples_per_period [Integer] Number of samples to take per orbital
+    #   period
+    def initialize(
+      body:,
+      primary_body:,
+      ephem:,
+      samples_per_period: 60
+    )
+      @ephem = ephem
+      @body = body
+      @primary_body = primary_body
+      @orbital_period = ORBITAL_PERIODS.fetch(body.name)
+      @samples_per_period = samples_per_period
+    end
+
+    # Finds all apoapsis events between two times
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of apoapsis events
+    def apoapsis_events_between(start_time, end_time)
+      find_extrema(
+        Astronoby::Instant.from_time(start_time).tt,
+        Astronoby::Instant.from_time(end_time).tt,
+        type: :maximum
+      )
+    end
+
+    # Finds all periapsis events between two times
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of periapsis events
+    def periapsis_events_between(start_time, end_time)
+      find_extrema(
+        Astronoby::Instant.from_time(start_time).tt,
+        Astronoby::Instant.from_time(end_time).tt,
+        type: :minimum
+      )
+    end
+
+    # Finds extrema (minima or maxima) in the distance between bodies within
+    #   a time range
+    # @param start_jd [Float] Start time in Julian Date (Terrestrial Time)
+    # @param end_jd [Float] End time in Julian Date (Terrestrial Time)
+    # @param type [Symbol] :maximum or :minimum
+    # @return [Array<Astronoby::ExtremumEvent>] Array of extrema events
+    def find_extrema(start_jd, end_jd, type: :maximum)
+      # 1: Find extrema candidates through adaptive sampling
+      candidates = find_extrema_candidates(start_jd, end_jd, type)
+
+      # 2: Refine each candidate using golden section search
+      refined_extrema = candidates
+        .map { |candidate| refine_extremum(candidate, type) }
+        .compact
+
+      # 3: Remove duplicates and boundary artifacts
+      refined_extrema = remove_duplicates(refined_extrema)
+      filter_boundary_artifacts(refined_extrema, start_jd, end_jd)
+    end
+
+    private
+
+    def distance_at(jd)
+      instant = Instant.from_terrestrial_time(jd)
+      body_geometric = @body.geometric(ephem: @ephem, instant: instant)
+      primary_geometric = @primary_body
+        .geometric(ephem: @ephem, instant: instant)
+
+      distance_vector = body_geometric.position - primary_geometric.position
+      distance_vector.magnitude
+    end
+
+    def find_extrema_candidates(start_jd, end_jd, type)
+      samples = collect_samples(start_jd, end_jd)
+      find_local_extrema_in_samples(samples, type)
+    end
+
+    def collect_samples(start_jd, end_jd)
+      duration = end_jd - start_jd
+      sample_count = calculate_sample_count(duration)
+      step = duration / sample_count
+
+      (0..sample_count).map do |i|
+        jd = start_jd + (i * step)
+        {jd: jd, value: distance_at(jd)}
+      end
+    end
+
+    def calculate_sample_count(duration)
+      # Adaptive sampling: scale with duration and orbital period
+      periods_in_range = duration / @orbital_period
+      base_samples = (periods_in_range * @samples_per_period).to_i
+
+      # Ensure minimum sample density for short ranges
+      [base_samples, MIN_SAMPLES_PER_PERIOD].max
+    end
+
+    def find_local_extrema_in_samples(samples, type)
+      candidates = []
+
+      # Check each interior point for local extrema
+      (1...samples.length - 1).each do |i|
+        if local_extremum?(samples, i, type)
+          candidates << {
+            start_jd: samples[i - 1][:jd],
+            end_jd: samples[i + 1][:jd],
+            center_jd: samples[i][:jd]
+          }
+        end
+      end
+
+      candidates
+    end
+
+    def local_extremum?(samples, index, type)
+      current_val = samples[index][:value].m
+      prev_val = samples[index - 1][:value].m
+      next_val = samples[index + 1][:value].m
+
+      if type == :maximum
+        current_val > prev_val && current_val > next_val
+      else
+        current_val < prev_val && current_val < next_val
+      end
+    end
+
+    def refine_extremum(candidate, type)
+      golden_section_search(candidate[:start_jd], candidate[:end_jd], type)
+    end
+
+    def golden_section_search(a, b, type)
+      return nil if b <= a
+
+      tol = GOLDEN_SECTION_TOLERANCE * (b - a).abs
+
+      # Initial points using golden ratio
+      x1 = a + (1 - INVPHI) * (b - a)
+      x2 = a + INVPHI * (b - a)
+
+      f1 = distance_at(x1).m
+      f2 = distance_at(x2).m
+
+      while (b - a).abs > tol
+        should_keep_left = (type == :maximum) ? (f1 > f2) : (f1 < f2)
+
+        if should_keep_left
+          b = x2
+          x2 = x1
+          f2 = f1
+          x1 = a + (1 - INVPHI) * (b - a)
+          f1 = distance_at(x1).m
+        else
+          a = x1
+          x1 = x2
+          f1 = f2
+          x2 = a + INVPHI * (b - a)
+          f2 = distance_at(x2).m
+        end
+      end
+
+      mid = (a + b) / 2
+      ExtremumEvent.new(
+        Instant.from_terrestrial_time(mid),
+        distance_at(mid)
+      )
+    end
+
+    def remove_duplicates(extrema)
+      return extrema if extrema.length <= 1
+
+      cleaned = [extrema.first]
+
+      extrema.each_with_index do |current, i|
+        next if i == 0
+
+        is_duplicate = cleaned.any? do |existing|
+          time_diff = (
+            current.instant.tt - existing.instant.tt
+          ).abs
+          time_diff < DUPLICATE_THRESHOLD_DAYS
+        end
+
+        cleaned << current unless is_duplicate
+      end
+
+      cleaned
+    end
+
+    def filter_boundary_artifacts(extrema, start_jd, end_jd)
+      extrema.reject do |extreme|
+        start_diff = (extreme.instant.tt - start_jd).abs
+        end_diff = (extreme.instant.tt - end_jd).abs
+
+        too_close_to_start = start_diff < BOUNDARY_BUFFER_DAYS
+        too_close_to_end = end_diff < BOUNDARY_BUFFER_DAYS
+        too_close_to_start || too_close_to_end
+      end
+    end
+  end
+end

data/lib/astronoby/events/extremum_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Represents an extremum event with its timing and value
+  class ExtremumEvent
+    attr_reader :instant, :value
+
+    # @param instant [Astronoby::Instant] When the event occurs
+    # @param value [Object] The extreme value
+    def initialize(instant, value)
+      @instant = instant
+      @value = value
+    end
+  end
+end

data/lib/astronoby/events/rise_transit_set_calculator.rb

@@ -23,7 +23,11 @@ module Astronoby
     SUN_REFRACTION_ANGLE = -Angle.from_dms(0, 50, 0)
     EVENT_TYPES = [:rising, :transit, :setting].freeze
 
-    def initialize(body:, observer:, ephem:)
+    # @param body [Astronoby::SolarSystemBody, Astronoby::DeepSkyObject]
+    #   Celestial body for which to calculate events
+    # @param observer [Astronoby::Observer] Observer location
+    # @param ephem [::Ephem::SPK, nil] Ephemeris data source
+    def initialize(body:, observer:, ephem: nil)
       @body = body
       @observer = observer
       @ephem = ephem
@@ -280,7 +284,7 @@ module Astronoby
           )
           Astronoby.cache.fetch(cache_key) do
             @body
-              .new(instant: instant, ephem: @ephem)
+              .at(instant, ephem: @ephem)
               .observed_by(@observer)
           end
         end
@@ -292,7 +296,7 @@ module Astronoby
             instant.tt.round(precision)
           )
           @positions_cache[rounded_instant] ||= @body
-            .new(instant: rounded_instant, ephem: @ephem)
+            .at(rounded_instant, ephem: @ephem)
             .observed_by(@observer)
         end
       end
@@ -352,10 +356,9 @@ module Astronoby
     end
 
     def horizon_angle(distance)
-      case @body.name
-      when "Astronoby::Sun"
+      if @body == Astronoby::Sun
         SUN_REFRACTION_ANGLE
-      when "Astronoby::Moon"
+      elsif @body == Astronoby::Moon
         STANDARD_REFRACTION_ANGLE -
           Angle.from_radians(Moon::EQUATORIAL_RADIUS.m / distance.m)
       else

data/lib/astronoby/events/twilight_calculator.rb

@@ -210,7 +210,7 @@ module Astronoby
 
       twilight_in_hours =
         time_sign * (hour_angle_at_twilight - hour_angle_at_period).hours *
-        GreenwichSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
+        GreenwichMeanSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
       twilight_in_seconds = time_sign *
         twilight_in_hours *
         Constants::SECONDS_PER_HOUR

data/lib/astronoby/instant.rb

@@ -94,7 +94,7 @@ module Astronoby
     def to_datetime
       DateTime.jd(
         @terrestrial_time -
-          Rational(delta_t / Constants::SECONDS_PER_DAY) +
+          Rational(delta_t, Constants::SECONDS_PER_DAY) +
           DATETIME_JD_EPOCH_ADJUSTMENT
       )
     end
@@ -123,9 +123,32 @@ module Astronoby
 
     # Get the Greenwich Mean Sidereal Time
     #
-    # @return [Numeric] the sidereal time in radians
+    # @return [Numeric] the sidereal time in hours
     def gmst
-      GreenwichSiderealTime.from_utc(to_time).time
+      GreenwichMeanSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Greenwich Apparent Sidereal Time
+    #
+    # @return [Numeric] the sidereal time in hours
+    def gast
+      GreenwichApparentSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Local Mean Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def lmst(longitude:)
+      LocalMeanSiderealTime.from_utc(to_time, longitude: longitude).time
+    end
+
+    # Get the Local Apparent Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def last(longitude:)
+      LocalApparentSiderealTime.from_utc(to_time, longitude: longitude).time
     end
 
     # Get the International Atomic Time (TAI)
@@ -151,7 +174,7 @@ module Astronoby
     #
     # @return [Numeric] the offset in days
     def utc_offset
-      @terrestrial_time - to_time.utc.to_datetime.ajd
+      Rational(delta_t / Constants::SECONDS_PER_DAY)
     end
 
     # Calculate hash value for the instant

data/lib/astronoby/reference_frames/apparent.rb

@@ -46,15 +46,5 @@ module Astronoby
         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
-        )
-      end
-    end
   end
 end

data/lib/astronoby/reference_frames/topocentric.rb

@@ -14,7 +14,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

data/lib/astronoby/stellar_propagation.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class StellarPropagation
+    # @return [Astronoby::Vector] Propagated position vector of
+    #   Astronoby::Distance components
+    def self.position_for(**kwargs)
+      new(**kwargs).position
+    end
+
+    # @return [Astronoby::Vector] Propagated position vector of
+    #   Astronoby::Velocity components
+    def self.velocity_vector_for(**kwargs)
+      new(**kwargs).velocity_vector
+    end
+
+    # @return [Astronoby::Coordinates::Equatorial] Propagated equatorial
+    #   coordinates
+    def self.equatorial_coordinates_for(**kwargs)
+      new(**kwargs).equatorial_coordinates
+    end
+
+    # @param instant [Astronoby::Instant] Instant of the observation
+    # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
+    #   Equatorial coordinates at epoch J2000.0
+    # @param proper_motion_ra [Astronoby::AngularVelocity] Proper motion in
+    #   right ascension
+    # @param proper_motion_dec [Astronoby::AngularVelocity] Proper motion in
+    #   declination
+    # @param parallax [Astronoby::Angle] Parallax angle
+    # @param radial_velocity [Astronoby::Velocity] Radial velocity
+    # @param earth_geometric [Astronoby::ReferenceFrame::Geometric, nil]
+    #   Geometric reference frame of the Earth
+    def initialize(
+      instant:,
+      equatorial_coordinates:,
+      proper_motion_ra:,
+      proper_motion_dec:,
+      parallax:,
+      radial_velocity:,
+      earth_geometric: nil
+    )
+      @instant = instant
+      @right_ascension = equatorial_coordinates.right_ascension
+      @declination = equatorial_coordinates.declination
+      @initial_epoch = equatorial_coordinates.epoch
+      @proper_motion_ra = proper_motion_ra
+      @proper_motion_dec = proper_motion_dec
+      @parallax = parallax
+      @radial_velocity = radial_velocity
+      @earth_geometric = earth_geometric
+    end
+
+    # @return [Astronoby::Vector] Propagated position vector of
+    #   Astronoby::Distance components
+    def position
+      @position ||= Distance.vector_from_meters(
+        initial_position_vector +
+        tangential_velocity.map(&:mps) * time_elapsed_seconds
+      )
+    end
+
+    # @return [Astronoby::Vector] Propagated position vector of
+    #   Astronoby::Velocity components
+    def velocity_vector
+      @velocity_vector ||= if @earth_geometric
+        @earth_geometric.velocity - tangential_velocity
+      else
+        tangential_velocity
+      end
+    end
+
+    # @return [Astronoby::Coordinates::Equatorial] Propagated equatorial
+    #   coordinates
+    def equatorial_coordinates
+      @equatorial_coordinates ||= begin
+        right_ascension = Util::Trigonometry.adjustement_for_arctangent(
+          position.y.m,
+          position.x.m,
+          Angle.atan(position.y.m / position.x.m)
+        )
+        declination = Angle.asin(position.z.m / position.magnitude.m)
+
+        Coordinates::Equatorial.new(
+          right_ascension: right_ascension,
+          declination: declination,
+          epoch: @instant.tt
+        )
+      end
+    end
+
+    private
+
+    def distance
+      @distance ||= Distance.from_parsecs(
+        1 / (@parallax.degrees * Constants::ARCSECONDS_PER_DEGREE)
+      )
+    end
+
+    def unit_position_vector
+      @unit_position_vector ||= Vector[
+        @right_ascension.cos * @declination.cos,
+        @right_ascension.sin * @declination.cos,
+        @declination.sin
+      ]
+    end
+
+    def right_ascension_unit_vector
+      @right_ascension_unit_vector ||= Vector[
+        -@right_ascension.sin,
+        @right_ascension.cos,
+        0.0
+      ]
+    end
+
+    def declination_unit_vector
+      @declination_unit_vector ||= Vector[
+        -@right_ascension.cos * @declination.sin,
+        -@right_ascension.sin * @declination.sin,
+        @declination.cos
+      ]
+    end
+
+    def initial_position_vector
+      @initial_position_vector ||= unit_position_vector * distance.meters
+    end
+
+    def tangential_velocity
+      @tangential_velocity ||= begin
+        # Doppler factor for light travel time correction
+        k = 1.0 / (1.0 - @radial_velocity.kmps / Velocity.light_speed.kmps)
+
+        proper_motion_ra_component =
+          @proper_motion_ra.mas_per_year / (
+            @parallax.degree_milliarcseconds * Constants::DAYS_PER_JULIAN_YEAR
+          ) * k
+        proper_motion_dec_component =
+          @proper_motion_dec.mas_per_year / (
+            @parallax.degree_milliarcseconds * Constants::DAYS_PER_JULIAN_YEAR
+          ) * k
+        radial_velocity_component = Velocity
+          .from_kmps(@radial_velocity.kmps * k)
+
+        Velocity.vector_from_astronomical_units_per_day([
+          -proper_motion_ra_component * @right_ascension.sin -
+            proper_motion_dec_component * @declination.sin * @right_ascension.cos +
+            radial_velocity_component.aupd * @declination.cos * @right_ascension.cos,
+          proper_motion_ra_component * @right_ascension.cos -
+            proper_motion_dec_component * @declination.sin * @right_ascension.sin +
+            radial_velocity_component.aupd * @declination.cos * @right_ascension.sin,
+          proper_motion_dec_component * @declination.cos +
+            radial_velocity_component.aupd * @declination.sin
+        ])
+      end
+    end
+
+    def time_elapsed_seconds
+      @time_elapsed_seconds ||=
+        (@instant.tt - @initial_epoch) * Constants::SECONDS_PER_DAY
+    end
+  end
+end