astro_chart 0.2.0 → 0.4.0

data/lib/astro_chart/chart.rb

@@ -1,17 +1,35 @@
 module AstroChart
   class Chart
-    attr_reader :birth_date, :birth_time, :latitude, :longitude, :timezone
+    # Supported house systems: "P" (Placidus) / "W" (Whole Sign) /
+    # "E" (Equal, from the ascendant) / "O" (Porphyry).
+    HOUSE_SYSTEMS = ["P", "W", "E", "O"].freeze
+
+    # Bodies that can never be retrograde in geocentric longitude.
+    NEVER_RETROGRADE = ["太陽", "月亮"].freeze
+
+    attr_reader :birth_date, :birth_time, :latitude, :longitude, :timezone,
+                :house_system
 
     # birth_date: "YYYY-MM-DD"
     # birth_time: "HH:MM"
     # latitude / longitude: Float
     # timezone: IANA timezone string (e.g. "Asia/Taipei")
-    def initialize(birth_date:, birth_time:, latitude:, longitude:, timezone:)
-      @birth_date = birth_date
-      @birth_time = birth_time
-      @latitude   = latitude.to_f
-      @longitude  = longitude.to_f
-      @timezone   = timezone
+    # house_system: "P" (Placidus, default), "W" (Whole Sign),
+    #               "E" (Equal, from the ascendant) or "O" (Porphyry)
+    def initialize(birth_date:, birth_time:, latitude:, longitude:, timezone:,
+                   house_system: "P")
+      unless HOUSE_SYSTEMS.include?(house_system)
+        raise ArgumentError,
+              "unknown house system #{house_system.inspect} " \
+              "(expected \"P\", \"W\", \"E\" or \"O\")"
+      end
+
+      @birth_date   = birth_date
+      @birth_time   = birth_time
+      @latitude     = latitude.to_f
+      @longitude    = longitude.to_f
+      @timezone     = timezone
+      @house_system = house_system
     end
 
     # Generate complete chart data.
@@ -19,12 +37,17 @@ module AstroChart
     def generate
       jd = TimeConversion.to_julian_day(birth_date, birth_time, timezone)
 
-      cusps, ascendant = Houses.calculate(jd, latitude, longitude)
+      cusps, ascendant = Houses.calculate(jd, latitude, longitude, system: house_system)
       asc_zodiac = Zodiac.sign_name(ascendant)
 
       positions = Planets.calculate_positions(jd)
       planet_details = Planets.build_details(positions, cusps)
 
+      # Retrograde flags for the 12 physical bodies (太陽/月亮 hard-false,
+      # 南交點 mirrors 北交點 — they share the same axis).
+      retro = retrograde_flags(jd)
+      planet_details.each { |p| p["retrograde"] = retro.fetch(p["planet"], false) }
+
       kp = Planets.key_points_data(positions, cusps, ascendant)
 
       # Merge aspects into planet details
@@ -42,8 +65,12 @@ module AstroChart
         planet["aspects"] = kp[key] if key
       end
 
-      # Append ruler points
-      planet_details.concat(kp["additional_points"])
+      # Derived points (福點 / 莉莉絲), placed before the ruler points
+      planet_details.concat(derived_points(jd, positions, cusps, ascendant))
+
+      # Append ruler points (定位星 carry no retrograde motion of their own)
+      ruler_points = kp["additional_points"].map { |p| p.merge("retrograde" => false) }
+      planet_details.concat(ruler_points)
 
       houses_data = cusps.each_with_index.map do |deg, i|
         {
@@ -53,6 +80,10 @@ module AstroChart
         }
       end
 
+      # 12-body positions feed pattern detection; the 10 classical planets
+      # (nodes excluded) feed the element/modality statistics.
+      classical = positions.reject { |name, _| name == "北交點" || name == "南交點" }
+
       {
         "input" => {
           "birth_date"  => birth_date,
@@ -69,10 +100,61 @@ module AstroChart
             "degree"       => (ascendant % 30).round(4),
             "total_degree" => ascendant.round(4),
           },
-          "planets" => planet_details,
-          "houses"  => houses_data,
+          "house_system"  => house_system,
+          "planets"       => planet_details,
+          "houses"        => houses_data,
+          "patterns"      => Patterns.detect(positions),
+          "element_stats" => Stats.elements(classical),
         },
       }
     end
