astronoby 0.7.0 → 0.8.0

data/docs/glossary.md

@@ -0,0 +1,152 @@
+# Glossary
+
+This glossary defines key astronomical and technical terms used throughout the Astronoby documentation.
+
+## Astronomical Terms
+
+### **Aberration**
+The apparent displacement of a celestial object due to the finite speed of light and the motion of the observer. In Astronoby, this is automatically corrected in apparent reference frames.
+
+### **Altitude**
+The angular distance of a celestial object above the observer's local horizon, measured in degrees from 0° (horizon) to 90° (zenith).
+
+### **Apparent Position**
+The position of a celestial object as it appears in the sky, corrected for light-time, aberration, and other effects. This is what you actually see when looking through a telescope.
+
+### **Arc Second**
+A unit of angular measurement equal to 1/3600th of a degree. Often used to describe the precision of astronomical calculations.
+
+### **Azimuth**
+The angular distance around the horizon from north, measured clockwise in degrees. North is 0°, east is 90°, south is 180°, and west is 270°.
+
+### **Barycentre**
+The centre of mass of a system of bodies. In the Solar System, this is the point around which all planets orbit, which is usually close to but not exactly at the Sun's centre.
+
+### **Celestial Equator**
+The projection of Earth's equator onto the celestial sphere. It's the reference plane for equatorial coordinates.
+
+### **Celestial Sphere**
+An imaginary sphere surrounding Earth, on which all celestial objects appear to be located. Used as a reference system for astronomical coordinates.
+
+### **Constellation**
+A region of the sky containing a group of stars that form a recognizable pattern. Astronoby can determine which constellation a celestial body appears to be in.
+
+### **Declination**
+The angular distance north or south of the celestial equator, measured in degrees. Positive values are north, negative values are south.
+
+### **Ecliptic**
+The apparent path of the Sun across the celestial sphere throughout the year. It's the plane of Earth's orbit around the Sun.
+
+### **Ephemeris**
+A table or file containing the calculated positions of celestial objects at specific times. Astronoby uses ephemeris files from JPL and IMCCE for high-precision calculations.
+
+### **Equinox**
+The two times each year when the Sun crosses the celestial equator, making day and night approximately equal in length. The March (vernal) and September (autumnal) equinoxes.
+
+### **Geocentric**
+As seen from the centre of Earth. Geocentric coordinates are useful for calculations but don't account for an observer's specific location.
+
+### **Horizon**
+The apparent boundary between Earth and sky as seen by an observer. The local horizon depends on the observer's location and elevation.
+
+### **Illuminated Fraction**
+The portion of a celestial body's disk that appears illuminated as seen from Earth. For the Moon, this varies from 0 (new moon) to 1 (full moon).
+
+### **Julian Date**
+A continuous count of days since January 1, 4713 BCE. Used in astronomy for precise time measurements and calculations.
+
+### **Light-Time Correction**
+The adjustment made to account for the time it takes light to travel from a celestial object to Earth. Important for accurate position calculations.
+
+### **Magnitude**
+A measure of a celestial object's brightness. Lower numbers indicate brighter objects (e.g., -4 is brighter than +2). Apparent magnitude is as seen from Earth, absolute magnitude is intrinsic brightness.
+
+### **Meridian**
+An imaginary line passing through the observer's zenith and the north and south celestial poles. Objects transit (cross) the meridian when they reach their highest point in the sky.
+
+### **Nutation**
+Small periodic variations in the orientation of Earth's rotation axis, caused by gravitational forces from the Sun and Moon.
+
+### **Obliquity**
+The angle between Earth's equatorial plane and the ecliptic plane. Currently about 23.4° and slowly decreasing.
+
+### **Parallax**
+The apparent shift in position of a nearby object when viewed from different locations. Important for calculating distances to nearby stars.
+
+### **Phase Angle**
+The angle between the Sun, a celestial object, and Earth. For planets, this determines how much of the disk is illuminated.
+
+### **Precession**
+The slow, continuous change in the orientation of Earth's rotation axis, causing the positions of the equinoxes to shift over time.
+
+### **Refraction**
+The bending of light as it passes through Earth's atmosphere, causing celestial objects to appear slightly higher in the sky than they actually are.
+
+### **Right Ascension**
+The angular distance eastward along the celestial equator from the vernal equinox, measured in hours (0-24h) or degrees (0-360°).
+
+### **Solstice**
+The two times each year when the Sun reaches its northernmost (June) or southernmost (December) position relative to the celestial equator.
+
+### **Topocentric**
+As seen from a specific location on Earth's surface. Topocentric positions account for the observer's latitude, longitude, and elevation.
+
+### **Transit**
+The moment when a celestial object crosses the observer's meridian, reaching its highest point in the sky for that day.
+
+### **Twilight**
+The period before sunrise and after sunset when the sky is partially illuminated by scattered sunlight. Civil, nautical, and astronomical twilight have different definitions based on the Sun's position below the horizon.
+
+### **Zenith**
+The point directly above an observer on Earth, at an altitude of 90°.
+
+## Technical Terms
+
+### **API (Application Programming Interface)**
+The set of methods and classes that programmers use to interact with the Astronoby library.
+
+### **Cache**
+A temporary storage system that stores frequently used calculation results to improve performance.
+
+### **Coordinate System**
+A system for specifying the position of objects in space. Astronoby supports equatorial, ecliptic, and horizontal coordinate systems.
+
+### **Ephemeris File**
+A binary file (usually with .bsp extension) containing orbital data for Solar System bodies. These files are produced by JPL and IMCCE.
+
+### **Floating-Point Precision**
+The accuracy of decimal number calculations. Higher precision values in Astronoby provide more accurate results but may be slower.
+
+### **Reference Frame**
+A coordinate system used to specify positions. Astronoby provides geometric, astrometric, mean of date, apparent, and topocentric reference frames.
+
+### **SPICE**
+A NASA toolkit for computing positions and orientations of Solar System bodies. Astronoby uses SPICE binary kernels (.bsp files) for ephemeris data.
+
+### **UTC (Coordinated Universal Time)**
+The primary time standard used worldwide. All astronomical calculations in Astronoby are based on UTC.
+
+## Units and Measurements
+
+### **Angular Units**
+- **Degree (°)**: 1/360th of a circle
+- **Arc Minute (′)**: 1/60th of a degree
+- **Arc Second (″)**: 1/60th of an arc minute
+- **Hour (h)**: 15 degrees (used for right ascension)
+- **Radian**: 180/π degrees (≈57.3°)
+
+### **Distance Units**
+- **Astronomical Unit (AU)**: The average distance between Earth and Sun (≈149.6 million km)
+- **Kilometre (km)**: Standard metric unit for distances
+- **Metre (m)**: Standard metric unit for elevations
+
+### **Time Units**
+- **Julian Day**: Continuous day count since 4713 BCE
+- **Terrestrial Time (TT)**: Astronomical time scale used for calculations
+- **UTC**: Coordinated Universal Time, the standard for civil time
+
+## See also
+- [Quick Start Guide](README.md) - for getting started
+- [Coordinates](coordinates.md) - for coordinate systems
+- [Reference Frames](reference_frames.md) - for position calculations
+- [Angles](angles.md) - for angular measurements

