Skip to content

Changelog

Notable changes to orhelper. Releases before this file was started are listed on the tags page and in the git history.

0.2.0 - 2026-10-01

Versions 0.1.4 to 0.1.6 appeared in setup.py but were never published; the latest release on PyPI before this one is 0.1.3, so this release includes all changes since then.

Upgrading from 0.1.3: startup problems now raise exceptions instead of calling sys.exit(), misspelt keyword arguments to OpenRocketInstance are errors, and Python 3.9 or newer and JPype 1.3 or newer are required. See Changed below.

Added

  • A documentation site, built with MkDocs and published to GitHub Pages: installation, quickstart, a user guide, an API reference generated from the docstrings, a reference of every FlightDataType and FlightEvent member (with units and the OpenRocket versions that have it), a page on the differences between OpenRocket versions, and troubleshooting. Its code samples are the tested files in examples/.
  • Docstrings for the whole public API, including every AbstractSimulationListener hook.
  • tools/generate_reference.py, which generates the flight data and event reference pages from OpenRocket jars.
  • Seven new examples: events_and_stats.py, edit_and_save.py, parameter_sweep.py, multistage.py, custom_listener.py, parallel_runs.py and custom_setup.py, and a guided notebook, examples/tour.ipynb.
  • tests/test_examples.py runs every script in examples/ against a real OpenRocket jar (with OPENROCKET_JAR), also in CI, so the examples stay working across OpenRocket versions.
  • Exceptions for startup problems: OrHelperError (a RuntimeError) and its subclasses OpenRocketNotFoundError, JVMNotFoundError and JVMAlreadyStartedError. Messages say what was searched and how to fix it.
  • OpenRocketInstance(jvm_args=[...]) passes extra options to the JVM, for example -Xmx4g or -Djava.awt.headless=true.
  • orhelper.sample_ork_path() returns the path of a sample rocket that is now bundled with the package, so examples and the quickstart work after pip install.
  • examples/quickstart.py, a minimal example that needs no plotting libraries.
  • Support for OpenRocket 24.12 and 26.xx, plus compatibility tests (tests/test_compatibility.py, and tests/test_integration.py with OPENROCKET_JAR).
  • GitHub Actions workflow running the unit tests and checking the package build.
  • CI job that runs the Java integration tests against the released OpenRocket 22.02, 23.09 and 24.12 jars.
  • CONTRIBUTING.md and this changelog.

Changed

  • Behaviour change: a missing OpenRocket installation, jar or JVM now raises OpenRocketNotFoundError / JVMNotFoundError instead of calling sys.exit(), so it can be caught with except Exception and no longer ends notebooks. Code that caught SystemExit should catch orhelper.OrHelperError instead.
  • Behaviour change: starting a second JVM in one process raises JVMAlreadyStartedError instead of a bare OSError, and Helper(...) on a stopped instance raises OrHelperError instead of Exception.
  • Behaviour change: unknown keyword arguments to OpenRocketInstance (for example a misspelt jvm_path=) raise TypeError; wrongly typed paths raise TypeError instead of being ignored. Log level names are case-insensitive and an unknown name raises ValueError.
  • README rewritten with a quickstart, a "how it works" overview, common tasks and troubleshooting.
  • Packaging moved from setup.py to pyproject.toml: corrected project URL, added classifiers, license and extras (orhelper[examples], orhelper[pandas]). The minimum Python version is now 3.9 and the minimum JPype version 1.3.
  • examples/simple.ork moved to orhelper/data/simple.ork.

Fixed

  • Helper.load_doc and save_doc raised TypeError for a pathlib.Path; they now accept any path-like object.
  • examples/lazy.py crashed with TypeError: only 0-dimensional arrays can be converted to Python scalars on NumPy 2 (scipy's fmin passes a one-element array where a number was expected).
  • examples/monte_carlo.py overstated the landing distance (by 41% at the sample rocket's latitude of 45 degrees) because it converted degrees of longitude to metres without the cos(latitude) factor, and gave the wrong bearing for rockets landing west of the pad. It now matches the positions OpenRocket reports.
  • The integration test comparing get_final_values with the last time-series sample failed when that sample is NaN, as it is for motor mass in some OpenRocket development builds; it now compares NaN-aware.
  • Fixed the typo in the get_final_values docstring and documented branch_number, the return value and that the final value can be NaN.
  • log_level now works for Python logging: the enum's raw integers (1-7) were being passed to logging as levels, so everything was always logged, including other libraries' DEBUG messages. orhelper no longer calls logging.basicConfig() or touches the root logger; it sets the level of the orhelper logger only. As a result its messages are not printed unless the application configures logging.
  • Startup no longer crashes on an unsupported platform or when PROGRAMFILES is unset.
  • package_data pointed at a removed directory, so the examples were not installed. The sample rocket is now included correctly.