+
+    private
+
+    # { "太陽" => false, ..., "南交點" => bool } — retrograde flags per body.
+    def retrograde_flags(jd)
+      flags = {}
+      Ephemeris::PLANETS.each do |name, planet_id|
+        flags[name] = if NEVER_RETROGRADE.include?(name)
+                        false
+                      else
+                        Ephemeris.retrograde?(jd, planet_id)
+                      end
+      end
+      flags["南交點"] = flags["北交點"]
+      flags
+    end
+
+    # 福點 (Part of Fortune) + 莉莉絲 (mean Black Moon Lilith) entries,
+    # shaped like regular planet entries. Both are hard-false retrograde:
+    # 福點 is a derived point with no motion of its own; 莉莉絲 is the mean
+    # lunar apogee, which always moves prograde.
+    def derived_points(jd, positions, cusps, ascendant)
+      # Sect (day/night) is an astronomical fact defined by the Sun relative
+      # to the ASC-DSC horizon axis, so it is judged from the horizon itself
+      # — never from the selected display house system's cusps (whole-sign
+      # cusps sit on sign boundaries, not on the horizon).
+      day_chart = Points.day_chart_from_horizon?(positions["太陽"], ascendant)
+      fortune = Points.fortune(
+        asc: ascendant,
+        sun: positions["太陽"],
+        moon: positions["月亮"],
+        day_chart: !!day_chart
+      )
+      lilith = Points.lilith(jd)
+
+      [point_entry("福點", fortune, cusps), point_entry("莉莉絲", lilith, cusps)]
+    end
+
+    def point_entry(name, pos, cusps)
+      {
+        "planet"       => name,
+        "zodiac"       => Zodiac.sign_name(pos),
+        "house"        => Houses.find_house(pos, cusps),
+        "degree"       => (pos % 30).round(4),
+        "total_degree" => pos.round(4),
+        "retrograde"   => false,
+      }
+    end
   end
 end

data/lib/astro_chart/composite.rb

@@ -0,0 +1,101 @@
+module AstroChart
+  # Composite chart (組合盤): the midpoint chart of two natal charts.
+  #
+  # For every body present in BOTH charts, the composite position is the
+  # shorter-arc midpoint of the two natal longitudes. Aspects are then
+  # computed among the composite positions themselves.
+  #
+  # Backend-independent: works purely on Chart#generate result hashes,
+  # no ephemeris call happens here.
+  #
+  #   result = Composite.between(chart_a, chart_b)
+  #   result["planets"] # 12 個組合盤中點位置
+  #   result["aspects"] # 組合盤位置彼此之間的相位（依 orb 排序）
+  #
+  # Houses are intentionally out of scope: midpoint-composite house systems
+  # are convention-contested (midpoint of cusps vs. recomputed for a
+  # reference location/time), so no single answer is returned here.
+  module Composite
+    # The 12 bodies considered: the 11 ephemeris bodies + 南交點.
+    BODIES = (Ephemeris::PLANETS.keys + ["南交點"]).freeze
+
+    # Full composite between two Chart#generate result hashes.
+    #
+    # Returns:
+    #   {
+    #     "planets" => [{ "planet", "zodiac", "degree", "total_degree" }],
+    #     "aspects" => [{ "planet_a", "planet_b", "aspect_type", "orb" }],
+    #   }
+    def self.between(chart_a, chart_b)
+      pos_a = positions_from_chart(chart_a)
+      pos_b = positions_from_chart(chart_b)
+
+      composite_positions = {}
+      BODIES.each do |name|
+        a = pos_a[name]
+        b = pos_b[name]
+        next if a.nil? || b.nil?
+
+        composite_positions[name] = midpoint(a, b)
+      end
+
+      {
+        "planets" => build_planets(composite_positions),
+        "aspects" => build_aspects(composite_positions),
+      }
+    end
+
+    # Shorter-arc midpoint of two ecliptic longitudes (degrees, [0, 360)).
+    # 350° & 10° => 0° (not 180°).
+    def self.midpoint(a, b)
+      (a + (((b - a + 540.0) % 360.0) - 180.0) / 2.0) % 360.0
+    end
+
+    # Extract { name => total_degree } for BODIES from a Chart#generate hash.
+    # Ruler points appended by key_points_data are ignored (not in BODIES).
+    def self.positions_from_chart(chart)
+      planets = chart&.dig("chart", "planets")
+      raise ArgumentError, "chart has no planets data" if planets.nil? || planets.empty?
+
+      planets.each_with_object({}) do |p, out|
+        name = p["planet"]
+        next unless BODIES.include?(name)
+
+        degree = p["total_degree"]
+        out[name] = degree if degree
+      end
+    end
+
+    def self.build_planets(positions)
+      positions.map do |name, pos|
+        {
+          "planet"       => name,
+          "zodiac"       => Zodiac.sign_name(pos),
+          "degree"       => (pos % 30).round(4),
+          "total_degree" => pos.round(4),
+        }
+      end
+    end
+
+    def self.build_aspects(positions)
+      names = positions.keys
+      results = []
+
+      names.combination(2) do |name_a, name_b|
+        aspect_type, orb = Aspects.calculate(positions[name_a], positions[name_b])
+        next if aspect_type.nil?
+
+        results << {
+          "planet_a"    => name_a,
+          "planet_b"    => name_b,
+          "aspect_type" => aspect_type,
+          "orb"         => orb,
+        }
+      end
+
+      results.sort_by { |r| r["orb"] }
+    end
+
+    private_class_method :build_planets, :build_aspects
+  end
+end

