{"id":25663488,"url":"https://github.com/bgeneto/planetary-alignment","last_synced_at":"2025-07-30T23:18:45.829Z","repository":{"id":274323897,"uuid":"922568727","full_name":"bgeneto/planetary-alignment","owner":"bgeneto","description":"A Python script to search for alignments of planets and the Moon in the ecliptic plane, with adjustable threshold and local sky plot generation.","archived":false,"fork":false,"pushed_at":"2025-04-22T22:17:20.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T16:25:47.043Z","etag":null,"topics":["alignment","astropy","planets"],"latest_commit_sha":null,"homepage":"https://planetary-align.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgeneto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-26T15:07:34.000Z","updated_at":"2025-04-22T22:17:23.000Z","dependencies_parsed_at":"2025-01-26T16:22:14.224Z","dependency_job_id":"3912a03e-292e-4ca1-95bc-87eba6a651dc","html_url":"https://github.com/bgeneto/planetary-alignment","commit_stats":null,"previous_names":["bgeneto/planetary-alignment"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bgeneto/planetary-alignment","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Fplanetary-alignment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Fplanetary-alignment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Fplanetary-alignment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Fplanetary-alignment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgeneto","download_url":"https://codeload.github.com/bgeneto/planetary-alignment/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Fplanetary-alignment/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267960366,"owners_count":24172496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alignment","astropy","planets"],"created_at":"2025-02-24T05:16:27.811Z","updated_at":"2025-07-30T23:18:45.743Z","avatar_url":"https://github.com/bgeneto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Planetary Alignment\n\n[Planetary Alignment Visualization](https://planetary-align.streamlit.app/)\n\nA computational tool for identifying multi-body celestial alignments using astronomical coordinate systems and parallel processing.\n\n## Table of Contents\n- [Key Features](#key-features)\n- [Astronomical Concepts Implemented](#astronomical-concepts-implemented)\n- [Code Structure \u0026 Algorithms](#code-structure--algorithms)\n- [Customization Options](#customization-options)\n- [Interpreting Results](#interpreting-results)\n- [Limitations \u0026 Approximations](#limitations--approximations)\n- [References](#references)\n\n## Key Features\n\n### 1. Multi-Mode Alignment Detection\n- **Pairwise Angular Separation**: Traditional approach checking maximum great-circle distance between any two bodies in ecliptic coordinates\n- **Longitude Clustering**: Alternative method considering only ecliptic longitude spread (ignores latitude differences)\n\n### 2. Observability Constraints\n- Local altitude threshold filtering (horizon clearance)\n- Real-time altazimuth coordinate transformation\n- Visibility window optimization\n\n### 3. High Temporal Resolution\n- Configurable time steps (1-24 hours)\n- Parallelized date processing for efficiency\n- Five-year search horizon\n\n## Astronomical Concepts Implemented\n\n### 1. Coordinate Systems\n- **Geocentric True Ecliptic**: \n  - Fundamental plane: Earth's orbital plane (ecliptic)\n  - Coordinates: Celestial longitude (λ) and latitude (β)\n  - Uses VSOP87 theory via JPL DE432s ephemeris\n- **Topocentric Horizontal**:\n  - Observer-centric coordinates (altitude/azimuth)\n  - Accounts for Earth rotation and observer location\n  - Uses Astropy's ITRS transformation chain\n\n### 2. Angular Separation Mathematics\n- Great-circle distance formula:\n$$\n  \\Delta\\sigma = \\arccos(\\sin\\beta_1\\sin\\beta_2 + \\cos\\beta_1\\cos\\beta_2\\cos\\Delta\\lambda)\n$$\n- Ecliptic longitude spread calculation:\n$$\n  \\text{Range} = \\max(\\lambda_i) - \\min(\\lambda_i) \\quad \\text{(mod 360°)}\n$$\n\n### 3. Planetary Motion Considerations\n- Inner planet orbital periods:\n  - Mercury: 88 days\n  - Venus: 225 days\n  - Moon: 27.3 days (sidereal)\n- Outer planet synodic periods:\n  - Jupiter: 398 days\n  - Saturn: 378 days\n\n## Code Structure \u0026 Algorithms\n\n### Core Functions\n\n1. **`get_ecliptic_positions()`**\n   - Ephemeris: JPL DE432s (1 arcsec accuracy)\n   - Transformations: ICRS → GCRS → GeocentricTrueEcliptic\n   - Output: Dictionary of λ/β positions\n\n2. **`check_ecliptic_alignment()`**\n   - Method dispatch for pairwise/longitude checks\n   - Circular statistics for longitude wrapping\n\n3. **`get_horizontal_positions()`**\n   - Location-specific transformations:\n     - EarthLocation → ITRS → AltAz\n   - Atmospheric refraction: Not modeled\n\n4. **Parallel Processing**\n   - ThreadPoolExecutor for date iteration\n   - Early termination on first valid alignment\n\n### Critical Algorithms\n\n```python\ndef check_alignment_for_date(...):\n    # Astronomical pipeline\n    positions = get_ecliptic_positions(bodies, date)\n    aligned = check_method(positions)\n    if aligned and check_visibility:\n        altaz = get_horizontal_positions(...)\n        visible = all(alt \u003e threshold)\n    return (date, aligned \u0026 visible)\n```\n\n## Customization Options\n\n### 1. Alignment Parameters\n| Parameter            | Range      | Astronomical Rationale                           |\n| -------------------- | ---------- | ------------------------------------------------ |\n| Separation Threshold | 5°-45°     | Moon's angular diameter ≈ 0.5°, conjunction \u003c 5° |\n| Time Step            | 1-24 hours | Mercury's daily motion ≈ 4°, Moon ≈ 13°          |\n| Minimum Altitude     | -20°-30°   | Atmospheric extinction limits (0° horizon)       |\n\n### 2. Detection Tradeoffs\n- **Conservative Settings** (5°, 1h steps):\n  - Likely miss events but high precision\n- **Permissive Settings** (30°, 6h steps):\n  - More false positives but better coverage\n\n## Interpreting Results\n\n### Sky Plot Analysis\n- Polar projection (altitude = radial axis)\n- Azimuth clockwise from North\n- Color-coded body markers\n\n### Physical Interpretation\n- **Ecliptic Alignment**: Solar system plane projection\n- **Local Sky Position**: Actual visual appearance\n- **Historical Context**: Notable alignments:\n  - 2000 BC: 5-planet alignment\n  - 2020: Jupiter-Saturn great conjunction (0.1°)\n\n## Limitations \u0026 Approximations\n\n1. **Geocentric Assumptions**\n   - Ignores parallax for Moon (up to 1° error)\n   - Assumes instantaneous Earth position\n\n2. **Time Resolution Limits**\n   - Mercury's maximum angular speed: 4.1°/day\n   - 6h steps → ±0.5° position uncertainty\n\n3. **Atmospheric Effects**\n   - No twilight/sun position checks\n   - Refraction not modeled below 0°\n\n4. **Ephemeris Limitations**\n   - DE432s accuracy (1550-2650 CE)\n   - No nongravitational forces for small bodies\n\n## References\n\n1. Astropy Collaboration (2022). \"Astropy v5.1\" \n   - ICRS/GCRS transformation models\n2. Folkner et al. (2014). \"JPL Planetary Ephemerides\"\n   - DE432s specification\n3. Meeus (1991). \"Astronomical Algorithms\"\n   - Angular separation mathematics\n4. USNO Circular 179 (2010)\n   - Coordinate system definitions\n\n---\n\n**License**: MIT Open Source  \n**Version**: 1.2 (2025-01-26)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgeneto%2Fplanetary-alignment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgeneto%2Fplanetary-alignment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgeneto%2Fplanetary-alignment/lists"}