Release v0.0.2 (#33)

* Fix evaluate's encode problem (#5)

* Fix evaluate's encode problem

* Update yaml encoding

* Update to return reward from each step only. Total count of popped balloon is returned in info. #10 (#12)

* DOC: readme (#11)

* MNT: README
* MNT: fix scenario 0 balloon position info. #8

* Skip Monte Carlo balloon simulation for scenario 0 (#18)

* Skip Monte Carlo balloon simulation for scenario 0

scenario 0 uses static balloons at fixed heights, but reset() ran a
full Monte Carlo balloon-flight simulation every call and immediately
overwrote the result with static positions. Move the Monte Carlo path
into the non-scenario-0 branch and build the static balloon array
directly via a new __generate_static_balloon_flights helper. The
resulting _balloon_flights array is identical to before; only the
wasted Monte Carlo run and its file writes are removed.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Add pytest to dev optional-dependencies

The scenario 0 test suite lives in tests/; declare pytest in the dev
extra so it installs via requirements-dev.txt and the suite can be run.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Make vpython an optional, lazily-imported render dependency (#15)

vpython was imported at module scope in balloon_world.py and listed as
a hard dependency, so importing the environment required vpython even
for matplotlib rendering or render_mode=None (e.g. Colab). Move the
import into the vpython branch of _render_frame and expose vpython via
a `vpython` optional extra. Default installs and the matplotlib
renderer are unaffected; `pip install -e ".[vpython]"` enables it.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Clean up dead code, redundant calls, and unused imports (#7)

* Add cleanup invariant tests

AST-based static checks for redundant file.close() after with-open,
dead class-level imports, drifted example agent_kwargs, and empty
f-strings. No new dependencies beyond the standard library and PyYAML.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Remove dead code, redundant calls, and unused imports

- evaluate.py: drop three redundant file.close() after with-open
- example_agents.py: drop dead class-level get_initial_attitude
  import inside NavigationAgent (already imported at module scope)
- balloon_world.py: drop unused rocketpy.Function and vpython.arrow
  imports; drop f-prefix from two f-strings without interpolation
- example_eval_cfg.yaml: drop dummy arg3 unused by AttitudeRateControlAgent
- envs/__init__.py: use explicit "as" re-export to satisfy F401

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Document how to run tests and ignore .ci-venv

Add a Testing section to README pointing at "python -m unittest
discover tests", and gitignore the throwaway venv name commonly
used to install ruff locally.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Declare PyYAML as a dependency

evaluate.py and the cleanup tests import yaml, but PyYAML was never
declared in pyproject.toml dependencies and is not pulled in
transitively. A fresh `pip install -r requirements.txt` therefore
leaves `import yaml` failing with ModuleNotFoundError. Add pyyaml to
the project dependencies.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
Co-authored-by: ZuoRen Chen <180084773+zuorenchen@users.noreply.github.com>

* Move Monte Carlo output out of the package directory (#22)

* Move Monte Carlo output out of the package directory

__generate_balloon_flights passed MonteCarlo a filename inside the
installed package directory (BalloonPoppingGymEnv/envs/data/), so every
non-scenario-0 reset wrote balloon_sim.{inputs,outputs,errors}.txt
there. That fails in read-only / installed environments and pollutes
the package tree. Write to tempfile.gettempdir() instead; the env only
uses the in-memory simulate() results, so the persisted files are a
pure side effect whose location does not affect behavior.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Use a per-process Monte Carlo output filename

tempfile.gettempdir() is shared across OS users, so a fixed "balloon_sim"
name there can collide: on a shared host the second user's reset() hits
a PermissionError writing the first user's files. Suffix the name with
the process id so concurrent processes and users get distinct paths.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Add uv as the recommended environment setup path (#20)

* Add uv as the recommended environment setup path

uv installs the pinned Python, creates the virtual environment, and
installs locked dependencies in one step, lowering the setup barrier
for contributors. Declare activerocketpy as a path dependency via
[tool.uv.sources] so uv resolves the submodule, pin Python to 3.14
via .python-version, and commit uv.lock. The requirements.txt / pip
path is unchanged and still works for users who do not use uv. Also
drop the duplicate vpython entry left in [project.dependencies] by the
PR #7 / #15 merge -- vpython is the optional extra only.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Switch the README uv setup to the standalone installer

The uv steps said `pip install uv` then `uv sync`, but pip places the
uv executable in a scripts directory that is frequently not on PATH,
so the bare `uv` command then fails. Document uv's standalone
installer instead, which puts `uv` on PATH, and add a troubleshooting
note covering a stale shell, PATH, and the `python -m uv` fallback.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Add standardized issue templates (#25)

Add GitHub issue form templates under .github/ISSUE_TEMPLATE: a bug
report, a feature request / proposal, and a question form, plus a
config that keeps blank issues enabled. Each form collects the
context that otherwise has to be asked for in follow-up comments.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* ENH: Add architecture for post sim graphics (#28)

* Enhance BalloonPoppingEnv with trajectory logging and tidy up attribute in _init_ and reset

* Add save_trajectory function to save balloon and rocket trajectories into json file. Call save_trajectories in evaluate_scenario. TODO: render_trajectory

* ENH: Add leaderboard submission functions (#31)

* Enhance BalloonPoppingEnv with trajectory logging and tidy up attribute in _init_ and reset

* Add save_trajectory function to save balloon and rocket trajectories into json file. Call save_trajectories in evaluate_scenario. TODO: render_trajectory

* Add balloon_status to trajectories

* ENH: pack results for leaderboard submission

* Add time to trajectory log

* Save trajectory file in UTC

* Add gust to balloon_world environment (#32)

* Add gust model configuration to environment parameters and implement gust handling in BalloonPoppingEnv

(cherry picked from commit 9550377)

* Refactor quasi-random gust model

* Fix rng usage. run __create_environment() after env.reset

---------

Co-authored-by: RickyRicato <rickywang44@gmail.com>

* Render every balloon in the vpython renderer (#27)

* Render every balloon in the vpython renderer

_render_frame's vpython branch created a single sphere and
positioned it from _balloon_states[0], so a scenario with N
balloons showed only the first. Create one sphere per balloon and
update them all, which matches the matplotlib branch that already
slices over every balloon. Add tests/test_render.py, which mocks
vpython and checks that a reset creates one sphere per balloon.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Assert the vpython renderer repositions every balloon

The render test checked that num spheres are created but not that
all of them are repositioned each frame, so a regression updating
only one sphere would still pass. Add a vector() call-count
assertion that pins the per-balloon update loop.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* ENH: Add rocket and balloon colors to vpython rendering

* Add vPython option to comment

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
Co-authored-by: zuorenchen <zuorenchen@m110.nthu.edu.tw>

* Add GitHub Actions CI workflow (#23)

* Add GitHub Actions CI workflow

Set up .github/workflows/ci.yml with a lint job (ruff check and
format check) and a test job that installs the project with its
ActiveRocketPy submodule, runs the suite with coverage, and uploads
a coverage report. CI runs on pushes to main, pull requests, and
manual dispatch. The Codecov upload step stays dormant until a
CODECOV_TOKEN secret is configured.

Add tests/test_import_smoke.py to confirm the package and example
agents import after an install, and declare pytest-cov as a dev
dependency for coverage generation.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Bump CI actions off the deprecated Node 20 runtime

actions/checkout@v4, actions/setup-python@v5 and
actions/upload-artifact@v4 run on Node 20, which GitHub deprecates
in June 2026. Move them to the current majors (v6, v6, v7), which
run on Node 24.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Probe the simulation stack with find_spec in the smoke test

The skip guard used importlib.import_module, which executes rocketpy
and so cannot tell an installed-but-broken stack apart from an absent
one -- test_import_example_agents would skip the import breakage it
exists to catch. find_spec checks installation without importing, so
the test runs and fails loudly when an installed stack is broken.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* Update readme  (#34)

* Add leaderboard information

* Run formatter

* Add release notes

* Update release notes

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>
Co-authored-by: ChiChun Wang <99960850+chichunwang@users.noreply.github.com>
Co-authored-by: 秀吉 <84045975+thc1006@users.noreply.github.com>
Co-authored-by: RickyRicato <rickywang44@gmail.com>

Author: 3 people

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report something broken in the simulator, environment, or evaluation
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please give enough detail for it to be reproduced.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened
+      description: A clear description of the bug, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Commands, scenario number, agent, and config used. A minimal snippet helps.
+      placeholder: |
+        1. ...
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output / traceback
+      description: Paste the full traceback or log. It is formatted as code automatically.
+      render: shell
+    validations:
+      required: false
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, install method (uv / pip), and the commit or branch.
+      placeholder: "Windows 11, Python 3.14, uv, develop @ abc1234"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature request / proposal
+description: Propose an enhancement, a design change, or new functionality
+title: "[Proposal] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for enhancements and design discussions. For a non-trivial change, open the proposal here and discuss before sending a PR.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / current state
+      description: What is missing or not working well today, and why it matters.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: What you want to do. Outline the approach and the files or areas affected.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives and trade-offs
+      description: Other options considered, and the trade-offs of the proposed one.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,19 @@
+name: Question
+description: Ask about using the simulator, the competition, or the leaderboard
+title: "[Question] "
+labels: ["question"]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Your question
+      description: What you are trying to do, and what you are unsure about.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What you have already tried, the relevant scenario or config, and docs you have already read.
+    validations:
+      required: false

.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install ruff
+        run: python -m pip install ruff
+
+      - name: Lint
+        run: ruff check BalloonPoppingGymEnv/ tests/
+
+      - name: Format check
+        run: ruff format --check BalloonPoppingGymEnv/ tests/
+
+  test:
+    name: Tests and coverage
+    runs-on: ubuntu-latest
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Run tests with coverage
+        run: pytest tests/ --cov=BalloonPoppingGymEnv --cov-report=xml --cov-report=term
+
+      - name: Upload coverage artifact
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: warn
+
+      # Skipped until a CODECOV_TOKEN repository secret is configured.
+      - name: Upload coverage to Codecov
+        if: ${{ env.CODECOV_TOKEN != '' }}
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: false

.gitignore

@@ -3,10 +3,17 @@ BalloonPoppingGymEnv/envs/data/*
 !BalloonPoppingGymEnv/envs/data/**.md
 !BalloonPoppingGymEnv/envs/data/**.nc
 
+BalloonPoppingGymEnv/evaluation/results/**.json
+BalloonPoppingGymEnv/evaluation/results/**.pkl
+
 # VSCode specific
 .vscode/
 
 # Python specific
 .venv
+.ci-venv
 .ruff_cache
-__pycache__
+__pycache__
+.pytest_cache
+.coverage
+coverage.xml

.python-version

@@ -0,0 +1 @@
+3.14

BalloonPoppingGymEnv/agents/example_agents.py

@@ -109,8 +109,6 @@ def get_action(self, observation):
 class NavigationAgent(BaseAgent):
     """A simple inertial navigation agent that integrates rocket states"""
 
-    from BalloonPoppingGymEnv.envs.balloon_world import get_initial_attitude
-
     def __init__(self, *args, **kwargs):
         super().__init__(*args)
 

BalloonPoppingGymEnv/envs/__init__.py

@@ -1 +1,3 @@
-from BalloonPoppingGymEnv.envs.balloon_world import BalloonPoppingEnv
+from BalloonPoppingGymEnv.envs.balloon_world import (
+    BalloonPoppingEnv as BalloonPoppingEnv,
+)