Skip to content

migration_guide.md

Latest commit

 

History

History
executable file
·
335 lines (251 loc) · 7.98 KB

migration_guide.md

File metadata and controls

executable file
·
335 lines (251 loc) · 7.98 KB

Migration Guide: v0.1.x to v0.2.0

Overview

Version 0.2.0 introduces major architectural changes that make RadioSim more powerful and easier to use:

  • Package structure: Now installable via pip install radiosim
  • GPU support: Universal GPU acceleration (NVIDIA/AMD/Apple Silicon/TPU)
  • High-level API: New Simulator class for easy notebook and script usage
  • Backend abstraction: Auto-detect and use best available hardware
  • Jones matrix framework: Complete polarization support with 8 Jones terms
  • Type-safe configuration: Pydantic-based configuration validation

Breaking Changes

1. Import Paths Changed

Before (v0.1.x):

# Not importable as a package - CLI only
python src/main.py --config config.yaml

After (v0.2.0):

# Now importable as a proper Python package
import radiosim
from radiosim import Simulator
from radiosim.core import calculate_visibility
from radiosim.backends import get_backend

2. CLI Command Changed

Before:

python src/main.py --config config.yaml --antenna-file antennas.txt

After:

# Installed CLI command
radiosim --config config.yaml --antenna-file antennas.txt

# Or via pixi
pixi run radiosim --config config.yaml

3. Module Structure Reorganized

Before (flat structure):

src/
├── antenna.py
├── baseline.py
├── beams.py
├── visibility.py
├── main.py
└── ...

After (modular package):

src/radiosim/
├── core/           # Core astronomy calculations
│   ├── antenna.py
│   ├── baseline.py
│   ├── beams.py
│   ├── visibility.py
│   └── jones/      # Jones matrix framework
├── backends/       # Compute backends (NumPy, JAX, Numba)
├── simulator/      # RIME simulator implementation
├── api/            # High-level Simulator class
├── io/             # Configuration and I/O
├── cli/            # Command-line interface
└── visualization/  # Plotting modules

4. Configuration Changes

Before (raw dictionaries):

config = yaml.safe_load(open("config.yaml"))
# No validation, runtime errors for typos

After (Pydantic models):

from radiosim.io.config import RadioSimConfig, load_config

# Type-safe with validation
config = load_config("config.yaml")
print(config.telescope.telescope_name)  # IDE autocomplete works!

# Validation catches errors early
config = RadioSimConfig(
    obs_frequency={"starting_frequency": -100}  # ValidationError!
)

5. Antenna File Format Parameter

Before:

from src.antenna import read_antenna_positions
antennas = read_antenna_positions("file.txt", file_format="radiosim")

After:

from radiosim.io import read_antenna_positions
antennas = read_antenna_positions("file.txt", format_type="radiosim")

New Features

GPU Acceleration

RadioSim v0.2.0 supports multiple GPU backends:

from radiosim import Simulator

# Auto-detect best available backend
sim = Simulator(backend="auto")

# Or explicitly choose:
sim = Simulator(backend="jax")    # JAX (NVIDIA/AMD/Apple/TPU)
sim = Simulator(backend="numba")  # Numba (CUDA/ROCm)
sim = Simulator(backend="numpy")  # CPU baseline

Installation for GPU support:

# NVIDIA GPU (CUDA 12)
pip install radiosim[gpu-cuda]

# AMD GPU (ROCm)
pip install radiosim[gpu-rocm]

# Apple Silicon (Metal) - auto-detected
pip install radiosim[gpu]

# Google TPU
pip install radiosim[tpu]

High-Level Simulator API

The new Simulator class provides a clean, notebook-friendly interface:

from radiosim import Simulator

# Create simulator with sensible defaults
sim = Simulator.from_config("config.yaml")
sim.setup()

# Run simulation
results = sim.run(progress=True)

# Save results
sim.save("output.h5")

