Scenario kind pagesEdit on GitHubSource: docs/kinds/by-kind/aocs.md

aocs (scenario kind)

Scenario kind of the engine v0.38.0, family Mission analysis, links and space operations. Advisory: analysis output from a research and engineering tool, not type-approved navigation equipment and not a safety-of-life service. Every label here is the engine's or the verification matrix's; a kind is MODELLED unless the matrix says otherwise (how a label is earned: the README's Evidence section).

What it does#

Spacecraft attitude control: an inertial-pointing slew of a rigid hub with three or more balanced reaction wheels under MRP feedback (L = -K sigma - P omega), minimum-norm wheel torques clipped to each motor's limit, RK4 with a zero-order hold; optionally closed on a multiplicative EKF from a simulated gyro (angle and rate random walk) and star tracker. Reports settling time, final and peak pointing error, peak wheel speed and torque, the saturated fraction, angular-momentum drift and, with the estimator, its attitude error and NEES. The true-state loop is VALIDATED against Basilisk 2.9.1; the estimator is MODELLED.

One run of scenarios/aocs-slew.toml summarises as: aocs: 4 wheels, 600 s slew from 82.06 deg -> settles below 0.1 deg at 481.0 s | final 2.37e-2 deg | peak wheel 1797 rpm | true-state loop

Inputs#

From the schema (kshana kinds --json):

  • Required fields: hub_inertia_kg_m2, k_nm, p_nms, wheels, sigma0
  • Optional fields: duration_s, dt_s, sample_s, omega0_rad_s, pointing_threshold_deg, estimator

The example scenarios/aocs-slew.toml sets, among others:

Field Value Unit
dt_s 0.1 s
duration_s 600 s
hub_inertia_kg_m2 [[900, 0, 0], [0, 800, 0], [0, 0, 600]] not stated
k_nm 3.5 N m
kind aocs text
omega0_rad_s [0.001, -0.01, 0.03] s
p_nms 30 N m s
pointing_threshold_deg 0.1 deg
sample_s 1 s
sigma0 [0.1, 0.2, -0.3] not stated
wheels[0].axis [0.57735, 0.57735, 0.57735] 1
wheels[0].js_kg_m2 0.08 kg m^2

Run it#

kshana scenarios/aocs-slew.toml

2 bundled scenarios use this kind; the others are in scenarios/.

What it gives#

The scalar results of that run, with the units the engine states:

Result Value Unit
dt_s 0.1 s
duration_s 600 s
estimator no value not stated
final_pointing_error_deg 0.023682 deg
k_nm 3.5 N m
max_pointing_error_deg 82.056509 deg
momentum_drift_nms 1.4672e-12 N m s
p_nms 30 N m s
pointing_threshold_deg 0.1 deg
sample_s 1 s

Result label (the engine's): VALIDATED control law and wheel dynamics (against Basilisk 2.9.1 on the true-state loop); this run's inputs are the scenario's own — reaction-wheel attitude control under MRP feedback, inertial pointing, no sensor noise, no friction

The chart the engine writes for scenarios/aocs-slew.toml, kind aocs

Evidence#

MODELLED 1 · VALIDATED 1: the verification matrix rows that name this kind.

  • VALIDATED Inertial-pointing attitude control of a rigid hub with three or more balanced reaction wheels: the MRP feedback law L_r = -K sigma_BR - P omega_BR (Schaub and Junkins), minimum-norm wheel motor torques G_s u = -L_r clipped to each wheel's l Tests: aocs_basilisk_oracle.rs.
  • MODELLED The Lefferts-Markley-Shuster multiplicative EKF: body-frame attitude error and gyro bias states, propagation with the gyro rate less the bias estimate and Farrenkopf's discrete process noise (angle and rate random walk), star-tracker update

The rows the run itself exercised, with the oracle the matrix gives each (the public sources are named there):

  • MODELLED Deterministic, scenario-hashed, SBOM + cross-platform golden gates. Oracle (ExternalDataset): SBOM conformance to the official CycloneDX 1.5 JSON Schema (+ valid SPDX identifiers) — an external published standard, zero validation errors over the full dependency graph; the FoM-determinism / byte-reproducibility part remains a pinned self-consistency check, so the row stays MODELLED
  • VALIDATED Inertial-pointing attitude control of a rigid hub with three or more balanced reaction wheels: the MRP feedback law L_r = -K sigma_BR - P omega_BR (Schaub and J. Oracle (ExternalDataset): Basilisk 2.9.1 (AVSLab, ISC; the bsk wheel run as a separate tool, never linked or vendored): spacecraft hub, reactionWheelStateEffector (BalancedWheels, torque limit on), simpleNav, inertial3D, attTrackingError, mrpFeedback (no integral term) and rwMotorTorque at dt = 0.1 s with its RK4, against Kshana's own implementation on three cases (three orthogonal wheels; a four-wheel pyramid; a saturating four-wheel case),
  • MODELLED The Lefferts-Markley-Shuster multiplicative EKF: body-frame attitude error and gyro bias states, propagation with the gyro rate less the bias estimate and Farre. Oracle (InternalConsistency): Internal consistency: the filter's normalised estimation error squared against truth simulated from the same sensor models over Monte Carlo seeds, and convergence of the attitude and bias estimates. WHAT IS NOT: no external estimator or flight data has been compared (Basilisk 2.9.1 has no MEKF module); the sensor models are the textbook ones, without misalignment, scale factor or star-tracker field-of-view effects.

Limitations#

What the run's own report says is not modelled or not validated:

  • The true-state loop is VALIDATED against Basilisk 2.9.1; the estimator is MODELLED. (kind catalogue (kshana kinds --json))
  • Reproducibility & software assurance is MODELLED, not validated: a sub-claim is externally checked, but the whole capability composes modelled pieces, so the capability stays Modelled. (verification matrix (docs/MODELLED-RATIONALE.md))
  • Multiplicative EKF attitude estimation from a gyro and a star tracker is MODELLED, not validated: checked against its own closed-form / analytic identity — catches transcription and coefficient errors, but is not an external oracle. (verification matrix (docs/MODELLED-RATIONALE.md))

See also#