astronoby 0.9.0 → 0.11.0

data/docs/twilight_times.md

@@ -5,14 +5,15 @@ some of its light still illuminates the atmosphere, making the sky brighter than
 during full night.
 
 We usually define 4 moments when talking about twilight:
-* sunrise/sunset: right when the Sun goes above the horizon or right after it
+
+- sunrise/sunset: right when the Sun goes above the horizon or right after it
   goes below the horizon. The Sun's horizon angle is 0°.
-* civil twilight: when the horizon angle is between 0° and -6°. Usually, during
+- civil twilight: when the horizon angle is between 0° and -6°. Usually, during
   this time, artificial light is not needed yet.
-* nautical twilight: when the horizon angle is between -6° and -12°. When the
+- nautical twilight: when the horizon angle is between -6° and -12°. When the
   nautical twilight starts, the difference between the horizon at sea and the
   sky cannot be seen clearly anymore.
-* astronomical twilight: when the horizon angle is between -12° and -18°. Some
+- astronomical twilight: when the horizon angle is between -12° and -18°. Some
   stars can be seen during this time.
 
 These moments change every day and depend on the observer's location. They can
@@ -24,8 +25,9 @@ Once instantiated, the calculator doesn't do anything yet, it waits for your
 instruction.
 
 It takes as key arguments:
-* `observer` (`Astronoby::Observer`): location on Earth of the observer
-* `ephem`: ephemeris to provide the initial raw data
+
+- `observer` (`Astronoby::Observer`): location on Earth of the observer
+- `ephem`: ephemeris to provide the initial raw data
 
 You can learn more about ephemerides on the [Ephem page].
 
@@ -53,17 +55,18 @@ that will happen between two dates.
 
 It returns a `Astronoby::TwilightEvents` object which exposes the 6 following
 instance methods:
-* `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
+
+- `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
   the horizon
-* `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
+- `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
   horizon
-* `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
+- `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
   horizon
-* `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
+- `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
   horizon
-* `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
+- `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
   horizon
-* `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
+- `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
   the horizon
 
 ```rb
@@ -74,13 +77,13 @@ events = calculator.events_between(
 
 events.morning_civil_twilight_times
 # =>
-# [2025-08-01 02:29:17 UTC,
-#  2025-08-02 02:30:21 UTC,
-#  2025-08-03 02:31:26 UTC,
-#  2025-08-04 02:32:30 UTC,
-#  2025-08-05 02:33:35 UTC,
-#  2025-08-06 02:34:40 UTC,
-#  2025-08-07 02:35:45 UTC]
+# [2025-08-01 02:29:11 UTC,
+#  2025-08-02 02:30:15 UTC,
+#  2025-08-03 02:31:20 UTC,
+#  2025-08-04 02:32:24 UTC,
+#  2025-08-05 02:33:29 UTC,
+#  2025-08-06 02:34:34 UTC,
+#  2025-08-07 02:35:39 UTC]
 ```
 
 ## `#event_on`
@@ -98,25 +101,41 @@ instance methods: `#morning_astronomical_twilight_time`,
 event = calculator.event_on(Date.new(2025, 5, 1))
 
 event.morning_astronomical_twilight_time
-# => 2025-05-01 01:17:18 UTC
+# => 2025-05-01 01:16:21 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 01:56:48 UTC
+# => 2025-05-01 01:55:49 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 17:29:41 UTC
+# => 2025-05-01 17:30:50 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 18:06:08 UTC
+# => 2025-05-01 18:07:27 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 18:45:38 UTC
+# => 2025-05-01 18:47:10 UTC
 ```
 
+## Accuracy and polar regions
+
+Each twilight time is the moment the Sun's centre, without refraction, reaches
+the matching altitude, found by `Astronoby::AltitudeCrossingCalculator`. Times
+are rounded to the second. Twilight that exists is returned even when the Sun
+does not rise or set that day, as in a polar night. Use the [altitude crossing
+calculator](altitude_crossings.md) directly for other altitudes or for unrounded
+instants.
+
+Solving for the real crossing costs more than approximating the Sun's position
+from a single evaluation, as versions before 0.11.0 did, which could be off by
+up to 30 seconds. `#event_on` takes around 7.5 milliseconds for one day, against
+around 4 before.
+
 [Ephem page]: ephem.md
 [Observer page]: observer.md
 
 ## See also