data/lib/astro_chart/dignities.rb

@@ -0,0 +1,220 @@
+require_relative "zodiac"
+
+module AstroChart
+  # Essential dignities (必然尊貴) — the classical Hellenistic / medieval
+  # scheme of five dignities and their planetary rulers, plus the two major
+  # debilities. Pure lookup tables; no ephemeris, fully deterministic.
+  #
+  # Rulers are the SEVEN traditional planets (太陽 月亮 水星 金星 火星 木星 土星).
+  # These use the TRADITIONAL rulerships (天蠍→火星, 水瓶→土星, 雙魚→木星), which
+  # differ from the modern rulers in Zodiac.ruler (冥王星/天王星/海王星). Dignity
+  # theory predates the outer planets, so it is defined on the traditional set.
+  #
+  # The five dignities and their scores (Lilly / Ptolemaic weighting):
+  #   廟 domicile     +5   planet rules the sign
+  #   旺 exaltation   +4   planet is exalted in the sign (with an exact degree)
+  #   三分性 triplicity +3   planet rules the sign's element by sect
+  #   界 term/bound   +2   planet rules the bound the degree falls in
+  #   外觀 face/decan  +1   planet rules the 10° face the degree falls in
+  # Debilities: 陷 detriment (−5, opposite domicile), 弱 fall (−4, opposite
+  # exaltation).
+  #
+  # Terms: two schemes are bundled — 埃及界 (Egyptian, the default and most
+  # widely used) and 托勒密界 (Ptolemaic). Both are cross-validated against
+  # Astrolog's tables; the Egyptian table additionally matches several
+  # independent references degree-for-degree.
+  module Dignities
+    PLANETS = ["太陽", "月亮", "水星", "金星", "火星", "木星", "土星"].freeze
+
+    # 傳統守護星 (traditional domicile rulers), by sign.
+    DOMICILE = {
+      "牡羊座" => "火星", "金牛座" => "金星", "雙子座" => "水星", "巨蟹座" => "月亮",
+      "獅子座" => "太陽", "處女座" => "水星", "天秤座" => "金星", "天蠍座" => "火星",
+      "射手座" => "木星", "摩羯座" => "土星", "水瓶座" => "土星", "雙魚座" => "木星",
+    }.freeze
+
+    # 旺 (exaltation): sign => [planet, exact degree]. Signs without an
+    # exaltation ruler are absent.
+    EXALTATION = {
+      "牡羊座" => ["太陽", 19], "金牛座" => ["月亮", 3],  "巨蟹座" => ["木星", 15],
+      "處女座" => ["水星", 15], "天秤座" => ["土星", 21], "摩羯座" => ["火星", 28],
+      "雙魚座" => ["金星", 27],
+    }.freeze
+
+    # 三分性 (triplicity), Dorothean scheme: element => day/night/participating
+    # rulers. Elements repeat every 4 signs from 牡羊 (火).
+    ELEMENTS = ["火", "土", "風", "水"].freeze
+    TRIPLICITY = {
+      "火" => { day: "太陽", night: "木星", participating: "土星" },
+      "土" => { day: "金星", night: "月亮", participating: "火星" },
+      "風" => { day: "土星", night: "水星", participating: "木星" },
+      "水" => { day: "金星", night: "火星", participating: "月亮" },
+    }.freeze
+
+    # 埃及界 (Egyptian terms): sign => [[ruler, ending_degree], ...5], the
+    # ending degree measured within the sign (0-30). Verified against multiple
+    # references.
+    EGYPTIAN_TERMS = {
+      "牡羊座" => [["木星", 6], ["金星", 12], ["水星", 20], ["火星", 25], ["土星", 30]],
+      "金牛座" => [["金星", 8], ["水星", 14], ["木星", 22], ["土星", 27], ["火星", 30]],
+      "雙子座" => [["水星", 6], ["木星", 12], ["金星", 17], ["火星", 24], ["土星", 30]],
+      "巨蟹座" => [["火星", 7], ["金星", 13], ["水星", 19], ["木星", 26], ["土星", 30]],
+      "獅子座" => [["木星", 6], ["金星", 11], ["土星", 18], ["水星", 24], ["火星", 30]],
+      "處女座" => [["水星", 7], ["金星", 17], ["木星", 21], ["火星", 28], ["土星", 30]],
+      "天秤座" => [["土星", 6], ["水星", 14], ["木星", 21], ["金星", 28], ["火星", 30]],
+      "天蠍座" => [["火星", 7], ["金星", 11], ["水星", 19], ["木星", 24], ["土星", 30]],
+      "射手座" => [["木星", 12], ["金星", 17], ["水星", 21], ["土星", 26], ["火星", 30]],
+      "摩羯座" => [["水星", 7], ["木星", 14], ["金星", 22], ["土星", 26], ["火星", 30]],
+      "水瓶座" => [["水星", 7], ["金星", 13], ["木星", 20], ["火星", 25], ["土星", 30]],
+      "雙魚座" => [["金星", 12], ["木星", 16], ["水星", 19], ["火星", 28], ["土星", 30]],
+    }.freeze
+
+    # 托勒密界 (Ptolemaic terms): Ptolemy's alternative bounds from the
+    # Tetrabiblos. Decoded from Astrolog's rgnTermPtolemy table (the same
+    # decoding reproduces Astrolog's Egyptian table identically to EGYPTIAN_TERMS
+    # above, which validates it). Resolves the classically disputed cells as
+    # 獅子 first term = 土星 and 天蠍 first term = 火星.
+    PTOLEMAIC_TERMS = {
+      "牡羊座" => [["木星", 6], ["金星", 14], ["水星", 21], ["火星", 26], ["土星", 30]],
+      "金牛座" => [["金星", 8], ["水星", 15], ["木星", 22], ["土星", 26], ["火星", 30]],
+      "雙子座" => [["水星", 7], ["木星", 14], ["金星", 21], ["土星", 25], ["火星", 30]],
+      "巨蟹座" => [["火星", 6], ["木星", 13], ["水星", 20], ["金星", 27], ["土星", 30]],
+      "獅子座" => [["土星", 6], ["水星", 13], ["金星", 19], ["木星", 25], ["火星", 30]],
+      "處女座" => [["水星", 7], ["金星", 13], ["木星", 18], ["土星", 24], ["火星", 30]],
+      "天秤座" => [["土星", 6], ["金星", 11], ["木星", 19], ["水星", 24], ["火星", 30]],
+      "天蠍座" => [["火星", 6], ["木星", 14], ["金星", 21], ["水星", 27], ["土星", 30]],
+      "射手座" => [["木星", 8], ["金星", 14], ["水星", 19], ["土星", 25], ["火星", 30]],
+      "摩羯座" => [["金星", 6], ["水星", 12], ["木星", 19], ["火星", 25], ["土星", 30]],
+      "水瓶座" => [["土星", 6], ["水星", 12], ["金星", 20], ["木星", 25], ["火星", 30]],
+      "雙魚座" => [["金星", 8], ["木星", 14], ["水星", 20], ["火星", 26], ["土星", 30]],
+    }.freeze
+
+    TERM_SCHEMES = { egyptian: EGYPTIAN_TERMS, ptolemaic: PTOLEMAIC_TERMS }.freeze
+
+    # 外觀 (faces / decans), Chaldean order: the 36 faces cycle the seven
+    # planets in Chaldean sequence (土木火日金水月) starting at 火星 for 牡羊 0°.
+    # Generated rather than tabulated — face n = CHALDEAN[(⌊lon/10⌋) mod 7].
+    CHALDEAN_FROM_MARS = ["火星", "太陽", "金星", "水星", "月亮", "土星", "木星"].freeze
+
+    DIGNITY_SCORES = { domicile: 5, exaltation: 4, triplicity: 3, term: 2, face: 1 }.freeze
+
+    module_function
+
+    def sign_of(longitude)
+      Zodiac.sign_name(longitude)
+    end
+
+    def element_of(longitude)
+      ELEMENTS[((longitude % 360).floor / 30) % 4]
+    end
+
+    # Degree within the current sign (0-30).
+    def degree_in_sign(longitude)
+      (longitude % 360.0) % 30.0
+    end
+
+    # +5 ruler of the sign (traditional).
+    def domicile_ruler(longitude)
+      DOMICILE[sign_of(longitude)]
+    end
+
+    # −5 planet in detriment here = ruler of the opposite sign.
+    def detriment_ruler(longitude)
+      DOMICILE[sign_of(longitude + 180.0)]
+    end
+
+    # +4 exalted planet in this sign, or nil.
+    def exaltation_ruler(longitude)
+      entry = EXALTATION[sign_of(longitude)]
+      entry && entry[0]
+    end
+
+    # −4 planet in fall here = the planet exalted in the opposite sign, or nil.
+    def fall_ruler(longitude)
+      entry = EXALTATION[sign_of(longitude + 180.0)]
+      entry && entry[0]
+    end
+
+    # Triplicity rulers for the sign's element.
+    # Returns { day:, night:, participating: }.
+    def triplicity_rulers(longitude)
+      TRIPLICITY[element_of(longitude)]
+    end
+
+    # +3 triplicity ruler active for the given sect (:day / :night).
+    def triplicity_ruler(longitude, sect: :day)
+      trip = triplicity_rulers(longitude)
+      sect == :night ? trip[:night] : trip[:day]
+    end
+
+    # +2 term/bound ruler at this degree (Egyptian by default).
+    def term_ruler(longitude, scheme: :egyptian)
+      table = TERM_SCHEMES[scheme]
+      unless table
+        raise ArgumentError,
+              "unknown term scheme #{scheme.inspect} (available: #{TERM_SCHEMES.keys.inspect})"
+      end
+      deg = degree_in_sign(longitude)
+      table[sign_of(longitude)].each do |ruler, ending|
+        return ruler if deg < ending
+      end
+      table[sign_of(longitude)].last[0] # exactly 30.0 → last term
+    end
+
+    # +1 face/decan ruler at this degree (Chaldean order).
+    def face_ruler(longitude)
+      CHALDEAN_FROM_MARS[((longitude % 360).floor / 10) % 7]
+    end
+
+    # Total essential-dignity score a planet holds at a longitude (sum of the
+    # positive dignities it rules). Debilities are reported separately by .of
+    # and are not subtracted here.
+    def score(planet, longitude, sect: :day, terms: :egyptian)
+      total = 0
+      total += DIGNITY_SCORES[:domicile]   if domicile_ruler(longitude) == planet
+      total += DIGNITY_SCORES[:exaltation] if exaltation_ruler(longitude) == planet
+      total += DIGNITY_SCORES[:triplicity] if triplicity_ruler(longitude, sect: sect) == planet
+      total += DIGNITY_SCORES[:term]       if term_ruler(longitude, scheme: terms) == planet
+      total += DIGNITY_SCORES[:face]       if face_ruler(longitude) == planet
+      total
+    end
+
+    # Full dignity/debility report for a planet at a longitude.
+    #
+    #   { "dignities" => ["廟", "界"...], "debilities" => ["陷"...],
+    #     "score" => 7 }
+    #
+    # Exaltation/fall are placement dignities of the sign (the exact degree is
+    # the peak but the whole sign confers the dignity), matching Lilly's table.
+    def of(planet, longitude, sect: :day, terms: :egyptian)
+      dignities = []
+      dignities << "廟"   if domicile_ruler(longitude) == planet
+      dignities << "旺"   if exaltation_ruler(longitude) == planet
+      dignities << "三分性" if triplicity_ruler(longitude, sect: sect) == planet
+      dignities << "界"   if term_ruler(longitude, scheme: terms) == planet
+      dignities << "外觀" if face_ruler(longitude) == planet
+
+      debilities = []
+      debilities << "陷" if detriment_ruler(longitude) == planet
+      debilities << "弱" if fall_ruler(longitude) == planet
+
+      {
+        "planet"     => planet,
+        "dignities"  => dignities,
+        "debilities" => debilities,
+        "score"      => score(planet, longitude, sect: sect, terms: terms),
+      }
+    end
+
+    # Almuten of a degree (界主星/度數勝利星): the traditional planet with the
+    # highest total dignity score at that longitude. Returns
+    #   { "planet" => "火星", "score" => 7, "tied" => ["火星", ...] }
+    # `tied` lists every planet sharing the top score (usually one).
+    def almuten(longitude, sect: :day, terms: :egyptian)
+      scored = PLANETS.map { |p| [p, score(p, longitude, sect: sect, terms: terms)] }
+      top = scored.map { |_p, s| s }.max
+      winners = scored.select { |_p, s| s == top }.map { |p, _s| p }
+      { "planet" => winners.first, "score" => top, "tied" => winners }
+    end
+  end
+end

