astronoby 0.6.0 → 0.7.0

data/UPGRADING.md

@@ -7,6 +7,244 @@ changes to it as long as a major version has not been released.
 If you are already using Astronoby and wish to follow the changes to its
 public API, please read the upgrading notes for each release.
 
+## Upgrading from 0.6.0 to 0.7.0
+
+## Signature change for `Sun` and `Moon`
+
+Both classes are now initialized with the key arguments `ephem` and `instant`.
+`ephem` comes from `Ephem.load` which provides the raw geometric data for Solar
+System bodies. `instant` is an instance of `Instant`, the new concept for
+representing an instant in time.
+
+```rb
+Ephem::IO::Download.call(name: "de421.bsp", target: "tmp/de421.bsp")
+ephem = Astronoby::Ephem.load("tmp/de421.bsp")
+
+time = Time.utc(2025, 6, 19, 12, 0, 0)
+instant = Astronoby::Instant.from_time(time)
+
+sun = Astronoby::Sun.new(instant: instant, ephem: ephem)
+```
+
+Learn more on [ephem].
+
+[ephem]: https://github.com/rhannequin/astronoby/wiki/Ephem
+
+## Drop of methods for `Sun`
+
+`Sun` doesn't expose the following class and instance methods anymore:
+* `::equation_of_time` (replaced with `#equation_of_time`)
+* `#epoch` (replaced with `#instant`)
+* `#true_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#apparent_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#horizontal_coordinates` (replaced with `#horizontal` on the Topocentric reference frame)
+* `#observation_events`
+* `#twilight_events`
+* `#earth_distance` (replaced with `#distance` on referential frames)
+* `#angular_size` (replaced with `#angular_diameter` on referential frames)
+* `#true_anomaly`
+* `#mean_anomaly`
+* `#longitude_at_perigee`
+* `#orbital_eccentricity`
+
+Learn more on [reference frames].
+
+[reference frames]: https://github.com/rhannequin/astronoby/wiki/Reference-Frames
+
+## Drop of instance methods for `Moon`
+
+`Moon` doesn't expose the following nstance methods anymore:
+* `#apparent_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#apparent_equatorial_coordinates` (replaced with `#equatorial` on reference frames)
+* `#horizontal_coordinates` (replaced with the Apparent and Topocentric reference frames)
+* `#distance` (replaced with `#distance` on referential frames)
+* `#mean_longitude`
+* `#mean_elongation`
+* `#mean_anomaly`
+* `#argument_of_latitude`
+* `#phase_angle`
+* `#observation_events`
+
+## Signature change for `Aberration`
+
+`Aberration` is now initialized with the key arguments `astrometric_position`
+and `observer_velocity`. `astrometric_position` is a position vector
+(`Astronoby::Vector<Astronoby::Distance>`) available from any referential frame
+with the `#position` method.`observer_velocity` is a velocity vector
+(`Astronoby::Vector<Astronoby::Distance>`) available from any referential frame
+with the `#velocity` method.
+
+`observer_velocity` is meant to be a geometric velocity, while
+`astrometric_position` is meant to be an astrometric position.
+
+```rb
+time = Time.utc(2025, 4, 1)
+instant = Astronoby::Instant.from_time(time)
+ephem = Astronoby::Ephem.load("de421.bsp")
+earth = Astronoby::Earth.new(instant: instant, ephem: ephem)
+mars = Astronoby::Mars.new(instant: instant, ephem: ephem)
+earth_geometric_velocity = earth.geometric.velocity
+mars_astrometric_position = mars.astrometric.position
+
+aberration = Astronoby::Aberration.new(
+  astrometric_position: mars_astrometric_position,
+  observer_velocity: earth_geometric_velocity
+)
+```
+
+## Signature change for `Angle#to_dms` and `Angle#to_hms`
+
+`Angle#to_dms` and `Angle#to_hms` don't have arguments anymore. The angle value
+is now taken from the object itself. This was a misbehavior in the previous
+implementation.
+
+```rb
+angle = Astronoby::Angle.from_degrees(45.0)
+dms = angle.to_dms
+
+dms.format
+# => "+45° 0′ 0.0″"
+```
+
+## Signature change for `EquinoxSolstice`
+
+`EquinoxSolstice.new` now takes an additional argument expected to be an ephem
+(`Astronoby::Ephem`).
+
+## Signature change for `Nutation`
+
+The expected `epoch` (`Astronoby::Epoch`) argument has been replaced by an
+`instant` (`Astronoby::Instant`) key argument.
+
+## Drop of `Nutation::for_ecliptic_longitude` and `Nutation::for_obliquity_of_the_ecliptic`
+
+`Nutation::for_ecliptic_longitude` and `Nutation::for_obliquity_of_the_ecliptic`
+methods have been removed. The `Nutation` class now exposes the
+`#nutation_in_longitude` and `#nutation_in_obliquity` instance methods which 
+both return an angle (`Astronoby::Angle`).
+
+## Signature change for `Precession`
+
+The expected `coordinates` and `epoch` (`Astronoby::Epoch`) key arguments have
+been replaced by an `instant` (`Astronoby::Instant`) key argument.
+
+## Drop of `Precession#for_equatorial_coordinates` and `Precession#precess`
+
+`Precession#for_equatorial_coordinates` and `Precession#precess` methods have
+been refactoed into class methods.
+
+## Drop of `Coordinates::Horizontal#to_equatorial`
+
+`Coordinates::Horizontal#to_equatorial` has been removed as equatorial
+coordinates are now available from the reference frames.
+
+## Drop of instance methods for `Coordinates::Ecliptic`
+
+`Coordinates::Ecliptic#to_true_equatorial` and
+`Coordinates::Ecliptic#to_apparent_equatorial` have been removed as
+equatorial coordinates are now available from the reference frames.
+
+## Drop of `Coordinates::Equatorial#to_epoch`
+
+`Coordinates::Equatorial#to_epoch` has been removed.
+
+## Drop of `Events::ObservationEvents`
+
+`Events::ObservationEvents` has been removed. The rising, transit and setting 
+times can now be calculated using `RiseTransitSetCalculator`.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48),
+  longitude: Astronoby::Angle.from_degrees(2)
+)
+date = Date.new(2025, 4, 24)
+
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(date)
+
+event.rising_time
+# => 2025-04-24 04:45:42 UTC
+
+event.transit_time
+# => 2025-04-24 11:50:04 UTC
+
+event.setting_time
+# => 2025-04-24 18:55:24 UTC
+```
+
+## Drop of `RiseTransitSetIteration`
+
+`RiseTransitSetIteration` has been removed as it was only used by
+`Events::ObservationEvents`.
+
+## Drop of `Events::TwilightEvents`
+
+`Events::TwilightEvents` has been removed. The twilight times can now be
+calculated using `TwilightCalculator`.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48),
+  longitude: Astronoby::Angle.from_degrees(2)
+)
+date = Date.new(2025, 4, 24)
+
+calculator = Astronoby::TwilightCalculator.new(
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(date)
+# Returns a Astronoby::TwilightEvent object
+
+event.morning_astronomical_twilight_time
+# => 2025-04-24 02:43:38 UTC
+
+event.morning_nautical_twilight_time
+# => 2025-04-24 03:30:45 UTC
+
+event.morning_civil_twilight_time
+# => 2025-04-24 04:12:38 UTC
+
+event.evening_civil_twilight_time
+# => 2025-04-24 19:27:34 UTC
+
+event.evening_nautical_twilight_time
+# => 2025-04-24 20:09:27 UTC
+
+event.evening_astronomical_twilight_time
+# => 2025-04-24 20:56:34 UTC
+```
+
+## Drop of `EphemerideLunaireParisienne`
+
+`EphemerideLunaireParisienne` has been removed.
+
+## Drop of `Util::Astrodynamics`
+
+`Util::Astrodynamics` has been removed.
+
+## Drop of `Util::Maths.interpolate` and `Util::Maths.normalize_angles_for_interpolation`
+
+`Util::Maths.interpolate` and `Util::Maths.normalize_angles_for_interpolation`
+have been removed.
+
+## Drop of `Constants::SECONDS_PER_DEGREE`
+
+`Constants::SECONDS_PER_DEGREE` has been removed.
+
+## Upgrading from 0.5.0 to 0.6.0
+
+No breaking changes.
+
 ## Upgrading from 0.4.0 to 0.5.0
 
 ### `Sun#horizontal_coordinates` method signature changed ([#69])

