astronoby 0.6.0 → 0.8.0

data/UPGRADING.md

@@ -7,6 +7,273 @@ 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.7.0 to 0.8.0
+
+### Benchmark directory changed
+
+The precision benchmark has been moved to `benchmarks`.
+
+### `Epoch` refactored into `JulianDate`
+
+The `Epoch` class has been removed and replaced by `JulianDate`. This change is
+meant to clarify the purpose of the class, which is to represent a Julian date
+and not an epoch.
+
+* Method `#to_utc` has been dropped in favor as is was ambiguous regarding the
+  timescale used.
+* Therefore, constant `JULIAN_DAY_NUMBER_OFFSET` has also been dropped.
+* `MeanObliquity::for_epoch` was renamed to `::at` and now takes an `instant` as
+  parameter
+* `MeanObliquity::obliquity_of_reference_in_milliarcseconds` was renamed to
+  `::obliquity_of_reference_in_arcseconds`
+* `TrueObliquity::for_epoch` was renamed to to `::at` and now takes an
+  `instant` as parameter
+* `Coordinates::Equatorial#to_ecliptic` method now takes an `instant` as
+  parameter
+
+### `#angular_diameter` moved from topocentric position to body
+
+Previously accessible from the topocentric reference frame, the angular diameter
+of a Solar System body is now accessible from the body itself.
+
+## Upgrading from 0.6.0 to 0.7.0
+
+### Signature change for `Sun` and `Moon`
+
+Both classes are now initialized with the key arguments `ephem` and `instant`.
+`ephem` comes from `Ephem.load` which provides the raw geometric data for Solar
+System bodies. `instant` is an instance of `Instant`, the new concept for
+representing an instant in time.
+
+```rb
+Astronoby::Ephem.download(name: "de421.bsp", target: "tmp/de421.bsp")
+ephem = Astronoby::Ephem.load("tmp/de421.bsp")
+
+time = Time.utc(2025, 6, 19, 12, 0, 0)
+instant = Astronoby::Instant.from_time(time)
+
+sun = Astronoby::Sun.new(instant: instant, ephem: ephem)
+```
+
+Learn more on [ephem].
+
+[ephem]: https://github.com/rhannequin/astronoby/wiki/Ephem
+
+### Drop of methods for `Sun`
+
+`Sun` doesn't expose the following class and instance methods anymore:
+* `::equation_of_time` (replaced with `#equation_of_time`)
+* `#epoch` (replaced with `#instant`)
+* `#true_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#apparent_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#horizontal_coordinates` (replaced with `#horizontal` on the Topocentric reference frame)
+* `#observation_events`
+* `#twilight_events`
+* `#earth_distance` (replaced with `#distance` on referential frames)
+* `#angular_size` (replaced with `#angular_diameter` on referential frames)
+* `#true_anomaly`
+* `#mean_anomaly`
+* `#longitude_at_perigee`
+* `#orbital_eccentricity`
+
+Learn more on [reference frames].
+
+[reference frames]: https://github.com/rhannequin/astronoby/wiki/Reference-Frames
+
+### Drop of instance methods for `Moon`
+
+`Moon` doesn't expose the following nstance methods anymore:
+* `#apparent_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
+* `#apparent_equatorial_coordinates` (replaced with `#equatorial` on reference frames)
+* `#horizontal_coordinates` (replaced with the Apparent and Topocentric reference frames)
+* `#distance` (replaced with `#distance` on referential frames)
+* `#mean_longitude`
+* `#mean_elongation`
+* `#mean_anomaly`
+* `#argument_of_latitude`
+* `#phase_angle`
+* `#observation_events`
+
+### Signature change for `Aberration`
+
+`Aberration` is now initialized with the key arguments `astrometric_position`
+and `observer_velocity`. `astrometric_position` is a position vector
+(`Astronoby::Vector<Astronoby::Distance>`) available from any referential frame
+with the `#position` method.`observer_velocity` is a velocity vector
+(`Astronoby::Vector<Astronoby::Distance>`) available from any referential frame
+with the `#velocity` method.
+
+`observer_velocity` is meant to be a geometric velocity, while
+`astrometric_position` is meant to be an astrometric position.
+
+```rb
+time = Time.utc(2025, 4, 1)
+instant = Astronoby::Instant.from_time(time)
+ephem = Astronoby::Ephem.load("de421.bsp")
+earth = Astronoby::Earth.new(instant: instant, ephem: ephem)
+mars = Astronoby::Mars.new(instant: instant, ephem: ephem)
+earth_geometric_velocity = earth.geometric.velocity
+mars_astrometric_position = mars.astrometric.position
+
+aberration = Astronoby::Aberration.new(
+  astrometric_position: mars_astrometric_position,
+  observer_velocity: earth_geometric_velocity
+)
+```
+
+### Signature change for `Angle#to_dms` and `Angle#to_hms`
+
+`Angle#to_dms` and `Angle#to_hms` don't have arguments anymore. The angle value
+is now taken from the object itself. This was a misbehavior in the previous
+implementation.
+
+```rb
+angle = Astronoby::Angle.from_degrees(45.0)
+dms = angle.to_dms
+
+dms.format
+# => "+45° 0′ 0.0″"
+```
+
+### Signature change for `EquinoxSolstice`
+
+`EquinoxSolstice.new` now takes an additional argument expected to be an ephem
+(`Astronoby::Ephem`).
+
+### Signature change for `Nutation`
+
+The expected `epoch` (`Astronoby::Epoch`) argument has been replaced by an
+`instant` (`Astronoby::Instant`) key argument.
+
+### Drop of `Nutation::for_ecliptic_longitude` and `Nutation::for_obliquity_of_the_ecliptic`
+
+`Nutation::for_ecliptic_longitude` and `Nutation::for_obliquity_of_the_ecliptic`
+methods have been removed. The `Nutation` class now exposes the
+`#nutation_in_longitude` and `#nutation_in_obliquity` instance methods which 
+both return an angle (`Astronoby::Angle`).
+
+### Signature change for `Precession`
+
+The expected `coordinates` and `epoch` (`Astronoby::Epoch`) key arguments have
+been replaced by an `instant` (`Astronoby::Instant`) key argument.
+
+### Drop of `Precession#for_equatorial_coordinates` and `Precession#precess`
+
+`Precession#for_equatorial_coordinates` and `Precession#precess` methods have
+been refactoed into class methods.
+
+### Drop of `Coordinates::Horizontal#to_equatorial`
+
+`Coordinates::Horizontal#to_equatorial` has been removed as equatorial
+coordinates are now available from the reference frames.
+
+### Drop of instance methods for `Coordinates::Ecliptic`
+
+`Coordinates::Ecliptic#to_true_equatorial` and
+`Coordinates::Ecliptic#to_apparent_equatorial` have been removed as
+equatorial coordinates are now available from the reference frames.
+
+### Drop of `Coordinates::Equatorial#to_epoch`
+
+`Coordinates::Equatorial#to_epoch` has been removed.
+
+### Drop of `Events::ObservationEvents`
+
+`Events::ObservationEvents` has been removed. The rising, transit and setting 
+times can now be calculated using `RiseTransitSetCalculator`.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48),
+  longitude: Astronoby::Angle.from_degrees(2)
+)
+date = Date.new(2025, 4, 24)
+
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: Astronoby::Sun,
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(date)
+
+event.rising_time
+# => 2025-04-24 04:45:42 UTC
+
+event.transit_time
+# => 2025-04-24 11:50:04 UTC
+
+event.setting_time
+# => 2025-04-24 18:55:24 UTC
+```
+
+### Drop of `RiseTransitSetIteration`
+
+`RiseTransitSetIteration` has been removed as it was only used by
+`Events::ObservationEvents`.
+
+### Drop of `Events::TwilightEvents`
+
+`Events::TwilightEvents` has been removed. The twilight times can now be
+calculated using `TwilightCalculator`.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48),
+  longitude: Astronoby::Angle.from_degrees(2)
+)
+date = Date.new(2025, 4, 24)
+
+calculator = Astronoby::TwilightCalculator.new(
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(date)
+# Returns a Astronoby::TwilightEvent object
+
+event.morning_astronomical_twilight_time
+# => 2025-04-24 02:43:38 UTC
+
+event.morning_nautical_twilight_time
+# => 2025-04-24 03:30:45 UTC
+
+event.morning_civil_twilight_time
+# => 2025-04-24 04:12:38 UTC
+
+event.evening_civil_twilight_time
+# => 2025-04-24 19:27:34 UTC
+
+event.evening_nautical_twilight_time
+# => 2025-04-24 20:09:27 UTC
+
+event.evening_astronomical_twilight_time
+# => 2025-04-24 20:56:34 UTC
+```
+
+### Drop of `EphemerideLunaireParisienne`
+
+`EphemerideLunaireParisienne` has been removed.
+
+### Drop of `Util::Astrodynamics`
+
+`Util::Astrodynamics` has been removed.
+
+### Drop of `Util::Maths.interpolate` and `Util::Maths.normalize_angles_for_interpolation`
+
+`Util::Maths.interpolate` and `Util::Maths.normalize_angles_for_interpolation`
+have been removed.
+
+### Drop of `Constants::SECONDS_PER_DEGREE`
+
+`Constants::SECONDS_PER_DEGREE` has been removed.
+
+## Upgrading from 0.5.0 to 0.6.0
+
+No breaking changes.
+
 ## Upgrading from 0.4.0 to 0.5.0
 
 ### `Sun#horizontal_coordinates` method signature changed ([#69])

data/docs/README.md

@@ -0,0 +1,196 @@
+# Quick Start
+
+## Download an ephemeris
+
+You only need to run this once, it will download and store an ephemeris on your
+file system.
+
+```rb
+Ephem::IO::Download.call(name: "de421.bsp", target: "tmp/de421.bsp")
+```
+
+Ephemerides can be large files, but Astronoby provides a tool to drastically
+reduce the size to your needs. You can learn more about ephemerides on the
+[Ephem page].
+
+## Load an ephemeris
+
+```rb
+ephem = Astronoby::Ephem.load("tmp/de421.bsp")
+```
+
+## Define a time and create an `Instant` object from it
+
+```rb
+time = Time.utc(2025, 6, 19, 12, 0, 0)
+instant = Astronoby::Instant.from_time(time)
+```
+
+You can learn more about time scales on the [Instant page].
+
+## Instantiate a Solar System body object
+
+```rb
+jupiter = Astronoby::Jupiter.new(instant: instant, ephem: ephem)
+```
+
+You can learn more about planets and bodies on the [Celestial Bodies page].
+
+## Define an observer from geographic coordinates
+
+```rb
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.83661378408946),
+  longitude: Astronoby::Angle.from_degrees(2.3366748126024466),
+  elevation: Astronoby::Distance.from_meters(65)
+)
+```
+
+You can learn more about angles on the [Angles page], and about observers on the
+[Observer page].
+
+## Compute the topocentric position of the body as seen from the observer
+
+```rb
+topocentric = jupiter.observed_by(observer)
+```
+
+You can learn more about reference frames and positions on the
+[Reference Frames page].
+
+## Get the horizontal coordinates from the position
+
+```rb
+topocentric.horizontal.azimuth.str(:dms)
+# => "+175° 34′ 28.2724″"
+
+topocentric.horizontal.altitude.str(:dms)
+# => "+64° 22′ 58.1084″"
+```
+
+You can learn more about coordinates on the [Coordinates page].
+
+## Get the rising, transit and setting times between two times
+
+```rb
+calculator = Astronoby::RiseTransitSetCalculator.new(
+  body: Astronoby::Jupiter,
+  observer: observer,
+  ephem: ephem
+)
+
+events = calculator.events_between(
+  Time.utc(2025, 5, 1),
+  Time.utc(2025, 5, 3),
+)
+
+events.rising_times
+# => [2025-05-01 06:35:35 UTC, 2025-05-02 06:32:26 UTC]
+
+events.transit_times
+# => [2025-05-01 14:34:34 UTC, 2025-05-02 14:31:31 UTC]
+
+events.setting_times
+# => [2025-05-01 22:33:37 UTC, 2025-05-02 22:30:39 UTC]
+```
+
+You can learn more about this calculator on the
+[Rise, transit and setting times page].
+
+## Get the twilight times of the day
+
+```rb
+calculator = Astronoby::TwilightCalculator.new(
+  observer: observer,
+  ephem: ephem
+)
+
+event = calculator.event_on(Date.new(2025, 5, 1))
+
+event.morning_astronomical_twilight_time
+# => 2025-05-01 02:17:28 UTC
+
+event.morning_nautical_twilight_time
+# => 2025-05-01 03:10:17 UTC
+
+event.morning_civil_twilight_time
+# => 2025-05-01 03:55:17 UTC
+
+event.evening_civil_twilight_time
+# => 2025-05-01 19:40:12 UTC
+
+event.evening_nautical_twilight_time
+# => 2025-05-01 20:25:12 UTC
+
+event.evening_astronomical_twilight_time
+# => 2025-05-01 21:18:01 UTC
+```
+
+You can learn more about this calculator on the [Twilight times page].
+
+## Moon phases
+
+You can either get all the major Moon phases that will happen in a month, or get
+information about the current Moon phase.
+
+```rb
+may_2024_phases = Astronoby::Events::MoonPhases.phases_for(year: 2024, month: 5)
+
+may_2024_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
+```
+
+```rb
+time = Time.utc(2025, 5, 15)
+instant = Astronoby::Instant.from_time(time)
+moon = Astronoby::Moon.new(ephem: ephem, instant: instant)
+
+moon.illuminated_fraction.round(2)
+# => 0.15
+
+moon.current_phase_fraction.round(2)
+# => 0.11
+```
+
+You can learn more about phases on the [Moon phases page].
+
+## Equinox and solstice times
+
+```rb
+
+Astronoby::EquinoxSolstice.march_equinox(2025, ephem)
+# => 2025-03-20 09:01:29 UTC
+
+Astronoby::EquinoxSolstice.june_solstice(2025, ephem)
+# => 2025-06-21 02:42:19 UTC
+
+Astronoby::EquinoxSolstice.september_equinox(2025, ephem)
+# => 2025-09-22 18:19:22 UTC
+
+Astronoby::EquinoxSolstice.december_solstice(2025, ephem)
+# => 2025-12-21 15:03:03 UTC
+```
+
+You can learn more about equinoxes and solstices on the
+[Equinoxes and solstices times page].
+
+## See also
+- [Glossary](glossary.md) - for astronomical and technical terms
+- [Configuration](configuration.md) - for performance tuning
+- [Performance Benchmarks](../benchmarks/README.md) - for testing improvements
+
+[Ephem page]: ephem.md
+[Instant page]: instant.md
+[Celestial Bodies page]: celestial_bodies.md
+[Observer page]: observer.md
+[Reference Frames page]: reference_frames.md
+[Angles page]: angles.md
+[Coordinates page]: coordinates.md
+[Rise, transit and setting times page]: rise_transit_set_times.md
+[Twilight times page]: twilight_times.md
+[Moon phases page]: moon_phases.md
+[Equinoxes and solstices times page]: equinoxes_solstices_times.md

