astronoby 0.7.0 → 0.9.0

data/lib/astronoby/bodies/deep_sky_object_position.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class DeepSkyObjectPosition
+    DEFAULT_DISTANCE = Distance.from_parsecs(1e9)
+
+    attr_reader :instant, :apparent
+
+    # @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, nil] Proper motion in
+    #   right ascension
+    # @param proper_motion_dec [Astronoby::AngularVelocity, nil] Proper motion
+    #   in declination
+    # @param parallax [Astronoby::Angle, nil] Parallax angle
+    # @param radial_velocity [Astronoby::Velocity, nil] Radial velocity
+    def initialize(
+      instant:,
+      equatorial_coordinates:,
+      ephem: nil,
+      proper_motion_ra: nil,
+      proper_motion_dec: nil,
+      parallax: nil,
+      radial_velocity: nil
+    )
+      @instant = instant
+      @initial_equatorial_coordinates = equatorial_coordinates
+      @proper_motion_ra = proper_motion_ra
+      @proper_motion_dec = proper_motion_dec
+      @parallax = parallax
+      @radial_velocity = radial_velocity
+      if ephem
+        @earth_geometric = Earth.geometric(ephem: ephem, instant: @instant)
+      end
+      compute_apparent
+    end
+
+    # @return [Astronoby::Astrometric] Astrometric position of the object
+    def astrometric
+      @astrometric ||= Astrometric.new(
+        instant: @instant,
+        position: astrometric_position,
+        velocity: astrometric_velocity,
+        center_identifier: SolarSystemBody::EARTH,
+        target_body: self
+      )
+    end
+
+    def observed_by(observer)
+      Topocentric.build_from_apparent(
+        apparent: @apparent,
+        observer: observer,
+        instant: @instant,
+        target_body: self
+      )
+    end
+
+    private
+
+    def astrometric_position
+      @astrometric_position ||= if use_stellar_propagation?
+        stellar_propagation.position
+      else
+        astronomical_distance = DEFAULT_DISTANCE.meters
+        right_ascension = @initial_equatorial_coordinates.right_ascension
+        declination = @initial_equatorial_coordinates.declination
+        Distance.vector_from_meters([
+          declination.cos * right_ascension.cos * astronomical_distance,
+          declination.cos * right_ascension.sin * astronomical_distance,
+          declination.sin * astronomical_distance
+        ])
+      end
+    end
+
+    def astrometric_velocity
+      @astrometric_velocity ||= if use_stellar_propagation?
+        stellar_propagation.velocity_vector
+      else
+        Velocity.vector_from_meters_per_second([0.0, 0.0, 0.0])
+      end
+    end
+
+    def use_stellar_propagation?
+      @proper_motion_ra && @proper_motion_dec && @parallax && @radial_velocity
+    end
+
+    def stellar_propagation
+      @stellar_propagation ||= StellarPropagation.new(
+        equatorial_coordinates: @initial_equatorial_coordinates,
+        proper_motion_ra: @proper_motion_ra,
+        proper_motion_dec: @proper_motion_dec,
+        parallax: @parallax,
+        radial_velocity: @radial_velocity,
+        instant: @instant,
+        earth_geometric: @earth_geometric
+      )
+    end
+
+    def compute_apparent
+      @apparent = if @earth_geometric
+        Apparent.build_from_astrometric(
+          instant: @instant,
+          target_astrometric: astrometric,
+          earth_geometric: @earth_geometric,
+          target_body: self
+        )
+      else
+        precession_matrix = Precession.matrix_for(@instant)
+        nutation_matrix = Nutation.matrix_for(@instant)
+        corrected_position = Distance.vector_from_meters(
+          precession_matrix * nutation_matrix * astrometric.position.map(&:m)
+        )
+        corrected_velocity = Velocity.vector_from_mps(
+          precession_matrix * nutation_matrix * astrometric.velocity.map(&:mps)
+        )
+        Apparent.new(
+          position: corrected_position,
+          velocity: corrected_velocity,
+          instant: @instant,
+          center_identifier: SolarSystemBody::EARTH,
+          target_body: self
+        )
+      end
+    end
+  end
+end

data/lib/astronoby/bodies/earth.rb

@@ -15,9 +15,19 @@ module Astronoby
       end
     end
 
