astro_chart 0.2.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/houses.rb

@@ -13,12 +13,18 @@ module AstroChart
     #     宮頭 11/12 位於 RAMC 東側 1/3、2/3 半日弧處；宮頭 2/3 以半夜弧對應）
     #
     # 公開 API：
-    #   Houses.calc(jd_ut, lat, lon)
+    #   Houses.calc(jd_ut, lat, lon, hsys = "P")
     #     -> { "cusps" => [12 floats], "ascendant" => Float, "mc" => Float }
-    #     欄位與 AstroChart::Ext.houses(jd, lat, lon, "P".ord) 相同。
+    #     欄位與 AstroChart::Ext.houses(jd, lat, lon, hsys.ord) 相同。
     #
-    # 適用範圍：|lat| < ~66°（Placidus 在極圈內無定義）。
-    # 超出範圍或迭代未收斂時 raise Core::DomainError（顯性失敗，不靜默 clamp）。
+    # 宮位制：
+    #   "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
@@ -26,7 +32,8 @@ module AstroChart
       module_function
 
       # jd_ut: UT 儒略日；lat: 地理緯度（北正）；lon: 地理經度（東正）
-      def calc(jd_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)      # 視恆星時（度）
@@ -36,6 +43,33 @@ module AstroChart
         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)
@@ -55,8 +89,59 @@ module AstroChart
         cusps[9]  = mc                         # 第 10 宮 = MC
         cusps[10] = c11
         cusps[11] = c12
+        cusps
+      end
 
-        { "cusps" => cusps, "ascendant" => asc, "mc" => mc }
+      # --- 東昇點修正 ---
+      # 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：天頂赤經 → 黃道經度 ---

data/lib/astro_chart/pure.rb

@@ -49,15 +49,20 @@ module AstroChart
       end
     end
 
-    # House cusps + ascendant + MC. Only Placidus is implemented.
-    # hsys accepts "P" or 80 ("P".ord) to mirror the C extension's int argument.
+    # House cusps + ascendant + MC. Placidus ("P") and Whole Sign ("W").
+    # hsys accepts "P"/"W" or 80/87 (ord values) to mirror the C extension's int argument.
     def houses(jd_ut, latitude, longitude, hsys = "P")
-      unless hsys == "P" || hsys == 80
+      case hsys
+      when "P", 80 then Houses.calc(jd_ut, latitude, longitude, "P")
+      when "W", 87 then Houses.calc(jd_ut, latitude, longitude, "W")
+      when "E", 69 then Houses.calc(jd_ut, latitude, longitude, "E")
+      when "O", 79 then Houses.calc(jd_ut, latitude, longitude, "O")
+      else
         raise ArgumentError,
-              "unsupported house system #{hsys.inspect} (pure backend only supports Placidus: \"P\" / 80)"
+              "unsupported house system #{hsys.inspect} " \
+              "(pure backend supports Placidus \"P\"/80, Whole Sign \"W\"/87, " \
+              "Equal \"E\"/69 and Porphyry \"O\"/79)"
       end
-
-      Houses.calc(jd_ut, latitude, longitude)
     end
   end
 end

data/lib/astro_chart/solar_arc.rb

