astronoby 0.8.0 → 0.10.0

data/docs/instant.md

@@ -14,7 +14,9 @@ from the irregularities in the rotation of Earth and the irregularly fluctuating
 mean solar time.
 
 Astronoby handles this situation by implementing an `Astronoby::Instant` class,
-used in most calculations instead of `Time`.
+used in most calculations instead of `Time`. Converting between UTC and
+Terrestrial Time requires knowing [Delta T (TT - UT1)][Delta T], which
+Astronoby obtains from [IERS data](iers.md).
 
 `Astronoby::Instant` is a value object that stores an instant in time on Earth
 in [Terrestrial Time], an astronomical time standard defined by the
@@ -28,9 +30,10 @@ standards can be expressed, such as the
 ## Initialization
 
 An `Astronoby::Instant` object can be instantiated from:
-* Terrestrial time (`Numeric`): `.from_terrestrial_time`
-* Ruby `Time` object: `.from_time`
-* UTC Julian date (`Numeric`): `.from_utc_julian_date`
+
+- Terrestrial time (`Numeric`): `.from_terrestrial_time`
+- Ruby `Time` object: `.from_time`
+- UTC Julian date (`Numeric`): `.from_utc_julian_date`
 
 ```rb
 Astronoby::Instant.from_terrestrial_time(2460796)
@@ -48,7 +51,7 @@ Astronoby::Instant.from_utc_julian_date(2460796)
 
 From the same instant, it is possible to extract different time standards.
 
-* Gregorian `Date`
+- Gregorian `Date`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
@@ -57,34 +60,34 @@ instant.to_date
 # => #<Date: 2025-04-30 ((2460796j,0s,0n),+0s,2299161j)>
 ```
 
-* UTC `DateTime`
+- UTC `DateTime`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => #<DateTime: 2025-04-30T11:58:51+00:00 ((2460796j,43131s,12159n),+0s,2299161j)>
+# => #<DateTime: 2025-04-30T11:58:50+00:00 ((2460796j,43130s,845637619n),+0s,2299161j)>
 ```
 
-* UTC `Time`
+- UTC `Time`
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.to_datetime
-# => 2025-04-30 11:58:51.000012159 UTC
+# => 2025-04-30T11:58:50+00:00 UTC
 ```
 
-* Greenwich Sidereal Time
+- Greenwich Sidereal Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.gmst
-# => 2.5597425440141457
+# => 2.5597070126923764
 ```
 
-* International Atomic Time
+- International Atomic Time
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
@@ -93,16 +96,16 @@ instant.tai.to_f
 # => 2460795.9996275003
 ```
 
-* UTC offset (difference with UTC in days)
+- UTC offset (difference with UTC in days)
 
 ```rb
 instant = Astronoby::Instant.from_terrestrial_time(2460796)
 
 instant.utc_offset.to_f
-# => 0.0007986109703819444
+# => 0.0008003974106626159
 ```
 