Jones Matrix Framework

Complete polarization support with 8 Jones terms:

from radiosim.core.jones import (
    GeometricDelayJones,    # K - Geometric phase delay
    BeamJones,              # E - Primary beam (direction-dependent)
    IonosphereJones,        # Z - Ionospheric effects
    TroposphereJones,       # T - Tropospheric effects
    ParallacticJones,       # P - Parallactic angle rotation
    GainJones,              # G - Electronic gains
    BandpassJones,          # B - Bandpass response
    PolarizationLeakageJones,  # D - Polarization leakage
)

# Create Jones chain
from radiosim.core.jones import JonesChain
jones = JonesChain([
    GeometricDelayJones(),
    BeamJones(beam_type="gaussian"),
    GainJones(amplitude_std=0.01),
])

# Apply to visibility calculation
vis = calculate_visibility(uvw, sky, jones_chain=jones)

Backend Abstraction

Write backend-agnostic code that runs on CPU or GPU:

from radiosim.backends import get_backend

# Get appropriate backend
backend = get_backend("auto")  # Auto-detect GPU

# Use backend operations (works on CPU or GPU)
x = backend.array([1, 2, 3])
y = backend.sin(x)
result = backend.sum(y)

# Check what's available
from radiosim.backends import list_backends
print(list_backends())  # ['numpy', 'jax', 'numba']

Migration Steps

Step 1: Update Imports

Use the migration tool to update import statements:

radiosim-migrate --check src/  # Check what needs updating
radiosim-migrate --apply src/  # Apply changes

Or manually update:

# Old imports
from src.antenna import read_antenna_positions
from src.visibility import calculate_visibility

# New imports
from radiosim.io import read_antenna_positions
from radiosim.core import calculate_visibility

Step 2: Update Configuration Files

Configuration files remain largely compatible, but you can now use Pydantic validation:

from radiosim.io.config import load_config

# Validates and provides helpful error messages
config = load_config("old_config.yaml")

Step 3: Use New API (Optional)

For new code, prefer the high-level Simulator API:

# Old style (still works)
from radiosim.core import (
    read_antenna_positions,
    generate_baselines,
    get_sources,
    calculate_visibility,
)

antennas = read_antenna_positions("antennas.txt")
baselines = generate_baselines(antennas)
sources = get_sources("gleam", flux_limit=1.0)
vis = calculate_visibility(baselines, sources, frequencies)

# New style (recommended)
from radiosim import Simulator

sim = Simulator.from_config("config.yaml")
sim.setup()
results = sim.run()

Step 4: Enable GPU Acceleration (Optional)

If you have a GPU, enable acceleration:

# Install GPU support
pip install radiosim[gpu-cuda]  # or gpu-rocm, gpu
from radiosim import Simulator

# GPU-accelerated simulation
sim = Simulator(backend="jax")
results = sim.run()  # 10-50x faster!

Deprecated Features

The following features are deprecated and will be removed in v0.3.0:

Deprecated Replacement
python src/main.py radiosim CLI command
from src.* import from radiosim.* import
file_format parameter format_type parameter

Getting Help

Version Compatibility

RadioSim Version Python NumPy Astropy
0.1.x 3.11 >=1.24 >=5.0
0.2.x 3.11-3.12 >=1.24 >=5.0

Changelog Summary

v0.2.0 (2025-12-15)

Added:

  • Proper Python package structure (pip install radiosim)
  • GPU support via JAX and Numba backends
  • High-level Simulator API class
  • Jones matrix framework (8 terms)
  • Pydantic configuration validation
  • Backend abstraction layer
  • radiosim and radiosim-migrate CLI commands
  • Comprehensive test suite (376 tests)

Changed:

  • Module structure reorganized into subpackages
  • Import paths changed (src.* -> radiosim.*)
  • file_format parameter renamed to format_type

Fixed:

  • Numerous bug fixes and performance improvements