API reference¶
Generated from docstrings. The package root re-exports the common entry points; the discipline models and optimization tools live in their submodules.
Package root¶
orbitdc
¶
orbitdc: MDAO of orbital compute infrastructure with terrestrial baselines.
The package optimizes delivered useful compute, not nominal capacity. See
SPEC.md and EQUATIONS.md. Public entry points:
import orbitdc as odc
space = odc.load_scenario("...space.yaml")
earth = odc.load_scenario("...earth.yaml")
result = odc.compare(space, earth)
print(result.summary())
print(result.explain_binding_constraints())
ComparisonResult
¶
Evaluation
dataclass
¶
evaluate(scenario, overrides=None)
¶
Dispatch on scenario kind.
evaluate_earth(scenario)
¶
Evaluate a terrestrial baseline scenario.
evaluate_space(scenario, overrides=None)
¶
Evaluate an orbital scenario, optionally overriding named scalar drivers.
list_catalogs()
¶
Names of the bundled data catalogs (YAML files under orbitdc/data).
load_scenario(path)
¶
Read a YAML scenario file and validate it into a Scenario.
load_scenario_dict(data)
¶
Validate an already-parsed scenario mapping.
export_report(result, path, fmt='html')
¶
Write a comparison report to path. fmt is 'html' or 'md'.
Comparison and evaluation¶
orbitdc.compare.compare(space, earth)
¶
Compare an orbital design against a terrestrial baseline.
orbitdc.compare.evaluate_space(scenario, overrides=None)
¶
Evaluate an orbital scenario, optionally overriding named scalar drivers.
orbitdc.compare.evaluate_earth(scenario)
¶
Evaluate a terrestrial baseline scenario.
orbitdc.evaluation.Evaluation
dataclass
¶
Scenario schema and loading¶
orbitdc.core.scenario.load_scenario(path)
¶
Read a YAML scenario file and validate it into a Scenario.
orbitdc.core.schema
¶
Validated scenario schema (the I/O boundary).
A Scenario is the user-facing description of a design to evaluate. Physical
and cost constants live in the catalogs (data/); a scenario references those
by key and adds architecture and a few high-level knobs. Two kinds are
supported, discriminated by kind: an orbital design (space) and a
terrestrial baseline (earth).
Thermal co-design¶
orbitdc.thermal.codesign
¶
Radiator-in-the-loop thermal co-design (THEMRAL_RADIATOR_DEEPDIVE §11).
Couples chip power -> junction temperature -> coolant loop -> radiator temperature -> radiator area -> radiator mass. The radiator runs as hot as the chip stack allows (to minimize area), sized for end-of-life rejection.
thermal_codesign(*, q_waste_w, chip_stack, coolant, surface, env, area_available_m2, eol=True, t_rad_override=None, view_factor=1.0)
¶
Solve the coupled chip->radiator thermal design and size area + mass.
t_rad_override (if given) caps the radiator temperature below the junction
ceiling — running cooler costs area but eases the chip thermal margin.
orbitdc.thermal.view_factors
¶
Thermal Level 4: a parametric effective view factor to deep space.
Levels 0-3 assume a radiator sees a full cold-space hemisphere. A real panel
does not: it partly sees its own structure and the opposite face, it is
articulated off the ideal edge-to-sun attitude, and the solar array subtends
part of its sky. This module reduces the view factor parametrically — NOT by
ray tracing or Monte-Carlo integration, which stay Tier-3 plugins (see
THEMRAL_RADIATOR_DEEPDIVE.md §4). Defaults are low confidence; expose them
as drivers rather than headline numbers.
The three losses combine multiplicatively on the nominal panel view factor:
F_eff = F_nominal * cos(articulation) * (1 - self_view) * (1 - array_block)
Articulation enters as a cosine because a panel tilted by theta from its ideal attitude projects less of its radiating area toward cold space.
effective_view_factor(*, nominal=0.95, articulation_deg=0.0, self_view_frac=0.05, array_blocking_frac=0.1)
¶
Effective radiator view factor to deep space (0..nominal).
nominal: panel's geometric view factor with no obstructions (catalog value). articulation_deg: panel attitude off the ideal cold-space pointing. self_view_frac: hemisphere fraction lost to own structure / opposite face. array_blocking_frac: hemisphere fraction subtended by the solar array.
orbitdc.thermal.degradation
¶
Thermal Level 5: mission-integrated degradation (coatings, MMOD, loop-out).
Levels 0-4 evaluate the radiator at a single end-of-life snapshot. Level 5
integrates three time-dependent losses over the mission and returns a derate on
the rejectable flux (THEMRAL_RADIATOR_DEEPDIVE.md §5):
- Coating trajectory. alpha rises and eps falls roughly linearly from BOL to EOL; the net flux is computed at each step rather than only at EOL.
- Micrometeoroid / debris. Cumulative panel area loss accrues with time.
- Single-loop-out. A coolant-loop failure removes 1/N of capacity for the rest of the mission; its probability rises with time.
The derate is the mission-averaged rejectable flux divided by the EOL-snapshot flux the lower levels already use, so Level 5 < EOL whenever MMOD or loop-out dominate the (favorable) BOL->EOL coating averaging. Defaults are low confidence.
mission_thermal_derate(*, mission_years, t_rad_k, surface, env, view_factor=1.0, mmod_area_loss_per_year=MMOD_AREA_LOSS_PER_YEAR, loop_out_prob_per_year=LOOP_OUT_PROB_PER_YEAR, n_loops=N_COOLANT_LOOPS, n_steps=24)
¶
Mission-integrated rejectable-flux derate vs the EOL snapshot.
Orbit and formation¶
orbitdc.models.formation
¶
Formation flying: relative dynamics, formation-keeping Δv, collision margin.
The formation-keeping budget couples to the same separation that 4A's optical crosslink uses: a tighter formation buys more crosslink bandwidth but costs more to hold safely. Two effects:
-
Drift cancellation. Differential drag (and J2) across the formation is a small fraction of the nominal drag acceleration; nulling the accumulated relative velocity costs Δv ≈ a_diff · t. This is set by the disturbance, not the separation.
-
Collision avoidance. With separation s and navigation uncertainty sigma, the margin is s/sigma "sigmas". When that drops below a safe threshold, conjunction maneuvers (CAMs) are needed; their rate rises as the formation tightens. This is the separation-dependent term: closer = riskier = more Δv.
Relative motion uses the Clohessy-Wiltshire mean motion n = sqrt(mu/a^3); in the unperturbed two-body CW model bounded relative orbits are closed (zero secular Δv), so all formation-keeping cost here is perturbation- or collision-driven.
mean_motion(radius_m)
¶
Clohessy-Wiltshire mean motion n = sqrt(mu / a^3).
formation_keeping(*, altitude_km, drag_deltav_per_year_ms, differential_drag_frac, separation_m, position_uncertainty_m, safe_margin_sigmas=SAFE_MARGIN_SIGMAS, cam_deltav_ms=CAM_DELTAV_MS)
¶
Formation-keeping Δv per year and the collision-avoidance margin.
drag_deltav_per_year_ms is the nominal station-keeping drag Δv (reused so the differential term stays consistent with the orbit model).
orbitdc.models.orbit
¶
Closed-form orbital mechanics (EQUATIONS.md §6).
Phase 1 needs only circular-orbit period, velocity, and a sunlit/eclipse fraction from a cylindrical-shadow model. No orbit-propagation library is used (poliastro is archived; prefer hapsira/astropy if one is ever needed).
circular_velocity(radius_m)
¶
v = sqrt(mu / r).
orbital_period(radius_m)
¶
T = 2 pi sqrt(r^3 / mu).
eclipse_fraction(radius_m, beta_deg=0.0)
¶
Fraction of a circular orbit spent in Earth's cylindrical shadow.
f_e = (1/pi) * arccos( sqrt(r^2 - Re^2) / (r * cos(beta)) ), and 0 when the beta angle is large enough that the orbit never enters the shadow.
atmospheric_density(altitude_km)
¶
Coarse log-linear interpolation of mean atmospheric density (kg/m^3).
drag_deltav_per_year_ms(altitude_km, drag_area_m2, mass_kg, cd=2.2)
¶
Annual delta-v to offset atmospheric drag: a_D = 0.5 rho v^2 Cd A / m.
station_keeping_propellant_kg(total_deltav_ms, dry_mass_kg, isp_s)
¶
Propellant from the rocket equation: m_prop = m_dry (exp(dv/(Isp g0)) - 1).
orbit_state(altitude_km, beta_deg=0.0)
¶
Full closed-form orbit state for a circular orbit at a given altitude.
Reliability¶
orbitdc.models.reliability
¶
Reliability and availability (EQUATIONS.md §10).
Exponential survival with an annual failure rate, averaged over the mission to get the mean online fraction, then adjusted by spares and reset-recovery availability. In space MTTR is reset/degradation/spare-activation, not a technician swap.
fleet_health_curve(*, n_accelerators, annual_failure_rate, mission_years, spare_fraction, reset_recovery_availability, resupply_interval_years=None, n_steps=48)
¶
Time-stepped fleet capacity, optionally restored at launch-quantized resupplies.
Without resupply the surviving fraction decays as exp(-lam t) (a graceful decline). With a resupply interval, failed units are replenished at each launch window, producing a sawtooth that the mission-mean availability integrates over. Spares add a flat buffer; reset-recovery scales the result.
Cost¶
orbitdc.models.cost
¶
Cost model (EQUATIONS.md §11).
Lifecycle cost on a present-value basis, plus levelized cost of compute (LCOC). Capex lands at t=0; opex and replacement are annual streams; delivered compute is its own discounted stream. Levelizing matters because space economics depend on mission life, degradation, failure rate, and utilization, not just capex.
learning_multiplier(quantity, learning_rate)
¶
Wright's-law unit-cost multiplier vs the first unit.
learning_rate is the cost fraction per doubling of cumulative production (e.g. 0.85 = 85% curve). 1.0 disables learning. Applied as a fleet-average proxy (the Nth-unit multiplier).
trl_multiplier(trl)
¶
Cost premium for immature hardware: TRL 9 = 1.0, lower TRL costs more.
Optimization¶
orbitdc.optimize.robust
¶
Multi-scenario comparison and robust optimization (Phase 4B).
A space design's LCOC is independent of the Earth baseline, so "robustness across Earth baselines" reduces to beating the toughest (cheapest) baseline. These helpers make that explicit: a batch matrix of verdicts across baselines, and an optimizer that minimizes space LCOC and reports how many baselines it then beats.
batch_compare(space, earths)
¶
Compare one space design against several Earth baselines.
robust_optimize(space, earths, design_vars, *, maxiter=60)
¶
Minimize space LCOC, then report how many Earth baselines it beats.
Beating the toughest (cheapest) baseline implies beating them all, so this is the robust objective across the ensemble.
orbitdc.optimize.sensitivity
¶
Sensitivity analysis: one-at-a-time tornado swings and global Sobol indices.
The tornado re-evaluates space LCOC at a low/high value per driver with the others nominal. Sobol (via SALib) attributes output variance to each driver and its interactions across the whole space.