data/docs/angles.md

@@ -0,0 +1,137 @@
+# Angles
+
+`Astronoby::Angle` is one of the most important object in the library. An object
+on the celestial sphere is described with angles, an observer's location on
+Earth is described with angles, the distance between two points in the sky is
+described with an angle.
+
+## Create an angle
+
+You can create an instance of `Astronoby::Angle` with a value in different
+units: radians, degrees or hours.
+
+```rb
+Astronoby::Angle.from_radians(Math::PI)
+Astronoby::Angle.from_degrees(180)
+Astronoby::Angle.from_hours(12)
+```
+
+You can also use the hour-minute-second (HMS) or degree-minute-second (DMS)
+formats.
+
+```rb
+Astronoby::Angle.from_hms(22, 45, 23)
+Astronoby::Angle.from_dms(340, 45, 23)
+```
+
+Alternatively, you can create an angle of 0 (regardless of the unit).
+
+```rb
+Astronoby::Angle.zero
+```
+
+Finally, you can create an angle from the ratio of a trigonometric function.
+
+```rb
+Astronoby::Angle.acos(0)
+Astronoby::Angle.asin(-1)
+Astronoby::Angle.atan(1 / Math.sqrt(3))
+```
+
+## Convert between units
+
+Once an angle object is instantiated, its value lives inside it. You need to
+specify a unit to extract it.
+
+```rb
+angle = Astronoby::Angle.from_degrees(180)
+
+angle.degrees # => 180.0
+angle.radians # => 3.141592653589793
+angle.hours   # => 12.0
+```
+
+## Format an angle
+
+You can format an angle in HMS or DMS formatted strings.
+
+```rb
+angle = Astronoby::Angle.from_degrees(155.76479)
+
+angle.str(:dms) # => "+155° 45′ 53.2439″"
+angle.str(:hms) # => "10h 23m 3.5496s"
+```
+
+Alternatively you can extract these numbers without having to format them into a
+string.
+
+```rb
+angle = Astronoby::Angle.from_degrees(155.76479)
+
+dms = angle.to_dms
+dms.sign    # => "+"
+dms.degrees # => 155
+dms.minutes # => 45
+dms.seconds # => 53.2439
+
+hms = angle.to_hms
+hms.hours   # => 10
+hms.minutes # => 23
+hms.seconds # => 3.5496
+```
+
+## Manipulate angles
+
+You can compare an angle with another angle.
+
+```rb
+Astronoby::Angle.from_hours(12) == Astronoby::Angle.from_degrees(180)
+# => true
+
+angle1 = Astronoby::Angle.from_degrees(90)
+angle2 = Astronoby::Angle.from_hours(12)
+
+angle1 < angle2 # => true
+```
+
+## Math with angles
+
+Trigonometric functions can be applied to angles to get the value as a `Float`.
+Please be aware some results won't be strictly exact because of the limited
+precision of floating-point numbers and the limited amount of digits
+of `Math::PI`.
+
+```rb
+angle = Astronoby::Angle.from_degrees(180)
+
+angle.cos # => -1.0
+angle.sin # => 1.2246467991473532e-16, strictly supposed to be 0
+angle.tan # => -1.2246467991473532e-16, strictly supposed to be 0
+```
+
+You can add up or subtract angles into a new one. Multiplication and division
+are not supported as they mathematically should return something else than an
+angle.
+
+```rb
+angle1 = Astronoby::Angle.from_hours(12)
+angle2 = Astronoby::Angle.from_degrees(90)
+
+angle3 = angle1 + angle2
+angle3.degrees   # => 270.0
+
+angle4 = angle1 - angle2
+angle4.degrees   # => 90.0
+
+angle5 = -angle1
+angle5.degrees   # => -180.0
+
+angle1.positive? # => true
+angle1.negative? # => false
+```
+
+## See also
+- [Coordinates](coordinates.md) - for using angles in coordinate systems
+- [Observer](observer.md) - for latitude and longitude
+- [Reference Frames](reference_frames.md) - for position calculations
+- [Celestial Bodies](celestial_bodies.md) - for object positions