data/lib/astronoby/aberration.rb

@@ -1,47 +1,72 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Applies relativistic aberration corrections to an astrometric position based
+  # on observer velocity.
   class Aberration
-    MAXIMUM_SHIFT = Angle.from_degrees(20.5)
+    # Source:
+    #  Title: Explanatory Supplement to the Astronomical Almanac
+    #  Authors: Sean E. Urban and P. Kenneth Seidelmann
+    #  Edition: University Science Books
+    #  Chapter: 7.2.3 - Aberration
 
-    def self.for_ecliptic_coordinates(coordinates:, epoch:)
-      new(coordinates, epoch).apply
-    end
+    LIGHT_SPEED = Astronoby::Velocity.light_speed.mps
 
-    def initialize(coordinates, epoch)
-      @coordinates = coordinates
-      @epoch = epoch
+    # Initializes the aberration correction with position and observer velocity.
+    #
+    # @param astrometric_position [Astronoby::Vector<Astronoby::Distance>] The
+    #   astrometric position vector.
+    # @param observer_velocity [Astronoby::Vector<Astronoby::Velocity>] The
+    #   velocity vector of the observer.
+    def initialize(astrometric_position:, observer_velocity:)
+      @position = astrometric_position
+      @velocity = observer_velocity
+      @distance_meters = @position.norm.m
+      @observer_speed = @velocity.norm.mps
     end
 
