zmanim 0.1.0

data/lib/zmanim/util/hebrew_numeric_formatter.rb

@@ -0,0 +1,67 @@
+# encoding: UTF-8
+module Zmanim::Util
+  module HebrewNumericFormatter
+    attr_accessor :use_geresh_gershayim
+
+    GERESH = '׳'
+    GERSHAYIM = '״'
+
+    def initialize
+      @use_geresh_gershayim = true
+    end
+
+    def format_hebrew_number(number, include_thousands=false)
+      raise ArgumentError unless (0..9999).include?(number)
+      descriptors = {efes: 'אפס', alafim: 'אלפים'}
+      one_glyphs = [''] + %w(א ב ג ד ה ו ז ח ט)
+      ten_glyphs = [''] + %w(י כ ל מ נ ס ע פ צ)
+      final_ten_glyphs = [''] + %w(י ך ל ם ן ס ע ף ץ)
+      hundred_glyphs = [''] + %w(ק ר ש ת תק תר תש תת תתק)
+      tav_taz_glyphs = %w(טו טז)
+
+      return descriptors[:efes] if number == 0
+
+      thousands, remainder = number.divmod(1000)
+      hundreds, remainder = remainder.divmod(100)
+      tens, ones = remainder.divmod(10)
+
+      str = ''
+
+      if number % 1000 == 0
+        return add_geresh(one_glyphs[thousands]) + ' ' + descriptors[:alafim]
+      elsif thousands > 0 && include_thousands
+        str += add_geresh(one_glyphs[thousands]) + ' '
+      end
+
+      str += hundred_glyphs[hundreds]
+      if tens == 1 and ones == 5
+        str += tav_taz_glyphs[0]
+      elsif tens == 1 and ones == 6
+        str += tav_taz_glyphs[1]
+      else
+        if ones == 0 && hundreds != 0
+          str += final_ten_glyphs[tens]
+        else
+          str += ten_glyphs[tens]
+        end
+        str += one_glyphs[ones]
+      end
+
+      if use_geresh_gershayim
+        if [hundreds, tens, ones].select{|p| p > 0}.count == 1 && hundreds <= 4
+          str += GERESH
+        else
+          str.insert(-2, GERSHAYIM)
+        end
+      end
+
+      str
+    end
+
+    private
+
+    def add_geresh(str)
+      use_geresh_gershayim ? str + GERESH : str
+    end
+  end
+end

data/lib/zmanim/util/math_helper.rb

@@ -0,0 +1,14 @@
+module Zmanim::Util
+  module MathHelper
+    DEGREE_RADIAN_RATIO = 180.0/Math::PI
+    refine Numeric do
+      def to_radians
+        self / DEGREE_RADIAN_RATIO
+      end
+
+      def to_degrees
+        self * DEGREE_RADIAN_RATIO
+      end
+    end
+  end
+end

data/lib/zmanim/util/noaa_calculator.rb

