astronoby 0.9.0 → 0.11.0

data/lib/astronoby/reference_frames/topocentric.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Topocentric reference frame. Represents a body's position as seen from a
+  # specific observer on Earth's surface, accounting for the observer's
+  # geocentric position and Earth rotation.
   class Topocentric < ReferenceFrame
+    # Builds a topocentric frame from an apparent frame and observer.
+    #
+    # @param apparent [Astronoby::Apparent] the apparent frame
+    # @param observer [Astronoby::Observer] the observer
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::Topocentric] a new topocentric frame
     def self.build_from_apparent(
       apparent:,
       observer:,
@@ -24,17 +34,23 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: [observer.longitude, observer.latitude],
+        center: Center.topocentric(observer),
         target_body: target_body,
         observer: observer
       )
     end
 
+    # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] velocity vector
+    # @param instant [Astronoby::Instant] the time instant
+    # @param center [Astronoby::Center] the center of the frame
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @param observer [Astronoby::Observer] the observer
     def initialize(
       position:,
       velocity:,
       instant:,
-      center_identifier:,
+      center:,
       target_body:,
       observer:
     )
@@ -42,20 +58,36 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: center_identifier,
+        center: center,
         target_body: target_body
       )
       @observer = observer
     end
 
+    # @return [Numeric] Julian Date epoch of the frame's coordinates, which
+    #   are referred to the true equator and equinox of date
+    def epoch
+      instant.tt
+    end
+
+    # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates at the
+    #   current instant (true ecliptic and equinox of date)
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(instant: @instant)
+        equatorial.to_ecliptic(
+          instant: @instant,
+          obliquity: TrueObliquity.at(@instant)
+        )
       end
     end
 
