astronoby 0.6.0 → 0.7.0

data/lib/astronoby/deflection.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Deflection
+    # Solar gravitational constant (m^3/s^2)
+    SOLAR_GRAVITATION_CONSTANT = 1.32712440017987e+20
+
+    # @param instant [Astronoby::Instant] the instant of the observation
+    # @param target_astrometric_position [Astronoby::Vector<Distance>] the
+    #   astrometric position of the target
+    # @param ephem [Astronoby::Ephemeris] the ephemeris to use for the
+    #   computation
+    def initialize(instant:, target_astrometric_position:, ephem:)
+      @instant = instant
+      @target_astrometric_position = target_astrometric_position
+      @ephem = ephem
+    end
+
+    # @return [Astronoby::Vector<Distance>] corrected position of the target
+    def corrected_position
+      Astronoby::Vector[
+        *(target_position + deflection_vector)
+          .map { |au| Astronoby::Distance.from_au(au) }
+      ]
+    end
+
+    private
+
+    def tt
+      @tt ||= @instant.tt
+    end
+
+    def earth_geometric
+      Earth.compute_geometric(ephem: @ephem, instant: @instant)
+    end
+
+    def sun_geometric
+      Sun.compute_geometric(ephem: @ephem, instant: @instant)
+    end
+
+    def observer_position
+      @observer_position ||= earth_geometric.position.map(&:au)
+    end
+
+    def target_position
+      @target_position ||= @target_astrometric_position.map(&:au)
+    end
+
+    def sun_position
+      @sun_position ||= sun_geometric.position.map(&:au)
+    end
+
+    def light_travel_time
+      @light_travel_time ||=
+        target_position.magnitude / Astronoby::Velocity.light_speed.aupd
+    end
+
+    def deflector_to_observer_position
+      sun_position - observer_position
+    end
+
+    def closest_deflector_to_target_position
+      observer_position + target_position - deflector_position_at_closest
+    end
+
+    def closest_deflector_to_observer_position
+      @closest_deflector_to_observer_position ||=
+        observer_position - deflector_position_at_closest
+    end
+
+    # Compute light-time difference for the point where light ray is closest to
+    # deflector
+    def closest_approach_time_diff
+      @closest_approach_time_diff ||=
+        Util::Maths.dot_product(
+          target_position / target_position.magnitude,
+          deflector_to_observer_position
+        ) / Astronoby::Velocity.light_speed.aupd
+    end
+
+    # Determine time when incoming photons were closest to the deflecting body
+    def time_at_closest_approach
+      @time_at_closest_approach ||= if closest_approach_time_diff > 0.0
+        tt - closest_approach_time_diff
+      elsif light_travel_time < closest_approach_time_diff
+        tt - light_travel_time
+      else
+        tt
+      end
+    end
+
+    # Get position of deflecting body at the time of closest approach
+    def deflector_position_at_closest
+      @deflector_position_at_closest ||=
+        Sun.compute_geometric(
+          ephem: @ephem,
+          instant: Instant.from_terrestrial_time(time_at_closest_approach)
+        ).position.map(&:au)
+    end
+
+    def observer_to_target_distance
+      @observer_to_target_distance ||= target_position.magnitude
+    end
+
+    def closest_deflector_to_target_distance
+      @closest_deflector_to_target_distance ||=
+        closest_deflector_to_target_position.magnitude
+    end
+
+    def closest_deflector_to_observer_distance
+      @closest_deflector_to_observer_distance ||=
+        closest_deflector_to_observer_position.magnitude
+    end
+
+    def observer_to_target_unit
+      @observer_to_target_unit ||=
+        target_position / observer_to_target_distance
+    end
+
+    def closest_deflector_to_target_unit
+      @closest_deflector_to_target_unit ||=
+        closest_deflector_to_target_position / closest_deflector_to_target_distance
+    end
+
+    def closest_deflector_to_observer_unit
+      @closest_deflector_to_observer_unit ||=
+        closest_deflector_to_observer_position / closest_deflector_to_observer_distance
+    end
+
+    def cos_angle_target
+      Util::Maths.dot_product(
+        observer_to_target_unit,
+        closest_deflector_to_target_unit
+      )
+    end
+
+    def cos_angle_deflector
+      Util::Maths.dot_product(
+        closest_deflector_to_target_unit,
+        closest_deflector_to_observer_unit
+      )
+    end
+
+    def cos_angle_observer
+      @cos_angle_observer ||= Util::Maths.dot_product(
+        closest_deflector_to_observer_unit,
+        observer_to_target_unit
+      )
+    end
+
+    # Calculate the relativistic deflection coefficient
+    # This implements Einstein's light deflection formula: α = 4GM/(c²r)
+    # where:
+    # - G is the gravitational constant
+    # - M is the mass of the deflecting body
+    # - c is the speed of light
+    # - r is the impact parameter (closest approach distance)
+    def relativistic_factor
+      2.0 * SOLAR_GRAVITATION_CONSTANT / (
+        Astronoby::Velocity.light_speed.mps *
+          Astronoby::Velocity.light_speed.mps *
+          closest_deflector_to_observer_distance *
+          Constants::ASTRONOMICAL_UNIT_IN_METERS
+      )
+    end
+
+    def geometry_factor
+      1.0 + cos_angle_deflector
+    end
+
+    def deflection_vector
+      return 0 if colinear?
+
+      relativistic_factor *
+        (
+          cos_angle_target * closest_deflector_to_observer_unit -
+            cos_angle_observer * closest_deflector_to_target_unit
+        ) / geometry_factor * observer_to_target_distance
+    end
+
+    # If deflector is nearly in line with target, make no correction
+    # (avoids numerical instability in nearly-collinear cases)
+    def colinear?
+      cos_angle_observer.abs > 0.99999999999
+    end
+  end
+end

