astronoby 0.7.0 → 0.9.0

data/lib/astronoby/events/moon_phases.rb

@@ -15,17 +15,19 @@ module Astronoby
       # @param month [Integer] Requested month
       # @return [Array<Astronoby::MoonPhase>] List of Moon phases
       def self.phases_for(year:, month:)
-        [
-          MoonPhase.first_quarter(new(year, month, :first_quarter, -0.75).time),
-          MoonPhase.full_moon(new(year, month, :full_moon, -0.5).time),
-          MoonPhase.last_quarter(new(year, month, :last_quarter, -0.25).time),
-          MoonPhase.new_moon(new(year, month, :new_moon, 0).time),
-          MoonPhase.first_quarter(new(year, month, :first_quarter, 0.25).time),
-          MoonPhase.full_moon(new(year, month, :full_moon, 0.5).time),
-          MoonPhase.last_quarter(new(year, month, :last_quarter, 0.75).time),
-          MoonPhase.new_moon(new(year, month, :new_moon, 1).time),
-          MoonPhase.first_quarter(new(year, month, :first_quarter, 1.25).time)
-        ].select { _1.time.month == month }
+        Astronoby.cache.fetch([:moon_phases, year, month]) do
+          [
+            MoonPhase.first_quarter(new(year, month, :first_quarter, -0.75).time),
+            MoonPhase.full_moon(new(year, month, :full_moon, -0.5).time),
+            MoonPhase.last_quarter(new(year, month, :last_quarter, -0.25).time),
+            MoonPhase.new_moon(new(year, month, :new_moon, 0).time),
+            MoonPhase.first_quarter(new(year, month, :first_quarter, 0.25).time),
+            MoonPhase.full_moon(new(year, month, :full_moon, 0.5).time),
+            MoonPhase.last_quarter(new(year, month, :last_quarter, 0.75).time),
+            MoonPhase.new_moon(new(year, month, :new_moon, 1).time),
+            MoonPhase.first_quarter(new(year, month, :first_quarter, 1.25).time)
+          ].select { _1.time.month == month }
+        end
       end
 
       # @param year [Integer] Requested year
@@ -43,13 +45,12 @@ module Astronoby
       def time
         correction = moon_phases_periodic_terms
           .public_send(:"#{@phase}_correction")
-        terrestrial_time = Epoch.to_utc(
+        terrestrial_time = Instant.from_terrestrial_time(
           julian_ephemeris_day +
             correction +
             moon_phases_periodic_terms.additional_corrections
         )
-        delta = Util::Time.terrestrial_universal_time_delta(terrestrial_time)
-        (terrestrial_time - delta).round
+        terrestrial_time.to_time.round
       end
 
       private

data/lib/astronoby/events/rise_transit_set_calculator.rb

@@ -23,7 +23,11 @@ module Astronoby
     SUN_REFRACTION_ANGLE = -Angle.from_dms(0, 50, 0)
     EVENT_TYPES = [:rising, :transit, :setting].freeze
 
-    def initialize(body:, observer:, ephem:)
+    # @param body [Astronoby::SolarSystemBody, Astronoby::DeepSkyObject]
+    #   Celestial body for which to calculate events
+    # @param observer [Astronoby::Observer] Observer location
+    # @param ephem [::Ephem::SPK, nil] Ephemeris data source
+    def initialize(body:, observer:, ephem: nil)
       @body = body
       @observer = observer
       @ephem = ephem
@@ -237,13 +241,14 @@ module Astronoby
         )
 
         # Calculate time differences
-        time_differences = new_instants.each_with_index.map do |instant, i|
-          Instant.from_terrestrial_time(instant.tt - old_instants[i].tt)
+        time_differences_in_days = new_instants.each_with_index.map do |instant, i|
+          instant.tt - old_instants[i].tt
         end
 
         # Calculate hour angle rate (radians per day)
         hour_angle_rates = hour_angle_changes.each_with_index.map do |angle, i|
-          angle.radians / time_differences[i].tt
+          denominator = time_differences_in_days[i]
+          angle.radians / denominator
         end
 
         # Store current values for next iteration
