astro_chart 0.1.0 → 0.4.0

data/lib/astro_chart/progressions.rb

@@ -0,0 +1,68 @@
+require_relative "time_conversion"
+require_relative "transits"
+
+module AstroChart
+  # Secondary progressions (二次推運): "a day for a year".
+  #
+  # For a target date N years after birth, the progressed chart is the sky
+  # N *days* after birth: jd_prog = jd_natal + years_elapsed, where
+  # years_elapsed = (jd_target - jd_natal) / 365.2425.
+  #
+  # Typical usage with a Chart#generate result:
+  #
+  #   AstroChart::Progressions.secondary(natal_chart, "2026-07-24")
+  module Progressions
+    # Mean Gregorian year length in days (matches the calendar's 400-year cycle).
+    DAYS_PER_YEAR = 365.2425
+
+    # Secondary-progressed positions for a natal chart at a target date.
+    #
+    # natal_chart: a Chart#generate result hash (its "input" block supplies
+    #   birth date/time/timezone, so jd_natal is reconstructed exactly).
+    # target_date: "YYYY-MM-DD". The target moment is taken at the same
+    #   local birth time + timezone, so whole calendar years elapse cleanly.
+    # orb_limit: keep only progressed-to-natal aspects with orb <= limit
+    #   (default 1.0 — progressions move slowly, only exact contacts matter).
+    #
+    # Returns:
+    #   {
+    #     "progressed_jd" => 2447926.72,
+    #     "years_elapsed" => 30.0,
+    #     "planets" => [ { "planet" => "太陽", "zodiac" => "獅子座",
+    #                      "degree" => 9.87, "total_degree" => 129.87,
+    #                      "natal_house" => 3 }, ... 12 entries ],
+    #     "aspects_to_natal" => [ { "progressed_planet" => "月亮",
+    #                               "natal_planet" => "金星",
+    #                               "aspect_type" => "三分相", "orb" => 0.4 }, ... ]
+    #   }
+    #
+    # aspects_to_natal are sorted by orb (tightest first).
+    def self.secondary(natal_chart, target_date, orb_limit: 1.0)
+      input = natal_chart&.dig("input")
+      if input.nil? || input["birth_date"].nil? || input["birth_time"].nil? || input["timezone"].nil?
+        raise ArgumentError, "chart has no input data (birth_date/birth_time/timezone required)"
+      end
+
+      jd_natal  = TimeConversion.to_julian_day(input["birth_date"], input["birth_time"], input["timezone"])
+      jd_target = TimeConversion.to_julian_day(target_date, input["birth_time"], input["timezone"])
+
+      years_elapsed = (jd_target - jd_natal) / DAYS_PER_YEAR
+      jd_prog = jd_natal + years_elapsed # a day for a year
+
+      progressed_positions = Planets.calculate_positions(jd_prog)
+      natal_positions      = Synastry.positions_from_chart(natal_chart)
+      natal_cusps          = Synastry.cusps_from_chart(natal_chart)
+
+      {
+        "progressed_jd" => jd_prog,
+        "years_elapsed" => years_elapsed.round(2),
+        "planets" => Transits.planet_details(progressed_positions, natal_cusps),
+        "aspects_to_natal" => Transits.aspects_to_natal(
+          progressed_positions, natal_positions,
+          orb_limit: orb_limit,
+          keys: %w[progressed_planet natal_planet]
+        ),
+      }
+    end
+  end
+end