+
+- [Altitude Crossings](altitude_crossings.md) - for any altitude, unrounded
 - [Rise, Transit and Set Times](rise_transit_set_times.md) - for sun and moon events
 - [Observer](observer.md) - for location setup
 - [Ephemerides](ephem.md) - for data sources

data/lib/astronoby/angle.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle with radians as its internal representation.
+  # Provides conversions between radians, degrees, hours, and sexagesimal
+  # formats (DMS and HMS), as well as trigonometric operations.
+  #
+  # @example Create an angle from degrees
+  #   angle = Astronoby::Angle.from_degrees(180)
+  #   angle.radians  # => Math::PI
+  #
+  # @example Create an angle from hours, minutes, seconds
+  #   angle = Astronoby::Angle.from_hms(12, 30, 0)
+  #
   class Angle
     include Comparable
 
@@ -8,29 +19,42 @@ module Astronoby
     FORMATS = %i[dms hms].freeze
 
     class << self
+      # @return [Astronoby::Angle] a zero angle
       def zero
         new(0)
       end
 
+      # @param radians [Numeric] the angle in radians
+      # @return [Astronoby::Angle] a new Angle, normalized to (-2π, 2π)
       def from_radians(radians)
         normalized_radians = radians.remainder(Constants::RADIANS_PER_CIRCLE)
         new(normalized_radians)
       end
 
+      # @param degrees [Numeric] the angle in degrees
+      # @return [Astronoby::Angle] a new Angle
       def from_degrees(degrees)
         radians = degrees / Constants::PI_IN_DEGREES * Math::PI
         from_radians(radians)
       end
 
+      # @param arcseconds [Numeric] the angle in arcseconds
+      # @return [Astronoby::Angle] a new Angle
       def from_degree_arcseconds(arcseconds)
         from_dms(0, 0, arcseconds)
       end
 
+      # @param hours [Numeric] the angle in hour-angle hours
+      # @return [Astronoby::Angle] a new Angle
       def from_hours(hours)
         radians = hours * Constants::RADIAN_PER_HOUR
         from_radians(radians)
       end
 
+      # @param hour [Numeric] hours component
+      # @param minute [Numeric] minutes component
+      # @param second [Numeric] seconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_hms(hour, minute, second)
         hours = hour +
           minute / Constants::MINUTES_PER_HOUR +
@@ -38,89 +62,118 @@ module Astronoby
         from_hours(hours)
       end
 
+      # @param degree [Numeric] degrees component (sign determines overall sign)
+      # @param minute [Numeric] arcminutes component
+      # @param second [Numeric] arcseconds component
+      # @return [Astronoby::Angle] a new Angle
       def from_dms(degree, minute, second)
         sign = degree.negative? ? -1 : 1
         degrees = degree.abs +
-          minute / Constants::MINUTES_PER_HOUR +
-          second / Constants::SECONDS_PER_HOUR
+          minute / Constants::ARCMINUTES_PER_DEGREE +
+          second / Constants::ARCSECONDS_PER_DEGREE
         from_degrees(sign * degrees)
       end
 
