astronoby 0.10.0 → 0.11.0

data/docs/lunar_eclipses.md

@@ -1,6 +1,6 @@
 # Lunar Eclipses
 
-Astronoby computes lunar eclipses: the passages of the Moon through Earth's shadow. A lunar eclipse is a geocentric event, the same for every observer who can see the Moon, so no observer is involved. The geometry is built from the apparent geocentric positions of the Sun and Moon, which matches the standard reduction used by [NASA's Five Millennium Canon of Lunar Eclipses] and by IMCCE.
+Astronoby computes lunar eclipses: the passages of the Moon through Earth's shadow. A lunar eclipse is a geocentric event, the same for every observer who can see the Moon, so finding one takes no observer. What one place sees of it depends only on whether the Moon is above its horizon, which is covered in [Local circumstances](#local-circumstances) below. The geometry is built from the apparent geocentric positions of the Sun and Moon, which matches the standard reduction used by [NASA's Five Millennium Canon of Lunar Eclipses] and by IMCCE.
 
 There are three kinds of lunar eclipses. A penumbral eclipse is when the Moon only enters Earth's penumbra, the outer, partial shadow. A partial eclipse is when part of the Moon enters the umbra, the inner, total shadow. A total eclipse is when the whole Moon enters the umbra.
 
@@ -18,20 +18,20 @@ eclipses = Astronoby::Moon.eclipse_events(
 )
 
 eclipses.map { |eclipse| [eclipse.instant.to_time, eclipse.kind] }
-# => [[2025-03-14 06:58:47 UTC, :total], [2025-09-07 18:11:49 UTC, :total]]
+# => [[2025-03-14 06:58:46 UTC, :total], [2025-09-07 18:11:49 UTC, :total]]
 ```
 
 ## An eclipse
 
-Each eclipse is an `Astronoby::LunarEclipse`. Its `#instant` (also available as `#greatest_eclipse`) is the moment of greatest eclipse, when the Moon's centre is least distant from the axis of Earth's shadow.
+Each eclipse is an `Astronoby::LunarEclipse`. Its `#instant` (also available as `#greatest_eclipse_instant`) is the moment of greatest eclipse, when the Moon's centre is least distant from the axis of Earth's shadow.
 
 ```rb
 eclipse = eclipses.first
 
 eclipse.kind                 # => :total
 eclipse.total?               # => true
-eclipse.instant.to_time      # => 2025-03-14 06:58:47 UTC
-eclipse.greatest_eclipse     # => same as #instant
+eclipse.instant.to_time      # => 2025-03-14 06:58:46 UTC
+eclipse.greatest_eclipse_instant # => same as #instant
 ```
 
 The umbral and penumbral magnitudes are the fractions of the Moon's diameter immersed in the umbra and the penumbra at greatest eclipse. The umbral magnitude is negative for a penumbral eclipse (the Moon misses the umbra), between 0 and 1 for a partial eclipse, and 1 or more for a total eclipse.
