Feature/cluster motor structure

[ayoubdsp]

Pull request type

• Code changes (bugfix, features)
• Code maintenance (refactoring, formatting, tests)

Checklist

• Tests for the changes have been added (if needed)
• Docs have been reviewed and added / updated
• Lint (black rocketpy/ tests/) has passed locally
• All tests (pytest tests/integration/motors/test_cluster_motor.py) have passed locally
• CHANGELOG.md has been updated (if relevant)

Current behavior

Currently, RocketPy does not have native support for clustered motor configurations.
Users attempting to simulate a cluster (e.g., 3x or 4x motors) must manually create a "custom" single motor with scaled thrust curves and manually calculate the complex inertia changes caused by the off-axis mass distribution using external tools. This process is error-prone and does not dynamically update the inertia tensor correctly as propellant is consumed.

New behavior

This PR introduces a new ClusterMotor class in rocketpy.motors.

• Wrapper Architecture: It wraps an existing SolidMotor object, preserving all its internal ballistics.
• Automatic Scaling: Thrust, Dry Mass, and Propellant Mass are automatically scaled by the number of motors ().
• Physics-Based Inertia: The class implements the Parallel Axis Theorem (Huygens-Steiner) to correctly calculate the global inertia tensor of the cluster. It accounts for the radial distance () of the motors from the central axis, dynamically updating (Pitch/Yaw) and (Roll) as the propellant mass decreases during the burn.

Breaking change

• No

To do

Once implementation has been validated, we will still need to improve the draw() function to enable the drawing of grouped projects. For now, I have only implemented a rear view, so that the placement of the engines is visible.

This feature was developed by the French rocket science association IPSA SPACE SYSTEMS. Come say hello to us on Instagram!
https://www.instagram.com/ipsa_space_systems/

[Copilot]

Pull request overview

Adds a new ClusterMotor implementation to RocketPy, intended to model a symmetric cluster of identical motors by aggregating thrust, mass, and inertia (including parallel-axis/Steiner corrections), with accompanying integration tests.

Changes:

• Introduces rocketpy.motors.cluster_motor.ClusterMotor (new motor type built on top of Motor).
• Implements cluster-scaled thrust/mass/inertia behavior plus a simple cluster layout plotting helper.
• Adds integration tests validating basic scaling and Steiner-theorem inertia expectations.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
rocketpy/motors/cluster_motor.py	New ClusterMotor class that aggregates an underlying motor’s properties for clustered configurations.
tests/integration/motors/test_cluster_motor.py	New integration tests for cluster initialization, scaling, and inertia calculations.

---

You can also share your feedback on Copilot code review. Take the survey.

[codecov]

Codecov Report

❌ Patch coverage is 88.54167% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.39%. Comparing base (9cf3dd4) to head (d3af016).
⚠️ Report is 95 commits behind head on develop.

Files with missing lines	Patch %	Lines
rocketpy/motors/ring_cluster_motor.py	90.06%	16 Missing ⚠️
rocketpy/plots/rocket_plots.py	80.00%	6 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #924      +/-   ##
===========================================
+ Coverage    80.27%   81.39%   +1.12%     
===========================================
  Files          104      115      +11     
  Lines        12769    15028    +2259     
===========================================
+ Hits         10250    12232    +1982     
- Misses        2519     2796     +277     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[MateusStano]

This is really good! Just requested a few changes and it should be good to merge

[ayoubdsp]

Hi @MateusStano, thanks for the great feedback! You were spot on about the inertia calculations.I've renamed the class to RingClusterMotor and updated the docstrings to make it clear that this specifically models an annular configuration without a central motor.To fix the issue with the $N=2$ case, I completely removed the N/2 approximation. Instead, the code now calculates the exact geometric summation using the true $x$ and $y$ coordinates of each motor. This ensures the transverse inertias are perfectly accurate and naturally asymmetric when there are only two motors, while staying mathematically consistent for larger clusters.Finally, I updated the test suite to validate this exact math and fixed that np.isclose ValueError we were getting by making sure the Function objects are properly evaluated at a given time $t$. All tests are now passing smoothly!Let me know if everything looks good to merge !

[Gui-FernandesBR]

Implemented one pending merge-readiness item on this PR:\n\n- updated CHANGELOG.md with an Unreleased entry for RingClusterMotor (#924).\n\nCommit: �d10a942\n\n@MateusStano could you please take a final look so we can move this to merge?

[Gui-FernandesBR]

Update: I rebased eature/cluster-motor-structure onto current develop and resolved conflicts to keep the PR merge-ready.\n\nAdditional adjustments included in this update:\n- added CHANGELOG.md Unreleased entry for RingClusterMotor (#924)\n- fixed post-rebase plotting imports/type dispatch in
ocketpy/plots/rocket_plots.py\n\nValidation run locally:\n- pytest tests/integration/motors/test_ring_cluster_motor.py -q\n- pytest tests/unit/test_plots.py -q\n-
uff check rocketpy/plots/rocket_plots.py rocketpy/motors/ring_cluster_motor.py tests/integration/motors/test_ring_cluster_motor.py\n\nLatest branch head: 378ec7c.\n\n@MateusStano could you please re-review for merge?

[Gui-FernandesBR]

gotta update documentation and also make a few tests to ensure it's working.

[Gui-FernandesBR]

Sorry for the long wait @ayoubdsp . Thank you so much for your great work, it still impresses me a lot. Awesome!