+      # @param ratio [Numeric] the sine value (-1..1)
+      # @return [Astronoby::Angle] the arcsine
       def asin(ratio)
         radians = Math.asin(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the cosine value (-1..1)
+      # @return [Astronoby::Angle] the arccosine
       def acos(ratio)
         radians = Math.acos(ratio)
         from_radians(radians)
       end
 
+      # @param ratio [Numeric] the tangent value
+      # @return [Astronoby::Angle] the arctangent
       def atan(ratio)
         radians = Math.atan(ratio)
         from_radians(radians)
       end
     end
 
+    # @return [Numeric] the angle in radians
     attr_reader :radians
 
+    # @param radians [Numeric] the angle in radians
     def initialize(radians)
       @radians = radians
       freeze
     end
 
+    # @return [Float] the angle in degrees
     def degrees
       @radians * Constants::PI_IN_DEGREES / Math::PI
     end
 
+    # @return [Float] the angle in milliarcseconds
     def degree_milliarcseconds
       degrees * Constants::MILLIARCSECONDS_PER_DEGREE
     end
 
+    # @return [Float] the angle in hour-angle hours
     def hours
       @radians / Constants::RADIAN_PER_HOUR
     end
 
+    # @param other [Astronoby::Angle] angle to add
+    # @return [Astronoby::Angle] the sum
     def +(other)
       self.class.from_radians(radians + other.radians)
     end
 
+    # @param other [Astronoby::Angle] angle to subtract
+    # @return [Astronoby::Angle] the difference
     def -(other)
       self.class.from_radians(@radians - other.radians)
     end
 
+    # @return [Astronoby::Angle] the negated angle
     def -@
       self.class.from_radians(-@radians)
     end
 
+    # @return [Float] the sine of the angle
     def sin
       Math.sin(radians)
     end
 
+    # @return [Float] the cosine of the angle
     def cos
       Math.cos(radians)
     end
 
+    # @return [Float] the tangent of the angle
     def tan
       Math.tan(radians)
     end
 
+    # @return [Boolean] true if the angle is positive
     def positive?
       radians > 0
     end
 
+    # @return [Boolean] true if the angle is negative
     def negative?
       radians < 0
     end
 
+    # @return [Boolean] true if the angle is zero
     def zero?
       radians.zero?
     end
 
+    # @return [Integer] hash value
     def hash
       [radians, self.class].hash
     end
 
+    # @param other [Astronoby::Angle] angle to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 
@@ -128,6 +181,12 @@ module Astronoby
     end
     alias_method :eql?, :==
 
+    # Formats the angle as a string in the given format.
+    #
+    # @param format [Symbol] :dms or :hms
+    # @param precision [Integer] decimal places for seconds
+    # @return [String] the formatted angle
+    # @raise [Astronoby::UnsupportedFormatError] if format is not :dms or :hms
     def str(format, precision: 4)
       case format
       when :dms then to_dms.format(precision: precision)
@@ -139,6 +198,7 @@ module Astronoby
       end
     end
 
+    # @return [Astronoby::Dms] the angle in degrees, arcminutes, arcseconds
     def to_dms
       sign = degrees.negative? ? "-" : "+"
       absolute_degrees = degrees.abs
@@ -156,6 +216,7 @@ module Astronoby
       Dms.new(sign, deg, minutes, seconds)
     end
 
+    # @return [Astronoby::Hms] the angle in hours, minutes, seconds
     def to_hms
       absolute_hours = hours.abs
       hrs = absolute_hours.floor

data/lib/astronoby/angles/dms.rb

@@ -1,9 +1,24 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in degrees, arcminutes, arcseconds (DMS) notation.
   class Dms
-    attr_reader :sign, :degrees, :minutes, :seconds
+    # @return [String] "+" or "-"
+    attr_reader :sign
 
+    # @return [Integer] degrees component
+    attr_reader :degrees
+
+    # @return [Integer] arcminutes component
+    attr_reader :minutes
+
+    # @return [Float] arcseconds component
+    attr_reader :seconds
+
+    # @param sign [String] "+" or "-"
+    # @param degrees [Integer] degrees component
+    # @param minutes [Integer] arcminutes component
+    # @param seconds [Float] arcseconds component
     def initialize(sign, degrees, minutes, seconds)
       @sign = sign
       @degrees = degrees
@@ -11,6 +26,8 @@ module Astronoby
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted DMS string (e.g., "+45° 30′ 15.0000″")
     def format(precision: 4)
       "#{sign}#{degrees}° #{minutes}′ #{seconds.floor(precision)}″"
     end

data/lib/astronoby/angles/hms.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angle in hours, minutes, seconds (HMS) notation.
   class Hms
-    attr_reader :hours, :minutes, :seconds
+    # @return [Integer] hours component
+    attr_reader :hours
 
+    # @return [Integer] minutes component
+    attr_reader :minutes
+
+    # @return [Float] seconds component
+    attr_reader :seconds
+
+    # @param hours [Integer] hours component
+    # @param minutes [Integer] minutes component
+    # @param seconds [Float] seconds component
     def initialize(hours, minutes, seconds)
       @hours = hours
       @minutes = minutes
       @seconds = seconds
     end
 
+    # @param precision [Integer] decimal places for the seconds component
+    # @return [String] the formatted HMS string (e.g., "12h 30m 45.0000s")
     def format(precision: 4)
       "#{hours}h #{minutes}m #{seconds.floor(precision)}s"
     end

data/lib/astronoby/angular_velocity.rb

@@ -1,18 +1,25 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents an angular velocity with radians per second as its internal
+  # representation. Used primarily for stellar proper motion.
   class AngularVelocity
     include Comparable
 
     class << self
+      # @return [Astronoby::AngularVelocity] a zero angular velocity
       def zero
         new(0)
       end
 
+      # @param radians_per_second [Numeric] the angular velocity in rad/s
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
       def from_radians_per_second(radians_per_second)
         new(radians_per_second)
       end
 
+      # @param mas_per_year [Numeric] the angular velocity in mas/yr
+      # @return [Astronoby::AngularVelocity] a new AngularVelocity
       def from_milliarcseconds_per_year(mas_per_year)
         angle = Angle.from_degree_arcseconds(mas_per_year / 1000.0)
         radians_per_second = angle.radians / Constants::SECONDS_PER_JULIAN_YEAR
@@ -20,52 +27,66 @@ module Astronoby
       end
     end
 
+    # @return [Numeric] the angular velocity in radians per second
     attr_reader :radians_per_second
     alias_method :rps, :radians_per_second
 
+    # @param radians_per_second [Numeric] the angular velocity in rad/s
     def initialize(radians_per_second)
       @radians_per_second = radians_per_second
       freeze
     end
 
+    # @return [Float] the angular velocity in milliarcseconds per year
     def milliarcseconds_per_year
       angle = Angle.from_radians(@radians_per_second)
       angle.degree_milliarcseconds * Constants::SECONDS_PER_JULIAN_YEAR
     end
     alias_method :mas_per_year, :milliarcseconds_per_year
 
+    # @param other [Astronoby::AngularVelocity] angular velocity to add
+    # @return [Astronoby::AngularVelocity] the sum
     def +(other)
       self.class.from_radians_per_second(
         @radians_per_second + other.radians_per_second
       )
     end
 
+    # @param other [Astronoby::AngularVelocity] angular velocity to subtract
+    # @return [Astronoby::AngularVelocity] the difference
     def -(other)
       self.class.from_radians_per_second(
         @radians_per_second - other.radians_per_second
       )
     end
 
+    # @return [Astronoby::AngularVelocity] the negated angular velocity
     def -@
       self.class.from_radians_per_second(-@radians_per_second)
     end
 
+    # @return [Boolean] true if the angular velocity is positive
     def positive?
       @radians_per_second > 0
     end
 
+    # @return [Boolean] true if the angular velocity is negative
     def negative?
       @radians_per_second < 0
     end
 
+    # @return [Boolean] true if the angular velocity is zero
     def zero?
       @radians_per_second.zero?
     end
 
+    # @return [Integer] hash value
     def hash
       [@radians_per_second, self.class].hash
     end
 
+    # @param other [Astronoby::AngularVelocity] angular velocity to compare with
+    # @return [Integer, nil] -1, 0, or 1; nil if not comparable
     def <=>(other)
       return unless other.is_a?(self.class)
 

data/lib/astronoby/bodies/deep_sky_object.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents a deep-sky object (star, galaxy, nebula, etc.) with optional
+  # proper motion and parallax data.
   class DeepSkyObject
+    include Body
+
     # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
     #   Equatorial coordinates at epoch J2000.0
     # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
@@ -37,7 +41,8 @@ module Astronoby
         proper_motion_ra: @proper_motion_ra,
         proper_motion_dec: @proper_motion_dec,
         parallax: @parallax,
-        radial_velocity: @radial_velocity
+        radial_velocity: @radial_velocity,
+        deep_sky_object: self
       )
     end
   end

