astronoby 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e781560f80c12781becc942c58f026386dbc252bff0830ab154e1217dba319f
-  data.tar.gz: '0939683834940fe9bef423fe6e59b5a8ce5a1c53921015ee612c0f258c0fd224'
+  metadata.gz: 1093c9a0d077cfa9c2a9fcf60e2af2a21ec4c1f74c268ef22dca8e93b5badadb
+  data.tar.gz: e12ccfad49e7a63821cde3b382e8584efdff3c0c06a42ffddf60119ad213b2f5
 SHA512:
-  metadata.gz: 731fe3a326ddeca238f9479647e61e0554bbef2e10a35e468079240a58e8482a3e21b316fc61d5bcfb6962de353002e882c1e104f3e5c1626f6a02177a55a9a1
-  data.tar.gz: 035fb37802b80e6be88c216d0b117e3804bcd55c75871c4de4d6554e55fe8634f39e7dfe73e794bef4d00d35e59ccdbab65851bf34525a05f3ef290c4a5d2373
+  metadata.gz: cc73661c433669d3b9efcd816088513a031d7c8c609844988e0ecabed36959e9a361d15d8cbd87905f83bfcb3685640dbad1a7862d624a6895b0b78fe0aa54f7
+  data.tar.gz: 7c544cd27042ec8436d2c11a9f27c6269e039256dadb1ba80a62dac6b3140669420c336df950077aa6a54786158f5c2f3b91744b3cacf67de2003db686ffca37

