zakuro 0.9.0 → 0.9.1

data/{lib/zakuro/version/senmyou/README.md → doc/version/senmyou.md}

@@ -10,117 +10,19 @@
 
 宣明暦は太陰太陽暦である
 
-太陰太陽暦の文化的・歴史的な背景には触れず、ここでは暦計算する上で必要なことのみ言及する
-
-私たち現代の日本人が使うグレゴリオ暦は太陽暦である
-
-太陽暦は `年` を太陽に対する公転周期、 `日` を地球の自転周期で求める
-
-太陰太陽暦はそれに加えて、`月` を月の満ち欠けの周期（朔望月）に合わせる
-
-本来この `年` と `月` の周期には何らかの関連性はなく、暦の側で辻褄合わせする必要がある
-
-（今回は触れないが、メトン周期はこのような辻褄合わせの一つである）
-
-`年` の太陽年は約365.24日、 `月` の1朔望月は約29.5日である
-
-1朔望月 * 12 = 354日であり、 1太陽年には常に約11日ほど満たないことになる
-
-古代中国人はこれを12ヶ月の平年（353/354/355/356日）と、13ヶ月の閏年(383/384/385日）で解決した
-
-問題は1年に含まれる朔望月のそれぞれを1月、2月...などと位置付けるのか
-
-これを理解するために、元弘元年-元弘2年を例にする
-
-![太陽と月](../../../../images/太陽と月.png)
-
-「定朔」は月の始まりを示す
-
-毎月1日の始まりであり、ここから次の月までは1朔望月かかる
-
-具体的に言えば、朔月（新月）-> 上弦 -> 望月（満月） -> 下弦 -> 次の朔月（新月）と約29.5日かけて移り変わる
-
-下の「黄経」は（地球から見える）太陽の位置を示し、360度で1太陽年が経過する
-
-この黄経15度ごとに名前が与えられており、これを「二十四節気」と呼ぶ
-
-宣明暦ではこの定朔の範囲にどの二十四節気が含まれるかを計算し、中気に対応する月名を与えている
-
-11月を例に取ると、「3-2240」と「33-6480」の間には大雪（「13-4659」）と冬至（「28-6495」）が含まれている
-
-この大余小余（xx-xxxx）の表現を細かくは説明しないが、とりあえずは左側の数字だけ見ていただければ良い
-
-この冬至は11月の中気であり、これが含まれている1朔望月を「11月」と呼ぶ
-
-次に閏2月を例に取ると、中気が一つも含まれていないことが分かる
-
-「1-329」と「30-4043」の間には節気しかない
-
-これを閏月と呼び、これが含まれる元弘3年は13ヶ月ある閏年になる
-
-このように、太陰太陽暦では太陽の位置を24分割し、月の所属を明らかにする方法を取っている
+詳細は [太陰太陽暦](./section/lunisolar_calendar.md) に記載してある
 
 # 計算
 
 計算にあたって、暦共通の計算と、宣明暦固有の計算がある
 
-現状は他の暦を扱っていないため、暦共通の計算から説明する
-
-その上で宣明暦固有の計算を説明することとする
-
-## 共通の計算
-
-これから記すことは原則として実装の問題であり、計算手順そのものは特定の資料に依拠するものではない
-
-『日本暦日原典』と同等の計算結果を出すためには、暦法編（同p.491〜）だけでは不十分であり、元号年の求め方など他に求めるべき項目がある
-
-これはそれらを補完するための手順となる
-
-### 計算の流れ
-
-正慶1年の日数を出すための流れを図示する
-
-![各月の求め方](../../../../images/各月の求め方.png)
-
-最後の「355日」を出すためには、月ごとの日数を出す必要がある
-
-月ごとの日数は定朔によって得られるが、それは経朔を補正することで得られる
-
-この図の正慶1年は宣明暦に属するため、定朔まで求める必要がある
-
-11月定朔に必要な「経朔」「入定気（二十四節気）」「月の進退」は冬至計算で求められる
-
-従って、まずは各年の冬至を求めなければならない
-
-計算の多くはそれぞれの暦に依存するが、まずは共通の計算部分を列挙する
-
-### 元号の求め方
-
-元慶（877-6-1 ～ 885-3-10）をもとに考える
+暦共通の計算は前処理/後処理として説明する
 
-元号開始年が存在する元号年（877）から、次の元号の開始年（885） + 1 までを和暦計算する。これをAとする
+その間に宣明暦固有の計算を説明することとする
 
-元号のはじまりは固定値のため、西暦開始日と、それに対応する和暦開始日を持つ（例: 元慶01年04月16日 = 877-6-1）
+## 共通前処理
 
-この和暦開始日は必ずAの1年目に存在するため、1年目の和暦日を特定し、その日と西暦開始日を関連付ける
-
-もし元慶2年以降を計算したい場合は、Aの西暦開始日から該当年月日までを加算で求める
-
-具体的には、和暦上の月の大小（29日 or 30日）を用いた加算となる
-
-念のため補足するが、西暦（太陽暦）のように1年あたりの日数は一定しない
-
-平年（353/354/355/356）または閏年(383/384/385）のパターンがあり、月の大小（29/30）や閏月（中気のない月）の有無で変動する
-
-したがって、2年目以降を加算なしに特定することはできない
-
-### 南北朝について
-
-南北朝による元号の並立がある（正慶１年 / 元弘2年）
-
-このような場合、元号は早くから始まったほうを基準に計算しなければならない（正慶 よりは 元弘 の方が一年早い）
-
-並立は最大でも2つであり、並びは『日本暦日原典』に従う
+詳細は [共通前処理](./section/common_pre_process.md) に記載してある
 
 ## 宣明暦固有の計算
 
@@ -140,9 +42,6 @@
     4. 11月の月の進退を進めて12月の月の進退を求める
     5. 12月の月の進退から月の運動の補正値を求める
     6. 太陽・月の運動の補正値から12月定朔（補正後の月初日）を求める
-3. 1ヶ月ごとの固有値を求める
-    1. 月の大小を求める
-    2. 二十四節気の所属を求める
 
 1の計算方法は『日本暦日原典』p.511-516に依拠する
 
@@ -228,7 +127,7 @@
 
 前提として、11月の朔日は二十四節気の小雪〜大雪、または大雪〜冬至の範囲内にある
 
-![入定気の起算](../../../../images/入定気の起算.png)
+![入定気の起算](../../images/入定気の起算.png)
 
 上記はp.513の第五図を参考の上、下記の変更を加えている
 
@@ -243,6 +142,8 @@ a: `大雪定数` (14-5235.5) - `天正閏余`
 
 b: `小雪定数` (14-4235.5) - ( `天正閏余` - `大雪定数` (14-5235.5))
 
+（ これは不完全な計算である。詳細は [宣明暦の11月朔日計算](./section/senmyou_november_1st.md) を参照のこと）
+
 慶安3年（1650年）の `天正閏余` (18-6867) はbのパターンであり、以下のように計算できる
 
 18-6867 - 14-5235.5 = 4-2631.3
@@ -377,6 +278,8 @@ NOTE: 後述の表が遠地点始まりで地球に向かって進み、近地
 
 前回の結果（2-2446.665）を求めるに当たり、`暦中日（暦周の半分）` で減算したが、この場合は 進退列の`退` を見ることになる
 
+まずは前回結果の小余を [小数点](./section/decimal.md) に従って切り捨て、 大余 2 、小余 2446 とする
+
 次に大余に相当する入暦列、小余に相当する小余列を確認し、損益率 -726 / 眺朒積 -830 を引き当てる
 
 ( `損益率` (-726) * `小余` (2446) ) / `統法（1日）` （8400） = -211 ... 余り -3396
@@ -409,7 +312,7 @@ NOTE: 後述の表が遠地点始まりで地球に向かって進み、近地
 
 なお、太陽・月の運動の補正値を求めるくだりは、「安藤有益著『再考長慶宣明暦算法』 について」p.89-90 を参考にする
 
-![各月の求め方](../../../../images/各月の求め方.png)
+![各月の求め方](../../images/各月の求め方.png)
 
 再掲する形になるが、流れについては上記の図を参考にしてほしい
 
@@ -454,7 +357,7 @@ NOTE: 後述の表が遠地点始まりで地球に向かって進み、近地
 
 12月以降を求めたい場合は、上記の定数を二十四節気の並びに合わせて順次使用する
 
-![12月以降の入定気](../../../../images/12月以降の入定気.png)
+![12月以降の入定気](../../images/12月以降の入定気.png)
 
 12月経朔の入定気は、上図のように弦を4回足して得られる
 
@@ -486,7 +389,7 @@ NOTE: 後述の表が遠地点始まりで地球に向かって進み、近地
 
 次に12月経朔に対応する月の進退を求める
 
-![12月以降の月の進退](../../../../images/12月以降の月の進退.png)
+![12月以降の月の進退](../../images/12月以降の月の進退.png)
 
 基本的な求め方は太陽の時と変わらない
 
@@ -522,70 +425,14 @@ NOTE: 後述の表が遠地点始まりで地球に向かって進み、近地
 つまり、以下により12月定朔は確定する
 
 21-6780 + 大余1 = 22-6780
+## 共通後処理
 
-### 1ヶ月ごとの固有値を求める
-
-これまでは定朔を求めてきたが、この定朔をもとに月ごとの固有値を求める
-
-この計算は当月と次月の定朔を必要とするため、例として11月定朔/12月定朔を使うことにする
-
-#### 月の大小を求める
-
-太陰太陽暦において1ヶ月の日数は29日または30日である
-
-求め方は『日本暦日原典』凡例のp.6を参照した
-
-これを求める上で、朔日の大余（1日を示す単位）を比較する
-
-例えば、 11月の朔日（定朔）が 52-2655 で、 12月の朔日（定朔）が 22-6780 の場合、52 と 22 を取り出し、 差分が10で割り切れるかを検証する
-
-52 - 22 = 30 は10で割り切れるため、これは11月は大の月（30日）である
-
-もし割り切れない場合（差分が29の場合）は小の月（29日）である
-
-なお、引用元では定朔の干支から求めているが、干支の元ネタが大余のため、実装の容易さから上記のような解説となった
-
-#### 二十四節気の所属を求める
-
-その月が何月であるかは二十四節気の中気にあることはすでに述べた通りである
-
-ここでは中気節気と月を対応させることにする
-
-求め方だがこれは確たる引用元がない
-
-『日本暦日原典』においても同著者の「宣明暦に関する研究」に遡っても言及がなかった
-
-ただし以下のようにすれば『日本暦日原典』通りに求めることができる
-
-11月定朔を求める時に、前年冬至として 11-2730 を求めていた
-
-また、 `気策（24分の1年）` (15-1835.5) が定義されており、二十四節気のそれぞれの間隔が固定値であることが分かる
-
-つまり、 `前年冬至` (11-2730) + `気策（24分の1年）` (15-1835.5) = `小寒` (26-4565.5) ≒ 26-4565
-
-結果から秒は省略する（切り捨てる）
-
-これを繰り返すことで二十四節気それぞれの値を得ることができる
-
-もし前年冬至〜当年冬至まで処理を繰り返す場合は、単に24個分を求めるというよりは、
-前年大雪（前年冬至 - 気策）、当年冬至、当年小寒まで求めておいた方が良い
-
-こうして得られた二十四節気を11月から順に比較していく
-
-11月を例に取ると、 11月定朔（ 52-2655 ） <= 二十四節気 < 12月定朔（22-6780） である
-
-すでに言及した通り大余は60で一巡して0になるため、範囲計算はそれを考慮して行う必要がある
-
-11月には前年大雪（ 56-894 ）と前年冬至（ 11-2730 ）が含まれているため、これが11月の中気/節気（取り上げた順番に従うと 節気/中気）となる
-
-以上の手続きで『日本暦日原典』通りの結果が得られる
+詳細は [共通後処理](./section/common_post_process.md) に記載してある
 
 # 結語
 
 暦共通・宣明暦の暦算は以上である
 
-今後は複数の暦を扱い、適宜ページ分割していくことにしたい
-
 # 参考文献
 
 * 内田　正男『日本暦日原典』雄山閣出版 1975(1975)

data/lib/zakuro/calculation/cycle/abstract_remainder.rb

@@ -349,6 +349,51 @@ module Zakuro
         #
         def floor_minute
           result = float_minute
+          # NOTE: 『日本暦日原典』に準じ、少数点以下桁数を2桁とし、3桁目は四捨五入する
+          # これが判明したのは、月の運動による計算を行う際、下記の小余が±1ズレていたことによる
+          #
+          # ## 儀鳳暦
+          # * 大宝 2年 5 大 丁卯 3-1129 702 5 31 (12)22-138 (11)6-1185
+          # * 養老 3年 閏7 小 丁巳 53-767 719 8 20            (17)7-478
+          #
+          # ## 大衍暦
+          # * 神護景雲 2年 5 小 甲辰 40-632 768 5 21 (12)8-363 (11)52-2739
+          # * 仁寿 2年 10 大 癸亥 59-1781 852 11 15 (22)0-2538 (23)16-162
+          #
+          # ## 宣明暦
+          # * 天暦 2年 7 小 戊申 44-8274 948 8 8 (16)53-690 (17)8-2525
+          # * 仁平 2年 3 小 丙申 32-1497 1152 4 7 (8)41-2025 (9)56-3860
+          # * 承久 2年 庚辰   2 小 壬戌 58-7037 1220 3 7 (6)7-3693 (7)22-5529
+          # * 安貞 1年 8 大 丁未 43-5913 1227 9 12 (18)46-6506 (19)1-8341
+          # * 永享 10年 12 大 辛亥 47-2832 1438 12 17 (2)15-1196 (1)59-7760
+          #
+          # これらは月の運行で表の引き当て時に使う大余小余のズレが原因だった
+          # 小余は、小余と秒の合算値で求められるが、次の合算値が『日本暦日原典』で切り上げられていた
+          #
+          # ## 儀鳳暦
+          # |小余|小余（秒 / 12）|合算|
+          # |:----|:----|:----|
+          # |950.4999913|0.5|950.9999913|
+          # |390.7499913|0.25|390.9999913|
+          #
+          # ## 大衍暦
+          # |小余|小余（秒 / 80）|合算|
+          # |:----|:----|:----|
+          # |1697.921259|0.075|1697.996259|
+          # |2656.833759|0.1625|2656.996259|
+          #
+          # ## 宣明暦
+          # |小余|小余（秒 / 100）|合算|
+          # |:----|:----|:----|
+          # |6291.709782|0.29|6291.999782|
+          # |361.9497818|0.05|361.9997818|
+          # |5470.569782|0.43|5470.999782|
+          # |4552.089782|0.91|4552.999782|
+          # |2161.659782|0.34|2161.999782|
+          #
+          # 従って、少数点以下桁数を2桁とし、3桁目は四捨五入することとした
+          result = result.round(2)
+          # 秒は切り捨てる
           result.floor
         end
 
@@ -393,6 +438,19 @@ module Zakuro
           self
         end
 
+        #
+        # 特定の文字フォーマットにして出力する
+        #
+        # @param [String] form フォーマット（大余、小余、秒それぞれを%dで指定する）
+        #
+        # @return [String] フォーマットした結果
+        #
+        def format(form: '%d-%d')
+          return '' if invalid?
+
+          super(form, @day, @minute, @second)
+        end
+
         private
 
         # 繰り上げ、繰り下げ

data/lib/zakuro/calculation/monthly/first_day.rb

@@ -2,6 +2,8 @@
 
 require_relative '../../era/western/calendar'
 
+require_relative '../cycle/abstract_remainder'
+
 # :nodoc:
 module Zakuro
   # :nodoc:
@@ -16,6 +18,8 @@ module Zakuro
         attr_reader :western_date
         # @return [Remainder] 大余小余
         attr_reader :remainder
+        # @return [Remainder] 大余小余（経朔）
+        attr_reader :average_remainder
 
         #
         # 初期化
@@ -24,11 +28,14 @@ module Zakuro
         # @param [Western::Calendar] western_date 大余小余
         #
         def initialize(western_date: Western::Calendar.new,
-                       remainder: Calculation::Cycle::AbstractRemainder.new)
+                       remainder: Calculation::Cycle::AbstractRemainder.new,
+                       average_remainder: Calculation::Cycle::AbstractRemainder.new)
           # 西暦日
           @western_date = western_date
           # 大余小余
           @remainder = remainder
+          # 大余小余（経朔）
+          @average_remainder = average_remainder
         end
 
         #
@@ -39,6 +46,7 @@ module Zakuro
         def initialize_copy(obj)
           @western_date = obj.western_date.clone
           @remainder = obj.remainder.clone
+          @average_remainder = obj.average_remainder.clone
         end
       end
     end

data/lib/zakuro/calculation/option/vanished_date/abstract_parameter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Zakuro
+  # :nodoc:
+  module Calculation
+    # :nodoc:
+    module Option
+      # :nodoc:
+      module VanishedDate
+        #
+        # AbstractParameter 滅日引数
+        #
+        class AbstractParameter
+          # @return [True] 有効
+          # @return [False] 無効
+          attr_reader :valid
+          # @return [Cycle::AbstractRemainder] 「有滅之朔」判定
+          attr_reader :limit
+          # @return [Class] 滅余クラス
+          attr_reader :remainder_class
+
+          #
+          # 初期化
+          #
+          # @param [True, False] valid 有効/無効
+          # @param [Cycle::AbstractRemainder] limit 「有滅之朔」判定
+          # @param [Class] remainder_class 滅余クラス
+          #
+          def initialize(valid: false, limit: Cycle::AbstractRemainder.new,
+                         remainder_class: Object)
+            @valid = valid
+            @limit = limit
+            @remainder_class = remainder_class
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zakuro/calculation/option/vanished_date/location.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# :nodoc:
+module Zakuro
+  # :nodoc:
+  module Calculation
+    # :nodoc:
+    module Option
+      # :nodoc:
+      module VanishedDate
+        #
+        # Location 滅日位置
+        #
+        class Location
+          # @return [Integer] 理想上の月日数
+          IDEAL_MONTH = 30
+
+          # @return [Context::Context] 暦コンテキスト
+          attr_reader :context
+          # @return [True] 有効
+          # @return [False] 無効
+          attr_reader :valid
+          # @return [Cycle::AbstractRemainder] 「有没之気」判定
+          attr_reader :limit
+          # @return [Cycle::AbstractRemainder] 経朔
+          attr_reader :average_remainder
+          # @return [Class] 滅余クラス
+          attr_reader :remainder_class
+
+          #
+          # 初期化
+          #
+          # @param [Context::Context] context 暦コンテキスト
+          # @param [Cycle::AbstractRemainder] average_remainder 経朔
+          #
+          def initialize(context:, average_remainder:)
+            parameter = context.resolver.vanished_date_parameter.new
+            @context = context
+            @valid = parameter.valid
+            @limit = parameter.limit
+            @average_remainder = average_remainder
+            @remainder_class = parameter.remainder_class
+          end
+
+          #
+          # 不正か
+          #
+          # @return [True] 不正
+          # @return [False] 不正なし
+          #
+          def invalid?
+            !@valid
+          end
+
+          #
+          # 滅日が存在するか？
+          #
+          # @return [True] 存在あり
+          # @return [False] 存在なし
+          #
+          def exist?
+            minute_later = average_remainder.class.new(
+              day: 0, minute: average_remainder.minute, second: average_remainder.second
+            )
+            minute_later < limit
+          end
+
+          #
+          # 「滅余」を返す
+          #
+          # @return [Cycle::AbstractRemainder] 滅余
+          #
+          def get
+            # 経朔の小余 * 30
+            minute = remainder_class.new(day: 0, minute: IDEAL_MONTH * average_remainder.minute, second: 0)
+            day = remainder_class.new(day: average_remainder.day, minute: 0, second: 0)
+
+            minute.add(day)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zakuro/calculation/range/medieval_annual_range.rb

@@ -64,13 +64,15 @@ module Zakuro
 
             # 14ヶ月分を生成する（閏年で最大13ヶ月 + 末月の大小/二十四節気を求めるために必要な月）
             (0..13).each do |_index|
+              average_remainder = lunar_phase.average_remainder.clone
               adjusted = lunar_phase.next_month
 
               result.push(
                 Monthly::InitializedMonth.new(
-                  context: context,
-                  month_label: Monthly::MonthLabel.new,
-                  first_day: Monthly::FirstDay.new(remainder: adjusted),
+                  context: context, month_label: Monthly::MonthLabel.new,
+                  first_day: Monthly::FirstDay.new(
+                    remainder: adjusted, average_remainder: average_remainder
+                  ),
                   phase_index: 0
                 )
               )

data/lib/zakuro/calculation/range/transfer/gengou_scroller.rb

@@ -43,6 +43,7 @@ module Zakuro
                   month_label: month.month_label,
                   first_day: Monthly::FirstDay.new(
                     remainder: month.first_day.remainder,
+                    average_remainder: month.first_day.average_remainder,
                     western_date: gengou.start_date.clone
                   ),
                   solar_terms: month.solar_terms, gengou: gengou

data/lib/zakuro/calculation/stella/lunar/abstract_location.rb

@@ -19,17 +19,21 @@ module Zakuro
         attr_reader :western_year
         # @return [Cycle::LunarRemainder] 大余小余（初回：昨年天正閏余）
         attr_reader :remainder
+        # @return [Cycle::LunarRemainder] 弦（1朔望月の1/4）
+        attr_reader :quarter
 
         #
         # 初期化
         #
         # @param [Cycle::LunarRemainder] lunar_age 天正閏余（大余小余）
+        # @param [Cycle::LunarRemainder] quarter 弦（1朔望月の1/4）
         # @param [Integer] western_year 西暦年
         #
-        def initialize(lunar_age:, western_year:)
+        def initialize(lunar_age:, quarter:, western_year:)
           @calculated = false
           @western_year = western_year
           @remainder = lunar_age
+          @quarter = quarter
         end
 
         #
@@ -43,7 +47,7 @@ module Zakuro
         # 弦の分だけ月地点を進める
         #
         def add_quarter
-          # abstract
+          remainder.add!(quarter)
         end
 
         #

data/lib/zakuro/calculation/stella/lunar/choukei_value.rb

@@ -13,6 +13,9 @@ module Zakuro
       #
       module ChoukeiValue
         class << self
+          # @return [Output::Logger] ロガー
+          LOGGER = Output::Logger.new(location: 'choukei_value')
+
           #
           # 四捨五入した大余を返す
           #
@@ -23,7 +26,12 @@ module Zakuro
           # @return [Integer] 累計値（大余）
           #
           def rounded_day(per:, denominator:, minute:)
+            # LOGGER.debug("minute: #{minute}")
+
             remainder_minute = Type::OldFloat.new((per * minute).to_f)
+
+            # LOGGER.debug("remainder_minute.get: #{remainder_minute.get}")
+
             day = day_only(remainder_minute: remainder_minute.get, denominator: denominator)
             # 繰り上げ結果を足す
             day += carried_minute(remainder_minute: remainder_minute, denominator: denominator)
@@ -42,6 +50,12 @@ module Zakuro
           # @return [Float] 小余
           #
           def remainder_without_second(remainder:)
+            # LOGGER.debug("minute.to_f: #{remainder.minute.to_f}")
+            # LOGGER.debug("second.to_f: #{remainder.second.to_f}")
+            # LOGGER.debug("base_minute: #{remainder.base_minute}")
+            # LOGGER.debug(
+            #   "second.to_f / base_minute: #{remainder.second.to_f / remainder.base_minute}"
+            # )
             adjusted = remainder.class.new(
               day: remainder.day, minute: remainder.floor_minute, second: 0
             )