astronoby 0.6.0 → 0.8.0

data/lib/astronoby/events/twilight_calculator.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class TwilightCalculator
+    TWILIGHTS = [
+      CIVIL = :civil,
+      NAUTICAL = :nautical,
+      ASTRONOMICAL = :astronomical
+    ].freeze
+
+    TWILIGHT_ANGLES = {
+      CIVIL => Angle.from_degrees(96),
+      NAUTICAL => Angle.from_degrees(102),
+      ASTRONOMICAL => Angle.from_degrees(108)
+    }.freeze
+
+    PERIODS_OF_THE_DAY = [
+      MORNING = :morning,
+      EVENING = :evening
+    ].freeze
+
+    def initialize(observer:, ephem:)
+      @observer = observer
+      @ephem = ephem
+    end
+
+    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)
+
+      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
+
+    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
+
+      within_range = ->(time) { time && time >= start_time && time <= end_time }
+
+      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:,
+      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}"
+      end
+
+      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
+
+      compute_twilight_time(
+        period_of_the_day,
+        zenith_angle,
+        observation_events,
+        equatorial_coordinates
+      )
+    end
+
+    private
+
+    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, utc_offset: 0)
+      Astronoby::RiseTransitSetCalculator.new(
+        body: Sun,
+        observer: @observer,
+        ephem: @ephem
+      ).event_on(date, utc_offset: utc_offset)
+    end
+
+    def compute_twilight_time(
+      period_of_the_day,
+      zenith_angle,
+      observation_events,
+      equatorial_coordinates
+    )
+      period_time = if period_of_the_day == MORNING
+        observation_events.rising_time
+      else
+        observation_events.setting_time
+      end
+
+      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
+        .compute_hour_angle(time: period_time, longitude: @observer.longitude)
+
+      term1 = zenith_angle.cos -
+        @observer.latitude.sin * equatorial_coordinates.declination.sin
+      term2 = @observer.latitude.cos * equatorial_coordinates.declination.cos
+      hour_angle_ratio_at_twilight = term1 / term2
+
+      # Check if twilight occurs at this location and date
+      return nil unless hour_angle_ratio_at_twilight.between?(-1, 1)
+
+      hour_angle_at_twilight = Angle.acos(hour_angle_ratio_at_twilight)
+      time_sign = -1
+
+      if period_of_the_day == MORNING
+        hour_angle_at_twilight = Angle.from_degrees(
+          Constants::DEGREES_PER_CIRCLE - hour_angle_at_twilight.degrees
+        )
+        time_sign = 1
+      end
+
+      twilight_in_hours =
+        time_sign * (hour_angle_at_twilight - hour_angle_at_period).hours *
+        GreenwichSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
+      twilight_in_seconds = time_sign *
+        twilight_in_hours *
+        Constants::SECONDS_PER_HOUR
+
+      (period_time + twilight_in_seconds).round
+    end
+  end
+end

data/lib/astronoby/events/twilight_event.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class TwilightEvent
+    attr_reader :morning_civil_twilight_time,
+      :evening_civil_twilight_time,
+      :morning_nautical_twilight_time,
+      :evening_nautical_twilight_time,
+      :morning_astronomical_twilight_time,
+      :evening_astronomical_twilight_time
+
+    def initialize(
+      morning_civil_twilight_time: nil,
+      evening_civil_twilight_time: nil,
+      morning_nautical_twilight_time: nil,
+      evening_nautical_twilight_time: nil,
+      morning_astronomical_twilight_time: nil,
+      evening_astronomical_twilight_time: nil
+    )
+      @morning_civil_twilight_time = morning_civil_twilight_time
+      @evening_civil_twilight_time = evening_civil_twilight_time
+      @morning_nautical_twilight_time = morning_nautical_twilight_time
+      @evening_nautical_twilight_time = evening_nautical_twilight_time
+      @morning_astronomical_twilight_time = morning_astronomical_twilight_time
+      @evening_astronomical_twilight_time = evening_astronomical_twilight_time
+    end
+  end
+end

data/lib/astronoby/events/twilight_events.rb

@@ -1,121 +1,28 @@
 # frozen_string_literal: true
 
 module Astronoby
