astronoby 0.6.0 → 0.7.0

data/lib/astronoby/events/rise_transit_set_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RiseTransitSetEvent
+    attr_reader :rising_time, :transit_time, :setting_time
+
+    def initialize(rising, transit, setting)
+      @rising_time = rising
+      @transit_time = transit
+      @setting_time = setting
+    end
+  end
+end

data/lib/astronoby/events/rise_transit_set_events.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class RiseTransitSetEvents
+    attr_reader :rising_times, :transit_times, :setting_times
+
+    def initialize(risings, transits, settings)
+      @rising_times = risings
+      @transit_times = transits
+      @setting_times = settings
+    end
+  end
+end

data/lib/astronoby/events/twilight_calculator.rb

@@ -0,0 +1,166 @@
+# 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)
+      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
+      )
+
+      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
+      )
+
+      morning_astronomical = compute_twilight_time(
+        MORNING,
+        TWILIGHT_ANGLES[ASTRONOMICAL],
+        observation_events,
+        equatorial_coordinates
+      )
+
+      evening_astronomical = compute_twilight_time(
+        EVENING,
+        TWILIGHT_ANGLES[ASTRONOMICAL],
+        observation_events,
+        equatorial_coordinates
+      )
+
+      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
+      )
+    end
+
+    def time_for_zenith_angle(date:, 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
+
+      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
+
+      compute_twilight_time(
+        period_of_the_day,
+        zenith_angle,
+        observation_events,
+        equatorial_coordinates
+      )
+    end
+
+    private
+
+    def create_midday_instant(date)
+      time = Time.utc(date.year, date.month, date.day, 12)
+      Instant.from_time(time)
+    end
+
+    def get_observation_events(date)
+      Astronoby::RiseTransitSetCalculator.new(
+        body: Sun,
+        observer: @observer,
+        ephem: @ephem
+      ).event_on(date)
+    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
+
+      # 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/instant.rb

@@ -0,0 +1,171 @@
+# 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
+
+    JULIAN_DAY_NUMBER_OFFSET = 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) +
+          JULIAN_DAY_NUMBER_OFFSET
+      )
+    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/mean_obliquity.rb

@@ -1,12 +1,13 @@
 # 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
     OBLIQUITY_OF_REFERENCE = 23.4392794
@@ -14,19 +15,31 @@ module Astronoby
     def self.for_epoch(epoch)
       return obliquity_of_reference if epoch == EPOCH_OF_REFERENCE
 
-      t = (epoch - EPOCH_OF_REFERENCE) / Constants::DAYS_PER_JULIAN_CENTURY
+      t = Rational(
+        (epoch - EPOCH_OF_REFERENCE),
+        Constants::DAYS_PER_JULIAN_CENTURY
+      )
+
+      epsilon0 = obliquity_of_reference_in_milliarcseconds
+      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_dms(
+        0,
+        0,
+        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_dms(0, 0, obliquity_of_reference_in_milliarcseconds)
+    end
+
+    def self.obliquity_of_reference_in_milliarcseconds
+      84381.406
     end
   end
 end