Guide

Commands

Everything user-facing goes through python main.py in the repository root. It puts python/ on the path itself. python main.py list prints every command and tool.

Where a run reads its settings

In orbit.yaml under training:, a pair [lo, hi] is drawn every episode, a bare number is fixed, and null keeps that variant’s own default.

Flags and --set section.key=value override the files. The value is read as YAML. Sections are network, orbit, and train. --network, --orbit, and --train swap in a whole file.

Check the install

python main.py test      # pytest. Basilisk referee tests skip when Basilisk is absent
python main.py verify    # each kernel against an independent check

Simulate

python main.py decay
python main.py decay --kind min --physics high --set orbit.simulation.alt0_km=450
python main.py decay --set orbit.simulation.geom=stl1pct

python main.py sim geometry --in craft.stl --quality 1pct
python main.py sim lift_drag_study --out outputs/results/lift_drag
python main.py sim aoa_decay --alpha 45
python main.py sim srp_assess
python main.py sim srp_f107_sweep -h
python main.py sim optics_run -h
python main.py sim advisor_run -h
python main.py sim validate_attitudes --quality 1pct
python main.py sim plot_simplify

decay reads config/orbit.yaml → simulation: and writes outputs/results/decay/<stamp>_<kind>_<physics>/ plus the settings.yaml it used. --kind is min, max, or both.

The shipped geometries on these tools are hex (the hex sail in data/earthcup_hex_v3.geom) and stl1pct (SolarCat, simplified at the 1% budget). A mesh of your own spacecraft takes the path on the free-molecular flow page. validate_attitudes checks the SolarCat STL. plot_simplify draws a cube and a hex prism.

python main.py sim <tool> -h prints that tool’s flags.

Train

python main.py train
python main.py train --network config/network_quick.yaml
python main.py train --algo sac --arch 3x32 --timesteps 500000 --n-envs 16 --seed 7
python main.py train --variant v11 --physics high --gsi cll --controller quaternion
python main.py train --name storm --set orbit.training.ap=[100,200]
python main.py train --variant v10r6

How that loop is built, and what the variant changes, is on the control page. A session writes:

• outputs/snapshots/<MM-DD-HH-MM>_<ALGO>_<LxW>.yaml before training starts, and again when it ends. A crash is recorded too.
• outputs/models/<id>/ with the Stable-Baselines3 zip, vecnormalize.pkl, TensorBoard logs, and metrics.json.

python main.py snapshots
python main.py train --from-snapshot outputs/snapshots/<id>.yaml
python main.py sweep --config config/sweep.yaml
python main.py quantize --in outputs/models/<id>/models/ppo_<id>.zip --out int8.zip

Replaying a snapshot keeps its plant. Changing train.variant, backend, physics, gsi, or reward_w reads the plant YAML again.

The v12 backend is PPO on variant v10 with an extra wrapper, a checkpoint, and a 10-orbit comparison every 50 000 steps. Pass --backend v12.

Physics switches you will actually use

Degree 70 is available by setting gravity.degree in a physics file. The training presets stay at 2, 4, and 8.

Older campaign tools

python main.py eval, plot, and legacy rebuild figures and reports from the pre-v2.7 campaigns. They read and write outputs/.old/. python main.py list names each one. Several of them take no flags and start as soon as you call them, so use -h when you only want the description.