astronoby 0.7.0 → 0.8.0

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

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