astro_chart 0.2.0 → 0.4.0

data/lib/astro_chart/transit_timing.rb

@@ -0,0 +1,186 @@
+require_relative "ephemeris"
+require_relative "aspects"
+require_relative "zodiac"
+require_relative "synastry"
+require_relative "solar_return"
+
+module AstroChart
+  # Transit timing (行運精確時點): the exact UTC instants, within a date range,
+  # when a transiting body forms an exact aspect to a natal point.
+  #
+  # Where Transits.against is a single snapshot ("what aspects hold right
+  # now?"), this answers the question people actually ask — "*when* does
+  # transiting 土星 exactly square my natal 太陽?".
+  #
+  #   natal  = AstroChart::Chart.new(...).generate
+  #   events = AstroChart::TransitTiming.events(natal, "2026-01-01", "2026-12-31")
+  #   events.first
+  #   #=> { "transit_planet" => "土星", "natal_planet" => "太陽",
+  #   #     "aspect_type" => "四分相", "jd" => 2461...,
+  #   #     "time_utc" => "2026-03-14T07:22:10Z", "transit_zodiac" => "牡羊座",
+  #   #     "retrograde" => false }
+  #
+  # Method: each transiting body's longitude is sampled across the range at
+  # `step_days`; for every natal point and aspect angle the signed separation
+  # is bracketed where it crosses exactness, then refined by bisection (robust
+  # through retrograde stations, unlike a pure Newton step). A step where the
+  # body moves < 90° guarantees no aliasing — 1 day is safe for all bodies
+  # (the Moon moves ~13°/day).
+  module TransitTiming
+    # Transiting bodies considered (12-body set minus 南交點, mirroring
+    # Synastry/Transits — a south-node hit merely mirrors a north-node one).
+    BODIES = Synastry::BODIES
+
+    # Major aspect angles. Each non-zero, non-opposition aspect is exact at two
+    # signed separations (applying from either side); 合相/對分相 have one.
+    MAJOR = { "合相" => 0, "六分相" => 60, "四分相" => 90, "三分相" => 120, "對分相" => 180 }.freeze
+    MINOR = { "十二分相" => 30, "半四分相" => 45, "補八分相" => 135, "補十二分相" => 150 }.freeze
+
+    CONVERGENCE_DAYS = 1e-6 # ~0.1 second of clock time
+    MAX_BISECT = 60
+
+    # natal_chart: a Chart#generate result hash.
+    # start_date / end_date: "YYYY-MM-DD" (interpreted at 00:00 UT).
+    # minor: also time the minor aspects (30/45/135/150).
+    # step_days: sampling stride (default 1.0 — safe for every body).
+    # bodies: restrict transiting bodies (default all BODIES; e.g. drop "月亮"
+    #   to avoid the Moon's ~monthly hits flooding the list).
+    #
+    # Returns an Array of event hashes sorted by time (jd ascending).
+    def self.events(natal_chart, start_date, end_date, minor: false,
+                    step_days: 1.0, bodies: nil)
+      natal = Synastry.positions_from_chart(natal_chart)
+      moving = (bodies || BODIES).select { |b| Ephemeris::PLANETS.key?(b) }
+      targets = signed_targets(minor)
+
+      jd_start = date_to_jd(start_date)
+      jd_end   = date_to_jd(end_date)
+
+      events = []
+      moving.each do |body|
+        id = Ephemeris::PLANETS[body]
+        # Sample this body's longitude ONCE across the grid, then reuse the
+        # cached samples for every natal point × aspect target (calc_ut is the
+        # cost; the scan phase does zero extra ephemeris calls, only bisection
+        # refinement recomputes).
+        grid = sample_grid(id, jd_start, jd_end, step_days)
+
+        natal.each do |n_name, n_pos|
+          targets.each do |aspect_type, sep|
+            scan_grid(grid, n_pos, sep).each do |jd0, h0, jd1, h1|
+              jd = bisect(id, n_pos, sep, jd0, h0, jd1, h1)
+              events << build_event(body, id, n_name, aspect_type, jd)
+            end
+          end
+        end
+      end
+
+      dedupe(events).sort_by { |e| e["jd"] }
+    end
+
+    # [[jd, lon], ...] samples of one body from jd_start to jd_end (inclusive).
+    def self.sample_grid(id, jd_start, jd_end, step)
+      grid = []
+      jd = jd_start
+      loop do
+        jd = jd_end if jd > jd_end
+        grid << [jd, Ephemeris.calc_ut(jd, id)]
+        break if jd >= jd_end
+
+        jd += step
+      end
+      grid
+    end
+
+    # Brackets where the signed separation crosses exactness, from cached
+    # longitudes. Returns [[jd0, h0, jd1, h1], ...] for bisection.
+    def self.scan_grid(grid, natal_pos, sep)
+      brackets = []
+      grid.each_cons(2) do |(jd0, l0), (jd1, l1)|
+        h0 = SolarReturn.angle_delta(l0 - natal_pos - sep)
+        h1 = SolarReturn.angle_delta(l1 - natal_pos - sep)
+        # A sign change with both endpoints near the target (|h| < 90°) is a
+        # real crossing; the |h| guard rejects the ±180° wrap discontinuity.
+        next unless h0 != 0 && (h0 <=> 0) != (h1 <=> 0) && h0.abs < 90 && h1.abs < 90
+
+        brackets << [jd0, h0, jd1, h1]
+      end
+      brackets
+    end
+
+    # Signed separations at which each aspect is exact. 合相 (0) and 對分相
+    # (180) have a single point; the rest have ±angle.
+    def self.signed_targets(minor)
+      table = minor ? MAJOR.merge(MINOR) : MAJOR
+      table.flat_map do |name, angle|
+        if angle.zero? || angle == 180
+          [[name, angle]]
+        else
+          [[name, angle], [name, -angle]]
+        end
+      end
+    end
+
+    def self.bisect(id, natal_pos, sep, a, ha, b, _hb)
+      MAX_BISECT.times do
+        break if (b - a) < CONVERGENCE_DAYS
+
+        mid = (a + b) / 2.0
+        hm = separation(id, mid, natal_pos, sep)
+        if hm == 0
+          return mid
+        elsif (ha <=> 0) != (hm <=> 0)
+          b = mid
+        else
+          a = mid
+          ha = hm
+        end
+      end
+      (a + b) / 2.0
+    end
+
+    # Signed distance (deg, [-180,180)) from exactness of this aspect.
+    def self.separation(id, jd, natal_pos, sep)
+      SolarReturn.angle_delta(Ephemeris.calc_ut(jd, id) - natal_pos - sep)
+    end
+
+    def self.build_event(body, id, natal_name, aspect_type, jd)
+      lon = Ephemeris.calc_ut(jd, id)
+      {
+        "transit_planet" => body,
+        "natal_planet"   => natal_name,
+        "aspect_type"    => aspect_type,
+        "jd"             => jd,
+        "time_utc"       => SolarReturn.jd_to_utc_iso8601(jd),
+        "transit_zodiac" => Zodiac.sign_name(lon),
+        "retrograde"     => never_retrograde?(body) ? false : Ephemeris.retrograde?(jd, id),
+      }
+    end
+
+    def self.never_retrograde?(body)
+      body == "太陽" || body == "月亮"
+    end
+
+    # Two roots for the same contact found at adjacent brackets (a root landing
+    # on a sample boundary) collapse to one.
+    def self.dedupe(events)
+      events
+        .group_by { |e| [e["transit_planet"], e["natal_planet"], e["aspect_type"]] }
+        .flat_map do |_key, group|
+          group.sort_by { |e| e["jd"] }.chunk_while { |a, b| (b["jd"] - a["jd"]) < 1e-3 }
+               .map(&:first)
+        end
+    end
+
+    def self.date_to_jd(date)
+      y, m, d = date.split("-").map(&:to_i)
+      raise ArgumentError, "invalid date: #{date.inspect}" if y.nil? || m.nil? || d.nil?
+
+      Ephemeris.julday(y, m, d, 0.0)
+    end
+
+    private_class_method :signed_targets, :sample_grid, :scan_grid, :bisect,
+                         :separation, :build_event, :never_retrograde?,
+                         :dedupe, :date_to_jd
+  end
+end

