Skip to content

ENH: Zero Inertia tensor Check #826

@aZira371

Description

@aZira371

Is your feature request related to a problem? Please describe.

Previously, users could accidentally set the rocket's dry inertia tensor to a zero vector or otherwise singular configuration. This led to runtime errors during simulation, typically manifesting as RuntimeWarning: divide by zero encountered in scalar divide and subsequent integration failures in the ODE solver.

Describe the solution you'd like

The dry inertia tensor should be validated as soon as the Rocket object is initialized. Specifically:

  • Construct the 3×3 inertia matrix from user-provided I_ij values in Rocket.init.

  • Immediately compute its determinant.

  • Raise a clear ValueError if the determinant is zero (i.e., the tensor is singular), with a helpful message prompting users to provide physically realistic values.

  • This approach shifts error detection earlier in the development cycle, prevents invalid configurations from reaching the solver, and gives users a precise explanation of what's wrong.

  • No changes are made to motor or dynamic inertia evaluation. Only the dry inertia (which is static and available at init) is validated.

Additional context

  • This change improves usability and safety, especially for multi-stage and upper-stage configurations where users often define placeholder or dummy inertia values.

  • It avoids obscure integration failures and makes RocketPy more robust to user error.

  • The solution avoids invasive structural changes by operating entirely within the Rocket class and leveraging existing Matrix functionality.

Future extensions could optionally introduce runtime checks for singular dynamic inertias (e.g., in u_dot_generalized), but this patch focuses only on validating static dry inertia at creation time. For dynamic inertia evaluation a debug_inertia_check can be implemented as optional boolean flag added to the Flight class to catch near-singular total inertia tensors during simulation. When enabled, it performs a lightweight determinant check on the dynamically evaluated total inertia matrix at each time step. If the determinant falls below a safe threshold, a clear error is raised indicating potential instability due to ill-conditioned inertial properties. This helps users catch modeling or configuration issues in motor or mass properties that may otherwise cause silent solver failures. The feature is off by default to avoid performance overhead in production runs.

Metadata

Metadata

Assignees

Labels

EnhancementNew feature or request, including adjustments in current codes

Projects

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions