astronoby 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3406973da55433c82cd985454453f570220feb119f8274176ed8ab0539a8c99d
-  data.tar.gz: c4094d2e8a6d9be6c93ef0c48a8202cec8fe8e6a8f12197f9ee930b18b1e1302
+  metadata.gz: e26fab1e74e0fa27c784712cb44a5557c553c1104752eb5e63ddda0c48a95b52
+  data.tar.gz: cfb3e98fc8a4f841b144a0ae2ea435ea764d7eafb85f150a0e3cc7495af3218e
 SHA512:
-  metadata.gz: 49156fb3ade1cc6b3d15120e4942c0a798b00fdff3b35024cf3ffe8f1bf9c8d7f1eeae40d457485ae3a225e418fa5f8e5c4bc95e826ed14b3ff26b71b2fa6200
-  data.tar.gz: cee4783838c39d8df122dc5542cc52eee1527aa37a6fab493759c58a89686b0bc2b9cc547cbec2bd6feaee2a46bc094a72dba0a372719a4875355d1af8440f00
+  metadata.gz: 43b7bdbd274fc42b1c1c992a677abf71dc831e727abb2bf78b93190595a4746a07f266affececa6e495a534eda304164422623a09673fe779c9b1064be9d11d0
+  data.tar.gz: b8a3dcd0992c55606c6e13b4f7783325268a1168d26343ac6a20d050514ca7b30b4fd3548a2903db5abfcbb8133efe79ae7868681cdcba8b61d284862f1f423c

data/.ruby-version

@@ -1 +1 @@
-3.4.3
+3.4.4