data/lib/astro_chart/transits.rb

@@ -0,0 +1,108 @@
+require_relative "pure"
+require_relative "ephemeris"
+require_relative "zodiac"
+require_relative "aspects"
+require_relative "houses"
+require_relative "planets"
+require_relative "synastry"
+
+module AstroChart
+  # Transits (行運): where the planets are in the sky right now (or at any
+  # moment), compared against a natal chart.
+  #
+  # Pure composition of existing modules — Planets.calculate_positions gives
+  # the sky positions for any JD, Houses.find_house places them into the
+  # natal houses, and Aspects.calculate scores transit-to-natal contacts.
+  #
+  # Typical usage with a Chart#generate result:
+  #
+  #   jd = AstroChart::TimeConversion.to_julian_day("2026-07-24", "12:00", "Asia/Taipei")
+  #   AstroChart::Transits.at(jd)                  # 天象快照 { "太陽" => 121.9, ... }
+  #   AstroChart::Transits.against(natal_chart, jd) # 行運行星落入本命宮位 + 行運相位
+  module Transits
+    # Bodies used for transit-to-natal aspects. Mirrors Synastry: 南交點 is
+    # excluded because it sits exactly opposite 北交點 — every south-node
+    # aspect would just mirror a north-node one and double the noise.
+    ASPECT_BODIES = Synastry::BODIES
+
+    # Sky snapshot at a Julian Day.
+    #
+    # Returns { "太陽" => 123.45, ..., "南交點" => 303.45 } — ecliptic
+    # longitudes (total degrees 0-360) for the 12 bodies
+    # (Ephemeris::PLANETS + 南交點 = 北交點 + 180°).
+    def self.at(jd)
+      Planets.calculate_positions(jd)
+    end
+
+    # Transits against a natal chart (a Chart#generate result hash).
+    #
+    # jd: Julian Day of the transit moment.
+    # orb_limit: keep only aspects with orb <= limit (default 3.0 — transit
+    #   practice uses much tighter orbs than the natal defaults in Aspects).
+    #
+    # Returns:
+    #   {
+    #     "planets" => [ { "planet" => "木星", "zodiac" => "獅子座",
+    #                      "degree" => 5.1, "total_degree" => 125.1,
+    #                      "natal_house" => 7 }, ... 12 entries ],
+    #     "aspects" => [ { "transit_planet" => "土星", "natal_planet" => "太陽",
+    #                      "aspect_type" => "四分相", "orb" => 1.23 }, ... ]
+    #   }
+    #
+    # aspects are sorted by orb (tightest first).
+    def self.against(natal_chart, jd, orb_limit: 3.0)
+      transit_positions = at(jd)
+      natal_positions   = Synastry.positions_from_chart(natal_chart)
+      natal_cusps       = Synastry.cusps_from_chart(natal_chart)
+
+      {
+        "planets" => planet_details(transit_positions, natal_cusps),
+        "aspects" => aspects_to_natal(transit_positions, natal_positions,
+                                      orb_limit: orb_limit,
+                                      keys: %w[transit_planet natal_planet]),
+      }
+    end
+
+    # Build the per-planet detail list, placing each transiting body into
+    # the natal houses.
+    def self.planet_details(positions, natal_cusps)
+      positions.map do |name, pos|
+        {
+          "planet"       => name,
+          "zodiac"       => Zodiac.sign_name(pos),
+          "degree"       => (pos % 30).round(4),
+          "total_degree" => pos.round(4),
+          "natal_house"  => Houses.find_house(pos, natal_cusps),
+        }
+      end
+    end
+
+    # Aspects from moving positions to natal positions, filtered by
+    # orb_limit and sorted by orb. `keys` names the two hash keys so
+    # Progressions can reuse this with "progressed_planet".
+    def self.aspects_to_natal(moving_positions, natal_positions, orb_limit:,
+                              keys: %w[transit_planet natal_planet])
+      moving_key, natal_key = keys
+      results = []
+
+      moving_positions.each do |m_name, m_pos|
+        next unless ASPECT_BODIES.include?(m_name)
+
+        natal_positions.each do |n_name, n_pos|
+          aspect_type, orb = Aspects.calculate(m_pos, n_pos)
+          next if aspect_type.nil?
+          next if orb_limit && orb > orb_limit
+
+          results << {
+            moving_key    => m_name,
+            natal_key     => n_name,
+            "aspect_type" => aspect_type,
+            "orb"         => orb,
+          }
+        end
+      end
+
+      results.sort_by { |r| r["orb"] }
+    end
+  end
+end