@@ -255,7 +260,8 @@ module Astronoby
           .each_with_index
           .map do |angle, i|
             ratio = angle.radians / hour_angle_rates[i]
-            [ratio.nan? ? 0 : ratio, MIN_TIME_ADJUSTMENT].max
+            time_adjustment = (ratio.nan? || ratio.infinite?) ? 0 : ratio
+            [time_adjustment, MIN_TIME_ADJUSTMENT].max
           end
 
         # Apply time adjustments
@@ -268,10 +274,31 @@ module Astronoby
     end
 
     def calculate_positions_at_instants(instants)
-      instants.map do |instant|
-        @body
-          .new(instant: instant, ephem: @ephem)
-          .observed_by(@observer)
+      if Astronoby.configuration.cache_enabled?
+        instants.map do |instant|
+          cache_key = CacheKey.generate(
+            :observed_by,
+            instant,
+            @body.to_s,
+            @observer.hash
+          )
+          Astronoby.cache.fetch(cache_key) do
+            @body
+              .at(instant, ephem: @ephem)
+              .observed_by(@observer)
+          end
+        end
+      else
+        @positions_cache ||= {}
+        precision = Astronoby.configuration.cache_precision(:observed_by)
+        instants.map do |instant|
+          rounded_instant = Instant.from_terrestrial_time(
+            instant.tt.round(precision)
+          )
+          @positions_cache[rounded_instant] ||= @body
+            .at(rounded_instant, ephem: @ephem)
+            .observed_by(@observer)
+        end
       end
     end
 
@@ -329,10 +356,9 @@ module Astronoby
     end
 
     def horizon_angle(distance)
-      case @body.name
-      when "Astronoby::Sun"
+      if @body == Astronoby::Sun
         SUN_REFRACTION_ANGLE
-      when "Astronoby::Moon"
+      elsif @body == Astronoby::Moon
         STANDARD_REFRACTION_ANGLE -
           Angle.from_radians(Moon::EQUATORIAL_RADIUS.m / distance.m)
       else
@@ -347,6 +373,7 @@ module Astronoby
       @sample_instants = nil
       @start_instant = nil
       @end_instant = nil
+      @positions_cache = nil
     end
   end
 end

data/lib/astronoby/events/twilight_calculator.rb

@@ -24,72 +24,114 @@ module Astronoby
       @ephem = ephem
     end
 
-    def event_on(date)
-      observation_events = get_observation_events(date)
-      midday_instant = create_midday_instant(date)
-      sun_at_midday = Sun.new(instant: midday_instant, ephem: @ephem)
-      equatorial_coordinates = sun_at_midday.apparent.equatorial
-
-      morning_civil = compute_twilight_time(
-        MORNING,
-        TWILIGHT_ANGLES[CIVIL],
-        observation_events,
-        equatorial_coordinates
-      )
-
-      evening_civil = compute_twilight_time(
-        EVENING,
-        TWILIGHT_ANGLES[CIVIL],
-        observation_events,
-        equatorial_coordinates
-      )
+    def event_on(date, utc_offset: 0)
+      start_time = Time
+        .new(date.year, date.month, date.day, 0, 0, 0, utc_offset)
+      end_time = Time
+        .new(date.year, date.month, date.day, 23, 59, 59, utc_offset)
+      events = events_between(start_time, end_time)
 