@@ -41,7 +41,7 @@ eclipse.umbral_magnitude     # => 1.179
 eclipse.penumbral_magnitude  # => 2.26
 ```
 
-`#gamma` is the least distance of the Moon's centre from the axis of Earth's shadow at greatest eclipse, in Earth radii, positive when the Moon passes north of the axis and negative when it passes south. It is the standard, dimensionless eclipse parameter used by IMCCE and NASA. The same quantity is also available as a `Astronoby::Distance` through `#shadow_axis_distance`.
+`#gamma` is the least distance of the Moon's centre from the axis of Earth's shadow at greatest eclipse, in Earth radii, positive when the Moon passes north of the axis and negative when it passes south. It is the standard, dimensionless eclipse parameter used by IMCCE and NASA. The same quantity is also available as an `Astronoby::Distance` through `#shadow_axis_distance`, and the side of the axis it takes its sign from is on the geometry as `#north_of_axis?`.
 
 ```rb
 eclipse.gamma                       # => 0.348
@@ -50,21 +50,53 @@ eclipse.shadow_axis_distance.km     # => 2222.37
 
 ## Phases
 
-An eclipse exposes its phases as `Astronoby::EclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` (an `Astronoby::Duration`). The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
+An eclipse exposes its phases as `Astronoby::LunarEclipsePhase` objects, each with a `#starting_instant`, an `#ending_instant`, and a `#duration` (an `Astronoby::Duration`). The penumbral phase is always present. The partial phase is present for partial and total eclipses, and the total phase (totality) only for total eclipses. A phase that does not occur is `nil`.
 
 ```rb
-eclipse.penumbral.starting_instant.to_time # => 2025-03-14 03:57:29 UTC (P1)
-eclipse.partial.starting_instant.to_time   # => 2025-03-14 05:09:37 UTC (U1)
-eclipse.total.starting_instant.to_time     # => 2025-03-14 06:26:01 UTC (U2)
-eclipse.total.ending_instant.to_time       # => 2025-03-14 07:31:32 UTC (U3)
+eclipse.penumbral.starting_instant.to_time # => 2025-03-14 03:57:28 UTC (P1)
+eclipse.partial.starting_instant.to_time   # => 2025-03-14 05:09:36 UTC (U1)
+eclipse.total.starting_instant.to_time     # => 2025-03-14 06:26:02 UTC (U2)
+eclipse.total.ending_instant.to_time       # => 2025-03-14 07:31:29 UTC (U3)
 eclipse.partial.ending_instant.to_time     # => 2025-03-14 08:47:55 UTC (U4)
 eclipse.penumbral.ending_instant.to_time   # => 2025-03-14 10:00:08 UTC (P4)
 
-eclipse.total.duration.seconds # => 3931 (seconds of totality)
+eclipse.total.duration.seconds # => 3927.11 (seconds of totality)
 ```
 
 For a penumbral eclipse, `#partial` and `#total` are `nil`. For a partial eclipse, `#total` is `nil`.
 
+## Shadow geometry
+
+`Astronoby::LunarEclipseGeometry` describes Earth's shadow and the Moon's place in it at one instant. The eclipse carries the geometry at greatest eclipse, and each phase carries the geometry at its two contacts, so all six contacts of a total eclipse are reachable as well as greatest eclipse. It gives the size of the two shadow cones, how far the Moon's centre is from the shadow axis, and where on the Moon's limb the shadow bites.
+
+```rb
+geometry = eclipse.geometry
+
+geometry.umbra_angular_radius.degrees * 60     # => 39.23 (arcminutes)
+geometry.penumbra_angular_radius.degrees * 60  # => 71.39
+geometry.angular_axis_distance.degrees * 60    # => 19.03
+geometry.position_angle.degrees                # => 29.07
+```
+
+The cone radii are measured in the plane perpendicular to the shadow axis at the Moon's distance, which is where they are published. They are available as an `Astronoby::Distance` through `#umbra_radius` and `#penumbra_radius`, and as an `Astronoby::Angle` through `#umbra_angular_radius` and `#penumbra_angular_radius`. `#moon_distance` is the geocentric distance of the Moon, the distance of that plane.
+
+`#position_angle` is the position angle of the contact point on the Moon's limb, seen from the Moon's centre, from celestial north through east. This is the quantity IMCCE and NASA publish. At greatest eclipse, where there is no contact point, it is the direction from the shadow axis to the Moon, which is what they report there too.
+
+`#umbral_magnitude` and `#penumbral_magnitude` are available at any of these instants, not only at greatest eclipse. Each one is 0 at the contacts that define it, so the penumbral magnitude at P1 and P4 and the umbral magnitude at U1 and U4. The umbral magnitude is 1 at U2 and U3, where the Moon is wholly inside the umbra. The penumbral magnitude is well past 1 by then, since the Moon is far deeper into the penumbra than into the umbra.
+
+```rb
+eclipse.penumbral.starting_geometry.penumbral_magnitude # => 0.0 (P1)
+eclipse.partial.starting_geometry.umbral_magnitude      # => 0.0 (U1)
+eclipse.total.starting_geometry.umbral_magnitude        # => 1.0 (U2)
+```
+
+```rb
+eclipse.penumbral.starting_geometry.position_angle.degrees # => 131.8 (P1)
+eclipse.total.starting_geometry.position_angle.degrees     # => 350.46 (U2)
+```
+
+Note that IMCCE labels the end of the penumbral phase `P2`, where this documentation uses `P4`.
+
 ```rb
 penumbral_eclipse = Astronoby::Moon.eclipse_events(
   ephem: ephem,
@@ -77,9 +109,92 @@ penumbral_eclipse.partial # => nil
 penumbral_eclipse.total   # => nil
 ```
 
