Exomoon Detection Pipeline

Pipeline for scanning and deep-diving exoplanet transit light curves for exomoon-like signals.

Setup

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt

Main Entry Points

• comprehensive_exomoon_search.py
  Batch scan across many planets. Outputs both:
  • combined_single_moon_score
  • combined_multi_moon_score
• test_single_planet_v2.py
  Single-target analysis with deep-dive diagnostics (single-moon and multi-moon passes).

Quick Start

Batch scan

python3 comprehensive_exomoon_search.py --input ranked_transiting_planets.csv --output comprehensive_exomoon_results.csv

Single-target deep-dive

python3 test_single_planet_v2.py "WASP-10 b" --deep-dive --catalog ranked_transiting_planets_enriched.csv

Deep-dive outputs both single- and multi-hypothesis diagnostics in one run.

Scoring Notes

• The scan and deep-dive both expose two final scores:
  • combined_single_moon_score
  • combined_multi_moon_score
• combined_exomoon_score is kept as a backward-compatible alias to the single score.
• Skew distribution diagnostics now separate:
  • *_skew_dist_score (consistency score; higher means closer to the single-moon occupancy hypothesis)
  • *_skew_dist_inconsistency_score (higher means stronger mismatch with that hypothesis)

Long-Run Stability Note

For long batch scans, a rare native-library teardown crash may print a segmentation fault after processing completes. If the script already printed "Processing complete" and the output CSV row counts/status summary are intact, results are usually usable.

Documentation

• USAGE_GUIDE.md - CLI usage, output schema, dual-score interpretation
• CODE_WALKTHROUGH.md - current code flow and architecture map
• PIPELINE_IMPROVEMENTS.md - implementation notes and model evolution
• SUMMARY_AND_RECOMMENDATIONS.md - practical interpretation and follow-up guidance

Repository Hygiene

This repository is intentionally configured to stay clean of run artifacts.

Ignored by default (.gitignore):

• generated outputs (comprehensive_exomoon_results*.csv, *_deepdive.csv, shard files)
• generated planet lists (ranked_transiting_planets*.csv, planet_candidates_master.csv)
• caches/downloads (.cache/, .lightkurve/, *.fits)
• logs/temp/one-off local scripts (*.log, tmp/, scratch_*.py, *_old.py)
• local IDE/tooling artifacts (.cursor/, .pytest_cache/, .ruff_cache/, core.*)

If a generated file is already tracked by git history, .gitignore will not remove it automatically; untrack it explicitly before committing.

License

See repository license file.