astronoby 0.7.0 → 0.9.0

data/docs/README.md

@@ -0,0 +1,224 @@
+# 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 [Solar System 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].
+
+## Deep-sky objects
+
+It is possible to manipulate any deep-sky possible, given equatorial coordinates
+from a catalogue at J2000 epoch.
+
+```rb
+time = Time.utc(2025, 10, 1)
+instant = Astronoby::Instant.from_time(time)
+
+vega_j2000 = Astronoby::Coordinates::Equatorial.new(
+  right_ascension: Astronoby::Angle.from_hms(18, 36, 56.33635),
+  declination: Astronoby::Angle.from_dms(38, 47, 1.2802),
+  epoch: Astronoby::JulianDate::J2000
+)
+
+# Build the body for star Vega
+vega = Astronoby::DeepSkyObject.new(equatorial_coordinates: vega_j2000)
+
+# Build the position of star Vega for a given instant
+vega_position = vega.at(instant)
+
+vega_position.apparent.equatorial.right_ascension.str(:hms)
+# => "18h 36m 56.3363s"
+```
+
+You can learn more about deep-sky objects on the [Deep-sky Bodies 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
+[Solar System Bodies page]: solar_system_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
+[Deep-sky Bodies page]: deep_sky_bodies.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
+- [Solar System Bodies](solar_system_bodies.md) - for object positions

data/docs/configuration.md

@@ -0,0 +1,98 @@
+# Configuration
+
+Astronoby handles an internal configuration to enable users to tweak the
+performance and precision of computed data.
+
+## Cache
+
+Some calculations are expensive but also repetitive in the intermediate computed
+data. To improve performance, an internal cache system has been developed.
+
+➡️ **Please note caching is disabled by default.**
+
+### Enable caching
+
+You can turn caching on with the following command:
+
+```rb
+Astronoby.configuration.cache_enabled = true
+```
+
+Once caching is enabled, it will be used for the following parts of the library
+with default precision values:
+* [Geometric positions]
+* [Topocentric positions] when computing rising/transit/setting times
+* [Moon phases]
+* Nutation
+* Precession
+
+## Cache precision
+
+When cache is enabled, some data is cached following a default precision
+threshold so that precision doesn't noticeably decrease.
+
+However, users may want to improve performance even more at the cost of some
+precision.
+
+It is possible to change the precision value for the following:
+* Geometric position, default: `9`
+* Topocentric position, default: `5`
+* Nutation, default: `2`
+* Precession, default: `2`
+
+### Precision value
+
+The precision value is how much rounded instants are. Because instants are
+stored as a [Julian Day], rounding may not seem very natural.
+
+Let's take the example of `1`. Rounding a Julian Day with only one digit means
+that all times within 8640 seconds will be rounded to the same instant, which
+means a maximum rounding of 2.4 hours.
+
+* `1`: 2.4 hours
+* `2`: 14.4 minutes
+* `3`: 86.4 seconds
+* `4`: 8.6 seconds
+* `5`: 0.86 seconds
+* `6`: 0.086 seconds
+* `7`: 0.0086 seconds
+* ...
+
+### Setting custom precision
+
+To set up your own precision, you can use:
+
+```rb
+Astronoby.cache_precision(:geometric, 5)
+```
+
+All geometric positions of the same celestial body within 0.86 seconds will be
+rounded and cached.
+
+## Cache size
+
+Cache has limited and configurable capacity, set by default to 10,000 stored
+items. This value can be changed to any positive number.
+
+```rb
+Astronoby.configuration.cache_enabled = true
+
+Astronoby.cache.max_size
+# => 10000
+
+Astronoby.cache.max_size = 1000000
+
+Astronoby.cache.max_size
+# => 1000000
+```
+
+[Geometric positions]: reference_frames.md#geometric
+[Topocentric positions]: reference_frames.md#topocentric
+[Moon phases]: moon_phases.md
+[Julian Day]: https://en.wikipedia.org/wiki/Julian_day
+
+## See also
+- [Reference Frames](reference_frames.md) - for understanding position calculations
+- [Ephemerides](ephem.md) - for data sources
+- [Performance Benchmarks](benchmarks/README.md) - for testing improvements
+- [Cache System](cache.md) - for detailed caching information

data/docs/coordinates.md

@@ -0,0 +1,167 @@
+# Coordinates
+
+Astronoby provides three different types of coordinates:
+
+* Equatorial
+* Ecliptic
+* Horizontal
+
+Equatorial and ecliptic coordinates are available for each [reference frame],
+while horizontal coordinates are only available for a topocentric position.
+
+## Equatorial
+
+In Astronoby, equatorial coordinates are geocentric spherical coordinates. As
+per [Wikipedia]'s definition:
+
+> defined by an origin at the centre of Earth, fundamental plane consisting of
+> the projection of Earth's equator onto the celestial sphere (forming the
+> celestial equator, a primary direction towards the March equinox, and a
+> right-handed convention.
+
+They have two main angular attributes:
+
+### Right ascension
+
+Angle measured East from the Vernal Equinox, the point where the Sun crosses the
+celestial equator in March as it passes from the southern to the northern half
+of the sky. By convention, right ascension is usually displayed in hours.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
+equatorial = saturn.apparent.equatorial
+
+equatorial.right_ascension.str(:hms)
+# => "20h 45m 2.6702s"
+```
+
+You can learn more about angles on the [Angle page].
+
+### Declination
+
+Angle measured north and south of the celestial equator in degrees, with north
+being positive. The North Celestial Pole is at +90° and the South Celestial Pole
+is at -90°.
+
+```rb
+equatorial.declination.str(:dms)
+# => "-18° 46′ 16.1226″"
+```
+
+### Hour angle
+
+Sometimes convenient for astronomers, a third attribute can be derived from
+equatorial coordinates: the hour angle. It is the angle between the meridian
+plane and the hour circle, meaning it depends on the observer's longitude and
+time. By convention, the hour angle is usually displayed in hours.
+
+```rb
+longitude = Astronoby::Angle.from_degrees(2)
+
+equatorial.compute_hour_angle(longitude: longitude, time: time).str(:hms)
+# => "23h 27m 54.9585s"
+```
+
+## Ecliptic
+
+In Astronoby, ecliptic coordinates are geocentric spherical coordinates. Their
+origin is the centre of Earth, their primary direction is towards the March
+equinox, and they have a right-hand convention. Ecliptic coordinates are
+particularly handy for representing positions of Solar System objects.
+
+As per Wikipedia's definition:
+
+> The celestial equator and the ecliptic are slowly moving due to perturbing
+> forces on the Earth, therefore the orientation of the primary direction, their
+> intersection at the March equinox, is not quite fixed. A slow motion of
+> Earth's axis, precession, causes a slow, continuous turning of the coordinate
+> system westward about the poles of the ecliptic. Superimposed on this is a
+> smaller motion of the ecliptic, and a small oscillation of the Earth's axis,
+> nutation.
+
+This primary direction depends on the [reference frame] used.
+
+They have two main angular attributes:
+
+### Latitude
+
+The ecliptic latitude measures the angular distance of an object along the
+ecliptic from the primary direction.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+time = Time.utc(1962, 7, 24)
+instant = Astronoby::Instant.from_time(time)
+
+saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
+ecliptic = saturn.apparent.ecliptic
+
+ecliptic.latitude.str(:dms)
+# => "-0° 41′ 27.5439″"
+```
+
+### Longitude
+
+The ecliptic latitude measures the angular distance of an object from the
+ecliptic towards the north (positive) or south (negative) ecliptic pole.
+
+```rb
+ecliptic.longitude.str(:dms)
+# => "+308° 38′ 33.1744″"
+```
+
+## Horizontal
+
+Horizontal coordinates are the most observer-centred and human-intuitive
+coordinates. They measure where an object is in the sky as seen from an observer
+on Earth as "up and down" and "left and right".
+
+In Astronoby, they can only be computed from a [topocentric position].
+
+They have two main angular attributes:
+
+### Altitude
+
+The angle between the object and the observer's local horizon.
+
+```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(42),
+  longitude: Astronoby::Angle.from_degrees(2)
+)
+
+saturn = Astronoby::Saturn.new(ephem: ephem, instant: instant)
+horizontal = saturn.observed_by(observer).horizontal
+
+horizontal.altitude.str(:dms)
+# => "+28° 46′ 39.5994″"
+```
+
+### Azimuth
+
+The angle of the object around the horizon from the north and increasing
+eastward.
+
+```rb
+horizontal.azimuth.str(:dms)
+# => "+171° 19′ 50.5798″"
+```
+
+[reference frame]: reference_frames.md
+[Wikipedia]: https://en.wikipedia.org/wiki/Equatorial_coordinate_system
+[Angle page]: angles.md
+[topocentric position]: reference_frames.md#topocentric
+
+## See also
+- [Reference Frames](reference_frames.md) - for coordinate system details
+- [Angles](angles.md) - for working with angular measurements
+- [Observer](observer.md) - for location setup
+- [Solar System Bodies](solar_system_bodies.md) - for object positions