REL: v0.1.0

[zuorenchen]

v0.1.0

Forty-seven pull requests since v0.0.2, from @zuorenchen, @thc1006 and @chichunwang.

Closes #93.

Urgent Upgrade Notes

Read this before running an existing agent

• Running out of time is reported as truncated, not terminated. Gymnasium keeps the two apart deliberately: terminated means the episode reached a terminal state, which here is the flight ending, and truncated means something outside it stopped the episode, which is what running out of the precomputed horizon is. v0.0.2 returned terminated=True for both, so a loop written as while not terminated: never ends on the horizon. It keeps calling step(), current_step walks past the end of the precomputed balloon flights, and the run dies indexing them. For scenario 1 the horizon is the usual ending, so this is the common path rather than an edge.

  Any agent loop needs to become while not (terminated or truncated): and keep the fourth value step() returns. evaluate.py and both example runners in doc/examples/ were updated with the change. The distinction also matters to a learning agent: an algorithm bootstraps the value of the final state when the episode was truncated and does not when it terminated, so reporting the clock as termination teaches it that running out of time is absorbing. (#94, #102, @thc1006), for #93

• Observations and given_parameters are copies now. An agent that wrote into the arrays it was handed used to be writing into the environment's own state, which was a scoring hole rather than an API detail: writing 2 into observation["balloon_status"] and never launching returned the whole scenario. Both are detached, so an agent that relied on mutating them in place no longer affects anything. (#99, @thc1006)

• The gimbal limit parameter was renamed. rocket.control.gimbal_range is now rocket.control.max_gimbal_angle, and there is no alias. This key is in the whitelist agents receive, so an agent that reads given_parameters["rocket"]["control"]["gimbal_range"] raises KeyError on v0.1.0. The shipped example agents do not read it, so they are unaffected. (#39, @zuorenchen)

• The default renderer crashes on Matplotlib 3.11. render_mode: "matplotlib" is what example_eval_cfg.yaml ships with and what README describes as needing no extra. On Matplotlib 3.11 the first frame raises AttributeError: 'list' object has no attribute 'shape' and the whole evaluation is lost. It needs two things at once, and this code produces both: Line3D.draw reads _verts3d[0].shape only when a coordinate is invalid for the axis scale, which every frame before launch is because the rocket state is all-NaN, and the update passed lists rather than arrays. Nothing bounds the version: the only constraint anywhere is ActiveRocketPy's matplotlib>=3.9.0. uv sync resolves 3.10.9 from the lockfile and is unaffected, but pip install -r requirements-dev.txt, which is what CI and the README's pip path both use, resolves whatever is current and hits it. Filed as #89 and fixed in this release by #90. Kept here because anyone who ran v0.0.2 against a current pip install hit it, and because it explains why the version you get is not the version the lockfile records.

• The command line score line gained a prefix, and the notebook stopped printing one. Diagnostics moved from print to the logging module, and only the CLI configures logging. Total reward: 7 now reads INFO:__main__:Total reward: 7, so anything reading that line by prefix breaks. The Colab notebook and run_for_evaluation in doc/examples/run_env_agent.py configure no logging at all, so they print neither the completion nor the score; the notebook's last cell renders the returned environment tuple where the score used to be. (#51, @thc1006). Fixed in this release by #88, so v0.1.0 prints the score the way v0.0.2 did. The note stays because a v0.0.2 user reading these lines from a script needs to know the format did move and came back.

• Trajectories differ from v0.0.2. The physics engine moved to the RocketPy v1.13 line and gained actuator dynamics. Results are reproducible within a release, not across this boundary, so anything measured against v0.0.2 needs re-running. (#60, @zuorenchen), (#39, @zuorenchen)

Changes by Kind

The first sixteen pull requests, grouped. Everything that landed after these
notes were first written is under Also in this release below.

Feature

• Actuator dynamics for the thrust vector, roll and throttle channels. Each gains a first-order lag through gimbal_time_constant, roll_torque_time_constant and throttle_time_constant; both shipped scenarios leave them null, which keeps the previous pass-through behaviour. (#39, @zuorenchen)
• The physics engine moves to the RocketPy v1.13 line. (#60, @zuorenchen)
• Rocket sensors are seeded from the scenario seed, so a run with a fixed seed reproduces its sensor noise instead of drawing from the process-global generator. (#54, @thc1006)
• Diagnostics go through the logging module rather than print. (#51, @thc1006)

Bug or Regression

• Submissions can be packed again. pack_for_submission raised TypeError on a SeedSequence sensor seed, which broke packing for every competitor. (#67, @thc1006)
• A network failure during the evaluate.py integrity check no longer throws away a submission that has already been simulated. (#68, @thc1006)
• An agent that never sends a launch action now reaches the timeout and ends the episode instead of raising AttributeError, and the interval between launch and the first simulated sample takes part in pop detection rather than being skipped. (#65, @thc1006)
• The evaluate.py integrity check no longer reports a mismatch for a file that differs only by a byte-order mark or by line endings. (#55, @thc1006)
• The default matplotlib renderer no longer crashes on Matplotlib 3.11. Line3D.draw reads a shape off the coordinates whenever one is invalid for the axis scale, which every frame before launch is, and the renderer was handing it lists. (#90, @thc1006)
• The command line prints Total reward: N again rather than INFO:__main__:Total reward: N, and the Colab notebook and run_for_evaluation print the score instead of nothing. (#88, @thc1006)
• Lint and pytest failures in the test suite. (#40, @zuorenchen)

Testing and CI

• Golden-master regression tests for scenarios 0 and 1, comparing the rocket and balloon trajectories against stored baselines so a change in the physics engine cannot move a score unnoticed. (#47, #49, @thc1006)
• Unit tests for the pop-detection geometry. (#48, @thc1006)
• Actuator dynamics tests with non-null time constants, and two test files that could skip silently now fail loudly instead. (#66, @thc1006)
• CI checks that uv.lock is current against the ActiveRocketPy submodule, which is what later caught a stale lockfile on develop. (#62, @thc1006)
• ruff is pinned so a release of it cannot turn a green branch red on its own. (#50, @thc1006)
• uv.lock relocked against the submodule. (#46, @thc1006)
• uv.lock relocked after the version bump, and CI now also runs on pushes to develop so a red integration branch cannot go unnoticed. (#78, @thc1006)

Known limitations

Stated here rather than discovered later. None of these are new in v0.1.0.

• Thrust vector control applies its moments without the matching lateral force. The flight equations reduce axial thrust for a gimbal deflection and apply the resulting moments, but the lateral components of that same thrust vector do not reach the translational equations. At the shipped 15 degree limit on both axes that is a missing 0.366 * T, and two independent 15 degree axes reach a combined deflection of 21.47 degrees. Every entrant runs the same model, so this does not favour anyone, but v0.1.0 should not be described as a validated thrust-vector model. Tracked upstream as ActiveRocketPy#21.
• Throttle scales thrust, not propellant flow. Mass properties come from the maximum flow rate and the motor cuts off at burn_time whatever the throttle did, so a throttle time constant lags the thrust without lagging the mass schedule. Documented in the README and unchanged here.
• The control fields on a launch action are not applied to that step. The launch action creates the flight; tvc, roll and throttle are first read on the following step(). The flight is not advanced on the launch step either, so nothing is simulated with the dropped values, but the contract is worth stating explicitly.

Also in this release

Everything below landed on develop after these notes were first written. Each
one names the regression it makes visible, since every one was found by a
mutation the suite as shipped did not catch.

Changes what a competitor sees

• #99 hands the agent copies. The observation arrays and the whitelisted parameter lists were the environment's own objects, so writing 2 into the status array and never launching scored the whole scenario, and an agent could widen its own throttle range or change the rocket's moment of inertia from its constructor.
• #70 stops the integrity check reading a partial or proxy-rewritten response as evidence that the competitor edited evaluate.py.
• #73, #74 make the submission write atomic and drop a redundant 165 MB field.
• #96 removes the Monte Carlo workspace instead of leaving 169 MB per run in /tmp, and keeps it when a run fails so there is something to read.
• #101 refuses a short Monte Carlo result set. The pinned RocketPy catches a keyboard interrupt and returns what it has, and exactly one returned trajectory broadcasts into a full hundred-balloon world in which every balloon flies the same path, scoring normally against a world that was never simulated.
• #98 decides whether two swept segments are parallel by the angle between them rather than by how long they are. A millimetre-scale pair at ninety degrees was classified as parallel and reported 1.5005 m where the real distance is 1.4995 m, which against a 1.5 m radius is a pop reported as a miss. Measured over a scenario 1 run: 56 of 9155 evaluations took that branch, all genuinely degenerate, so no score moved.
• #88, #90 are described under Urgent Upgrade Notes above.

Closes a hole in what the suite can see

• #83 checks scenario 1's release timing. Deleting the ground-to-released update, releasing all hundred balloons on the first step, or an off-by-one on the release condition each left all seven golden-master tests green.
• #100 pins when scenario 0 pops each balloon and how the episode ends. Replacing pop detection with "mark every balloon popped on the first flown step" passed every test before it, because the count, the trajectory and the duration are all unchanged by it.
• #81 writes down the pop rule settled in #63 and covers the clamping branches.
• #71 proves the scenario's actuator time constant is the one being used.
• #85 bounds the 3D position error absolutely. The relative bound scaled with altitude above sea level, so it exceeded the balloon radius at 108 of scenario 0's 119 sampled points and reached 48.8 m at apogee.
• #86 restores the per-balloon render assertions #40 deleted.
• #84 writes baselines as strict JSON, atomically, without narrowing their permissions.
• #82 stops a test import guard turning an installed but broken simulation stack into a skip.
• #87 pins the coordinate frame the observation is reported in. A 500 m offset on the horizontal position, latitude and longitude in place of X and Y, and X swapped with Y all passed before.
• #77 covers the submission path #67 fixed. Reverting Give sensors JSON-safe seeds so submissions can be packed again #67 left the suite green; with Cover the submission path #67 actually fixed, and pin the seed derivation #77 it fails 8 of 11.
• #95 normalises the console level and pins the records production emits.
• #69 hardens the sweep origin.
• #102, #103 finish the truncation change across every runner, and narrow what the isolation tests claim to what they establish.
• #104 finishes it everywhere else: the log line for running out of time still said "Terminated", a truncated episode drew no final frame unless its last step happened to land on the render cadence, and the README still described one termination flag and one way for an episode to end. The README snippet is not a .py file, so the invariant test could not see it; it reads the fenced blocks now.

Tooling

• #97 adds scripts/verify_submission.py, which regenerates a submission's balloons from the shipped scenario and its seed and asks whether the claimed pops were anywhere the rocket says it went. It does not verify the rocket trajectory, which stays the competitor's claim.
• #75 tests the Python 3.10 floor the package claims. #76 adds CONTRIBUTING and CHANGELOG. #79 groups these notes by kind automatically from labels, and adds CITATION.cff and SECURITY.md.

Still open, and therefore not in v0.1.0

• #58 moves submissions off pickle, paired with the leaderboard side.

Open questions rather than pending work: #57 on submission size, and #35 on the integrity warning, which fires for any checkout that is not current main and needs a release-pinned reference rather than a moving branch to close properly.

Verified as a whole

Each of these was green on its own base, which says nothing about the merged
tree, so develop was checked out clean and run through the exact CI after the
last of them landed: ruff check, ruff format, uv lock --check, and 315 tests
with 190 subtests passing with the slow suite enabled.

Contributors

Thank you to everyone whose work is in this release: @zuorenchen, @thc1006, @chichunwang.

Full Changelog: v0.0.2...v0.1.0

[thc1006]

Your order works. One step to add, and one thing I measured that says the rest is safe.

TLDR:

1. ARP #19  -> ARP develop
2. ARP develop -> ARP master        <- the step BPC actually needs
3. BPC submodule bump to that master
4. BPC #61 merge, tag v0.1.0
5. BPC #58 + leaderboard move to JSON together, release v0.1.1

Step 2 is easy to miss. BPC pins ActiveRocketPy master (435f58d), and #19 targets develop, so merging it alone changes nothing here. I checked whether that step drags anything else in: the two trees are byte-identical today, git diff master develop is empty, and master is just one release merge ahead. So after #19 lands, master picks up the actuator change and nothing else.

On whether the bump moves anyone's numbers, I pointed a scratch worktree's submodule at the #19 branch and ran it:

• both golden masters pass unchanged, 34 passed
• full BPC suite 315 passed
• uv lock --check still resolves, so the bump needs no lockfile change

That holds because both shipped scenarios leave gimbal_time_constant, roll_torque_time_constant and throttle_time_constant at null, so the branch #19 touches never runs.

On the cut-off: I would leave my six open PRs (#105 to #110) out of v0.1.0
and put them in v0.1.1. None of them changes a score, the golden masters are unchanged by all six together, and the submission checker they mostly touch is maintainer tooling that is not in the release. No reason to hold the tag for them.

Happy to run 3 and 4 once you have done 1 and 2, or to do the whole thing if you would rather. Step 2 is a release, so I would rather you called that one.

[thc1006]

Approving so this can go in.

Everything in the notes matches what is on develop: I checked each #nnn in the merge commits between main and develop against the changelog rather than reading for it.

One thing to land first, #111. The changelog was missing twenty of those pull requests, including a scoring change (#69, the first interval after launch was not checked for pops). It is a one file docs change, green, and without it v0.1.0 ships with an incomplete record.

My six open PRs (#105 to #110) are deliberately not in this cut. None of them changes a score, and the golden masters are unchanged by all six together, so there is no reason to hold the tag for them. They can go in v0.1.1 alongside the ActiveRocketPy bump.