🌟 manim-astro

Astronomical animations for Manim - Create stunning, scientifically accurate visualizations of astronomical phenomena.

✨ Features

• 🌟 Physically accurate stellar models with proper color-temperature relations
• 🌌 Galaxy simulations with realistic morphologies
• 🪐 Orbital mechanics using real gravitational physics
• 📊 Astronomical diagrams (HR, Hubble, CMDs)
• 🔭 Observation planning tools and projections
• 🌈 Spectroscopy animations with real line physics
• 🚀 Cosmological simulations with proper scaling

🚀 Quick Start

Installation

pip install manim-astro

For development:

git clone https://github.com/yourusername/manim-astro.git
cd manim-astro
pip install -e ".[dev,docs]"

Basic Usage

from manim import *
from manim_astro import Star, HRDiagram

class StellarScene(Scene):
    def construct(self):
        # Create a main sequence star
        sun = Star(mass=1.0)
        self.add(sun)
        
        # Create an HR diagram
        hr_diagram = HRDiagram()
        hr_diagram.plot_main_sequence()
        self.play(Create(hr_diagram))

📚 Documentation

Full documentation available at manim-astro.readthedocs.io

• Installation Guide
• Tutorials
• API Reference
• Example Gallery

🎓 Educational Examples

Main Sequence Stars

# Demonstrate mass-luminosity relation
star_sequence = StarSequence(masses=[0.5, 1.0, 2.0, 5.0])
star_sequence.show_scaling_relations()

Galaxy Evolution

# Animate galaxy collision
galaxy1 = SpiralGalaxy(mass=1e12)
galaxy2 = SpiralGalaxy(mass=5e11)
collision = GalaxyCollision(galaxy1, galaxy2)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

This project is licensed under the MIT License - see LICENSE file.

🙏 Acknowledgments

• Manim Community for the amazing animation framework
• ASTR596 course at [Your University]
• Astronomical data from ESA Gaia, SDSS, and NASA

📖 Citation

If you use manim-astro in your research or teaching, please cite:

@software{manim_astro,
  author = {Your Name},
  title = {manim-astro: Astronomical Animations for Manim},
  year = {2024},
  url = {https://github.com/yourusername/manim-astro}
}

### **CONTRIBUTING.md**
```markdown
# Contributing to manim-astro

Thank you for your interest in contributing to manim-astro! 

## 🚀 Getting Started

1. Fork the repository
2. Clone your fork:
   ```bash
   git clone https://github.com/yourusername/manim-astro.git
   cd manim-astro

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

4. Install in development mode:

   pip install -e ".[dev,docs]"
   pre-commit install

🔧 Development Workflow

1. Create a new branch:

   git checkout -b feature/your-feature-name

2. Make your changes and ensure:

   • All tests pass: pytest
   • Code is formatted: black src/ tests/
   • Imports are sorted: isort src/ tests/
   • Type hints are correct: mypy src/

3. Write tests for new features

4. Update documentation if needed

5. Commit with descriptive messages:

   git commit -m "feat: add binary star system class"

6. Push and create a pull request

📝 Code Style

• Follow PEP 8
• Use Black for formatting
• Add type hints for all functions
• Document with NumPy-style docstrings

🧪 Testing

Run tests with:

pytest                          # All tests
pytest tests/unit/test_star.py  # Specific file
pytest -v --cov=manim_astro    # With coverage

📚 Documentation

Build docs locally:

cd docs
make html
open _build/html/index.html

🌟 Areas for Contribution

• New celestial objects: Nebulae, clusters, etc.
• Physical processes: Accretion, jets, shocks
• Observational tools: Telescope simulations
• Educational animations: Tutorials and demos
• Performance optimizations: Speed improvements
• Documentation: Tutorials, examples, API docs

📄 Pull Request Process

1. Ensure all tests pass
2. Update CHANGELOG.md
3. Update documentation
4. Request review from maintainers

🤝 Code of Conduct

Please read our Code of Conduct.

❓ Questions?

Open an issue or join our Discord: [link]

### **tests/conftest.py** - Pytest Configuration
```python
"""
Pytest configuration and fixtures for manim-astro tests.
"""

import pytest
import numpy as np
from manim import *
import tempfile
import shutil
from pathlib import Path

# Configure Manim for testing
config.verbosity = "WARNING"
config.preview = False
config.progress_bar = "none"
config.background_color = BLACK

@pytest.fixture
def temp_media_dir():
    """Create temporary directory for test media files."""
    temp_dir = tempfile.mkdtemp()
    original_media_dir = config.media_dir
    config.media_dir = temp_dir
    
    yield Path(temp_dir)
    
    # Cleanup
    config.media_dir = original_media_dir
    shutil.rmtree(temp_dir)

@pytest.fixture
def test_scene():
    """Create a test scene for animations."""
    class TestScene(Scene):
        def construct(self):
            pass
    
    return TestScene()

@pytest.fixture
def sample_star_data():
    """Sample stellar parameters for testing."""
    return {
        'sun': {'mass': 1.0, 'radius': 1.0, 'temperature': 5772},
        'sirius': {'mass': 2.06, 'radius': 1.71, 'temperature': 9940},
        'proxima': {'mass': 0.12, 'radius': 0.15, 'temperature': 3042},
        'betelgeuse': {'mass': 20, 'radius': 1000, 'temperature': 3500},
    }

@pytest.fixture
def sample_galaxy_data():
    """Sample galaxy parameters for testing."""
    return {
        'milky_way': {
            'mass': 1.5e12,  # M_sun
            'radius': 50000,  # pc
            'type': 'spiral'
        },
        'andromeda': {
            'mass': 1.2e12,
            'radius': 60000,
            'type': 'spiral'
        }
    }

GitHub Actions Workflow - .github/workflows/tests.yml

name: Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.8', '3.9', '3.10', '3.11']

    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v4
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install system dependencies (Ubuntu)
      if: runner.os == 'Linux'
      run: |
        sudo apt-get update
        sudo apt-get install -y ffmpeg libcairo2-dev
    
    - name: Install system dependencies (macOS)
      if: runner.os == 'macOS'
      run: |
        brew install ffmpeg cairo
    
    - name: Install Python dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[dev]"
    
    - name: Lint with flake8
      run: |
        flake8 src/ tests/ --count --select=E9,F63,F7,F82 --show-source --statistics
    
    - name: Check formatting with black
      run: |
        black --check src/ tests/
    
    - name: Sort imports with isort
      run: |
        isort --check-only src/ tests/
    
    - name: Type check with mypy
      run: |
        mypy src/
    
    - name: Test with pytest
      run: |
        pytest --cov=manim_astro --cov-report=xml --cov-report=term
    
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3
      with:
        file: ./coverage.xml
        flags: unittests
        name: codecov-umbrella

🚀 Getting Started Commands

# 1. Create the repository structure
mkdir manim-astro
cd manim-astro

# 2. Initialize git
git init
git remote add origin https://github.com/yourusername/manim-astro.git

# 3. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 4. Create the directory structure
mkdir -p src/manim_astro/{celestial,coordinates,physics,spectroscopy,diagrams,data,utils,animations}
mkdir -p tests/{unit,integration,fixtures}
mkdir -p docs/{api,tutorials,gallery,_static}
mkdir -p examples/{basic,intermediate,advanced}
mkdir -p scripts
mkdir -p media/{images,videos,logos}
mkdir -p .github/workflows

# 5. Create all the configuration files
# Copy the content from above into respective files

# 6. Install in development mode
pip install -e ".[dev,docs]"

# 7. Initialize pre-commit
pre-commit install

# 8. Run initial tests
pytest

# 9. Build documentation
cd docs
sphinx-quickstart
make html

# 10. Initial commit
git add .
git commit -m "feat: initial manim-astro package structure"
git push -u origin main

📋 Development Checklist

• Set up repository structure
• Configure packaging (pyproject.toml)
• Set up testing framework
• Configure CI/CD (GitHub Actions)
• Set up documentation (Sphinx)
• Create initial Star class
• Write comprehensive tests
• Add example animations
• Configure pre-commit hooks
• Set up code coverage
• Create contribution guidelines
• Add issue templates
• Configure automated releases
• Set up ReadTheDocs
• Create project logo
• Write comprehensive README

### 📁 Complete Directory Structure

manim-astro/
│
├── 📄 README.md                    # Main project documentation
├── 📄 LICENSE                      # MIT License
├── 📄 CONTRIBUTING.md              # Contribution guidelines
├── 📄 CHANGELOG.md                 # Version history
├── 📄 CODE_OF_CONDUCT.md          # Community guidelines
├── 📄 pyproject.toml              # Modern Python packaging config
├── 📄 setup.cfg                   # Additional setup configuration
├── 📄 MANIFEST.in                 # Include non-Python files
├── 📄 .gitignore                  # Git ignore patterns
├── 📄 .gitattributes              # Git attributes
│
├── 📂 .github/                    # GitHub specific files
│   ├── 📂 workflows/              # GitHub Actions CI/CD
│   │   ├── tests.yml              # Run tests on push/PR
│   │   ├── docs.yml               # Build and deploy docs
│   │   ├── release.yml            # Automated releases
│   │   └── lint.yml               # Code quality checks
│   ├── 📂 ISSUE_TEMPLATE/         # Issue templates
│   │   ├── bug_report.md
│   │   ├── feature_request.md
│   │   └── documentation.md
│   └── 📄 PULL_REQUEST_TEMPLATE.md
│
├── 📂 src/                        # Source code (src layout)
│   └── 📂 manim_astro/
│       ├── 📄 __init__.py         # Package initialization
│       ├── 📄 __version__.py      # Version information
│       │
│       ├── 📂 celestial/          # Celestial objects
│       │   ├── __init__.py
│       │   ├── star.py            # Star class
│       │   ├── planet.py          # Planet classes
│       │   ├── galaxy.py          # Galaxy classes
│       │   ├── binary.py          # Binary systems
│       │   └── exotics.py         # Pulsars, black holes, etc.
│       │
│       ├── 📂 coordinates/        # Coordinate systems
│       │   ├── __init__.py
│       │   ├── celestial.py       # RA/Dec, Alt/Az
│       │   ├── projections.py     # Sky projections
│       │   └── transformations.py # Coordinate transforms
│       │
│       ├── 📂 physics/            # Physical processes
│       │   ├── __init__.py
│       │   ├── radiation.py       # Radiation processes
│       │   ├── dynamics.py        # Orbital mechanics
│       │   ├── relativity.py      # GR effects
│       │   └── cosmology.py       # Cosmological models
│       │
│       ├── 📂 spectroscopy/       # Spectral analysis
│       │   ├── __init__.py
│       │   ├── spectrum.py        # Spectrum classes
│       │   ├── lines.py           # Spectral lines
│       │   └── photometry.py      # Photometric tools
│       │
│       ├── 📂 diagrams/           # Astronomical diagrams
│       │   ├── __init__.py
│       │   ├── hr_diagram.py      # HR diagram
│       │   ├── hubble.py          # Hubble diagram
│       │   └── color_magnitude.py # CMD
│       │
│       ├── 📂 data/               # Package data
│       │   ├── __init__.py
│       │   ├── constants.py       # Physical constants
│       │   ├── catalogs/          # Star catalogs
│       │   ├── filters/           # Filter curves
│       │   └── colormaps/         # Custom colormaps
│       │
│       ├── 📂 utils/              # Utilities
│       │   ├── __init__.py
│       │   ├── units.py           # Unit conversions
│       │   ├── validators.py      # Input validation
│       │   ├── data_loader.py     # Load FITS, etc.
│       │   └── colors.py          # Color utilities
│       │
│       └── 📂 animations/         # Pre-built animations
│           ├── __init__.py
│           ├── stellar_evolution.py
│           ├── galaxy_collision.py
│           └── cosmological_evolution.py
│
├── 📂 tests/                      # Test suite
│   ├── 📄 __init__.py
│   ├── 📄 conftest.py            # Pytest configuration
│   ├── 📂 unit/                  # Unit tests
│   │   ├── test_star.py
│   │   ├── test_coordinates.py
│   │   └── test_physics.py
│   ├── 📂 integration/           # Integration tests
│   │   └── test_animations.py
│   └── 📂 fixtures/              # Test data
│       └── sample_data.py
│
├── 📂 examples/                   # Example animations
│   ├── 📄 README.md
│   ├── 📂 basic/                 # Basic examples
│   │   ├── 01_creating_stars.py
│   │   ├── 02_hr_diagram.py
│   │   └── 03_orbits.py
│   ├── 📂 intermediate/          # Intermediate examples
│   │   ├── stellar_evolution.py
│   │   ├── binary_systems.py
│   │   └── galaxy_rotation.py
│   └── 📂 advanced/              # Advanced examples
│       ├── nbody_simulation.py
│       ├── cosmological_sim.py
│       └── gravitational_lensing.py
│
├── 📂 docs/                      # Documentation
│   ├── 📄 conf.py               # Sphinx configuration
│   ├── 📄 index.rst             # Documentation home
│   ├── 📄 installation.rst      # Installation guide
│   ├── 📄 quickstart.rst        # Quick start guide
│   ├── 📄 requirements.txt      # Docs dependencies
│   ├── 📂 api/                  # API reference
│   │   └── modules.rst
│   ├── 📂 tutorials/            # Tutorials
│   │   ├── index.rst
│   │   ├── stellar.rst
│   │   └── cosmology.rst
│   ├── 📂 gallery/              # Example gallery
│   │   └── index.rst
│   └── 📂 _static/              # Static files
│       ├── css/
│       └── images/
│
├── 📂 scripts/                   # Utility scripts
│   ├── generate_catalog.py      # Generate star catalogs
│   ├── validate_physics.py      # Validate physics
│   └── benchmark.py             # Performance benchmarks
│
└── 📂 media/                     # Media files
    ├── 📂 images/               # README images
    ├── 📂 videos/               # Demo videos
    └── 📂 logos/                # Project logos