data/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.8.0 - 2025-09-01
+
+_If you are upgrading: please see [UPGRADING.md]._
+
+### Bug fixes
+
+* Fix UPGRADING documentation ([#178])
+* Fix possible division by zero in RTS ([#185])
+
+### Features
+
+* Introduce performance benchmark ([#183])
+* Cache positions in RTS calculator ([#182])
+* Internal global LRU cache ([#186])
+* Global configuration ([#187])
+* Compute the constellation a body is in ([#199])
+* Add `#phase_angle` and `#illuminated_fraction` to planets ([#200])
+* Apparent magnitude ([#201])
+* Add #events_between to TwilightCalculator with better accuracy ([#204])
+* `#angular_diameter` on Solar System bodies ([#207])
+* Fix constellation boundaries near 24h right ascension ([#209])
+
+### Improvements
+
+* Bump standard from 1.49.0 to 1.50.0 by @dependabot ([#177])
+* Bump ephem from 0.3.0 to 0.4.1 by @dependabot ([#181], [#191])
+* Bump irb from 1.14.3 to 1.15.2 by @dependabot ([#184])
+* Bump rspec from 3.13.0 to 3.13.1 by @dependabot ([#188])
+* Bump benchmark from 0.4.0 to 0.4.1 by @dependabot ([#189])
+* Bump rake from 13.2.1 to 13.3.0 by @dependabot ([#190])
+* Bump matrix from 0.4.2 to 0.4.3 by @dependabot ([#193])
+* Update rubyzip requirement from ~> 2.3 to ~> 3.0 by @dependabot ([#194])
+* Bump rubyzip from 3.0.0 to 3.0.2 by @dependabot ([#202], [#206])
+* Exclude benchmarks from release ([#196])
+* `Epoch` refactoring into `JulianDate` ([#197])
+* Support Ruby 3.4.4 ([#198])
+* Bump actions/checkout from 4 to 5 ([#203])
+* Internal documentation ([#205])
+
+### Backward-incompatible changes
+
+* `Epoch` refactoring into `JulianDate` ([#197])
+* `#angular_diameter` on Solar System bodies ([#207])
+* Rename "epoch" ([#208])
+
+### Closed issues
+
+* Consider adding typical usage/deployment info ([#179])
+* Performance degradation in v0.7 ([#180])
+
+**Full Changelog**: https://github.com/rhannequin/astronoby/compare/v0.7.0...v0.8.0
+
+[#177]: https://github.com/rhannequin/astronoby/pull/177
+[#178]: https://github.com/rhannequin/astronoby/pull/178
+[#179]: https://github.com/rhannequin/astronoby/pull/179
+[#180]: https://github.com/rhannequin/astronoby/pull/180
+[#181]: https://github.com/rhannequin/astronoby/pull/181
+[#182]: https://github.com/rhannequin/astronoby/pull/182
+[#183]: https://github.com/rhannequin/astronoby/pull/183
+[#184]: https://github.com/rhannequin/astronoby/pull/184
+[#185]: https://github.com/rhannequin/astronoby/pull/185
+[#186]: https://github.com/rhannequin/astronoby/pull/186
+[#187]: https://github.com/rhannequin/astronoby/pull/187
+[#188]: https://github.com/rhannequin/astronoby/pull/188
+[#189]: https://github.com/rhannequin/astronoby/pull/189
+[#190]: https://github.com/rhannequin/astronoby/pull/190
+[#191]: https://github.com/rhannequin/astronoby/pull/191
+[#193]: https://github.com/rhannequin/astronoby/pull/193
+[#194]: https://github.com/rhannequin/astronoby/pull/194
+[#196]: https://github.com/rhannequin/astronoby/pull/196
+[#197]: https://github.com/rhannequin/astronoby/pull/197
+[#198]: https://github.com/rhannequin/astronoby/pull/198
+[#199]: https://github.com/rhannequin/astronoby/pull/199
+[#200]: https://github.com/rhannequin/astronoby/pull/200
+[#201]: https://github.com/rhannequin/astronoby/pull/201
+[#202]: https://github.com/rhannequin/astronoby/pull/202
+[#203]: https://github.com/rhannequin/astronoby/pull/203
+[#204]: https://github.com/rhannequin/astronoby/pull/204
+[#205]: https://github.com/rhannequin/astronoby/pull/205
+[#206]: https://github.com/rhannequin/astronoby/pull/206
+[#207]: https://github.com/rhannequin/astronoby/pull/207
+[#208]: https://github.com/rhannequin/astronoby/pull/208
+[#209]: https://github.com/rhannequin/astronoby/pull/209
+
 ## 0.7.0 - 2025-05-12
 
 _If you are upgrading: please see [UPGRADING.md]._
@@ -296,7 +380,7 @@ _If you are upgrading: please see [UPGRADING.md]._
 
 ## 0.3.0 - 2024-03-29
 
-_If you are upgrading: please see [`UPGRADING.md`]._
+_If you are upgrading: please see [UPGRADING.md]._
 
 ### Improvements
 
@@ -315,7 +399,7 @@ _If you are upgrading: please see [`UPGRADING.md`]._
 
 ## 0.2.0 - 2024-03-24
 
-_If you are upgrading: please see [`UPGRADING.md`]._
+_If you are upgrading: please see [UPGRADING.md]._
 
 ### Features
 
@@ -386,4 +470,4 @@ _If you are upgrading: please see [`UPGRADING.md`]._
 * Add `Astronoby::Angle`
 * Support angles in degrees and radians
 
-[`UPGRADING.md`]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md
+[UPGRADING.md]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md

data/README.md

@@ -2,7 +2,7 @@
 
 [![Tests](https://github.com/rhannequin/astronoby/workflows/Ruby/badge.svg)](https://github.com/rhannequin/astronoby/actions?query=workflow%3ARuby)
 
-Ruby library to provide a useful API to compute astronomical calculations.
+Ruby library that provides a useful API for computing astronomical calculations.
 
 Some algorithms are based on the following astrometry books:
 * _Astronomical Algorithms_ by Jean Meeus
@@ -10,10 +10,8 @@ Some algorithms are based on the following astrometry books:
 * _Practical Astronomy with your Calculator or Spreadsheet_ by Peter
   Duffet-Smith and Jonathan Zwart
 
-Solar System body's positions are computed based on ephemerides coming from
-the [IMCCE] or [NASA/JPL].
-
-[NASA/JPL]: https://ssd.jpl.nasa.gov/planets/eph_export.html
+Solar System bodies' positions are computed based on ephemerides from the
+[IMCCE] or [NASA/JPL].
 
 ## Content
 - [Installation](#installation)
@@ -35,45 +33,39 @@ executing:
 
     $ gem install astronoby
 
-[Bundler]: https://bundler.io
-
 ## Usage Documentation
 
-Since version 0.7.0, the usage documentation resides in the [Wiki]. For
+Since version 0.7.0, the usage documentation resides in [`docs/`]. For
 previous versions, you can access the documentation in the README for each
 [release].
 
-[Wiki]: https://github.com/rhannequin/astronoby/wiki
-[release]: https://github.com/rhannequin/astronoby/releases
+### See also
+- [Quick Start Guide](docs/README.md) - for getting started examples
+- [Celestial Bodies](docs/celestial_bodies.md) - for understanding planets and objects
+- [Reference Frames](docs/reference_frames.md) - for coordinate systems
+- [Observer Setup](docs/observer.md) - for location configuration
+- [Glossary](docs/glossary.md) - for astronomical and technical terms
 
 ### Expected breaking changes notice
 
-This library is still in heavy development. The public is not stable, please
-be aware new minor versions will probably lead to breaking changes until a
-major one is released.
+This library is still in heavy development. The public API is not stable, so
+please be aware that new minor versions will probably lead to breaking changes
+until a major one is released.
 
 Changes are documented in the [CHANGELOG] and adapting to breaking changes is
 described in the [UPGRADING] document.
 
-[CHANGELOG]: https://github.com/rhannequin/astronoby/blob/main/CHANGELOG.md
-[UPGRADING]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md
-
 ## Precision
 
-The current precision for the major Solar System bodies' location in the sky
-as seen from an observer on Earth is below 10 arc seconds. It corresponds to
-half the size of Saturn when it is the closest to Earth.
+The current precision for the major Solar System bodies' locations in the sky
+as seen from an observer on Earth is below 10 arc seconds. This corresponds to
+half the size of Saturn when it is closest to Earth.
 
 While the precision is not enough for spacecraft navigation, it is enough for
 automated guiding of amateur telescopes.
 
-The compared sources are: [IMCCE], [JPL Horizons], [Stellarium], and the
-[Skyfield] library.
-
-[IMCCE]: https://www.imcce.fr
-[JPL Horizons]: https://ssd.jpl.nasa.gov/horizons.cgi
-[Stellarium]: https://stellarium.org
-[Skyfield]: https://rhodesmill.org/skyfield/
+The sources used for comparison are: [IMCCE], [JPL Horizons], [Stellarium],
+and the [Skyfield] library.
 
 ## Development
 
@@ -86,15 +78,35 @@ release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and the created tag, and push the `.gem` file to [rubygems.org].
 
-[rubygems.org]: https://rubygems.org
+### Performance
 
-## Contributing
+The library is designed to be fast, but there is always room for improvement.
+When comparing the performance of two implementations, please use the
+performance benchmark in the console before and after your implementation.
 
-Please see [CONTRIBUTING.md].
+    $ bin/console
 
-[CONTRIBUTING.md]: https://github.com/rhannequin/astronoby/blob/main/CONTRIBUTING.md
+```rb
+require_relative "benchmarks/performance"
 
-[code of conduct]: https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md
+PerformanceBenchmark.new.run
+```
+
+For fast feedback, you can customise the parameters:
+
+```rb
+PerformanceBenchmark
+  .new(warmup_runs: 1, measure_runs: 3, iterations_per_run: 5)
+  .run
+```
+
+Performance is not absolute, which is why the results are not documented here.
+What is important is to compare the relative performance of two implementations
+and make sure new features do not degrade performance.
+
+## Contributing
+
+Please see [CONTRIBUTING.md].
 
 ## License
 
@@ -105,6 +117,18 @@ The gem is available as open source under the terms of the [MIT License].
 ## Code of Conduct
 
 Everyone interacting in the Astronoby project's codebases, issue trackers, chat
-rooms and mailing lists are expected to follow the [code of conduct].
+rooms and mailing lists is expected to follow the [code of conduct].
 
+[NASA/JPL]: https://ssd.jpl.nasa.gov/planets/eph_export.html
+[Bundler]: https://bundler.io
+[`docs/`]: https://github.com/rhannequin/astronoby/blob/main/docs
+[release]: https://github.com/rhannequin/astronoby/releases
+[CHANGELOG]: https://github.com/rhannequin/astronoby/blob/main/CHANGELOG.md
+[UPGRADING]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md
+[IMCCE]: https://www.imcce.fr
+[JPL Horizons]: https://ssd.jpl.nasa.gov/horizons.cgi
+[Stellarium]: https://stellarium.org
+[Skyfield]: https://rhodesmill.org/skyfield/
+[rubygems.org]: https://rubygems.org
+[CONTRIBUTING.md]: https://github.com/rhannequin/astronoby/blob/main/CONTRIBUTING.md
 [code of conduct]: https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md

data/UPGRADING.md

@@ -7,9 +7,38 @@ 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`
+### 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
@@ -17,7 +46,7 @@ System bodies. `instant` is an instance of `Instant`, the new concept for
 representing an instant in time.
 
 ```rb
-Ephem::IO::Download.call(name: "de421.bsp", target: "tmp/de421.bsp")
+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)
@@ -30,7 +59,7 @@ Learn more on [ephem].
 
 [ephem]: https://github.com/rhannequin/astronoby/wiki/Ephem
 
-## Drop of methods for `Sun`
+### Drop of methods for `Sun`
 
 `Sun` doesn't expose the following class and instance methods anymore:
 * `::equation_of_time` (replaced with `#equation_of_time`)
@@ -51,7 +80,7 @@ Learn more on [reference frames].
 
 [reference frames]: https://github.com/rhannequin/astronoby/wiki/Reference-Frames
 
-## Drop of instance methods for `Moon`
+### Drop of instance methods for `Moon`
 
 `Moon` doesn't expose the following nstance methods anymore:
 * `#apparent_ecliptic_coordinates` (replaced with `#ecliptic` on reference frames)
@@ -65,7 +94,7 @@ Learn more on [reference frames].
 * `#phase_angle`
 * `#observation_events`
 
-## Signature change for `Aberration`
+### Signature change for `Aberration`
 
 `Aberration` is now initialized with the key arguments `astrometric_position`
 and `observer_velocity`. `astrometric_position` is a position vector
@@ -92,7 +121,7 @@ aberration = Astronoby::Aberration.new(
 )
 ```
 
-## Signature change for `Angle#to_dms` and `Angle#to_hms`
+### 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
@@ -106,49 +135,49 @@ dms.format
 # => "+45° 0′ 0.0″"
 ```
 
-## Signature change for `EquinoxSolstice`
+### Signature change for `EquinoxSolstice`
 
 `EquinoxSolstice.new` now takes an additional argument expected to be an ephem
 (`Astronoby::Ephem`).
 
-## Signature change for `Nutation`
+### 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`
+### 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`
+### 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`
+### 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`
+### 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`
+### 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`
+### Drop of `Coordinates::Equatorial#to_epoch`
 
 `Coordinates::Equatorial#to_epoch` has been removed.
 
-## Drop of `Events::ObservationEvents`
+### Drop of `Events::ObservationEvents`
 
 `Events::ObservationEvents` has been removed. The rising, transit and setting 
 times can now be calculated using `RiseTransitSetCalculator`.
@@ -179,12 +208,12 @@ event.setting_time
 # => 2025-04-24 18:55:24 UTC
 ```
 
-## Drop of `RiseTransitSetIteration`
+### Drop of `RiseTransitSetIteration`
 
 `RiseTransitSetIteration` has been removed as it was only used by
 `Events::ObservationEvents`.
 
-## Drop of `Events::TwilightEvents`
+### Drop of `Events::TwilightEvents`
 
 `Events::TwilightEvents` has been removed. The twilight times can now be
 calculated using `TwilightCalculator`.
@@ -224,20 +253,20 @@ event.evening_astronomical_twilight_time
 # => 2025-04-24 20:56:34 UTC
 ```
 
-## Drop of `EphemerideLunaireParisienne`
+### Drop of `EphemerideLunaireParisienne`
 
 `EphemerideLunaireParisienne` has been removed.
 
-## Drop of `Util::Astrodynamics`
+### Drop of `Util::Astrodynamics`
 
 `Util::Astrodynamics` has been removed.
 
-## Drop of `Util::Maths.interpolate` and `Util::Maths.normalize_angles_for_interpolation`
+### 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`
+### Drop of `Constants::SECONDS_PER_DEGREE`
 
 `Constants::SECONDS_PER_DEGREE` has been removed.
 

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