+    # Converts to horizontal coordinates (azimuth/altitude).
+    #
+    # @param refraction [Boolean] whether to apply atmospheric refraction
+    #   correction (default: false)
+    # @return [Astronoby::Coordinates::Horizontal] horizontal coordinates
     def horizontal(refraction: false)
       horizontal = equatorial.to_horizontal(
         time: @instant.to_time,

data/lib/astronoby/refraction.rb

@@ -1,27 +1,44 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Computes atmospheric refraction corrections for horizontal coordinates.
+  #
+  # Source:
+  #  Title: Practical Astronomy with your Calculator or Spreadsheet
+  #  Authors: Peter Duffett-Smith and Jonathan Zwart
+  #  Edition: Cambridge University Press
+  #  Chapter: 37 - Refraction
   class Refraction
     LOW_ALTITUDE_BODY_ANGLE = Angle.from_degrees(15)
     ZENITH = Angle.from_degrees(90)
 
+    # Computes the refraction angle for the given horizontal coordinates.
+    #
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
+    # @return [Astronoby::Angle] the refraction angle
     def self.angle(coordinates:)
       new(coordinates).refraction_angle
     end
 
+    # Returns horizontal coordinates corrected for atmospheric refraction.
+    #
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
+    # @return [Astronoby::Coordinates::Horizontal] corrected coordinates
     def self.correct_horizontal_coordinates(coordinates:)
       new(coordinates).refract
     end
 
+    # @param coordinates [Astronoby::Coordinates::Horizontal] horizontal
+    #   coordinates
     def initialize(coordinates)
       @coordinates = coordinates
     end
 
-    # Source:
-    #  Title: Practical Astronomy with your Calculator or Spreadsheet
-    #  Authors: Peter Duffett-Smith and Jonathan Zwart
-    #  Edition: Cambridge University Press
-    #  Chapter: 37 - Refraction
+    # Returns horizontal coordinates with refraction applied to the altitude.
+    #
+    # @return [Astronoby::Coordinates::Horizontal] corrected coordinates
     def refract
       Coordinates::Horizontal.new(
         azimuth: @coordinates.azimuth,
@@ -30,6 +47,10 @@ module Astronoby
       )
     end
 
+    # Computes the refraction angle based on the observer's atmospheric
+    # conditions and the body's altitude.
+    #
+    # @return [Astronoby::Angle] the refraction angle
     def refraction_angle
       if @coordinates.altitude > LOW_ALTITUDE_BODY_ANGLE
         high_altitude_angle

data/lib/astronoby/root_finder.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RootFinder
+    MIN_SAMPLES_PER_PERIOD = 20
+    BISECTION_TOLERANCE_DAYS = 1e-8
+
+    # @param value_at [#call] callable mapping a Julian Date (Terrestrial Time)
+    #   to a Float
+    # @param period [Float] the characteristic period of the quantity in days
+    # @param samples_per_period [Integer] number of samples per period
+    def initialize(value_at:, period:, samples_per_period: 60)
+      @value_at = value_at
+      @period = period
+      @samples_per_period = samples_per_period
+    end
+
+    # @param start_jd [Float] start time in Julian Date (Terrestrial Time)
+    # @param end_jd [Float] end time in Julian Date (Terrestrial Time)
+    # @param accept [#call, nil] optional predicate on a located root (a Julian
+    #   Date)
+    # @return [Array<Float>] root times in Julian Date (Terrestrial Time),
+    #   sorted by time
+    def roots(start_jd, end_jd, accept: nil)
+      samples = collect_samples(start_jd, end_jd)
+      located = (
+        samples_on_root(samples) +
+          find_brackets(samples).map { |a, b, f_a| bisect(a, b, f_a) }
+      ).uniq.sort
+      located.select { |jd| accept.nil? || accept.call(jd) }
+    end
+
+    private
+
+    def samples_on_root(samples)
+      samples.filter_map { |sample| sample[:jd] if sample[:value].zero? }
+    end
+
+    def find_brackets(samples)
+      (0...samples.length - 1).filter_map do |i|
+        current = samples[i]
+        following = samples[i + 1]
+
+        if sign_change?(current, following)
+          [current[:jd], following[:jd], current[:value]]
+        end
+      end
+    end
+
+    def sign_change?(current, following)
+      current[:value] * following[:value] < 0
+    end
+
+    def collect_samples(start_jd, end_jd)
+      duration = end_jd - start_jd
+      sample_count = sample_count_for(duration)
+      step = duration / sample_count
+
+      (0..sample_count).map do |i|
+        jd = start_jd + (i * step)
+        {jd: jd, value: @value_at.call(jd)}
+      end
+    end
+
+    def sample_count_for(duration)
+      periods_in_range = duration / @period
+      base_samples = (periods_in_range * @samples_per_period).to_i
+      [base_samples, MIN_SAMPLES_PER_PERIOD].max
+    end
+
+    def bisect(a, b, f_a)
+      while (b - a).abs > BISECTION_TOLERANCE_DAYS
+        midpoint = (a + b) / 2
+        break if midpoint == a || midpoint == b
+
+        f_midpoint = @value_at.call(midpoint)
+        return midpoint if f_midpoint.zero?
+
+        if f_a.negative? == f_midpoint.negative?
+          a = midpoint
+          f_a = f_midpoint
+        else
+          b = midpoint
+        end
+      end
+
+      (a + b) / 2
+    end
+  end
+end

data/lib/astronoby/rotation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "matrix"
+
+module Astronoby
+  # Builds elementary rotation matrices about the coordinate axes from an
+  # +Astronoby::Angle+.
+  #
+  # These use the passive (frame) convention: the matrix expresses a fixed
+  # vector in a frame rotated by +angle+ about the axis. This is the convention
+  # used throughout the reference-frame chain (precession, nutation, body
+  # orientation).
+  module Rotation
+    module_function
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the x-axis
+    def about_x(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [1, 0, 0],
+        [0, cosine, sine],
+        [0, -sine, cosine]
+      ]
+    end
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the y-axis
+    def about_y(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [cosine, 0, -sine],
+        [0, 1, 0],
+        [sine, 0, cosine]
+      ]
+    end
+
+    # @param angle [Astronoby::Angle] the rotation angle
+    # @return [Matrix] rotation about the z-axis
+    def about_z(angle)
+      cosine, sine = angle.cos, angle.sin
+      Matrix[
+        [cosine, sine, 0],
+        [-sine, cosine, 0],
+        [0, 0, 1]
+      ]
+    end
+  end
+end

data/lib/astronoby/time/greenwich_apparent_sidereal_time.rb

@@ -1,20 +1,31 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Greenwich Apparent Sidereal Time (GAST). Derived from GMST by applying
+  # the equation of the equinoxes (nutation correction).
   class GreenwichApparentSiderealTime < GreenwichSiderealTime
+    # Creates GAST from UTC by computing GMST and applying the equation
+    # of the equinoxes.
+    #
+    # @param utc [Time] the UTC time
+    # @return [Astronoby::GreenwichApparentSiderealTime]
     def self.from_utc(utc)
-      gmst = GreenwichMeanSiderealTime.from_utc(utc)
-      instant = Instant.from_time(utc)
-      nutation = Nutation.new(instant: instant)
-      mean_obliquity = MeanObliquity.at(instant)
+      Astronoby.cache.fetch(CacheKey.generate_for_utc(:gast, utc)) do
+        gmst = GreenwichMeanSiderealTime.from_utc(utc)
+        instant = Instant.from_time(utc)
+        nutation = Nutation.new(instant: instant)
+        mean_obliquity = MeanObliquity.at(instant)
 
-      equation_of_equinoxes = nutation.nutation_in_longitude.hours *
-        mean_obliquity.cos
-      gast_time = normalize_time(gmst.time + equation_of_equinoxes)
+        equation_of_equinoxes = nutation.nutation_in_longitude.hours *
+          mean_obliquity.cos
+        gast_time = normalize_time(gmst.time + equation_of_equinoxes)
 
-      new(date: gmst.date, time: gast_time)
+        new(date: gmst.date, time: gast_time)
+      end
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] GAST in hours
     def initialize(date:, time:)
       super(date: date, time: time, type: APPARENT)
     end

