Simulations and scenarios

The assistant can change the world it is analyzing. It injects synthetic satellites and ground stations, knocks gateways offline, applies deterministic rain, and saves the whole configuration as a named scenario that reproduces the same numbers later. Every mutation runs through the same deterministic engines as every other answer: nothing is estimated, and everything synthetic is labeled as such.

This page covers the agent-driven side of scenarios. For the console UI around simulations, see Simulations and scenarios in the console.

Synthetic satellites and Walker constellations

create_orbit_scenario synthesizes temporary, clearly labeled SYNTHETIC satellites from a mission request, propagates them deterministically with SGP4 over a window, and scores coverage against the ground station network. It answers requests like "create a satellite", "what coverage would a 700 km SSO have over 12 hours", or "add three SAR satellites in staggered planes".

The tool never refuses for missing parameters. Unstated values get nominal defaults, and every choice is stated as an assumption in the answer:

Parameter	Default
orbit_type	sso (custom accepts an explicit inclination)
altitude_km	700
window_hours	12
step_seconds	60
min_elevation_deg	10
count	1 (maximum 48)
planes	1
phasing	walker (or even)
raan_spread_deg	360
walker_f	1

For an SSO the inclination is auto-derived from the sun-synchronous condition (about 98.2 degrees at 700 km); the answer reports the derived inclination and mean motion.

Walker geometry

Multi-satellite requests use the same tool with count and planes. Planes are spaced evenly in RAAN across raan_spread_deg, satellites evenly in mean anomaly within each plane, and adjacent planes carry the Walker inter-plane phase offset walker_f * 360 / count. The result adds a constellation block: per-plane RAANs (planeRaansDeg), the applied phase offset (interPlanePhaseDeg), per-satellite coverage, the single-satellite baseline, and coverageDeltaPercent, so the answer can state exactly what the extra satellites bought.

Coverage is combined: a sample counts as covered when any satellite sees any station above the elevation mask. Pass region ("Europe", "Germany") to score against just that region's stations.

First-class synthetic assets

Synthesized satellites are injected through the same pipeline uploaded TLEs use. They appear on the globe, are click-selectable, have detail panels, ground tracks, and fronthaul links, and participate in analytics, coverage, beam, and availability engines exactly like real assets. The only difference is provenance: source synthetic plus a SYNTHETIC label, which the assistant always discloses along with the fact that results are separate from live telemetry.

Synthetic ground stations

create_ground_station_scenario places a temporary SYNTHETIC ground station at a lat/lon and evaluates it against the currently enabled fleet. Coordinates are required; when the operator names a place instead ("Iceland", "Nairobi"), the agent picks representative coordinates itself and states them as an assumption rather than refusing.

Every satellite with usable orbital elements is SGP4-propagated over the window (defaults: 12 h, 60 s step, 10 degree mask). The result reports:

• Contact percent: the share of the window with at least one satellite in view above the mask.
• Total contact minutes and per-satellite passes with max elevation.
• The longest idle gap.
• satellitesEvaluated versus satellitesExcluded with the exclusion rule. Satellites with no propagable TLE are excluded and counted, never fabricated.
• The exact calculation.

The station is a first-class synthetic asset with globe presence, a detail panel, and Ka fronthaul access links. An optional count_antennas is recorded as an assumption but does not change geometric visibility, and the tool says so.

Gateway outage what-ifs

simulate_gateway_outage deterministically models a gateway outage and how fronthaul traffic redistributes. The what-if pipeline is fixed:

1. set_timeline_mode("replay") loads the fleet and its fronthaul links.
2. simulate_gateway_outage selects gateways by country ("Germany"), region code ("DE", "US"), or explicit node ids, with mode either disable (flag offline) or remove (drop entirely). Fronthaul access links are geometrically re-derived over the surviving fleet, and every affected satellite is reported as either re-homed to a surviving gateway or orphaned with no coverage, with before and after fleet statistics.
3. The regular read tools (query_fleet_statistics, query_fleet_breakdown, query_fleet_trend) now compute under the scenario automatically, so the redistributed numbers come from the same deterministic statistics engines.
4. reset_scenario restores the baseline when the operator is done. list_scenario shows which mutations are currently active.

Two honesty rules apply without exception:

• Zero matches end the analysis. If no gateway matches the request (say, "Germany" when the fleet has no German gateway), the result says so and the assistant reports it plainly. It never invents a hypothetical gateway or made-up traffic figures.
• Scenario results are modeled. Fronthaul links are geometrically re-derived and may differ from the replayed store links, and the globe is not re-rendered under the mutation. The answer says "modeled under scenario, globe unchanged".

Deterministic weather

The coverage and siting tools (create_orbit_scenario, create_ground_station_scenario, optimize_ground_network, compare_candidate_sites) accept optional rain:

• rain_rate_mm_hr applies a uniform rain rate.
• rain_regions describes localized weather as lat/lon boxes each carrying a rain rate. Stations outside every box see 0 mm/h; overlapping boxes take the maximum rate.

For a request like "simulate heavy rain over the UK", the agent constructs a rain region with representative bounds and a representative rate, and states both as assumptions. Representative rates: moderate around 10 mm/h, heavy around 25 mm/h, severe or tropical around 50 mm/h.

Under weather, a sample only counts as covered or in contact when the Ka fronthaul link budget also closes under modeled rain attenuation (a P.618 approximation) at that sample's elevation. Low-elevation contacts are lost first, which matches physical intuition: longer atmospheric path, more rain loss.

Weather answers always report both figures: clear-sky versus weather-degraded coverage or contact, plus samplesLostToWeather from the result. The optimizer additionally reports finalAvailabilityClearSkyPercent versus finalAccessAvailabilityPercent, so picks made under rain show which gateways need proactive rerouting. The model is always named for what it is: modeled rain attenuation, never measured weather. There is no random weather. The rain field is exactly what was requested, and identical inputs reproduce identical results.

Saved scenarios and reproducibility

Mission sandboxes are worth keeping. Three tools make them durable and reproducible:

• save_scenario persists the current sandbox under a name: the exact synthetic injection payloads (TLE text and station table content), the active what-if mutations, the current sim epoch, and the last-used evaluation config (window, step, elevation mask, weather). Saving an existing name overwrites that scenario.
• load_scenario restores by name or id: it removes the scene's current synthetic assets, resets the active what-if scenario, re-injects the saved payloads through the same import path, and re-applies the saved mutations. After a load, the assistant states what was restored, tells the operator to seek the timeline to the saved epoch (epochIso, via seek_time), and notes that re-running the saved evaluations there reproduces the identical numbers. Unknown names come back with the list of available scenarios, never a guess.
• list_scenarios enumerates saved scenarios with name, id, save time, saved epoch, and asset and mutation counts, for when the operator refers to a design loosely ("yesterday's design").

Reproducibility falls out of determinism: the engines have no randomness and no wall-clock dependence, so a saved scenario plus its saved epoch and evaluation config is a complete recipe for the original numbers. This is what makes two-design comparisons and regulatory evidence trustworthy: anyone can reload the scenario and get the same result. See the worked comparison in Examples.

Where to go next

• Tools reference: full parameter and result detail for every scenario tool.
• Visualization choreography: how synthetic assets fade in and scenario results play on the globe.
• Examples: worked scenarios including Walker synthesis, outage what-ifs, and rain-degraded coverage.