-  module Events
-    class TwilightEvents
-      TWILIGHTS = [
-        CIVIL = :civil,
-        NAUTICAL = :nautical,
-        ASTRONOMICAL = :astronomical
-      ].freeze
-
-      TWILIGHT_ANGLES = {
-        CIVIL => Angle.from_degrees(96),
-        NAUTICAL => Angle.from_degrees(102),
-        ASTRONOMICAL => Angle.from_degrees(108)
-      }.freeze
-
-      PERIODS_OF_THE_DAY = [
-        MORNING = :morning,
-        EVENING = :evening
-      ].freeze
-
-      attr_reader :morning_civil_twilight_time,
-        :evening_civil_twilight_time,
-        :morning_nautical_twilight_time,
-        :evening_nautical_twilight_time,
-        :morning_astronomical_twilight_time,
-        :evening_astronomical_twilight_time
-
-      def initialize(observer:, sun:)
-        @observer = observer
-        @sun = sun
-        PERIODS_OF_THE_DAY.each do |period_of_the_day|
-          TWILIGHT_ANGLES.each do |twilight, _|
-            zenith_angle = TWILIGHT_ANGLES[twilight]
-            instance_variable_set(
-              :"@#{period_of_the_day}_#{twilight}_twilight_time",
-              compute(period_of_the_day, zenith_angle)
-            )
-          end
-        end
-      end
-
-      # @param period_of_the_day [Symbol] :morning or :evening
-      # @param zenith_angle [Angle] The zenith angle of the twilight
-      def time_for_zenith_angle(period_of_the_day:, zenith_angle:)
-        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}"
-        end
-
-        compute(period_of_the_day, zenith_angle)
-      end
-
-      private
-
-      # Source:
-      #  Title: Practical Astronomy with your Calculator or Spreadsheet
-      #  Authors: Peter Duffett-Smith and Jonathan Zwart
-      #  Edition: Cambridge University Press
-      #  Chapter: 50 - Twilight
-      def compute(period_of_the_day, zenith_angle)
-        period_time = if period_of_the_day == MORNING
-          observation_events.rising_time
-        else
-          observation_events.setting_time
-        end
-
-        hour_angle_at_period = equatorial_coordinates_at_midday
-          .compute_hour_angle(time: period_time, longitude: @observer.longitude)
-
-        term1 = zenith_angle.cos -
-          @observer.latitude.sin *
-            @equatorial_coordinates_at_midday.declination.sin
-        term2 = @observer.latitude.cos *
-          equatorial_coordinates_at_midday.declination.cos
-        hour_angle_ratio_at_twilight = term1 / term2
-
-        return unless hour_angle_ratio_at_twilight.between?(-1, 1)
-
-        hour_angle_at_twilight = Angle.acos(hour_angle_ratio_at_twilight)
-        time_sign = -1
-
-        if period_of_the_day == MORNING
-          hour_angle_at_twilight = Angle.from_degrees(
-            Constants::DEGREES_PER_CIRCLE - hour_angle_at_twilight.degrees
-          )
-          time_sign = 1
-        end
-
-        twilight_in_hours =
-          time_sign * (hour_angle_at_twilight - hour_angle_at_period).hours *
-          GreenwichSiderealTime::SIDEREAL_MINUTE_IN_UT_MINUTE
-        twilight_in_seconds = time_sign *
-          twilight_in_hours *
-          Constants::SECONDS_PER_HOUR
-
-        (period_time + twilight_in_seconds).round
-      end
-
-      def observation_events
-        @observation_events ||= @sun.observation_events(observer: @observer)
-      end
-
-      def midday
-        date = @sun.time.to_date
-        Time.utc(date.year, date.month, date.day, 12)
-      end
-
-      def sun_at_midday
-        Sun.new(time: midday)
-      end
-
-      def equatorial_coordinates_at_midday
-        @equatorial_coordinates_at_midday ||= sun_at_midday
-          .apparent_ecliptic_coordinates
-          .to_apparent_equatorial(epoch: Epoch.from_time(midday))
-      end
+  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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Astronoby
+  # Represents a specific instant in time using Terrestrial Time (TT) as its
+  # internal representation. This class provides conversions between different
+  # time scales commonly used in astronomy:
+  # - Terrestrial Time (TT)
+  # - International Atomic Time (TAI)
+  # - Universal Time Coordinated (UTC)
+  # - Greenwich Mean Sidereal Time (GMST)
+  #
+  # @example Create an instant from the current time
+  #   instant = Astronoby::Instant.from_time(Time.now)
+  #   instant.tai  # Get International Atomic Time
+  #
+  # @example Create an instant from Terrestrial Time
+  #   instant = Astronoby::Instant.from_terrestrial_time(2460000.5)
+  #
+  class Instant
+    include Comparable
+
+    # 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
+      #
+      # @param terrestrial_time [Numeric] the Terrestrial Time as a Julian Date
+      # @return [Astronoby::Instant] a new Instant object
+      # @raise [Astronoby::UnsupportedFormatError] if terrestrial_time is not
+      #   numeric
+      def from_terrestrial_time(terrestrial_time)
+        new(terrestrial_time)
+      end
+
+      # Creates a new Instant from a Time object
+      #
+      # @param time [Time] a Time object to convert
+      # @return [Astronoby::Instant] a new Instant object
+      def from_time(time)
+        delta_t = Util::Time.terrestrial_universal_time_delta(time)
+        terrestrial_time = time.utc.to_datetime.ajd +
+          Rational(delta_t, Constants::SECONDS_PER_DAY)
+        from_terrestrial_time(terrestrial_time)
+      end
+
+      # Creates a new Instant from a Julian Date in UTC
+      #
+      # @param julian_date [Numeric] the Julian Date in UTC
+      # @return [Astronoby::Instant] a new Instant object
+      def from_utc_julian_date(julian_date)
+        delta_t = Util::Time.terrestrial_universal_time_delta(julian_date)
+        terrestrial_time = julian_date +
+          Rational(delta_t, Constants::SECONDS_PER_DAY)
+        from_terrestrial_time(terrestrial_time)
+      end
+    end
+
+    attr_reader :terrestrial_time
+    alias_method :tt, :terrestrial_time
+    alias_method :julian_date, :terrestrial_time
+
+    # Initialize a new Instant
+    #
+    # @param terrestrial_time [Numeric] the Terrestrial Time as Julian Date
+    # @raise [Astronoby::UnsupportedFormatError] if terrestrial_time is not
+    #   numeric
+    def initialize(terrestrial_time)
+      unless terrestrial_time.is_a?(Numeric)
+        raise UnsupportedFormatError, "terrestrial_time must be a Numeric"
+      end
+
+      @terrestrial_time = terrestrial_time
+      freeze
+    end
+
+    # Calculate the time difference between two Instant objects
+    #
+    # @param other [Astronoby::Instant] another Instant to compare with
+    # @return [Numeric] the difference in days
+    def diff(other)
+      @terrestrial_time - other.terrestrial_time
+    end
+
+    # Convert to DateTime (UTC)
+    #
+    # @return [DateTime] the UTC time as DateTime
+    def to_datetime
+      DateTime.jd(
+        @terrestrial_time -
+          Rational(delta_t / Constants::SECONDS_PER_DAY) +
+          DATETIME_JD_EPOCH_ADJUSTMENT
+      )
+    end
+
+    # Convert to Date (UTC)
+    #
+    # @return [Date] the UTC date
+    def to_date
+      to_datetime.to_date
+    end
+
+    # Convert to Time (UTC)
+    #
+    # @return [Time] the UTC time
+    def to_time
+      to_datetime.to_time.utc
+    end
+
+    # Get the ΔT (Delta T) value for this instant
+    # ΔT is the difference between TT and UT1
+    #
+    # @return [Numeric] Delta T in seconds
+    def delta_t
+      Util::Time.terrestrial_universal_time_delta(@terrestrial_time)
+    end
+
+    # Get the Greenwich Mean Sidereal Time
+    #
+    # @return [Numeric] the sidereal time in radians
+    def gmst
+      GreenwichSiderealTime.from_utc(to_time).time
+    end
+
+    # Get the International Atomic Time (TAI)
+    #
+    # @return [Numeric] TAI as Julian Date
+    def tai
+      @terrestrial_time -
+        Rational(Constants::TAI_TT_OFFSET, Constants::SECONDS_PER_DAY)
+    end
+
+    # Get the Barycentric Dynamical Time (TDB)
+    # Note: Currently approximated as equal to TT
+    #
+    # @return [Numeric] TDB as Julian Date
+    def tdb
+      # This is technically false, there is a slight difference between TT and
+      # TDB. However, this difference is so small that currenly Astronoby
+      # doesn't support it and consider they are the same value.
+      @terrestrial_time
+    end
+
+    # Get the offset between TT and UTC for this instant
+    #
+    # @return [Numeric] the offset in days
+    def utc_offset
+      @terrestrial_time - to_time.utc.to_datetime.ajd
+    end
+
+    # Calculate hash value for the instant
+    #
+    # @return [Integer] hash value
+    def hash
+      [@terrestrial_time, self.class].hash
+    end
+
+    # Compare this instant with another
+    #
+    # @param other [Astronoby::Instant] another instant to compare with
+    # @return [Integer, nil] -1, 0, 1 for less than, equal to, greater than;
+    #   nil if other is not an Instant
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      @terrestrial_time <=> other.terrestrial_time
+    end
+    alias_method :eql?, :==
+  end
+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

