Initial commit

yksa_orbital/README.md

@@ -0,0 +1,86 @@
+# yksa_orbital
+
+Propagation for Django services: a backend registry, and the client to the
+Orekit sidecar.
+
+```python
+from yksa_orbital import get_backend
+
+state = get_backend().state_at(omm, at)
+weather = get_backend("orekit").space_weather(start, stop)
+```
+
+## Why it is its own app
+
+ODMS and `track.tmtc.yksa.space` both propagate, both against the same sidecar.
+The alternative to sharing this is two HTTP clients that drift apart on timeouts,
+on 503 handling, and on what they put in a request — and since the sidecar's
+whole purpose is that two services fly the *same* model, two clients that send
+different things quietly defeat it.
+
+## Install
+
+Add `"yksa_orbital"` to `INSTALLED_APPS` and set:
+
+```
+ORBITAL_PROPAGATOR_BACKEND=sgp4        # or "orekit"
+OREKIT_SERVICE_URL=http://orekit:5000
+```
+
+It depends on `odm` and on `httpx`. Nothing else — in particular, nothing
+from the host service.
+
+## Backends
+
+| Name | What it can do |
+|---|---|
+| `sgp4` | Pure Python. TEME plus a GMST Earth-fixed frame. Analytical theory only: **no drag integration**, so it refuses decay, drag fitting and space weather rather than returning a number nobody should trust. |
+| `orekit` | HTTP client to the Orekit sidecar (`tle/services/orekit`). Rigorous frames, numerical and semi-analytical propagation, TLE fitting, drag fitting, decay forecasts, solar-activity ensembles, space weather. |
+
+### Name the backend when you need the sidecar
+
+`get_backend()` returns the deployment's default, which is `sgp4`. Anything
+needing physics `sgp4` does not have must ask for `"orekit"` explicitly.
+
+This is not hypothetical. A view that forgot to, and swallowed the resulting
+`PropagationError`, rendered an empty space-weather chart for weeks with nothing
+logging a complaint. If your call needs the sidecar, say so.
+
+## Capacity
+
+The sidecar keeps a worker free for the interactive queries a page load waits on,
+and turns heavy work away rather than queueing it. A 503 arrives here as
+`BackendBusy` — a subclass of `PropagationError`, so existing handlers still
+work, but a Celery task should catch it **first** and retry. Nothing about the
+request needs to change for it to succeed later; recording it as a failed
+forecast is wrong.
+
+## The model config
+
+`yksa_orbital.model_config` reads the sidecar's `GET /config` — the force model,
+propagator, decay altitude, drag-fit thresholds and weather sources it is
+actually flying — with a cache and a vendored fallback.
+
+Use it for values a page genuinely needs locally: the ensemble's display floor,
+the decay altitude in a caption. Do **not** use it to build a request. Omitting a
+parameter already gets the sidecar's value; echoing it back only adds a way for
+the two to disagree.
+
+```python
+from yksa_orbital.model_config import model_config, setting
+
+floor_km = setting("ensemble", "display_floor_km", 150.0)
+```
+
+`setting()` applies this deployment's `DECAY_*` override when there is one, so a
+caption describes the run on screen rather than the model in general.
+
+## Layout
+
+| File | What |
+|---|---|
+| `registry.py` | `get_backend()`, and `register()` for a service with its own propagator. |
+| `backends/sgp4.py` | The pure-Python backend. |
+| `backends/orekit.py` | The sidecar HTTP client. |
+| `wire.py` | Stored OMM dict → the CCSDS message the sidecar consumes. The only place that conversion happens. |
+| `model_config.py` | Cached access to the sidecar's model definition. |