+    def phase_angle
+      nil
+    end
+
     private
 
-    def compute_astrometric(ephem)
+    # 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,
@@ -35,7 +45,7 @@ module Astronoby
       )
     end
 
-    def compute_mean_of_date(ephem)
+    def compute_mean_of_date(_ephem)
       MeanOfDate.new(
         position: Vector[
           Distance.zero,

data/lib/astronoby/bodies/jupiter.rb

@@ -3,9 +3,26 @@
 module Astronoby
   class Jupiter < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(71_492_000)
+    ABSOLUTE_MAGNITUDE = -9.395
 
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, JUPITER_BARYCENTER]]
     end
+
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
+    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
+      -3.7 * 10**-4 * phase_angle_degrees +
+        6.16 * 10**-4 * phase_angle_degrees * phase_angle_degrees
+    end
   end
 end

data/lib/astronoby/bodies/mars.rb

@@ -3,9 +3,26 @@
 module Astronoby
   class Mars < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(3_396_200)
+    ABSOLUTE_MAGNITUDE = -1.601
 
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MARS_BARYCENTER]]
     end
+
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
+    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
+      2.267 * 10**-2 * phase_angle_degrees -
+        1.302 * 10**-4 * phase_angle_degrees * phase_angle_degrees
+    end
   end
 end

data/lib/astronoby/bodies/mercury.rb

@@ -3,9 +3,30 @@
 module Astronoby
   class Mercury < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(2_439_700)
+    ABSOLUTE_MAGNITUDE = -0.613
 
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, MERCURY_BARYCENTER]]
     end
+
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
+    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
+      6.328 * 10**-2 * phase_angle_degrees -
+        1.6336 * 10**-3 * phase_angle_degrees * phase_angle_degrees +
+        3.3634 * 10**-5 * phase_angle_degrees**3 -
+        3.4265 * 10**-7 * phase_angle_degrees**4 +
+        1.6893 * 10**-9 * phase_angle_degrees**5 -
+        3.0334 * 10**-12 * phase_angle_degrees**6
+    end
   end
 end

data/lib/astronoby/bodies/moon.rb

@@ -4,6 +4,7 @@ module Astronoby
   class Moon < SolarSystemBody
     SEMIDIAMETER_VARIATION = 0.7275
     EQUATORIAL_RADIUS = Distance.from_meters(1_737_400)
+    ABSOLUTE_MAGNITUDE = 0.28
 
     def self.ephemeris_segments(ephem_source)
       if ephem_source == ::Ephem::SPK::JPL_DE
@@ -32,16 +33,8 @@ module Astronoby
       Events::MoonPhases.phases_for(year: year, month: month)
     end
 
-    attr_reader :phase_angle
-
-    def initialize(instant:, ephem:)
-      super
-      @phase_angle = compute_phase_angle(ephem)
-    end
-
-    # @return [Float] Moon's illuminated fraction
-    def illuminated_fraction
-      @illuminated_fraction ||= (1 + phase_angle.cos) / 2.0
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
     end
 
     # @return [Float] Phase fraction, from 0 to 1
@@ -49,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:
@@ -56,31 +70,6 @@ module Astronoby
     #  Author: Jean Meeus
     #  Edition: 2nd edition
     #  Chapter: 48 - Illuminated Fraction of the Moon's Disk
-
-    # @return [Angle] Moon's phase angle
-    def compute_phase_angle(ephem)
-      @phase_angle ||= begin
-        sun = Sun.new(instant: @instant, ephem: ephem)
-        geocentric_elongation = Angle.acos(
-          sun.apparent.equatorial.declination.sin *
-            apparent.equatorial.declination.sin +
-            sun.apparent.equatorial.declination.cos *
-              apparent.equatorial.declination.cos *
-              (
-                sun.apparent.equatorial.right_ascension -
-                  apparent.equatorial.right_ascension
-              ).cos
-        )
-
-        term1 = sun.astrometric.distance.km * geocentric_elongation.sin
-        term2 = astrometric.distance.km -
-          sun.astrometric.distance.km * geocentric_elongation.cos
-        angle = Angle.atan(term1 / term2)
-        Astronoby::Util::Trigonometry
-          .adjustement_for_arctangent(term1, term2, angle)
-      end
-    end
-
     def mean_elongation
       @mean_elongation ||= Angle.from_degrees(
         (
@@ -94,7 +83,32 @@ module Astronoby
     end
 
     def elapsed_centuries
-      (@instant.tt - Epoch::DEFAULT_EPOCH) / Constants::DAYS_PER_JULIAN_CENTURY
+      (@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
+      else
+        super
+      end
     end
   end
 end

data/lib/astronoby/bodies/neptune.rb

@@ -3,9 +3,30 @@
 module Astronoby
   class Neptune < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(24_764_000)
+    ABSOLUTE_MAGNITUDE = -7.0
 
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, NEPTUNE_BARYCENTER]]
     end
+
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
+    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 < 133 && @instant.tt > JulianDate::J2000
+        7.944 * 10**-3 * phase_angle_degrees +
+          9.617 * 10**-5 * phase_angle_degrees * phase_angle_degrees
+      else
+        super
+      end
+    end
   end
 end

data/lib/astronoby/bodies/saturn.rb

@@ -3,9 +3,35 @@
 module Astronoby
   class Saturn < SolarSystemBody
     EQUATORIAL_RADIUS = Distance.from_meters(60_268_000)
+    ABSOLUTE_MAGNITUDE = -8.914
 
     def self.ephemeris_segments(_ephem_source)
       [[SOLAR_SYSTEM_BARYCENTER, SATURN_BARYCENTER]]
     end
+
+    def self.absolute_magnitude
+      ABSOLUTE_MAGNITUDE
+    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 <= 6
+        -0.036 -
+          3.7 * 10**-4 * phase_angle_degrees +
+          6.16 * 10**-4 * phase_angle_degrees * phase_angle_degrees
+      else
+        0.026 +
+          2.446 * 10**-4 * phase_angle_degrees +
+          2.672 * 10**-4 * phase_angle_degrees * phase_angle_degrees -
+          1.505 * 10**-6 * phase_angle_degrees**3 +
+          4.767 * 10**-9 * phase_angle_degrees**4
+      end
+    end
   end
 end

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
@@ -27,42 +31,49 @@ module Astronoby
       segments = ephemeris_segments(ephem.type)
       segment1 = segments[0]
       segment2 = segments[1] if segments.size == 2
+      cache_key = CacheKey.generate(:geometric, instant, segment1, segment2)
 
-      state1 = ephem[*segment1].state_at(instant.terrestrial_time)
+      Astronoby.cache.fetch(cache_key) do
+        state1 = ephem[*segment1].state_at(instant.tt)
 
-      if segment2
-        state2 = ephem[*segment2].state_at(instant.terrestrial_time)
-        position = state1.position + state2.position
-        velocity = state1.velocity + state2.velocity
-      else
-        position = state1.position
-        velocity = state1.velocity
-      end
+        if segment2
+          state2 = ephem[*segment2].state_at(instant.tt)
+          position = state1.position + state2.position
+          velocity = state1.velocity + state2.velocity
+        else
+          position = state1.position
+          velocity = state1.velocity
+        end
 
-      position_vector = Vector[
-        Distance.from_kilometers(position.x),
-        Distance.from_kilometers(position.y),
-        Distance.from_kilometers(position.z)
-      ]
-
-      velocity_vector = Vector[
-        Velocity.from_kilometers_per_day(velocity.x),
-        Velocity.from_kilometers_per_day(velocity.y),
-        Velocity.from_kilometers_per_day(velocity.z)
-      ]
-
-      Geometric.new(
-        position: position_vector,
-        velocity: velocity_vector,
-        instant: instant,
-        target_body: self
-      )
+        position_vector = Vector[
+          Distance.from_kilometers(position.x),
+          Distance.from_kilometers(position.y),
+          Distance.from_kilometers(position.z)
+        ]
+
+        velocity_vector = Vector[
+          Velocity.from_kilometers_per_day(velocity.x),
+          Velocity.from_kilometers_per_day(velocity.y),
+          Velocity.from_kilometers_per_day(velocity.z)
+        ]
+
+        Geometric.new(
+          position: position_vector,
+          velocity: velocity_vector,
+          instant: instant,
+          target_body: self
+        )
+      end
     end
 
     def self.ephemeris_segments(_ephem_source)
       raise NotImplementedError
     end
 
+    def self.absolute_magnitude
+      nil
+    end
+
     def initialize(ephem:, instant:)
       @instant = instant
       @geometric = compute_geometric(ephem)
@@ -74,6 +85,7 @@ module Astronoby
           target: @geometric,
           ephem: ephem
         )