data/lib/astro_chart/pure/core.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module AstroChart
+  module Pure
+    # Core — MIT-safe 純 Ruby 天文基建（零外部依賴）。
+    #
+    # 只使用公開文獻公式，不參考 Swiss Ephemeris C 原始碼：
+    #   - 儒略日：Jean Meeus, "Astronomical Algorithms" 2nd ed., Ch. 7 (eq. 7.1)
+    #   - ΔT（TT−UT）：Espenak & Meeus 多項式擬合
+    #     （NASA Eclipse website, "Polynomial Expressions for Delta T (ΔT)",
+    #       Five Millennium Canon of Solar Eclipses: -1999 to +3000）
+    #   - 章動（Δψ / Δε）：Meeus Ch. 22（IAU 1980 序列截斷，振幅最大 13 項）
+    #   - 平黃赤交角：Meeus eq. 22.2
+    #   - 平恆星時 GMST：Meeus Ch. 12 (eq. 12.4，等同 IAU 1982 GMST)
+    #   - 視恆星時 = GMST + Δψ·cos(ε_true)（Meeus Ch. 12）
+    #
+    # 時間尺度慣例（呼叫者必須遵守，弄錯會差 ~ΔT ≈ 70s → 月亮 ~0.01°）：
+    #   - julday / gmst_deg / apparent_sidereal_deg 吃 **JD(UT)**
+    #   - nutation / mean_obliquity / true_obliquity 吃 **JD(TT)**（先過 jd_tt 換算）
+    #
+    # 公開 API（module_function，皆回傳 Float 或 [Float, Float]）：
+    #   Core.julday(year, month, day, hour)   -> JD(UT)；hour 為十進位 UT 小時
+    #   Core.delta_t(jd_ut)                   -> ΔT 秒（TT − UT）
+    #   Core.jd_tt(jd_ut)                     -> JD(TT) = jd_ut + ΔT/86400
+    #   Core.nutation(jd_tt)                  -> [Δψ_deg, Δε_deg]（度）
+    #   Core.mean_obliquity(jd_tt)            -> ε₀（度）
+    #   Core.true_obliquity(jd_tt)            -> ε = ε₀ + Δε（度）
+    #   Core.gmst_deg(jd_ut)                  -> 格林威治平恆星時（度，[0,360)）
+    #   Core.apparent_sidereal_deg(jd_ut)     -> 格林威治視恆星時（度，[0,360)）
+    #   Core.norm360(deg)                     -> 正規化到 [0, 360)
+    #   Core::DomainError                     -> 超出適用範圍時 raise（顯性失敗）
+    module Core
+      DEG2RAD = Math::PI / 180.0
+      RAD2DEG = 180.0 / Math::PI
+
+      # 超出公式適用範圍或演算法未收斂時丟出——失敗必須顯性，
+      # 不可靜默回傳一個看似正常、實則錯誤的值。
+      class DomainError < StandardError; end
+
+      module_function
+
+      # --- 儒略日（Meeus 7.1，Gregorian） ---
+      # hour 為十進位 UT 小時（例 1.5 = 01:30 UT）
+      def julday(year, month, day, hour)
+        y = year
+        m = month
+        if m <= 2
+          y -= 1
+          m += 12
+        end
+        a = (y / 100.0).floor
+        b = 2 - a + (a / 4.0).floor
+        (365.25 * (y + 4716)).floor + (30.6001 * (m + 1)).floor +
+          day + hour / 24.0 + b - 1524.5
+      end
+
+      # --- ΔT = TT − UT（秒） ---
+      # Espenak & Meeus 分段多項式（NASA Eclipse website，涵蓋 -1999..+3000）。
+      # 決策年 y 用儒略年近似（y = 2000 + (JD-J2000)/365.25），與 E&M 定義的
+      # y = year + (month-0.5)/12 差 < 半個月，對逐年平滑的 ΔT 曲線影響 < 0.01s。
+      # 注意：2005 之後為預測值，與實測（IERS）可差數秒 → 月亮 ~0.001°，
+      # 在本專案 0.01° 精度預算內。
+      def delta_t(jd_ut)
+        y = 2000.0 + (jd_ut - 2451545.0) / 365.25
+
+        if y < -500.0
+          u = (y - 1820.0) / 100.0
+          -20.0 + 32.0 * u * u
+        elsif y < 500.0
+          u = y / 100.0
+          10583.6 - 1014.41 * u + 33.78311 * u**2 - 5.952053 * u**3 -
+            0.1798452 * u**4 + 0.022174192 * u**5 + 0.0090316521 * u**6
+        elsif y < 1600.0
+          u = (y - 1000.0) / 100.0
+          1574.2 - 556.01 * u + 71.23472 * u**2 + 0.319781 * u**3 -
+            0.8503463 * u**4 - 0.005050998 * u**5 + 0.0083572073 * u**6
+        elsif y < 1700.0
+          t = y - 1600.0
+          120.0 - 0.9808 * t - 0.01532 * t**2 + t**3 / 7129.0
+        elsif y < 1800.0
+          t = y - 1700.0
+          8.83 + 0.1603 * t - 0.0059285 * t**2 + 0.00013336 * t**3 - t**4 / 1_174_000.0
+        elsif y < 1860.0
+          t = y - 1800.0
+          13.72 - 0.332447 * t + 0.0068612 * t**2 + 0.0041116 * t**3 -
+            0.00037436 * t**4 + 0.0000121272 * t**5 - 0.0000001699 * t**6 +
+            0.000000000875 * t**7
+        elsif y < 1900.0
+          t = y - 1860.0
+          7.62 + 0.5737 * t - 0.251754 * t**2 + 0.01680668 * t**3 -
+            0.0004473624 * t**4 + t**5 / 233_174.0
+        elsif y < 1920.0
+          t = y - 1900.0
+          -2.79 + 1.494119 * t - 0.0598939 * t**2 + 0.0061966 * t**3 - 0.000197 * t**4
+        elsif y < 1941.0
+          t = y - 1920.0
+          21.20 + 0.84493 * t - 0.076100 * t**2 + 0.0020936 * t**3
+        elsif y < 1961.0
+          t = y - 1950.0
+          29.07 + 0.407 * t - t**2 / 233.0 + t**3 / 2547.0
+        elsif y < 1986.0
+          t = y - 1975.0
+          45.45 + 1.067 * t - t**2 / 260.0 - t**3 / 718.0
+        elsif y < 2005.0
+          t = y - 2000.0
+          63.86 + 0.3345 * t - 0.060374 * t**2 + 0.0017275 * t**3 +
+            0.000651814 * t**4 + 0.00002373599 * t**5
+        elsif y < 2050.0
+          t = y - 2000.0
+          62.92 + 0.32217 * t + 0.005589 * t**2
+        elsif y < 2150.0
+          -20.0 + 32.0 * ((y - 1820.0) / 100.0)**2 - 0.5628 * (2150.0 - y)
+        else
+          u = (y - 1820.0) / 100.0
+          -20.0 + 32.0 * u * u
+        end
+      end
+
+      # --- JD(TT) = JD(UT) + ΔT/86400 ---
+      def jd_tt(jd_ut)
+        jd_ut + delta_t(jd_ut) / 86_400.0
+      end
+
+      # --- 章動（Meeus Ch. 22，IAU 1980 截斷序列） ---
+      # 係數單位：0.0001 角秒。取振幅最大的 13 項（Δψ 主項 -17.1996" sinΩ 起），
+      # 截斷誤差 < 0.0004"，遠小於 0.01° 目標。
+      # 各項引數為 [D, M, M', F, Ω] 的整數倍組合（Meeus Table 22.A 前段）。
+      NUTATION_TERMS = [
+        # [D, M, Mp, F, Om,   psi_sin,  psi_sin_t,  eps_cos, eps_cos_t]
+        [0,  0, 0, 0, 1, -171_996.0, -174.2, 92_025.0,  8.9],
+        [-2, 0, 0, 2, 2,  -13_187.0,   -1.6,  5736.0,  -3.1],
+        [0,  0, 0, 2, 2,   -2274.0,    -0.2,   977.0,  -0.5],
+        [0,  0, 0, 0, 2,    2062.0,     0.2,  -895.0,   0.5],
+        [0,  1, 0, 0, 0,    1426.0,    -3.4,    54.0,  -0.1],
+        [0,  0, 1, 0, 0,     712.0,     0.1,    -7.0,   0.0],
+        [-2, 1, 0, 2, 2,    -517.0,     1.2,   224.0,  -0.6],
+        [0,  0, 0, 2, 1,    -386.0,    -0.4,   200.0,   0.0],
+        [0,  0, 1, 2, 2,    -301.0,     0.0,   129.0,  -0.1],
+        [-2, -1, 0, 2, 2,    217.0,    -0.5,   -95.0,   0.3],
+        [-2, 0, 1, 0, 0,    -158.0,     0.0,     0.0,   0.0],
+        [-2, 0, 0, 2, 1,     129.0,     0.1,   -70.0,   0.0],
+        [0,  0, -1, 2, 2,    123.0,     0.0,   -53.0,   0.0]
+      ].freeze
+
+      # 回傳 [Δψ_deg, Δε_deg]（度）。引數時間尺度為 **TT**。
+      def nutation(jd_tt)
+        t = (jd_tt - 2451545.0) / 36525.0
+
+        # 基本引數（Meeus Ch. 22，度）
+        d  = 297.85036 + 445_267.111480 * t - 0.0019142 * t * t + t**3 / 189_474.0
+        m  = 357.52772 + 35_999.050340 * t - 0.0001603 * t * t - t**3 / 300_000.0
+        mp = 134.96298 + 477_198.867398 * t + 0.0086972 * t * t + t**3 / 56_250.0
+        f  = 93.27191 + 483_202.017538 * t - 0.0036825 * t * t + t**3 / 327_270.0
+        om = 125.04452 - 1934.136261 * t + 0.0020708 * t * t + t**3 / 450_000.0
+
+        dpsi_01as = 0.0 # 單位 0.0001"
+        deps_01as = 0.0
+        NUTATION_TERMS.each do |cd, cm, cmp, cf, com, ps, pst, ec, ect|
+          arg = (cd * d + cm * m + cmp * mp + cf * f + com * om) * DEG2RAD
+          dpsi_01as += (ps + pst * t) * Math.sin(arg)
+          deps_01as += (ec + ect * t) * Math.cos(arg)
+        end
+
+        [dpsi_01as * 0.0001 / 3600.0, deps_01as * 0.0001 / 3600.0]
+      end
+
+      # --- 平黃赤交角（Meeus 22.2，度）。引數時間尺度為 **TT**。 ---
+      # 23°26'21.448" - 46.8150"T - 0.00059"T² + 0.001813"T³
+      def mean_obliquity(jd_tt)
+        t = (jd_tt - 2451545.0) / 36525.0
+        23.0 + 26.0 / 60.0 + 21.448 / 3600.0 -
+          (46.8150 * t + 0.00059 * t * t - 0.001813 * t**3) / 3600.0
+      end
+
+      # --- 真黃赤交角 ε = ε₀ + Δε（度）。引數時間尺度為 **TT**。 ---
+      def true_obliquity(jd_tt)
+        mean_obliquity(jd_tt) + nutation(jd_tt)[1]
+      end
+
+      # --- 平恆星時 GMST（Meeus 12.4 / IAU 1982），回傳度。引數為 **UT**。 ---
+      def gmst_deg(jd_ut)
+        t = (jd_ut - 2451545.0) / 36525.0
+        norm360(
+          280.46061837 +
+            360.98564736629 * (jd_ut - 2451545.0) +
+            0.000387933 * t * t -
+            t * t * t / 38_710_000.0
+        )
+      end
+
+      # --- 視恆星時 = GMST + Δψ·cos(ε_true)（度）。引數為 **UT**。 ---
+      # 章動與交角的引數在內部換算為 TT。
+      def apparent_sidereal_deg(jd_ut)
+        tt = jd_tt(jd_ut)
+        dpsi_deg, = nutation(tt)
+        eps_rad = true_obliquity(tt) * DEG2RAD
+        norm360(gmst_deg(jd_ut) + dpsi_deg * Math.cos(eps_rad))
+      end
+
+      # --- 正規化到 [0, 360) ---
+      def norm360(deg)
+        deg %= 360.0
+        # Ruby 的 float % 對正模數永不為負，但極小負數（如 -1e-16 % 360.0）
+        # 會因浮點捨入得到恰好 360.0，違反 [0, 360) 契約 → 下游 floor(deg/30) 會得 12。
+        deg >= 360.0 ? 0.0 : deg
+      end
+    end
+  end
+end