@@ -0,0 +1,180 @@
+require_relative 'astronomical_calculations'
+require_relative 'math_helper'
+
+module Zmanim::Util
+  class NOAACalculator
+    include AstronomicalCalculations
+    using Zmanim::Util::MathHelper
+
+    JULIAN_DAY_JAN_1_2000 = 2451545.0
+    JULIAN_DAYS_PER_CENTURY = 36525.0
+
+    def name
+      'US National Oceanic and Atmospheric Administration Algorithm'
+    end
+
+    def utc_sunrise(date, geo_location, zenith, adjust_for_elevation: false)
+      utc_sun_position(date, geo_location, zenith, adjust_for_elevation, :sunrise)
+    rescue Math::DomainError
+      nil
+    end
+
+    def utc_sunset(date, geo_location, zenith, adjust_for_elevation: false)
+      utc_sun_position(date, geo_location, zenith, adjust_for_elevation, :sunset)
+    rescue Math::DomainError
+      nil
+    end
+
+    private
+
+    def julian_centuries_from_julian_day(julian_day)
+      (julian_day - JULIAN_DAY_JAN_1_2000) / JULIAN_DAYS_PER_CENTURY
+    end
+
+    def julian_day_from_julian_centuries(julian_centuries)
+      (julian_centuries * JULIAN_DAYS_PER_CENTURY) + JULIAN_DAY_JAN_1_2000
+    end
+
+    def utc_sun_position(date, geo_location, zenith, adjust_for_elevation, mode)
+      elevation = adjust_for_elevation ? geo_location.elevation : 0.0
+      adjusted_zenith = adjusted_zenith(zenith, elevation)
+      utc_time = calculate_utc_sun_position(date.ajd,
+                                            geo_location.latitude,
+                                            -geo_location.longitude,
+                                            adjusted_zenith,
+                                             mode) # in minutes
+      utc_time /= 60.0   # in hours
+      utc_time % 24      # normalized (0...24)
+    end
+
+    def calculate_utc_sun_position(julian_day, latitude, longitude, zenith, mode)
+      julian_centuries = julian_centuries_from_julian_day(julian_day)
+
+      # first pass using solar noon
+      noonmin = solar_noon_utc(julian_centuries, longitude)
+      tnoon = julian_centuries_from_julian_day(julian_day + (noonmin / 1440.0))
+      first_pass = approximate_utc_sun_position(tnoon, latitude, longitude, zenith, mode)
+
+      # refine using output of first pass
+      trefinement = julian_centuries_from_julian_day(julian_day + (first_pass / 1440.0))
+      approximate_utc_sun_position(trefinement, latitude, longitude, zenith, mode)
+    end
+
+    def approximate_utc_sun_position(approx_julian_centuries, latitude, longitude, zenith, mode)
+      eq_time = equation_of_time(approx_julian_centuries)
+      solar_dec = solar_declination(approx_julian_centuries)
+      hour_angle = sun_hour_angle_at_horizon(latitude, solar_dec, zenith, mode)
+
+      delta = longitude - hour_angle.to_degrees
+      time_delta = delta * 4.0
+      720 + time_delta - eq_time
+    end
+
+    def sun_hour_angle_at_horizon(latitude, solar_dec, zenith, mode)
+      lat_r = latitude.to_radians
+      solar_dec_r = solar_dec.to_radians
+      zenith_r = zenith.to_radians
+
+      hour_angle = Math.acos(
+          (Math.cos(zenith_r) / (Math.cos(lat_r) * Math.cos(solar_dec_r))) -
+              (Math.tan(lat_r) * Math.tan(solar_dec_r))
+      )
+
+      hour_angle *= -1 if mode == :sunset
+      hour_angle # in radians
+    end
+
+    def solar_declination(julian_centuries)
+      correction = obliquity_correction(julian_centuries).to_radians
+      lambda = sun_apparent_longitude(julian_centuries).to_radians
+      sint = Math.sin(correction) * Math.sin(lambda)
+      Math.asin(sint).to_degrees    # in degrees
+    end
+
+    def sun_apparent_longitude(julian_centuries)
+      true_longitude = sun_true_longitude(julian_centuries)
+      omega = 125.04 - (1934.136 * julian_centuries)
+      true_longitude - 0.00569 - (0.00478 * Math.sin(omega.to_radians))  # in degrees
+    end
+
+    def sun_true_longitude(julian_centuries)
+      sgml = sun_geometric_mean_longitude(julian_centuries)
+      center = sun_equation_of_center(julian_centuries)
+      sgml + center       # in degrees
+    end
+
+    def sun_equation_of_center(julian_centuries)
+      mrad = sun_geometric_mean_anomaly(julian_centuries).to_radians
+      sinm = Math.sin(mrad)
+      sin2m = Math.sin(2 * mrad)
+      sin3m = Math.sin(3 * mrad)
+
+      (sinm * (1.914602 - (julian_centuries * (0.004817 + (0.000014 * julian_centuries))))) +
+      (sin2m * (0.019993 - (0.000101 * julian_centuries))) +
+      (sin3m * 0.000289)  # in degrees
+    end
+
+    def solar_noon_utc(julian_centuries, longitude)
+      century_start = julian_day_from_julian_centuries(julian_centuries)
+
+      # first pass to yield approximate solar noon
+      approx_tnoon = julian_centuries_from_julian_day(century_start + (longitude / 360.0))
+      approx_eq_time = equation_of_time(approx_tnoon)
+      approx_sol_noon = 720 + (longitude * 4) - approx_eq_time
+
+      # refinement using output of first pass
+      tnoon = julian_centuries_from_julian_day(century_start - 0.5 + (approx_sol_noon / 1440.0))
+      eq_time = equation_of_time(tnoon)
+      720 + (longitude * 4) - eq_time
+    end
+
+    def equation_of_time(julian_centuries)
+      epsilon = obliquity_correction(julian_centuries).to_radians
+      sgml = sun_geometric_mean_longitude(julian_centuries).to_radians
+      sgma = sun_geometric_mean_anomaly(julian_centuries).to_radians
+      eoe = earth_orbit_eccentricity(julian_centuries)
+
+      y = Math.tan(epsilon / 2.0)
+      y *= y
+
+      sin2l0 = Math.sin(2.0 * sgml)
+      sin4l0 = Math.sin(4.0 * sgml)
+      cos2l0 = Math.cos(2.0 * sgml)
+      sinm = Math.sin(sgma)
+      sin2m = Math.sin( 2.0 * sgma)
+
+      eq_time = (y * sin2l0) - (2.0 * eoe * sinm) + (4.0 * eoe * y * sinm * cos2l0) - (0.5 * y * y * sin4l0) - (1.25 * eoe * eoe * sin2m)
+      eq_time.to_degrees * 4.0  # minutes of time
+    end
+
+
+    def earth_orbit_eccentricity(julian_centuries)
+      0.016708634 - (julian_centuries * (0.000042037 + (0.0000001267 * julian_centuries)))  # unitless
+    end
+
+    def sun_geometric_mean_anomaly(julian_centuries)
+      anomaly = 357.52911 + (julian_centuries * (35999.05029 - (0.0001537 * julian_centuries)))   # in degrees
+
+      anomaly % 360         # normalized (0...360)
+    end
+
+    def sun_geometric_mean_longitude(julian_centuries)
+      longitude = 280.46646 + (julian_centuries * (36000.76983 + (0.0003032 * julian_centuries)))  # in degrees
+
+      longitude % 360       # normalized (0...360)
+    end
+
+    def obliquity_correction(julian_centuries)
+      obliquity_of_ecliptic = mean_obliquity_of_ecliptic(julian_centuries)
+
+      omega = 125.04 - (1934.136 * julian_centuries)
+      correction = obliquity_of_ecliptic + (0.00256 * Math.cos(omega.to_radians))
+      correction % 360     # normalized (0...360)
+    end
+
+    def mean_obliquity_of_ecliptic(julian_centuries)
+      seconds = 21.448 - (julian_centuries * (46.8150 + (julian_centuries * (0.00059 - (julian_centuries * 0.001813)))))
+      23.0 + ((26.0 + (seconds / 60)) / 60.0)  # in degrees
+    end
+  end
+end

