sekki24 1.0.0

data/lib/sekki24/time_scale.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Sekki24
+  module TimeScale
+    UNIX_EPOCH_JD = 2_440_587.5
+    SECONDS_PER_DAY = 86_400.0
+    OFFSET_PATTERN = /\A([+-])(\d{2}):(\d{2})\z/
+
+    module_function
+
+    def utc_to_jd(time)
+      utc_time = coerce_time(time).getutc
+      (utc_time.to_r / SECONDS_PER_DAY) + UNIX_EPOCH_JD
+    end
+
+    def jd_to_utc(jd)
+      Time.at((Float(jd) - UNIX_EPOCH_JD) * SECONDS_PER_DAY).utc
+    end
+
+    def utc_to_jde(time)
+      utc_time = coerce_time(time).getutc
+      utc_to_jd(utc_time) + (DeltaT.seconds(decimal_year(utc_time)) / SECONDS_PER_DAY)
+    end
+
+    def jde_to_utc(jde)
+      utc = jd_to_utc(jde)
+      2.times do
+        utc = jd_to_utc(Float(jde) - (DeltaT.seconds(decimal_year(utc)) / SECONDS_PER_DAY))
+      end
+      utc
+    end
+
+    def decimal_year(time)
+      utc_time = coerce_time(time).getutc
+      year_start = Time.utc(utc_time.year, 1, 1)
+      next_year = Time.utc(utc_time.year + 1, 1, 1)
+      utc_time.year + ((utc_time - year_start) / (next_year - year_start))
+    end
+
+    def localize(time, timezone)
+      utc_time = coerce_time(time).getutc
+      offset = fixed_offset(timezone)
+      return utc_time.getlocal(offset) unless offset.nil?
+
+      local = timezone.utc_to_local(utc_time)
+      return local if local.is_a?(Time)
+
+      raise ArgumentError, "timezone utc_to_local must return a Time"
+    end
+
+    def timezone_key(timezone)
+      offset = fixed_offset(timezone)
+      return [:offset, offset].freeze unless offset.nil?
+
+      identifier = timezone.identifier if timezone.respond_to?(:identifier)
+      [:timezone, identifier || timezone.object_id].freeze
+    end
+
+    def fixed_offset(timezone)
+      return validate_offset(timezone) if timezone.is_a?(Integer)
+      return 0 if %w[UTC Z].include?(timezone)
+
+      if timezone.is_a?(String)
+        match = OFFSET_PATTERN.match(timezone)
+        raise ArgumentError, 'timezone must use the format "+09:00"' unless match
+
+        sign = match[1] == "+" ? 1 : -1
+        hours = match[2].to_i
+        minutes = match[3].to_i
+        raise ArgumentError, "timezone offset is out of range" if hours > 23 || minutes > 59
+
+        return validate_offset(sign * ((hours * 3600) + (minutes * 60)))
+      end
+
+      return nil if timezone.respond_to?(:utc_to_local)
+
+      raise ArgumentError, "timezone must be an offset String, Integer, or timezone object"
+    end
+
+    def coerce_time(value)
+      return value if value.is_a?(Time)
+
+      raise TypeError, "expected Time, got #{value.class}"
+    end
+    private_class_method :coerce_time
+
+    def validate_offset(offset)
+      raise ArgumentError, "timezone offset is out of range" unless (-86_399..86_399).cover?(offset)
+
+      offset
+    end
+    private_class_method :validate_offset
+  end
+end

data/lib/sekki24/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sekki24
+  VERSION = "1.0.0"
+end

data/lib/sekki24/zassetsu.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Sekki24
+  class Zassetsu
+    include Comparable
+
+    ATTRIBUTES = %i[key name_ja reading category date end_date time longitude].freeze
+
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(key:, name_ja:, reading:, category:, date:, end_date: date, time: nil, longitude: nil)
+      @key = key
+      @name_ja = name_ja
+      @reading = reading
+      @category = category
+      @date = date.freeze
+      @end_date = end_date.freeze
+      @time = time&.dup&.freeze
+      @longitude = longitude
+      freeze
+    end
+
+    def <=>(other)
+      return unless other.respond_to?(:date)
+
+      sort_key <=> other.sort_key
+    end
+
+    def include?(value)
+      target = value.is_a?(Time) ? value.to_date : value
+      (date..end_date).cover?(target)
+    end
+
+    def to_h
+      ATTRIBUTES.to_h { |attribute| [attribute, public_send(attribute)] }
+    end
+
+    def inspect
+      suffix = date == end_date ? date.iso8601 : "#{date.iso8601}..#{end_date.iso8601}"
+      "#<#{self.class} #{name_ja} (#{key}) #{suffix}>"
+    end
+
+    protected
+
+    def sort_key
+      seconds = time ? (time.hour * 3600) + (time.min * 60) + time.sec : -1
+      [date.jd, seconds]
+    end
+  end
+end

