Metadata-Version: 2.4
Name: space-ml-sim
Version: 0.5.0
Summary: Simulation framework for AI inference on orbital satellite constellations
Author: space-ml-sim contributors
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
Keywords: AI,fault-tolerance,radiation,satellite,simulation,space
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: plotly>=5.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: sgp4>=2.22
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: pip-audit>=2.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: onnx
Requires-Dist: onnx>=1.14; extra == 'onnx'
Requires-Dist: onnxruntime>=1.16; extra == 'onnx'
Provides-Extra: poliastro
Requires-Dist: astropy>=5.0; extra == 'poliastro'
Requires-Dist: poliastro>=0.17; extra == 'poliastro'
Description-Content-Type: text/markdown

# space-ml-sim

**Simulate AI inference on orbital satellite constellations under realistic space radiation.**

SpaceX is building TERAFAB with 200 TOPS rad-hardened chips for AI Sat Mini. Cloud-grade TPUs are being tested for on-orbit inference. But what happens to a ResNet or a transformer when a galactic cosmic ray flips a bit in a weight tensor 550 km above Earth?

`space-ml-sim` answers that question.

---

## Features

**Orbital mechanics** -- Walker-Delta and sun-synchronous constellation generation, Keplerian propagation with J2 secular perturbations, eclipse detection, real TLE ingestion via SGP4

**Radiation environment** -- Parametric SEU and TID models for LEO (500 km to 2000 km), SAA enhancement, shielding attenuation, altitude/inclination-dependent rates

**ML fault injection** -- Flip bits in PyTorch model weights and activations using radiation-derived Poisson rates. Sweep fault counts and measure accuracy degradation. Transformer-aware targeting for attention, LayerNorm, and embedding layers

**Fault tolerance** -- Full TMR, selective TMR (per-layer vulnerability ranking), and checkpoint rollback with majority voting and anomaly detection

**Radiation timeline** -- Generate time-series radiation exposure from real TLEs with SAA crossing detection and visualization

**Quantization comparison** -- Compare FP32/FP16/INT8 fault resilience curves for the same model in one call

**Sensitivity heatmap** -- Visual per-layer vulnerability ranking showing which layers need protection

**ONNX import** -- Load `.onnx` models for fault injection without writing PyTorch code (`pip install space-ml-sim[onnx]`)

**Mission budget** -- Deterministic SEU/TID projections over mission lifetime with shielding recommendations

**Monte Carlo reliability** -- Statistical mission survival estimation with confidence intervals (`pip install space-ml-sim`)

**Ground track visualization** -- World map with satellite ground track, radiation color overlay, and SAA boundary

**poliastro import** -- Convert poliastro Orbit objects to space-ml-sim (`pip install space-ml-sim[poliastro]`)

**Hardware profiles** -- TERAFAB D3, Trillium TPU v6e, BAE RAD5500, NOEL-V RISC-V, Jetson Orin, Zynq, Versal AI Core

---

## Install

```bash
pip install space-ml-sim
```

From source:

```bash
git clone https://github.com/orbital-sim-project/space-ml-sim.git
cd space-ml-sim
pip install -e ".[dev]"
```

---

## Quickstart

### Fault sweep in 10 lines

```python
import torch, torchvision, copy
from space_ml_sim.compute.fault_injector import FaultInjector
from space_ml_sim.environment.radiation import RadiationEnvironment
from space_ml_sim.models.chip_profiles import TRILLIUM_V6E

model = torchvision.models.resnet18(weights="DEFAULT").eval()
injector = FaultInjector(RadiationEnvironment.leo_500km(), TRILLIUM_V6E)

for n_faults in [0, 10, 50, 100, 500]:
    test = copy.deepcopy(model)
    report = injector.inject_weight_faults(test, num_faults=n_faults)
    out = test(torch.randn(1, 3, 224, 224))
    print(f"{n_faults:>4d} faults -> argmax={out.argmax().item()}, layers_hit={len(report.layers_affected)}")
```

### Build a constellation and simulate

```python
from space_ml_sim.core import Constellation
from space_ml_sim.models.chip_profiles import TERAFAB_D3

constellation = Constellation.walker_delta(
    num_planes=10, sats_per_plane=10,
    altitude_km=550, inclination_deg=53,
    chip_profile=TERAFAB_D3,
)

for _ in range(95):  # ~1 orbit
    metrics = constellation.step(dt_seconds=60.0)

print(f"Active: {metrics['active_count']}, SEUs: {metrics['total_seus']}")
```

### Load real satellites from TLE

```python
from space_ml_sim.core import parse_tle, Constellation
from space_ml_sim.models.chip_profiles import TERAFAB_D3

tle_line1 = "1 25544U 98067A   24045.54783565  .00016717  00000+0  30057-3 0  9993"
tle_line2 = "2 25544  51.6416 247.4627 0006703 130.5360 229.6116 15.49815508441075"

orbit = parse_tle(tle_line1, tle_line2)
print(f"ISS: {orbit.altitude_km:.0f} km, {orbit.inclination_deg:.1f} deg")
```

