astronoby 0.9.0 → 0.10.0

data/lib/astronoby/time/local_mean_sidereal_time.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Local Mean Sidereal Time (LMST). Derived from GMST by adding the
+  # observer's longitude.
   class LocalMeanSiderealTime < LocalSiderealTime
+    # Creates LMST from a Greenwich Mean Sidereal Time and longitude.
+    #
     # Source:
     #  Title: Practical Astronomy with your Calculator or Spreadsheet
     #  Authors: Peter Duffett-Smith and Jonathan Zwart
     #  Edition: Cambridge University Press
     #  Chapter: 14 - Local sidereal time (LST)
+    #
+    # @param gst [Astronoby::GreenwichMeanSiderealTime] GMST
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalMeanSiderealTime]
+    # @raise [ArgumentError] if gst is not mean sidereal time
     def self.from_gst(gst:, longitude:)
       unless gst.mean?
         raise ArgumentError, "GST must be mean sidereal time"
@@ -18,20 +27,32 @@ module Astronoby
       new(date: date, time: time, longitude: longitude)
     end
 
+    # Creates LMST from UTC and longitude.
+    #
+    # @param utc [Time] the UTC time
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalMeanSiderealTime]
     def self.from_utc(utc, longitude:)
       gmst = GreenwichMeanSiderealTime.from_utc(utc)
       from_gst(gst: gmst, longitude: longitude)
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] LMST in hours
+    # @param longitude [Astronoby::Angle] the observer's longitude
     def initialize(date:, time:, longitude:)
       super(date: date, time: time, longitude: longitude, type: MEAN)
     end
 
+    # Converts to Greenwich Mean Sidereal Time.
+    #
     # Source:
     #  Title: Practical Astronomy with your Calculator or Spreadsheet
     #  Authors: Peter Duffett-Smith and Jonathan Zwart
     #  Edition: Cambridge University Press
     #  Chapter: 15 - Converting LST to GST
+    #
+    # @return [Astronoby::GreenwichMeanSiderealTime]
     def to_gst
       date = @date
       time = normalize_time(@time - @longitude.hours)

data/lib/astronoby/time/local_sidereal_time.rb

@@ -1,9 +1,18 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Local Sidereal Time base class. Dispatches to mean or apparent subclasses
+  # based on the type of the source GST.
   class LocalSiderealTime < SiderealTime
+    # @return [Astronoby::Angle] the observer's longitude
     attr_reader :longitude
 
+    # Creates an LST from a Greenwich Sidereal Time and longitude.
+    #
+    # @param gst [Astronoby::GreenwichSiderealTime] Greenwich Sidereal Time
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalMeanSiderealTime,
+    #   Astronoby::LocalApparentSiderealTime]
     def self.from_gst(gst:, longitude:)
       case gst.type
       when MEAN
@@ -13,6 +22,13 @@ module Astronoby
       end
     end
 
+    # Creates an LST from UTC and longitude.
+    #
+    # @param utc [Time] the UTC time
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @param type [Symbol] :mean or :apparent
+    # @return [Astronoby::LocalMeanSiderealTime,
+    #   Astronoby::LocalApparentSiderealTime]
     def self.from_utc(utc, longitude:, type: MEAN)
       validate_type!(type)
       case type
@@ -23,11 +39,19 @@ module Astronoby
       end
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] the sidereal time in hours
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @param type [Symbol] :mean or :apparent
     def initialize(date:, time:, longitude:, type: MEAN)
       super(date: date, time: time, type: type)
       @longitude = longitude
     end
 
+    # Converts to Greenwich Sidereal Time.
+    #
+    # @return [Astronoby::GreenwichMeanSiderealTime,
+    #   Astronoby::GreenwichApparentSiderealTime]
     def to_gst
       case @type
       when MEAN

data/lib/astronoby/time/sidereal_time.rb

@@ -1,40 +1,62 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Base class for sidereal time representations. Sidereal time measures the
+  # rotation of the Earth relative to the vernal equinox.
   class SiderealTime
     TYPES = [
       MEAN = :mean,
       APPARENT = :apparent
     ].freeze
 
-    attr_reader :date, :time, :type
+    # @return [Date] the calendar date
+    attr_reader :date
 
+    # @return [Numeric] the sidereal time in hours
+    attr_reader :time
+
+    # @return [Symbol] :mean or :apparent
+    attr_reader :type
+
+    # Normalizes a time value to the range [0, 24) hours.
+    #
+    # @param time [Numeric] time in hours
+    # @return [Numeric] normalized time in hours
     def self.normalize_time(time)
       time += Constants::HOURS_PER_DAY if time.negative?
       time -= Constants::HOURS_PER_DAY if time > Constants::HOURS_PER_DAY
       time
     end
 
+    # @param type [Symbol] :mean or :apparent
+    # @raise [ArgumentError] if type is invalid
     def self.validate_type!(type)
       unless TYPES.include?(type)
         raise ArgumentError, "Invalid type: #{type}. Must be one of #{TYPES}"
       end
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] the sidereal time in hours
+    # @param type [Symbol] :mean or :apparent
     def initialize(date:, time:, type: MEAN)
       @date = date
       @time = time
       @type = type
     end
 
+    # @return [Boolean] true if this is mean sidereal time
     def mean?
       @type == MEAN
     end
 
+    # @return [Boolean] true if this is apparent sidereal time
     def apparent?
       @type == APPARENT
     end
 
+    # @param time [Numeric] time in hours
+    # @return [Numeric] normalized time in hours
     def normalize_time(time)
       self.class.normalize_time(time)
     end

data/lib/astronoby/true_obliquity.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes the true obliquity of the ecliptic (mean obliquity + nutation
+  # in obliquity).
   class TrueObliquity
+    # @param instant [Astronoby::Instant] the time instant
+    # @return [Astronoby::Angle] the true obliquity
     def self.at(instant)
       mean_obliquity = MeanObliquity.at(instant)
       nutation = Nutation.new(instant: instant).nutation_in_obliquity

data/lib/astronoby/util/maths.rb

@@ -9,6 +9,14 @@ module Astronoby
         a.zip(b).sum { |x, y| x * y }
       end
 
+      def cross_product(a, b)
+        [
+          a[1] * b[2] - a[2] * b[1],
+          a[2] * b[0] - a[0] * b[2],
+          a[0] * b[1] - a[1] * b[0]
+        ]
+      end
+
       # Find maximum altitude using quadratic interpolation
       # @param t1, t2, t3 [Time] Three consecutive times
       # @param alt1, alt2, alt3 [Float] Corresponding altitudes