data/lib/astronoby/distance.rb

@@ -25,6 +25,11 @@ module Astronoby
         from_meters(meters)
       end
       alias_method :from_au, :from_astronomical_units
+
+      def vector_from_meters(array)
+        Vector.elements(array.map { from_meters(_1) })
+      end
+      alias_method :vector_from_m, :vector_from_meters
     end
 
     attr_reader :meters
@@ -69,6 +74,10 @@ module Astronoby
       meters.zero?
     end
 
+    def abs2
+      meters**2
+    end
+
     def hash
       [meters, self.class].hash
     end

data/lib/astronoby/ephem.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "ephem"
+
+module Astronoby
+  class Ephem
+    # Download an ephemeris file.
+    #
+    # @param name [String] Name of the ephemeris file, supported by the Ephem
+    #   gem
+    # @param target [String] Location where to store the file
+    # @return [Boolean] true if the download was successful, false otherwise
+    #
+    # @example Downloading de440t SPK from NASA JPL
+    #   Astronoby::Ephem.download(name: "de440t.bsp", target: "tmp/de440t.bsp")
+    def self.download(name:, target:)
+      ::Ephem::Download.call(name: name, target: target)
+    end
+
+    # Load an ephemeris file.
+    #
+    # @param target [String] Path of the ephemeris file
+    # @return [::Ephem::SPK] Ephemeris object from the Ephem gem
+    #
+    # @example Loading previously downloaded de440t SPK from NASA JPL
+    #   Astronoby::Ephem.load("tmp/de440t.bsp")
+    def self.load(target)
+      spk = ::Ephem::SPK.open(target)
+      unless ::Ephem::SPK::TYPES.include?(spk&.type)
+        raise(
+          EphemerisError,
+          "#{target} is not a valid type. Accepted: #{::Ephem::SPK::TYPES.join(", ")}"
+        )
+      end
+
+      spk
+    end
+  end
+end

data/lib/astronoby/equinox_solstice.rb

@@ -73,23 +73,23 @@ module Astronoby
       [8, 15.45, 16859.074]
     ].freeze
 
-    def self.march_equinox(year)
-      new(year, MARCH_EQUINOX).compute
+    def self.march_equinox(year, ephem)
+      new(year, MARCH_EQUINOX, ephem).time
     end
 
-    def self.june_solstice(year)
-      new(year, JUNE_SOLSTICE).compute
+    def self.june_solstice(year, ephem)
+      new(year, JUNE_SOLSTICE, ephem).time
     end
 
-    def self.september_equinox(year)
-      new(year, SEPTEMBER_EQUINOX).compute
+    def self.september_equinox(year, ephem)
+      new(year, SEPTEMBER_EQUINOX, ephem).time
     end
 
-    def self.december_solstice(year)
-      new(year, DECEMBER_SOLSTICE).compute
+    def self.december_solstice(year, ephem)
+      new(year, DECEMBER_SOLSTICE, ephem).time
     end
 
