astronoby 0.9.0 → 0.11.0

data/lib/astronoby/earth_rotation.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # Computes Earth rotation matrices using Greenwich Sidereal Time.
+  # Provides both apparent (GAST-based) and mean (GMST-based) rotation
+  # matrices for transforming between Earth-fixed and celestial frames.
+  class EarthRotation
+    # Computes the apparent Earth rotation matrix R₃(GAST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 Earth rotation matrix
+    def self.matrix_for(instant)
+      new(instant: instant).matrix
+    end
+
+    # Computes the mean Earth rotation matrix R₃(GMST) for a given
+    # instant.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Matrix] 3x3 mean Earth rotation matrix
+    def self.mean_matrix_for(instant)
+      new(instant: instant).mean_matrix
+    end
+
+    # @param instant [Astronoby::Instant] the time instant
+    def initialize(instant:)
+      @instant = instant
+    end
+
+    # Computes R₃(GAST), the apparent Earth rotation matrix.
+    # GAST = GMST + equation of the equinoxes (Δψ cos ε₀).
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def matrix
+      rotation_matrix_for(gast)
+    end
+
+    # Computes R₃(GMST), the mean Earth rotation matrix.
+    #
+    # @return [Matrix] 3x3 rotation matrix
+    def mean_matrix
+      rotation_matrix_for(gmst)
+    end
+
+    private
+
+    def gmst
+      Angle.from_hours(@instant.gmst)
+    end
+
+    def gast
+      nutation = Nutation.new(instant: @instant)
+      dpsi = nutation.nutation_in_longitude
+      mean_obliquity = MeanObliquity.at(@instant)
+      Angle.from_radians(
+        gmst.radians + dpsi.radians * mean_obliquity.cos
+      )
+    end
+
+    def rotation_matrix_for(angle)
+      c, s = angle.cos, angle.sin
+      Matrix[
+        [c, -s, 0],
+        [s, c, 0],
+        [0, 0, 1]
+      ]
+    end
+  end
+end

data/lib/astronoby/equinox_solstice.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes the time of equinoxes and solstices for a given year.
+  #
+  # Source:
+  #  Title: Astronomical Algorithms
+  #  Author: Jean Meeus
+  #  Edition: 2nd edition
+  #  Chapter: 27 - Equinoxes and Soltices
   class EquinoxSolstice
-    # Source:
-    #  Title: Astronomical Algorithms
-    #  Author: Jean Meeus
-    #  Edition: 2nd edition
-    #  Chapter: 27 - Equinoxes and Soltices
-
     EVENTS = [
       MARCH_EQUINOX = 0,
       JUNE_SOLSTICE = 1,
@@ -73,22 +74,39 @@ module Astronoby
       [8, 15.45, 16859.074]
     ].freeze
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the March equinox
     def self.march_equinox(year, ephem)
       new(year, MARCH_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the June solstice
     def self.june_solstice(year, ephem)
       new(year, JUNE_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the September equinox
     def self.september_equinox(year, ephem)
       new(year, SEPTEMBER_EQUINOX, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @return [Time] time of the December solstice
     def self.december_solstice(year, ephem)
       new(year, DECEMBER_SOLSTICE, ephem).time
     end
 
+    # @param year [Integer] the year
+    # @param event [Integer] one of MARCH_EQUINOX, JUNE_SOLSTICE,
+    #   SEPTEMBER_EQUINOX, or DECEMBER_SOLSTICE
+    # @param ephem [::Ephem::SPK] ephemeris data source
+    # @raise [Astronoby::UnsupportedEventError] if event is invalid
     def initialize(year, event, ephem)
       unless EVENTS.include?(event)
         raise UnsupportedEventError.new(
@@ -97,12 +115,13 @@ module Astronoby
       end
 
       @event = event
+      @ephem = ephem
       @year = (year.to_i - 2000) / 1000.0
       uncorrected_time = compute
       @instant = Instant.from_time(uncorrected_time)
-      @sun = Sun.new(ephem: ephem, instant: @instant)
     end
 
+    # @return [Time] the corrected UTC time of the event
     def time
       Instant.from_terrestrial_time(@instant.tt + corrected).to_time.round
     end
@@ -135,8 +154,12 @@ module Astronoby
         component[4] * @year**4
     end
 
+    def sun
+      @sun ||= Sun.new(ephem: @ephem, instant: @instant)
+    end
+
     def corrected
-      longitude = @sun.apparent.ecliptic.longitude
+      longitude = sun.apparent.ecliptic.longitude
       58 * Angle.from_degrees(@event * 90 - longitude.degrees).sin
     end
   end

data/lib/astronoby/errors.rb

@@ -1,11 +1,22 @@
 module Astronoby
+  # Raised when arguments are mutually incompatible.
   class IncompatibleArgumentsError < ArgumentError; end
 
+  # Raised when an unsupported format is requested.
   class UnsupportedFormatError < ArgumentError; end
 
+  # Raised when an unsupported event type is requested.
   class UnsupportedEventError < ArgumentError; end
 
+  # Raised when an astronomical calculation fails.
   class CalculationError < StandardError; end
 
+  # Raised when there is an error with ephemeris data.
   class EphemerisError < StandardError; end
+
+  # Raised when an orientation kernel is not a supported orientation source.
+  class OrientationError < StandardError; end
+
+  # Raised when an orientation kernel does not cover the requested instant.
+  class OrientationOutOfRangeError < StandardError; end
 end

data/lib/astronoby/events/altitude_crossing.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # A moment when a body's altitude passes through a given value.
+  class AltitudeCrossing
+    # @return [Astronoby::Instant] when the crossing happens, unrounded
+    attr_reader :instant
+
+    # @return [Symbol] +:rising+ when the altitude increases through the
+    #   target, +:setting+ when it decreases
+    attr_reader :direction
+
+    # @param instant [Astronoby::Instant] when the crossing happens
+    # @param direction [Symbol] +:rising+ or +:setting+
+    # @param grazing [Boolean] whether the body only just reaches the target
+    def initialize(instant:, direction:, grazing: false)
+      @instant = instant
+      @direction = direction
+      @grazing = grazing
+    end
+
+    # @return [Boolean] true when the target is within a few hundredths of a
+    #   degree of the body's highest or lowest altitude, so the crossing is
+    #   nearly tangent and its instant is sensitive to small errors
+    def grazing?
+      @grazing
+    end
+  end
+end