astronoby 0.5.0 → 0.7.0

data/UPGRADING.md

@@ -7,6 +7,244 @@ 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.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
+Ephem::IO::Download.call(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/benchmark/README.md

@@ -0,0 +1,131 @@
+# Benchmark
+
+This is a first attempt to benchmark the accuracy of the library. It is not
+very scientific, but it gives a rough idea.
+
+## Method
+
+The goal is to answer these two questions:
+- Is the library accurate enough compared to a source of truth?
+- Is the library accurate enough compared with other Ruby libraries?
+
+The source of truth is the <abbr title="Institut de Mécanique
+Céleste et de Calcul des Éphémérides">IMCCE</abbr>, a French public
+institude attached to the Paris Observatory. Their ephemerides are used by
+governements and public institutions in multiple European countries, their
+precesion is among the highest in the world.
+They also provide web services to easily access all their data. Many thanks
+for providing such high accuracy data for free.
+
+The other Ruby library is [sun_calc](https://github.com/fishbrain/sun_calc).
+
+474,336 combinations of dates, latitudes and longitudes have been used to
+produce time predictions for the following events:
+- sunrise
+- sun's highest point
+- sunset
+- moonrise
+- moon's highest point
+- moonset
+
+For each combination, we first find out which of SunCalc or Astronoby is the
+closest to the IMCCE. Then we calculate the difference between Astronoby and
+the IMCCE, to discover if the difference is larger than the defined
+threshold of 5 minutes.
+
+## Results
+
+The following output has been generated using what will be part of version 0.6.
+
+```
+Unarchiving sun_calc.csv.zip...
+Done unarchiving sun_calc.csv.zip.
+Parsing sun_calc.csv...
+Done parsing sun_calc.csv.
+Unarchiving imcce.csv.zip...
+Done unarchiving imcce.csv.zip.
+Parsing imcce.csv...
+Done parsing imcce.csv.
+Comparing data...
+2024-01-01: Done.
+2024-01-02: Done.
+...
+2024-12-30: Done.
+2024-12-31: Done.
+Done comparing data.
+
+
+Sun rising time:
+astronoby: 295395 (62.28%)
+sun_calc: 99710 (21.02%)
+n/a: 79231 (16.7%)
+
+Sun transit time:
+astronoby: 434495 (91.6%)
+sun_calc: 39769 (8.38%)
+n/a: 72 (0.02%)
+
+Sun setting time:
+astronoby: 358428 (75.56%)
+n/a: 79231 (16.7%)
+sun_calc: 36677 (7.73%)
+
+Moon rising time:
+astronoby: 290866 (61.32%)
+n/a: 113815 (23.99%)
+sun_calc: 69655 (14.68%)
+
+Moon transit time:
+astronoby: 341902 (72.08%)
+n/a: 101916 (21.49%)
+sun_calc: 30518 (6.43%)
+
+Moon setting time:
+astronoby: 327099 (68.96%)
+n/a: 114308 (24.1%)
+sun_calc: 32929 (6.94%)
+
+Moon illuminated fraction:
+astronoby: 474336 (100.0%)
+
+Sun rising time too far:
+false: 452887 (95.48%)
+true: 21449 (4.52%)
+
+Sun transit time too far:
+false: 396617 (83.62%)
+true: 77719 (16.38%)
+
+Sun setting time too far:
+false: 453208 (95.55%)
+true: 21128 (4.45%)
+
+Moon rising time too far:
+false: 459044 (96.78%)
+true: 15292 (3.22%)
+
+Moon transit time too far:
+false: 384516 (81.06%)
+true: 89820 (18.94%)
+
+Moon setting time too far:
+false: 459222 (96.81%)
+true: 15114 (3.19%)
+```
+
+## Conclusion
+
+As we can see, Astronoby is more accurate than SunCalc in a vast majority of
+cases. When it comes to the Moon's illuminated fraction, Astronoby is always
+more accurate than SunCalc.
+
+`n/a` values means that at least one of the three sources don't have a value
+for the combination of date, latitude and longitude. This happens because
+the Moon and the Sun cannot always rise, transit and set everywhere on Earth
+every day of the year. Latitudes close to the poles are more likely to miss
+data.
+
+Astronoby can be considered "good enough" for more around 90% of the cases,
+which means there is still work to do if we want to always be less than 5
+minutes away from the what the IMCCE provides. We can notice that transit
+times are those that experience the most significant differences.

data/benchmark/benchmark.rb

@@ -0,0 +1,259 @@
+require "astronoby"
+require "csv"
+require "zip"
+
+class Source
+  NAMES = [
+    ASTRONOBY = "astronoby",
+    IMCCE = "imcce",
+    SUN_CALC = "sun_calc"
+  ].freeze
+
+  attr_accessor :name,
+    :sun_rising_time,
+    :sun_transit_time,
+    :sun_setting_time,
+    :moon_rising_time,
+    :moon_transit_time,
+    :moon_setting_time,
+    :moon_illuminated_fraction
+end
+
+class Comparison
+  SUN_CALC = "sun_calc"
+  ASTRONOBY = "astronoby"
+  NON_APPLICABLE = "n/a"
+
+  TOO_FAR_THRESHOLD = 60 * 5 # 5 minutes
+
+  attr_accessor :sources, :truth
+
+  def initialize
+    @sources = []
+  end
+
+  %i[
+    sun_rising_time
+    sun_transit_time
+    sun_setting_time
+    moon_rising_time
+    moon_transit_time
+    moon_setting_time
+  ].each do |attribute|
+    define_method(:"closest_#{attribute}") do
+      compare(attribute)
+    end
+
+    define_method(:"#{attribute}_too_far?") do
+      too_far?(attribute)
+    end
+  end
+
+  def closest_moon_illuminated_fraction
+    compare(:moon_illuminated_fraction)
+  end
+
+  private
+
+  def compare(attribute)
+    unless truth.public_send(attribute) && sources.all? { |source| source.public_send(attribute) }
+      return NON_APPLICABLE
+    end
+
+    closest_source = sources.min_by do |source|
+      (truth.public_send(attribute) - source.public_send(attribute)).abs
+    end
+
+    closest_source.name
+  end
+
+  def too_far?(attribute)
+    truth_attribute = truth.public_send(attribute)
+    astronoby_attribute = sources
+      .find { _1.name == Source::ASTRONOBY }
+      .public_send(attribute)
+
+    return false unless truth_attribute && astronoby_attribute
+
+    (truth_attribute - astronoby_attribute).abs > TOO_FAR_THRESHOLD
+  end
+end
+
+class Result
+  def initialize
+    @sun_rising_time = []
+    @sun_transit_time = []
+    @sun_setting_time = []
+    @moon_rising_time = []
+    @moon_transit_time = []
+    @moon_setting_time = []
+    @illuminated_fraction = []
+    @sun_rising_time_too_far = []
+    @sun_transit_time_too_far = []
+    @sun_setting_time_too_far = []
+    @moon_rising_time_too_far = []
+    @moon_transit_time_too_far = []
+    @moon_setting_time_too_far = []
+  end
+
+  def add_comparison(comparison)
+    @sun_rising_time << comparison.closest_sun_rising_time
+    @sun_transit_time << comparison.closest_sun_transit_time
+    @sun_setting_time << comparison.closest_sun_setting_time
+    @moon_rising_time << comparison.closest_moon_rising_time
+    @moon_transit_time << comparison.closest_moon_transit_time
+    @moon_setting_time << comparison.closest_moon_setting_time
+    @illuminated_fraction << comparison.closest_moon_illuminated_fraction
+    @sun_rising_time_too_far << comparison.sun_rising_time_too_far?
+    @sun_transit_time_too_far << comparison.sun_transit_time_too_far?
+    @sun_setting_time_too_far << comparison.sun_setting_time_too_far?
+    @moon_rising_time_too_far << comparison.moon_rising_time_too_far?
+    @moon_transit_time_too_far << comparison.moon_transit_time_too_far?
+    @moon_setting_time_too_far << comparison.moon_setting_time_too_far?
+  end
+
+  def display
+    puts "Sun rising time:"
+    tally(@sun_rising_time)
+    puts "Sun transit time:"
+    tally(@sun_transit_time)
+    puts "Sun setting time:"
+    tally(@sun_setting_time)
+    puts "Moon rising time:"
+    tally(@moon_rising_time)
+    puts "Moon transit time:"
+    tally(@moon_transit_time)
+    puts "Moon setting time:"
+    tally(@moon_setting_time)
+    puts "Moon illuminated fraction:"
+    tally(@illuminated_fraction)
+    puts "Sun rising time too far:"
+    tally(@sun_rising_time_too_far)
+    puts "Sun transit time too far:"
+    tally(@sun_transit_time_too_far)
+    puts "Sun setting time too far:"
+    tally(@sun_setting_time_too_far)
+    puts "Moon rising time too far:"
+    tally(@moon_rising_time_too_far)
+    puts "Moon transit time too far:"
+    tally(@moon_transit_time_too_far)
+    puts "Moon setting time too far:"
+    tally(@moon_setting_time_too_far)
+  end
+
+  private
+
+  def tally(data)
+    t = data.tally
+    t.sort_by { |_key, value| -value }.each do |key, value|
+      puts "#{key}: #{value} (#{(value.to_f / t.values.sum * 100).round(2)}%)"
+    end
+    puts "\n"
+  end
+end
+
+data = {}
+result = Result.new
+
+sun_calc_zip_file = File.join(File.dirname(__FILE__), "data/sun_calc.csv.zip")
+imcce_zip_file = File.join(File.dirname(__FILE__), "data/imcce.csv.zip")
+
+puts "Unarchiving sun_calc.csv.zip..."
+
+Zip::File.open(sun_calc_zip_file) do |zip_file|
+  puts "Done unarchiving sun_calc.csv.zip."
+
+  csv_file = zip_file.find { |entry| entry.name.end_with?(".csv") }
+  break unless csv_file
+
+  puts "Parsing sun_calc.csv..."
+
+  csv_content = csv_file.get_input_stream.read
+  CSV.parse(csv_content, headers: true) do |row|
+    data[row["date"]] ||= {}
+    data[row["date"]][row["latitude"]] ||= {}
+    data[row["date"]][row["latitude"]][row["longitude"]] = Comparison.new.tap do |comparison|
+      source = Source.new.tap do |source|
+        source.name = Source::SUN_CALC
+        source.sun_rising_time = Time.new(row["sun_rising_time"]) if row["sun_rising_time"]
+        source.sun_transit_time = Time.new(row["sun_transit_time"]) if row["sun_transit_time"]
+        source.sun_setting_time = Time.new(row["sun_setting_time"]) if row["sun_setting_time"]
+        source.moon_rising_time = Time.new(row["moon_rising_time"]) if row["moon_rising_time"]
+        source.moon_transit_time = Time.new(row["moon_transit_time"]) if row["moon_transit_time"]
+        source.moon_setting_time = Time.new(row["moon_setting_time"]) if row["moon_setting_time"]
+        source.moon_illuminated_fraction = row["illuminated_fraction"].to_f
+      end
+      comparison.sources << source
+    end
+  end
+
+  puts "Done parsing sun_calc.csv."
+end
+
+puts "Unarchiving imcce.csv.zip..."
+
+Zip::File.open(imcce_zip_file) do |zip_file|
+  puts "Done unarchiving imcce.csv.zip."
+
+  csv_file = zip_file.find { |entry| entry.name.end_with?(".csv") }
+  break unless csv_file
+
+  puts "Parsing imcce.csv..."
+
+  csv_content = csv_file.get_input_stream.read
+  CSV.parse(csv_content, headers: true) do |row|
+    comparison = data[row["date"]][row["latitude"]][row["longitude"]]
+    comparison.truth = Source.new.tap do |source|
+      source.name = Source::IMCCE
+      source.sun_rising_time = Time.new(row["sun_rising_time"] + " UTC") if row["sun_rising_time"]
+      source.sun_transit_time = Time.new(row["sun_transit_time"] + " UTC") if row["sun_transit_time"]
+      source.sun_setting_time = Time.new(row["sun_setting_time"] + " UTC") if row["sun_setting_time"]
+      source.moon_rising_time = Time.new(row["moon_rising_time"] + " UTC") if row["moon_rising_time"]
+      source.moon_transit_time = Time.new(row["moon_transit_time"] + " UTC") if row["moon_transit_time"]
+      source.moon_setting_time = Time.new(row["moon_setting_time"] + " UTC") if row["moon_setting_time"]
+      source.moon_illuminated_fraction = row["illuminated_fraction"].to_f
+    end
+  end
+
+  puts "Done parsing imcce.csv."
+end
+
+puts "Comparing data..."
+
+data.each do |date, latitudes|
+  latitudes.each do |latitude, longitudes|
+    longitudes.each do |longitude, comparison|
+      noon = Time.new("#{date}T12:00:00Z")
+      observer = Astronoby::Observer.new(
+        latitude: Astronoby::Angle.from_degrees(latitude.to_i),
+        longitude: Astronoby::Angle.from_degrees(longitude.to_i)
+      )
+      sun = Astronoby::Sun.new(time: noon)
+      sun_observation_events = sun.observation_events(observer: observer)
+      moon = Astronoby::Moon.new(time: noon)
+      moon_observation_events = moon.observation_events(observer: observer)
+
+      source = Source.new.tap do |source|
+        source.name = Source::ASTRONOBY
+        source.sun_rising_time = sun_observation_events.rising_time
+        source.sun_transit_time = sun_observation_events.transit_time
+        source.sun_setting_time = sun_observation_events.setting_time
+        source.moon_rising_time = moon_observation_events.rising_time
+        source.moon_transit_time = moon_observation_events.transit_time
+        source.moon_setting_time = moon_observation_events.setting_time
+        source.moon_illuminated_fraction = moon.illuminated_fraction
+      end
+
+      comparison.sources << source
+      result.add_comparison(comparison)
+    end
+  end
+
+  puts "#{date}: Done."
+end
+
+puts "Done comparing data."
+puts
+puts
+
+puts result.display