@@ -0,0 +1,59 @@
+require_relative "time_conversion"
+require_relative "planets"
+require_relative "synastry"
+require_relative "transits"
+
+module AstroChart
+  # Solar arc directions (太陽弧正向推運): advance every natal point by a single
+  # arc — the distance the secondary-progressed Sun has travelled since birth.
+  # Unlike secondary progressions (where each body moves at its own rate),
+  # solar arc moves the whole chart rigidly, so directed-to-natal aspects
+  # perfect at a rate of ~1° per year of life.
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   result = AstroChart::SolarArc.directions(natal, "2026-07-24")
+  #   result["arc"]              # degrees the chart has been directed (~age)
+  #   result["planets"]          # directed positions + natal-house placement
+  #   result["aspects_to_natal"] # directed→natal aspects, sorted by orb
+  module SolarArc
+    DAYS_PER_YEAR = 365.2425 # matches Progressions
+
+    SUN = "太陽"
+
+    # natal_chart: a Chart#generate result hash (its input block gives birth
+    #   date/time/timezone). target_date: "YYYY-MM-DD".
+    # orb_limit: keep only directed-to-natal aspects within this orb (default
+    #   1.0 — solar arc is slow, only near-exact contacts matter).
+    def self.directions(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"])
+      jd_prog   = jd_natal + (jd_target - jd_natal) / DAYS_PER_YEAR # a day for a year
+
+      natal_positions = Synastry.positions_from_chart(natal_chart)
+      natal_cusps     = Synastry.cusps_from_chart(natal_chart)
+
+      natal_sun = natal_positions[SUN] || Planets.calculate_positions(jd_natal)[SUN]
+      prog_sun  = Planets.calculate_positions(jd_prog)[SUN]
+      # The Sun only ever moves forward, so the forward arc is the plain
+      # modular difference (< 360° for any human lifespan).
+      arc = (prog_sun - natal_sun) % 360.0
+
+      directed_positions = natal_positions.transform_values { |lon| (lon + arc) % 360.0 }
+
+      {
+        "arc" => arc.round(4),
+        "planets" => Transits.planet_details(directed_positions, natal_cusps),
+        "aspects_to_natal" => Transits.aspects_to_natal(
+          directed_positions, natal_positions,
+          orb_limit: orb_limit,
+          keys: %w[directed_planet natal_planet]
+        ),
+      }
+    end
+  end
+end

data/lib/astro_chart/solar_return.rb

@@ -0,0 +1,193 @@
+module AstroChart
+  # Solar return chart (太陽回歸盤): the chart cast for the exact UTC instant
+  # the transiting Sun returns to its natal longitude in a given year.
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   result = SolarReturn.for_year(natal, 2026)
+  #   result["return_jd"]       # Julian Day (UT) of the return instant
+  #   result["return_time_utc"] # ISO8601 UTC string, e.g. "2026-07-03T05:12:34Z"
+  #   result["chart"]           # full chart structure at the return instant
+  #
+  # The return instant is found by Newton iteration on the Sun's longitude,
+  # then the chart is computed directly at that Julian Day (no lossy
+  # round-trip through date strings).
+  module SolarReturn
+    SUN_ID = Ephemeris::PLANETS["太陽"]
+
+    # Raised when the Newton iteration fails to converge (should not happen
+    # for the Sun, whose longitude is monotonic at ~0.9856°/day).
+    class ConvergenceError < StandardError; end
+
+    # Convergence threshold in degrees (~0.36 arcsec, i.e. under 10 seconds
+    # of clock time at the Sun's mean speed).
+    CONVERGENCE_DEG = 1e-4
+    MAX_ITERATIONS  = 20
+
+    # Same planet => aspect-list wiring as Chart#generate.
+    ASPECT_MAP = {
+      "太陽"  => "sun_aspects",
+      "月亮"  => "moon_aspects",
+      "土星"  => "saturn_aspects",
+      "金星"  => "venus_aspects",
+      "北交點" => "north_node_aspects",
+      "南交點" => "south_node_aspects",
+    }.freeze
+
+    # Build the solar return for a natal chart (a Chart#generate hash) in the
+    # given year. Location defaults to the natal chart's coordinates/timezone;
+    # pass latitude:/longitude: (and timezone:, informational) to relocate.
+    def self.for_year(natal_chart, year, latitude: nil, longitude: nil, timezone: nil)
+      natal_sun = natal_sun_degree(natal_chart)
+      month, day = natal_month_day(natal_chart)
+
+      input = natal_chart["input"] || {}
+      coords = input["coordinates"] || {}
+      lat = latitude  || coords["latitude"]
+      lng = longitude || coords["longitude"]
+      tz  = timezone  || input["timezone"]
+      if lat.nil? || lng.nil?
+        raise ArgumentError,
+              "no coordinates: natal chart input has none and none were given"
+      end
+      lat = lat.to_f
+      lng = lng.to_f
+
+      jd = find_return_jd(natal_sun, year, month, day)
+
+      {
+        "return_jd"       => jd,
+        "return_time_utc" => jd_to_utc_iso8601(jd),
+        "location"        => {
+          "latitude"  => lat,
+          "longitude" => lng,
+          "timezone"  => tz,
+        },
+        "chart" => build_chart_at(jd, lat, lng),
+      }
+    end
+
+    # Newton iteration: find the JD(UT) nearest the birthday in `year` where
+    # the Sun's longitude equals target_deg.
+    def self.find_return_jd(target_deg, year, month, day)
+      jd = Ephemeris.julday(year, month, day, 12.0)
+
+      MAX_ITERATIONS.times do
+        delta = angle_delta(target_deg - Ephemeris.calc_ut(jd, SUN_ID))
+        return jd if delta.abs < CONVERGENCE_DEG
+
+        jd += delta / sun_speed(jd)
+      end
+
+      raise ConvergenceError,
+            "solar return did not converge within #{MAX_ITERATIONS} iterations " \
+            "(year=#{year}, target=#{target_deg})"
+    end
+
+    # Sun's longitudinal speed (deg/day) via central difference (~0.9856).
+    def self.sun_speed(jd, step = 0.05)
+      diff = angle_delta(
+        Ephemeris.calc_ut(jd + step, SUN_ID) - Ephemeris.calc_ut(jd - step, SUN_ID)
+      )
+      diff / (2.0 * step)
+    end
+
+    # Signed shortest angular difference, mapped into [-180, 180).
+    def self.angle_delta(deg)
+      (deg + 540.0) % 360.0 - 180.0
+    end
+
+    # Inverse Julian Day (Meeus, Astronomical Algorithms ch. 7):
+    # JD(UT) -> [year, month, day, hour, minute, second] in UTC.
+    # Rounded to the nearest whole second before decomposition, so
+    # 23:59:59.6 rolls over to 00:00:00 of the next day correctly.
+    def self.jd_to_utc(jd)
+      total_seconds = ((jd + 0.5) * 86_400.0).round
+      z   = total_seconds / 86_400
+      sec = total_seconds % 86_400
+
+      if z < 2_299_161 # before the Gregorian reform (1582-10-15)
+        a = z
+      else
+        alpha = ((z - 1_867_216.25) / 36_524.25).floor
+        a = z + 1 + alpha - (alpha / 4)
+      end
+
+      b = a + 1524
+      c = ((b - 122.1) / 365.25).floor
+      d = (365.25 * c).floor
+      e = ((b - d) / 30.6001).floor
+
+      day   = b - d - (30.6001 * e).floor
+      month = e < 14 ? e - 1 : e - 13
+      year  = month > 2 ? c - 4716 : c - 4715
+
+      [year, month, day, sec / 3600, (sec % 3600) / 60, sec % 60]
+    end
+
+    def self.jd_to_utc_iso8601(jd)
+      y, mo, d, h, mi, s = jd_to_utc(jd)
+      format("%04d-%02d-%02dT%02d:%02d:%02dZ", y, mo, d, h, mi, s)
+    end
+
+    # Chart structure at an exact JD — mirrors the "chart" section of
+    # Chart#generate, computed directly with Planets/Houses (Chart itself
+    # only accepts date strings, which would lose sub-minute precision).
+    def self.build_chart_at(jd, latitude, longitude)
+      cusps, ascendant = Houses.calculate(jd, latitude, longitude)
+
+      positions = Planets.calculate_positions(jd)
+      planet_details = Planets.build_details(positions, cusps)
+
+      kp = Planets.key_points_data(positions, cusps, ascendant)
+
+      planet_details.each do |planet|
+        key = ASPECT_MAP[planet["planet"]]
+        planet["aspects"] = kp[key] if key
+      end
+
+      planet_details.concat(kp["additional_points"])
+
+      houses_data = cusps.each_with_index.map do |deg, i|
+        {
+          "house_number" => i + 1,
+          "degree"       => deg.round(4),
+          "zodiac"       => Zodiac.sign_name(deg),
+        }
+      end
+
+      {
+        "ascendant" => {
+          "zodiac"       => Zodiac.sign_name(ascendant),
+          "degree"       => (ascendant % 30).round(4),
+          "total_degree" => ascendant.round(4),
+        },
+        "planets" => planet_details,
+        "houses"  => houses_data,
+      }
+    end
+
+    # Natal Sun total longitude from a Chart#generate hash.
+    def self.natal_sun_degree(chart)
+      planets = chart&.dig("chart", "planets")
+      raise ArgumentError, "chart has no planets data" if planets.nil? || planets.empty?
+
+      sun = planets.find { |p| p["planet"] == "太陽" }
+      raise ArgumentError, "chart has no 太陽 position" if sun.nil? || sun["total_degree"].nil?
+
+      sun["total_degree"]
+    end
+
+    # [month, day] of the natal birthday from a Chart#generate hash.
+    def self.natal_month_day(chart)
+      birth_date = chart&.dig("input", "birth_date")
+      raise ArgumentError, "chart has no input birth_date" if birth_date.nil?
+
+      _, month, day = birth_date.split("-").map(&:to_i)
+      raise ArgumentError, "invalid birth_date: #{birth_date.inspect}" if month.nil? || day.nil?
+
+      [month, day]
+    end
+
+    private_class_method :natal_sun_degree, :natal_month_day
+  end
+end

data/lib/astro_chart/stats.rb

@@ -0,0 +1,34 @@
+module AstroChart
+  # Element (四大元素) and modality (三大模式) distribution statistics.
+  #
+  # Both classifications follow directly from the zodiac sign a body
+  # occupies. Starting from 牡羊座, elements repeat every 4 signs
+  # (火土風水) and modalities every 3 signs (基本固定變動):
+  #
+  #   牡羊=火基本  金牛=土固定  雙子=風變動  巨蟹=水基本
+  #   獅子=火固定  處女=土變動  天秤=風基本  天蠍=水固定
+  #   射手=火變動  摩羯=土基本  水瓶=風固定  雙魚=水變動
+  module Stats
+    ELEMENTS = ["火", "土", "風", "水"].freeze
+    MODALITIES = ["基本", "固定", "變動"].freeze
+
+    # positions: { "太陽" => 123.45, ... } — the 10 classical planets
+    # (太陽..冥王星); the caller is responsible for passing only those.
+    #
+    # Returns:
+    #   { "elements"   => { "火" => n, "土" => n, "風" => n, "水" => n },
+    #     "modalities" => { "基本" => n, "固定" => n, "變動" => n } }
+    def self.elements(positions)
+      element_counts = ELEMENTS.to_h { |e| [e, 0] }
+      modality_counts = MODALITIES.to_h { |m| [m, 0] }
+
+      positions.each_value do |degree|
+        sign_index = (degree % 360).floor / 30
+        element_counts[ELEMENTS[sign_index % 4]] += 1
+        modality_counts[MODALITIES[sign_index % 3]] += 1
+      end
+
+      { "elements" => element_counts, "modalities" => modality_counts }
+    end
+  end
+end