sekki24 1.0.0

data/lib/sekki24/lunar/moon.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "periodic_terms"
+require_relative "../nutation"
+
+module Sekki24
+  module Lunar
+    module Moon
+      J2000 = 2_451_545.0
+      JULIAN_CENTURY = 36_525.0
+      DEGREES_TO_RADIANS = Math::PI / 180.0
+
+      module_function
+
+      def longitude(jde)
+        centuries = (Float(jde) - J2000) / JULIAN_CENTURY
+        arguments = fundamental_arguments(centuries)
+        correction = periodic_correction(arguments, centuries) + additive_correction(arguments, centuries)
+
+        (arguments.fetch(:moon_longitude) + correction + Nutation.longitude(jde)) % 360.0
+      end
+
+      def fundamental_arguments(t)
+        {
+          moon_longitude: 218.3164477 + (481_267.88123421 * t) - (0.0015786 * t**2) +
+            (t**3 / 538_841.0) - (t**4 / 65_194_000.0),
+          elongation: 297.8501921 + (445_267.1114034 * t) - (0.0018819 * t**2) +
+            (t**3 / 545_868.0) - (t**4 / 113_065_000.0),
+          sun_anomaly: 357.5291092 + (35_999.0502909 * t) - (0.0001536 * t**2) +
+            (t**3 / 24_490_000.0),
+          moon_anomaly: 134.9633964 + (477_198.8675055 * t) + (0.0087414 * t**2) +
+            (t**3 / 69_699.0) - (t**4 / 14_712_000.0),
+          latitude_argument: 93.2720950 + (483_202.0175233 * t) - (0.0036539 * t**2) -
+            (t**3 / 3_526_000.0) + (t**4 / 863_310_000.0)
+        }
+      end
+      private_class_method :fundamental_arguments
+
+      def periodic_correction(arguments, centuries)
+        eccentricity = 1.0 - (0.002516 * centuries) - (0.0000074 * centuries**2)
+        sum = PeriodicTerms::LONGITUDE.sum do |d, m, moon_m, f, coefficient|
+          angle = (d * arguments.fetch(:elongation)) + (m * arguments.fetch(:sun_anomaly)) +
+            (moon_m * arguments.fetch(:moon_anomaly)) + (f * arguments.fetch(:latitude_argument))
+          coefficient * eccentricity**m.abs * sin_degrees(angle)
+        end
+        sum / 1_000_000.0
+      end
+      private_class_method :periodic_correction
+
+      def additive_correction(arguments, centuries)
+        a1 = 119.75 + (131.849 * centuries)
+        a2 = 53.09 + (479_264.290 * centuries)
+        correction = (3_958 * sin_degrees(a1)) +
+          (1_962 * sin_degrees(arguments.fetch(:moon_longitude) - arguments.fetch(:latitude_argument))) +
+          (318 * sin_degrees(a2))
+        correction / 1_000_000.0
+      end
+      private_class_method :additive_correction
+
+      def sin_degrees(angle)
+        Math.sin(angle * DEGREES_TO_RADIANS)
+      end
+      private_class_method :sin_degrees
+    end
+  end
+end

data/lib/sekki24/lunar/periodic_terms.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sekki24
+  module Lunar
+    module PeriodicTerms
+      # D, M, M', F and longitude coefficient in millionths of a degree.
+      LONGITUDE = [
+        [0, 0, 1, 0, 6_288_774], [2, 0, -1, 0, 1_274_027], [2, 0, 0, 0, 658_314],
+        [0, 0, 2, 0, 213_618], [0, 1, 0, 0, -185_116], [0, 0, 0, 2, -114_332],
+        [2, 0, -2, 0, 58_793], [2, -1, -1, 0, 57_066], [2, 0, 1, 0, 53_322],
+        [2, -1, 0, 0, 45_758], [0, 1, -1, 0, -40_923], [1, 0, 0, 0, -34_720],
+        [0, 1, 1, 0, -30_383], [2, 0, 0, -2, 15_327], [0, 0, 1, 2, -12_528],
+        [0, 0, 1, -2, 10_980], [4, 0, -1, 0, 10_675], [0, 0, 3, 0, 10_034],
+        [4, 0, -2, 0, 8_548], [2, 1, -1, 0, -7_888], [2, 1, 0, 0, -6_766],
+        [1, 0, -1, 0, -5_163], [1, 1, 0, 0, 4_987], [2, -1, 1, 0, 4_036],
+        [2, 0, 2, 0, 3_994], [4, 0, 0, 0, 3_861], [2, 0, -3, 0, 3_665],
+        [0, 1, -2, 0, -2_689], [2, 0, -1, 2, -2_602], [2, -1, -2, 0, 2_390],
+        [1, 0, 1, 0, -2_348], [2, -2, 0, 0, 2_236], [0, 1, 2, 0, -2_120],
+        [0, 2, 0, 0, -2_069], [2, -2, -1, 0, 2_048], [2, 0, 1, -2, -1_773],
+        [2, 0, 0, 2, -1_595], [4, -1, -1, 0, 1_215], [0, 0, 2, 2, -1_110],
+        [3, 0, -1, 0, -892], [2, 1, 1, 0, -810], [4, -1, -2, 0, 759],
+        [0, 2, -1, 0, -713], [2, 2, -1, 0, -700], [2, 1, -2, 0, 691],
+        [2, -1, 0, -2, 596], [4, 0, 1, 0, 549], [0, 0, 4, 0, 537],
+        [4, -1, 0, 0, 520], [1, 0, -2, 0, -487], [2, 1, 0, -2, -399],
+        [0, 0, 2, -2, -381], [1, 1, 1, 0, 351], [3, 0, -2, 0, -340],
+        [4, 0, -3, 0, 330], [2, -1, 2, 0, 327], [0, 2, 1, 0, -323],
+        [1, 1, -1, 0, 299], [2, 0, 3, 0, 294]
+      ].map(&:freeze).freeze
+    end
+  end
+end