-* Barycentric Dynamic Time
+- Barycentric Dynamic Time
 
 ```rb
 # This is not handled for now, and returns TT
@@ -131,9 +134,11 @@ instant1 < instant2
 [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
+[Delta T]: https://en.wikipedia.org/wiki/ΔT_(timekeeping)
 
 ## See also
+
 - [Ephemerides](ephem.md) - for time-based calculations
-- [Celestial Bodies](celestial_bodies.md) - for object positions
+- [Solar System Bodies](solar_system_bodies.md) - for object positions
 - [Reference Frames](reference_frames.md) - for coordinate systems
 - [Configuration](configuration.md) - for performance settings

data/docs/lunar_eclipses.md

@@ -0,0 +1,93 @@
+# 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.
+
+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.
+
+## Finding eclipses
+
+`Astronoby::Moon.eclipse_events` takes an ephemeris and a time range, and returns the lunar eclipses whose greatest instant falls in that range, sorted by time.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+eclipses = Astronoby::Moon.eclipse_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+)
+
+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]]
+```
+
+## 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.
+
+```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
+```
+
+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.
+
+```rb
+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`.
+
+```rb
+eclipse.gamma                       # => 0.348
+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`.
+
+```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.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)
+```
+
+For a penumbral eclipse, `#partial` and `#total` are `nil`. For a partial eclipse, `#total` is `nil`.
+
+```rb
+penumbral_eclipse = Astronoby::Moon.eclipse_events(
+  ephem: ephem,
+  start_time: Time.utc(2024, 3, 1),
+  end_time: Time.utc(2024, 4, 1)
+).first
+
+penumbral_eclipse.kind    # => :penumbral
+penumbral_eclipse.partial # => nil
+penumbral_eclipse.total   # => nil
+```
+
+## 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.
+
+## See also
+
+- [Moon Phases](moon_phases.md) - for lunar phases
+- [Lunar Observation](lunar_observation.md) - for libration, axis and limb angles
+- [Planetary Phenomena](planetary_phenomena.md) - for conjunctions, oppositions and elongations
+- [Solar System Bodies](solar_system_bodies.md) - for moon object details
+- [Ephemerides](ephem.md) - for data sources
+
+[NASA's Five Millennium Canon of Lunar Eclipses]: https://eclipse.gsfc.nasa.gov/SEpubs/5MCLE.html
+[IMCCE]: https://www.imcce.fr/

data/docs/lunar_observation.md

@@ -0,0 +1,87 @@
+# Lunar Observation
+
+Beyond phases and apsides, Astronoby exposes the quantities lunar observers rely on to describe the Moon's appearance and orientation in the sky: its libration, the position angle of its rotation axis, the position angle of its bright limb, and the parallactic angle. By default they follow Jean Meeus, *Astronomical Algorithms*, 2nd edition, and are derived from the Moon's and the Sun's apparent positions, which Astronoby already computes from the ephemeris. The libration and the position angle of the axis can additionally use the integrated lunar orientation from a JPL DE kernel to reach arcsecond accuracy, as described below.
+
+All of these are available directly on a `Astronoby::Moon` instance.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+instant = Astronoby::Instant.from_time(Time.utc(2025, 3, 1))
+moon = Astronoby::Moon.new(instant: instant, ephem: ephem)
+```
+
+## Libration
+
+Libration is the apparent oscillation that lets an observer on Earth see slightly more than half of the lunar surface over time. `Astronoby::Moon#libration` returns a `Astronoby::Libration` value object holding the total (optical plus physical) libration in longitude and latitude, both as `Astronoby::Angle` objects. A positive longitude exposes more of the Moon's eastern limb (Mare Crisium side); a positive latitude exposes more of its northern limb.
+
+```rb
+libration = moon.libration
+
+libration.longitude.str(:dms) # => "-2° 5′ 4.4219″"
+libration.latitude.str(:dms)  # => "+0° 28′ 45.9616″"
+```
+
+By default this is the analytic optical plus physical libration from Meeus's series. Compared with the lunar orientation integrated in the JPL DE solution (as reported by JPL Horizons), the libration in longitude and the position angle of the axis agree to within a few arcseconds, while the libration in latitude agrees to about 0.02 degrees. That residual is the well known difference between the mean lunar equator used by the classical Meeus method and the DE mean-Earth frame. It is eliminated by loading an orientation kernel.
+
+## Arcsecond accuracy with an orientation kernel
+
+For the libration and the position angle of the axis, you can reach the accuracy of JPL Horizons, Skyfield and IMCCE by also loading a binary PCK lunar orientation kernel, such as `moon_pa_de440_200625.bpc`, which carries the integrated DE440 orientation of the Moon. Load it once with `Astronoby::Orientation` and pass it to the Moon alongside the ephemeris.
+
+```rb
+ephem = Astronoby::Ephem.load("de440.bsp")
+orientation = Astronoby::Orientation.load("moon_pa_de440_200625.bpc")
+
+moon = Astronoby::Moon.new(instant: instant, ephem: ephem, orientation: orientation)
+
+moon.libration.latitude.str(:dms)     # => "+0° 27′ 27.7258″"
+moon.position_angle_of_axis.str(:dms) # => "-21° 48′ 32.9625″"
+```
+
+The libration is then computed as the selenographic longitude and latitude of the sub-Earth point in the Moon's mean-Earth body-fixed frame, and matches JPL Horizons to better than an arcsecond. Without an orientation kernel the Moon keeps using the analytic method, so this is an opt-in refinement, not a requirement. The `bright_limb_position_angle` and `parallactic_angle` are unaffected and do not need a kernel.
+
+If you do not already have the kernel, Astronoby can download it for you.
+
+```rb
+Astronoby::Orientation.download(
+  name: "moon_pa_de440_200625.bpc",
+  target: "moon_pa_de440_200625.bpc"
+)
+```
+
+## Position angle of the axis
+
+`Astronoby::Moon#position_angle_of_axis` returns the position angle of the Moon's axis of rotation, the angle of the projection of the lunar north pole, measured eastward from the north point of the disk. It is returned as an `Astronoby::Angle`.
+
+```rb
+moon.position_angle_of_axis.str(:dms) # => "-21° 48′ 46.657″"
+```
+
+## Position angle of the bright limb
+
+`Astronoby::Moon#bright_limb_position_angle` returns the position angle of the midpoint of the illuminated limb, measured eastward from the north point of the disk, between 0 and 360 degrees. It is a geocentric quantity computed from the apparent equatorial coordinates of the Moon and the Sun, and it points towards the Sun, since the bright limb is the limb facing the Sun.
+
+```rb
+moon.bright_limb_position_angle.str(:dms) # => "+248° 1′ 57.9467″"
+```
+
+## Parallactic angle
+
+The parallactic angle is the angle at the Moon between the direction of the north celestial pole and the direction of the observer's zenith. Unlike the previous quantities it depends on the observer, so it is computed from the topocentric place, where lunar parallax is significant. `Astronoby::Moon#parallactic_angle` takes an observer and returns an `Astronoby::Angle`.
+
+```rb
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.8566),
+  longitude: Astronoby::Angle.from_degrees(2.3522)
+)
+
+moon.parallactic_angle(observer: observer).str(:dms) # => "+11° 42′ 47.1246″"
+```
+
+## See also
+
+- [Solar System Bodies](solar_system_bodies.md) - for the Moon's other properties
+- [Moon Phases](moon_phases.md) - for lunar phase events
+- [Lunar Eclipses](lunar_eclipses.md) - for eclipses of the Moon
+- [Observer](observer.md) - for setting up observation locations
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Angles](angles.md) - for working with angular measurements