+## Local circumstances
+
+The eclipse is the same everywhere, so there is no path of visibility to compute. All that changes from place to place is whether the Moon is above the horizon, and visibility is the intersection of the eclipse with the time the Moon spends up. Half the Earth sees an eclipse; the other half is in daylight, with the Moon below the horizon.
+
+`LunarEclipse#visibility_from` takes an `Astronoby::Observer` and returns an `Astronoby::LunarEclipseVisibility`. No ephemeris is involved: the Moon's place at every contact is already carried by the geometry, so an eclipse can be observed from as many places as wanted, including after a round trip through a cache.
+
+```rb
+paris = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.8566),
+  longitude: Astronoby::Angle.from_degrees(2.3522)
+)
+
+visibility = eclipse.visibility_from(paris)
+
+visibility.visible?           # => true
+visibility.entirely_visible?  # => false
+visibility.circumstance       # => :ends_after_moonset
+```
+
+`#circumstance` sums up what the place gets of the eclipse:
+
+- `:not_visible`, the Moon is below the horizon for the whole eclipse
+- `:entirely_visible`, the Moon is up from the first to the last penumbral contact
+- `:begins_before_moonrise`, the eclipse is already under way when the Moon rises
+- `:ends_after_moonset`, the eclipse is still under way when the Moon sets
+- `:partially_visible`, anything else, which at high latitudes can be the Moon rising and setting within the eclipse
+
+`#coverage` takes a phase and answers how much of it happens with the Moon up, in the same three words `#circumstance` uses of the whole eclipse: `:entirely_visible`, `:partially_visible`, `:not_visible`, or `nil` when the eclipse has no such phase. In the example, in Paris, the Moon sets during the partial phase, before totality begins.
+
+```rb
+visibility.coverage(:penumbral) # => :partially_visible
+visibility.coverage(:partial)   # => :partially_visible
+visibility.coverage(:total)     # => :not_visible
+```
+
+`#horizon_crossings` are the instants of the eclipse at which the Moon rises or sets, and `#observable_windows` are the stretches of the eclipse spent with the Moon up. There is one window for an eclipse seen whole or in part, none for one not seen at all, and more than one only where the Moon crosses the horizon repeatedly.
+
+```rb
+visibility.horizon_crossings.map { |instant| instant.to_time }
+# => [2025-03-14 06:11:41 UTC]
+
+visibility.observable_windows.map { |window| [window.first.to_time, window.last.to_time] }
+# => [[2025-03-14 03:57:28 UTC, 2025-03-14 06:11:41 UTC]]
+```
+
+From Mexico City the same eclipse runs from end to end with the Moon high in the sky.
+
+```rb
+mexico_city = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(19.4326),
+  longitude: Astronoby::Angle.from_degrees(-99.1332)
+)
+
+visibility = eclipse.visibility_from(mexico_city)
+
+visibility.circumstance     # => :entirely_visible
+visibility.coverage(:total) # => :entirely_visible
+visibility.horizon_crossings # => []
+```
+
+`#above_horizon_at?` answers whether the Moon is up at an instant of the eclipse, and raises outside it.
+
+```rb
+visibility.above_horizon_at?(eclipse.total.starting_instant) # => true
+```
+
+Visibility answers whether the Moon is up, not how high it is. The Moon's place at each contact is interpolated from what the eclipse carries, which is what lets an eclipse be observed from anywhere without an ephemeris, and that is accurate well past what the horizon convention can resolve. For the altitude itself, ask the Moon, which computes it from the ephemeris with no interpolation at all.
+
+```rb
+Astronoby::Moon
+  .new(ephem: ephem, instant: eclipse.total.starting_instant)
+  .observed_by(mexico_city)
+  .horizontal
+  .altitude
+  .degrees # => 72.45
+```
+
+The Moon counts as up once its upper limb clears the refracted horizon, which is the convention Astronoby uses for moonrise and moonset, through `Astronoby::Horizon`.
+
 ## Precision
 