data/lib/sekki24/lunar/phase_finder.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "moon"
+
+module Sekki24
+  module Lunar
+    module PhaseFinder
+      MEAN_NEW_MOON_EPOCH = 2_451_550.09765
+      SYNODIC_MONTH = 29.530588853
+      DERIVATIVE_HALF_WINDOW = 1.0 / 24.0
+      ANGULAR_TOLERANCE = 1e-7
+      NEWTON_ATTEMPTS = 8
+
+      @cache_mutex = Mutex.new
+      @root_cache = {}
+      @year_cache = {}
+
+      class << self
+        def new_moons(year, tz:)
+          calendar_year = validate_year(year)
+          new_moons_for_calendar(calendar_year, tz: tz)
+        end
+
+        def new_moons_for_calendar(calendar_year, tz:)
+          cache_key = [calendar_year, TimeScale.timezone_key(tz)].freeze
+          cached = @cache_mutex.synchronize { @year_cache[cache_key] }
+          return cached if cached
+
+          roots = roots_near_year(calendar_year).filter_map do |time|
+            local = TimeScale.localize(time, tz)
+            local.freeze if local.year == calendar_year
+          end.freeze
+          @cache_mutex.synchronize { @year_cache[cache_key] ||= roots }
+        end
+
+        def new_moon_before(time)
+          raise TypeError, "expected Time, got #{time.class}" unless time.is_a?(Time)
+
+          jde = TimeScale.utc_to_jde(time)
+          lunation = ((jde - MEAN_NEW_MOON_EPOCH) / SYNODIC_MONTH).floor
+          root = root_for(lunation)
+          root > time ? root_for(lunation - 1) : root
+        end
+
+        def new_moon_after(time)
+          raise TypeError, "expected Time, got #{time.class}" unless time.is_a?(Time)
+
+          jde = TimeScale.utc_to_jde(time)
+          lunation = ((jde - MEAN_NEW_MOON_EPOCH) / SYNODIC_MONTH).ceil
+          root = root_for(lunation)
+          root <= time ? root_for(lunation + 1) : root
+        end
+
+        def clear_cache!
+          @cache_mutex.synchronize do
+            @root_cache.clear
+            @year_cache.clear
+          end
+        end
+
+        private
+
+        def roots_near_year(year)
+          start_jde = TimeScale.utc_to_jde(Time.utc(year, 1, 1))
+          end_jde = TimeScale.utc_to_jde(Time.utc(year + 1, 1, 1))
+          first = ((start_jde - MEAN_NEW_MOON_EPOCH) / SYNODIC_MONTH).floor - 2
+          last = ((end_jde - MEAN_NEW_MOON_EPOCH) / SYNODIC_MONTH).ceil + 2
+          (first..last).map { |lunation| root_for(lunation) }
+        end
+
+        def root_for(lunation)
+          cached = @cache_mutex.synchronize { @root_cache[lunation] }
+          return cached if cached
+
+          estimate = MEAN_NEW_MOON_EPOCH + (SYNODIC_MONTH * lunation)
+          utc = TimeScale.jde_to_utc(solve(estimate)).freeze
+          @cache_mutex.synchronize { @root_cache[lunation] ||= utc }
+        end
+
+        def solve(estimate)
+          jde = estimate
+          NEWTON_ATTEMPTS.times do
+            error = phase_error(jde)
+            return jde if error.abs < ANGULAR_TOLERANCE
+
+            derivative = numerical_derivative(jde)
+            break unless derivative.finite? && derivative.positive?
+
+            step = error / derivative
+            break if step.abs > 2.0
+
+            jde -= step
+          end
+          bisect(estimate - 2.0, estimate + 2.0)
+        end
+
+        def numerical_derivative(jde)
+          before = phase_error(jde - DERIVATIVE_HALF_WINDOW)
+          after = phase_error(jde + DERIVATIVE_HALF_WINDOW)
+          signed_difference(after, before) / (2.0 * DERIVATIVE_HALF_WINDOW)
+        end
+
+        def bisect(lower, upper)
+          lower_error = phase_error(lower)
+          80.times do
+            midpoint = (lower + upper) / 2.0
+            midpoint_error = phase_error(midpoint)
+            return midpoint if midpoint_error.abs < ANGULAR_TOLERANCE
+
+            if lower_error * midpoint_error <= 0.0
+              upper = midpoint
+            else
+              lower = midpoint
+              lower_error = midpoint_error
+            end
+          end
+          (lower + upper) / 2.0
+        end
+
+        def phase_error(jde)
+          signed_difference(Moon.longitude(jde), Solar::Precise.longitude(jde))
+        end
+
+        def signed_difference(left, right)
+          ((left - right + 180.0) % 360.0) - 180.0
+        end
+
+        def validate_year(year)
+          value = Integer(year)
+          return value if (MIN_YEAR..MAX_YEAR).cover?(value)
+
+          raise RangeError, "year must be between #{MIN_YEAR} and #{MAX_YEAR}"
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "year must be an Integer between #{MIN_YEAR} and #{MAX_YEAR}"
+        end
+      end
+    end
+  end
+
+  class << self
+    def new_moons(year, tz: DEFAULT_TIMEZONE)
+      Lunar::PhaseFinder.new_moons(year, tz: tz)
+    end
+
+    def new_moon_before(time = Time.now)
+      Lunar::PhaseFinder.new_moon_before(time)
+    end
+
+    def new_moon_after(time = Time.now)
+      Lunar::PhaseFinder.new_moon_after(time)
+    end
+
+    def moon_longitude(time)
+      Lunar::Moon.longitude(TimeScale.utc_to_jde(time))
+    end
+  end
+end

