Resilience

POST/resilience/kfailure

POST/resilience/montecarlo

Purpose

POST /resilience/kfailure answers a deterministic question: how many satellites can fail before the fleet stops meeting its minimum, and which combination is the first to break it.

POST /resilience/montecarlo answers a probabilistic one: given a failure rate and a mission horizon, what fraction of the time does the fleet meet its requirement.

These endpoints do not take a constellation_id

Unlike almost every other analysis endpoint, these take the shape of the fleet rather than a registered constellation. There is no constellation_id field, and supplying one is silently ignored while the required shape fields fail with a 422:


Failed to deserialize the JSON body into the target type: missing field `planes` at line 1 column 33

That is deliberate. Resilience here is a combinatorial property of the fleet structure, not of any particular orbit, so it needs no propagation and no registered constellation.

POST /resilience/kfailure

Parameter	Type	Unit	Default	Required	Description
`planes`	integer	count	—	Yes	Number of orbital planes.
`satellites_per_plane`	integer	count	—	Yes	Satellites per plane. Note: spelled out in full here, unlike `sats_per_plane` on the constellation endpoint.
`min_operational_per_plane`	integer	count	—	Yes	Minimum satellites that must remain working in every plane.
`max_k`	integer	count	`2`	No	Largest failure count to search exhaustively.

The field is satellites_per_plane here and sats_per_plane on /constellations/walker. Both are required, so a mix-up fails loudly, but it is a genuine inconsistency in the API surface worth knowing about.

Example

A 6-by-10 fleet that must keep at least 8 satellites in every plane:


curl -s -X POST http://127.0.0.1:8080/resilience/kfailure \
  -H 'content-type: application/json' \
  -d '{
        "planes": 6,
        "satellites_per_plane": 10,
        "min_operational_per_plane": 8,
        "max_k": 3
      }'


{ "k_max": 2, "critical_set": [0, 1, 2], "exhaustive": true }

Reading the result

Field	Value	Meaning
`k_max`	2	The fleet tolerates any 2 failures; some combination of 3 breaks it
`critical_set`	`[0, 1, 2]`	Indices of a failure combination that violates the requirement
`exhaustive`	`true`	Every combination up to `max_k` was checked, so `k_max` is exact

The answer is the obvious one once stated: each plane holds 10 and must keep 8, so it tolerates 2 losses. Three failures concentrated in one plane breaks it, and critical_set names such a combination.

k_max is a worst-case figure. It says nothing about the far more likely case of three failures spread across three different planes, which this fleet survives comfortably.

That distinction is exactly why /resilience/montecarlo exists: worst case is what k-failure measures, and expected case is what operations experience.

exhaustive: true matters. It confirms the search covered every combination up to max_k rather than sampling, so k_max is proven rather than estimated. Raising max_k grows the combination count sharply.

POST /resilience/montecarlo

Simulates failures over a mission horizon and reports the fraction of time the fleet meets its requirement.

It takes the same fleet-shape fields plus reliability and horizon parameters, including horizon_years. As with k-failure, the required fields fail loudly when absent:


Failed to deserialize the JSON body into the target type: missing field `horizon_years` at line 1 column 118

Model basis: k-failure tolerance and Monte Carlo availability

Assumptions: Uniform Walker fleet with identical planes; a plane is satisfied when at least the minimum number of its satellites are operational; k-failure searches combinations exhaustively up to the stated bound; the Monte Carlo path samples independent failures against the supplied reliability over the horizon.
Validity range: Uniform fleets. A heterogeneous constellation, or one where planes serve different roles, is not represented by a single minimum-per-plane figure.
Accuracy: k-failure is exact within its search bound when `exhaustive` is true. Monte Carlo results carry sampling error that falls with trial count, and both depend entirely on the assumed failure model, which no simulation can validate.
Reference: Standard combinatorial N-k analysis and Monte Carlo availability simulation.