@@ -1,32 +1,43 @@
 # frozen_string_literal: true
 
-require "date"
+# TODO: This needs to be improved by receiving an instant instead of an Epoch
+# as these coefficients work with TT (Terrestrial Time).
 
 module Astronoby
   class MeanObliquity
     # Source:
     #  IAU resolution in 2006 in favor of the P03 astronomical model
-    #  The Astronomical Almanac for 2010
+    #  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 = (epoch - EPOCH_OF_REFERENCE) / Constants::DAYS_PER_JULIAN_CENTURY
+      t = Rational(
+        instant.julian_date - EPOCH_OF_REFERENCE,
+        Constants::DAYS_PER_JULIAN_CENTURY
+      )
+
+      epsilon0 = obliquity_of_reference_in_arcseconds
+      c1 = -46.836769
+      c2 = -0.0001831
+      c3 = 0.00200340
+      c4 = -0.000000576
+      c5 = -0.0000000434
 
-      Angle.from_degrees(
-        obliquity_of_reference.degrees - (
-          46.815 * t -
-          0.0006 * t * t +
-          0.00181 * t * t * t
-        ) / Constants::SECONDS_PER_DEGREE
+      Angle.from_degree_arcseconds(
+        epsilon0 + t * (c1 + t * (c2 + t * (c3 + t * (c4 + t * c5))))
       )
     end
 
     def self.obliquity_of_reference
-      Angle.from_dms(23, 26, 21.45)
+      Angle.from_degree_arcseconds(obliquity_of_reference_in_arcseconds)
+    end
+
+    def self.obliquity_of_reference_in_arcseconds
+      84381.406
     end
   end
 end