Simulation Sessions
Version: 1.1.0
Simulation Sessions extend the Orbital Sim with stateful, multi-satellite simulation. Unlike the stateless propagation endpoints, sessions persist constellation state in KV and let you advance time step-by-step, track subsystem health, model inter-satellite link quality, and inject faults.
Sessions are designed for integration testing of constellation workloads. They power the agent executor’s simulated satellite mode and the CAE constellation planner’s test harness.
Base URL
https://sim.rotastellar.com
Concepts
Session Lifecycle
A session represents a constellation of up to 50 satellites. On creation, each satellite is initialized with orbital elements and default subsystem state. You advance the simulation by calling the tick endpoint, which propagates orbits, updates subsystems, checks for natural faults, and recalculates ISL links.
Sessions are stored in the SIM_STATE KV binding with a 1-hour TTL. If a session is not ticked within one hour, it is automatically evicted.
Subsystem State
Every satellite in a session tracks five subsystems:
| Subsystem | Unit | Initial Value | Model |
|---|
battery | % | 100 | Charge in sunlight, discharge in eclipse. Rate depends on compute load. |
solar_power | W | 100 (sunlit) / 0 (eclipse) | Binary based on eclipse state. |
temperature | C | 20 | Rises under compute load, radiative cooling in eclipse. |
memory | MB | 0 (of 512) | Accumulates with data generation, freed on downlink. |
cpu | % | 0 | Set by active workload. Idle satellites report 0%. |
ISL Link Quality
Inter-satellite links (ISLs) are modeled between all satellite pairs within range:
| Parameter | Value |
|---|
| Max range | 5,000 km |
| Distance factor | 1 - (distance / 5000) * 0.6 |
| Eclipse penalty | 0.9 (applied when either endpoint is in eclipse) |
| Effective bandwidth | 100 Mbps * quality |
Natural Fault Detection
Each tick evaluates three natural fault conditions:
| Fault | Condition | Probability |
|---|
| SAA radiation upset | Satellite passes through the South Atlantic Anomaly region | 2% per tick in region |
| Thermal exceedance | Temperature exceeds 50C | Deterministic |
| Power critical | Battery drops below 5% | Deterministic |
faults array entry.
Endpoints
Create Session
Creates a new simulation session with the specified satellites.
Request body:
| Field | Type | Required | Description |
|---|
satellites | array | yes | Array of satellite definitions (max 50) |
satellites[].id | string | yes | Unique satellite identifier within the session |
satellites[].elements | object | yes | Orbital elements (same schema as /v1/state) |
curl -X POST https://sim.rotastellar.com/v1/sessions \
-H "Content-Type: application/json" \
-d '{
"satellites": [
{
"id": "sat-1",
"elements": {
"altitude_km": 550,
"inclination_deg": 53,
"raan_deg": 0,
"mean_anomaly_deg": 0
}
},
{
"id": "sat-2",
"elements": {
"altitude_km": 550,
"inclination_deg": 53,
"raan_deg": 0,
"mean_anomaly_deg": 120
}
},
{
"id": "sat-3",
"elements": {
"altitude_km": 550,
"inclination_deg": 53,
"raan_deg": 0,
"mean_anomaly_deg": 240
}
}
]
}'
{
"session_id": "ses-a1b2c3d4",
"satellite_count": 3,
"created_at": "2026-03-10T12:00:00Z",
"ttl_seconds": 3600
}
Sessions are limited to 50 satellites. Requests exceeding this limit return a 400 error.
Get Session State
Returns the full constellation state including all satellite positions, subsystems, and active ISL links.
Response (200):
{
"session_id": "ses-a1b2c3d4",
"tick": 5,
"sim_time": "2026-03-10T12:25:00Z",
"satellites": [
{
"id": "sat-1",
"position": {
"lat": 42.15,
"lon": -73.82,
"altitude_km": 550.3
},
"in_eclipse": false,
"subsystems": {
"battery": 94.2,
"solar_power": 100,
"temperature": 22.5,
"memory": 45.0,
"cpu": 30
}
}
],
"isl_links": [
{
"from": "sat-1",
"to": "sat-2",
"distance_km": 1823.4,
"quality": 0.78,
"bandwidth_mbps": 78.0,
"eclipse_penalty_applied": false
}
]
}
Tick (Advance Simulation)
POST /v1/sessions/:id/tick
- Propagate all satellite orbits forward
- Detect eclipse transitions (sunlit/shadow)
- Update subsystem state (battery, thermal, solar)
- Check natural fault conditions
- Recalculate all ISL links
Request body:
| Field | Type | Required | Default | Description |
|---|
duration_s | number | no | 300 | Time step duration in seconds |
curl -X POST https://sim.rotastellar.com/v1/sessions/ses-a1b2c3d4/tick \
-H "Content-Type: application/json" \
-d '{
"duration_s": 300
}'
{
"session_id": "ses-a1b2c3d4",
"tick": 6,
"sim_time": "2026-03-10T12:30:00Z",
"duration_s": 300,
"satellites": [ ... ],
"isl_links": [ ... ],
"eclipse_transitions": [
{
"satellite_id": "sat-2",
"transition": "entered_eclipse",
"sim_time": "2026-03-10T12:27:14Z"
}
],
"faults": []
}
The eclipse_transitions array only contains satellites whose eclipse state changed during this tick. An empty array means no transitions occurred.
Inject Fault
POST /v1/sessions/:id/fault
| Field | Type | Required | Description |
|---|
satellite_id | string | yes | Target satellite |
fault_type | string | yes | One of the fault types below |
| Fault Type | Immediate Effect |
|---|
power_loss | Battery set to 0%, solar power disabled |
thermal_exceedance | Temperature set to 85C |
radiation_upset | CPU reset to 0%, memory corrupted (set to 0) |
comms_failure | All ISL links to/from this satellite removed |
isl_degradation | All ISL links to/from this satellite quality halved |
curl -X POST https://sim.rotastellar.com/v1/sessions/ses-a1b2c3d4/fault \
-H "Content-Type: application/json" \
-d '{
"satellite_id": "sat-2",
"fault_type": "power_loss"
}'
{
"session_id": "ses-a1b2c3d4",
"satellite_id": "sat-2",
"fault_type": "power_loss",
"applied_at_tick": 6,
"effects": {
"battery": 0,
"solar_power": 0
}
}
Fault injection is irreversible within a session. To restore a satellite, create a new session.
Storage
Sessions are stored in the SIM_STATE KV binding. Each session is a single JSON document keyed by session:{session_id}. The 1-hour TTL ensures stale sessions are automatically cleaned up.
| KV Binding | Key Pattern | TTL |
|---|
SIM_STATE | session:{session_id} | 3600s (1 hour) |
