Merge branch 'develop' into copilot/implement-3dof-acceptance-test

Author: aZira371

.pylintrc

@@ -229,6 +229,7 @@ good-names=FlightPhases,
            center_of_mass_without_motor_to_CDM,
            motor_center_of_dry_mass_to_CDM,
            generic_motor_cesaroni_M1520,
+           Re, # Reynolds number
 
 # Good variable names regexes, separated by a comma. If names match any regex,
 # they will always be accepted

.vscode/settings.json

@@ -241,6 +241,7 @@
         "outerboundaryis",
         "overshootable",
         "planform",
+        "pointmassmotor",
         "polystyle",
         "powerseries",
         "Prandtl",

CHANGELOG.md

@@ -32,10 +32,31 @@ Attention: The newest changes should be on top -->
 
 ### Added
 
+- MNT: net thrust addition to 3 dof in flight class [#907] (https://github.com/RocketPy-Team/RocketPy/pull/907)
+- ENH: 3-dof lateral motion improvement [#883](https://github.com/RocketPy-Team/RocketPy/pull/883)
+- ENH: Add multi-dimensional drag coefficient support (Cd as function of M, Re, α) [#875](https://github.com/RocketPy-Team/RocketPy/pull/875)
+- ENH: Add save functionality to `_MonteCarloPlots.all` method [#848](https://github.com/RocketPy-Team/RocketPy/pull/848)
+- ENH: add animations for motor propellant mass and tank fluid volumes [#894](https://github.com/RocketPy-Team/RocketPy/pull/894)
+- ENH: Rail button bending moments calculation in Flight class [#893](https://github.com/RocketPy-Team/RocketPy/pull/893)
+- ENH: Implement Bootstrapping for Confidence Interval Estimation [#891](https://github.com/RocketPy-Team/RocketPy/pull/897)
+- ENH: Built-in flight comparison tool (`FlightComparator`) to validate simulations against external data [#888](https://github.com/RocketPy-Team/RocketPy/pull/888)
+- ENH: Add persistent caching for ThrustCurve API [#881](https://github.com/RocketPy-Team/RocketPy/pull/881)
+- ENH: Add axial_acceleration attribute to the Flight class [#876](https://github.com/RocketPy-Team/RocketPy/pull/876)
+- ENH: custom warning no motor or aerosurface [#871](https://github.com/RocketPy-Team/RocketPy/pull/871)
+- ENH: Add thrustcurve api integration to retrieve motor eng data [#870](https://github.com/RocketPy-Team/RocketPy/pull/870)
+- ENH: Compatibility with MERRA-2 atmosphere reanalysis files [#825](https://github.com/RocketPy-Team/RocketPy/pull/825)
+- ENH: Enable only radial burning [#815](https://github.com/RocketPy-Team/RocketPy/pull/815)
+
 ### Changed
 
+-
+
 ### Fixed
 
+- BUG: energy_data plot not working for 3 dof sims [[#906](https://github.com/RocketPy-Team/RocketPy/issues/906)]
+- BUG: Fix CSV column header spacing in FlightDataExporter [#864](https://github.com/RocketPy-Team/RocketPy/issues/864)
+- BUG: Fix parallel Monte Carlo simulation showing incorrect iteration count [#806](https://github.com/RocketPy-Team/RocketPy/pull/806)
+
 
 ## [v1.11.0] - 2025-11-01
 
@@ -71,6 +92,7 @@ Attention: The newest changes should be on top -->
 ## [v1.10.0] - 2025-05-16
 
 ### Added
+
 - ENH: Support for ND arithmetic in Function class. [#810] (https://github.com/RocketPy-Team/RocketPy/pull/810)
 - ENH: allow users to provide custom samplers [#803](https://github.com/RocketPy-Team/RocketPy/pull/803)
 - ENH: Implement Multivariate Rejection Sampling (MRS) [#738] (https://github.com/RocketPy-Team/RocketPy/pull/738)

docs/user/environment/1-atm-models/reanalysis.rst

@@ -46,6 +46,27 @@ ERA5 data can be downloaded from the
     processed by RocketPy. It is recommended that you download only the \
     necessary data.
 
+MERRA-2
+-------
+
+The Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) is a NASA atmospheric reanalysis for the satellite era using the Goddard Earth Observing System, Version 5 (GEOS-5) with its Atmospheric Data Assimilation System (ADAS).
+
+You can download these files from the `NASA GES DISC <https://disc.gsfc.nasa.gov/>`_.
+
+To use MERRA-2 data in RocketPy, you generally need the **Assimilated Meteorological Fields** collection (specifically the 3D Pressure Level data, usually named ``inst3_3d_asm_Np``). Note that MERRA-2 files typically use the ``.nc4`` extension (NetCDF-4), which is fully supported by RocketPy.
+
+You can load these files using the ``dictionary="MERRA2"`` argument:
+
+.. code-block:: python
+
+    env.set_atmospheric_model(
+        type="Reanalysis",
+        file="MERRA2_400.inst3_3d_asm_Np.20230620.nc4",
+        dictionary="MERRA2"
+    )
+
+RocketPy automatically handles the unit conversion for MERRA-2's surface geopotential (energy) to geometric height (meters).
+
 
 Setting the Environment
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/user/environment/1-atm-models/standard_atmosphere.rst

@@ -22,8 +22,7 @@ Other profiles can be derived from it, however, winds are automatically set to
 
     env.plots.atmospheric_model()
 
-.. skip one line with |
-| 
+|
 
 The International Standard Atmosphere can also be reset at any time by using the
 :meth:`rocketpy.Environment.set_atmospheric_model` method. For example:

docs/user/first_simulation.rst

@@ -90,6 +90,7 @@ regarding the launch site:
 
 | This roughly corresponds to the location of Spaceport America, New Mexico.
 
+
 Next, we need to specify the atmospheric model to be used. In this example,
 we will get GFS forecasts data from tomorrow.
 
@@ -110,6 +111,7 @@ of tomorrow:
 
 | Now we set the atmospheric model to be used:
 
+
 .. jupyter-execute::
 
     env.set_atmospheric_model(type="Forecast", file="GFS")
@@ -189,6 +191,7 @@ to specify several parameters:
 
 | We can see its characteristics by calling the info method:
 
+
 .. jupyter-execute::
 
     Pro75M1670.info()
@@ -637,8 +640,9 @@ and the rocket Mach number (see :meth:`rocketpy.Flight.mach_number`) to the file
     )
 
 | As you can see, the first argument is the file name to be created. The following
-arguments are the attributes to be exported. We can check the file by reading it
-with :func:`pandas.read_csv`:
+  arguments are the attributes to be exported. We can check the file by reading it
+  with :func:`pandas.read_csv`:
+
 
 .. jupyter-execute::
 
@@ -647,8 +651,9 @@ with :func:`pandas.read_csv`:
     pd.read_csv("calisto_flight_data.csv")
 
 | The file header specifies the meaning of each column. The time samples are
-obtained from the simulation solver steps. To export the data at a different
-sampling rate, use the ``time_step`` argument:
+  obtained from the simulation solver steps. To export the data at a different
+  sampling rate, use the ``time_step`` argument:
+
 
 .. jupyter-execute::
 

docs/user/flight.rst

@@ -266,6 +266,39 @@ The Flight object provides access to all forces and accelerations acting on the
     M2 = flight.M2                   # Pitch moment
     M3 = flight.M3                   # Yaw moment
 
+Rail Button Forces and Bending Moments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+During the rail launch phase, RocketPy calculates reaction forces and internal bending moments at the rail button attachment points:
+
+**Rail Button Forces (N):**
+
+- ``rail_button1_normal_force`` : Normal reaction force at upper rail button
+- ``rail_button1_shear_force`` : Shear (tangential) reaction force at upper rail button  
+- ``rail_button2_normal_force`` : Normal reaction force at lower rail button
+- ``rail_button2_shear_force`` : Shear (tangential) reaction force at lower rail button
+
+**Rail Button Bending Moments (N⋅m):**
+
+- ``rail_button1_bending_moment`` : Time-dependent bending moment at upper rail button attachment
+- ``max_rail_button1_bending_moment`` : Maximum absolute bending moment at upper rail button
+- ``rail_button2_bending_moment`` : Time-dependent bending moment at lower rail button attachment  
+- ``max_rail_button2_bending_moment`` : Maximum absolute bending moment at lower rail button
+
+**Calculation Method:**
+
+Bending moments are calculated using beam theory assuming simple supports (rail buttons provide reaction forces but no moment reaction at rail contact). The total moment combines:
+
+1. Shear force × button height (cantilever moment from button standoff)
+2. Normal force × distance to center of dry mass (lever arm effect)
+
+Moments are zero after rail departure and represent internal structural loads for airframe and fastener stress analysis. Requires ``button_height`` to be defined when adding rail buttons via ``rocket.set_rail_buttons()``.
+
+.. note::
+   See Issue #893 for implementation details and validation approach.
+
+
+
 Attitude and Orientation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/user/flight_comparator.rst

@@ -0,0 +1,183 @@
+Flight Comparator
+=================
+
+This example demonstrates how to use the RocketPy ``FlightComparator`` class to
+compare a Flight simulation against external data sources.
+
+Users must explicitly create a `FlightComparator` instance.
+
+
+This class is designed to compare a RocketPy Flight simulation against external
+data sources, such as:
+
+- Real flight data (avionics logs, altimeter CSVs)
+- Simulations from other software (OpenRocket, RASAero)
+- Theoretical models or manual calculations
+
+Unlike ``CompareFlights`` (which compares multiple RocketPy simulations),
+``FlightComparator`` specifically handles the challenge of aligning different
+time steps and calculating error metrics (RMSE, MAE, etc.) between a
+"Reference" simulation and "External" data.
+
+Importing classes
+-----------------
+
+We will start by importing the necessary classes and modules:
+
+.. jupyter-execute::
+
+   import numpy as np
+
+   from rocketpy import Environment, Rocket, SolidMotor, Flight
+   from rocketpy.simulation import FlightComparator, FlightDataImporter
+
+Create Simulation (Reference)
+-----------------------------
+
+First, let's create the standard RocketPy simulation that will serve as our
+"Ground Truth" or reference model. This follows the standard setup.
+
+.. jupyter-execute::
+
+   # 1. Setup Environment
+   env = Environment(
+       date=(2022, 10, 1, 12),
+       latitude=32.990254,
+       longitude=-106.974998,
+       elevation=1400,
+   )
+   env.set_atmospheric_model(type="standard_atmosphere")
+
+   # 2. Setup Motor
+   Pro75M1670 = SolidMotor(
+       thrust_source="../data/motors/cesaroni/Cesaroni_M1670.eng",
+       burn_time=3.9,
+       grain_number=5,
+       grain_density=1815,
+       grain_outer_radius=33 / 1000,
+       grain_initial_inner_radius=15 / 1000,
+       grain_initial_height=120 / 1000,
+       grain_separation=5 / 1000,
+       nozzle_radius=33 / 1000,
+       throat_radius=11 / 1000,
+       interpolation_method="linear",
+       coordinate_system_orientation="nozzle_to_combustion_chamber",
+       dry_mass=1.815,
+       dry_inertia=(0.125, 0.125, 0.002),
+       grains_center_of_mass_position=0.33,
+       center_of_dry_mass_position=0.317,
+       nozzle_position=0,
+   )
+
+   # 3. Setup Rocket
+   calisto = Rocket(
+       radius=127 / 2000,
+       mass=19.197 - 2.956,
+       inertia=(6.321, 6.321, 0.034),
+       power_off_drag="../data/calisto/powerOffDragCurve.csv",
+       power_on_drag="../data/calisto/powerOnDragCurve.csv",
+       center_of_mass_without_motor=0,
+       coordinate_system_orientation="tail_to_nose",
+   )
+
+   calisto.set_rail_buttons(0.0818, -0.618, 45)
+   calisto.add_motor(Pro75M1670, position=-1.255)
+
+   # Add aerodynamic surfaces
+   nosecone = calisto.add_nose(length=0.55829, kind="vonKarman", position=0.71971)
+   fin_set = calisto.add_trapezoidal_fins(
+       n=4,
+       root_chord=0.120,
+       tip_chord=0.040,
+       span=0.100,
+       position=-1.04956,
+       cant_angle=0.5,
+       airfoil=("../data/calisto/fins/NACA0012-radians.txt", "radians"),
+   )
+   tail = calisto.add_tail(
+       top_radius=0.0635,
+       bottom_radius=0.0435,
+       length=0.060,
+       position=-1.194656,
+   )
+
+    # 4. Simulate
+    flight = Flight(
+    rocket=calisto,
+    environment=env,
+    rail_length=5.2,
+    inclination=85,
+    heading=0,
+    )
+
+    # 5. Create FlightComparator instance
+    comparator = FlightComparator(flight)
+
+Adding Another Flight Object
+----------------------------
+
+You can compare against another RocketPy Flight simulation directly:
+
+.. jupyter-execute::
+
+    # Create a second simulation with slightly different parameters
+    flight2 = Flight(
+        rocket=calisto,
+        environment=env,
+        rail_length=5.0,  # Slightly shorter rail
+        inclination=85,
+        heading=0,
+    )
+
+    # Add the second flight directly
+    comparator.add_data("Alternative Sim", flight2)
+
+    print(f"Added variables from flight2: {list(comparator.data_sources['Alternative Sim'].keys())}")
+
+Importing External Data (dict)
+------------------------------
+
+The primary data format expected by ``FlightComparator.add_data`` is a dictionary
+where keys are variable names (e.g. ``"z"``, ``"vz"``, ``"altitude"``) and values
+are either:
+
+- A RocketPy ``Function`` object, or
+- A tuple of ``(time_array, data_array)``.
+
+Let's create some synthetic external data to compare against our reference
+simulation:
+
+.. jupyter-execute::
+
+    # Generate synthetic external data with realistic noise
+    time_external = np.linspace(0, flight.t_final, 80)  # Different time steps
+    external_altitude = flight.z(time_external) + np.random.normal(0, 3, 80)  # 3m noise
+    external_velocity = flight.vz(time_external) + np.random.normal(0, 0.5, 80)  # 0.5 m/s noise
+
+    # Add the external data to our comparator
+    comparator.add_data(
+        "External Simulator", 
+        {
+            "altitude": (time_external, external_altitude),
+            "vz": (time_external, external_velocity),
+        }
+    )
+
+Running Comparisons
+-------------------
+
+Now we can run the various comparison methods:
+
+.. jupyter-execute::
+
+    # Generate summary with key events
+    comparator.summary()
+
+    # Compare specific variable
+    comparator.compare("altitude")
+
+    # Compare all available variables
+    comparator.all()
+
+    # Plot 2D trajectory
+    comparator.trajectories_2d(plane="xz")

docs/user/index.rst

@@ -7,10 +7,11 @@ RocketPy's User Guide
 
    Installation and Requirements <installation.rst>
    First Simulation <first_simulation.rst>
+   3 DOF Simulations and Comparison <three_dof_simulation.rst>
 
 .. toctree::
    :maxdepth: 1
-   :caption: Main Classes Usage  
+   :caption: Main Classes Usage
 
    Positions and Coordinate Systems <positions.rst>
    Motors <motors/motors.rst>