astrolith 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d189aaf9ea9a6f0c78bd37ef2db4d5c466ed2dfb6ddaa167d57a7a66ee1704d
+  data.tar.gz: fd4a37d35802c4c6646dc37e805921d0095d3802c7e162fcce553ca94ef5468b
+SHA512:
+  metadata.gz: b66c0604a9c413c15fefd9054a93e97baab4ed63940fdc20ce7bcc50d2ad0c53c3fb727d79a9a4ba617ddead19e1461a5a19912e0cdbda69dafa16238bc6f2cb
+  data.tar.gz: 61f675bb33986226be7385fa20f6cd0cc58574add760ade7bc91f5ed363f7a127f642ed1fa596c0829a0f898e1db90d0b91e3b1f427f0627f854323f6a5580e4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Go-pye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,317 @@
+# Astrolith
+
+A Ruby port of the [immanuel-python](https://github.com/theriftlab/immanuel-python) astrology library, functioning as a decoupled data calculation engine with structured JSON output.
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]()
+[![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red)]()
+
+## Features
+
+- **Multiple Chart Types**: Natal, Solar Return, Progressed, Composite, Transit
+- **Comprehensive Data**: Planets, houses, aspects, dignities, decans, moon phase, chart shape
+- **Swiss Ephemeris**: High-precision astronomical calculations using built-in Moshier ephemeris
+- **No External Files Required**: Uses analytical ephemeris (precision: ~0.1 arc seconds for planets, ~3" for Moon)
+- **JSON Output**: Structured data output for easy integration
+- **Flexible Input**: Multiple formats for coordinates, datetime, and timezone
+- **7 House Systems**: Placidus, Koch, Whole Sign, Equal, Porphyrius, Regiomontanus, Campanus
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'astrolith'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install astrolith
+```
+
+## Quick Start
+
+```ruby
+require 'ruby_chart_engine'
+
+# Create a natal chart
+chart = RubyChartEngine::Charts::Natal.new(
+  datetime: '1990-05-15T14:30:00',
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York',
+  house_system: :placidus
+)
+
+# Access chart data
+puts chart.planets[:sun][:sign][:name]  # => "Taurus"
+puts chart.planets[:sun][:house]        # => 10
+puts chart.moon_phase                   # => "Waxing Gibbous"
+puts chart.chart_shape                  # => "bowl"
+
+# Export to JSON
+json = chart.to_json
+puts json
+```
+
+## Usage Examples
+
+### Natal Chart
+
+```ruby
+chart = RubyChartEngine::Charts::Natal.new(
+  datetime: '1990-05-15T14:30:00',
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York'
+)
+
+# Access planetary data
+sun = chart.planets[:sun]
+# => {
+#   longitude: 54.123,
+#   sign_longitude: 24.123,
+#   sign: { name: "Taurus", element: "Earth", modality: "Fixed" },
+#   house: 10,
+#   decan: 3,
+#   movement: "direct",
+#   dignities: { domicile: false, exaltation: false, ... }
+# }
+
+# Check aspects
+chart.aspects.each do |aspect|
+  puts "#{aspect[:planet1]} #{aspect[:type]} #{aspect[:planet2]} (orb: #{aspect[:orb]}�)"
+end
+```
+
+### Solar Return
+
+```ruby
+solar_return = RubyChartEngine::Charts::SolarReturn.new(
+  natal_datetime: '1990-05-15T14:30:00',
+  return_year: 2024,
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York'
+)
+```
+
+### Progressed Chart
+
+```ruby
+progressed = RubyChartEngine::Charts::Progressed.new(
+  natal_datetime: '1990-05-15T14:30:00',
+  progression_date: '2024-03-15',
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York'
+)
+```
+
+### Composite Chart
+
+```ruby
+composite = RubyChartEngine::Charts::Composite.new(
+  chart1_params: {
+    datetime: '1990-05-15T14:30:00',
+    latitude: 40.7128,
+    longitude: -74.0060,
+    timezone: 'America/New_York'
+  },
+  chart2_params: {
+    datetime: '1992-08-20T10:00:00',
+    latitude: 34.0522,
+    longitude: -118.2437,
+    timezone: 'America/Los_Angeles'
+  }
+)
+```
+
+### Transit Chart
+
+```ruby
+natal = RubyChartEngine::Charts::Natal.new(
+  datetime: '1990-05-15T14:30:00',
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York'
+)
+
+transit = RubyChartEngine::Charts::Transit.new(
+  natal_chart_params: natal,
+  transit_datetime: Time.now.iso8601
+)
+
+# View transit aspects
+transit.transit_aspects.each do |aspect|
+  puts "#{aspect[:planet1]} #{aspect[:type]} #{aspect[:planet2]}"
+end
+```
+
+## Input Formats
+
+### Coordinates
+
+```ruby
+# Decimal degrees
+latitude: 40.7128, longitude: -74.0060
+
+# Text format (degrees and minutes)
+latitude: '40n43', longitude: '74w00'
+
+# Mixed formats work too
+latitude: 40.7128, longitude: '74w00'
+```
+
+### DateTime
+
+```ruby
+# ISO 8601 string
+datetime: '1990-05-15T14:30:00'
+
+# Hash
+datetime: { year: 1990, month: 5, day: 15, hour: 14, minute: 30 }
+
+# Ruby DateTime object
+datetime: DateTime.new(1990, 5, 15, 14, 30, 0)
+```
+
+### House Systems
+
+```ruby
+# Available systems:
+house_system: :placidus       # Default
+house_system: :koch
+house_system: :whole_sign
+house_system: :equal
+house_system: :porphyrius
+house_system: :regiomontanus
+house_system: :campanus
+```
+
+## Output Structure
+
+```json
+{
+  "metadata": {
+    "datetime": "1990-05-15T14:30:00+00:00",
+    "julian_day": 2448025.1041666665,
+    "latitude": 40.7128,
+    "longitude": -74.006,
+    "timezone": "America/New_York",
+    "house_system": "placidus"
+  },
+  "planets": {
+    "sun": {
+      "longitude": 54.123,
+      "sign_longitude": 24.123,
+      "sign": { "name": "Taurus", "element": "Earth", "modality": "Fixed" },
+      "house": 10,
+      "decan": 3,
+      "movement": "direct",
+      "dignities": { "domicile": false, "exaltation": false, ... }
+    }
+  },
+  "houses": { "cusps": [...] },
+  "angles": { "ascendant": {...}, "midheaven": {...}, ... },
+  "aspects": [...],
+  "moon_phase": "Waxing Gibbous",
+  "chart_shape": "bowl"
+}
+```
+
+## Celestial Objects
+
+**Planets**: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto
+
+**Points**: North Node, South Node *(Note: Chiron is not available when using the built-in Moshier ephemeris)*
+
+**Angles**: Ascendant, Midheaven, Descendant, Imum Coeli
+
+## Aspects
+
+Supported aspects with configurable orbs:
+- Conjunction (0�)
+- Opposition (180�)
+- Trine (120�)
+- Square (90�)
+- Sextile (60�)
+- Quincunx (150�)
+- Semi-Sextile (30�)
+- Semi-Square (45�)
+- Sesquiquadrate (135�)
+
+## Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+
+# With documentation format
+bundle exec rspec --format documentation
+
+# Run specific test file
+bundle exec rspec spec/charts/natal_spec.rb
+```
+
+## Dependencies
+
+- **swe4r**: Swiss Ephemeris C extension for astronomical calculations
+- **ephemeris**: Higher-level astrological logic built on swe4r
+- **daru**: Data Analysis in Ruby for data structuring
+- **tzinfo**: Timezone handling
+
+### Optional Visualization
+
+- **apexcharts**: For analytical charts
+- **prawn**: For PDF and geometric drawing (chart wheels)
+
+## Documentation
+
+- [Quick Start Guide](docs/QUICK_START.md) - Get started quickly with common use cases
+- [Project Overview](docs/PROJECT_OVERVIEW.md) - Architecture and implementation details
+- [Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md) - Technical implementation notes
+
+## Development
+
+After checking out the repo:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run console for experimentation
+bundle console
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+This library is a Ruby port of [immanuel-python](https://github.com/theriftlab/immanuel-python), maintaining compatibility with its JSON output structure while leveraging Ruby's ecosystem.
+
+## Notes
+
+- This implementation uses the **built-in Moshier ephemeris** (analytical calculations) which provides excellent precision without requiring external ephemeris files
+- Chiron is not available with the Moshier ephemeris (would require external `.se1` files)
+- For production use with extended date ranges or maximum precision, consider using the full Swiss Ephemeris with external data files

data/astrolith.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |spec|
+  spec.name          = "astrolith"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Go-pye"]
+  spec.email         = ["Go-pye@users.noreply.github.com"]
+
+  spec.summary       = "A Ruby port of immanuel-python astrology library"
+  spec.description   = "Astrolith is a decoupled astrological data calculation engine that generates structured JSON output. It supports multiple chart types including Natal, Solar Return, Progressed, Composite, and Transit charts."
+  spec.homepage      = "https://github.com/Go-pye/astrolith"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.files = Dir.glob("{lib,examples}/**/*") + %w[
+    README.md
+    LICENSE
+    astrolith.gemspec
+  ]
+
+  spec.require_paths = ["lib"]
+
+  # Core dependencies
+  spec.add_dependency "swe4r", "~> 0.0.2"
+  spec.add_dependency "ephemeris", "~> 0.1"
+  spec.add_dependency "daru", "~> 0.3"
+  spec.add_dependency "tzinfo", "~> 2.0"
+
+  # Optional visualization dependencies
+  spec.add_dependency "apexcharts", "~> 0.1"
+  spec.add_dependency "prawn", "~> 2.4"
+
+  # Development dependencies
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "pry", "~> 0.14"
+end

data/examples/example_usage.rb

@@ -0,0 +1,154 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/ruby_chart_engine'
+
+# Example 1: Basic Natal Chart
+puts "=" * 80
+puts "Example 1: Basic Natal Chart"
+puts "=" * 80
+
+natal_chart = RubyChartEngine::Charts::Natal.new(
+  datetime: '1990-05-15T14:30:00',
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York',
+  house_system: :placidus
+)
+
+puts "\nSun Position:"
+sun = natal_chart.planets[:sun]
+puts "  Longitude: #{sun[:longitude].round(2)}°"
+puts "  Sign: #{sun[:sign][:name]}"
+puts "  House: #{sun[:house]}"
+puts "  Movement: #{sun[:movement]}"
+
+puts "\nMoon Position:"
+moon = natal_chart.planets[:moon]
+puts "  Longitude: #{moon[:longitude].round(2)}°"
+puts "  Sign: #{moon[:sign][:name]}"
+puts "  House: #{moon[:house]}"
+
+puts "\nMoon Phase: #{natal_chart.moon_phase}"
+puts "Chart Shape: #{natal_chart.chart_shape}"
+
+puts "\nAspects (first 3):"
+natal_chart.aspects.take(3).each do |aspect|
+  puts "  #{aspect[:planet1]} #{aspect[:type]} #{aspect[:planet2]} (orb: #{aspect[:orb].round(2)}°)"
+end
+
+# Example 2: Solar Return Chart
+puts "\n" + "=" * 80
+puts "Example 2: Solar Return Chart for 2024"
+puts "=" * 80
+
+solar_return = RubyChartEngine::Charts::SolarReturn.new(
+  natal_datetime: '1990-05-15T14:30:00',
+  return_year: 2024,
+  latitude: 40.7128,
+  longitude: -74.0060,
+  timezone: 'America/New_York'
+)
+
+puts "\nSolar Return Date: #{solar_return.datetime.datetime}"
+puts "Natal Sun Longitude: #{solar_return.natal_sun_longitude.round(2)}°"
+puts "Solar Return Sun: #{solar_return.planets[:sun][:longitude].round(2)}°"
+
+# Example 3: Composite Chart
+puts "\n" + "=" * 80
+puts "Example 3: Composite Chart"
+puts "=" * 80
+
+composite = RubyChartEngine::Charts::Composite.new(
+  chart1_params: {
+    datetime: '1990-05-15T14:30:00',
+    latitude: 40.7128,
+    longitude: -74.0060,
+    timezone: 'America/New_York'
+  },
+  chart2_params: {
+    datetime: '1992-08-20T10:00:00',
+    latitude: 34.0522,
+    longitude: -118.2437,
+    timezone: 'America/Los_Angeles'
+  }
+)
+
+puts "\nComposite Sun:"
+comp_sun = composite.planets[:sun]
+puts "  Longitude: #{comp_sun[:longitude].round(2)}°"
+puts "  Sign: #{comp_sun[:sign][:name]}"
+puts "  House: #{comp_sun[:house]}"
+
+# Example 4: Transit Chart
+puts "\n" + "=" * 80
+puts "Example 4: Transit Chart"
+puts "=" * 80
+
+transit = RubyChartEngine::Charts::Transit.new(
+  natal_chart_params: natal_chart,
+  transit_datetime: '2024-03-15T12:00:00'
+)
+
+puts "\nTransit Aspects to Natal Chart (first 5):"
+transit.transit_aspects.take(5).each do |aspect|
+  puts "  Transit #{aspect[:planet1]} #{aspect[:type]} Natal #{aspect[:planet2]} (orb: #{aspect[:orb].round(2)}°)"
+end
+
+# Example 5: JSON Export
+puts "\n" + "=" * 80
+puts "Example 5: JSON Export"
+puts "=" * 80
+
+puts "\nNatal Chart as JSON (pretty):"
+json = RubyChartEngine::Serializers::JsonSerializer.serialize_pretty(natal_chart)
+puts json[0..500] + "..."
+
+puts "\nChart with filtered output (metadata and planets only):"
+filtered_json = RubyChartEngine::Serializers::JsonSerializer.serialize_with_options(
+  natal_chart,
+  include: [:metadata, :planets],
+  pretty: true
+)
+puts filtered_json[0..300] + "..."
+
+# Example 6: Different Coordinate Formats
+puts "\n" + "=" * 80
+puts "Example 6: Different Coordinate Formats"
+puts "=" * 80
+
+# Standard text format
+chart_text = RubyChartEngine::Charts::Natal.new(
+  datetime: '1990-05-15T14:30:00',
+  latitude: '40n43',
+  longitude: '74w00',
+  timezone: 'America/New_York'
+)
+
+puts "\nChart with text coordinates:"
+puts "  Latitude: #{chart_text.coordinates.latitude.round(4)}°"
+puts "  Longitude: #{chart_text.coordinates.longitude.round(4)}°"
+
+# Example 7: Different House Systems
+puts "\n" + "=" * 80
+puts "Example 7: Different House Systems"
+puts "=" * 80
+
+house_systems = [:placidus, :koch, :whole_sign, :equal]
+
+house_systems.each do |system|
+  chart = RubyChartEngine::Charts::Natal.new(
+    datetime: '1990-05-15T14:30:00',
+    latitude: 40.7128,
+    longitude: -74.0060,
+    timezone: 'America/New_York',
+    house_system: system
+  )
+
+  puts "\n#{system.to_s.capitalize} House System:"
+  puts "  1st House Cusp: #{chart.houses[:cusps][0].round(2)}°"
+  puts "  10th House Cusp: #{chart.houses[:cusps][9].round(2)}°"
+end
+
+puts "\n" + "=" * 80
+puts "Examples Complete!"
+puts "=" * 80

data/lib/ruby_chart_engine/calculations/aspects.rb

@@ -0,0 +1,88 @@
+module RubyChartEngine
+  module Calculations
+    class Aspects
+      # Standard aspect definitions with orbs
+      ASPECT_TYPES = {
+        conjunction: { angle: 0, orb: 8 },
+        opposition: { angle: 180, orb: 8 },
+        trine: { angle: 120, orb: 8 },
+        square: { angle: 90, orb: 8 },
+        sextile: { angle: 60, orb: 6 },
+        quincunx: { angle: 150, orb: 3 },
+        semi_sextile: { angle: 30, orb: 3 },
+        semi_square: { angle: 45, orb: 3 },
+        sesquiquadrate: { angle: 135, orb: 3 }
+      }.freeze
+
+      # Calculate all aspects between two sets of planets
+      def self.calculate(planets1, planets2 = nil)
+        planets2 ||= planets1
+        aspects = []
+
+        planets1.each do |name1, data1|
+          planets2.each do |name2, data2|
+            # Skip if comparing planet to itself
+            next if planets2.equal?(planets1) && name1 == name2
+
+            # Skip if we've already calculated this pair (for same chart)
+            next if planets2.equal?(planets1) && planets1.keys.index(name1) >= planets1.keys.index(name2)
+
+            aspect = find_aspect(
+              data1[:longitude],
+              data2[:longitude],
+              name1,
+              name2
+            )
+
+            aspects << aspect if aspect
+          end
+        end
+
+        aspects
+      end
+
+      # Find aspect between two longitudes
+      def self.find_aspect(lon1, lon2, name1, name2)
+        angle = calculate_angle(lon1, lon2)
+
+        ASPECT_TYPES.each do |type, config|
+          diff = (angle - config[:angle]).abs
+
+          if diff <= config[:orb]
+            return {
+              type: type,
+              planet1: name1,
+              planet2: name2,
+              angle: config[:angle],
+              orb: diff,
+              applying: false # TODO: Calculate if aspect is applying or separating
+            }
+          end
+        end
+
+        nil
+      end
+
+      # Calculate the angle between two longitudes
+      def self.calculate_angle(lon1, lon2)
+        diff = (lon2 - lon1).abs
+        diff = 360 - diff if diff > 180
+        diff
+      end
+
+      # Determine if aspect is applying or separating based on speeds
+      def self.applying?(planet1_data, planet2_data, aspect_angle)
+        # Get speeds
+        speed1 = planet1_data[:speed_longitude]
+        speed2 = planet2_data[:speed_longitude]
+
+        # If speeds are moving toward exact aspect, it's applying
+        # This is a simplified calculation
+        relative_speed = speed2 - speed1
+
+        # If faster planet is behind slower planet, aspect is applying
+        relative_speed > 0
+      end
+    end
+  end
+end

data/lib/ruby_chart_engine/calculations/dignities.rb

@@ -0,0 +1,71 @@
+module RubyChartEngine
+  module Calculations
+    class Dignities
+      # Essential dignities table
+      RULERSHIPS = {
+        aries: { ruler: :mars, detriment: :venus, exaltation: :sun, fall: :saturn },
+        taurus: { ruler: :venus, detriment: :mars, exaltation: :moon, fall: nil },
+        gemini: { ruler: :mercury, detriment: :jupiter, exaltation: nil, fall: nil },
+        cancer: { ruler: :moon, detriment: :saturn, exaltation: :jupiter, fall: :mars },
+        leo: { ruler: :sun, detriment: :saturn, exaltation: nil, fall: nil },
+        virgo: { ruler: :mercury, detriment: :jupiter, exaltation: :mercury, fall: :venus },
+        libra: { ruler: :venus, detriment: :mars, exaltation: :saturn, fall: :sun },
+        scorpio: { ruler: :mars, detriment: :venus, exaltation: nil, fall: :moon },
+        sagittarius: { ruler: :jupiter, detriment: :mercury, exaltation: nil, fall: nil },
+        capricorn: { ruler: :saturn, detriment: :moon, exaltation: :mars, fall: :jupiter },
+        aquarius: { ruler: :saturn, detriment: :sun, exaltation: nil, fall: nil },
+        pisces: { ruler: :jupiter, detriment: :mercury, exaltation: :venus, fall: :mercury }
+      }.freeze
+
+      # Modern rulerships (for outer planets)
+      MODERN_RULERSHIPS = {
+        scorpio: :pluto,
+        aquarius: :uranus,
+        pisces: :neptune
+      }.freeze
+
+      # Calculate dignities for a planet in a sign
+      def self.calculate(planet_name, sign_index)
+        sign_name = SIGNS[sign_index][:name].downcase.to_sym
+        dignities_for_sign = RULERSHIPS[sign_name]
+
+        return default_dignities unless dignities_for_sign
+
+        {
+          domicile: dignities_for_sign[:ruler] == planet_name,
+          detriment: dignities_for_sign[:detriment] == planet_name,
+          exaltation: dignities_for_sign[:exaltation] == planet_name,
+          fall: dignities_for_sign[:fall] == planet_name,
+          peregrine: !has_any_dignity?(planet_name, dignities_for_sign)
+        }
+      end
+
+      # Calculate dignity score
+      def self.score(dignities)
+        score = 0
+        score += 5 if dignities[:domicile]
+        score += 4 if dignities[:exaltation]
+        score -= 5 if dignities[:detriment]
+        score -= 4 if dignities[:fall]
+        score
+      end
+
+      private
+
+      def self.has_any_dignity?(planet_name, dignities_for_sign)
+        dignities_for_sign[:ruler] == planet_name ||
+          dignities_for_sign[:exaltation] == planet_name
+      end
+
+      def self.default_dignities
+        {
+          domicile: false,
+          detriment: false,
+          exaltation: false,
+          fall: false,
+          peregrine: true
+        }
+      end
+    end
+  end
+end