-    # Source:
-    #  Title: Practical Astronomy with your Calculator or Spreadsheet
-    #  Authors: Peter Duffett-Smith and Jonathan Zwart
-    #  Edition: Cambridge University Press
-    #  Chapter: 36 - Aberration
-    def apply
-      delta_longitude = Angle.from_degrees(
-        -MAXIMUM_SHIFT.degrees * (
-          sun_longitude - @coordinates.longitude
-        ).cos / @coordinates.latitude.cos / Constants::SECONDS_PER_DEGREE
-      )
+    # Computes the aberration-corrected position.
+    #
+    # @return [Astronoby::Vector<Astronoby::Distance>] The corrected position
+    #   vector.
+    def corrected_position
+      beta = @observer_speed / LIGHT_SPEED
+      projected_velocity = beta * aberration_angle_cos
+      lorentz_factor_inv = lorentz_factor_inverse(beta)
 
-      delta_latitude = Angle.from_degrees(
-        -MAXIMUM_SHIFT.degrees *
-        (sun_longitude - @coordinates.longitude).sin *
-        @coordinates.latitude.sin / Constants::SECONDS_PER_DEGREE
-      )
+      velocity_correction =
+        velocity_correction_factor(projected_velocity) * velocity_mps
+      normalization_factor = 1.0 + projected_velocity
+      position_scaled = position_meters * lorentz_factor_inv
 
