`orbitforge design`

Synopsis


orbitforge design --requirements <PATH> [OPTIONS]

Description

Solves the inverse problem. Instead of specifying a constellation and measuring what it achieves, you state what you need and the solver searches for a geometry that delivers it.

It enumerates candidate Walker geometries, propagates each one, verifies it against your requirements, and recommends the best feasible design under the stated objective.

Options

Parameter	Type	Unit	Default	Required	Description
`--requirements`	path	n/a	—	Yes	Path to a design requirements JSON document. See the schema below.
`--output`	path	n/a	—	No	Write the full design report, including every candidate evaluated.
`--constellation`	path	n/a	—	No	Also write the recommended constellation, ready for `simulate`, `coverage`, and `link`.

Requirements schema


{
  "name": "europe-broadband",
  "start": "2026-01-01T00:00:00Z",
  "verification_hours": 6.0,
  "step_seconds": 120.0,
  "stations": [
    {
      "id": "madrid",
      "name": "Madrid",
      "latitude_deg": 40.43,
      "longitude_deg": -3.7,
      "altitude_km": 0.6
    },
    {
      "id": "stockholm",
      "name": "Stockholm",
      "latitude_deg": 59.33,
      "longitude_deg": 18.07,
      "altitude_km": 0.02
    }
  ]
}

Field	Required	Purpose
`name`	Yes	Design name, carried into the output
`start`	No	Verification window start epoch
`verification_hours`	No	Window length over which candidates are checked
`step_seconds`	No	Verification sampling step
`stations`	No	Ground stations that must be served
`link`	No	Link, latency, and continuity requirement
`constraints`	No	Search-space bounds, such as altitude and inclination ranges
`objective`	No	What to optimize, plus tie-breakers

Only name is strictly required; everything else has a default. A request with no stations and no link requirement is under-constrained, and will return a trivially small design.

Worked example


orbitforge design \
  --requirements req.json \
  --output design.json \
  --constellation designed.json


Design 'europe-broadband': Feasible. Recommended: 16 satellites (Star, 4 planes x 4 per plane, 1238 km, 59.0 deg).
  worst-case round-trip latency: 22.3 ms; global min fold: 1; latency margin: inf ms.
  verified 518 candidates across 50 geometries.
Wrote design report -> design.json
Wrote recommended constellation -> designed.json

Reading the result

Figure	Value	Meaning
Verdict	Feasible	At least one candidate met every requirement
Recommendation	16 satellites, Star, 4 by 4	The winning geometry under the objective
Altitude and inclination	1238 km, 59.0 degrees	Chosen by the search, not supplied by you
Worst-case latency	22.3 ms round trip	Across the verification window and all stations
Global min fold	1	The worst-served point saw one satellite; no redundancy
Candidates verified	518 across 50 geometries	Size of the search actually performed

The choices the solver made are informative

Nothing in the request named an altitude, an inclination, or a Walker pattern. The solver picked 1238 km, 59.0 degrees, and a Star pattern, and each choice follows from the two stations at 40 and 59 degrees north:

59.0 degrees inclination is just enough to reach Stockholm at 59.33 degrees. Inclination sets a hard latitude ceiling, so anything lower could never serve that station.
1238 km is far above the 550 km typical of broadband shells. A higher orbit sees more ground per satellite, so fewer satellites are needed, and the objective rewards exactly that.
16 satellites rather than the 60 in the hand-built example, because the requirement is two stations rather than global coverage.

Global min fold of 1 means no redundancy. The worst-served point had exactly one satellite visible, so a single failure creates an outage there.

If the mission needs continuity, state a minimum fold in the requirements. The solver optimizes what you ask for, and it will not add redundancy you did not request.

The latency margin: inf ms line means no latency limit was specified, so everything satisfies it trivially. That is a symptom of an under-constrained request rather than an excellent design.

Constrain the search, or accept its answer

The solver returns the best design under the objective and constraints it was given. A minimal request produces a minimal answer.

To get	State it in
A redundant design	Minimum fold, in the link or continuity requirement
A lower orbit	An altitude ceiling, in `constraints`
A closed link at a frequency	Frequency and availability, in `link`
A latency bound	Maximum round-trip latency, in `link`

The 1238 km recommendation is a good illustration. It is optimal for “fewest satellites”, and it is probably wrong for a real broadband system, where path loss and latency both argue for a lower shell. The solver was never told that.

Model basis: Requirements-driven constellation synthesis

Assumptions: Candidate geometries drawn from Walker Delta and Star families within the constrained search space; each candidate propagated over the verification window at the given step; feasibility judged against the stated station, link, latency, and continuity requirements; ranking by the stated objective with tie-breakers.
Validity range: Walker-family geometries only. Non-Walker or heterogeneous architectures are outside the search space, so a better non-Walker design may exist and will not be found.
Accuracy: Verification inherits the discretization limits of the underlying coverage and link analysis: a gap shorter than the step or a hole between sample points can be missed, so a marginal design may verify as feasible and fail at finer resolution. Re-verify the recommendation directly with `coverage` and `link` at a finer step.
Reference: Walker constellation families; verification by the same coverage and link models the analysis commands use.

Verify the recommendation independently

The design report states that a candidate passed the solver’s own verification. Confirm it at finer resolution before trusting it:


orbitforge coverage --constellation designed.json \
  --duration-hours 24 --step-seconds 60 --grid-deg 2 --min-elevation-deg 25
 
orbitforge link --constellation designed.json \
  --station "Madrid,40.43,-3.7,0.6" \
  --frequency-ghz 20 --availability 99.9 --climate-zone K

The solver verified at a 120-second step over 6 hours. A 24-hour run at 60 seconds and a 2-degree grid is a substantially harder test, and it is the one worth quoting.

orbitforge design