Skip to content

jes5199/starloom

BranchesTags

Repository files navigation

Starloom 2025

A streamlined Python toolkit for precise astronomical ephemeris calculations, data retrieval, and visualization, optimized for speed and ease of use.

Features

  • JPL Horizons Integration: Fetch precise planetary positions and orbital elements
  • Weft Binary Ephemeris: Efficiently handle binary ephemeris data for rapid calculations
  • Advanced Time Utilities: Accurate astronomical time conversions and manipulations
  • Retrograde Analysis: Find and analyze planetary retrograde periods
  • Data Visualization: Generate SVG visualizations of planetary positions
  • Flexible Storage: Multiple storage options including SQLite and binary formats
  • Smart Caching: Efficient data caching for improved performance

Quick Start

Installation

pip install -e .

Basic Usage

Get current planetary positions effortlessly:

starloom ephemeris venus
starloom ephemeris mars --date 2025-03-19T20:00:00
starloom ephemeris jupiter --location 34.0522,-118.2437,0

Example output:

2025-03-20 05:12:45 UTC
Venus Aries 4°, 8.5°N, 0.28 AU

Command Reference

Ephemeris Commands

Basic Position Queries

# Current position
starloom ephemeris venus --date now

# Specific date/time
starloom ephemeris mars --date 2025-03-19T20:00:00

# With location
starloom ephemeris jupiter --location 34.0522,-118.2437,0

Detailed Horizons Queries

# Get ecliptic coordinates
starloom horizons ecliptic venus --date now

# Get orbital elements
starloom horizons elements mars --date 2025-03-19T20:00:00

# Time range query
starloom horizons ecliptic venus \
    --start 2025-03-19T20:00:00 \
    --stop 2025-03-19T22:00:00 \
    --step 1h

Weft Binary Ephemeris Commands

Generate Weft Files

# Generate a weft file for a planet's quantity
starloom weft generate mars longitude \
    --start 2025-01-01 \
    --stop 2025-02-01 \
    --step 1h \
    --output mars_longitude.weft

# Combine weft files
starloom weft combine mars1.weft mars2.weft combined_mars.weft \
    --timespan 2020-2040

Using Weftballs

# Generate comprehensive planetary data (1900-2100)
python -m scripts.make_weftball mars

# Use weftball for calculations
starloom ephemeris mars \
    --source weft \
    --data mars_weftball.tar.gz \
    --date 2025-03-19T20:00:00

Generating Weftballs for Lunar Nodes

