# ThermoCast — full agent documentation

> Long-form companion to /llms.txt. This file is intended to be ingested in a
> single fetch by an LLM agent that needs working knowledge of the ThermoCast
> service without crawling the site.

Operated by Trillium Technologies (https://trillium.tech).
Source: https://github.com/Trillium-Technologies/thermocast-api
Canonical site: https://thermocast.spaceml.org/
OpenAPI spec: https://thermocast.spaceml.org/api/openapi.json

## What ThermoCast is

ThermoCast is a public HTTP service that serves machine-learned predictions of
**neutral thermospheric mass density** (kg/m³) at altitudes between 250 km and
600 km. This is the regime occupied by most low-Earth-orbit (LEO) satellites,
including the International Space Station, most Earth-observation
constellations, and the bulk of commercial smallsat traffic. The service is
designed for satellite-drag, orbit-determination, re-entry prediction, and
space-weather workflows.

The underlying model (`thermocast.density_models.NowcastingModel`) is a
feed-forward neural network conditioned on:

- Geomagnetic activity indices (Kp, Dst)
- Solar radio flux (F10.7)
- Time-of-day and day-of-year (encoded as sin/cos pairs)
- Longitude (encoded as sin/cos)
- Altitude

It returns a point estimate of log-density which the API converts to mass
density in kg/m³ before serving.

### What it is not

- **Not** a number-density service. Outputs are mass density.
- **Not** an uncertainty-quantified forecast. The current model returns point
  predictions only; there are no per-prediction error bars.
- **Not** a general-atmosphere model. Below 250 km and above 600 km the model
  is out of distribution and queries are rejected.
- **Not** a real-time geomagnetic-driver source. The Kp/Dst/F10.7 values come
  from a pre-loaded driver table; consult the driver source for live values.

## When to call ThermoCast

Use ThermoCast when a workflow needs:

- Density along a satellite trajectory (sample `/api/density` per ephemeris
  point, or — much better — sample `/api/surface/all` once and interpolate
  client-side).
- Density fields for visualisation or atmospheric-drag calculations at LEO.
- A reproducible model-versioned density source (the API exposes
  `X-Model-Version` and `X-Model-Train-Date` headers on every response).

Do **not** call ThermoCast for:

- Altitudes outside 250–600 km.
- Datetimes outside the range reported by `GET /api/about`.
- Cases where you need uncertainty bounds.
- High-cadence point queries; batch endpoints are dramatically more efficient.

## Endpoint reference

All endpoints are mounted under `/api`. All forecast endpoints accept an
optional ISO-8601 `date_time` query parameter; if omitted, a fixed default
date is used.

### `GET /api/surface`

Density map at a single altitude.

Query parameters:
- `altitude` (required): one of 250, 300, 350, 400, 450, 500, 550, 600 (km).
- `date_time` (optional): ISO-8601 timestamp.

Response:
```json
{
  "density":  [[...], ...],   // 100x100 grid of kg/m^3
  "latitude": [...],          // length 10000, flattened row-major
  "longitude": [...]          // length 10000, flattened row-major
}
```

### `GET /api/surface/all`

Density maps at every supported altitude in one call. **Prefer this over
calling `/api/surface` eight times** — the model evaluates all altitudes in a
single forward pass.

Response:
```json
{
  "densities": { "250": [[...]], "300": [[...]], ..., "600": [[...]] },
  "altitudes": [250, 300, 350, 400, 450, 500, 550, 600],
  "latitude":  [...],
  "longitude": [...]
}
```

### `GET /api/altitude`

Vertical density profile at one location.

Query parameters:
- `latitude` (required): degrees, -90..90.
- `longitude` (required): degrees, -180..180.
- `date_time` (optional): ISO-8601 timestamp.

Response:
```json
{
  "density":  [...],   // length 8, kg/m^3
  "altitude": [250, 300, 350, 400, 450, 500, 550, 600]
}
```

### `GET /api/density`

Single-point prediction. Use only for one-off lookups; prefer batch endpoints
when you need more than one point.

Query parameters: `latitude`, `longitude`, `altitude`, `date_time`.

Response:
```json
{
  "density": 1.23e-12,
  "altitude": 375,
  "latitude": 45.0,
  "longitude": -120.0,
  "date_time": "2024-01-15 12:00:00"
}
```

### `GET /api/geomag`

Hourly Kp, Dst, and F10.7 indices used as model drivers. If `date_time` is
omitted, returns the latest record; otherwise returns the nearest hour.

Response:
```json
{
  "datetime": "2024-01-15T12:00:00",
  "kp":   3.0,
  "dst": -12.0,
  "f107": 145.2
}
```

### `GET /api/about`

Loaded-model metadata and the valid datetime range. Call this **before** a
forecast endpoint if you are uncertain whether your timestamp is in range.

Response:
```json
{
  "model": {
    "display_name": "thermocast nowcasting",
    "model_file":   "thermocast/models/karman_model_log_exp_residual_best_78.torch",
    "train_date":   "2024-09-30",
    "version":      "v0.1",
    "altitude_range_km": [250, 600]
  },
  "datetime_range": {
    "first": "...",
    "last":  "..."
  }
}
```

## Response headers (every endpoint)

- `X-Model-Version` — semantic version of the loaded model.
- `X-Model-Train-Date` — ISO date the model was trained.
- `X-Model-File` — basename of the underlying weights file.
- `X-Thermocast-Version` — version of the upstream thermocast Python package.
- `Cache-Control` — set on forecast endpoints to mirror the server-side cache
  TTL (120 s for forecast routes, 300 s for `/geomag`).

CORS is open (`Access-Control-Allow-Origin: *`) and the four `X-Model-*` /
`X-Thermocast-*` headers are listed in `Access-Control-Expose-Headers` so
browser clients can read them.

## Conventions

- **Units.** Density is mass density in kg/m³ (not number density, not
  log-density). Altitude is kilometres. Latitude and longitude are degrees.
  Timestamps are UTC.
- **Grid layout.** The lat/lon grid is 100×100 with cell-centre spacing of
  1.8° latitude × 3.6° longitude. Returned `latitude` and `longitude` arrays
  are flattened in row-major order (longitude varies fastest) and align
  element-wise with the flattened density grid.
- **Caching.** Forecast endpoints are cached server-side for 120 s and
  `/geomag` for 300 s. The cache key includes altitude, datetime (truncated to
  seconds), and the model file name, so model upgrades invalidate cleanly.
- **Default datetime.** Forecast endpoints default to a fixed past date when
  `date_time` is omitted. Do not rely on this default in production code; pass
  an explicit timestamp.

## Worked examples

Density surface at 300 km for a specific datetime:

```bash
curl "https://thermocast.spaceml.org/api/surface?altitude=300&date_time=2024-01-15T12:00:00"
```

Density profile across all altitudes for one location:

```bash
curl "https://thermocast.spaceml.org/api/altitude?latitude=45.0&longitude=-120.0&date_time=2024-01-15T12:00:00"
```

Single-point density:

```bash
curl "https://thermocast.spaceml.org/api/density?latitude=45.0&longitude=-120.0&altitude=375&date_time=2024-01-15T12:00:00"
```

Geomagnetic indices at a specific hour:

```bash
curl "https://thermocast.spaceml.org/api/geomag?date_time=2024-01-15T12:00:00"
```

Pinning the model from a response:

```bash
curl -sI "https://thermocast.spaceml.org/api/about" \
  | grep -i '^x-model-\|^x-thermocast-'
```

## Glossary

- **Thermosphere.** The atmospheric region from roughly 80 km to 600+ km
  altitude; density there governs satellite drag.
- **Mass density.** Mass per unit volume (kg/m³).
- **Kp.** Planetary geomagnetic-activity index, 0..9 (quasi-logarithmic).
- **Dst.** Disturbance storm-time index (nT); negative during geomagnetic storms.
- **F10.7.** Solar radio flux at 10.7 cm wavelength (sfu); proxy for solar UV
  heating of the thermosphere.
- **LEO.** Low Earth Orbit, conventionally below 2000 km altitude.
- **Nowcasting.** Predicting the present (or very recent past) state from
  contemporaneous driver inputs, as distinct from a multi-hour forecast.