-    def initialize(year, event)
+    def initialize(year, event, ephem)
       unless EVENTS.include?(event)
         raise UnsupportedEventError.new(
           "Expected a format between #{EVENTS.join(", ")}, got #{event}"
@@ -98,8 +98,17 @@ module Astronoby
 
       @event = event
       @year = (year.to_i - 2000) / 1000.0
+      uncorrected_time = compute
+      @instant = Instant.from_time(uncorrected_time)
+      @sun = Sun.new(ephem: ephem, instant: @instant)
     end
 
+    def time
+      Instant.from_terrestrial_time(@instant.tt + corrected).to_time.round
+    end
+
+    private
+
     def compute
       t = (julian_day - Epoch::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
       w = Angle.from_degrees(35999.373 * t) - Angle.from_degrees(2.47)
@@ -113,13 +122,10 @@ module Astronoby
 
       delta_days = 0.00001 * s / delta
       epoch = julian_day + delta_days
-      epoch += correction(epoch)
 
-      Epoch.to_utc(epoch).round
+      Epoch.to_utc(epoch)
     end
 
-    private
-
     def julian_day
       component = JDE_COMPONENTS[@event]
       component[0] +
@@ -129,11 +135,8 @@ module Astronoby
         component[4] * @year**4
     end
 
-    def correction(epoch)
-      time = Epoch.to_utc(epoch)
-      sun = Sun.new(time: time)
-      longitude = sun.apparent_ecliptic_coordinates.longitude
-
+    def corrected
+      longitude = @sun.apparent.ecliptic.longitude
       58 * Angle.from_degrees(@event * 90 - longitude.degrees).sin
     end
   end

data/lib/astronoby/errors.rb

@@ -4,4 +4,8 @@ module Astronoby
   class UnsupportedFormatError < ArgumentError; end
 
   class UnsupportedEventError < ArgumentError; end
+
+  class CalculationError < StandardError; end
+
+  class EphemerisError < StandardError; end
 end

data/lib/astronoby/events/moon_phases.rb

@@ -23,7 +23,8 @@ module Astronoby
           MoonPhase.first_quarter(new(year, month, :first_quarter, 0.25).time),
           MoonPhase.full_moon(new(year, month, :full_moon, 0.5).time),
           MoonPhase.last_quarter(new(year, month, :last_quarter, 0.75).time),
-          MoonPhase.new_moon(new(year, month, :new_moon, 1).time)
+          MoonPhase.new_moon(new(year, month, :new_moon, 1).time),
+          MoonPhase.first_quarter(new(year, month, :first_quarter, 1.25).time)
         ].select { _1.time.month == month }
       end
 

data/lib/astronoby/events/rise_transit_set_calculator.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RiseTransitSetCalculator
+    class PotentialEvent
+      attr_reader :hour_angle, :can_occur
+
+      def initialize(hour_angle, can_occur)
+        @hour_angle = hour_angle
+        @can_occur = can_occur
+      end
+
+      def negated
+        self.class.new(-@hour_angle, @can_occur)
+      end
+    end
+
+    TAU = Math::PI * 2
+    SAMPLE_THRESHOLD = 0.8
+    REFINEMENT_ITERATIONS = 3
+    MIN_TIME_ADJUSTMENT = Constants::MICROSECOND_IN_DAYS
+    STANDARD_REFRACTION_ANGLE = -Angle.from_dms(0, 34, 0)
+    SUN_REFRACTION_ANGLE = -Angle.from_dms(0, 50, 0)
+    EVENT_TYPES = [:rising, :transit, :setting].freeze
+
+    def initialize(body:, observer:, ephem:)
+      @body = body
+      @observer = observer
+      @ephem = ephem
+    end
+
+    def event_on(date, utc_offset: 0)
+      events = events_on(date, utc_offset: utc_offset)
+      RiseTransitSetEvent.new(
+        events.rising_times.first,
+        events.transit_times.first,
+        events.setting_times.first
+      )
+    end
+
+    def events_on(date, utc_offset: 0)
+      start_time = Time.new(
+        date.year,
+        date.month,
+        date.day,
+        0, 0, 0, utc_offset
+      )
+      end_time = Time.new(
+        date.year,
+        date.month,
+        date.day,
+        23, 59, 59, utc_offset
+      )
+      events_between(start_time, end_time)
+    end
+
+    def events_between(start_time, end_time)
+      reset_state
+      @start_instant = Instant.from_time(start_time)
+      @end_instant = Instant.from_time(end_time)
+      events
+    end
+
+    private
+
+    def events
+      rising_events = calculate_initial_positions.map do |position|
+        calculate_rising_event(position)
+      end
+      setting_events = rising_events.map(&:negated)
+      transit_event = PotentialEvent.new(Angle.zero, true)
+
+      event_data = {
+        rising: rising_events,
+        transit: [transit_event],
+        setting: setting_events
+      }
+
+      results = EVENT_TYPES.each_with_object({}) do |event_type, results|
+        results[event_type] = calculate_event_times(
+          event_type,
+          event_data[event_type]
+        )
+      end
+
+      RiseTransitSetEvents.new(
+        results[:rising],
+        results[:transit],
+        results[:setting]
+      )
+    end
+
+    def calculate_rising_event(position)
+      declination = position.equatorial.declination
+      latitude = @observer.latitude
+      altitude = horizon_angle(position.distance)
+
+      # Calculate the unmodified ratio to check if the body rises/sets
+      numerator = altitude.sin - latitude.sin * declination.sin
+      denominator = latitude.cos * declination.cos
+      ratio = numerator / denominator
+
+      # Determine if the body can rise/set and calculate the hour angle
+      can_rise_set = ratio.abs <= 1.0
+      angle = can_rise_set ? -Angle.acos(ratio.clamp(-1.0, 1.0)) : Angle.zero
+
+      PotentialEvent.new(angle, can_rise_set)
+    end
+
+    def calculate_event_times(event_type, events)
+      desired_hour_angles = events.map(&:hour_angle)
+
+      # Calculate differences between current and desired hour angles
+      angle_differences = calculate_angle_differences(
+        calculate_initial_hour_angles,
+        desired_hour_angles
+      )
+
+      # Find intervals where the body crosses the desired hour angle
+      crossing_indexes = find_crossing_intervals(angle_differences)
+
+      # Skip if no relevant crossing points found
+      return [] if crossing_indexes.empty?
+
+      valid_crossings = if events.size == 1
+        # For transit (single event), all crossings are valid
+        crossing_indexes.map { true }
+      else
+        # For rise/set, check if each crossing corresponds to a valid event
+        crossing_indexes.map { |i| events[i].can_occur }
+      end
+
+      old_hour_angles = calculate_initial_hour_angles
+        .values_at(*crossing_indexes)
+      old_instants = sample_instants.values_at(*crossing_indexes)
+
+      # Initial estimate of event times using linear interpolation
+      new_instants = interpolate_initial_times(
+        crossing_indexes,
+        angle_differences
+      )
+
+      # Refine the estimates through iteration
+      refined_times = refine_time_estimates(
+        event_type,
+        new_instants,
+        old_hour_angles,
+        old_instants
+      )
+
+      # Filter out times for bodies that never rise/set
+      refined_times
+        .zip(valid_crossings)
+        .filter_map { |time, valid| time if valid }
+    end
+
+    def sample_count
+      @sample_count ||=
+        ((@end_instant.tt - @start_instant.tt) / SAMPLE_THRESHOLD).ceil + 1
+    end
+
+    def sample_instants
+      @sample_instants ||= Util::Maths.linspace(
+        @start_instant.tt,
+        @end_instant.tt,
+        sample_count
+      ).map { |tt| Instant.from_terrestrial_time(tt) }
+    end
+
+    def calculate_initial_positions
+      @initial_positions ||= calculate_positions_at_instants(sample_instants)
+    end
+
+    def calculate_initial_hour_angles
+      @initial_hour_angles ||=
+        calculate_hour_angles(calculate_initial_positions)
+    end
+
+    def calculate_angle_differences(hour_angles, angles)
+      hour_angles.each_with_index.map do |hour_angle, i|
+        angle = (angles.size == 1) ? angles[0] : angles[i]
+        Angle.from_radians((angle - hour_angle).radians % TAU)
+      end
+    end
+
+    def find_crossing_intervals(differences)
+      differences
+        .each_cons(2)
+        .map { |a, b| b - a }
+        .each_with_index
+        .filter_map { |diff, i| i if diff.radians > 0.0 }
+    end
+
+    def interpolate_initial_times(crossing_indexes, angle_differences)
+      crossing_indexes.map do |index|
+        a = angle_differences[index].radians
+        b = TAU - angle_differences[index + 1].radians
+        c = sample_instants[index].tt
+        d = sample_instants[index + 1].tt
+
+        # Linear interpolation formula
+        tt = (b * c + a * d) / (a + b)
+        Instant.from_terrestrial_time(tt)
+      end
+    end
+
+    def refine_time_estimates(
+      event_type,
+      new_instants,
+      old_hour_angles,
+      old_instants
+    )
+      REFINEMENT_ITERATIONS.times do |iteration|
+        # Calculate positions at current estimates
+        apparent_positions = calculate_positions_at_instants(new_instants)
+
+        # Calculate current hour angles
+        current_hour_angles = calculate_hour_angles(apparent_positions)
+
+        # Calculate desired hour angles based on current positions
+        desired_hour_angles = calculate_desired_hour_angles(
+          event_type,
+          apparent_positions
+        )
+
+        # Calculate hour angle adjustments
+        hour_angle_adjustments = calculate_hour_angle_adjustments(
+          current_hour_angles,
+          desired_hour_angles
+        )
+
+        # Calculate hour angle changes for rate determination
+        hour_angle_changes = calculate_hour_angle_changes(
+          current_hour_angles,
+          old_hour_angles,
+          iteration
+        )
+
+        # Calculate time differences
+        time_differences = new_instants.each_with_index.map do |instant, i|
+          Instant.from_terrestrial_time(instant.tt - old_instants[i].tt)
+        end
+
+        # Calculate hour angle rate (radians per day)
+        hour_angle_rates = hour_angle_changes.each_with_index.map do |angle, i|
+          angle.radians / time_differences[i].tt
+        end
+
+        # Store current values for next iteration
+        old_hour_angles = current_hour_angles
+        old_instants = new_instants
+
+        # Calculate time adjustments
+        time_adjustments = hour_angle_adjustments
+          .each_with_index
+          .map do |angle, i|
+            ratio = angle.radians / hour_angle_rates[i]
+            [ratio.nan? ? 0 : ratio, MIN_TIME_ADJUSTMENT].max
+          end
+
+        # Apply time adjustments
+        new_instants = new_instants.each_with_index.map do |instant, i|
+          Instant.from_terrestrial_time(instant.tt + time_adjustments[i])
+        end
+      end
+
+      new_instants.map { _1.to_time.round }
+    end
+
+    def calculate_positions_at_instants(instants)
+      instants.map do |instant|
+        @body
+          .new(instant: instant, ephem: @ephem)
+          .observed_by(@observer)
+      end
+    end
+
+    def calculate_hour_angles(positions)
+      positions.map do |position|
+        position.equatorial.compute_hour_angle(
+          time: position.instant.to_time,
+          longitude: @observer.longitude
+        )
+      end
+    end
+
+    def calculate_desired_hour_angles(event_type, positions)
+      positions.map do |position|
+        if event_type == :transit
+          Angle.zero
+        else
+          declination = position.equatorial.declination
+          ha = rising_hour_angle(
+            @observer.latitude,
+            declination,
+            horizon_angle(position.distance)
+          )
+          (event_type == :rising) ? ha : -ha
+        end
+      end
+    end
+
+    def calculate_hour_angle_adjustments(current_angles, angles)
+      current_angles.each_with_index.map do |angle, i|
+        radians = ((angles[i] - angle).radians + Math::PI) % TAU - Math::PI
+        Angle.from_radians(radians)
+      end
+    end
+
+    def calculate_hour_angle_changes(current_angles, old_angles, iteration)
+      current_angles.each_with_index.map do |angle, i|
+        radians = angle.radians - old_angles[i].radians
+
+        if iteration == 0
+          radians %= TAU
+        else
+          radians = (radians + Math::PI) % TAU - Math::PI
+        end
+
+        Angle.from_radians(radians)
+      end
+    end
+
+    def rising_hour_angle(latitude, declination, altitude)
+      numerator = altitude.sin - latitude.sin * declination.sin
+      denominator = latitude.cos * declination.cos
+      ratio = (numerator / denominator).clamp(-1.0, 1.0)
+      -Angle.acos(ratio)
+    end
+
+    def horizon_angle(distance)
+      case @body.name
+      when "Astronoby::Sun"
+        SUN_REFRACTION_ANGLE
+      when "Astronoby::Moon"
+        STANDARD_REFRACTION_ANGLE -
+          Angle.from_radians(Moon::EQUATORIAL_RADIUS.m / distance.m)
+      else
+        STANDARD_REFRACTION_ANGLE
+      end
+    end
+
+    def reset_state
+      @initial_hour_angles = nil
+      @initial_positions = nil
+      @sample_count = nil
+      @sample_instants = nil
+      @start_instant = nil
+      @end_instant = nil
+    end
+  end
+end