astronoby 0.7.0 → 0.8.0

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

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
@@ -90,7 +95,7 @@ module Astronoby
       DateTime.jd(
         @terrestrial_time -
           Rational(delta_t / Constants::SECONDS_PER_DAY) +
-          JULIAN_DAY_NUMBER_OFFSET
+          DATETIME_JD_EPOCH_ADJUSTMENT
       )
     end
 

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 +

data/lib/astronoby/precession.rb

@@ -16,41 +16,43 @@ module Astronoby
       #  https://syrte.obspm.fr/iau2006/aa03_412_P03.pdf
       # P(t) = R3(χA) R1(−ωA) R3(−ψA) R1(ϵ0)
 
-      # Precession in right ascension
-      psi_a = ((((
-          -0.0000000951 * t +
-          +0.000132851) * t +
-          -0.00114045) * t +
-          -1.0790069) * t +
-          +5038.481507) * t
-
-      # Precession in declination
-      omega_a = ((((
-        +0.0000003337 * t +
-        -0.000000467) * t +
-        -0.00772503) * t +
-        +0.0512623) * t +
-        -0.025754) * t +
-        eps0
-
-      # Precession of the ecliptic
-      chi_a = ((((
-        -0.0000000560 * t +
-        +0.000170663) * t +
-        -0.00121197) * t +
-        -2.3814292) * t +
-        +10.556403) * t
-
-      psi_a = Angle.from_degree_arcseconds(psi_a)
-      omega_a = Angle.from_degree_arcseconds(omega_a)
-      chi_a = Angle.from_degree_arcseconds(chi_a)
-
-      r3_psi = rotation_z(-psi_a)
-      r1_omega = rotation_x(-omega_a)
-      r3_chi = rotation_z(chi_a)
-      r1_eps0 = rotation_x(MeanObliquity.obliquity_of_reference)
-
-      r3_chi * r1_omega * r3_psi * r1_eps0
+      cache.fetch(cache_key) do
+        # Precession in right ascension
+        psi_a = ((((
+            -0.0000000951 * t +
+            +0.000132851) * t +
+            -0.00114045) * t +
+            -1.0790069) * t +
+            +5038.481507) * t
+
+        # Precession in declination
+        omega_a = ((((
+          +0.0000003337 * t +
+          -0.000000467) * t +
+          -0.00772503) * t +
+          +0.0512623) * t +
+          -0.025754) * t +
+          eps0
+
+        # Precession of the ecliptic
+        chi_a = ((((
+          -0.0000000560 * t +
+          +0.000170663) * t +
+          -0.00121197) * t +
+          -2.3814292) * t +
+          +10.556403) * t
+
+        psi_a = Angle.from_degree_arcseconds(psi_a)
+        omega_a = Angle.from_degree_arcseconds(omega_a)
+        chi_a = Angle.from_degree_arcseconds(chi_a)
+
+        r3_psi = rotation_z(-psi_a)
+        r1_omega = rotation_x(-omega_a)
+        r3_chi = rotation_z(chi_a)
+        r1_eps0 = rotation_x(MeanObliquity.obliquity_of_reference)
+
+        r3_chi * r1_omega * r3_psi * r1_eps0
+      end
     end
 
     def rotation_x(angle)
@@ -106,7 +108,7 @@ module Astronoby
     end
 
     def self.matrix_for_epoch(epoch)