data/lib/astro_chart/pure/houses.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative "core"
+
+module AstroChart
+  module Pure
+    # Houses — MIT-safe 純 Ruby Placidus 宮位（ASC / MC / 12 宮頭）。
+    #
+    # 零外部依賴、不參考 Swiss Ephemeris C 原始碼，僅使用公開文獻公式：
+    #   - 視恆星時 / 章動 / 黃赤交角：見 Core（Meeus Ch. 12 / 22）
+    #   - ASC / MC：標準球面天文公式（Meeus Ch. 13 座標轉換推得）
+    #   - Placidus 宮頭：古典半弧迭代法（半日弧 SA = arccos(-tanφ·tanδ)，
+    #     宮頭 11/12 位於 RAMC 東側 1/3、2/3 半日弧處；宮頭 2/3 以半夜弧對應）
+    #
+    # 公開 API：
+    #   Houses.calc(jd_ut, lat, lon, hsys = "P")
+    #     -> { "cusps" => [12 floats], "ascendant" => Float, "mc" => Float }
+    #     欄位與 AstroChart::Ext.houses(jd, lat, lon, hsys.ord) 相同。
+    #
+    # 宮位制：
+    #   "P" — Placidus（預設）。適用範圍 |lat| < ~66°（極圈內無定義），
+    #         超出範圍或迭代未收斂時 raise Core::DomainError（顯性失敗，不靜默 clamp）。
+    #   "W" — 整宮制（Whole Sign）。宮頭 1 = ASC 所在星座起點（floor(asc/30)*30），
+    #         其後每宮 +30°。ASC / MC 計算與 Placidus 相同（整宮制只改宮頭），
+    #         唯極圈內（|lat| > 90° − ε ≈ 66.56°）另套用東昇點修正（見
+    #         east_ascendant）——標準公式在該區可能傳回差 180° 的西方交點。
+    #         於 |lat| < 90° 皆有定義（lat = ±90° 時 tanφ 發散，ASC 本身無定義）。
+    module Houses
+      DEG2RAD = Core::DEG2RAD
+      RAD2DEG = Core::RAD2DEG
+
+      module_function
+
+      # jd_ut: UT 儒略日；lat: 地理緯度（北正）；lon: 地理經度（東正）
+      # hsys: "P"（Placidus，預設）或 "W"（整宮制）
+      def calc(jd_ut, lat, lon, hsys = "P")
+        tt = Core.jd_tt(jd_ut)
+        eps = Core.true_obliquity(tt) * DEG2RAD          # 真黃赤交角（弧度）
+        ast_deg = Core.apparent_sidereal_deg(jd_ut)      # 視恆星時（度）
+        armc = Core.norm360(ast_deg + lon)               # 天頂赤經 RAMC
+
+        phi = lat * DEG2RAD
+        mc  = mc_longitude(armc, eps)
+        asc = asc_longitude(armc, eps, phi)
+
+        cusps =
+          case hsys
+          when "W"
+            # 極圈內（|lat| > 90° − ε ≈ 66.56°）標準 atan2 公式可能傳回西方
+            # 交點（差 180°）；整宮制在極圈內仍有定義，故此處修正為東昇點。
+            # 極圈外此修正恆為 no-op；Placidus 路徑不套用（維持原輸出）。
+            asc = east_ascendant(asc, mc)
+            whole_sign_cusps(asc)
+          when "E"
+            # 等宮制：宮頭 1 = ASC，其後每宮 +30°。與整宮制同樣在 |lat| < 90°
+            # 皆有定義，故一併套用東昇點修正。
+            asc = east_ascendant(asc, mc)
+            equal_cusps(asc)
+          when "O"
+            # Porphyry：四大軸（ASC/IC/DSC/MC）之間的黃道弧各三等分。純幾何，
+            # 不需半弧迭代，於 |lat| < 90° 皆有定義。
+            asc = east_ascendant(asc, mc)
+            porphyry_cusps(asc, mc)
+          else
+            placidus_cusps(armc, eps, phi, asc, mc)
+          end
+
+        { "cusps" => cusps, "ascendant" => asc, "mc" => mc }
+      end
+
+      # --- Placidus 12 宮頭 ---
+      def placidus_cusps(armc, eps, phi, asc, mc)
+        # Placidus 半弧迭代：宮頭 11、12（地平上，RAMC 東側）與 2、3（地平下）
+        c11 = placidus_cusp(armc, eps, phi, 30.0,  1.0 / 3.0, :diurnal)
+        c12 = placidus_cusp(armc, eps, phi, 60.0,  2.0 / 3.0, :diurnal)
+        c2  = placidus_cusp(armc, eps, phi, 120.0, 2.0 / 3.0, :nocturnal)
+        c3  = placidus_cusp(armc, eps, phi, 150.0, 1.0 / 3.0, :nocturnal)
+
+        cusps = Array.new(12)
+        cusps[0]  = asc                        # 第 1 宮 = ASC
+        cusps[1]  = c2
+        cusps[2]  = c3
+        cusps[3]  = Core.norm360(mc + 180.0)   # 第 4 宮 = MC 對沖
+        cusps[4]  = Core.norm360(c11 + 180.0)
+        cusps[5]  = Core.norm360(c12 + 180.0)
+        cusps[6]  = Core.norm360(asc + 180.0)  # 第 7 宮 = ASC 對沖
+        cusps[7]  = Core.norm360(c2 + 180.0)
+        cusps[8]  = Core.norm360(c3 + 180.0)
+        cusps[9]  = mc                         # 第 10 宮 = MC
+        cusps[10] = c11
+        cusps[11] = c12
+        cusps
+      end
+
+      # --- 東昇點修正 ---
+      # ASC 依定義位於 MC 東側半圓：(asc − mc) mod 360 ∈ (0°, 180°)。
+      # 極圈內原始公式可能落在西側半圓（實為降點），此時加 180°。
+      # 與 Swiss Ephemeris 極區行為一致（tmp/explore_polar_asc.rb 驗證 400 例全符）。
+      def east_ascendant(asc, mc)
+        ((asc - mc) % 360.0) < 180.0 ? asc : Core.norm360(asc + 180.0)
+      end
+
+      # --- 整宮制 12 宮頭 ---
+      # 宮頭 1 = ASC 所在星座 0°，其後每宮 +30°（模 360）。
+      def whole_sign_cusps(asc)
+        base = (asc / 30.0).floor * 30.0
+        Array.new(12) { |i| (base + 30.0 * i) % 360.0 }
+      end
+
+      # --- 等宮制 12 宮頭 ---
+      # 宮頭 1 = ASC 本身，其後每宮 +30°（模 360）。MC 仍照常算出並回傳，
+      # 但等宮制的第 10 宮頭為 ASC+270°，不等於 MC（MC 在宮內浮動）。
+      def equal_cusps(asc)
+        Array.new(12) { |i| (asc + 30.0 * i) % 360.0 }
+      end
+
+      # --- Porphyry 12 宮頭 ---
+      # 依黃道經度遞增，四大軸順序為 ASC(1) → IC(4) → DSC(7) → MC(10)。每個
+      # 象限的黃道弧三等分，得中間兩個宮頭：
+      #   1→4：ASC..IC 弧 → 宮頭 2、3      4→7：IC..DSC 弧 → 宮頭 5、6
+      #   7→10：DSC..MC 弧 → 宮頭 8、9     10→1：MC..ASC 弧 → 宮頭 11、12
+      def porphyry_cusps(asc, mc)
+        ic  = Core.norm360(mc + 180.0)   # 第 4 宮 = MC 對沖
+        dsc = Core.norm360(asc + 180.0)  # 第 7 宮 = ASC 對沖
+
+        q1 = (ic  - asc) % 360.0  # ASC → IC
+        q2 = (dsc - ic)  % 360.0  # IC  → DSC
+        q3 = (mc  - dsc) % 360.0  # DSC → MC
+        q4 = (asc - mc)  % 360.0  # MC  → ASC
+
+        cusps = Array.new(12)
+        cusps[0]  = asc
+        cusps[1]  = Core.norm360(asc + q1 / 3.0)
+        cusps[2]  = Core.norm360(asc + 2.0 * q1 / 3.0)
+        cusps[3]  = ic
+        cusps[4]  = Core.norm360(ic + q2 / 3.0)
+        cusps[5]  = Core.norm360(ic + 2.0 * q2 / 3.0)
+        cusps[6]  = dsc
+        cusps[7]  = Core.norm360(dsc + q3 / 3.0)
+        cusps[8]  = Core.norm360(dsc + 2.0 * q3 / 3.0)
+        cusps[9]  = mc
+        cusps[10] = Core.norm360(mc + q4 / 3.0)
+        cusps[11] = Core.norm360(mc + 2.0 * q4 / 3.0)
+        cusps
+      end
+
+      # --- MC：天頂赤經 → 黃道經度 ---
+      # tan λ_MC = tan(ARMC) / cos ε，以 atan2 處理象限
+      def mc_longitude(armc_deg, eps)
+        ra = armc_deg * DEG2RAD
+        Core.norm360(Math.atan2(Math.sin(ra), Math.cos(ra) * Math.cos(eps)) * RAD2DEG)
+      end
+
+      # --- ASC：標準公式 ---
+      # λ_ASC = atan2( cos ARMC, -(sin ARMC · cos ε + tan φ · sin ε) )
+      def asc_longitude(armc_deg, eps, phi)
+        ra = armc_deg * DEG2RAD
+        Core.norm360(
+          Math.atan2(
+            Math.cos(ra),
+            -(Math.sin(ra) * Math.cos(eps) + Math.tan(phi) * Math.sin(eps))
+          ) * RAD2DEG
+        )
+      end
+
+      # --- Placidus 宮頭半弧迭代 ---
+      # 定義：黃道上一點 (α, δ)，半日弧 SA_d = arccos(-tanφ·tanδ)、半夜弧 SA_n = arccos(tanφ·tanδ)。
+      #   宮頭 11：α = RAMC + (1/3)·SA_d      宮頭 12：α = RAMC + (2/3)·SA_d
+      #   宮頭 2 ：α = RAMC + 180 - (2/3)·SA_n 宮頭 3 ：α = RAMC + 180 - (1/3)·SA_n
+      # 黃道點的赤緯由 tan δ = tan ε · sin α 得出，固定點迭代至收斂。
+      # offset_deg：初值偏移（赤道情形的精確解）；frac：半弧比例；mode：地平上/下。
+      def placidus_cusp(armc_deg, eps, phi, offset_deg, frac, mode)
+        tan_phi = Math.tan(phi)
+        tan_eps = Math.tan(eps)
+        ra = (armc_deg + offset_deg) * DEG2RAD
+        armc_rad = armc_deg * DEG2RAD
+
+        converged = false
+        60.times do
+          dec = Math.atan(tan_eps * Math.sin(ra)) # 黃道點赤緯
+          x = tan_phi * Math.tan(dec)
+          if x.abs > 1.0
+            # 極圈內該點無升落，Placidus 無定義。顯性失敗，不靜默 clamp。
+            raise Core::DomainError,
+                  "Placidus 在此緯度無定義（|tanφ·tanδ| = #{x.abs.round(4)} > 1，lat=#{(phi * RAD2DEG).round(4)}°）"
+          end
+          new_ra =
+            if mode == :diurnal
+              armc_rad + frac * Math.acos(-x)
+            else
+              armc_rad + Math::PI - frac * Math.acos(x)
+            end
+          step = (new_ra - ra).abs
+          ra = new_ra # 先採納本次結果，收斂時回傳的才是最終值
+          if step < 1e-9 * DEG2RAD
+            converged = true
+            break
+          end
+        end
+        raise Core::DomainError, "Placidus 宮頭迭代 60 次未收斂" unless converged
+
+        # 赤經 → 黃道經度：tan λ = tan α / cos ε
+        Core.norm360(Math.atan2(Math.sin(ra), Math.cos(ra) * Math.cos(eps)) * RAD2DEG)
+      end
+    end
+  end
+end