Reference

Architecture & the step loop

How one RL decision turns into 300 s of integrated orbit and attitude motion, and which module owns each part.

Repository layout

main.py              front door (train, sweep, decay, snapshots, quantize, sim/eval/plot/legacy, run, test, verify)
cpp/include/arlamx/  headers: types, constants, api, aero/, srp/, orbit/, attitude/, control/, mag/, onboard/
cpp/src/             implementations + bindings.cpp (pybind11 module arlamx_cpp)
python/arlamx_v2/    env.py (Gym), physics.py (presets), atmosphere.py (MSIS), geometry.py, train*.py,
                     session.py (snapshots), sweep.py, reward*.py, sensors.py, estimators.py, power.py,
                     advisors/ (heuristic, sampling MPC), propagator.py + nav.py (onboard), quantize.py, int8.py
config/              network.yaml, orbit.yaml, train.yaml, sweep.yaml, sc_v*_6mq*.yaml, plant/*.yaml
data/                GGM03S, WMM COF, .geom plate models, STL meshes
tests/               per-module tests + basilisk_ref + integration + validation
docs/                module notes (docs/modules), handoff notes, this site (docs/html)
outputs/             snapshots/, models/, results/, .old/ (pre-v2.7 campaigns)

Who does what

Concern	Owner	Language
Orbit + attitude integration, all forces and torques	`Simulator::step` (`cpp/src/api.cpp`)	C++
Atmosphere density, temperature, mean mass, species	`atmosphere.query_msis` → `Simulator.set_atmosphere[_end]`	Python (pymsis)
Space-weather draws and jumps, SRP flashes, damage events	`ArlamxV2Env.reset / _apply_jumps / step`	Python
Physics preset → `SimParams`	`physics.apply_to_params`	Python
Observations, reward, power, sensors, torque KF	`env.py`, `reward*.py`, `sensors.py`, `estimators.py`, `power.py`	Python
Onboard forecast (FP32 two-body + J2 + exp. drag + held SRP)	`propagator.py` ↔ `onboard/propagator_f32.cpp`	both (mirror)
Policies	SB3 (PPO/SAC/TD3), `advisors/` (heuristic, sampling MPC), `duo.py`	Python

One env step

One env step is one advisor step: 300 s (150 s for v6), 150 substeps of 2 s, RK4 inside each substep. External forces and torques are evaluated once per substep and held (zero-order hold) across its RK4 stages. Gravity is re-evaluated at every RK4 stage.

Timing constants

Quantity	Default	Where
advisor step (env step)	300 s (v6: 150 s; override `advisor_s`)	`SimParams.advisor_step_s`, env ctor
substep (force/torque evaluation)	2 s (override `inner_dt`)	`SimParams.dt_s`
RK4 step	2 s (≤ dt_s)	`integrator.rk4_step_s`
slew clip per step	45° (v3), 40° (v4+)	`SimParams.max_slew_rad`
epoch	JD 2461060.5 = 2026-01-15 00:00 UTC	`env.EPOCH_JD`, `SimParams.epoch_jd`
hard stop	geodetic altitude < 80 km (plant); env terminal altitudes are per variant	`api.cpp`
step cost	≈1.23 ms (v10 standard physics)	CHANGELOG_v2.7

Frames

Frame	Definition in code
N (inertial)	Earth-centred, z = rotation axis. Earth-fixed is reached by a z-rotation of IAU-1982 GMST (`dcm_EN`), with no precession, nutation or polar motion. The analytic Sun and Moon are given in the mean equator of date and used as N. SPICE returns J2000 (see limits).
E (Earth-fixed)	`r_E = dcm_EN(gmst) r_N`, used for gravity SH, WMM and MSIS longitude
B (body)	MRP σ_BN, `C_BN = mrp_to_dcm(σ)`. Panels, rods and the inertia are in B.
F (flow)	e₁ = v_rel, e₃ = orbit normal (or ⟂B for `flowB`, ⟂Sun for `flowS`), e₂ = e₃ × e₁. Used when `cmd_frame ≠ inertial`.
L (LVLH)	`dcm_LN`: z = −r̂, y = −ĥ, x = y × z

StepOut (what `Simulator.step` returns)

Key	Meaning
`r, v, sigma, omega, t`	state at the end of the step (N frame, MRP shadow set, body rates)
`altitude_km`, `sma_m`	Bowring geodetic height; vis-viva semi-major axis
`eclipse`, `sun_B`, `B_B`	shadow flag at the end, Sun and field in body axes
`Cd`, `Cl`	last-substep coefficients on A_ref (half the total panel area if `one_sided_ref`)
`drag_N`	mean along-track drag magnitude (N)
`dE_actual`, `dE_baseline`, `dE_drag`, `dE_lift`	specific orbital-energy change (J/kg) from aero + SRP + ERP, from the min-drag counterfactual, and the drag and lift parts
`tracking_err_rad`	mean attitude error to the target
`tau_ctrl_mean, tau_aero_mean, tau_srp_mean, tau_erp_mean, tau_gg_mean, tau_env_mean`	mean torques (N·m, body)
`tau_cmd_mean, tau_demand_mean, tau_demand_absmean, tau_shortfall_frac, m_mean, gyro_mean`	controller demand before and after clips, dipole used, magnetic shortfall, gyroscopic term
`a_srp_sun`, `n_sunlit`	mean along-track SRP acceleration while lit; count of lit substeps
`rod_duty2_mean`	per-rod mean of (d/d_max)² × duty (I²R power proxy)
`n_substeps`	substeps completed (fewer if the 80 km stop fired)