astronoby 0.9.0 → 0.11.0

data/lib/astronoby/bodies/earth.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the Earth. Provides ephemeris segments for computing Earth's
+  # geometric position.
   class Earth < SolarSystemBody
+    ORBITAL_PERIOD = 365.256
+
+    # @param ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(ephem_source)
       if ephem_source == ::Ephem::SPK::JPL_DE
         [
@@ -15,52 +21,9 @@ module Astronoby
       end
     end
 
+    # @return [nil] Earth has no phase angle as seen from itself
     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?
-      true
-    end
-
-    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

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Jupiter.
   class Jupiter < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(71_492_000)
     ABSOLUTE_MAGNITUDE = -9.395
+    ORBITAL_PERIOD = 4332.59
 
+    # @return [Boolean] true; Jupiter is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, JUPITER_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/mars.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Mars.
   class Mars < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(3_396_200)
     ABSOLUTE_MAGNITUDE = -1.601
+    ORBITAL_PERIOD = 686.98
 
+    # @return [Boolean] true; Mars is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MARS_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/mercury.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Mercury.
   class Mercury < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(2_439_700)
     ABSOLUTE_MAGNITUDE = -0.613
+    ORBITAL_PERIOD = 87.969
 
+    # @return [Boolean] true; Mercury is an inferior planet
+    def self.inferior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MERCURY_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/moon.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the Moon. Provides phase events, apoapsis/periapsis events,
+  # and phase fraction.
   class Moon < SolarSystemBody
     SEMIDIAMETER_VARIATION = 0.7275
     EQUATORIAL_RADIUS = Distance.from_meters(1_737_400)
     ABSOLUTE_MAGNITUDE = 0.28
+    ORBITAL_PERIOD = 27.504339
 
+    # @param ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(ephem_source)
       if ephem_source == ::Ephem::SPK::JPL_DE
         [
@@ -33,38 +38,155 @@ module Astronoby
       Events::MoonPhases.phases_for(year: year, month: month)
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end
 
+    # Finds all apoapsis events between two times
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of apoapsis events
+    def self.apoapsis_events(
+      ephem:,
+      start_time:,
+      end_time:,
+      samples_per_period: 60
+    )
+      ExtremumCalculator.new(
+        body: self,
+        primary_body: Earth,
+        ephem: ephem,
+        samples_per_period: samples_per_period
+      ).apoapsis_events_between(start_time, end_time)
+    end
+
+    # Finds all periapsis events between two times
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::ExtremumEvent>] Array of periapsis events
+    def self.periapsis_events(
+      ephem:,
+      start_time:,
+      end_time:,
+      samples_per_period: 60
+    )
+      ExtremumCalculator.new(
+        body: self,
+        primary_body: Earth,
+        ephem: ephem,
+        samples_per_period: samples_per_period
+      ).periapsis_events_between(start_time, end_time)
+    end
+
+    # Finds all lunar eclipses whose greatest instant falls between two times
+    # @param ephem [::Ephem::SPK] Ephemeris data source
+    # @param start_time [Time] Start time
+    # @param end_time [Time] End time
+    # @return [Array<Astronoby::LunarEclipse>] Lunar eclipses in the range
+    def self.eclipse_events(ephem:, start_time:, end_time:)
+      LunarEclipseCalculator
+        .new(ephem: ephem)
+        .events_between(start_time, end_time)
+    end
+
     # @return [Float] Phase fraction, from 0 to 1
     def current_phase_fraction
       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
+    # Total geocentric libration of the Moon, in longitude and latitude.
+    #
+    # With an orientation kernel (see +orientation:+ on the constructor), this
+    # is the sub-Earth point from the integrated DE orientation, accurate to
+    # better than an arcsecond. Without one, it is the analytic optical plus
+    # physical libration (Meeus, Astronomical Algorithms, 2nd ed., chapter 53).
+    #
+    # @return [Astronoby::Libration] Libration in longitude and latitude
+    def libration
+      lunar_ephemeris.libration
+    end
+
+    # Position angle of the Moon's axis of rotation, measured eastward from the
+    # north point of the disk.
+    #
+    # With an orientation kernel this comes from the integrated DE orientation;
+    # without one, from the analytic series (Meeus, Astronomical Algorithms,
+    # 2nd ed., chapter 53).
+    #
+    # @return [Astronoby::Angle] Position angle of the axis
+    def position_angle_of_axis
+      lunar_ephemeris.position_angle_of_axis
     end
 
-    # @return [Boolean] True if the body is receding from the primary
-    #   body (Earth), false otherwise.
-    def receding_from_primary?
-      !approaching_primary?
+    # Position angle of the Moon's bright limb: the position angle of the
+    # midpoint of the illuminated limb, measured eastward from the north point
+    # of the disk. Geocentric, from the apparent equatorial coordinates of the
+    # Moon and the Sun.
+    #
+    # Source:
+    #  Title: Astronomical Algorithms
+    #  Author: Jean Meeus
+    #  Edition: 2nd edition
+    #  Chapter: 48 - Illuminated Fraction of the Moon's Disk
+    # @return [Astronoby::Angle, nil] Position angle of the bright limb, between
+    #   0 and 360 degrees
+    def bright_limb_position_angle
+      return unless sun
+
+      @bright_limb_position_angle ||= begin
+        angle = apparent.equatorial.position_angle_to(sun.apparent.equatorial)
+        Angle.from_degrees(angle.degrees % Constants::DEGREES_PER_CIRCLE)
+      end
+    end
+
+    # Parallactic angle of the Moon for a given observer: the angle at the Moon
+    # between the direction of the north celestial pole and the direction of
+    # the observer's zenith. Computed from the topocentric place, where lunar
+    # parallax is significant.
+    #
+    # Source:
+    #  Title: Astronomical Algorithms
+    #  Author: Jean Meeus
+    #  Edition: 2nd edition
+    #  Chapter: 14 - The Parallactic Angle
+    # @param observer [Astronoby::Observer] Observer for whom to compute the
+    #   parallactic angle
+    # @return [Astronoby::Angle] Parallactic angle
+    def parallactic_angle(observer:)
+      equatorial = observed_by(observer).equatorial
+      declination = equatorial.declination
+      hour_angle = equatorial.compute_hour_angle(
+        time: @instant.to_time,
+        longitude: observer.longitude
+      )
+
+      Angle.from_radians(
+        Math.atan2(
+          hour_angle.sin,
+          observer.latitude.tan * declination.cos -
+            declination.sin * hour_angle.cos
+        )
+      )
     end
 
     private
 
+    def lunar_ephemeris
+      @lunar_ephemeris ||=
+        if orientation
+          MoonOrientationEphemeris.new(self)
+        else
+          MoonPhysicalEphemeris.new(self)
+        end
+    end
+
+    def primary_body_geometric
+      earth_geometric
+    end
+
     # Source:
     #  Title: Astronomical Algorithms
     #  Author: Jean Meeus
@@ -86,29 +208,33 @@ module Astronoby
       (@instant.tt - JulianDate::DEFAULT_EPOCH) / Constants::DAYS_PER_JULIAN_CENTURY
     end
 
-    private
-
     # Source:
     #  Title: Computing Apparent Planetary Magnitudes for The Astronomical
     #    Almanac (2018)
     #  Authors: Anthony Mallama and James L. Hilton
     def magnitude_correction_term
       phase_angle_degrees = phase_angle.degrees
-      if phase_angle_degrees <= 150 && current_phase_fraction <= 0.5
-        2.9994 * 10**-2 * phase_angle_degrees -
-          1.6057 * 10**-4 * phase_angle_degrees**2 +
-          3.1543 * 10**-6 * phase_angle_degrees**3 -
-          2.0667 * 10**-8 * phase_angle_degrees**4 +
-          6.2553 * 10**-11 * phase_angle_degrees**5
-      elsif phase_angle_degrees <= 150 && current_phase_fraction > 0.5
-        3.3234 * 10**-2 * phase_angle_degrees -
-          3.0725 * 10**-4 * phase_angle_degrees**2 +
-          6.1575 * 10**-6 * phase_angle_degrees**3 -
-          4.7723 * 10**-8 * phase_angle_degrees**4 +
-          1.4681 * 10**-10 * phase_angle_degrees**5
+      if phase_angle_degrees <= 150 && current_phase_fraction > 0.5
+        waning_magnitude_correction(phase_angle_degrees)
       else
-        super
+        waxing_magnitude_correction(phase_angle_degrees)
       end
     end
+
+    def waxing_magnitude_correction(phase_angle_degrees)
+      2.9994 * 10**-2 * phase_angle_degrees -
+        1.6057 * 10**-4 * phase_angle_degrees**2 +
+        3.1543 * 10**-6 * phase_angle_degrees**3 -
+        2.0667 * 10**-8 * phase_angle_degrees**4 +
+        6.2553 * 10**-11 * phase_angle_degrees**5
+    end
+
+    def waning_magnitude_correction(phase_angle_degrees)
+      3.3234 * 10**-2 * phase_angle_degrees -
+        3.0725 * 10**-4 * phase_angle_degrees**2 +
+        6.1575 * 10**-6 * phase_angle_degrees**3 -
+        4.7723 * 10**-8 * phase_angle_degrees**4 +
+        1.4681 * 10**-10 * phase_angle_degrees**5
+    end
   end
 end

data/lib/astronoby/bodies/neptune.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Neptune.
   class Neptune < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(24_764_000)
     ABSOLUTE_MAGNITUDE = -7.0
+    ORBITAL_PERIOD = 60182.0
 
+    # @return [Boolean] true; Neptune is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, NEPTUNE_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end

data/lib/astronoby/bodies/saturn.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents Saturn.
   class Saturn < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(60_268_000)
     ABSOLUTE_MAGNITUDE = -8.914
+    ORBITAL_PERIOD = 10759.22
 
+    # @return [Boolean] true; Saturn is a superior planet
+    def self.superior_planet?
+      true
+    end
+
+    # @param _ephem_source [Symbol] the ephemeris source type
+    # @return [Array<Array>] ephemeris segment identifiers
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, SATURN_BARYCENTER]]
     end
 
+    # @return [Float] absolute magnitude
     def self.absolute_magnitude
       ABSOLUTE_MAGNITUDE
     end