data/lib/astro_chart/version.rb

@@ -1,3 +1,3 @@
 module AstroChart
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/astro_chart.rb

@@ -10,8 +10,21 @@ require_relative "astro_chart/aspects"
 require_relative "astro_chart/houses"
 require_relative "astro_chart/time_conversion"
 require_relative "astro_chart/planets"
+require_relative "astro_chart/points"
+require_relative "astro_chart/patterns"
+require_relative "astro_chart/stats"
 require_relative "astro_chart/synastry"
 require_relative "astro_chart/chart"
+require_relative "astro_chart/transits"
+require_relative "astro_chart/progressions"
+require_relative "astro_chart/composite"
+require_relative "astro_chart/solar_return"
+require_relative "astro_chart/draconic"
+require_relative "astro_chart/dignities"
+require_relative "astro_chart/profection"
+require_relative "astro_chart/transit_timing"
+require_relative "astro_chart/solar_arc"
+require_relative "astro_chart/lunar_return"
 
 module AstroChart
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: astro_chart
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Huang Yudi
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tzinfo
@@ -52,10 +52,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: 'Natal astrology chart calculation in pure Ruby: apparent planetary longitudes
-  (VSOP87D, ELP-2000/82B moon, Meeus Pluto), Placidus houses, aspects and synastry.
-  No C extension, no external data files. Implemented from public formulas (Meeus,
-  Astronomical Algorithms 2nd ed.).'
+description: 'Astrology chart calculation in pure Ruby: apparent planetary longitudes
+  (VSOP87D, ELP-2000/82B moon, Meeus Pluto), Placidus and whole-sign houses, retrograde
+  flags, aspects, derived points (Part of Fortune, mean Lilith), aspect-pattern detection
+  and element statistics, plus synastry, transits, secondary progressions, composite
+  charts and solar returns. No C extension, no external data files. Implemented from
+  public formulas (Meeus, Astronomical Algorithms 2nd ed.).'
 email:
 executables: []
 extensions: []
