ENH: Add multi-dimensional drag coefficient support (Cd as function of M, Re, α)

[Copilot]

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 -m slow --runslow) have passed locally
• CHANGELOG.md has been updated (if relevant)

Current behavior

Drag coefficients are limited to 1D functions of Mach number. CFD simulations typically produce drag data varying with Reynolds number and angle of attack, which cannot be properly represented.

New behavior

Drag coefficients now support N-dimensional structured grids via Function.from_grid(). Flight simulations automatically calculate and pass Reynolds number (from velocity, density, viscosity, rocket diameter) and angle of attack (from freestream velocity vectors in body frame) to multi-dimensional drag functions.

Implementation

Function Class (rocketpy/mathutils/function.py)

• Added from_grid() class method using scipy.interpolate.RegularGridInterpolator
• Added 'regular_grid' interpolation type with edge clamping (no extrapolation beyond bounds)
• Grid data stored as flattened array for serialization compatibility
• Added flatten_for_compatibility parameter to skip O(n^d) memory overhead for large grids when legacy code compatibility is not required
• Added warning when axes are not strictly sorted in ascending order

Flight Class (rocketpy/simulation/flight.py)

• Added __get_drag_coefficient() helper detecting function dimensionality (uses early return guard clause for cleaner code)
• Calculates Re = ρVD/μ and α from body-frame velocities during integration
• Updated udot_rail1(), u_dot(), u_dot_generalized() to use helper

Rocket Class (rocketpy/rocket/rocket.py)

• Preserves Function objects when passed as drag coefficients (previously wrapped in 1D Function)

Usage Example

import numpy as np
from rocketpy import Function, Rocket

# Create 3D drag data from CFD
mach = np.array([0.0, 0.5, 1.0, 1.5, 2.0])
reynolds = np.array([1e5, 5e5, 1e6])
alpha = np.array([0.0, 2.0, 4.0, 6.0])  # degrees

M, Re, A = np.meshgrid(mach, reynolds, alpha, indexing='ij')
cd_data = 0.3 + 0.1*M - 1e-7*Re + 0.01*A

# Create structured grid function
drag_func = Function.from_grid(
    cd_data, 
    [mach, reynolds, alpha],
    inputs=['Mach', 'Reynolds', 'Alpha'],
    outputs='Cd'
)

# Use directly in Rocket - Flight automatically handles M, Re, α
rocket = Rocket(..., power_off_drag=drag_func, power_on_drag=drag_func)

# For large grids, skip flattening to reduce memory usage
drag_func_optimized = Function.from_grid(
    cd_data, 
    [mach, reynolds, alpha],
    inputs=['Mach', 'Reynolds', 'Alpha'],
    outputs='Cd',
    flatten_for_compatibility=False  # Skip O(n^d) memory overhead
)

Testing

• 14 unit tests for Function.from_grid() covering 1D/2D/3D grids, extrapolation, validation, unsorted axis warnings, and memory optimization
• 5 integration tests for 3D drag in flight simulations
• All existing tests pass (full backward compatibility)

Breaking change

• No

Existing 1D drag curves (Mach only) work unchanged. Multi-dimensional support is opt-in via from_grid().

Additional information

Resolves #874

CodeQL security scan: 0 alerts

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[aZira371]

The code implementation is as I planned it to be done. There might be a slight edge case which should be addressed in regular grid interpolator unit tests or with warning: that the grid was not sorted in ascending order as intended. This can happen with repeated values in the grid. Apart from that the changes are okay to be merged! @Gui-FernandesBR @copilot

[aZira371]

@Gui-FernandesBR Is there a way to see this branch on VSC? I am unable to access it there. It is not being listed as a remote branch. I think one of the previous lint errors was related to the new grid method being too big in function.py. It should be ideally broken down into helper functions or pylint has to be disabled for it.

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
rocketpy/mathutils/function.py	83.78%	18 Missing ⚠️
rocketpy/simulation/flight.py	93.65%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #875      +/-   ##
===========================================
+ Coverage    80.27%   80.96%   +0.68%     
===========================================
  Files          104      107       +3     
  Lines        12769    13609     +840     
===========================================
+ Hits         10250    11018     +768     
- Misses        2519     2591      +72     

☔ View full report in Codecov by Sentry.
📢 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.

[aZira371]

The pull request is ready for review now. Pylint is failing due to a problem in .pylintrc, I am not sure if this file should be corrected in this PR or not as this is an unrelated error. Tests did pass locally on my end before merging from develop. @RocketPy-Team/code-owners will need help from you, because different tests are failing at different places - on github test_sensor failed but on local after merging develop test_environment failed.

[Copilot]

Pull request overview

This PR implements multi-dimensional drag coefficient support, allowing drag to vary with Mach number, Reynolds number, and angle of attack. This enhancement enables RocketPy users to utilize CFD simulation data that naturally depends on multiple flow parameters, significantly improving aerodynamic modeling accuracy.

Key changes:

• Added Function.from_grid() class method for creating N-dimensional structured grid interpolators using scipy.interpolate.RegularGridInterpolator
• Modified Flight class to automatically calculate Reynolds number and angle of attack during trajectory integration, passing these to multi-dimensional drag functions
• Updated Rocket class to preserve Function objects when provided directly as drag coefficients (backward compatible with existing 1D usage)

Reviewed changes

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

Show a summary per file

File	Description
rocketpy/mathutils/function.py	Adds from_grid() class method, linear_grid interpolation type, and __get_value_opt_grid() for structured grid evaluation with edge-clamping extrapolation
rocketpy/simulation/flight.py	Implements __get_drag_coefficient() helper to detect function dimensionality and calculate Re/α during integration; updates all u_dot methods
rocketpy/rocket/rocket.py	Preserves Function objects when passed as drag coefficients instead of wrapping them, enabling multi-dimensional drag
tests/unit/mathutils/test_function_grid.py	Comprehensive unit tests for grid interpolation (1D/2D/3D), extrapolation modes, validation, and fallback behavior
tests/integration/test_multidim_drag.py	Integration tests verifying 3D drag works in full flight simulations and maintains backward compatibility with 1D drag
.pylintrc	Adds 'Re' (Reynolds number) to accepted variable names

[Gui-FernandesBR]

• @MateusStano please review changes in the flight.py file
• @phmbressan please review changes in the function.py ile

Everything is looking good, @aZira371 great work here! I'm confortable with what has been done so far. I believe we can include this one on the next release.

---

@aZira371 could you please update changelog?

[aZira371]

Thanks for the review @Gui-FernandesBR will soon work on this and update the changelog.

[Gui-FernandesBR]

LGTM,

I'd like to request @MateusStano 's review here as well

[Copilot]

The code implementation is as I planned it to be done. There might be a slight edge case which should be addressed in regular grid interpolator unit tests or with warning: that the grid was not sorted...

Added warning for unsorted axes in commit 05ebb10. The from_grid() method now checks if each axis is strictly sorted in ascending order and issues a UserWarning if not. Added two new unit tests: test_from_grid_unsorted_axis_warns and test_from_grid_repeated_values_warns.

[Gui-FernandesBR]

LGTM.

It is a big change, I can't say everything is correct, but I prefer to deploy it to production so we let users report bugs if any.

Acceptance tests have passed so I'm ok with this.