data/lib/sekki24/lunisolar/calendar.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "month"
+require_relative "date"
+require_relative "month_builder"
+
+module Sekki24
+  module Lunisolar
+    module Calendar
+      LEAP_MONTH_RULE = :winter_solstice_priority
+      MIN_LUNISOLAR_YEAR = MIN_YEAR - 1
+      MAX_LUNISOLAR_YEAR = MAX_YEAR
+      @cache_mutex = Mutex.new
+      @range_cache = {}
+      @year_cache = {}
+
+      class << self
+        def convert(value, tz:)
+          local_date = local_date(value, tz)
+          validate_gregorian_year(local_date.year)
+          month = generated_range(local_date.year, tz).find { |entry| entry.include?(local_date) }
+          raise Error, "could not assign lunisolar month for #{local_date}" unless month
+
+          Date.new(
+            year: month.year,
+            month: month.month,
+            day: (local_date - month.start_date).to_i + 1,
+            leap: month.leap?,
+            gregorian_date: local_date,
+            month_length: month.length
+          )
+        end
+
+        def year(year, tz:)
+          lunar_year = validate_lunar_year(year)
+          cache_key = [lunar_year, TimeScale.timezone_key(tz)].freeze
+          cached = @cache_mutex.synchronize { @year_cache[cache_key] }
+          return cached if cached
+
+          months = generated_range(lunar_year, tz).select { |month| month.year == lunar_year }.freeze
+          unless [12, 13].include?(months.length)
+            raise Error, "expected 12 or 13 lunisolar months for #{lunar_year}, got #{months.length}"
+          end
+          @cache_mutex.synchronize { @year_cache[cache_key] ||= months }
+        end
+
+        def to_gregorian(year, month, day, leap:, tz:)
+          lunar_year = validate_lunar_year(year)
+          month_number = Integer(month)
+          day_number = Integer(day)
+          raise ArgumentError, "leap must be true or false" unless [true, false].include?(leap)
+          unless (1..12).cover?(month_number)
+            raise ArgumentError, "lunar month must be between 1 and 12"
+          end
+
+          target = self.year(lunar_year, tz: tz).find do |entry|
+            entry.month == month_number && entry.leap? == leap
+          end
+          raise ArgumentError, "lunisolar month does not exist" unless target
+          unless (1..target.length).cover?(day_number)
+            raise ArgumentError, "lunar day must be between 1 and #{target.length}"
+          end
+
+          result = target.start_date + day_number - 1
+          validate_gregorian_year(result.year)
+          result
+        rescue TypeError
+          raise ArgumentError, "lunar month and day must be Integers"
+        end
+
+        def clear_cache!
+          @cache_mutex.synchronize do
+            @range_cache.clear
+            @year_cache.clear
+          end
+          MonthBuilder.clear_cache!
+        end
+
+        private
+
+        def generated_range(center_year, timezone)
+          cache_key = [center_year, TimeScale.timezone_key(timezone)].freeze
+          cached = @cache_mutex.synchronize { @range_cache[cache_key] }
+          return cached if cached
+
+          years = ((center_year - 2)..(center_year + 2)).to_a
+          generated = MonthBuilder.build(years, timezone)
+          @cache_mutex.synchronize { @range_cache[cache_key] ||= generated }
+        end
+
+        def local_date(value, timezone)
+          return value if value.instance_of?(::Date)
+          return TimeScale.localize(value, timezone).to_date if value.is_a?(Time)
+
+          raise TypeError, "expected Date or Time, got #{value.class}"
+        end
+
+        def validate_gregorian_year(year)
+          return year if (MIN_YEAR..MAX_YEAR).cover?(year)
+
+          raise RangeError, "date must fall within years #{MIN_YEAR}..#{MAX_YEAR}"
+        end
+
+        def validate_lunar_year(year)
+          value = Integer(year)
+          return value if (MIN_LUNISOLAR_YEAR..MAX_LUNISOLAR_YEAR).cover?(value)
+
+          raise RangeError, "lunisolar year must be between #{MIN_LUNISOLAR_YEAR} and #{MAX_LUNISOLAR_YEAR}"
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "lunisolar year must be an Integer"
+        end
+      end
+    end
+  end
+
+  class << self
+    def lunisolar(value, tz: DEFAULT_TIMEZONE)
+      Lunisolar::Calendar.convert(value, tz: tz)
+    end
+
+    def lunisolar_year(year, tz: DEFAULT_TIMEZONE)
+      Lunisolar::Calendar.year(year, tz: tz)
+    end
+
+    def gregorian(lunar_year, month, day, leap: false, tz: DEFAULT_TIMEZONE)
+      Lunisolar::Calendar.to_gregorian(lunar_year, month, day, leap: leap, tz: tz)
+    end
+  end
+end