The lunar north node (Moon's ascending node) can be generated as a weftball:

# Generate lunar north node weftball for 1900-2100
python -m scripts.make_weftball lunar_north_node

# Or use the CLI directly for a specific time range
starloom weft generate lunar_north_node longitude \
  --start 2024-01-01 \
  --stop 2025-01-01 \
  --step 1h \
  --output lunar_north_node_2024.weft

The lunar north node is calculated from the Moon's orbital elements. The south node is always 180 degrees opposite the north node and can be calculated as (north_node + 180) % 360.

Retrograde Analysis

Find planetary retrograde periods with shadow periods and key aspects:

# Basic retrograde search
starloom retrograde mercury \
    --start 2024-01-01 \
    --stop 2024-12-31 \
    --output mercury_2024.json

# High precision with weftballs
starloom retrograde mars \
    --start 2024-01-01 \
    --stop 2025-12-31 \
    --source weft \
    --data mars_weftball.tar.gz \
    --sun-data sun_weftball.tar.gz \
    --step 6h \
    --output mars_retro.json

Decan Analysis

Find precise decan periods for the Sun with high accuracy:

# Find all decans from 1900 to 2099 using weftball
starloom decans \
    --start 1900-01-01 \
    --stop 2099-12-31 \
    --source weft \
    --data sun_weftball.tar.gz \
    --step 15m \
    --output decans_1900_2099.json

# Find decans for a specific period with high precision
starloom decans \
    --start 2025-03-30 \
    --stop 2025-04-10 \
    --step 15m \
    --format text

# Generate CSV output for spreadsheet analysis
starloom decans \
    --start 2025-01-01 \
    --stop 2025-12-31 \
    --format csv \
    --output decans_2025.csv

Example output:

Finding decan periods for the Sun...

Decan 2 of Aries:
  Ingress at: 2025-03-30T11:12:11.250000+00:00 (longitude: 9.999982°)
  Egress at: 2025-04-09T14:49:13.125000+00:00 (longitude: 20.000073°)

CSV output format:

sign,decan,ingress_date,ingress_longitude,egress_date,egress_longitude
Aries,2,2025-03-30 11:12:11,9.999982,2025-04-09 14:49:13,20.000073
Aries,3,2025-04-09 14:49:13,20.000073,2025-04-19 18:26:15,30.000064

The decan command provides:

  • Precise ingress and egress times (better than 15 seconds)
  • Exact ecliptic longitudes at transitions
  • Support for multiple output formats (text, JSON, CSV)
  • High-precision calculations using weftballs

Data Types and Formats

Ephemeris Output

Basic position output includes:

  • Date/time (UTC)
  • Zodiac position (° and sign)
  • Ecliptic latitude (°N/S)
  • Distance from Earth (AU)

Orbital Elements

Detailed elements include:

  • Eccentricity (EC)
  • Periapsis distance (QR) in km
  • Inclination (IN) in degrees
  • Longitude of Ascending Node (OM) in degrees
  • Argument of Perifocus (W) in degrees
  • Time of periapsis (Tp) as Julian Day Number
  • Mean motion (N) in degrees/sec
  • Mean anomaly (MA) in degrees
  • True anomaly (TA) in degrees
  • Semi-major axis (A) in km
  • Apoapsis distance (AD) in km
  • Sidereal orbit period (PR) in seconds

Retrograde Data Format

JSON output includes for each period:

{
  "retrograde_periods": [
    {
      "planet": "MARS",
      "pre_shadow_start": {
        "date": "2024-12-06T12:00:00",
        "julian_date": 2460289.0,
        "longitude": 295.5
      },
      "station_retrograde": {
        "date": "2024-12-31T18:00:00",
        "julian_date": 2460314.25,
        "longitude": 298.2
      },
      "station_direct": {
        "date": "2025-03-02T06:00:00",
        "julian_date": 2460375.75,
        "longitude": 282.4
      },
      "post_shadow_end": {
        "date": "2025-03-27T12:00:00",
        "julian_date": 2460401.0,
        "longitude": 285.1
      },
      "sun_aspect": {
        "date": "2025-01-15T00:00:00",
        "julian_date": 2460328.5,
        "longitude": 290.3
      }
    }
  ]
}

Advanced Usage

Data Storage & Caching

from starloom.cached_horizons.ephemeris import CachedHorizonsEphemeris
from datetime import datetime, timedelta

# Create a cached ephemeris instance
ephemeris = CachedHorizonsEphemeris(data_dir="./data")

# Prefetch data for future use
start_time = datetime.utcnow()
end_time = start_time + timedelta(days=30)
ephemeris.prefetch_data("mars", start_time, end_time, step_hours=24)

Using Weftballs Programmatically

from starloom.weft_ephemeris import WeftEphemeris
from datetime import datetime, timezone

# Create an ephemeris instance using a weftball
ephemeris = WeftEphemeris(data="mars_weftball.tar.gz")

# Get a planet's position
time_point = datetime(2025, 3, 22, tzinfo=timezone.utc)
position = ephemeris.get_planet_position("mars", time_point)

# Access position data
longitude = position[Quantity.ECLIPTIC_LONGITUDE]  # Degrees [0, 360)
latitude = position[Quantity.ECLIPTIC_LATITUDE]    # Degrees [-90, 90]
distance = position[Quantity.DELTA]                # Distance in AU

Project Structure

src/starloom/
├── cli/                # Command-line interface modules
│   ├── ephemeris.py   # Ephemeris calculation commands
│   ├── graphics.py    # SVG visualization commands
│   ├── horizons.py    # JPL Horizons API commands
│   ├── retrograde.py  # Retrograde period finder
│   └── weft.py        # Weft file manipulation commands
│
├── ephemeris/         # Abstract ephemeris interface and utilities
├── graphics/         # SVG visualization tools
├── horizons/         # JPL Horizons API integration
├── retrograde/       # Retrograde period detection and analysis
├── weft/            # Weft binary ephemeris tools
├── weft_ephemeris/  # Weft-based ephemeris implementation
├── cached_horizons/ # Cached JPL Horizons data access
├── local_horizons/  # Local SQLite-based data storage
├── space_time/      # Datetime and Julian date utilities
└── linting/         # Code quality tools

Development

Testing

Run all tests:

python -m pytest

Run specific test modules:

python -m pytest tests/local_horizons
python -m pytest tests/cached_horizons

Profiling

Profile any command for performance analysis:

python -m starloom.profile ephemeris mars --date 2025-03-19T20:00:00

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run the tests: python -m pytest tests/
  5. Submit a pull request

Supported Objects

  • Mercury
  • Venus
  • Earth
  • Mars
  • Jupiter
  • Saturn
  • Uranus
  • Neptune
  • Pluto
  • Sun
  • Moon

Date and Time Formats

  • ISO format: YYYY-MM-DDTHH:MM:SS
  • "now" for current time
  • UTC assumed if no timezone specified

Step sizes for time ranges:

  • 1d: 1 day
  • 1h: 1 hour
  • 30m: 30 minutes
  • 1m: 1 minute

License

[Add license information here]

About

ephemeris management tool

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages