astronoby 0.9.0 → 0.11.0

data/lib/astronoby/moon_physical_ephemeris.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes the ephemeris for physical observations of the Moon: the total
+  # (optical + physical) libration in longitude and latitude, and the position
+  # angle of the Moon's axis of rotation.
+  #
+  # Source:
+  #  Title: Astronomical Algorithms
+  #  Author: Jean Meeus
+  #  Edition: 2nd edition
+  #  Chapter: 53 - Ephemeris for Physical Observations of the Moon
+  class MoonPhysicalEphemeris
+    # Inclination of the mean lunar equator to the ecliptic
+    INCLINATION = Angle.from_degrees(1.54242)
+
+    # @param moon [Astronoby::Moon] the Moon at the desired instant
+    def initialize(moon)
+      @moon = moon
+      @instant = moon.instant
+    end
+
+    # @return [Astronoby::Libration] the total libration in longitude and
+    #   latitude
+    def libration
+      Libration.new(
+        longitude: Angle.from_degrees(libration_in_longitude),
+        latitude: Angle.from_degrees(libration_in_latitude)
+      )
+    end
+
+    # @return [Astronoby::Angle] the position angle of the Moon's axis of
+    #   rotation, measured eastward from the north point of the disk
+    def position_angle_of_axis
+      i_rho = INCLINATION + Angle.from_degrees(rho)
+      v = ascending_node +
+        nutation_in_longitude +
+        Angle.from_degrees(sigma / INCLINATION.sin)
+
+      x = i_rho.sin * v.sin
+      y = i_rho.sin * v.cos * obliquity.cos - i_rho.cos * obliquity.sin
+      omega = Math.atan2(x, y)
+
+      Angle.from_radians(
+        Math.asin(
+          Math.sqrt(x * x + y * y) *
+            Math.cos(right_ascension.radians - omega) /
+            Angle.from_degrees(libration_in_latitude).cos
+        )
+      )
+    end
+
+    private
+
+    # @return [Float] total libration in longitude, in degrees, in (-180, 180]
+    def libration_in_longitude
+      l = optical_longitude + physical_longitude
+      ((l + 180) % 360) - 180
+    end
+
+    # @return [Float] total libration in latitude, in degrees
+    def libration_in_latitude
+      optical_latitude + physical_latitude
+    end
+
+    # Optical libration in longitude, l' = A - F (Meeus 53.1)
+    # @return [Float] in degrees
+    def optical_longitude
+      argument_a.degrees - argument_of_latitude.degrees
+    end
+
+    # Optical libration in latitude (Meeus 53.1)
+    # @return [Float] in degrees
+    def optical_latitude
+      Angle.from_radians(optical_latitude_radians).degrees
+    end
+
+    # Physical libration in longitude (Meeus 53.2)
+    # @return [Float] in degrees
+    def physical_longitude
+      -tau +
+        (rho * argument_a.cos + sigma * argument_a.sin) *
+          Math.tan(optical_latitude_radians)
+    end
+
+    # Physical libration in latitude (Meeus 53.2)
+    # @return [Float] in degrees
+    def physical_latitude
+      sigma * argument_a.cos - rho * argument_a.sin
+    end
+
+    # The argument "A" of the optical libration (Meeus 53.1)
+    def argument_a
+      @argument_a ||= Angle.from_radians(
+        Math.atan2(
+          w.sin * latitude.cos * INCLINATION.cos -
+            latitude.sin * INCLINATION.sin,
+          w.cos * latitude.cos
+        )
+      )
+    end
+
+    def optical_latitude_radians
+      @optical_latitude_radians ||= Math.asin(
+        -w.sin * latitude.cos * INCLINATION.sin - latitude.sin * INCLINATION.cos
+      )
+    end
+
+    # W = λ - Δψ - Ω, the Moon's longitude referred to the mean equinox of
+    # date, measured from the ascending node of the mean lunar equator
+    def w
+      @w ||= longitude - nutation_in_longitude - ascending_node
+    end
+
+    # @return [Float] periodic terms ρ, in degrees (Meeus 53)
+    def rho
+      @rho ||= trig_series([
+        [-0.02752, mp.radians, :cos],
+        [-0.02245, f.radians, :sin],
+        [0.00684, (mp - f - f).radians, :cos],
+        [-0.00293, (f + f).radians, :cos],
+        [-0.00085, (f + f - d - d).radians, :cos],
+        [-0.00054, (mp - d - d).radians, :cos],
+        [-0.00020, (mp + f).radians, :sin],
+        [-0.00020, (mp + f + f).radians, :cos],
+        [-0.00020, (mp - f).radians, :cos],
+        [0.00014, (mp + f + f - d - d).radians, :cos]
+      ])
+    end
+
+    # @return [Float] periodic terms σ, in degrees (Meeus 53)
+    def sigma
+      @sigma ||= trig_series([
+        [-0.02816, mp.radians, :sin],
+        [0.02244, f.radians, :cos],
+        [-0.00682, (mp - f - f).radians, :sin],
+        [-0.00279, (f + f).radians, :sin],
+        [-0.00083, (f + f - d - d).radians, :sin],
+        [0.00069, (mp - d - d).radians, :sin],
+        [0.00040, (mp + f).radians, :cos],
+        [-0.00025, (mp + mp).radians, :sin],
+        [-0.00023, (mp + f + f).radians, :sin],
+        [0.00020, (mp - f).radians, :cos],
+        [0.00019, (mp - f).radians, :sin],
+        [0.00013, (mp + f + f - d - d).radians, :sin],
+        [-0.00010, (mp - f - f - f).radians, :cos]
+      ])
+    end
+
+    # @return [Float] periodic terms τ, in degrees (Meeus 53)
+    def tau
+      @tau ||= trig_series([
+        [0.02520 * eccentricity, m.radians, :sin],
+        [0.00473, (mp + mp - f - f).radians, :sin],
+        [-0.00467, mp.radians, :sin],
+        [0.00396, k1.radians, :sin],
+        [0.00276, (mp + mp - d - d).radians, :sin],
+        [0.00196, ascending_node.radians, :sin],
+        [-0.00183, (mp - f).radians, :cos],
+        [0.00115, (mp - d - d).radians, :sin],
+        [-0.00096, (mp - d).radians, :sin],
+        [0.00046, (f + f - d - d).radians, :sin],
+        [-0.00039, (mp - f).radians, :sin],
+        [-0.00032, (mp - m - d).radians, :sin],
+        [0.00027, (mp + mp - m - d - d).radians, :sin],
+        [0.00023, k2.radians, :sin],
+        [-0.00014, (d + d).radians, :sin],
+        [0.00014, (mp + mp - f - f).radians, :cos],
+        [-0.00012, (mp - f - f).radians, :sin],
+        [-0.00012, (mp + mp).radians, :sin],
+        [0.00011, (mp + mp - m - m - d - d).radians, :sin]
+      ])
+    end
+
+    def trig_series(terms)
+      terms.sum do |coefficient, argument, fn|
+        coefficient * Math.send(fn, argument)
+      end
+    end
+
+    # Apparent geocentric ecliptic longitude (true equinox of date, λ)
+    def longitude
+      @longitude ||= @moon.apparent.ecliptic.longitude
+    end
+
+    # Apparent geocentric ecliptic latitude (β)
+    def latitude
+      @latitude ||= @moon.apparent.ecliptic.latitude
+    end
+
+    # Apparent geocentric right ascension (α)
+    def right_ascension
+      @right_ascension ||= @moon.apparent.equatorial.right_ascension
+    end
+
+    def obliquity
+      @obliquity ||= TrueObliquity.at(@instant)
+    end
+
+    def nutation_in_longitude
+      @nutation_in_longitude ||=
+        Nutation.new(instant: @instant).nutation_in_longitude
+    end
+
+    def t
+      @t ||=
+        (@instant.tt - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
+    end
+
+    # Mean elongation of the Moon (D), Meeus 47.5
+    def d
+      @d ||= Angle.from_degrees(
+        297.8501921 + 445267.1114034 * t - 0.0018819 * t**2 +
+          t**3 / 545868 - t**4 / 113065000
+      )
+    end
+
+    # Sun's mean anomaly (M), Meeus 47.3
+    def m
+      @m ||= Angle.from_degrees(
+        357.5291092 + 35999.0502909 * t - 0.0001536 * t**2 + t**3 / 24490000
+      )
+    end
+
+    # Moon's mean anomaly (M'), Meeus 47.4
+    def mp
+      @mp ||= Angle.from_degrees(
+        134.9633964 + 477198.8675055 * t + 0.0087414 * t**2 +
+          t**3 / 69699 - t**4 / 14712000
+      )
+    end
+
+    # Moon's argument of latitude (F), Meeus 47.5
+    def f
+      @f ||= Angle.from_degrees(
+        93.2720950 + 483202.0175233 * t - 0.0036539 * t**2 -
+          t**3 / 3526000 + t**4 / 863310000
+      )
+    end
+    alias_method :argument_of_latitude, :f
+
+    # Longitude of the mean ascending node (Ω), Meeus 47.7
+    def ascending_node
+      @ascending_node ||= Angle.from_degrees(
+        125.0445479 - 1934.1362891 * t + 0.0020754 * t**2 +
+          t**3 / 467441 - t**4 / 60616000
+      )
+    end
+
+    # Eccentricity correction (E), Meeus 47.6
+    def eccentricity
+      @eccentricity ||= 1 - 0.002516 * t - 0.0000074 * t**2
+    end
+
+    def k1
+      @k1 ||= Angle.from_degrees(119.75 + 131.849 * t)
+    end
+
+    def k2
+      @k2 ||= Angle.from_degrees(72.56 + 20.186 * t)
+    end
+  end
+end

data/lib/astronoby/nutation.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes nutation using the IAU 2000B model (77-term series).
+  # Provides both the nutation matrix and the individual nutation angles
+  # (in longitude and obliquity).
   class Nutation
     # IAU 2000B model corrections (in microarcseconds)
     IAU2000B_DPSI_CORRECTION = -0.000135e7
@@ -139,31 +142,18 @@ module Astronoby
       dpsi = 0.0
       deps = 0.0
 
-      NUTATION_TERMS.each do |term|
-        # Extract the fundamental argument coefficients
-        arg_coef = term[0..4]
+      radians = a.map(&:radians)
+      jc = julian_centuries
 
-        # Calculate the argument
-        arg = Util::Maths.dot_product(arg_coef, a.map(&:radians))
+      NUTATION_TERMS.each do |term|
+        arg = term[0] * radians[0] + term[1] * radians[1] +
+          term[2] * radians[2] + term[3] * radians[3] + term[4] * radians[4]
 
         sin_arg = Math.sin(arg)
         cos_arg = Math.cos(arg)
 
-        # Extract longitude coefficients
-        long_coef = term[5..7]
-
-        # Extract obliquity coefficients
-        obl_coef = term[8..10]
-
-        # Update dpsi using longitude coefficients
-        dpsi += long_coef[0] * sin_arg
-        dpsi += long_coef[1] * sin_arg * julian_centuries
-        dpsi += long_coef[2] * cos_arg
-
-        # Update deps using obliquity coefficients
-        deps += obl_coef[0] * cos_arg
-        deps += obl_coef[1] * cos_arg * julian_centuries
-        deps += obl_coef[2] * sin_arg
+        dpsi += term[5] * sin_arg + term[6] * sin_arg * jc + term[7] * cos_arg
+        deps += term[8] * cos_arg + term[9] * cos_arg * jc + term[10] * sin_arg
       end
 
       [dpsi, deps] # in microarcseconds

data/lib/astronoby/observer.rb

@@ -10,15 +10,26 @@ module Astronoby
     MOLAR_MASS_OF_AIR = 0.0289644
     UNIVERSAL_GAS_CONSTANT = 8.31432
 
-    attr_reader :latitude,
-      :longitude,
-      :elevation,
-      :utc_offset,
-      :temperature,
-      :pressure
-
-    # @param latitude [Angle] geographic latitude of the observer
-    # @param longitude [Angle] geographic longitude of the observer
+    # @return [Astronoby::Angle] geographic latitude
+    attr_reader :latitude
+
+    # @return [Astronoby::Angle] geographic longitude
+    attr_reader :longitude
+
+    # @return [Astronoby::Distance] geographic elevation above sea level
+    attr_reader :elevation
+
+    # @return [Numeric, String] offset from Coordinated Universal Time
+    attr_reader :utc_offset
+
+    # @return [Numeric] temperature in kelvins
+    attr_reader :temperature
+
+    # @return [Numeric] atmospheric pressure in millibars
+    attr_reader :pressure
+
+    # @param latitude [Astronoby::Angle] geographic latitude of the observer
+    # @param longitude [Astronoby::Angle] geographic longitude of the observer
     # @param elevation [Astronoby::Distance] geographic elevation (or altitude)
     #   of the observer above sea level
     # @param utc_offset [Numeric, String] offset from Coordinated Universal Time
@@ -42,45 +53,44 @@ module Astronoby
       @pressure = pressure || compute_pressure
     end
 
+    # Returns the observer's ECEF position vector (WGS-84 geodetic to ECEF).
+    #
+    # @return [Astronoby::Vector<Astronoby::Distance>] geocentric position
     def geocentric_position
-      n = earth_prime_vertical_radius_of_curvature
-      x = (n + @elevation.m) * @latitude.cos * @longitude.cos
-      y = (n + @elevation.m) * @latitude.cos * @longitude.sin
-      z = (n * (1 - Constants::WGS84_ECCENTICITY_SQUARED) + @elevation.m) *
-        @latitude.sin
-      Distance.vector_from_meters([x, y, z])
+      @geocentric_position ||= begin
+        n = earth_prime_vertical_radius_of_curvature
+        x = (n + @elevation.m) * @latitude.cos * @longitude.cos
+        y = (n + @elevation.m) * @latitude.cos * @longitude.sin
+        z = (n * (1 - Constants::WGS84_ECCENTICITY_SQUARED) + @elevation.m) *
+          @latitude.sin
+        Distance.vector_from_meters([x, y, z])
+      end
     end
 
+    # Returns the observer's ECEF velocity vector due to Earth rotation.
+    #
+    # @return [Astronoby::Vector<Astronoby::Velocity>] geocentric velocity
     def geocentric_velocity
-      r = projected_radius
-      vx = -Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S * r * @longitude.sin
-      vy = Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S * r * @longitude.cos
-      vz = 0.0
-      Velocity.vector_from_mps([vx, vy, vz])
+      @geocentric_velocity ||= begin
+        r = projected_radius
+        vx = -Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S * r * @longitude.sin
+        vy = Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S * r * @longitude.cos
+        vz = 0.0
+        Velocity.vector_from_mps([vx, vy, vz])
+      end
     end
 
+    # Computes the Earth-fixed rotation matrix R₃(GAST) * W (polar motion)
+    # for a given instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 rotation matrix
     def earth_fixed_rotation_matrix_for(instant)
-      dpsi = Nutation.new(instant: instant).nutation_in_longitude
-
-      mean_obliquity = MeanObliquity.at(instant)
-
-      gast = Angle.from_radians(
-        Angle.from_hours(instant.gmst).radians +
-          dpsi.radians * mean_obliquity.cos
-      )
-
-      earth_rotation_matrix = Matrix[
-        [gast.cos, -gast.sin, 0],
-        [gast.sin, gast.cos, 0],
-        [0, 0, 1]
-      ]
-
-      nutation_matrix = Nutation.matrix_for(instant)
-      precession_matrix = Precession.matrix_for(instant)
-
-      earth_rotation_matrix * nutation_matrix * precession_matrix
+      EarthRotation.matrix_for(instant) * polar_motion_matrix_for(instant)
     end
 
+    # @param other [Astronoby::Observer] observer to compare with
+    # @return [Boolean] true if all attributes are equal
     def ==(other)
       return false unless other.is_a?(self.class)
 
@@ -93,6 +103,7 @@ module Astronoby
     end
     alias_method :eql?, :==
 
+    # @return [Integer] hash value
     def hash
       [
         self.class,
@@ -107,7 +118,6 @@ module Astronoby
 
     private
 
-    # @return [Float] the atmospheric pressure in millibars.
     def compute_pressure
       @pressure ||= PRESSURE_AT_SEA_LEVEL * pressure_ratio
     end
@@ -124,20 +134,28 @@ module Astronoby
       Math.exp(-term1 / term2)
     end
 
+    def polar_motion_matrix_for(instant)
+      rows = IERS::PolarMotion.rotation_matrix_at(instant.to_time)
+      Matrix[*rows]
+    rescue IERS::OutOfRangeError
+      Matrix.identity(3)
+    end
+
     def earth_prime_vertical_radius_of_curvature
-      Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS./(
-        Math.sqrt(
-          1 -
-            Constants::WGS84_ECCENTICITY_SQUARED * @latitude.sin * @latitude.sin
+      @earth_prime_vertical_radius_of_curvature ||=
+        Constants::WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS./(
+          Math.sqrt(
+            1 -
+              Constants::WGS84_ECCENTICITY_SQUARED * @latitude.sin * @latitude.sin
+          )
         )
-      )
     end
 
     def projected_radius
-      Math.sqrt(
-        geocentric_position.x.m * geocentric_position.x.m +
-          geocentric_position.y.m * geocentric_position.y.m
-      )
+      @projected_radius ||= begin
+        pos = geocentric_position
+        Math.sqrt(pos.x.m * pos.x.m + pos.y.m * pos.y.m)
+      end
     end
   end
 end

data/lib/astronoby/orientation.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "ephem"
+require "matrix"
+
+module Astronoby
+  # Wraps a binary PCK lunar orientation kernel (for example
+  # +moon_pa_de440_200625.bpc+) and exposes the rotation from the inertial frame
+  # (J2000/ICRF) to the Moon's mean-Earth (ME) body-fixed frame at a given
+  # instant.
+  #
+  # A binary kernel only provides the principal-axis (PA) orientation, and which
+  # PA frame it describes is read from the kernel itself. JPL Horizons and IMCCE
+  # report selenographic positions in the mean-Earth frame, whose small fixed
+  # offset from the principal axes is published in the NAIF lunar frame kernels
+  # (the +moon_*.tf+ files) rather than in the binary kernel. That alignment is
+  # essentially constant across ephemeris versions (below 0.15 arcsecond), so
+  # the DE440 values are applied here.
+  class Orientation
+    # Principal-axis to mean-Earth alignment from the NAIF DE440 lunar frame
+    # kernel (moon_de440_250416.tf): the rotation angles about the z, y and x
+    # axes that align the principal-axis frame with the mean-Earth frame.
+    MEAN_EARTH_ALIGNMENT = [
+      Angle.from_degree_arcseconds(67.8526),
+      Angle.from_degree_arcseconds(78.6944),
+      Angle.from_degree_arcseconds(0.2785)
+    ].freeze
+
+    # Download a binary PCK orientation kernel.
+    #
+    # @param name [String] kernel name supported by the Ephem gem
+    # @param target [String] destination path
+    # @return [Boolean] true if the download was successful
+    def self.download(name:, target:)
+      ::Ephem::Download.call(name: name, target: target)
+    end
+
+    # Load a binary PCK orientation kernel.
+    #
+    # @param target [String] path to the +.bpc+ file
+    # @return [Astronoby::Orientation]
+    # @raise [Astronoby::OrientationError] if the kernel has no orientation data
+    def self.load(target)
+      new(::Ephem::PCK.open(target))
+    end
+
+    # @param pck [::Ephem::PCK] an opened binary PCK
+    def initialize(pck)
+      @pck = pck
+      @source = orientation_source
+      @mean_earth_rotation = mean_earth_rotation
+      @start_jd = @pck.segments.map(&:start_jd).min
+      @end_jd = @pck.segments.map(&:end_jd).max
+    end
+
+    # Rotation from the inertial frame (J2000/ICRF) to the Moon's mean-Earth
+    # body-fixed frame.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] a 3x3 rotation matrix
+    # @raise [Astronoby::OrientationOutOfRangeError] if the kernel does not
+    #   cover the instant
+    def rotation_for(instant)
+      @mean_earth_rotation * principal_axis_rotation(instant)
+    end
+
+    # @return [void]
+    def close
+      @pck.close
+    end
+
+    private
+
+    # The orientation source for the body frame the kernel describes, read from
+    # the kernel rather than assumed.
+    def orientation_source
+      segment = @pck.segments.first
+      raise OrientationError, "Orientation kernel has no segments" unless segment
+
+      @pck[segment.target]
+    end
+
+    # Inertial -> principal-axis rotation from the binary kernel's Euler angles.
+    def principal_axis_rotation(instant)
+      terrestrial_time = instant.terrestrial_time
+      unless terrestrial_time.between?(@start_jd, @end_jd)
+        raise OrientationOutOfRangeError,
+          "Orientation kernel covers #{date(@start_jd)} to #{date(@end_jd)}; " \
+          "requested #{date(terrestrial_time)}"
+      end
+
+      Matrix[*@source.matrix_at(terrestrial_time)]
+    end
+
+    # Principal-axis -> mean-Earth rotation (constant), about the x, y, z axes.
+    def mean_earth_rotation
+      about_z, about_y, about_x = MEAN_EARTH_ALIGNMENT
+      Rotation.about_x(-about_x) *
+        Rotation.about_y(-about_y) *
+        Rotation.about_z(-about_z)
+    end
+
+    def date(terrestrial_time)
+      Instant.from_terrestrial_time(terrestrial_time).to_time.utc.to_date
+    end
+  end
+end

data/lib/astronoby/position.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Astronoby
+  module Position
+    # @param observer [Astronoby::Observer] the observer
+    # @return [Astronoby::Topocentric] the topocentric reference frame
+    def observed_by(observer)
+      Topocentric.build_from_apparent(
+        apparent: apparent,
+        observer: observer,
+        instant: instant,
+        target_body: body
+      )
+    end
+  end
+end