astronoby 0.9.0 → 0.10.0

data/lib/astronoby/reference_frames/geometric.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Geometric reference frame (BCRS). Represents a body's position relative
+  # to the Solar System Barycenter, without any corrections applied.
   class Geometric < ReferenceFrame
+    # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] velocity vector
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_body [Astronoby::Body, nil] the target body
     def initialize(
       position:,
       velocity:,
@@ -12,7 +18,7 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::SOLAR_SYSTEM_BARYCENTER,
+        center: Center.barycentric,
         target_body: target_body
       )
     end

data/lib/astronoby/reference_frames/mean_of_date.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Mean-of-date reference frame. Represents a body's geocentric position
+  # corrected for precession only (no nutation or aberration).
   class MeanOfDate < ReferenceFrame
+    # Builds a mean-of-date frame from geometric frames by applying
+    # precession.
+    #
+    # @param instant [Astronoby::Instant] the time instant
+    # @param target_geometric [Astronoby::Geometric] target's geometric frame
+    # @param earth_geometric [Astronoby::Geometric] Earth's geometric frame
+    # @param target_body [Astronoby::Body, nil] the target body
+    # @return [Astronoby::MeanOfDate] a new mean-of-date frame
     def self.build_from_geometric(
       instant:,
       target_geometric:,
@@ -22,11 +32,13 @@ module Astronoby
         position: corrected_position,
         velocity: corrected_velocity,
         instant: instant,
-        center_identifier: SolarSystemBody::EARTH,
+        center: Center.geocentric,
         target_body: target_body
       )
     end
 
+    # @return [Astronoby::Coordinates::Ecliptic] ecliptic coordinates at the
+    #   current instant (mean equinox of date)
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?