data/lib/sekki24/lunisolar/date.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Sekki24
+  module Lunisolar
+    class Date
+      attr_reader :year, :month, :day, :gregorian_date, :month_length
+
+      def initialize(year:, month:, day:, leap:, gregorian_date:, month_length:)
+        @year = year
+        @month = month
+        @day = day
+        @leap = leap
+        @gregorian_date = gregorian_date.freeze
+        @month_length = month_length
+        freeze
+      end
+
+      def leap?
+        @leap
+      end
+
+      def month_name_ja
+        prefix = leap? ? "閏" : ""
+        "#{prefix}#{Month::MONTH_NAMES.fetch(month - 1)}"
+      end
+
+      def to_date
+        gregorian_date
+      end
+
+      def ==(other)
+        other.is_a?(Date) && year == other.year && month == other.month &&
+          day == other.day && leap? == other.leap?
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, year, month, day, leap?].hash
+      end
+
+      def to_h
+        {
+          year: year,
+          month: month,
+          day: day,
+          leap: leap?,
+          month_name_ja: month_name_ja,
+          month_length: month_length,
+          gregorian_date: gregorian_date
+        }
+      end
+
+      def inspect
+        "#<#{self.class} #{year}年#{month_name_ja}#{day}日 (#{gregorian_date.iso8601})>"
+      end
+    end
+  end
+end

data/lib/sekki24/lunisolar/month.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sekki24
+  module Lunisolar
+    class Month
+      MONTH_NAMES = %w[正月 二月 三月 四月 五月 六月 七月 八月 九月 十月 十一月 十二月].freeze
+
+      attr_reader :year, :month, :start_date, :end_date, :new_moon_time, :principal_longitudes
+
+      def initialize(year:, month:, leap:, start_date:, end_date:, new_moon_time:, principal_longitudes:)
+        @year = year
+        @month = month
+        @leap = leap
+        @start_date = start_date.freeze
+        @end_date = end_date.freeze
+        @new_moon_time = new_moon_time.dup.freeze
+        @principal_longitudes = principal_longitudes.dup.freeze
+        freeze
+      end
+
+      def leap?
+        @leap
+      end
+
+      def length
+        (end_date - start_date).to_i + 1
+      end
+
+      def name_ja
+        prefix = leap? ? "閏" : ""
+        "#{prefix}#{MONTH_NAMES.fetch(month - 1)}"
+      end
+
+      def include?(date)
+        (start_date..end_date).cover?(date)
+      end
+
+      def ==(other)
+        other.is_a?(Month) && year == other.year && month == other.month &&
+          leap? == other.leap? && start_date == other.start_date
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, year, month, leap?, start_date].hash
+      end
+
+      def to_h
+        {
+          year: year,
+          month: month,
+          leap: leap?,
+          name_ja: name_ja,
+          start_date: start_date,
+          end_date: end_date,
+          length: length,
+          new_moon_time: new_moon_time,
+          principal_longitudes: principal_longitudes
+        }
+      end
+
+      def inspect
+        "#<#{self.class} #{year}年#{name_ja} #{start_date.iso8601}..#{end_date.iso8601}>"
+      end
+    end
+  end
+end