data/lib/astronoby/bodies/deep_sky_object_position.rb

@@ -1,20 +1,33 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Represents the computed position of a deep-sky object at a specific
+  # instant, providing astrometric, apparent, and topocentric reference frames.
   class DeepSkyObjectPosition
+    include Position
+
     DEFAULT_DISTANCE = Distance.from_parsecs(1e9)
 
-    attr_reader :instant, :apparent
+    # @return [Astronoby::Instant] the time instant
+    attr_reader :instant
+
+    # @return [Astronoby::Apparent] the apparent reference frame
+    attr_reader :apparent
+
+    # @return [Astronoby::DeepSkyObject, nil] the body definition
+    attr_reader :body
 
     # @param instant [Astronoby::Instant] Instant of the observation
     # @param equatorial_coordinates [Astronoby::Coordinates::Equatorial]
     #   Equatorial coordinates at epoch J2000.0
+    # @param ephem [::Ephem::SPK, nil] Ephemeris data source for Earth position
     # @param proper_motion_ra [Astronoby::AngularVelocity, nil] Proper motion in
     #   right ascension
     # @param proper_motion_dec [Astronoby::AngularVelocity, nil] Proper motion
     #   in declination
     # @param parallax [Astronoby::Angle, nil] Parallax angle
     # @param radial_velocity [Astronoby::Velocity, nil] Radial velocity