data/docs/moon_phases.md

@@ -69,11 +69,14 @@ phases.each { puts "#{_1.phase}: #{_1.time}" }
 # new_moon: 2024-05-08 03:21:56 UTC
 # first_quarter: 2024-05-15 11:48:02 UTC
 # full_moon: 2024-05-23 13:53:12 UTC
-# last_quarter: 2024-05-30 17:12:43 UTC
+# last_quarter: 2024-05-30 17:12:42 UTC
 ```
 
 ## See also
+
 - [Twilight Times](twilight_times.md) - for sun-related events
 - [Rise, Transit and Set Times](rise_transit_set_times.md) - for moon events
-- [Celestial Bodies](celestial_bodies.md) - for moon object details
+- [Lunar Observation](lunar_observation.md) - for libration, axis and limb angles
+- [Lunar Eclipses](lunar_eclipses.md) - for eclipses of the Moon
+- [Solar System Bodies](solar_system_bodies.md) - for moon object details
 - [Ephemerides](ephem.md) - for data sources

data/docs/observer.md

@@ -6,19 +6,31 @@ events computed by Astronoby are location and date based.
 ## Initialization
 
 The two required key arguments to instantiate an observer are:
-* `latitude` (`Astronoby::Angle`): the angle from the equator to the observer,
+
+- `latitude` (`Astronoby::Angle`): the angle from the equator to the observer,
   from 90° to -90°, with positive angles for the Northern Hemisphere.
-* `longitude` (`Astronoby::Angle`): the angle from the Greenwich meridian to the
+- `longitude` (`Astronoby::Angle`): the angle from the Greenwich meridian to the
   observer, from 180° to -180°, with positive angles eastward of the Greenwich
   meridian.
 
-Latitude and longitude are defined according to the [World Geodetic System].
-In other words, they are the same as those used for the [GPS].
+Latitude and longitude are defined according to the [World Geodetic System]
+(WGS-84). In other words, they are the same as those used for the [GPS].
+
+Internally, the observer's geodetic coordinates are converted to geocentric
+Cartesian coordinates in the **International Terrestrial Reference System
+(ITRS)**, also known as Earth-Centered Earth-Fixed (ECEF). These are then
+rotated into the celestial frame using Earth rotation (GAST) via
+`Astronoby::EarthRotation` and IERS polar motion corrections. See
+[Reference Frames](reference_frames.md) for details.
+
+The reverse conversion (ECEF → geodetic) is available via
+[`Astronoby::Coordinates::Geodetic.from_ecef`][Coordinates page].
 
 It is also possible to give the following optional key arguments:
-* `elevation` (`Astronoby::Distance`): the distance above or below the average
+
+- `elevation` (`Astronoby::Distance`): the distance above or below the average
   sea level
-* `utc_offset`: local time difference with UTC. Check the [timezone specifiers]
+- `utc_offset`: local time difference with UTC. Check the [timezone specifiers]
   for the format.
 
 ```rb