+      compute_sun(ephem) if requires_sun_data?
     end
 
     def astrometric
@@ -113,10 +125,133 @@ module Astronoby
       )
     end
 
+    # Returns the constellation of the body
+    # @return [Astronoby::Constellation, nil]
+    def constellation
+      @constellation ||= Constellations::Finder.find(
+        Precession.for_equatorial_coordinates(
+          coordinates: astrometric.equatorial,
+          epoch: JulianDate::B1875
+        )
+      )
+    end
+
+    # Source:
+    #  Title: Astronomical Algorithms
+    #  Author: Jean Meeus
+    #  Edition: 2nd edition
+    #  Chapter: 48 - Illuminated Fraction of the Moon's Disk
+    # @return [Astronoby::Angle, nil] Phase angle of the body
+    def phase_angle
+      return unless @sun
+
+      @phase_angle ||= begin
+        geocentric_elongation = Angle.acos(
+          @sun.apparent.equatorial.declination.sin *
+          apparent.equatorial.declination.sin +
+          @sun.apparent.equatorial.declination.cos *
+          apparent.equatorial.declination.cos *
+          (
+            @sun.apparent.equatorial.right_ascension -
+              apparent.equatorial.right_ascension
+          ).cos
+        )
+
+        term1 = @sun.astrometric.distance.km * geocentric_elongation.sin
+        term2 = astrometric.distance.km -
+          @sun.astrometric.distance.km * geocentric_elongation.cos
+        angle = Angle.atan(term1 / term2)
+        Astronoby::Util::Trigonometry
+          .adjustement_for_arctangent(term1, term2, angle)
+      end
+    end
+
+    # Fraction between 0 and 1 of the body's disk that is illuminated.
+    # @return [Float, nil] Body's illuminated fraction, between 0 and 1.
+    def illuminated_fraction
+      return unless phase_angle
+
+      @illuminated_fraction ||= (1 + phase_angle.cos) / 2.0
+    end
+
+    # Source:
+    #  Title: Astronomical Algorithms
+    #  Author: Jean Meeus
+    #  Edition: 2nd edition
+    #  Chapter: 48 - Illuminated Fraction of the Moon's Disk
+    # Apparent magnitude of the body, as seen from Earth.
+    # @return [Float, nil] Apparent magnitude of the body.
+    def apparent_magnitude
+      return unless self.class.absolute_magnitude
+
+      @apparent_magnitude ||= begin
+        body_sun_distance =
+          (astrometric.position - @sun.astrometric.position).magnitude
+        self.class.absolute_magnitude +
+          5 * Math.log10(body_sun_distance.au * astrometric.distance.au) +
+          magnitude_correction_term
+      end
+    end
+
+    # Angular diameter of the body, as seen from Earth. Based on the apparent
+    #   position of the body.
+    # @return [Astronoby::Angle] Angular diameter of the body
+    def angular_diameter
+      @angular_radius ||= begin
+        return if apparent.position.zero?
+
+        Angle.from_radians(
+          Math.asin(self.class::EQUATORIAL_RADIUS.m / apparent.distance.m) * 2
+        )
+      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
+    # the Sun's position, such as phase angle and illuminated fraction.
+    # If a body does not require Sun data, it should override this method to
+    # return false.
+    def requires_sun_data?
+      true
+    end
+
     def compute_geometric(ephem)
       self.class.compute_geometric(ephem: ephem, instant: @instant)
     end
+
+    def compute_sun(ephem)
+      @sun ||= Sun.new(instant: @instant, ephem: ephem)
+    end
+
+    # Source:
+    #  Title: Explanatory Supplement to the Astronomical Almanac
+    #  Authors: Sean E. Urban and P. Kenneth Seidelmann
+    #  Edition: University Science Books
+    #  Chapter: 10.3 - Phases and Magnitudes
+    def magnitude_correction_term
+      -2.5 * Math.log10(illuminated_fraction)
+    end
   end
 end