-Earth's shadow is enlarged by its atmosphere. Astronoby enlarges Earth's radius by 1/99 before building the shadow cones, a factor calibrated against IMCCE. Validated across the 2023 to 2025 eclipses, the eclipse kind, greatest eclipse instant, magnitudes, and contact times all match IMCCE to within a second or two.
+Two conventions shape the result. Earth's shadow is enlarged by its atmosphere, so Astronoby adds a 64 km shell to Earth's radius before building the shadow cones. And eclipse contacts are reduced with the IAU eclipse constant k, which puts the Moon's radius at 1738.09 km, slightly above its physical equatorial radius. Both are calibrated against IMCCE.
+
+Validated against IMCCE, the eclipse kind and the magnitudes match, and the contacts agree to within a couple of seconds. The shadow radii and the distance from the shadow axis match to well under an arcsecond, and position angles to 0.03 degrees.
+
+The local circumstances are reduced without the ephemeris, from the Moon's place at the contacts and the sidereal rate. The altitudes agree with the topocentric places computed from the ephemeris to under an arcminute, and the horizon crossings put the Moon on the horizon to a few arcseconds, which is well inside the uncertainty of the fixed refraction the convention assumes.
 
 ## See also
 

data/docs/twilight_times.md

@@ -77,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:25 UTC,
-#  2025-08-04 02:32:30 UTC,
-#  2025-08-05 02:33:34 UTC,
-#  2025-08-06 02:34:39 UTC,
-#  2025-08-07 02:35:44 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`
@@ -104,23 +104,38 @@ event.morning_astronomical_twilight_time
 # => 2025-05-01 01:16:21 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 01:55:54 UTC
+# => 2025-05-01 01:55:49 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 17:30:45 UTC
+# => 2025-05-01 17:30:50 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 18:07:13 UTC
+# => 2025-05-01 18:07:27 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 18:46:47 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/bodies/deep_sky_object_position.rb

@@ -113,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: body
-        )
-      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: Center.geocentric,
-          target_body: body
-        )
-      end
+      @apparent = Apparent.build_from_astrometric(
+        instant: @instant,
+        target_astrometric: astrometric,
+        earth_geometric: @earth_geometric,
+        target_body: body
+      )
     end
   end
 end

data/lib/astronoby/cache.rb

@@ -175,6 +175,19 @@ module Astronoby
         [type, rounded_tt, *components]
       end
 
+      # Generate a cache key for a UTC time, without rounding. Sidereal time
+      # moves by about 15 arcseconds per second, so unlike nutation it can't
+      # share an entry with a nearby instant.
+      # @param type [Symbol] The calculation type (e.g., :gmst)
+      # @param utc [Time] The UTC time
+      # @param components [Array] Additional components for the key
+      # @return [Array, nil] The complete cache key, nil if cache is disabled
+      def generate_for_utc(type, utc, *components)
+        return nil unless Astronoby.configuration.cache_enabled?
+
+        [type, utc.to_r, *components]
+      end
+
       # Round terrestrial time to specified precision
       # @param tt [Numeric] Terrestrial time value
       # @param precision [Numeric] Precision in seconds

data/lib/astronoby/constants.rb

@@ -36,6 +36,7 @@ module Astronoby
 
     # WGS84 Earth Constants
     WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS = 6378137