@@ -57,9 +69,11 @@ observer1 == observer2
 [GPS]: https://en.wikipedia.org/wiki/GPS
 [timezone specifiers]: https://ruby-doc.org/3.4.1/Time.html#class-Time-label-Timezone+Specifiers
 [Angles page]: angles.md
+[Coordinates page]: coordinates.md#geodetic
 
 ## See also
+
 - [Angles](angles.md) - for working with latitude and longitude
 - [Coordinates](coordinates.md) - for understanding position systems
 - [Reference Frames](reference_frames.md) - for topocentric calculations
-- [Celestial Bodies](celestial_bodies.md) - for observing objects
+- [Solar System Bodies](solar_system_bodies.md) - for observing objects

data/docs/planetary_phenomena.md

@@ -0,0 +1,78 @@
+# Planetary Phenomena
+
+Astronoby computes the classic planetary phenomena relative to the Sun: conjunctions, oppositions, and greatest elongations. They are all defined in the apparent geocentric ecliptic frame of date.
+
+The available phenomena depend on the planet. Inferior planets (Mercury and Venus) have conjunctions and greatest elongations. Superior planets (Mars to Neptune) have conjunctions and oppositions. Requesting a phenomenon that cannot occur for a given body raises an `Astronoby::UnsupportedEventError`.
+
+Each method takes an ephemeris and a time range, and returns the events found within that range.
+
+## Oppositions
+
+An opposition is the instant when a superior planet and the Sun have opposite apparent ecliptic longitudes (a difference of 180 degrees), so the planet is opposite the Sun in the sky.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+opposition = Astronoby::Mars.opposition_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+opposition.instant.to_time # => 2025-01-16 02:38:35 UTC
+opposition.body            # => Astronoby::Mars
+```
+
+## Conjunctions
+
+A conjunction is the instant when a planet and the Sun share the same apparent ecliptic longitude. Each conjunction is classified as inferior (the planet passes between the Earth and the Sun) or superior (the planet passes behind the Sun), determined from the apparent distances. Superior planets only ever have superior conjunctions.
+
+```rb
+conjunction = Astronoby::Venus.conjunction_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+conjunction.instant.to_time # => 2025-03-23 01:07:30 UTC
+conjunction.inferior?       # => true
+conjunction.superior?       # => false
+```
+
+## Greatest elongations
+
+A greatest elongation is the instant when an inferior planet reaches its maximum apparent angular separation from the Sun. It is eastern when the planet is east of the Sun (visible in the evening sky) and western when it is west of the Sun (visible in the morning sky).
+
+```rb
+elongation = Astronoby::Mercury.greatest_elongation_events(
+  ephem: ephem,
+  start_time: Time.utc(2025, 1, 1),
+  end_time: Time.utc(2026, 1, 1)
+).first
+
+elongation.instant.to_time   # => 2025-03-08 06:09:18 UTC
+elongation.angle.degrees     # => 18.25
+elongation.eastern?          # => true
+elongation.western?          # => false
+```
+
+## Elongation of a body
+
+The elongation of any Solar System body, the apparent Sun-Earth-body angle, is also available directly on a body instance, along with the side of the Sun it lies on.
+
+```rb
+instant = Astronoby::Instant.from_time(Time.utc(2025, 7, 14))
+venus = Astronoby::Venus.new(instant: instant, ephem: ephem)
+
+venus.elongation.degrees # => 41.47
+venus.eastern?           # => false
+venus.western?           # => true
+```
+
+## See also
+
+- [Solar System Bodies](solar_system_bodies.md) - for planets and their properties
+- [Equinoxes and Solstices Times](equinoxes_solstices_times.md) - for solar events
+- [Moon Phases](moon_phases.md) - for lunar events
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Ephemerides](ephem.md) - for data sources