data/docs/instant.md

@@ -0,0 +1,139 @@
+# `Instant`
+
+Time in astronomy is usually a slightly different concept than in everyday
+life. Today, the vast majority of people use the [Gregorian calendar] and a time
+based on <abbr title="Coordinated Universal Time">UTC</abbr>. This timescale is
+convenient for matching what we experience on Earth, but it is not static, it
+includes leap days, leap seconds.
+
+Also, most of us live in areas where the local legal time is not UTC, so we
+have to deal with time zones that are arbitrary and constantly changing.
+
+Astronomical calculations need a stable, uniform and linear time scale, free
+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`.
+
+`Astronoby::Instant` is a value object that stores an instant in time on Earth
+in [Terrestrial Time], an astronomical time standard defined by the
+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>.
+
+## 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`
+
+```rb
+Astronoby::Instant.from_terrestrial_time(2460796)
+# => Represents UTC time 2025-04-30 11:58:51
+
+Astronoby::Instant.from_time(Time.utc(2025, 5, 1))
+# => Represents terrestrial time Julian Date 2460796.500798611
+
+Astronoby::Instant.from_utc_julian_date(2460796)
+# => Represents UTC time 2025-04-30 12:00:00
+# => Represents terrestrial time Julian Date 2460796.000798611
+```
+
+## Time standards
+
+From the same instant, it is possible to extract different time standards.
+
+* Gregorian `Date`
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.to_date
+# => #<Date: 2025-04-30 ((2460796j,0s,0n),+0s,2299161j)>
+```
+
+* 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)>
+```
+
+* UTC `Time`
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.to_datetime
+# => 2025-04-30 11:58:51.000012159 UTC
+```
+
+* Greenwich Sidereal Time
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.gmst
+# => 2.5597425440141457
+```
+
+* International Atomic Time
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.tai.to_f
+# => 2460795.9996275003
+```
+
+* UTC offset (difference with UTC in days)
+
+```rb
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.utc_offset.to_f
+# => 0.0007986109703819444
+```
+
+* Barycentric Dynamic Time
+
+```rb
+# This is not handled for now, and returns TT
+
+instant = Astronoby::Instant.from_terrestrial_time(2460796)
+
+instant.tdb
+# => 2460796
+```
+
+## Value Equality
+
+As a value object, it is possible to compare different instants.
+
+```rb
+instant1 = Astronoby::Instant.from_terrestrial_time(2460796)
+instant2 = Astronoby::Instant.from_terrestrial_time(2460797)
+
+instant1.diff(instant2)
+# => -1
+
+instant1 < instant2
+# => true
+```
+
+[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
+
+## See also
+- [Ephemerides](ephem.md) - for time-based calculations
+- [Celestial Bodies](celestial_bodies.md) - for object positions
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Configuration](configuration.md) - for performance settings

data/docs/moon_phases.md

@@ -0,0 +1,79 @@
+# Moon Phases
+
+Astronoby lets you compute the current Moon phase, or when the major ones
+happen.
+
+## Current Moon phase
+
+`Astronoby::Moon` provides two pieces of information about the current Moon phase: the
+illuminated fraction and the phase fraction.
+
+### `#illuminated_fraction`
+
+As mentioned in the name, this method provides the illuminated fraction of the
+Moon. It will not give precise information about the "age" of the Moon as the
+same illumination happens twice in the same lunar month.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(2025, 5, 1)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+
+moon.illuminated_fraction.round(2)
+# => 0.15
+# 15% of the Moon is illuminated as seen from Earth
+```
+
+### `#current_phase_fraction`
+
+This method is more convenient for a user interested in how far we are into the
+lunar month as it returns a fraction from 0 to 1 between two new Moons.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+time = Time.utc(2025, 5, 1)
+instant = Astronoby::Instant.from_time(time)
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+
+moon.current_phase_fraction.round(2)
+# => 0.11
+
+time = Time.utc(2025, 5, 15)
+instant = Astronoby::Instant.from_time(time)
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+
+moon.current_phase_fraction.round(2)
+# => 0.59
+```
+
+## Major Moon phases in the month
+
+If you are interested to know when the major Moon phases will happen during a
+civil month, you can use `Astronoby::Events::MoonPhases` and its class method
+`::phases_for` with the key arguments `year` and `month`, both `Integer`.
+
+It returns an array of `Astronoby::MoonPhase` objects, which each expose a
+`phase` (`Symbol`) and a `time` (`Time`).
+
+Please note that because a lunar month is around 29 days, some months will have
+the same phase twice.
+
+```rb
+phases = Astronoby::Events::MoonPhases.phases_for(year: 2024, month: 5)
+
+phases.each { puts "#{_1.phase}: #{_1.time}" }
+# last_quarter: 2024-05-01 11:27:15 UTC
+# 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
+```
+
+## 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
+- [Ephemerides](ephem.md) - for data sources

data/docs/observer.md

@@ -0,0 +1,65 @@
+# Observer
+
+`Astronoby::Observer` is the representation of an observer on Earth. Most of the
+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,
+  from 90° to -90°, with positive angles for the Northern Hemisphere.
+* `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].
+
+It is also possible to give the following optional key arguments:
+* `elevation` (`Astronoby::Distance`): the distance above or below the average
+  sea level
+* `utc_offset`: local time difference with UTC. Check the [timezone specifiers]
+  for the format.
+
+```rb
+# Location: Alhambra, Spain
+
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(37.176),
+  longitude: Astronoby::Angle.from_degrees(-3.588),
+  elevation: Astronoby::Distance.from_meters(792)
+)
+```
+
+You can learn more about angles on the [Angles page].
+
+## Value equality
+
+`Astronoby::Observer` is a value object, which means it implements value
+equality.
+
+```rb
+observer1 = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(90),
+  longitude: Astronoby::Angle.from_degrees(180)
+)
+
+observer2 = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_hours(6),
+  longitude: Astronoby::Angle.from_hours(12)
+)
+
+observer1 == observer2
+# => true
+```
+
+[World Geodetic System]: https://en.wikipedia.org/wiki/World_Geodetic_System
+[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
+
+## 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

data/docs/reference_frames.md

@@ -0,0 +1,138 @@
+# Reference Frames
+
+A given body at a given time can be perceived at different positions, depending
+on the reference frame and the corrections applied.
+
+Astronoby provides five reference frames for each celestial body:
+
+* Geometric
+* Astrometric
+* Mean of date
+* Apparent
+* Topocentric
+
+All reference frames provide this common interface:
+
+* `#position`: Vector of position as x,y,z `Astronoby::Distance` objects
+* `#velocity`: Vector of velocity as x,y,z `Astronoby::Velocity` objects
+* `#distance`: Distance from the centre (`Astronoby::Distance`)
+* `#equatorial`: Equatorial coordinates (`Astronoby::Coordinates::Equatorial`)
+* `#ecliptic`: Ecliptic coordinates (`Astronoby::Coordinates::Ecliptic`)
+
+## Geometric
+
+Also called "mean J2000", this reference frame is related to the mean ecliptic
+or terrestrial equator and the mean equinox of the reference date (J2000). It is
+the strict position computed from the ephemeris file in a reference frame
+centered on the Solar System barycentre, with no corrections applied.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+geometric = moon.geometric
+# => #<Astronoby::Geometric:0x000000011e7ffd40
+
+geometric.distance.au
+# => 1.0095091198501744
+
+geometric.equatorial.right_ascension.str(:hms, precision: 0)
+# => "20h 13m 52s"
+```
+
+## Astrometric
+
+Also called "astrometric J2000", this reference frame is related to the ecliptic
+or the mean terrestrial equator and the mean equinox of the reference date
+(J2000). It applies light-time correction between the celestial body and the
+observer. The frame is centred on the Earth's centre, as are all the following
+reference frames.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+astrometric = moon.astrometric
+
+astrometric.distance.km.round
+# => 371187
+
+astrometric.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 54m 27s"
+```
+
+## Mean of date
+
+This reference frame is related to the ecliptic or the mean equator and the mean
+equinox of the date. It provides the geometric position corrected for the
+precessional motion of the Earth's rotation axis (precession and nutation).
+
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+mean_of_date = moon.mean_of_date
+
+mean_of_date.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 52m 29s"
+```
+
+## Apparent
+
+This reference frame is related to the true ecliptic or equator and the true
+equinox of the date. It is the actual position in the sky of a celestial object
+as seen from the centre of the Earth. It applies several corrections to the
+astrometric position:the deflection of light, the aberration, the precession and
+the nutation.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+apparent = moon.apparent
+
+apparent.equatorial.right_ascension.str(:hms, precision: 0)
+# => "1h 52m 28s"
+```
+
+## Topocentric
+
+This reference frame is the final transformation of a position. It provides the
+apparent position of a celestial body as seen from a location on Earth. It can
+only be produced given an observer (`Astronoby::Observer`). It provides another
+set of coordinates: horizontal (`Astronoby::Coordinates::Horizontal`).
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.838),
+  longitude: Astronoby::Angle.from_degrees(2.4843)
+)
+
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+topocentric = moon.observed_by(observer)
+
+topocentric.horizontal.azimuth.str(:dms, precision: 0)
+# => "+90° 14′ 19″"
+```
+
+You can learn more about observers on the [Observer page].
+
+## See also
+- [Coordinates](coordinates.md) - for understanding coordinate systems
+- [Observer](observer.md) - for location setup
+- [Celestial Bodies](celestial_bodies.md) - for object positions
+- [Ephemerides](ephem.md) - for data sources
+
+[Observer page]: observer.md

data/docs/rise_transit_set_times.md

@@ -0,0 +1,119 @@
+# Rise, Transit and Set Times
+
+Astronoby provides a calculator to compute all the rise, transit and set times
+that will happen for a celestial body as observed from Earth during a period
+of time: `Astronoby::RiseTransitSetCalculator`.
+
+## Initialization
+
+Once instantiated, the calculator doesn't do anything yet, it waits for your
+instruction.
+
+It takes as key arguments:
+* `body` (`Astronoby::SolarSystemBody`): any supported celestial body,
+  e.g. `Astronoby::Sun`
+* `observer` (`Astronoby::Observer`): location on Earth of the observer
+* `ephem`: ephemeris to provide the initial raw data
+
+You can learn more about [celestial bodies] and [ephemerides].
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(41.0082),
+  longitude: Astronoby::Angle.from_degrees(28.9784),
+  elevation: Astronoby::Distance.from_meters(40)
+)
+
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: Astronoby::Saturn,
+  observer: observer,
+  ephem: ephem
+)
+```
+
+You can learn more about observers on the
+[Observer page](https://github.com/rhannequin/astronoby/wiki/Observer).
+
+## `#events_between`
+
+This is the main method of the calculator. It provides all the rising, transit
+and setting times that will happen between two dates. It returns a
+`Astronoby::RiseTransitSetEvents` object which exposes the methods
+`#rising_times`, `#transit_times` and `#setting_times`.
+
+```rb
+events = calculator.events_between(
+  Time.utc(2025, 5, 1),
+  Time.utc(2025, 5, 3)
+)
+
+events.rising_times
+# => [2025-05-01 01:28:48 UTC, 2025-05-02 01:25:07 UTC]
+
+events.transit_times
+# => [2025-05-01 07:21:34 UTC, 2025-05-02 07:18:01 UTC]
+
+events.setting_times
+# => [2025-05-01 13:14:24 UTC, 2025-05-02 13:10:59 UTC]
+```
+
+## `#events_on`
+
+You can call `#events_on` to compute the event times that will happen during a
+civil day. You can provide a UTC offset to specify the boundaries of the civil
+day for your location.
+
+This method also returns a `Astronoby::RiseTransitSetEvents` object because some
+celestial bodies could occasionally have the same event happen multiple times in
+a single day. This is the case for the Moon, for example, which can seem to rise
+twice in the same civil day because of its quick motion around the Earth.
+
+```rb
+events = calculator.events_on(Date.new(2025, 5, 1))
+
+events.rising_times
+# => [2025-05-01 01:28:48 UTC]
+
+events.transit_times
+# => [2025-05-01 07:21:34 UTC]
+
+events.setting_times
+# => [2025-05-01 13:14:24 UTC]
+```
+
+## `#event_on`
+
+For convenience, `Astronoby::RiseTransitSetCalculator` also exposes a
+`#event_on` method that behaves the same way as `#events_on` but returns the
+first time of rising, transit and setting for the civil date, as these events
+only happen once in most cases. It returns a `Astronoby::RiseTransitSetEvent`
+which exposes the instance methods `#rising_time`, `#transit_time` and
+`#setting_time`.
+
+```rb
+utc_offset = "+03:00"
+event = calculator.event_on(
+  Date.new(2025, 5, 1),
+  utc_offset: utc_offset
+)
+
+event.rising_time.localtime(utc_offset)
+# => 2025-05-01 04:28:48 +0300
+
+event.transit_time.localtime(utc_offset)
+# => 2025-05-01 10:21:34 +0300
+
+event.setting_time.localtime(utc_offset)
+# => 2025-05-01 16:14:24 +0300
+```
+
+[celestial bodies]: celestial_bodies.md
+[ephemerides]: ephem.md
+
+## See also
+- [Twilight Times](twilight_times.md) - for sun-related events
+- [Celestial Bodies](celestial_bodies.md) - for object information
+- [Observer](observer.md) - for location setup
+- [Ephemerides](ephem.md) - for data sources