+    IAU_MOON_RADIUS_IN_METERS = 0.2725076 * WGS84_EARTH_EQUATORIAL_RADIUS_IN_METERS
     WGS84_INVERSE_FLATTENING = 298.257223563
     WGS84_FLATTENING = 1.0 / WGS84_INVERSE_FLATTENING
     WGS84_ECCENTICITY_SQUARED = 2.0 * WGS84_FLATTENING - WGS84_FLATTENING * WGS84_FLATTENING
@@ -45,7 +46,5 @@ module Astronoby
     EARTH_FLATTENING_CORRECTION = 0.996647
 
     EARTH_ANGULAR_VELOCITY_RAD_PER_S = 7.2921159e-5
-
-    TAI_TT_OFFSET = 32.184
   end
 end

data/lib/astronoby/constellations/data.rb

@@ -31,7 +31,7 @@ module Astronoby
       end
 
       def self.read_file(filename)
-        File.readlines(data_path(filename)).map(&:strip)
+        File.readlines(data_path(filename), encoding: "UTF-8").map(&:strip)
       end
 
       def self.data_path(filename)

data/lib/astronoby/coordinates/equatorial.rb

@@ -32,17 +32,23 @@ module Astronoby
         @epoch = epoch
       end
 
+      # @param epoch [Numeric] Julian Date epoch the coordinates are referred to
       # @return [Astronoby::Coordinates::Equatorial] zero coordinates
-      def self.zero
-        new(declination: Angle.zero, right_ascension: Angle.zero)
+      def self.zero(epoch: JulianDate::DEFAULT_EPOCH)
+        new(
+          declination: Angle.zero,
+          right_ascension: Angle.zero,
+          epoch: epoch
+        )
       end
 
       # Derives equatorial coordinates from a position vector.
       #
       # @param position [Astronoby::Vector<Astronoby::Distance>] position vector
+      # @param epoch [Numeric] Julian Date epoch the vector is referred to
       # @return [Astronoby::Coordinates::Equatorial] equatorial coordinates
-      def self.from_position_vector(position)
-        return zero if position.zero?
+      def self.from_position_vector(position, epoch: JulianDate::DEFAULT_EPOCH)
+        return zero(epoch: epoch) if position.zero?
 
         term1 = position.z.m
         term2 = position.magnitude.m
@@ -58,7 +64,11 @@ module Astronoby
             angle
           )
 
-        new(declination: declination, right_ascension: right_ascension)
+        new(
+          declination: declination,
+          right_ascension: right_ascension,
+          epoch: epoch
+        )
       end
 
       # Computes the hour angle for a given time and observer longitude.

data/lib/astronoby/delta_t.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "iers"
+
+module Astronoby
+  module DeltaT
+    class << self
+      # @param instant [Numeric, Time, Date, DateTime] a Julian Date, or a date
+      #   and time. Any time scale will do.
+      # @return [Numeric] ΔT in seconds
+      # @raise [Astronoby::IncompatibleArgumentsError] if the instant is not a
+      #   Numeric, Time, Date or DateTime
+      def at(instant)
+        case instant
+        when Numeric
+          IERS::DeltaT.at(jd: instant).delta_t
+        when ::Time, ::Date, ::DateTime
+          IERS::DeltaT.at(instant).delta_t
+        else
+          raise IncompatibleArgumentsError,
+            "Expected a Numeric, Time, Date or DateTime object, got #{instant.class}"
+        end
+      rescue IERS::OutOfRangeError => error
+        outside_available_range(error)
+      end
+
+      private
+
+      # IERS covers 1800 up to the end of its EOP series, and refuses anything
+      # outside. Rather than propagate that, we answer with the closest value
+      # we have: 0 before 1800, where ΔT is small next to the uncertainty on
+      # it, and the last measured value after the series, which drifts slowly
+      # enough to beat any extrapolation we could invent.
+      def outside_available_range(error)
+        last_measured = IERS::Data.finals_entries.last
+        return 0 if last_measured.nil?
+        return 0 if error.requested_mjd.nil?
+        return 0 if error.requested_mjd < last_measured.mjd
+
+        IERS::DeltaT.at(mjd: last_measured.mjd).delta_t
+      end
+    end
+  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