Errors, logging and JVM options

Exceptions

When orhelper can't start OpenRocket, it raises an exception. They all derive from OrHelperError, which is a RuntimeError, so you can catch them together:

Exception	Meaning	What to do
OpenRocketNotFoundError	The installation or the jar was not found	Pass jar= or orhome=
JVMNotFoundError	No Java was found	Install Java, set JAVA_HOME, or pass jvm=
JVMAlreadyStartedError	A second JVM in the same process	Use one with block, or separate processes

A misspelt keyword argument (jvm_path=, for example) raises TypeError, and an unknown log level raises ValueError.

Problems inside OpenRocket surface as the Java exception, raised by JPype, for example RocketLoadException for a file that can't be loaded. Asking for a flight data variable that your OpenRocket version doesn't have raises an AttributeError, and a component that doesn't exist in get_component_named raises a ValueError.

Choosing which OpenRocket and Java

By default orhelper finds the installed OpenRocket. You can choose another with these keyword arguments of OpenRocketInstance:

Argument	Meaning
jar	An OpenRocket jar file. It takes precedence over the installed one.
orhome	An OpenRocket installation folder, if it is not in the default location.
jvm	The Java library to use (libjvm.so, libjvm.dylib or jvm.dll).
jvm_args	A list of extra options for the JVM, for example ["-Xmx4g", "-Djava.awt.headless=true"].

Logging

log_level sets how much OpenRocket tells you. It takes "OFF", "ERROR", "WARN", "INFO" (the default), "DEBUG", "TRACE" or "ALL", in any case. At the default level OpenRocket prints a lot of information while it loads files and simulates, so log_level="ERROR" is a good choice for scripts.

orhelper's own messages (which jar it found, for example) go through Python's logging module, in the orhelper logger. orhelper doesn't configure logging for you; to see the messages:

import logging
logging.basicConfig(level=logging.INFO)

All of it together

examples/custom_setup.py

"""Start OpenRocket with explicit settings and handle startup problems.

By default orhelper finds the installed OpenRocket. To use a specific jar, set the
OPENROCKET_JAR environment variable (or pass ``jar=`` directly):

    OPENROCKET_JAR=/path/to/OpenRocket-24.12.jar python custom_setup.py

Besides ``jar``, you can pass ``orhome`` (an OpenRocket installation folder), ``jvm`` (the
Java runtime library) and ``jvm_args`` (options for the JVM, for example ``-Xmx2g``).
"""
import logging
import os
import sys

import jpype

import orhelper

# orhelper logs through the standard `logging` module and does not configure it for you.
logging.basicConfig(level=logging.INFO)

try:
    instance = orhelper.OpenRocketInstance(
        jar=os.environ.get("OPENROCKET_JAR"),  # None means: use the installed OpenRocket
        jvm_args=["-Xmx1g"],  # limit the Java heap to 1 GB
        log_level="ERROR",  # log level of OpenRocket itself: "ERROR" hides its warnings
    )
except (orhelper.OpenRocketNotFoundError, orhelper.JVMNotFoundError) as error:
    sys.exit(f"Could not start OpenRocket: {error}")

with instance:
    java = jpype.java.lang
    print(f"Java version: {java.System.getProperty('java.version')}")
    print(f"Java heap limit: {java.Runtime.getRuntime().maxMemory() // 2 ** 20} MB")

    orh = orhelper.Helper(instance)
    doc = orh.load_doc(orhelper.sample_ork_path())
    print(f"Loaded rocket '{doc.getRocket().getName()}' with {doc.getSimulationCount()} simulation(s)")