ENH: Add custom exceptions and unstable rocket warning (#285) (#970)

* ENH: Add custom exceptions and unstable rocket warning (#285)

Introduces a dedicated `rocketpy/exceptions.py` module with three new
types: `InvalidParameterError` (bad radius/mass values), `InvalidInertiaError`
(wrong inertia tuple length), and `UnstableRocketWarning` (negative static
margin at ignition). Validation is applied in `Rocket.__init__` and a warning
is issued automatically after `evaluate_static_margin` when the rocket is
aerodynamically unstable. All three new names are exported from the top-level
`rocketpy` package.

Closes #285

* test: add coverage for Rocket input validation exceptions

* MNT: fix lint formatting and skip UnstableRocketWarning for GenericSurface

black/ruff reformat the multi-name exception imports in rocketpy/__init__.py
and rocketpy/rocket/rocket.py.

evaluate_center_of_pressure ignores GenericSurface lift coefficients, so the
computed static margin does not reflect rockets that rely on them. Skip the
UnstableRocketWarning in that case to avoid false positives, echoing the
concern raised in the review of #764 that blocked a similar check.

* DOC: add changelog entry for PR #970

---------

Co-authored-by: Gui-FernandesBR <guilherme_fernandes@usp.br>

Author: Matanski

CHANGELOG.md

@@ -32,6 +32,7 @@ Attention: The newest changes should be on top -->
 
 ### Added
 
+- ENH: Add custom exceptions and unstable rocket warning [#970](https://github.com/RocketPy-Team/RocketPy/pull/970)
 - ENH: MNT: Remove redundant wind_heading/wind_direction functions from EnvironmentAnalysis [#1041](https://github.com/RocketPy-Team/RocketPy/pull/1041)
 - ENH: Pass acceleration (`u_dot`) data to parachute trigger functions [#911](https://github.com/RocketPy-Team/RocketPy/pull/911)
 - ENH: Add 3D flight trajectory and attitude animations in Flight plots layer [#909](https://github.com/RocketPy-Team/RocketPy/pull/909)

rocketpy/__init__.py

@@ -1,5 +1,10 @@
 from .control import _Controller
 from .environment import Environment, EnvironmentAnalysis
+from .exceptions import (
+    InvalidInertiaError,
+    InvalidParameterError,
+    UnstableRocketWarning,
+)
 from .mathutils import (
     Function,
     PiecewiseFunction,

rocketpy/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions and warnings for RocketPy."""
+
+
+class RocketPyError(Exception):
+    """Base class for all RocketPy exceptions."""
+
+
+class InvalidParameterError(RocketPyError, ValueError):
+    """Raised when a constructor parameter has an invalid value (e.g. negative
+    radius or mass)."""
+
+
+class InvalidInertiaError(RocketPyError, ValueError):
+    """Raised when the inertia tuple/list does not have the expected length."""
+
+
+class UnstableRocketWarning(UserWarning):
+    """Issued when the rocket's static margin is negative at motor ignition,
+    indicating an aerodynamically unstable configuration.
+
+    Not issued when the rocket has any ``GenericSurface`` aerodynamic
+    surfaces, since their lift coefficient derivative is not accounted for
+    in the center of pressure calculation, making the static margin
+    unreliable for this check in that case.
+    """

rocketpy/rocket/rocket.py

@@ -26,6 +26,11 @@
 from rocketpy.rocket.aero_surface.fins.free_form_fins import FreeFormFins
 from rocketpy.rocket.aero_surface.fins.trapezoidal_fin import TrapezoidalFin
 from rocketpy.rocket.aero_surface.generic_surface import GenericSurface
+from rocketpy.exceptions import (
+    InvalidInertiaError,
+    InvalidParameterError,
+    UnstableRocketWarning,
+)
 from rocketpy.rocket.components import Components
 from rocketpy.rocket.parachute import Parachute
 from rocketpy.tools import (
@@ -311,6 +316,22 @@ def __init__(  # pylint: disable=too-many-statements
                     + '"tail_to_nose" and "nose_to_tail".'
                 )
 
+        # Validate inputs
+        if not isinstance(radius, (int, float)) or radius <= 0:
+            raise InvalidParameterError(
+                f"Rocket radius must be a positive number, got {radius!r}."
+            )
+        if not isinstance(mass, (int, float)) or mass <= 0:
+            raise InvalidParameterError(
+                f"Rocket mass must be a positive number, got {mass!r}."
+            )
+        if not isinstance(inertia, (tuple, list)) or len(inertia) not in (3, 6):
+            raise InvalidInertiaError(
+                "Inertia must be a tuple or list with 3 components (I_11, I_22, I_33) "
+                "or 6 components (I_11, I_22, I_33, I_12, I_13, I_23), "
+                f"got length {len(inertia) if isinstance(inertia, (tuple, list)) else 'N/A'}."
+            )
+
         # Define rocket inertia attributes in SI units
         self.mass = mass
         inertia = (*inertia, 0, 0, 0) if len(inertia) == 3 else inertia
@@ -734,6 +755,26 @@ def evaluate_static_margin(self):
         self.static_margin.set_discrete(
             lower=0, upper=self.motor.burn_out_time, samples=200
         )
+        # Warn the user if the rocket is aerodynamically unstable at ignition.
+        # Skipped when GenericSurface instances are present: their lift
+        # coefficient derivative is not accounted for in
+        # evaluate_center_of_pressure, so the computed static margin does not
+        # reflect their contribution and cannot be trusted for this check.
+        has_generic_surface = any(
+            isinstance(aero_surface, GenericSurface)
+            for aero_surface, _position in self.aerodynamic_surfaces
+        )
+        if not has_generic_surface:
+            initial_static_margin = self.static_margin.get_value_opt(0)
+            if initial_static_margin < 0:
+                warnings.warn(
+                    f"The rocket has a negative static margin ({initial_static_margin:.2f} cal) "
+                    "at motor ignition (t=0), indicating an aerodynamically unstable "
+                    "configuration. Check the placement of fins and nose cone relative "
+                    "to the center of mass.",
+                    UnstableRocketWarning,
+                    stacklevel=2,
+                )
         return self.static_margin
 
     def evaluate_dry_inertias(self):

tests/unit/rocket/test_rocket.py

@@ -5,7 +5,12 @@
 import numpy as np
 import pytest
 
-from rocketpy import Function, NoseCone, Rocket, SolidMotor
+from rocketpy import Function, GenericSurface, NoseCone, Rocket, SolidMotor
+from rocketpy.exceptions import (
+    InvalidInertiaError,
+    InvalidParameterError,
+    UnstableRocketWarning,
+)
 from rocketpy.mathutils.vector_matrix import Vector
 from rocketpy.motors.empty_motor import EmptyMotor
 from rocketpy.motors.motor import Motor
@@ -835,3 +840,85 @@ def test_drag_input_types_supported_for_power_on_and_power_off(tmp_path):
 
         assert rocket.power_off_drag_7d(*query_point) == pytest.approx(expected)
         assert rocket.power_on_drag_7d(*query_point) == pytest.approx(expected)
+
+
+@pytest.mark.parametrize("radius", [-1, 0, -0.001])
+def test_rocket_invalid_radius_raises(radius):
+    """InvalidParameterError must be raised for non-positive radius values."""
+    with pytest.raises(InvalidParameterError, match="radius"):
+        Rocket(
+            radius=radius,
+            mass=10,
+            inertia=(0.1, 0.1, 0.01),
+            power_off_drag=0.3,
+            power_on_drag=0.3,
+            center_of_mass_without_motor=0,
+        )
+
+
+@pytest.mark.parametrize("mass", [-1, 0, -0.001])
+def test_rocket_invalid_mass_raises(mass):
+    """InvalidParameterError must be raised for non-positive mass values."""
+    with pytest.raises(InvalidParameterError, match="mass"):
+        Rocket(
+            radius=0.05,
+            mass=mass,
+            inertia=(0.1, 0.1, 0.01),
+            power_off_drag=0.3,
+            power_on_drag=0.3,
+            center_of_mass_without_motor=0,
+        )
+
+
+@pytest.mark.parametrize("inertia", [(0.1,), (0.1, 0.1), (0.1, 0.1, 0.01, 0.0, 0.0)])
+def test_rocket_invalid_inertia_length_raises(inertia):
+    """InvalidInertiaError must be raised when inertia tuple has wrong length."""
+    with pytest.raises(InvalidInertiaError):
+        Rocket(
+            radius=0.05,
+            mass=10,
+            inertia=inertia,
+            power_off_drag=0.3,
+            power_on_drag=0.3,
+            center_of_mass_without_motor=0,
+        )
+
+
+def test_unstable_rocket_warning_raised(calisto):
+    """UnstableRocketWarning must be raised when the static margin at motor
+    ignition is negative."""
+    nose = NoseCone(
+        length=0.55829,
+        kind="vonkarman",
+        base_radius=0.0635,
+        rocket_radius=0.0635,
+        name="Nose Cone",
+    )
+    with pytest.warns(UnstableRocketWarning):
+        calisto.add_surfaces(nose, 1.16)
+    assert calisto.static_margin(0) < 0
+
+
+def test_unstable_rocket_warning_skipped_with_generic_surface(calisto):
+    """UnstableRocketWarning must not be raised when the rocket has a
+    GenericSurface, since its lift coefficient derivative is not accounted
+    for in the center of pressure calculation, making the static margin
+    unreliable for this check."""
+    nose = NoseCone(
+        length=0.55829,
+        kind="vonkarman",
+        base_radius=0.0635,
+        rocket_radius=0.0635,
+        name="Nose Cone",
+    )
+    generic_surface = GenericSurface(
+        reference_area=None,
+        reference_length=None,
+        coefficients={
+            "cL": lambda alpha, beta, mach, reynolds, pitch_rate, yaw_rate, roll_rate: 1
+        },
+    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", UnstableRocketWarning)
+        calisto.add_surfaces([nose, generic_surface], [1.16, 0])
+    assert calisto.static_margin(0) < 0