-      Coordinates::Ecliptic.new(
-        latitude: @coordinates.latitude + delta_latitude,
-        longitude: @coordinates.longitude + delta_longitude
+      Distance.vector_from_meters(
+        (position_scaled + velocity_correction) / normalization_factor
       )
     end
 
-    def sun_longitude
-      @_sun_longitude ||= Sun
-        .new(time: Epoch.to_utc(@epoch))
-        .true_ecliptic_coordinates
-        .longitude
+    private
+
+    def aberration_angle_cos
+      denominator = [@distance_meters * @observer_speed, 1e-20].max
+      Util::Maths.dot_product(position_meters, velocity_mps) / denominator
+    end
+
+    def position_meters
+      @position.map(&:meters)
+    end
+
+    def velocity_mps
+      @velocity.map(&:mps)
+    end
+
+    def lorentz_factor_inverse(beta)
+      Math.sqrt(1.0 - beta**2)
+    end
+
+    def velocity_correction_factor(projected_velocity)
+      lorentz_inv = lorentz_factor_inverse(projected_velocity)
+      (1.0 + projected_velocity / (1.0 + lorentz_inv)) *
+        (@distance_meters / LIGHT_SPEED)
     end
   end
 end

data/lib/astronoby/angle.rb

@@ -22,6 +22,10 @@ module Astronoby
         from_radians(radians)
       end
 
+      def from_degree_arcseconds(arcseconds)
+        from_dms(0, 0, arcseconds)
+      end
+
       def from_hours(hours)
         radians = hours * Constants::RADIAN_PER_HOUR
         from_radians(radians)
@@ -120,10 +124,10 @@ module Astronoby
     end
     alias_method :eql?, :==
 
-    def str(format)
+    def str(format, precision: 4)
       case format
-      when :dms then to_dms(degrees).format
-      when :hms then to_hms(hours).format
+      when :dms then to_dms.format(precision: precision)
+      when :hms then to_hms.format(precision: precision)
       else
         raise UnsupportedFormatError.new(
           "Expected a format between #{FORMATS.join(", ")}, got #{format}"
@@ -131,36 +135,36 @@ module Astronoby
       end
     end
 
-    def to_dms(deg)
-      sign = deg.negative? ? "-" : "+"
-      absolute_degrees = deg.abs
-      degrees = absolute_degrees.floor
+    def to_dms
+      sign = degrees.negative? ? "-" : "+"
+      absolute_degrees = degrees.abs
+      deg = absolute_degrees.floor
       decimal_minutes = Constants::MINUTES_PER_DEGREE *
-        (absolute_degrees - degrees)
+        (absolute_degrees - deg)
       absolute_decimal_minutes = (
-        Constants::MINUTES_PER_DEGREE * (absolute_degrees - degrees)
+        Constants::MINUTES_PER_DEGREE * (absolute_degrees - deg)
       ).abs
       minutes = decimal_minutes.floor
       seconds = Constants::SECONDS_PER_MINUTE * (
         absolute_decimal_minutes - absolute_decimal_minutes.floor
       )
 
-      Dms.new(sign, degrees, minutes, seconds.floor(4))
+      Dms.new(sign, deg, minutes, seconds)
     end
 
-    def to_hms(hrs)
-      absolute_hours = hrs.abs
-      hours = absolute_hours.floor
-      decimal_minutes = Constants::MINUTES_PER_HOUR * (absolute_hours - hours)
+    def to_hms
+      absolute_hours = hours.abs
+      hrs = absolute_hours.floor
+      decimal_minutes = Constants::MINUTES_PER_HOUR * (absolute_hours - hrs)
       absolute_decimal_minutes = (
-        Constants::MINUTES_PER_HOUR * (absolute_hours - hours)
+        Constants::MINUTES_PER_HOUR * (absolute_hours - hrs)
       ).abs
       minutes = decimal_minutes.floor
       seconds = Constants::SECONDS_PER_MINUTE * (
         absolute_decimal_minutes - absolute_decimal_minutes.floor
       )
 
-      Hms.new(hours, minutes, seconds.floor(4))
+      Hms.new(hrs, minutes, seconds)
     end
   end
 end

data/lib/astronoby/angles/dms.rb

@@ -11,8 +11,8 @@ module Astronoby
       @seconds = seconds
     end
 
-    def format
-      "#{sign}#{degrees}° #{minutes}′ #{seconds}″"
+    def format(precision: 4)
+      "#{sign}#{degrees}° #{minutes}′ #{seconds.floor(precision)}″"
     end
   end
 end

data/lib/astronoby/angles/hms.rb

@@ -10,8 +10,8 @@ module Astronoby
       @seconds = seconds
     end
 
-    def format
-      "#{hours}h #{minutes}m #{seconds}s"
+    def format(precision: 4)
+      "#{hours}h #{minutes}m #{seconds.floor(precision)}s"
     end
   end
 end

data/lib/astronoby/bodies/earth.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Earth < SolarSystemBody
+    def self.ephemeris_segments(ephem_source)
+      if ephem_source == ::Ephem::SPK::JPL_DE
+        [
+          [SOLAR_SYSTEM_BARYCENTER, EARTH_MOON_BARYCENTER],
+          [EARTH_MOON_BARYCENTER, EARTH]
+        ]
+      elsif ephem_source == ::Ephem::SPK::INPOP
+        [
+          [SOLAR_SYSTEM_BARYCENTER, EARTH]
+        ]
+      end
+    end
+
+    private
+
+    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
+      )
+    end
+  end
+end

data/lib/astronoby/bodies/jupiter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Jupiter < SolarSystemBody
+    EQUATORIAL_RADIUS = Distance.from_meters(71_492_000)
+
+    def self.ephemeris_segments(_ephem_source)
+      [[SOLAR_SYSTEM_BARYCENTER, JUPITER_BARYCENTER]]
+    end
+  end
+end

data/lib/astronoby/bodies/mars.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Mars < SolarSystemBody
+    EQUATORIAL_RADIUS = Distance.from_meters(3_396_200)
+
+    def self.ephemeris_segments(_ephem_source)
+      [[SOLAR_SYSTEM_BARYCENTER, MARS_BARYCENTER]]
+    end
+  end
+end

data/lib/astronoby/bodies/mercury.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Mercury < SolarSystemBody
+    EQUATORIAL_RADIUS = Distance.from_meters(2_439_700)
+
+    def self.ephemeris_segments(_ephem_source)
+      [[SOLAR_SYSTEM_BARYCENTER, MERCURY_BARYCENTER]]
+    end
+  end
+end