astronoby 0.6.0 → 0.8.0

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
+- [Celestial Bodies](celestial_bodies.md) - for object positions

data/docs/ephem.md

@@ -0,0 +1,85 @@
+# `Ephem`
+
+`Astronoby` depends on the gem [`ephem`] which provides a Ruby interface for
+<abbr title="Jet Propulsion Laboratory">JPL</abbr> SPICE binary kernels.
+
+These kernels are extremely precise ephemerides produced by the JPL and are the
+foundation of the data provided by Astronoby. The [IMCCE] also produces
+kernels in the same format for their
+<abbr title="Intégrateur numérique planétaire de l'Observatoire de Paris">INPOP</abbr>
+model.
+
+## Download an ephemeris
+
+To download an ephemeris, you can either do it manually or use `ephem` by
+providing the filename.
+
+### Manually
+
+Ephemerides are available for download from:
+* the JPL public FTP interface: https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/
+* the INPOP releases page of the IMCCE: https://www.imcce.fr/inpop
+
+You can download any `.bsp` file. For the moment, Astronoby only supports the
+planets of the Solar System, and the Sun and the Moon, so you need to
+download a _Development Ephemeris_, which starts with `de` (i.e. `de421.bsp`),
+or any of the INPOP ephemeris files (i.e. `inpop19a.bsp`).
+
+### With `Ephem`
+
+If you already know the ephemeris you want to use, you can use `Ephem` to
+download and store it for you:
+
+```rb
+Astronoby::Ephem.download(name: "de421.bsp", target: "tmp/de421.bsp")
+```
+
+## Load an ephemeris
+
+To compute the position of a Solar System body, you need to provide an ephemeris
+to extract the data from. You can use `Astronoby::Ephem` to load the file you
+downloaded.
+
+```rb
+ephem = Astronoby::Ephem.load("tmp/de421.bsp")
+```
+
+## How to choose the right ephemeris?
+
+JPL produces many different kernels over the years, with different accuracy and
+ranges of supported years. Here are some that we recommend to begin with:
+- `de421.bsp`: from 1900 to 2050, 17 MB
+- `de440s.bsp`: from 1849 to 2150, 32 MB
+- `inpop19a.bsp`: from 1900 to 2100, 22 MB
+
+## How to limit weight and increase speed?
+
+The `Ephem` library offers a <abbr title="Command-Line Interface">CLI</abbr> to
+produce excerpt ephemerides in order to limit the range of dates or bodies.
+
+Here is an example to produce an excerpt ephemeris for the year 2025:
+
+```
+ruby-ephem excerpt 2024-12-31 2026-01-01 de440s.bsp de440s_2025_excerpt.bsp
+```
+
+You can also specify which bodies of the Solar System (or "targets") you want to
+include:
+
+```
+ruby-ephem excerpt --targets 10,399 2024-12-31 2026-01-01 inpop19a.bsp inpop19a_2025_sun_earth.bsp
+```
+
+You may want to check how bodies are handled between JPL DE and IMCCE INPOP. For
+example, the excerpt file from a JPL DE kernel needs to include targets `3` and
+`399` for the Earth, while the excerpt file from a IMCCE INPOP kernel only needs
+the target `399`.
+
+[`ephem`]: https://github.com/rhannequin/ruby-ephem
+[IMCCE]: https://www.imcce.fr
+
+## See also
+- [Celestial Bodies](celestial_bodies.md) - for using ephemeris data
+- [Reference Frames](reference_frames.md) - for coordinate calculations
+- [Observer](observer.md) - for location-based calculations
+- [Configuration](configuration.md) - for performance tuning

data/docs/equinoxes_solstices_times.md

@@ -0,0 +1,31 @@
+# Equinoxes and Solstice Times
+
+The equinox and solstice are two precise events that each happen twice a year.
+
+The equinox is the time when the Sun appears directly above the equator, the
+solstice is the time when the Sun reaches its most northerly or southerly
+excursion relative to the celestial equator on the celestial sphere.
+
+Astronoby enables you to compute the time for each of these four events.
+
+```rb
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+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
+```
+
+## See also
+- [Twilight Times](twilight_times.md) - for seasonal sun events
+- [Moon Phases](moon_phases.md) - for lunar events
+- [Ephemerides](ephem.md) - for data sources
+- [Instant](instant.md) - for time handling

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