-      t = (epoch - Epoch::DEFAULT_EPOCH) / Constants::DAYS_PER_JULIAN_CENTURY
+      t = (epoch - JulianDate::DEFAULT_EPOCH) / Constants::DAYS_PER_JULIAN_CENTURY
 
       zeta = Angle.from_degrees(
         0.6406161 * t + 0.0000839 * t * t + 0.000005 * t * t * t
@@ -146,15 +148,23 @@ module Astronoby
 
     private
 
+    def cache_key
+      @_cache_key ||= CacheKey.generate(:precession, @instant)
+    end
+
+    def cache
+      Astronoby.cache
+    end
+
     def t
       @t ||= Rational(
-        @instant.tdb - Epoch::DEFAULT_EPOCH,
+        @instant.tdb - JulianDate::DEFAULT_EPOCH,
         Constants::DAYS_PER_JULIAN_CENTURY
       )
     end
 
     def eps0
-      @eps0 ||= MeanObliquity.obliquity_of_reference_in_milliarcseconds
+      @eps0 ||= MeanObliquity.obliquity_of_reference_in_arcseconds
     end
   end
 end

data/lib/astronoby/reference_frame.rb

@@ -34,7 +34,8 @@ module Astronoby
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(epoch: Epoch::J2000)
+        j2000 = Instant.from_terrestrial_time(JulianDate::J2000)
+        equatorial.to_ecliptic(instant: j2000)
       end
     end
 

data/lib/astronoby/reference_frames/apparent.rb

@@ -43,7 +43,7 @@ module Astronoby
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(epoch: @instant.tdb)
+        equatorial.to_ecliptic(instant: @instant)
       end
     end
 

data/lib/astronoby/reference_frames/mean_of_date.rb

@@ -31,7 +31,7 @@ module Astronoby
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(epoch: @instant.tdb)
+        equatorial.to_ecliptic(instant: @instant)
       end
     end
   end

data/lib/astronoby/reference_frames/topocentric.rb

@@ -48,21 +48,11 @@ module Astronoby
       @observer = observer
     end
 
-    def angular_diameter
-      @angular_radius ||= begin
-        return Angle.zero if @position.zero?
-
-        Angle.from_radians(
-          Math.atan(@target_body.class::EQUATORIAL_RADIUS.m / distance.m) * 2
-        )
-      end
-    end
-
     def ecliptic
       @ecliptic ||= begin
         return Coordinates::Ecliptic.zero if distance.zero?
 
-        equatorial.to_ecliptic(epoch: @instant.tdb)
+        equatorial.to_ecliptic(instant: @instant)
       end
     end
 

data/lib/astronoby/time/greenwich_sidereal_time.rb

@@ -20,7 +20,7 @@ module Astronoby
     def self.from_utc(utc)
       date = utc.to_date
       julian_day = utc.to_date.ajd
-      t = (julian_day - Epoch::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
+      t = (julian_day - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
       t0 = (
         (JULIAN_CENTURIES_EXPONENTS[0] +
           (JULIAN_CENTURIES_EXPONENTS[1] * t) +
@@ -51,7 +51,7 @@ module Astronoby
     def to_utc
       date = @date
       julian_day = @date.ajd
-      t = (julian_day - Epoch::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
+      t = (julian_day - JulianDate::J2000) / Constants::DAYS_PER_JULIAN_CENTURY
 
       t0 = (
         (JULIAN_CENTURIES_EXPONENTS[0] +

data/lib/astronoby/true_obliquity.rb

@@ -2,9 +2,8 @@
 
 module Astronoby
   class TrueObliquity
-    def self.for_epoch(epoch)
-      instant = Instant.from_utc_julian_date(epoch)
-      mean_obliquity = MeanObliquity.for_epoch(epoch)
+    def self.at(instant)
+      mean_obliquity = MeanObliquity.at(instant)
       nutation = Nutation.new(instant: instant).nutation_in_obliquity
 
       mean_obliquity + nutation

data/lib/astronoby/util/time.rb

@@ -496,7 +496,7 @@ module Astronoby
         when Numeric
           instant
         when ::Time, ::Date, ::DateTime
-          Epoch.from_time(instant)
+          JulianDate.from_time(instant)
         else
           raise IncompatibleArgumentsError,
             "Expected a Numeric, Time, Date or DateTime object, got #{instant.class}"

data/lib/astronoby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Astronoby
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end