data/docs/celestial_bodies.md

@@ -0,0 +1,107 @@
+# Celestial Bodies
+
+Currently, Astronoby only supports the following major bodies of the Solar
+System:
+* the Sun (`Astronoby::Sun`)
+* planets from Mercury to Neptune, including the Earth (`Astronoby::Earth`, ...)
+* the Moon (`Astronoby::Moon`)
+
+Given an ephemeris (`Astronoby::Ephem`) and an instant object
+(`Astronoby::Instant`), these classes enable you to get instances which provide
+positions in different reference frames.
+
+You can learn more about [ephemerides] and [reference frames].
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(2021, 7, 8)
+instant = Astronoby::Instant.from_time(time)
+
+venus = Astronoby::Venus.new(ephem: ephem, instant: instant)
+apparent_position = venus.apparent.position
+
+apparent_position.x.km.round
+# => -148794622
+```
+
+Each of these bodies also provides its own equatorial radius
+(`Astronoby::Distance`).
+
+```rb
+Astronoby::Venus::EQUATORIAL_RADIUS.meters
+# => 6051800
+```
+
+## Attributes of planets
+
+For all Solar System bodies, except the Sun and the Earth, the following
+attributes are available. Note that dynamic values are accessible through
+instance methods, while absolute values are accessible through class methods.
+
+### `#angular_diameter`
+
+Size of the body in the sky. Returns a `Astronoby::Angle` object.
+
+```rb
+venus.angular_diameter.str(:dms)
+# => "+0° 0′ 11.4587″"
+```
+
+### `#constellation`
+
+Constellation where the body appears in the sky as seen from Earth. Returns
+a `Astronoby::Constellation` object.
+
+```rb
+venus.constellation.name
+# => "Cancer"
+
+venus.constellation.abbreviation
+# => "Cnc"
+```
+
+### `#phase_angle`
+
+"Sun-object-Earth" angle. Returns a `Astronoby::Angle` object.
+
+```rb
+venus.phase_angle.degrees.round
+# => 40
+```
+
+### `#illuminated_fraction`
+
+Fraction of the object's disk illuminated as seen from Earth. Returns a `Float`
+between `0` and `1`.
+
+```rb
+venus.illuminated_fraction.round(2)
+# => 0.88
+```
+
+### `#apparent_magnitude`
+
+Apparent brightness of the body. Returns a `Float`.
+
+```rb
+venus.apparent_magnitude.round(2)
+# => -3.89
+```
+
+### `::absolute_magnitude`
+
+Absolute brightness of the body. Returns a `Float`.
+
+```rb
+Astronoby::Venus.absolute_magnitude
+# => -4.384
+```
+
+[ephemerides]: ephem.md
+[reference frames]: reference_frames.md
+
+## See also
+- [Ephemerides](ephem.md) - for understanding data sources
+- [Reference Frames](reference_frames.md) - for coordinate systems
+- [Observer](observer.md) - for setting up observation locations
+- [Angles](angles.md) - for working with angular measurements