Removed Flight.compare wrapper to fix circular imports, updated docs and tests accordingly

Author: Monta120

docs/user/compare_flights.rst

@@ -1,7 +1,11 @@
 Flight Comparator
 =================
 
-This example demonstrates how to use the RocketPy ``FlightComparator`` class.
+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:
@@ -97,14 +101,38 @@ First, let's create the standard RocketPy simulation that will serve as our
        position=-1.194656,
    )
 
-   # 4. Simulate
-   flight = Flight(
-       rocket=calisto,
-       environment=env,
-       rail_length=5.2,
-       inclination=85,
-       heading=0,
-   )
+    # 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)
 ------------------------------
@@ -116,4 +144,40 @@ are either:
 - A RocketPy ``Function`` object, or
 - A tuple of ``(time_array, data_array)``.
 
-In this example, external data is generated synthetically, but in practice you
+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")

rocketpy/simulation/flight.py

@@ -3958,36 +3958,3 @@ def __lt__(self, other):
                     otherwise.
                 """
                 return self.t < other.t
-
-    def compare(self, data, variable="z", label="External Data"): # pylint: disable=import-outside-toplevel)
-        """
-        Compares the simulated flight against provided external data.
-
-        This is a convenience wrapper for the FlightComparator class.
-
-        Parameters
-        ----------
-        data : dict
-            Dictionary containing the external data.
-            Keys should be variables (e.g. 'z', 'vz') and values should be
-            (time_array, data_array) tuples or RocketPy Functions.
-        variable : str, optional
-            The variable to compare immediately. Default is "z" (Altitude).
-        label : str, optional
-            Legend label for the external data. Default is "External Data".
-
-        Returns
-        -------
-        FlightComparator
-            The comparator object, allowing for further comparisons.
-        """
-
-        from rocketpy.simulation.flight_comparator import (
-            FlightComparator,
-        )  
-
-        comparator = FlightComparator(self)
-        comparator.add_data(label=label, data_dict=data)
-        comparator.compare(variable)
-
-        return comparator

rocketpy/simulation/flight_comparator.py

@@ -4,6 +4,7 @@
 import numpy as np
 
 from rocketpy.mathutils import Function
+from rocketpy.simulation.flight import Flight
 from rocketpy.simulation.flight_data_importer import FlightDataImporter
 
 from ..plots.plot_helpers import show_or_save_fig
@@ -15,7 +16,9 @@ class FlightComparator:
     (such as flight logs, OpenRocket simulations, RASAero).
 
     This class handles the time-interpolation required to compare datasets
-    recorded at different frequencies.
+    recorded at different frequencies, and computes error metrics (RMSE, MAE, etc.)
+    between your RocketPy simulation and external or reference data.
+
 
     Parameters
     ----------
@@ -35,15 +38,20 @@ class FlightComparator:
 
     .. code-block:: python
 
-        # Assuming you have a Flight object named 'my_flight'
+        from rocketpy.simulation import FlightComparator
+
+        # Suppose you have a Flight object named 'my_flight'
         comparator = FlightComparator(my_flight)
 
-        # Add external data
+        # Add external data (e.g., from OpenRocket or logs)
         comparator.add_data('OpenRocket', {
             'altitude': (time_array, altitude_array),
             'vz': (time_array, velocity_array)
         })
 
+        # You can also add another RocketPy Flight directly:
+        comparator.add_data('OtherSimulation', other_flight)
+
         # Run comparisons
         comparator.compare('altitude')
         comparator.summary()
@@ -52,7 +60,7 @@ class FlightComparator:
 
     DEFAULT_GRID_POINTS = 1000  # number of points for interpolation grids
 
-    def __init__(self, flight):
+    def __init__(self, flight: Flight):
         """
         Initialize the comparator with a reference RocketPy Flight.
 
@@ -65,19 +73,19 @@ def __init__(self, flight):
         -------
         None
         """
-        # Minimal duck-typed validation to give clear errors early
+        # Duck-typed validation gives clear errors for Flight-like objects, more flexible than an isinstance check
         required_attrs = ("t_final", "apogee", "apogee_time", "impact_velocity")
         missing = [attr for attr in required_attrs if not hasattr(flight, attr)]
         if missing:
             raise TypeError(
-                "flight must be a rocketpy.Flight-like object with attributes "
+                "flight must be a rocketpy.Flight or Flight-like object with attributes "
                 f"{required_attrs}. Missing: {', '.join(missing)}"
             )
 
         self.flight = flight
         self.data_sources = {}  # The format is {'Source Name': {'variable': Function}}
 
-    def add_data(self, label, data_dict):  # pylint: disable=too-many-statements,import-outside-toplevel,cyclic-import
+    def add_data(self, label, data_dict):  # pylint: disable=too-many-statements
         """
         Add an external dataset to the comparator.
 
@@ -102,9 +110,8 @@ def add_data(self, label, data_dict):  # pylint: disable=too-many-statements,imp
             if present.
         """
 
-        from rocketpy.simulation.flight import (
-            Flight,  
-        )
+        if isinstance(data_dict, dict) and not data_dict:
+            raise ValueError("data_dict cannot be empty")
 
         processed_data = {}
 
@@ -197,45 +204,9 @@ def add_data(self, label, data_dict):  # pylint: disable=too-many-statements,imp
                 "or FlightDataImporter object."
             )
 
-        self.data_sources[label] = processed_data
-        print(
-            f"Added data source '{label}' with variables: {list(processed_data.keys())}"
-        )
-        # If this is not a dict (e.g., a Flight or FlightDataImporter), we're done.
-        if not isinstance(data_dict, dict):
-            return
-
-        # Check if label already exists
         if label in self.data_sources:
             warnings.warn(f"Data source '{label}' already exists. Overwriting.")
 
-        # Making sure that data_dict is not empty
-        if not data_dict:
-            raise ValueError("data_dict cannot be empty")
-
-        processed_data = {}
-
-        for key, value in data_dict.items():
-            # If already a Function, store it
-            if isinstance(value, Function):
-                processed_data[key] = value
-
-            # If raw data, convert to a function
-            elif isinstance(value, (tuple, list)) and len(value) == 2:
-                time_arr, data_arr = value
-                # Creating a Function for automatic interpolation
-                processed_data[key] = Function(
-                    np.column_stack((time_arr, data_arr)),
-                    inputs="Time (s)",
-                    outputs=key,
-                    interpolation="linear",
-                )
-            else:
-                warnings.warn(
-                    f"Skipping '{key}' in '{label}'. Format not recognized. "
-                    "Expected RocketPy Function or (time, data) tuple."
-                )
-
         self.data_sources[label] = processed_data
         print(
             f"Added data source '{label}' with variables: {list(processed_data.keys())}"

tests/integration/simulation/test_flight_comparator_workflow.py

@@ -90,18 +90,3 @@ def test_full_workflow_with_importer(flight_calisto, tmp_path):
     assert isinstance(results, dict)
     assert "Apogee Altitude (m)" in results
     assert "Impact Velocity (m/s)" in results
-
-
-def test_flight_compare_helper(flight_calisto):
-    """Test Flight.compare() convenience wrapper."""
-    time_data = np.linspace(0, flight_calisto.t_final, 100)
-    external = {
-        "z": (time_data, flight_calisto.z(time_data) + 5.0),
-        "vz": (time_data, flight_calisto.vz(time_data)),
-    }
-
-    comparator = flight_calisto.compare(external, variable="z", label="External")
-
-    assert isinstance(comparator, FlightComparator)
-    assert "External" in comparator.data_sources
-    assert "z" in comparator.data_sources["External"]