data/lib/sekki24/zassetsu_calendar.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "zassetsu"
+
+module Sekki24
+  module ZassetsuCalendar
+    NAMES = {
+      winter_doyo: ["冬土用", "ふゆどよう"],
+      setsubun: ["節分", "せつぶん"],
+      spring_higan: ["春彼岸", "はるひがん"],
+      spring_shanichi: ["春社日", "はるしゃにち"],
+      spring_doyo: ["春土用", "はるどよう"],
+      hachijuhachiya: ["八十八夜", "はちじゅうはちや"],
+      nyubai: ["入梅", "にゅうばい"],
+      hangesho: ["半夏生", "はんげしょう"],
+      summer_doyo: ["夏土用", "なつどよう"],
+      nihyakutoka: ["二百十日", "にひゃくとおか"],
+      nihyakuhatsuka: ["二百二十日", "にひゃくはつか"],
+      autumn_higan: ["秋彼岸", "あきひがん"],
+      autumn_shanichi: ["秋社日", "あきしゃにち"],
+      autumn_doyo: ["秋土用", "あきどよう"]
+    }.transform_values(&:freeze).freeze
+
+    SOLAR_EVENTS = {
+      winter_doyo: 297,
+      spring_doyo: 27,
+      nyubai: 80,
+      hangesho: 100,
+      summer_doyo: 117,
+      autumn_doyo: 207
+    }.freeze
+
+    @cache_mutex = Mutex.new
+    @year_cache = {}
+
+    class << self
+      def year(year, tz:, precision:)
+        calendar_year = validate_year(year)
+        mode = normalize_precision(precision)
+        solar = Solar.model(mode)
+        cache_key = [calendar_year, TimeScale.timezone_key(tz), mode].freeze
+        cached = @cache_mutex.synchronize { @year_cache[cache_key] }
+        return cached if cached
+
+        calculated = calculate_year(calendar_year, tz, mode, solar).sort.freeze
+        @cache_mutex.synchronize { @year_cache[cache_key] ||= calculated }
+      end
+
+      def fetch(year, key, tz:, precision:)
+        normalized = key.to_sym
+        raise ArgumentError, "unknown zassetsu: #{key.inspect}" unless NAMES.key?(normalized)
+
+        self.year(year, tz: tz, precision: precision).find { |entry| entry.key == normalized }
+      rescue NoMethodError
+        raise ArgumentError, "unknown zassetsu: #{key.inspect}"
+      end
+
+      def on(date, tz:, precision:)
+        raise TypeError, "expected Date, got #{date.class}" unless date.is_a?(Date)
+
+        year(date.year, tz: tz, precision: precision).select { |entry| entry.date == date }.freeze
+      end
+
+      def active(date, tz:, precision:)
+        raise TypeError, "expected Date or Time, got #{date.class}" unless date.is_a?(Date) || date.is_a?(Time)
+
+        local_date = date.is_a?(Time) ? TimeScale.localize(date, tz).to_date : date
+        year(local_date.year, tz: tz, precision: precision).select { |entry| entry.include?(local_date) }.freeze
+      end
+
+      def clear_cache!
+        @cache_mutex.synchronize { @year_cache.clear }
+      end
+
+      private
+
+      def calculate_year(year, timezone, mode, solar)
+        terms = Sekki24.year(year, tz: timezone, precision: mode)
+        by_key = terms.to_h { |term| [term.key, term] }
+        solar_events = calculate_solar_events(year, timezone, solar, by_key)
+
+        solar_events + date_observances(by_key) + shanichi_observances(by_key)
+      end
+
+      def calculate_solar_events(year, timezone, solar, terms)
+        SOLAR_EVENTS.map do |key, longitude|
+          utc_time = Finder.find(year: year, longitude: longitude, solar: solar)
+          local_time = TimeScale.localize(utc_time, timezone)
+          end_date = doyo_end_date(key, terms) || local_time.to_date
+          build(key, category: :solar_longitude, date: local_time.to_date, end_date: end_date,
+                     time: local_time, longitude: longitude)
+        end
+      end
+
+      def date_observances(terms)
+        risshun = terms.fetch(:risshun).to_date
+        spring_equinox = terms.fetch(:shunbun).to_date
+        autumn_equinox = terms.fetch(:shubun).to_date
+
+        [
+          build(:setsubun, category: :calendar_day, date: risshun - 1),
+          build(:spring_higan, category: :period, date: spring_equinox - 3, end_date: spring_equinox + 3),
+          build(:hachijuhachiya, category: :counted_day, date: risshun + 87),
+          build(:nihyakutoka, category: :counted_day, date: risshun + 209),
+          build(:nihyakuhatsuka, category: :counted_day, date: risshun + 219),
+          build(:autumn_higan, category: :period, date: autumn_equinox - 3, end_date: autumn_equinox + 3)
+        ]
+      end
+
+      def shanichi_observances(terms)
+        [
+          [:spring_shanichi, terms.fetch(:shunbun)],
+          [:autumn_shanichi, terms.fetch(:shubun)]
+        ].map do |key, equinox|
+          build(key, category: :sexagenary_day, date: closest_tsuchinoe_day(equinox))
+        end
+      end
+
+      def closest_tsuchinoe_day(equinox)
+        center = equinox.to_date
+        candidates = (-5..5).map { |offset| center + offset }.select { |date| ((date.jd + 49) % 10) == 4 }
+        return candidates.first if candidates.length == 1
+
+        equinox.time.hour < 12 ? candidates.min : candidates.max
+      end
+
+      def doyo_end_date(key, terms)
+        season_start = {
+          winter_doyo: :risshun,
+          spring_doyo: :rikka,
+          summer_doyo: :risshu,
+          autumn_doyo: :ritto
+        }[key]
+        terms.fetch(season_start).to_date - 1 if season_start
+      end
+
+      def build(key, **attributes)
+        name_ja, reading = NAMES.fetch(key)
+        Zassetsu.new(key: key, name_ja: name_ja, reading: reading, **attributes)
+      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
+
+      def normalize_precision(precision)
+        precision.to_sym
+      rescue NoMethodError
+        raise ArgumentError, "precision must be :fast or :precise"
+      end
+    end
+  end
+
+  class << self
+    def zassetsu_year(year, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      ZassetsuCalendar.year(year, tz: tz, precision: precision)
+    end
+
+    def zassetsu(year, key, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      ZassetsuCalendar.fetch(year, key, tz: tz, precision: precision)
+    end
+
+    def zassetsu_on(date, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      ZassetsuCalendar.on(date, tz: tz, precision: precision)
+    end
+
+    def current_zassetsu(date = Date.today, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      ZassetsuCalendar.active(date, tz: tz, precision: precision)
+    end
+  end
+end

data/lib/sekki24.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "sekki24/version"
+
+module Sekki24
+  class Error < StandardError; end
+end
+
+require_relative "sekki24/names"
+require_relative "sekki24/term"
+require_relative "sekki24/delta_t"
+require_relative "sekki24/time_scale"
+require_relative "sekki24/solar"
+require_relative "sekki24/finder"
+
+module Sekki24
+  MIN_YEAR = 1900
+  MAX_YEAR = 2100
+  DEFAULT_TIMEZONE = "+00:00"
+  DEFAULT_PRECISION = :precise
+
+  @cache_mutex = Mutex.new
+  @year_cache = {}
+  @candidate_cache = {}
+
+  class << self
+    def year(year, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      calendar_year = validate_year(year)
+      mode, solar = resolve_precision(precision)
+      cache_key = [calendar_year, TimeScale.timezone_key(tz), mode].freeze
+      cached = @cache_mutex.synchronize { @year_cache[cache_key] }
+      return cached if cached
+
+      calculated = calculate_year(calendar_year, tz, mode, solar)
+      @cache_mutex.synchronize { @year_cache[cache_key] ||= calculated }
+    end
+
+    def term(year, key, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      definition = Names.fetch(key)
+      self.year(year, tz: tz, precision: precision).find { |entry| entry.key == definition.key }
+    end
+
+    def current(time = Time.now, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      instant = ensure_time(time)
+      navigation_terms(instant, tz, precision).select { |entry| entry.time <= instant }.max ||
+        raise(RangeError, "no current solar term in the supported range")
+    end
+
+    def next_term(time = Time.now, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      instant = ensure_time(time)
+      navigation_terms(instant, tz, precision).select { |entry| entry.time > instant }.min ||
+        raise(RangeError, "no next solar term in the supported range")
+    end
+
+    def prev_term(time = Time.now, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      instant = ensure_time(time)
+      navigation_terms(instant, tz, precision).select { |entry| entry.time < instant }.max ||
+        raise(RangeError, "no previous solar term in the supported range")
+    end
+
+    def on(date, tz: DEFAULT_TIMEZONE, precision: DEFAULT_PRECISION)
+      unless date.is_a?(Date)
+        raise TypeError, "expected Date, got #{date.class}"
+      end
+
+      year(date.year, tz: tz, precision: precision).find { |entry| entry.to_date == date }
+    end
+
+    def clear_cache!
+      @cache_mutex.synchronize do
+        @year_cache.clear
+        @candidate_cache.clear
+      end
+      SeventyTwoKou.clear_cache! if defined?(SeventyTwoKou)
+      ZassetsuCalendar.clear_cache! if defined?(ZassetsuCalendar)
+      Lunar::PhaseFinder.clear_cache! if defined?(Lunar::PhaseFinder)
+      Lunisolar::Calendar.clear_cache! if defined?(Lunisolar::Calendar)
+      nil
+    end
+
+    private
+
+    def calculate_year(calendar_year, timezone, mode, solar)
+      candidates = ((calendar_year - 1)..(calendar_year + 1)).flat_map do |utc_year|
+        candidate_times(utc_year, mode, solar)
+      end
+      terms = candidates.filter_map do |definition, utc_time|
+        local_time = TimeScale.localize(utc_time, timezone)
+        next unless local_time.year == calendar_year
+
+        Term.new(definition: definition, time: local_time)
+      end.sort.freeze
+
+      return terms if terms.length == 24
+
+      raise Error, "expected 24 solar terms for #{calendar_year}, got #{terms.length}"
+    end
+
+    def candidate_times(year, mode, solar)
+      cache_key = [year, mode].freeze
+      cached = @cache_mutex.synchronize { @candidate_cache[cache_key] }
+      return cached if cached
+
+      calculated = Names::CALENDAR_ORDER.map do |definition|
+        utc_time = Finder.find(year: year, longitude: definition.longitude, solar: solar).freeze
+        [definition, utc_time].freeze
+      end.freeze
+      @cache_mutex.synchronize { @candidate_cache[cache_key] ||= calculated }
+    end
+
+    def navigation_terms(time, timezone, precision)
+      local_year = TimeScale.localize(time, timezone).year
+      years = ((local_year - 1)..(local_year + 1)).select { |value| (MIN_YEAR..MAX_YEAR).cover?(value) }
+      raise RangeError, "time must fall within years #{MIN_YEAR}..#{MAX_YEAR}" if years.empty?
+
+      years.flat_map { |value| year(value, tz: timezone, precision: precision) }
+    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
+
+    def resolve_precision(precision)
+      mode = precision.to_sym
+      [mode, Solar.model(mode)]
+    rescue NoMethodError
+      raise ArgumentError, "precision must be :fast or :precise"
+    end
+
+    def ensure_time(time)
+      return time if time.is_a?(Time)
+
+      raise TypeError, "expected Time, got #{time.class}"
+    end
+  end
+end
+
+require_relative "sekki24/seventy_two_kou"
+require_relative "sekki24/zassetsu_calendar"
+require_relative "sekki24/lunar/phase_finder"
+require_relative "sekki24/lunisolar/calendar"

data/sekki24.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/sekki24/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "sekki24"
+  spec.version = Sekki24::VERSION
+  spec.authors = ["Yudai Takada"]
+  spec.email = ["t.yudai92@gmail.com"]
+
+  spec.summary = "Calculate Japanese solar terms, observances, and lunisolar dates"
+  spec.description = <<~DESCRIPTION
+    Sekki24 calculates the 24 solar terms, 72 microseasons, supplementary
+    seasonal observances, new moons, and Japanese lunisolar dates for years
+    1900 through 2100 using pure Ruby and no runtime dependencies.
+  DESCRIPTION
+  spec.homepage = "https://rubygems.org/gems/sekki24"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      f.start_with?(*%w[bin/ Gemfile .gitignore .rspec spec/ .github/])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: sekki24
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Sekki24 calculates the 24 solar terms, 72 microseasons, supplementary
+  seasonal observances, new moons, and Japanese lunisolar dates for years
+  1900 through 2100 using pure Ruby and no runtime dependencies.
+email:
+- t.yudai92@gmail.com
+executables:
+- sekki24
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/sekki24
+- lib/sekki24.rb
+- lib/sekki24/delta_t.rb
+- lib/sekki24/finder.rb
+- lib/sekki24/kou.rb
+- lib/sekki24/kou_names.rb
+- lib/sekki24/lunar/moon.rb
+- lib/sekki24/lunar/periodic_terms.rb
+- lib/sekki24/lunar/phase_finder.rb
+- lib/sekki24/lunisolar/calendar.rb
+- lib/sekki24/lunisolar/date.rb
+- lib/sekki24/lunisolar/month.rb
+- lib/sekki24/lunisolar/month_builder.rb
+- lib/sekki24/names.rb
+- lib/sekki24/nutation.rb
+- lib/sekki24/seventy_two_kou.rb
+- lib/sekki24/solar.rb
+- lib/sekki24/solar/fast.rb
+- lib/sekki24/solar/precise.rb
+- lib/sekki24/solar/vsop87_earth.rb
+- lib/sekki24/term.rb
+- lib/sekki24/time_scale.rb
+- lib/sekki24/version.rb
+- lib/sekki24/zassetsu.rb
+- lib/sekki24/zassetsu_calendar.rb
+- sekki24.gemspec
+homepage: https://rubygems.org/gems/sekki24
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://rubygems.org/gems/sekki24
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Calculate Japanese solar terms, observances, and lunisolar dates
+test_files: []