data/lib/astronoby/reference_frames/teme.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # TEME (True Equator, Mean Equinox) reference frame. This is the output
+  # frame of the SGP4/SDP4 satellite orbit propagators. Provides conversions
+  # to ECEF, GCRS, and topocentric frames.
+  class Teme < ReferenceFrame
+    # ECEF position and velocity vectors.
+    class EcefCoordinates
+      # @return [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      attr_reader :position
+
+      # @return [Astronoby::Vector<Astronoby::Velocity>] ECEF velocity
+      attr_reader :velocity
+
+      # @param position [Astronoby::Vector<Astronoby::Distance>] ECEF position
+      # @param velocity [Astronoby::Vector<Astronoby::Velocity>] ECEF velocity
+      def initialize(position:, velocity:)
+        @position = position
+        @velocity = velocity
+        freeze
+      end
+
+      # Converts the ECEF position to WGS-84 geodetic coordinates using
+      # Bowring's iterative method.
+      #
+      # @return [Astronoby::Coordinates::Geodetic] geodetic coordinates
+      def geodetic
+        Coordinates::Geodetic.from_ecef(@position)
+      end
+    end
+
+    # @param position [Astronoby::Vector<Astronoby::Distance>] TEME position
+    # @param velocity [Astronoby::Vector<Astronoby::Velocity>] TEME velocity
+    # @param instant [Astronoby::Instant] the time instant
+    def initialize(position:, velocity:, instant:)
+      super(
+        position: position,
+        velocity: velocity,
+        instant: instant,
+        center: Center.geocentric,
+        target_body: nil
+      )
+    end
+
+    # Converts TEME position and velocity to ECEF using the canonical
+    # Vallado formulation with R₃(GMST).
+    #
+    # Velocity includes the ω×r transport term to account for Earth
+    # rotation.
+    #
+    # @return [Astronoby::Teme::EcefCoordinates] ECEF position and velocity
+    def to_ecef
+      mean_rotation_matrix = EarthRotation.mean_matrix_for(@instant).transpose
+
+      position = mean_rotation_matrix * @position.map(&:m)
+      velocity_mps = mean_rotation_matrix * @velocity.map(&:mps)
+
+      omega = Constants::EARTH_ANGULAR_VELOCITY_RAD_PER_S
+      corrected_vel = ::Vector[
+        velocity_mps[0] + omega * position[1],
+        velocity_mps[1] - omega * position[0],
+        velocity_mps[2]
+      ]
+
+      EcefCoordinates.new(
+        position: Distance.vector_from_meters(position),
+        velocity: Velocity.vector_from_mps(corrected_vel)
+      )
+    end
+
+    # Converts TEME to GCRS using the pragmatic approach: reuse existing
+    # IAU 2006/2000B precession and nutation matrices transposed.
+    #
+    # The transformation chain is: r_GCRS = PBᵀ * Nᵀ * R₃(EoE) * r_TEME
+    #
+    # @return [Astronoby::Astrometric] GCRS Earth-centered frame
+    def to_gcrs
+      Astrometric.new(
+        position: Distance.vector_from_meters(
+          gcrs_rotation_matrix * @position.map(&:m)
+        ),
+        velocity: Velocity.vector_from_mps(
+          gcrs_rotation_matrix * @velocity.map(&:mps)
+        ),
+        instant: @instant,
+        center: Center.geocentric,
+        target_body: nil
+      )
+    end
+
+    # Converts TEME to topocentric coordinates as seen from an observer.
+    #
+    # Both satellite (via equation of equinoxes) and observer (via
+    # R₃(GAST) * W) are placed in the TOD frame, then subtracted.
+    #
+    # @param observer [Astronoby::Observer] the observer
+    # @return [Astronoby::Topocentric] topocentric frame
+    def observed_by(observer)
+      satellite_position = Distance.vector_from_meters(
+        equation_of_equinoxes_matrix * @position.map(&:m)
+      )
+      satellite_velocity = Velocity.vector_from_mps(
+        equation_of_equinoxes_matrix * @velocity.map(&:mps)
+      )
+
+      matrix = observer.earth_fixed_rotation_matrix_for(@instant)
+      observer_position = Distance.vector_from_meters(
+        matrix * observer.geocentric_position.map(&:m)
+      )
+      observer_velocity = Velocity.vector_from_mps(
+        matrix * observer.geocentric_velocity.map(&:mps)
+      )
+
+      Topocentric.new(
+        position: satellite_position - observer_position,
+        velocity: satellite_velocity - observer_velocity,
+        instant: @instant,
+        center: Center.topocentric(observer),
+        target_body: nil,
+        observer: observer
+      )
+    end
+
+    private
+
+    def gcrs_rotation_matrix
+      @gcrs_rotation_matrix ||= begin
+        precession_matrix = Precession.matrix_for(@instant)
+        nutation_matrix = Nutation.matrix_for(@instant)
+        precession_matrix.transpose *
+          nutation_matrix.transpose *
+          equation_of_equinoxes_matrix
+      end
+    end
+
+    def equation_of_equinoxes_matrix
+      @equation_of_equinoxes_matrix ||= begin
+        nutation = Nutation.new(instant: @instant)
+        dpsi = nutation.nutation_in_longitude
+        mean_obliquity = MeanObliquity.at(@instant)
+        eoe = dpsi.radians * mean_obliquity.cos
+
+        c, s = Math.cos(eoe), Math.sin(eoe)
+        Matrix[
+          [c, -s, 0],
+          [s, c, 0],
+          [0, 0, 1]
+        ]
+      end
+    end
+  end
+end

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,30 @@ module Astronoby
         position: position,
         velocity: velocity,
         instant: instant,
-        center_identifier: center_identifier,
+        center: center,
         target_body: target_body
       )
       @observer = observer
     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,83 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RootFinder
+    MIN_SAMPLES_PER_PERIOD = 20
+    BISECTION_TOLERANCE_DAYS = 1e-5
+
+    # @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)
+      brackets = find_brackets(start_jd, end_jd)
+      located = brackets.map { |a, b| bisect(a, b) }
+      located.select { |jd| accept.nil? || accept.call(jd) }
+    end
+
+    private
+
+    def find_brackets(start_jd, end_jd)
+      samples = collect_samples(start_jd, end_jd)
+
+      (0...samples.length - 1).filter_map do |i|
+        current = samples[i]
+        following = samples[i + 1]
+
+        [current[:jd], following[:jd]] if sign_change?(current, following)
+      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 = @value_at.call(a)
+
+      while (b - a).abs > BISECTION_TOLERANCE_DAYS
+        midpoint = (a + b) / 2
+        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,7 +1,14 @@
 # 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)
@@ -15,6 +22,8 @@ module Astronoby
       new(date: gmst.date, time: gast_time)
     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,41 @@ 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)
+      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
+
+    # 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 +62,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)