-      morning_nautical = compute_twilight_time(
-        MORNING,
-        TWILIGHT_ANGLES[NAUTICAL],
-        observation_events,
-        equatorial_coordinates
-      )
-
-      evening_nautical = compute_twilight_time(
-        EVENING,
-        TWILIGHT_ANGLES[NAUTICAL],
-        observation_events,
-        equatorial_coordinates
+      TwilightEvent.new(
+        morning_civil_twilight_time:
+          events.morning_civil_twilight_times.first,
+        evening_civil_twilight_time:
+          events.evening_civil_twilight_times.first,
+        morning_nautical_twilight_time:
+          events.morning_nautical_twilight_times.first,
+        evening_nautical_twilight_time:
+          events.evening_nautical_twilight_times.first,
+        morning_astronomical_twilight_time:
+          events.morning_astronomical_twilight_times.first,
+        evening_astronomical_twilight_time:
+          events.evening_astronomical_twilight_times.first
       )
+    end
 
-      morning_astronomical = compute_twilight_time(
-        MORNING,
-        TWILIGHT_ANGLES[ASTRONOMICAL],
-        observation_events,
-        equatorial_coordinates
-      )
+    def events_between(start_time, end_time)
+      rts_events = Astronoby::RiseTransitSetCalculator.new(
+        body: Sun,
+        observer: @observer,
+        ephem: @ephem
+      ).events_between(start_time, end_time)
+
+      equatorial_by_time = {}
+
+      (rts_events.rising_times + rts_events.setting_times)
+        .compact
+        .each do |event_time|
+          rounded_time = event_time.round
+          next if equatorial_by_time.key?(rounded_time)
+
+          instant = Instant.from_time(rounded_time)
+          sun_at_time = Sun.new(instant: instant, ephem: @ephem)
+          equatorial_by_time[rounded_time] = sun_at_time.apparent.equatorial
+        end
+
+      morning_civil = []
+      evening_civil = []
+      morning_nautical = []
+      evening_nautical = []
+      morning_astronomical = []
+      evening_astronomical = []
+
+      arrays_by_period = {
+        MORNING => {
+          CIVIL => morning_civil,
+          NAUTICAL => morning_nautical,
+          ASTRONOMICAL => morning_astronomical
+        },
+        EVENING => {
+          CIVIL => evening_civil,
+          NAUTICAL => evening_nautical,
+          ASTRONOMICAL => evening_astronomical
+        }
+      }
+
+      [
+        [rts_events.rising_times, MORNING],
+        [rts_events.setting_times, EVENING]
+      ].each do |times, period|
+        times.each do |event_time|
+          next unless event_time
+
+          equatorial_coordinates = equatorial_by_time[event_time.round]
+          TWILIGHT_ANGLES.each do |twilight, angle|
+            arrays_by_period[period][twilight] << compute_twilight_time_from(
+              period,
+              angle,
+              event_time,
+              equatorial_coordinates
+            )
+          end
+        end
+      end
 
-      evening_astronomical = compute_twilight_time(
-        EVENING,
-        TWILIGHT_ANGLES[ASTRONOMICAL],
-        observation_events,
-        equatorial_coordinates
-      )
+      within_range = ->(time) { time && time >= start_time && time <= end_time }
 
-      TwilightEvent.new(
-        morning_civil_twilight_time: morning_civil,
-        evening_civil_twilight_time: evening_civil,
-        morning_nautical_twilight_time: morning_nautical,
-        evening_nautical_twilight_time: evening_nautical,
-        morning_astronomical_twilight_time: morning_astronomical,
-        evening_astronomical_twilight_time: evening_astronomical
+      TwilightEvents.new(
+        morning_civil.select(&within_range),
+        evening_civil.select(&within_range),
+        morning_nautical.select(&within_range),
+        evening_nautical.select(&within_range),
+        morning_astronomical.select(&within_range),
+        evening_astronomical.select(&within_range)
       )
     end
 
-    def time_for_zenith_angle(date:, period_of_the_day:, zenith_angle:)
+    def time_for_zenith_angle(
+      date:,
+      period_of_the_day:,
+      zenith_angle:,
+      utc_offset: 0
+    )
       unless PERIODS_OF_THE_DAY.include?(period_of_the_day)
         raise IncompatibleArgumentsError,
-          "Only #{PERIODS_OF_THE_DAY.join(" or ")} are allowed as period_of_the_day, got #{period_of_the_day}"
+          "Only #{PERIODS_OF_THE_DAY.join(" or ")} are allowed as " \
+          "period_of_the_day, got #{period_of_the_day}"
       end
 
-      observation_events = get_observation_events(date)
-      midday_instant = create_midday_instant(date)
+      observation_events = get_observation_events(date, utc_offset: utc_offset)
+      midday_instant = create_midday_instant(date, utc_offset: utc_offset)
       sun_at_midday = Sun.new(instant: midday_instant, ephem: @ephem)
       equatorial_coordinates = sun_at_midday.apparent.equatorial
 
@@ -103,17 +145,17 @@ module Astronoby
 
     private
 
-    def create_midday_instant(date)
-      time = Time.utc(date.year, date.month, date.day, 12)
+    def create_midday_instant(date, utc_offset: 0)
+      time = Time.new(date.year, date.month, date.day, 12, 0, 0, utc_offset)
       Instant.from_time(time)
     end
 
-    def get_observation_events(date)
+    def get_observation_events(date, utc_offset: 0)
       Astronoby::RiseTransitSetCalculator.new(
         body: Sun,
         observer: @observer,
         ephem: @ephem
-      ).event_on(date)
+      ).event_on(date, utc_offset: utc_offset)
     end
 
     def compute_twilight_time(
@@ -128,8 +170,21 @@ module Astronoby
         observation_events.setting_time
       end
 
-      # If the sun doesn't rise or set on this day, we can't calculate
-      # twilight
+      compute_twilight_time_from(
+        period_of_the_day,
+        zenith_angle,
+        period_time,
+        equatorial_coordinates
+      )
+    end
+
+    def compute_twilight_time_from(
+      period_of_the_day,
+      zenith_angle,
+      period_time,
+      equatorial_coordinates
+    )
+      # If the sun doesn't rise or set on this day, we can't calculate twilight
       return nil unless period_time
 
       hour_angle_at_period = equatorial_coordinates
@@ -155,7 +210,7 @@ module Astronoby
 
       twilight_in_hours =
         time_sign * (hour_angle_at_twilight - hour_angle_at_period).hours *
-        GreenwichSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
+        GreenwichMeanSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
       twilight_in_seconds = time_sign *
         twilight_in_hours *
         Constants::SECONDS_PER_HOUR

data/lib/astronoby/events/twilight_events.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class TwilightEvents
+    attr_reader :morning_civil_twilight_times,
+      :evening_civil_twilight_times,
+      :morning_nautical_twilight_times,
+      :evening_nautical_twilight_times,
+      :morning_astronomical_twilight_times,
+      :evening_astronomical_twilight_times
+
+    def initialize(
+      morning_civil,
+      evening_civil,
+      morning_nautical,
+      evening_nautical,
+      morning_astronomical,
+      evening_astronomical
+    )
+      @morning_civil_twilight_times = morning_civil
+      @evening_civil_twilight_times = evening_civil
+      @morning_nautical_twilight_times = morning_nautical
+      @evening_nautical_twilight_times = evening_nautical
+      @morning_astronomical_twilight_times = morning_astronomical
+      @evening_astronomical_twilight_times = evening_astronomical
+    end
+  end
+end

data/lib/astronoby/instant.rb

@@ -21,7 +21,12 @@ module Astronoby
   class Instant
     include Comparable
 
-    JULIAN_DAY_NUMBER_OFFSET = 0.5
+    # The adjustment value to align our noon-based Julian Date with the
+    # midnight-based epoch required by Ruby's `DateTime.jd` constructor.
+    # Our internal time values are standard astronomical Julian Dates, which
+    # start at noon. `DateTime.jd` expects a day that starts at the preceding
+    # midnight. This constant adds 0.5 days (12 hours) to make the conversion.
+    DATETIME_JD_EPOCH_ADJUSTMENT = 0.5
 
     class << self
       # Creates a new Instant from a Terrestrial Time value
@@ -89,8 +94,8 @@ module Astronoby
     def to_datetime
       DateTime.jd(
         @terrestrial_time -
-          Rational(delta_t / Constants::SECONDS_PER_DAY) +
-          JULIAN_DAY_NUMBER_OFFSET
+          Rational(delta_t, Constants::SECONDS_PER_DAY) +
+          DATETIME_JD_EPOCH_ADJUSTMENT
       )
     end
 
@@ -118,9 +123,32 @@ module Astronoby
 
     # Get the Greenwich Mean Sidereal Time
     #
-    # @return [Numeric] the sidereal time in radians
+    # @return [Numeric] the sidereal time in hours
     def gmst
-      GreenwichSiderealTime.from_utc(to_time).time
+      GreenwichMeanSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Greenwich Apparent Sidereal Time
+    #
+    # @return [Numeric] the sidereal time in hours
+    def gast
+      GreenwichApparentSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the Local Mean Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def lmst(longitude:)
+      LocalMeanSiderealTime.from_utc(to_time, longitude: longitude).time
+    end
+
+    # Get the Local Apparent Sidereal Time
+    #
+    # @param longitude [Astronoby::Angle] the observer's longitude
+    # @return [Numeric] the sidereal time in hours
+    def last(longitude:)
+      LocalApparentSiderealTime.from_utc(to_time, longitude: longitude).time
     end
 
     # Get the International Atomic Time (TAI)
@@ -146,7 +174,7 @@ module Astronoby
     #
     # @return [Numeric] the offset in days
     def utc_offset
-      @terrestrial_time - to_time.utc.to_datetime.ajd
+      Rational(delta_t / Constants::SECONDS_PER_DAY)
     end
 
     # Calculate hash value for the instant

data/lib/astronoby/julian_date.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Astronoby
+  # @see https://en.wikipedia.org/wiki/Julian_day
+  # @see https://en.wikipedia.org/wiki/Epoch_(astronomy)
+  class JulianDate
+    # Starting year for Besselian epoch calculations
+    # @return [Integer] 1900
+    BESSELIAN_EPOCH_STARTING_YEAR = 1900
+
+    # Starting year for Julian epoch calculations
+    # @return [Integer] 2000
+    JULIAN_EPOCH_STARTING_YEAR = 2000
+
+    # Julian Date for Besselian epoch 1875.0
+    # @return [Float] 2405889.258550475
+    B1875 = 2405889.258550475
+
+    # Julian Date for Besselian epoch 1900.0
+    # @return [Float] 2415020.31352
+    B1900 = 2415020.31352
+
+    # Julian Date for Julian epoch 1950.0
+    # @return [Float] 2433282.5
+    J1950 = 2433282.5
+
+    # Julian Date for Julian epoch 2000.0 (current standard)
+    # @return [Float] 2451545.0
+    J2000 = 2451545.0
+
+    # Default epoch used by the library
+    # @return [Float] 2451545.0
+    DEFAULT_EPOCH = J2000
+
+    # Converts a Time object to Julian Date
+    #
+    # @param time [Time] the time to convert
+    # @return [Rational] the Julian Date
+    #
+    # @example
+    #   JulianDate.from_time(Time.utc(2000, 1, 1, 12, 0, 0))
+    #   # => 2451545.0
+    def self.from_time(time)
+      time.to_datetime.ajd
+    end
+
+    # Converts a Julian year to Julian Date
+    #
+    # Uses the formula: JD = J2000 + 365.25 * (year - 2000)
+    #
+    # @param julian_year [Float] the Julian year
+    # @return [Float] the Julian Date
+    #
+    # @example
+    #   JulianDate.from_julian_year(2025.0)
+    #   # => 2460676.25
+    def self.from_julian_year(julian_year)
+      J2000 + Constants::DAYS_PER_JULIAN_YEAR *
+        (julian_year - JULIAN_EPOCH_STARTING_YEAR)
+    end
+
+    # Converts a Besselian year to Julian Date
+    #
+    # Uses the formula: JD = B1900 + 365.242198781 * (year - 1900)
+    # where 365.242198781 is the tropical year length at B1900.
+    #
+    # @param besselian_year [Float] the Besselian year
+    # @return [Float] the Julian Date
+    #
+    # @example
+    #   JulianDate.from_besselian_year(1875.0)
+    #   # => 2405889.258550475
+    def self.from_besselian_year(besselian_year)
+      B1900 + Constants::TROPICAL_YEAR_AT_B1900 *
+        (besselian_year - BESSELIAN_EPOCH_STARTING_YEAR)
+    end
+  end
+end

data/lib/astronoby/mean_obliquity.rb

@@ -9,36 +9,34 @@ module Astronoby
     #  IAU resolution in 2006 in favor of the P03 astronomical model
     #  https://syrte.obspm.fr/iau2006/aa03_412_P03.pdf
 
-    EPOCH_OF_REFERENCE = Epoch::DEFAULT_EPOCH
+    EPOCH_OF_REFERENCE = JulianDate::DEFAULT_EPOCH
     OBLIQUITY_OF_REFERENCE = 23.4392794
 
-    def self.for_epoch(epoch)
-      return obliquity_of_reference if epoch == EPOCH_OF_REFERENCE
+    def self.at(instant)
+      return obliquity_of_reference if instant.julian_date == EPOCH_OF_REFERENCE
 
       t = Rational(
-        (epoch - EPOCH_OF_REFERENCE),
+        instant.julian_date - EPOCH_OF_REFERENCE,
         Constants::DAYS_PER_JULIAN_CENTURY
       )
 
-      epsilon0 = obliquity_of_reference_in_milliarcseconds
+      epsilon0 = obliquity_of_reference_in_arcseconds
       c1 = -46.836769
       c2 = -0.0001831
       c3 = 0.00200340
       c4 = -0.000000576
       c5 = -0.0000000434
 
-      Angle.from_dms(
-        0,
-        0,
+      Angle.from_degree_arcseconds(
         epsilon0 + t * (c1 + t * (c2 + t * (c3 + t * (c4 + t * c5))))
       )
     end
 
     def self.obliquity_of_reference
-      Angle.from_dms(0, 0, obliquity_of_reference_in_milliarcseconds)
+      Angle.from_degree_arcseconds(obliquity_of_reference_in_arcseconds)
     end
 
-    def self.obliquity_of_reference_in_milliarcseconds
+    def self.obliquity_of_reference_in_arcseconds
       84381.406
     end
   end

data/lib/astronoby/nutation.rb

@@ -104,7 +104,7 @@ module Astronoby
 
     # @return [Matrix] The nutation matrix
     def matrix
-      mean_obliquity = MeanObliquity.for_epoch(@instant.tt)
+      mean_obliquity = MeanObliquity.at(@instant)
       true_obliquity = mean_obliquity + nutation_in_obliquity
       build_nutation_matrix(
         mean_obliquity: mean_obliquity,
@@ -125,6 +125,14 @@ module Astronoby
 
     private
 
+    def cache_key
+      @_cache_key ||= CacheKey.generate(:nutation, @instant)
+    end
+
+    def cache
+      Astronoby.cache
+    end
+
     def iau2000a
       a = fundamental_arguments
 
@@ -172,7 +180,7 @@ module Astronoby
     end
 
     def iau2000b_angles
-      @iau2000b_angles ||= begin
+      cache.fetch(cache_key) do
         dpsi, deps = iau2000b
         dpsi = Angle.from_degree_arcseconds(dpsi / 1e7)
         deps = Angle.from_degree_arcseconds(deps / 1e7)
@@ -206,7 +214,7 @@ module Astronoby
 
     def julian_centuries
       @julian_centuries ||=
-        (@instant.tt - Epoch::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
+        (@instant.tt - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
     end
 
     # IAU 2006/2000A formula for the mean anomaly of the Moon

data/lib/astronoby/observer.rb

@@ -62,7 +62,7 @@ module Astronoby
     def earth_fixed_rotation_matrix_for(instant)
       dpsi = Nutation.new(instant: instant).nutation_in_longitude
 
-      mean_obliquity = MeanObliquity.for_epoch(instant.tt)
+      mean_obliquity = MeanObliquity.at(instant)
 
       gast = Angle.from_radians(
         Angle.from_hours(instant.gmst).radians +