@@ -63,13 +65,22 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- README.md
 - astro_chart.gemspec
 - lib/astro_chart.rb
 - lib/astro_chart/aspects.rb
 - lib/astro_chart/chart.rb
+- lib/astro_chart/composite.rb
+- lib/astro_chart/dignities.rb
+- lib/astro_chart/draconic.rb
 - lib/astro_chart/ephemeris.rb
 - lib/astro_chart/houses.rb
+- lib/astro_chart/lunar_return.rb
+- lib/astro_chart/patterns.rb
 - lib/astro_chart/planets.rb
+- lib/astro_chart/points.rb
+- lib/astro_chart/profection.rb
+- lib/astro_chart/progressions.rb
 - lib/astro_chart/pure.rb
 - lib/astro_chart/pure/core.rb
 - lib/astro_chart/pure/houses.rb
@@ -78,8 +89,13 @@ files:
 - lib/astro_chart/pure/pluto.rb
 - lib/astro_chart/pure/vsop87.rb
 - lib/astro_chart/pure/vsop87_data.rb
+- lib/astro_chart/solar_arc.rb
+- lib/astro_chart/solar_return.rb
+- lib/astro_chart/stats.rb
 - lib/astro_chart/synastry.rb
 - lib/astro_chart/time_conversion.rb
+- lib/astro_chart/transit_timing.rb
+- lib/astro_chart/transits.rb
 - lib/astro_chart/version.rb
 - lib/astro_chart/zodiac.rb
 homepage: https://github.com/morriedig/astro_chart
@@ -104,5 +120,6 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Pure-Ruby natal chart calculation (planets, Placidus houses, aspects, synastry)
+summary: Pure-Ruby astrology chart calculation (planets, Placidus/whole-sign houses,
+  aspects, synastry, transits, progressions, composite, solar returns)
 test_files: []