feat(simint-alpha): dev experience of simulation run data (#2158)

Co-authored-by: Ivan Polomani <ivan.polomanyi@cognite.com>

Author: evertoncolling

cognite/client/data_classes/simulators/runs.py

@@ -17,9 +17,13 @@
 )
 from cognite.client.data_classes.simulators.logs import SimulatorLog
 from cognite.client.utils._experimental import FeaturePreviewWarning
+from cognite.client.utils._importing import local_import
 from cognite.client.utils._retry import Backoff
+from cognite.client.utils._text import to_snake_case
 
 if TYPE_CHECKING:
+    import pandas
+
     from cognite.client import CogniteClient
 
 _WARNING = FeaturePreviewWarning(api_maturity="General Availability", sdk_maturity="alpha", feature_name="Simulators")
@@ -236,6 +240,18 @@ def get_logs(self) -> SimulatorLog | None:
         """
         return self._cognite_client.simulators.logs.retrieve(id=self.log_id)
 
+    def get_data(self) -> SimulationRunDataItem | None:
+        """`Retrieve data associated with this simulation run. <https://developer.cognite.com/api#tag/Simulation-Runs/operation/simulation_data_by_run_id_simulators_runs_data_list_post>`_
+
+        Returns:
+            SimulationRunDataItem | None: Data for the simulation run.
+        """
+        data = self._cognite_client.simulators.runs.list_run_data(run_id=self.id)
+        if data:
+            return data[0]
+
+        return None
+
     def update(self) -> None:
         """Update the simulation run object to the latest state. Useful if the run was created with wait=False."""
         # same logic as Cognite Functions
@@ -424,10 +440,56 @@ def dump(self, camel_case: bool = True) -> dict[str, Any]:
         output["outputs"] = [output_.dump(camel_case=camel_case) for output_ in self.outputs]
         return output
 
+    def to_pandas(  # type: ignore [override]
+        self,
+    ) -> pandas.DataFrame:
+        """Convert the simulation run data to a pandas DataFrame.
+
+        Returns:
+            pandas.DataFrame: The dataframe.
+        """
+        pd = local_import("pandas")
+
+        def _create_row(item: SimulationInput | SimulationOutput) -> dict:
+            """Create a row dictionary for an input or output item."""
+            item_type = (isinstance(item, SimulationInput) and "Input") or "Output"
+            row = {
+                "run_id": self.run_id,
+                "type": item_type,
+                "reference_id": item.reference_id,
+                "value": item.value,
+                "unit_name": item.unit.name if item.unit else None,
+                "value_type": item.value_type,
+                "overridden": getattr(item, "overridden", None),
+                "timeseries_external_id": item.timeseries_external_id,
+            }
+
+            if item.simulator_object_reference:
+                for reference_key, reference_value in item.simulator_object_reference.items():
+                    snake_key = to_snake_case(reference_key)
+                    row[snake_key] = reference_value
+
+            return row
+
+        rows = [_create_row(item) for item in self.inputs + self.outputs]
+
+        return pd.DataFrame(rows)
+
 
 class SimulatorRunDataList(CogniteResourceList[SimulationRunDataItem], IdTransformerMixin):
     _RESOURCE = SimulationRunDataItem
 
+    def to_pandas(  # type: ignore [override]
+        self,
+    ) -> pandas.DataFrame:
+        """Convert the simulation run data list to a pandas DataFrame.
+
+        Returns:
+            pandas.DataFrame: The dataframe.
+        """
+        pd = local_import("pandas")
+        return pd.concat([item.to_pandas() for item in self.data], ignore_index=True)
+
 
 class SimulationRunWriteList(CogniteResourceList[SimulationRunWrite], ExternalIDTransformerMixin):
     _RESOURCE = SimulationRunWrite

tests/tests_integration/test_api/test_simulators/test_runs.py

@@ -99,6 +99,11 @@ async def test_run_with_wait_and_retrieve(self, cognite_client: CogniteClient, s
         assert logs_res is not None
         assert logs_res.dump() == logs_res2.dump()
 
+        data_res = retrieved_run.get_data()
+        data_res2 = cognite_client.simulators.runs.list_run_data(run_id=created_run.id)[0]
+        assert data_res is not None
+        assert data_res.dump() == data_res2.dump()
+
     def test_create_run(
         self, cognite_client: CogniteClient, seed_simulator_routine_revisions, seed_resource_names
     ) -> None:

tests/tests_unit/test_api/test_simulators/test_run_data.py

@@ -0,0 +1,102 @@
+import pytest
+
+from cognite.client.data_classes.simulators.runs import (
+    SimulationInput,
+    SimulationOutput,
+    SimulationRunDataItem,
+    SimulationValueUnitName,
+)
+
+
+@pytest.mark.dsl
+class TestSimulationRunDataItemPandasIntegration:
+    def test_to_pandas(self):
+        import pandas as pd
+
+        # Create sample data
+        unit = SimulationValueUnitName(name="C")
+        inputs = [
+            SimulationInput(
+                reference_id="CWT",
+                value=11.0,
+                value_type="DOUBLE",
+                overridden=True,
+                unit=unit,
+            ),
+            SimulationInput(
+                reference_id="CWP",
+                value=[5.0],
+                value_type="DOUBLE_ARRAY",
+                overridden=True,
+                unit=SimulationValueUnitName(name="bar"),
+            ),
+        ]
+        outputs = [
+            SimulationOutput(
+                reference_id="ST",
+                simulator_object_reference={"address": "test_out"},
+                value=18.5,
+                value_type="DOUBLE",
+                unit=unit,
+            )
+        ]
+
+        # Create the SimulationRunDataItem
+        data_item = SimulationRunDataItem(run_id=123, inputs=inputs, outputs=outputs)
+
+        # Convert to pandas DataFrame
+        df = data_item.to_pandas()
+
+        # Assertions
+        assert isinstance(df, pd.DataFrame)
+        assert df.shape == (3, 9)  # 3 rows (2 inputs + 1 output), 9 columns
+
+        # Check that the data is correctly formatted
+        assert list(df.columns) == [
+            "run_id",
+            "type",
+            "reference_id",
+            "value",
+            "unit_name",
+            "value_type",
+            "overridden",
+            "timeseries_external_id",
+            "address",
+        ]
+
+        expected_data_rows = [
+            {
+                "run_id": 123,
+                "type": "Input",
+                "reference_id": "CWT",
+                "value": 11.0,
+                "unit_name": "C",
+                "value_type": "DOUBLE",
+                "overridden": True,
+                "timeseries_external_id": None,
+            },
+            {
+                "run_id": 123,
+                "type": "Input",
+                "reference_id": "CWP",
+                "value": [5.0],
+                "unit_name": "bar",
+                "value_type": "DOUBLE_ARRAY",
+                "overridden": True,
+                "timeseries_external_id": None,
+            },
+            {
+                "run_id": 123,
+                "type": "Output",
+                "reference_id": "ST",
+                "value": 18.5,
+                "unit_name": "C",
+                "value_type": "DOUBLE",
+                "overridden": None,
+                "timeseries_external_id": None,
+                "address": "test_out",
+            },
+        ]
+
+        expected_df = pd.DataFrame(expected_data_rows)
+        pd.testing.assert_frame_equal(df, expected_df)