data/lib/zmanim/util/sun_times_calculator.rb

@@ -0,0 +1,123 @@
+require_relative 'astronomical_calculations'
+require_relative 'math_helper'
+
+module Zmanim::Util
+  class SunTimesCalculator
+    include AstronomicalCalculations
+    using Zmanim::Util::MathHelper
+
+    def name
+      'US Naval Almanac Algorithm'
+    end
+
+    def utc_sunrise(date, geo_location, zenith, adjust_for_elevation: false)
+      utc_sun_position(date, geo_location, zenith, adjust_for_elevation, :sunrise)
+    rescue Math::DomainError
+      nil
+    end
+
+    def utc_sunset(date, geo_location, zenith, adjust_for_elevation: false)
+      utc_sun_position(date, geo_location, zenith, adjust_for_elevation, :sunset)
+    rescue Math::DomainError
+      nil
+    end
+
+    private
+
+    DEG_PER_HOUR = 360.0 / 24.0
+
+    def sin_deg(deg)
+      Math.sin(deg.to_radians)
+    end
+
+    def cos_deg(deg)
+      Math.cos(deg.to_radians)
+    end
+
+    def tan_deg(deg)
+      Math.tan(deg.to_radians)
+    end
+
+    def acos_deg(x)
+      Math.acos(x).to_degrees
+    end
+
+    def asin_deg(x)
+      Math.asin(x).to_degrees
+    end
+
+    def atan_deg(x)
+      Math.atan(x).to_degrees
+    end
+
+    def utc_sun_position(date, geo_location, zenith, adjust_for_elevation, mode)
+      elevation = adjust_for_elevation ? geo_location.elevation : 0
+      adjusted_zenith = adjusted_zenith(zenith, elevation)
+      utc_time = calculate_utc_sun_position(date,
+                                            geo_location.latitude,
+                                            geo_location.longitude,
+                                            adjusted_zenith,
+                                            mode) # in hours
+      utc_time % 24    # normalized (0...24)
+    end
+
+    def calculate_utc_sun_position(date, latitude, longitude, zenith, mode)
+      day_of_year = date.yday
+      hours_offset = hours_from_meridian(longitude)
+      time_days = approx_time_days(day_of_year, hours_offset, mode)
+
+      mean_anomaly = sun_mean_anomaly(time_days)
+      true_long = sun_true_longitude(mean_anomaly)
+      right_ascension_hours = sun_right_ascension_hours(true_long)
+      cos_local_hour_angle = cos_local_hour_angle(true_long, latitude, zenith)
+
+      local_hour_angle = acos_deg(cos_local_hour_angle)
+      local_hour_angle = 360.0 - local_hour_angle if mode == :sunrise
+
+      local_hour = local_hour_angle / DEG_PER_HOUR
+
+      mean_time = local_mean_time(local_hour, right_ascension_hours, time_days)
+      mean_time - hours_offset
+    end
+
+    def local_mean_time(local_hour, right_ascension_hours, time_days)
+      local_hour + right_ascension_hours - (0.06571 * time_days) - 6.622
+    end
+
+    def cos_local_hour_angle(sun_true_long, latitude, zenith)
+      sin_dec = 0.39782 * sin_deg(sun_true_long)
+      cos_dec = cos_deg(asin_deg(sin_dec))
+      (cos_deg(zenith) - (sin_dec * sin_deg(latitude))) / (cos_dec * cos_deg(latitude))
+    end
+
+    def sun_right_ascension_hours(sun_true_long)
+      ra = atan_deg(0.91764 * tan_deg(sun_true_long))
+      l_quadrant = (sun_true_long / 90.0).floor * 90.0
+      ra_quadrant = (ra / 90.0).floor * 90.0
+      ra += (l_quadrant - ra_quadrant)
+
+      ra / DEG_PER_HOUR    # in hours
+    end
+
+    def sun_true_longitude(sun_mean_anomaly)
+      true_longitude = sun_mean_anomaly +
+          (1.916 * sin_deg(sun_mean_anomaly)) +
+          (0.02 * sin_deg(2 * sun_mean_anomaly)) +
+          282.634
+      true_longitude % 360
+    end
+
+    def sun_mean_anomaly(time_days)
+      (0.9856 * time_days) - 3.289
+    end
+
+    def approx_time_days(day_of_year, hours_offset, mode)
+      mode_offset = mode == :sunrise ? 6.0 : 18.0
+      day_of_year + ((mode_offset - hours_offset) / 24)
+    end
+
+    def hours_from_meridian(longitude)
+      longitude / DEG_PER_HOUR
+    end
+  end
+end