data/lib/sekki24/lunisolar/month_builder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Sekki24
+  module Lunisolar
+    module MonthBuilder
+      PRINCIPAL_LONGITUDES = (0.step(330, 30).to_a).freeze
+
+      RawMonth = Struct.new(
+        :start_date,
+        :end_date,
+        :new_moon_time,
+        :principal_longitudes,
+        :number,
+        :leap,
+        :year,
+        keyword_init: true
+      )
+
+      @cache_mutex = Mutex.new
+      @principal_cache = {}
+
+      class << self
+        def build(years, timezone)
+          terms = principal_terms(years, timezone)
+          months = build_raw_months(years, timezone, terms)
+          assign_month_numbers(months, terms)
+          assign_lunar_years(months)
+          months.filter_map { |raw| build_month(raw) }.freeze
+        end
+
+        def clear_cache!
+          @cache_mutex.synchronize { @principal_cache.clear }
+        end
+
+        private
+
+        def build_raw_months(years, timezone, principal_terms)
+          moons = years.flat_map do |year|
+            Lunar::PhaseFinder.new_moons_for_calendar(year, tz: timezone)
+          end.uniq.sort
+          moons.each_cons(2).map do |start_time, next_time|
+            start_date = start_time.to_date
+            end_date = next_time.to_date - 1
+            terms = principal_terms.select { |term| (start_date..end_date).cover?(term.fetch(:date)) }
+            RawMonth.new(
+              start_date: start_date,
+              end_date: end_date,
+              new_moon_time: start_time,
+              principal_longitudes: terms.map { |term| term.fetch(:longitude) }.freeze
+            )
+          end
+        end
+
+        def principal_terms(years, timezone)
+          years.flat_map { |year| principal_terms_for_year(year, timezone) }
+        end
+
+        def principal_terms_for_year(year, timezone)
+          cache_key = [year, TimeScale.timezone_key(timezone)].freeze
+          cached = @cache_mutex.synchronize { @principal_cache[cache_key] }
+          return cached if cached
+
+          calculated = PRINCIPAL_LONGITUDES.map do |longitude|
+            utc = Finder.find(year: year, longitude: longitude, solar: Solar::Precise)
+            local = TimeScale.localize(utc, timezone)
+            { longitude: longitude, date: local.to_date }.freeze
+          end.freeze
+          @cache_mutex.synchronize { @principal_cache[cache_key] ||= calculated }
+        end
+
+        def assign_month_numbers(months, principal_terms)
+          solstice_dates = principal_terms.select { |term| term.fetch(:longitude) == 270 }.map { |term| term.fetch(:date) }
+          anchors = solstice_dates.filter_map do |date|
+            index = months.index { |month| (month.start_date..month.end_date).cover?(date) }
+            [index, date] if index
+          end
+
+          anchors.each_cons(2) do |(left_index, _), (right_index, _)|
+            assign_solstice_segment(months, left_index, right_index)
+          end
+        end
+
+        def assign_solstice_segment(months, first_index, next_index)
+          span = next_index - first_index
+          unless [12, 13].include?(span)
+            raise Error, "unexpected lunisolar month count between winter solstices: #{span}"
+          end
+
+          leap_index = find_leap_index(months, first_index, next_index, span)
+          number = 11
+          (first_index...next_index).each do |index|
+            month = months.fetch(index)
+            if index == leap_index
+              month.leap = true
+            else
+              number = (number % 12) + 1 unless index == first_index
+              month.leap = false
+            end
+            month.number = number
+          end
+        end
+
+        def find_leap_index(months, first_index, next_index, span)
+          return unless span == 13
+
+          index = ((first_index + 1)...next_index).find do |candidate|
+            months.fetch(candidate).principal_longitudes.empty?
+          end
+          raise Error, "could not identify leap month" unless index
+
+          index
+        end
+
+        def assign_lunar_years(months)
+          assigned = months.select(&:number)
+          first_new_year = assigned.index { |month| month.number == 1 && !month.leap }
+          raise Error, "could not identify lunisolar new year" unless first_new_year
+
+          current_year = assigned.fetch(first_new_year).start_date.year
+          assigned.take(first_new_year).each { |month| month.year = current_year }
+          assigned.drop(first_new_year).each do |month|
+            current_year = month.start_date.year if month.number == 1 && !month.leap
+            month.year = current_year
+          end
+        end
+
+        def build_month(raw)
+          return unless raw.number && raw.year
+
+          Month.new(
+            year: raw.year,
+            month: raw.number,
+            leap: raw.leap,
+            start_date: raw.start_date,
+            end_date: raw.end_date,
+            new_moon_time: raw.new_moon_time,
+            principal_longitudes: raw.principal_longitudes
+          )
+        end
+      end
+    end
+  end
+end