data/lib/astro_chart/draconic.rb

@@ -0,0 +1,64 @@
+require_relative "zodiac"
+require_relative "aspects"
+
+module AstroChart
+  # Draconic chart (龍盤): the tropical zodiac rotated so the natal True North
+  # Node sits at 0° 牡羊. Every ecliptic longitude is shifted by the node's
+  # longitude, which re-signs the whole chart around the lunar nodal axis.
+  # Widely read as the "soul level" overlay of the ordinary tropical chart.
+  #
+  #   draconic_longitude = (L − 北交點) mod 360
+  #
+  # Pure composition: this only transforms longitudes. Feed it the raw
+  # positions hash from `Planets.calculate_positions` (or any { name => L }
+  # hash) together with the natal True North Node longitude.
+  module Draconic
+    # positions:  { "太陽" => 123.45, ... } tropical ecliptic longitudes
+    # north_node: True North Node longitude (degrees, 0-360)
+    #
+    # Returns { name => draconic_longitude } with 北交點 mapped to 0.0.
+    def self.positions(positions, north_node)
+      positions.transform_values { |lon| (lon - north_node) % 360.0 }
+    end
+
+    # Full draconic view: draconic longitude, zodiac sign and in-sign degree
+    # for every body, plus the aspects among them (major aspects only, via
+    # Aspects.calculate — draconic-to-draconic contacts are identical to the
+    # tropical ones, but the signs and houses they fall in differ).
+    #
+    # Returns:
+    #   { "planets" => [ { "planet" =>, "zodiac" =>, "degree" =>,
+    #                      "total_degree" => }, ... ],
+    #     "aspects" => [ { "a_planet" =>, "b_planet" =>,
+    #                      "aspect_type" =>, "orb" => }, ... ] }  # sorted by orb
+    def self.chart(positions, north_node)
+      draconic = self.positions(positions, north_node)
+
+      planets = draconic.map do |name, lon|
+        {
+          "planet"       => name,
+          "zodiac"       => Zodiac.sign_name(lon),
+          "degree"       => (lon % 30).round(4),
+          "total_degree" => lon.round(4),
+        }
+      end
+
+      names = draconic.keys
+      aspects = []
+      names.combination(2) do |a, b|
+        type, orb = Aspects.calculate(draconic[a], draconic[b])
+        next if type.nil?
+
+        aspects << {
+          "a_planet"    => a,
+          "b_planet"    => b,
+          "aspect_type" => type,
+          "orb"         => orb,
+        }
+      end
+      aspects.sort_by! { |asp| asp["orb"] }
+
+      { "planets" => planets, "aspects" => aspects }
+    end
+  end
+end