data/lib/astronoby/time/greenwich_mean_sidereal_time.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
+require "iers"
+
 module Astronoby
+  # Greenwich Mean Sidereal Time (GMST). Computed from UTC using the IERS
+  # Conventions 2010 ERA-based expression, with a polynomial fallback for
+  # dates outside the IERS EOP data range.
   class GreenwichMeanSiderealTime < GreenwichSiderealTime
     JULIAN_CENTURIES_EXPONENTS = [
       6.697374558,
@@ -10,13 +15,43 @@ module Astronoby
 
     SIDEREAL_MINUTE_IN_UT_MINUTE = 0.9972695663
 
+    UT_TO_SIDEREAL_RATIO = 1.002737909
+
+    # Creates GMST from UTC using the IERS Conventions 2010 ERA-based
+    # expression.
+    #
+    # Source:
+    #  Title: IERS Conventions (2010)
+    #  Chapter: 5.5.7 - ERA based expressions for Greenwich Sidereal Time
+    #
+    # @param utc [Time] the UTC time
+    # @return [Astronoby::GreenwichMeanSiderealTime]
+    def self.from_utc(utc)
+      Astronoby.cache.fetch(CacheKey.generate_for_utc(:gmst, utc)) do
+        date = utc.to_date
+        gmst_hours = begin
+          gmst_radians = IERS::GMST.at(utc)
+          gmst_radians * 12.0 / Math::PI
+        rescue IERS::OutOfRangeError
+          from_utc_polynomial(utc)
+        end
+        gmst_hours = normalize_time(gmst_hours)
+
+        new(date: date, time: gmst_hours)
+      end
+    end
+
+    # Polynomial fallback for dates outside the IERS EOP data range.
+    #
     # Source:
     #  Title: Practical Astronomy with your Calculator or Spreadsheet
     #  Authors: Peter Duffett-Smith and Jonathan Zwart
     #  Edition: Cambridge University Press
     #  Chapter: 12 - Conversion of UT to Greenwich sidereal time (GST)
-    def self.from_utc(utc)
-      date = utc.to_date
+    #
+    # @param utc [Time] the UTC time
+    # @return [Numeric] GMST in hours
+    def self.from_utc_polynomial(utc)
       julian_day = utc.to_date.ajd
       t = (julian_day - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
       t0 = (
@@ -29,20 +64,24 @@ module Astronoby
         utc.min / Constants::MINUTES_PER_HOUR +
         (utc.sec + utc.subsec) / Constants::SECONDS_PER_HOUR
 
-      gmst = normalize_time(1.002737909 * ut_in_hours + t0)
-
-      new(date: date, time: gmst)
+      UT_TO_SIDEREAL_RATIO * ut_in_hours + t0
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] GMST in hours
     def initialize(date:, time:)
       super(date: date, time: time, type: MEAN)
     end
 
+    # Converts GMST back to UTC.
+    #
     # Source:
     #  Title: Practical Astronomy with your Calculator or Spreadsheet
     #  Authors: Peter Duffett-Smith and Jonathan Zwart
     #  Edition: Cambridge University Press
     #  Chapter: 13 - Conversion of GST to UT
+    #
+    # @return [Time] the UTC time
     def to_utc
       date = @date
       julian_day = @date.ajd

data/lib/astronoby/time/greenwich_sidereal_time.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Greenwich Sidereal Time base class. Dispatches to mean or apparent
+  # subclasses.
   class GreenwichSiderealTime < SiderealTime
+    # Creates a Greenwich Sidereal Time from UTC.
+    #
+    # @param utc [Time] the UTC time
+    # @param type [Symbol] :mean or :apparent
+    # @return [Astronoby::GreenwichMeanSiderealTime,
+    #   Astronoby::GreenwichApparentSiderealTime]
     def self.from_utc(utc, type: MEAN)
       validate_type!(type)
       case type
@@ -12,14 +20,22 @@ module Astronoby
       end
     end
 
+    # @param utc [Time] the UTC time
+    # @return [Astronoby::GreenwichMeanSiderealTime]
     def self.mean_from_utc(utc)
       GreenwichMeanSiderealTime.from_utc(utc)
     end
 
+    # @param utc [Time] the UTC time
+    # @return [Astronoby::GreenwichApparentSiderealTime]
     def self.apparent_from_utc(utc)
       GreenwichApparentSiderealTime.from_utc(utc)
     end
 
+    # Converts to UTC.
+    #
+    # @return [Time] the UTC time
+    # @raise [NotImplementedError] if this is apparent sidereal time
     def to_utc
       unless mean?
         raise NotImplementedError,
@@ -30,6 +46,11 @@ module Astronoby
       gmst.to_utc
     end
 
+    # Converts to Local Sidereal Time for a given longitude.
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalMeanSiderealTime,
+    #   Astronoby::LocalApparentSiderealTime]
     def to_lst(longitude:)
       LocalSiderealTime.from_gst(gst: self, longitude: longitude)
     end

data/lib/astronoby/time/local_apparent_sidereal_time.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Local Apparent Sidereal Time (LAST). Derived from GAST by adding the
+  # observer's longitude.
   class LocalApparentSiderealTime < LocalSiderealTime
+    # Creates LAST from a Greenwich Apparent 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::GreenwichApparentSiderealTime] GAST
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalApparentSiderealTime]
+    # @raise [ArgumentError] if gst is not apparent sidereal time
     def self.from_gst(gst:, longitude:)
       unless gst.apparent?
         raise ArgumentError, "GST must be apparent sidereal time"
@@ -18,20 +27,32 @@ module Astronoby
       new(date: date, time: time, longitude: longitude)
     end
 
+    # Creates LAST from UTC and longitude.
+    #
+    # @param utc [Time] the UTC time
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Astronoby::LocalApparentSiderealTime]
     def self.from_utc(utc, longitude:)
       gast = GreenwichApparentSiderealTime.from_utc(utc)
       from_gst(gst: gast, longitude: longitude)
     end
 
+    # @param date [Date] the calendar date
+    # @param time [Numeric] LAST in hours
+    # @param longitude [Astronoby::Angle] the observer's longitude
     def initialize(date:, time:, longitude:)
       super(date: date, time: time, longitude: longitude, type: APPARENT)
     end
 
+    # Converts to Greenwich Apparent 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::GreenwichApparentSiderealTime]
     def to_gst
       date = @date
       time = normalize_time(@time - @longitude.hours)

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