data/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## 0.11.0 - 2026-10-31
+
+_If you are upgrading: please see [UPGRADING.md]._
+
+### Bug fixes
+
+* Apply nutation after precession for a `DeepSkyObject` without an ephemeris.
+  The two rotations were composed in the wrong order, so the apparent position
+  was off by up to about 0.1 arcsecond depending on the date, and the velocity
+  had the same error. The rotation now matches ERFA and Skyfield, and is the
+  one used when an ephemeris is given. Without an ephemeris there is still no
+  aberration correction ([#316])
+* Let the rise, transit and set refinement move an estimate back in time. The
+  correction was clamped to be positive, so an estimate that overshot its event
+  could never be brought back, and settings and transits came out up to a few
+  minutes late depending on the window asked for ([#301])
+* Refer equatorial coordinates to the epoch of the frame they come from
+  ([#302])
+* Return real Barycentric Dynamical Time from `Instant#tdb`, which returned
+  Terrestrial Time unchanged. The two scales differ by up to about 1.7
+  milliseconds ([#304])
+* Keep ΔT at its last measured value past the end of the IERS series. `iers`
+  0.3.0 stopped attaching an `available_range` to the `OutOfRangeError` it
+  raises for an uncovered date, and the fallback read that absence as "no data
+  at all" and answered 0. Every date after the bundled series, currently
+  2027-09-04, was off by about 69 seconds ([#304])
+* Read the constellation data files as UTF-8, so that `Constellations::Finder`
+  and `Constellations::Repository` work when the default external encoding is
+  not UTF-8, as under `LANG=C`
+
+### Features
+
+* Add `HorizontalTransformation`, which converts equatorial coordinates at
+  J2000 epoch into horizontal coordinates for one observer and one instant. The
+  rotation and the sidereal time are computed once, which makes converting many
+  points, like the stars of a catalogue, about 70 times faster than going
+  through `DeepSkyObject#at(instant).observed_by(observer).horizontal`. Points
+  are treated as fixed directions, as for a `DeepSkyObject` without an
+  ephemeris. `refraction:` is an option ([#317])
+* Add `AltitudeCrossingCalculator`, which finds when a body reaches any
+  altitude, with unrounded instants, the crossing direction, a grazing flag and
+  the culminations. `refraction:` and `reference:` (`:center`, `:upper_limb`,
+  `:lower_limb`) are options ([#311])
+* Expose lunar eclipse shadow geometry at greatest eclipse and at every contact
+  ([#300])
+* Add lunar eclipse local circumstances with `LunarEclipse#visibility_from`
+  ([#302])
+* Expose the Moon's apparent place at every lunar eclipse contact ([#302])
+
+### Improvements
+
+* Cache Greenwich mean and apparent sidereal times when the cache is enabled.
+  The cache is still disabled by default, which is now stated in the README
+  ([#320])
+* Compute the TAI and TDB time scales with the horologium gem, which owns the
+  scales that convert by definition or by model. UT1 stays in Astronoby
+  ([#304])
+* Read `Instant#tai` and `#tdb` as a `Rational`, which a `Float` Julian Date is
+  too coarse to hold ([#304])
+* Evaluate `Precession` in TT, as SOFA and ERFA do ([#304])
+* Raise the minimum `iers` version from 0.1 to 0.3.1, which `horologium`
+  requires ([#304])
+* Share the rise and set horizon convention through `Astronoby::Horizon`
+  ([#311])
+* Derive a lunar eclipse's magnitudes, axis distance and gamma from its
+  geometry ([#300], [#302])
+* Resolve the lunar eclipse shadow axis offset with vectors ([#302])
+* Reduce the Moon to the observer by vectors for lunar eclipse visibility
+  ([#302])
+* Answer lunar eclipse phase coverage in the words the whole eclipse uses
+  ([#302])
+* Pin CI runner to ubuntu-24.04 ([#312])
+* Fix CI for the standard and simplecov bumps ([#319])
+* Bump rubyzip from 3.4.0 to 3.7.0 by @dependabot ([#285], [#299], [#305],
+  [#308])
+* Bump standard from 1.55.0 to 1.56.0 by @dependabot ([#288])
+* Bump simplecov from 0.22 to 1.0.3 by @dependabot ([#287], [#289], [#291])
+* Bump iers from 0.1.0 to 0.2.0 by @dependabot ([#284], [#294])
+* Update json to 2.21.2 ([#296])
+
+### Backward-incompatible changes
+
+* `TwilightCalculator` is based on `AltitudeCrossingCalculator`. Times change
+  slightly: up to about 30 seconds at the standard angles, and up to about 100
+  seconds with `time_for_zenith_angle` and custom angles. The new values match
+  IMCCE, Horizons and Skyfield. Twilight that exists is returned when the Sun
+  doesn't rise or set, as in a polar night, instead of `nil`. Results are still
+  rounded to the second. `#event_on` is about 1.8 times slower than before,
+  because it solves for the real crossing instead of approximating the Sun's
+  position from a single evaluation ([#311])
+* Equatorial coordinates carry the epoch of the frame they come from ([#302])
+* `Instant#tdb` returns real TDB, and `#tai` and `#tdb` return a `Rational`
+  ([#304])
+* Remove `Constants::TAI_TT_OFFSET` ([#304])
+* `Util::Time.terrestrial_universal_time_delta` is replaced by `DeltaT.at`
+  ([#295])
+* `EclipsePhase` is now `LunarEclipsePhase`, `LunarEclipse#greatest_eclipse` is
+  now `#greatest_eclipse_instant`, `LunarEclipse.new` no longer accepts the
+  magnitudes, gamma or shadow axis distance, and `LunarEclipsePhase#duration` is
+  no longer rounded ([#300], [#302])
+* Remove `LunarEclipseVisibility#altitude_at` ([#302])
+* Lunar eclipse contacts are reduced with the IAU eclipse constant k. Contact
+  times may shift by a second or two, and magnitudes by up to about 0.001
+  ([#302])
+* Bisect to a millisecond rather than to a second when locating an event in
+  time. Conjunction and opposition times may move by a fraction of a second, and
+  searches are about 20% slower ([#302])
+
+**Full Changelog**: https://github.com/rhannequin/astronoby/compare/v0.10.0...v0.11.0
+
+[#284]: https://github.com/rhannequin/astronoby/pull/284
+[#285]: https://github.com/rhannequin/astronoby/pull/285
+[#287]: https://github.com/rhannequin/astronoby/pull/287
+[#288]: https://github.com/rhannequin/astronoby/pull/288
+[#289]: https://github.com/rhannequin/astronoby/pull/289
+[#291]: https://github.com/rhannequin/astronoby/pull/291
+[#294]: https://github.com/rhannequin/astronoby/pull/294
+[#295]: https://github.com/rhannequin/astronoby/pull/295
+[#296]: https://github.com/rhannequin/astronoby/pull/296
+[#299]: https://github.com/rhannequin/astronoby/pull/299
+[#300]: https://github.com/rhannequin/astronoby/pull/300
+[#301]: https://github.com/rhannequin/astronoby/pull/301
+[#302]: https://github.com/rhannequin/astronoby/pull/302
+[#304]: https://github.com/rhannequin/astronoby/pull/304
+[#305]: https://github.com/rhannequin/astronoby/pull/305
+[#308]: https://github.com/rhannequin/astronoby/pull/308
+[#311]: https://github.com/rhannequin/astronoby/pull/311
+[#312]: https://github.com/rhannequin/astronoby/pull/312
+[#316]: https://github.com/rhannequin/astronoby/pull/316
+[#317]: https://github.com/rhannequin/astronoby/pull/317
+[#319]: https://github.com/rhannequin/astronoby/pull/319
+[#320]: https://github.com/rhannequin/astronoby/pull/320
+[UPGRADING.md]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md
+
 ## 0.10.0 - 2026-06-26
 
 _If you are upgrading: please see [UPGRADING.md]._

data/README.md

@@ -73,6 +73,19 @@ automated guiding of amateur telescopes and some professional use-cases.
 The sources used for comparison are: [IMCCE], [JPL Horizons], [Stellarium],
 and the [Skyfield] library.
 
+## Performance
+
+Astronoby has an internal cache for intermediate results like nutation,
+precession and sidereal time. It is disabled by default. It helps when the same
+computation is repeated at one instant, for example for many bodies or many
+points seen by one observer, and can make it about 2.5 times faster:
+
+```rb
+Astronoby.configuration.cache_enabled = true
+```
+
+See the [configuration documentation](docs/configuration.md) for the details.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/UPGRADING.md

@@ -7,6 +7,192 @@ changes to it as long as a major version has not been released.
 If you are already using Astronoby and wish to follow the changes to its
 public API, please read the upgrading notes for each release.
 
+## Upgrading from 0.10.0 to 0.11.0
+
+### Lunar eclipse contacts and magnitudes have changed slightly
+
+Lunar eclipse contacts are now reduced with the IAU eclipse constant
+k = 0.2725076 Earth radii, putting the Moon's radius at 1738.09 km, instead of
+its physical equatorial radius of 1737.4 km. This is what IMCCE and NASA reduce
+eclipses with. The atmospheric enlargement of Earth's shadow has been
+recalibrated alongside it, from 1/99 of Earth's radius to a 64 km shell.
+
+The two constants have to move together: either one alone makes agreement with
+IMCCE worse, because the old 1/99 enlargement was partly compensating for the
+smaller lunar radius. Together they cut the contact-time error against IMCCE by
+more than half, and the worst case over the 2026 to 2048 eclipses from 8.9
+seconds to 2.2 seconds.
+
+Contact times may shift by a second or two, and the magnitudes by up to about
+0.001. Greatest eclipse, `#gamma` and `#shadow_axis_distance` are unaffected,
+since they depend on neither constant.
+
+### `EclipsePhase` is now `LunarEclipsePhase`
+
+`Astronoby::EclipsePhase` has been renamed to `Astronoby::LunarEclipsePhase`.
+Its geometry is a `LunarEclipseGeometry`, so the class was never general to
+every kind of eclipse, and the old name reserved a place that solar eclipses
+will need.
+
+### A lunar eclipse and its phases are built from fewer values
+
+`Astronoby::LunarEclipsePhase.new` requires `starting_geometry:` and
+`ending_geometry:`, and `Astronoby::LunarEclipse.new` requires `geometry:`,
+each an `Astronoby::LunarEclipseGeometry`.
+
+`LunarEclipse.new` no longer accepts `umbral_magnitude:`,
+`penumbral_magnitude:`, `gamma:` or `shadow_axis_distance:`. All four are now
+read off the geometry at greatest eclipse, so an eclipse can no longer be
+built holding values that contradict its own geometry. The readers are
+unchanged.
+
+Both objects are built by `Astronoby::LunarEclipseCalculator`, so this only
+affects code constructing them directly.
+
+### `LunarEclipse#greatest_eclipse` is now `#greatest_eclipse_instant`
+
+The method returns an `Astronoby::Instant`, not an eclipse. `#instant` remains
+available and is the same value.
+
+### `LunarEclipsePhase#duration` is no longer rounded
+
+The duration was rounded to whole seconds. It is now measured on the
+terrestrial time scale, which is continuous, so it is unaffected by a leap
+second falling inside the phase, and it keeps the fraction of a second.
+`#duration.seconds` may now return a Float with a fractional part.
+
+### Equatorial coordinates carry the epoch of the frame they came from
+
+`#equatorial` reported the J2000 epoch on every reference frame, including
+frames referred to the equator and equinox of date. Precessing a mean of date,
+apparent, topocentric or TEME place was therefore a no operation rather than
+removing the precession accumulated since J2000, and `GeocentricParallax`
+carried the wrong epoch into anything derived from one.
+
+`MeanOfDate`, `Apparent`, `Topocentric` and `Teme` now report their own
+instant as the epoch, through a new `#epoch` reader on `ReferenceFrame`.
+`Geometric` and `Astrometric` are unchanged, since both are built on the ICRS
+and were already right.
+
+Code passing an of date coordinate to
+`Precession.for_equatorial_coordinates` will now get a precessed result where
+it previously got the coordinate back nearly unchanged.
+
+### Twilight times are computed from altitude crossings
+
+`TwilightCalculator` is now built on `AltitudeCrossingCalculator`, which finds
+the instant the Sun's centre reaches each altitude directly. The previous
+approach was an approximation that could be off by tens of seconds.
+
+Times change slightly: up to about 30 seconds at the standard angles, and up to
+about 100 seconds with `time_for_zenith_angle` and custom angles. The new
+values agree with IMCCE, JPL Horizons and Skyfield. Results are still rounded
+to the second.
+
+When the Sun doesn't rise or set, as in a polar night, the twilight that does
+happen is now returned instead of `nil`. A twilight that never happens, such as
+astronomical twilight at high latitude in midsummer, is still `nil`.
+
+`TwilightCalculator#event_on` is about 1.8 times slower than before, from around
+4 to around 7.5 milliseconds for one day. The previous version approximated the
+Sun's position from a single evaluation, which could be off by up to 30
+seconds. This one solves for the real crossing, evaluating the Sun's position
+about 20 times, and agrees with IMCCE, JPL Horizons and Skyfield to the second.
+
+### Rise, transit and set times are no longer late
+
+The refinement of a rise, transit or set time could only move its estimate
+forward in time. An estimate that overshot its event was never brought back, so
+settings and transits came out up to a few minutes late depending on the window
+asked for. Moon transits now agree with Skyfield to the second. Expect Moon
+times to move by up to a few minutes, and Sun and planet times by a few
+seconds.
+
+### Event times are located more precisely
+
+Bisection accepted a root once its bracket fell under 0.864 seconds, so a
+reported time could sit up to 0.43 seconds from the root of the model it came
+from. It now bisects to under a millisecond. Conjunction and opposition times
+may move by a fraction of a second, and a time that sat near a whole second
+may round to the next one.
+
+A sample landing exactly on a root is also no longer missed, and bisection
+stops if a bracket reaches the resolution of a Float rather than looping.
+
+### New `horologium` dependency, and `iers` raised to 0.3.1
+
+The TAI and TDB time scales are now computed by the
+[`horologium`](https://github.com/rhannequin/horologium) gem, which owns the
+scales that convert by definition or by model. UT1 stays in Astronoby: it
+follows the actual rotation of the Earth rather than a definition, and comes
+from `Astronoby::DeltaT`. Nothing else about time changes, and `Instant#tt`,
+`#to_time`, `#to_date`, `#to_datetime`, `#delta_t`, `#gmst`, `#gast`, `#lmst`
+and `#last` are untouched.
+
+`horologium` requires `iers` 0.3.1, so the minimum `iers` version is raised
+from 0.1 to 0.3.1. One `iers` API Astronoby used did change on the way: `iers`
+0.3.0 stopped attaching an `available_range` to the `OutOfRangeError` that
+`DeltaT.at` raises for a date it cannot answer. Astronoby reads the end of the
+published series directly now, so ΔT past that end still comes back as the last
+measured value rather than 0.
+
+Astronoby pins the precision it asks `horologium` for, so an application that
+calls `Horologium.configure` for its own purposes cannot change what Astronoby
+computes.
+
+### `Instant#tdb` now returns Barycentric Dynamical Time
+
+`tdb` previously returned Terrestrial Time unchanged, documented in the source
+as an approximation. It now returns real TDB, from the Fairhead and Bretagnon
+series that ERFA uses. The two scales differ by up to about 1.7 milliseconds.
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+# Before
+instant.tdb          # => 2460796
+
+# After
+instant.tdb.to_f     # => 2460796.000000017
+```
+
+`Precession` is now evaluated in TT, as SOFA and ERFA do. It read `tdb` before,
+which was TT under another name, so precession results are unchanged.
+
+### `Instant#tai` and `#tdb` return a `Rational`
+
+Both are read as a `Rational` rather than a `Float`. A Julian Date is around
+2.46 million, so a single `Float` rounds to about 47 microseconds of the day,
+which is more than the whole TDB - TT correction. Call `to_f` where a `Float`
+is what you want.
+
+`tai` is now exactly 32.184 seconds behind TT. It was within a few femtoseconds
+of that for an instant built from an `Integer` or a `Rational`, the offset
+having been built from a `Float` literal, and up to 47 microseconds off for one
+built from a `Float`, where the result came back as a `Float` too. So the type
+changes in that last case, and `tai.to_f` can land one `Float` step from where
+it used to, closer to the true value.
+
+### Drop of `Constants::TAI_TT_OFFSET`
+
+`Astronoby::Constants::TAI_TT_OFFSET` has been removed. The offset between TAI
+and TT is `horologium`'s to hold now, and Astronoby no longer names it.
+
+### `Util::Time.terrestrial_universal_time_delta` replaced by `DeltaT.at`
+
+Delta T (TT - UT1) now has its own namespace instead of living in
+`Astronoby::Util::Time`. The returned value is unchanged.
+
+```rb
+# Before
+Astronoby::Util::Time.terrestrial_universal_time_delta(time)
+
+# After
+Astronoby::DeltaT.at(time)
+```
+
+`Astronoby::Util::Time` keeps `decimal_hour_to_time`.
+
 ## Upgrading from 0.9.0 to 0.10.0
 
 ### Minimum Ruby version bumped to 3.2.0

data/docs/README.md

@@ -108,26 +108,47 @@ calculator = Astronoby::TwilightCalculator.new(
 event = calculator.event_on(Date.new(2025, 5, 1))
 
 event.morning_astronomical_twilight_time
-# => 2025-05-01 02:17:07 UTC
+# => 2025-05-01 02:17:02 UTC
 
 event.morning_nautical_twilight_time
-# => 2025-05-01 03:09:44 UTC
+# => 2025-05-01 03:09:39 UTC
 
 event.morning_civil_twilight_time
-# => 2025-05-01 03:54:38 UTC
+# => 2025-05-01 03:54:36 UTC
 
 event.evening_civil_twilight_time
-# => 2025-05-01 19:41:51 UTC
+# => 2025-05-01 19:41:58 UTC
 
 event.evening_nautical_twilight_time
-# => 2025-05-01 20:26:56 UTC
+# => 2025-05-01 20:27:15 UTC
 
 event.evening_astronomical_twilight_time
-# => 2025-05-01 21:19:57 UTC
+# => 2025-05-01 21:20:32 UTC
 ```
 
 You can learn more about this calculator on the [Twilight times page].
 
+## Find when a body reaches any altitude
+
+```rb
+calculator = Astronoby::AltitudeCrossingCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+
+crossing = calculator.crossings_between(
+  Time.utc(2025, 5, 1),
+  Time.utc(2025, 5, 2),
+  altitude: Astronoby::Angle.from_degrees(30)
+).first
+
+crossing.direction
+# => :rising
+```
+
+You can learn more about this calculator on the [Altitude crossings page].
+
 ## Moon phases
 
 You can either get all the major Moon phases that will happen in a month, or get
@@ -191,7 +212,7 @@ 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]]
 ```
 
 You can learn more about umbral and penumbral magnitudes, phases and contact
@@ -263,7 +284,9 @@ vega_position.apparent.equatorial.right_ascension.str(:hms)
 # => "18h 37m 48.2804s"
 ```
 
-You can learn more about deep-sky objects on the [Deep-sky Bodies page].
+You can learn more about deep-sky objects, and about converting many points to
+horizontal coordinates at once with `HorizontalTransformation`, on the
+[Deep-sky Bodies page].
 
 ## See also
 
@@ -281,6 +304,7 @@ You can learn more about deep-sky objects on the [Deep-sky Bodies page].
 [Coordinates page]: coordinates.md
 [Rise, transit and setting times page]: rise_transit_set_times.md
 [Twilight times page]: twilight_times.md
+[Altitude crossings page]: altitude_crossings.md
 [Moon phases page]: moon_phases.md
 [Lunar observation page]: lunar_observation.md
 [Lunar eclipses page]: lunar_eclipses.md

data/docs/altitude_crossings.md

@@ -0,0 +1,92 @@
+# Altitude crossings
+
+`Astronoby::AltitudeCrossingCalculator` finds when a body reaches any altitude above the observer's horizon, positive or negative, with instants that are not rounded. [Twilight times](twilight_times.md) are built on it.
+
+## Initialization
+
+It takes as key arguments:
+
+- `body`: the body to track, for example `Astronoby::Sun`
+- `observer` (`Astronoby::Observer`): location on Earth of the observer
+- `ephem`: ephemeris to provide the initial raw data
+- `refraction` (optional, `false` by default): whether atmospheric refraction is applied to the altitude, `false` being the twilight convention
+- `reference` (optional, `:center` by default): which point of the body reaches the altitude, `:center`, `:upper_limb` or `:lower_limb`. The limbs use the body's true semi-diameter and need a solar system body.
+
+```rb
+calculator = Astronoby::AltitudeCrossingCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+```
+
+## `#crossings_between`
+
+It returns the `Astronoby::AltitudeCrossing` objects in a time range, sorted by time.
+
+```rb
+crossings = calculator.crossings_between(
+  Time.utc(2026, 10, 23),
+  Time.utc(2026, 10, 24),
+  altitude: Astronoby::Angle.from_degrees(-17.5)
+)
+
+crossing = crossings.first
+
+crossing.instant    # => Astronoby::Instant, unrounded
+crossing.direction  # => :rising or :setting
+crossing.grazing?   # => true when the body only just reaches the altitude
+```
+
+A crossing is `:rising` when the altitude increases through the target. It is `grazing?` when the target is within 0.05° of the body's highest or lowest altitude, where the instant is sensitive to small errors.
+
+## `#multiple_crossings_between`
+
+It does the same for several altitudes at once and returns one array of crossings per altitude, in the order given. The culminations and the computed positions are shared between the altitudes, which makes it much cheaper than one call per altitude.
+
+```rb
+civil, nautical = calculator.multiple_crossings_between(
+  start_time,
+  end_time,
+  altitudes: [Astronoby::Angle.from_degrees(-6), Astronoby::Angle.from_degrees(-12)]
+)
+```
+
+## `#crossing_on`
+
+It returns the first crossing of a given direction on a local day, or `nil`.
+
+```rb
+calculator.crossing_on(
+  Date.new(2026, 10, 23),
+  altitude: Astronoby::Angle.from_degrees(-17.5),
+  direction: :setting,
+  utc_offset: "+02:00"
+)
+```
+
+## `#extremes_between`
+
+It returns the upper and lower culminations in a time range, as `Astronoby::AltitudeExtreme` objects with `#kind`, `#instant` and `#altitude`. They are useful to explain why a crossing is absent: the body never got as high as, or as low as, the target.
+
+```rb
+calculator.extremes_between(start_time, end_time)
+```
+
+## Accuracy
+
+The altitude at the returned instant is within 10⁻⁵° of the target, and crossings agree with independent tools. The Sun's centre, without refraction, was compared on 2026-10-23 in Paris, 2026-03-20 in Makkah and 2026-12-21 at 60° N 10° E and 75° N 10° E, at -6°, -12° and -18° (22 crossings, observer at sea level):
+
+| Tool | Resolution | Largest difference with Astronoby |
+| --- | --- | --- |
+| [IMCCE OPALE](https://opale.imcce.fr) | 1 s | 0.6 s |
+| [JPL Horizons](https://ssd.jpl.nasa.gov/horizons/) | 1 min table, interpolated | 0.10 s |
+| [Skyfield](https://rhodesmills.github.io/skyfield/) on the same DE440s excerpt | 1 ms | 0.19 s |
+| [USNO](https://aa.usno.navy.mil/data/api) | 1 min, civil twilight only | within its rounding |
+
+The Skyfield differences are a time-scale effect rather than a geometric one: they are 0.00 s in March, 0.14 s in October and 0.18 s in December, which is the difference between Skyfield's built-in ΔT prediction and the IERS value Astronoby uses on those days. The remaining differences with Horizons and IMCCE come from the ephemerides (DE441 and INPOP19A against DE440s). The comparison also includes the polar night at 75° N, where the Sun does not rise but reaches -12° and -18°, and where the Sun never reaches -6°, as every tool agrees.
+
+## See also
+
+- [Twilight Times](twilight_times.md)
+- [Rise, Transit and Set Times](rise_transit_set_times.md) 

data/docs/configuration.md

@@ -26,6 +26,14 @@ with default precision values:
 - [Moon phases]
 - Nutation
 - Precession
+- Greenwich mean and apparent sidereal times, which also cover the local
+  apparent sidereal time
+
+Sidereal times are cached for the exact UTC time, with no rounding. The cache
+helps when the same instant is used many times, for example when converting
+many points to horizontal coordinates for one observer. Calling
+`DeepSkyObject#at(instant).observed_by(observer).horizontal` repeatedly at one
+instant is about 2.5 times faster with the cache enabled.
 
 ## Cache precision
 

data/docs/deep_sky_bodies.md

@@ -96,6 +96,51 @@ event.rising_time
 # => 2025-10-01 01:31:25 UTC
 ```
 
+## Many points at once
+
+Getting the horizontal coordinates of a single object goes through the whole
+chain of reference frames. Doing so for thousands of points at the same instant
+for the same observer, like the stars of a catalogue for a sky chart, repeats
+the same work for each of them: the rotation from the ICRS to the true equator
+and equinox of date, and the sidereal time only depend on the observer and the
+instant.
+
+`Astronoby::HorizontalTransformation` computes them once, and then converts
+any equatorial coordinates at J2000 epoch into horizontal coordinates. It is
+about 70 times faster per point than going through
+`DeepSkyObject#at(instant).observed_by(observer).horizontal`.
+
+```rb
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(51.5072),
+  longitude: Astronoby::Angle.from_degrees(-0.1276)
+)
+instant = Astronoby::Instant.from_time(Time.utc(2025, 10, 1, 3))
+
+sirius = Astronoby::Coordinates::Equatorial.new(
+  right_ascension: Astronoby::Angle.from_hms(6, 45, 8.917),
+  declination: Astronoby::Angle.from_dms(-16, 42, 58.02)
+)
+
+transformation = Astronoby::HorizontalTransformation.new(
+  observer: observer,
+  instant: instant
+)
+horizontal = transformation.apply(sirius)
+
+horizontal.altitude.str(:dms, precision: 0)
+# => "+10° 36′ 27″"
+horizontal.azimuth.str(:dms, precision: 0)
+# => "+134° 56′ 25″"
+```
+
+The result is the same as the one of a `DeepSkyObject` without an ephemeris,
+which means the points are treated as fixed directions: there is no aberration,
+no proper motion and no parallax. Atmospheric refraction is not applied by
+default, and can be requested with `transformation.apply(sirius, refraction:
+true)`. The coordinates must be at J2000 epoch, otherwise an
+`Astronoby::IncompatibleArgumentsError` is raised.
+
 [ephemerides]: ephem.md
 [reference frames]: reference_frames.md
 [SIMBAD Astronomical Database]: https://simbad.u-strasbg.fr/simbad/

data/docs/glossary.md

@@ -238,6 +238,8 @@ The primary time standard used worldwide. All astronomical calculations in Astro
 
 - **Julian Day**: Continuous day count since 4713 BCE
 - **Terrestrial Time (TT)**: Astronomical time scale used for calculations
+- **International Atomic Time (TAI)**: The atomic time scale TT is defined against, 32.184 seconds behind it
+- **Barycentric Dynamical Time (TDB)**: Time at the Solar System barycentre, within about 1.7 milliseconds of TT
 - **UTC**: Coordinated Universal Time, the standard for civil time
 
 ## See also

data/docs/instant.md

@@ -25,7 +25,10 @@ International Astronomical Union, as a [Julian Date].
 From this instant in <abbr title="Terrestrial Time">TT</abbr>, other time
 standards can be expressed, such as the
 <abbr title="International Atomic Time">TAI</abbr> or the
-<abbr title="Barycentric Dynamic Time">TDB</abbr>.
+<abbr title="Barycentric Dynamical Time">TDB</abbr>. Those two are computed by
+the [horologium] gem, which owns the time scales that convert by definition or
+by model. UT1 is not one of them: it follows the actual rotation of the Earth,
+so it stays in Astronoby, backed by [IERS data](iers.md).
 
 ## Initialization
 
@@ -93,7 +96,7 @@ instant.gmst
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.tai.to_f
-# => 2460795.9996275003
+# => 2460795.9996275
 ```
 
 - UTC offset (difference with UTC in days)
@@ -105,17 +108,20 @@ instant.utc_offset.to_f
 # => 0.0008003974106626159
 ```
 
-- Barycentric Dynamic Time
+- Barycentric Dynamical Time
 
 ```rb
-# This is not handled for now, and returns TT
-
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
-instant.tdb
-# => 2460796
+instant.tdb.to_f
+# => 2460796.000000017
 ```
 
+`tai` and `tdb` are read as a `Rational`. A Julian Date is around 2.46
+million, so a single `Float` rounds to about 47 microseconds of the day, which
+is more than the whole TDB - TT correction. Call `to_f` when a `Float` is what
+you want.
+
 ## Value Equality
 
 As a value object, it is possible to compare different instants.
@@ -131,6 +137,7 @@ instant1 < instant2
 # => true
 ```
 
+[horologium]: https://github.com/rhannequin/horologium
 [Gregorian calendar]: https://en.wikipedia.org/wiki/Gregorian_calendar
 [Terrestrial Time]: https://en.wikipedia.org/wiki/Terrestrial_Time
 [Julian Date]: https://en.wikipedia.org/wiki/Julian_day