---

## Examples

```bash
python examples/01_basic_constellation.py    # Propagate 100 sats for 1 orbit
python examples/02_radiation_fault_sweep.py  # Accuracy vs bit flips (all 4 chips)
python examples/03_tmr_comparison.py         # TMR vs unprotected under faults
```

---

## Architecture

```
space_ml_sim/
├── core/                  # Orbital mechanics and satellite state
│   ├── orbit.py           # Keplerian propagation, J2 drift, Walker-Delta, SSO
│   ├── satellite.py       # Satellite with power/thermal/radiation tracking
│   ├── constellation.py   # Bulk operations, ISL link detection
│   ├── tle.py             # TLE parsing and SGP4 propagation
│   └── clock.py           # Simulation time management
├── environment/           # Space environment models
│   ├── radiation.py       # SEU rates, TID accumulation, SAA
│   ├── thermal.py         # Steady-state thermal balance
│   ├── power.py           # Solar/battery power model
│   └── comms.py           # Inter-satellite link latency
├── compute/               # ML inference and fault tolerance
│   ├── fault_injector.py  # Bit-flip injection into PyTorch models
│   ├── transformer_fault.py # Attention/LayerNorm/embedding targeting
│   ├── tmr.py             # Full TMR, selective TMR, checkpoint rollback
│   ├── checkpoint.py      # Model checkpointing for fault recovery
│   └── scheduler.py       # Power/thermal-aware inference scheduling
├── models/                # Hardware profiles
│   ├── chip_profiles.py   # TERAFAB D3, Trillium, RAD5500, NOEL-V
│   └── rad_profiles.py    # Radiation environment presets
├── metrics/               # Reliability and performance tracking
└── viz/                   # Plotly visualization
```

---

## Chip Profiles

| Chip | Node | TDP | INT8 TOPS | TID Tolerance | Notes |
|------|------|-----|-----------|---------------|-------|
| TERAFAB D3 | 2 nm | 300 W | 200 | 100 krad | SpaceX rad-hardened |
| Trillium TPU v6e | 4 nm | 200 W | 450 | 15 krad | COTS with shielding |
| Jetson AGX Orin | 8 nm | 60 W | 275 | 10 krad | Flying on Planet Labs |
| Versal AI Core | 7 nm | 75 W | 130 | 100 krad | Space-grade, 15-year missions |
| Zynq UltraScale+ | 16 nm | 10 W | 0.5 | 30 krad | Xiphos Q8S OBC |
| BAE RAD5500 | 45 nm | 15 W | 0.001 | 1000 krad | Space-grade baseline |
| NOEL-V FT | 28 nm | 5 W | 0.01 | 50 krad | Open RISC-V in orbit |

---

## Quality & Security

Every PR is automatically checked by CI before merge:

| Check | What it does |
|-------|-------------|
| **Tests + Coverage** | 494 tests, 80% minimum coverage enforced |
| **Lint & Format** | `ruff check` + `ruff format` |
| **Security Scan** | `pip-audit` (dependency CVEs) + `bandit` (code security) |
| **License Compliance** | Verifies all dependencies are AGPL-compatible |
| **Performance Benchmarks** | Fault injection, constellation step, and orbit propagation speed gates |
| **Branch Protection** | PRs require passing CI + 1 review before merge |
| **Dependabot** | Weekly automated dependency updates |
| **Pre-commit Hooks** | Local checks: ruff, bandit, secret detection, conventional commits |

```bash
# Run all checks locally
pytest tests/ -v --cov=space_ml_sim --cov-fail-under=80
ruff check src/ tests/ && ruff format --check src/ tests/
bandit -r src/ -c pyproject.toml -ll
```

---

## Roadmap

- [x] **v0.1** -- Keplerian orbits, parametric radiation, fault injection, full TMR
- [x] **v0.2** -- J2 perturbations, selective TMR, transformer faults, TLE/SGP4 ingestion, CI
- [x] **v0.3** -- Radiation timeline with SAA detection, quantization-aware fault comparison, sensitivity heatmap, ONNX model import
- [x] **v0.4** (current) -- SPENVIS validation, Monte Carlo reliability, mission budget calculator, ground track viz, poliastro import
- [ ] **v0.5** -- Distributed inference across constellation, ISL communication delays
- [ ] **v0.6** -- Ground station scheduling, downlink-aware task placement, compliance report export

---

## Contributing

Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, standards, and CLA.

**Focus areas:**
- Distributed inference across ISL links
- Ground station downlink scheduling
- ECSS compliance report export
- More chip profiles and radiation model refinements

For security vulnerabilities, see [SECURITY.md](SECURITY.md).

---

## License

This project is dual-licensed:

- **AGPL-3.0** for open-source use -- see [LICENSE](LICENSE)
- **Commercial license** for proprietary use -- see [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)

If you are building proprietary software or a SaaS product with `space-ml-sim`, you need a commercial license. [Learn more](COMMERCIAL_LICENSE.md).
