Metadata-Version: 2.4
Name: orbitplan
Version: 0.1.0
Summary: Feasibility planner for inference in orbit: reconcile power, thermal and downlink, and find the binding constraint.
Author-email: captainawesome78 <mailmenaveed88@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/captainawesome78/orbitplan
Project-URL: Repository, https://github.com/captainawesome78/orbitplan
Project-URL: Issues, https://github.com/captainawesome78/orbitplan/issues
Keywords: orbital,inference,edge-ai,satellite,downlink,power-budget,thermal,space-datacenter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: thermal
Requires-Dist: orbitherm>=0.1.0; extra == "thermal"
Dynamic: license-file

# orbitplan

**Feasibility planner for inference in orbit — find the constraint that's actually stopping you.**

Three things decide whether a model can run in space, and they fight each other:
the array has to make the power, the radiator has to shed the heat that power
becomes, and the ground link has to carry whatever data survives. Optimising one
in isolation is how orbital compute plans die. `orbitplan` reconciles all three
against a real sensor or serving load and names the binding constraint.

Part of a set:

- [`orbitherm`](https://github.com/captainawesome78/orbitherm) — sizes the radiator (used automatically when installed)
- [`radshield`](https://github.com/captainawesome78/radshield) — keeps the model correct under radiation-induced bit flips

## Install

```bash
pip install orbitplan            # core
pip install orbitplan[thermal]   # + orbitherm for the full thermal model
```

## Quick start

```python
import orbitplan as op

plan = op.MissionPlan(
    sensor=op.Sensor(burst_gb_per_s=10, duty_cycle=0.002),      # SAR instrument
    workload=op.Workload.preset("sar_segmenter", input_mb=800, output_mb=2),
    accelerator=op.Accelerator.preset("jetson_agx_orin"),
    power=op.PowerBudget(array_area_m2=8),
    thermal=op.ThermalBudget(radiator_area_m2=2),
    link=op.LinkBudget(band="x_band"),
)

r = plan.evaluate()
print(r.bottleneck)     # -> 'none'
print(r.summary())
```

Drop the onboard inference (`output_mb=800`) and the same satellite becomes
downlink-bound: 1,728 GB/day of raw data against 72 GB/day of X-band capacity.
That gap is the entire business case for processing in orbit.

## What it models

**Power** — solar array output derated for cell efficiency, packing, eclipse
fraction, battery round-trip and PMAD losses, minus bus overhead.

**Thermal** — the heat-rejection ceiling on sustained compute. Delegates to
`orbitherm` when installed; falls back to a bare Stefan-Boltzmann estimate
otherwise.

**Downlink** — contact time × rate × passes, derated for protocol overhead, versus
the data actually produced. Anything the payload can't process has to go down raw.

**Workload** — energy and latency per inference from real accelerator
efficiency (peak TOPS derated by an achievable-utilisation factor, which is
where most naive estimates go wrong).

## Verdicts

`evaluate()` returns a `PlanResult` whose `bottleneck` is one of:

| value | meaning |
|---|---|
| `power` | the array can't sustain the processing load |
| `thermal` | the radiator can't shed the heat that load produces |
| `downlink` | compute keeps up, but the results still don't fit the link |
| `none` | all three close, with margin |

Every result carries the numbers behind the call — margins, watts required
versus available, GB/day generated versus downlinked — so you can see *how far*
off you are, not just that you failed.

## Presets

Accelerators: `jetson_orin_nx`, `jetson_agx_orin`, `nvidia_l4`, `nvidia_h100`.
Workloads: `resnet50`, `vit_b16`, `yolov8m`, `sar_segmenter`, `llm_1b_token`.
Bands: `s_band`, `x_band`, `ka_band`, `optical`. All overridable.

## Scope

First-order feasibility triage — for architecture trade studies, go/no-go calls
and sanity-checking orbital compute claims. Not a substitute for detailed
mission design: it assumes circular LEO, worst-case (β=0) eclipse geometry, an
isothermal radiator, and steady-state operation.

## License

Apache-2.0
