Merge branch 'develop' into copilot/enhance-drag-curve-functionality

Author: aZira371

CHANGELOG.md

@@ -34,20 +34,25 @@ Attention: The newest changes should be on top -->
 
 - 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)
-- ENH: Add thrustcurve api integration to retrieve motor eng data [#870](https://github.com/RocketPy-Team/RocketPy/pull/870)
-- ENH: custom warning no motor or aerosurface [#871](https://github.com/RocketPy-Team/RocketPy/pull/871)
 
 ### Changed
 
 -
 
 ### Fixed
 
-- BUG: Fix parallel Monte Carlo simulation showing incorrect iteration count [#806](https://github.com/RocketPy-Team/RocketPy/pull/806)
 - 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

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/motors/liquidmotor.rst

@@ -160,6 +160,21 @@ For example:
 
   example_liquid.exhaust_velocity.plot(0, 5)
 
+The tanks added to a ``LiquidMotor`` can now be animated to visualize
+how the liquid and gas volumes evolve during the burn.
+
+To animate the tanks, we can use the ``animate_fluid_volume()`` method:
+
+.. jupyter-execute::
+
+  example_liquid.animate_fluid_volume(fps=30)
+
+Optionally, the animation can be saved to a GIF file:
+
+.. jupyter-execute::
+
+  example_liquid.animate_fluid_volume(fps=30, save_as="liquid_motor.gif")
+
 Alternatively, you can plot all the information at once:
 
 .. jupyter-execute::

docs/user/motors/tanks.rst

@@ -263,6 +263,21 @@ We can see some outputs with:
   # Evolution of the Propellant center of mass position
   N2O_mass_tank.center_of_mass.plot()
 
+All tank types now include a built-in method for animating the evolution
+of liquid and gas volumes over time. This visualization aids in understanding the dynamic behavior
+of the tank's contents. To animate the tanks, we can use the 
+``animate_fluid_volume()`` method:
+
+.. jupyter-execute::
+
+  N2O_mass_tank.animate_fluid_volume(fps=30)
+
+Optionally, the animation can be saved to a GIF file:
+
+.. jupyter-execute::
+
+  N2O_mass_tank.animate_fluid_volume(fps=30, save_as="mass_based_tank.gif")
+
 
 Ullage Based Tank
 -----------------

docs/user/mrs.rst

@@ -204,6 +204,37 @@ Finally, we can compare the ellipses for the apogees and landing points using th
 Note we can pass along parameters used in the usual `ellipses` method of the 
 `MonteCarlo` class, in this case the `ylim` argument to expand the y-axis limits.
 
+
+Calculating Confidence Intervals
+--------------------------------
+
+Beyond visual comparisons, you may want to calculate statistical confidence intervals
+for specific attributes of the flight (e.g., apogee, max velocity) based on the
+resampled data. Since the resulting data is loaded into a ``MonteCarlo`` object,
+you can use its method to compute these intervals using the bootstrap method.
+
+The following example shows how to calculate the 95% confidence interval for the
+mean of the apogee using the ``mrs_results`` object created earlier:
+
+.. jupyter-execute::
+
+    # Calculate the 95% Confidence Interval for the mean apogee
+    # We pass np.mean as the statistic to be evaluated
+    apogee_ci = mrs_results.calculate_confidence_interval(
+        attribute="apogee",
+        statistic=np.mean,
+        confidence_level=0.95,
+        n_resamples=10000
+    )
+
+    print(f"95% Confidence Interval for Apogee Mean: {apogee_ci}")
+
+You can use any statistic function that accepts an array of data, such as ``np.median``
+or ``np.std``.
+
+
+
+
 Time Comparison
 ---------------