+    # @param deep_sky_object [Astronoby::DeepSkyObject, nil] the body definition
     def initialize(
       instant:,
       equatorial_coordinates:,
@@ -22,7 +35,8 @@ module Astronoby
       proper_motion_ra: nil,
       proper_motion_dec: nil,
       parallax: nil,
-      radial_velocity: nil
+      radial_velocity: nil,
+      deep_sky_object: nil
     )
       @instant = instant
       @initial_equatorial_coordinates = equatorial_coordinates
@@ -30,6 +44,7 @@ module Astronoby
       @proper_motion_dec = proper_motion_dec
       @parallax = parallax
       @radial_velocity = radial_velocity
+      @body = deep_sky_object
       if ephem
         @earth_geometric = Earth.geometric(ephem: ephem, instant: @instant)
       end
@@ -42,24 +57,24 @@ module Astronoby
         instant: @instant,
         position: astrometric_position,
         velocity: astrometric_velocity,
-        center_identifier: SolarSystemBody::EARTH,
-        target_body: self
-      )
-    end
-
-    def observed_by(observer)
-      Topocentric.build_from_apparent(
-        apparent: @apparent,
-        observer: observer,
-        instant: @instant,
-        target_body: self
+        center: Center.geocentric,
+        target_body: body
       )
     end
 
     private
 
     def astrometric_position
-      @astrometric_position ||= if use_stellar_propagation?
+      @astrometric_position ||=
+        if @earth_geometric
+          barycentric_position - @earth_geometric.position
+        else
+          barycentric_position
+        end
+    end
+
+    def barycentric_position
+      if use_stellar_propagation?
         stellar_propagation.position
       else
         astronomical_distance = DEFAULT_DISTANCE.meters
@@ -98,30 +113,12 @@ module Astronoby
     end
 
     def compute_apparent
-      @apparent = if @earth_geometric
-        Apparent.build_from_astrometric(
-          instant: @instant,
-          target_astrometric: astrometric,
-          earth_geometric: @earth_geometric,
-          target_body: self
-        )
-      else
-        precession_matrix = Precession.matrix_for(@instant)
-        nutation_matrix = Nutation.matrix_for(@instant)
-        corrected_position = Distance.vector_from_meters(
-          precession_matrix * nutation_matrix * astrometric.position.map(&:m)
-        )
-        corrected_velocity = Velocity.vector_from_mps(
-          precession_matrix * nutation_matrix * astrometric.velocity.map(&:mps)
-        )
-        Apparent.new(
-          position: corrected_position,
-          velocity: corrected_velocity,
-          instant: @instant,
-          center_identifier: SolarSystemBody::EARTH,
-          target_body: self
-        )
-      end
+      @apparent = Apparent.build_from_astrometric(
+        instant: @instant,
+        target_astrometric: astrometric,
+        earth_geometric: @earth_geometric,
+        target_body: body
+      )
     end
   end
 end