astronoby 0.6.0 → 0.8.0

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

data/docs/twilight_times.md

@@ -0,0 +1,123 @@
+# Twilight times
+
+In astronomy, twilight is a period of time when the Sun is already set but
+some of its light still illuminates the atmosphere, making the sky brighter than
+during full night.
+
+We usually define 4 moments when talking about twilight:
+* sunrise/sunset: right when the Sun goes above the horizon or right after it
+  goes below the horizon. The Sun's horizon angle is 0°.
+* civil twilight: when the horizon angle is between 0° and -6°. Usually, during
+  this time, artificial light is not needed yet.
+* nautical twilight: when the horizon angle is between -6° and -12°. When the
+  nautical twilight starts, the difference between the horizon at sea and the
+  sky cannot be seen clearly anymore.
+* astronomical twilight: when the horizon angle is between -12° and -18°. Some
+  stars can be seen during this time.
+
+These moments change every day and depend on the observer's location. They can
+be computed using `Astronoby::TwilightCalculator`.
+
+## Initialization
+
+Once instantiated, the calculator doesn't do anything yet, it waits for your
+instruction.
+
+It takes as key arguments:
+* `observer` (`Astronoby::Observer`): location on Earth of the observer
+* `ephem`: ephemeris to provide the initial raw data
+
+You can learn more about ephemerides on the [Ephem page].
+
+```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::TwilightCalculator.new(
+  observer: observer,
+  ephem: ephem
+)
+```
+
+You can learn more about observers on the [Observer page].
+
+## `events_between`
+
+This is the main method of the calculator. It provides all the twilight times
+that will happen between two dates.
+
+It returns a `Astronoby::TwilightEvents` object which exposes the 6 following
+instance methods:
+* `#morning_astronomical_twilight_times`: when the rising Sun reaches 18° below
+  the horizon
+* `#morning_nautical_twilight_times`: when the rising Sun reaches 12° below the
+  horizon
+* `#morning_civil_twilight_times`: when the rising Sun reaches 6° below the
+  horizon
+* `#evening_civil_twilight_times`: when the setting Sun reaches 6° below the
+  horizon
+* `#evening_nautical_twilight_times`: when the setting Sun reaches 12° below the
+  horizon
+* `#evening_astronomical_twilight_times`: when the setting Sun reaches 18° below
+  the horizon
+
+```rb
+events = calculator.events_between(
+  Time.utc(2025, 8, 1),
+  Time.utc(2025, 8, 8)
+)
+
+events.morning_civil_twilight_times
+# =>
+# [2025-08-01 02:29:17 UTC,
+#  2025-08-02 02:30:21 UTC,
+#  2025-08-03 02:31:26 UTC,
+#  2025-08-04 02:32:30 UTC,
+#  2025-08-05 02:33:35 UTC,
+#  2025-08-06 02:34:40 UTC,
+#  2025-08-07 02:35:45 UTC]
+```
+
+## `#event_on`
+
+The calculator exposes the instance method `#event_on` to compute the twilight
+times for a given `date` (`Date`) parameter.
+
+It returns a `Astronoby::TwilightEvent` object which exposes the 6 following
+instance methods: `#morning_astronomical_twilight_time`,
+`#morning_nautical_twilight_time`, `#morning_civil_twilight_time`,
+`#evening_civil_twilight_time`, `#evening_nautical_twilight_time` and
+`#evening_astronomical_twilight_time`.
+
+```rb
+event = calculator.event_on(Date.new(2025, 5, 1))
+
+event.morning_astronomical_twilight_time
+# => 2025-05-01 01:17:18 UTC
+
+event.morning_nautical_twilight_time
+# => 2025-05-01 01:56:48 UTC
+
+event.evening_civil_twilight_time
+# => 2025-05-01 17:29:41 UTC
+
+event.evening_nautical_twilight_time
+# => 2025-05-01 18:06:08 UTC
+
+event.evening_astronomical_twilight_time
+# => 2025-05-01 18:45:38 UTC
+```
+
+[Ephem page]: ephem.md
+[Observer page]: observer.md
+
+## See also
+- [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
+- [Moon Phases](moon_phases.md) - for lunar events

data/lib/astronoby/aberration.rb

@@ -1,47 +1,72 @@
 # frozen_string_literal: true
 
 module Astronoby
+  # Applies relativistic aberration corrections to an astrometric position based
+  # on observer velocity.
   class Aberration
-    MAXIMUM_SHIFT = Angle.from_degrees(20.5)
+    # Source:
+    #  Title: Explanatory Supplement to the Astronomical Almanac
+    #  Authors: Sean E. Urban and P. Kenneth Seidelmann
+    #  Edition: University Science Books
+    #  Chapter: 7.2.3 - Aberration
 
-    def self.for_ecliptic_coordinates(coordinates:, epoch:)
-      new(coordinates, epoch).apply
-    end
+    LIGHT_SPEED = Astronoby::Velocity.light_speed.mps
 
-    def initialize(coordinates, epoch)
-      @coordinates = coordinates
-      @epoch = epoch
+    # Initializes the aberration correction with position and observer velocity.
+    #
+    # @param astrometric_position [Astronoby::Vector<Astronoby::Distance>] The
+    #   astrometric position vector.
+    # @param observer_velocity [Astronoby::Vector<Astronoby::Velocity>] The
+    #   velocity vector of the observer.
+    def initialize(astrometric_position:, observer_velocity:)
+      @position = astrometric_position
+      @velocity = observer_velocity
+      @distance_meters = @position.norm.m
+      @observer_speed = @velocity.norm.mps
     end
 
-    # Source:
-    #  Title: Practical Astronomy with your Calculator or Spreadsheet
-    #  Authors: Peter Duffett-Smith and Jonathan Zwart
-    #  Edition: Cambridge University Press
-    #  Chapter: 36 - Aberration
-    def apply
-      delta_longitude = Angle.from_degrees(
-        -MAXIMUM_SHIFT.degrees * (
-          sun_longitude - @coordinates.longitude
-        ).cos / @coordinates.latitude.cos / Constants::SECONDS_PER_DEGREE
-      )
+    # Computes the aberration-corrected position.
+    #
+    # @return [Astronoby::Vector<Astronoby::Distance>] The corrected position
+    #   vector.
+    def corrected_position
+      beta = @observer_speed / LIGHT_SPEED
+      projected_velocity = beta * aberration_angle_cos
+      lorentz_factor_inv = lorentz_factor_inverse(beta)
 
-      delta_latitude = Angle.from_degrees(
-        -MAXIMUM_SHIFT.degrees *
-        (sun_longitude - @coordinates.longitude).sin *
-        @coordinates.latitude.sin / Constants::SECONDS_PER_DEGREE
-      )
+      velocity_correction =
+        velocity_correction_factor(projected_velocity) * velocity_mps
+      normalization_factor = 1.0 + projected_velocity
+      position_scaled = position_meters * lorentz_factor_inv
 
-      Coordinates::Ecliptic.new(
-        latitude: @coordinates.latitude + delta_latitude,
-        longitude: @coordinates.longitude + delta_longitude
+      Distance.vector_from_meters(
+        (position_scaled + velocity_correction) / normalization_factor
       )
     end
 
-    def sun_longitude
-      @_sun_longitude ||= Sun
-        .new(time: Epoch.to_utc(@epoch))
-        .true_ecliptic_coordinates
-        .longitude
+    private
+
+    def aberration_angle_cos
+      denominator = [@distance_meters * @observer_speed, 1e-20].max
+      Util::Maths.dot_product(position_meters, velocity_mps) / denominator
+    end
+
+    def position_meters
+      @position.map(&:meters)
+    end
+
+    def velocity_mps
+      @velocity.map(&:mps)
+    end
+
+    def lorentz_factor_inverse(beta)
+      Math.sqrt(1.0 - beta**2)
+    end
+
+    def velocity_correction_factor(projected_velocity)
+      lorentz_inv = lorentz_factor_inverse(projected_velocity)
+      (1.0 + projected_velocity / (1.0 + lorentz_inv)) *
+        (@distance_meters / LIGHT_SPEED)
     end
   end
 end