data/lib/zmanim/util/text_helper.rb

@@ -0,0 +1,7 @@
+module Zmanim::Util
+  module TextHelper
+    def titleize(string)
+      string.to_s.gsub(/_/,' ').scan(/\w+/).map{|w| w[0].upcase + w[1..-1]}.join(' ')
+    end
+  end
+end

data/lib/zmanim/util/time_zone_converter.rb

@@ -0,0 +1,20 @@
+module Zmanim::Util
+  class TimeZoneConverter
+    attr_reader :time_zone
+
+    def initialize(time_zone)
+      @time_zone = time_zone
+    end
+
+    # Adjust a DateTime for the provided time zone
+    def modify_offset(time)
+      offset = offset_at(time)
+      time.new_offset(offset/24)
+    end
+
+    # offset in effect for time zone at the given time (in hours)
+    def offset_at(time)
+      time_zone.period_for_utc(time.new_offset(0)).utc_total_offset / (60 * 60).to_f
+    end
+  end
+end

data/lib/zmanim/version.rb

@@ -0,0 +1,3 @@
+module Zmanim
+  VERSION = "0.1.0"
+end

data/lib/zmanim/zmanim_calendar.rb

@@ -0,0 +1,106 @@
+module Zmanim
+  class ZmanimCalendar < AstronomicalCalendar
+    attr_accessor :candle_lighting_offset
+
+    ZENITH_16_POINT_1 = GEOMETRIC_ZENITH + 16.1
+    ZENITH_8_POINT_5 = GEOMETRIC_ZENITH + 8.5
+
+    def initialize(opts={})
+      super
+      @candle_lighting_offset = opts[:candle_lighting_offset] || 18
+    end
+
+    def tzais(opts={degrees: 8.5})
+      degrees, offset = extract_degrees_offset(opts)
+      offset_by_minutes(sunset_offset_by_degrees(GEOMETRIC_ZENITH + degrees), offset)
+    end
+
+    def tzais_72
+      tzais(offset: 72)
+    end
+
+    def alos(opts={degrees: 16.1})
+      degrees, offset = extract_degrees_offset(opts)
+      offset_by_minutes(sunrise_offset_by_degrees(GEOMETRIC_ZENITH + degrees), offset)
+    end
+
+    def alos_72
+      alos(offset: -72)
+    end
+
+    alias_method :chatzos, :sun_transit
+
+    def sof_zman_shma(day_start, day_end)
+      shaos_into_day(day_start, day_end, 3)
+    end
+
+    def sof_zman_shma_gra
+      sof_zman_shma(sea_level_sunrise, sea_level_sunset)
+    end
+
+    def sof_zman_shma_mga
+      sof_zman_shma(alos_72, tzais_72)
+    end
+
+    def candle_lighting
+      offset_by_minutes(sea_level_sunset , -candle_lighting_offset)
+    end
+
+    def sof_zman_tfila(day_start, day_end)
+      shaos_into_day(day_start, day_end, 4)
+    end
+
+    def sof_zman_tfila_gra
+      sof_zman_tfila(sea_level_sunrise, sea_level_sunset)
+    end
+
+    def sof_zman_tfila_mga
+      sof_zman_tfila(alos_72, tzais_72)
+    end
+
+    def mincha_gedola(day_start=sea_level_sunrise, day_end=sea_level_sunset)
+      shaos_into_day(day_start, day_end, 6.5)
+    end
+
+    def mincha_ketana(day_start=sea_level_sunrise, day_end=sea_level_sunset)
+      shaos_into_day(day_start, day_end, 9.5)
+    end
+
+    def plag_hamincha(day_start=sea_level_sunrise, day_end=sea_level_sunset)
+      shaos_into_day(day_start, day_end, 10.75)
+    end
+
+    def shaah_zmanis(day_start, day_end)
+      temporal_hour(day_start, day_end)
+    end
+
+    def shaah_zmanis_gra
+      shaah_zmanis(sea_level_sunrise, sea_level_sunset)
+    end
+
+    def shaah_zmanis_mga
+      shaah_zmanis(alos_72, tzais_72)
+    end
+
+    def shaah_zmanis_by_degrees_and_offset(degrees, offset)
+      opts = {degrees: degrees, offset: offset}
+      shaah_zmanis(alos(opts.merge(offset: -offset)), tzais(opts))
+    end
+
+    private
+
+    def shaos_into_day(day_start, day_end, shaos)
+      return unless shaah_zmanis = temporal_hour(day_start, day_end)
+      offset_by_minutes(day_start, (shaah_zmanis / MINUTE_MILLIS) * shaos)
+    end
+
+    def extract_degrees_offset(opts)
+      [opts[:degrees] || 0.0, opts[:offset] || 0]
+    end
+
+    def offset_by_minutes(time, minutes)
+      return unless time
+      time + (minutes / (60 * 24).to_f)
+    end
+  end
+end