feat(stats): add StatsAccessor.summary() headline KPI table

src/fluxopt/stats.py

@@ -100,3 +100,30 @@ def effect_contributions(self) -> xr.Dataset:
             self._result.data,
             self._result.solution,
         )
+
+    def summary(self) -> xr.Dataset:
+        """Headline KPIs overview.
+
+        Returns a tidy dataset with the objective value, total effects,
+        and per-flow full load hours.
+        """
+        import numpy as np
+        import xarray as xr
+
+        ds = xr.Dataset()
+        ds['objective'] = xr.DataArray(self._result.objective)
+
+        if self._result.effect_totals is not None and len(self._result.effect_totals) > 0:
+            ds['effect_totals'] = self._result.effect_totals
+
+        # Compute full load hours
+        combined_size = self._result.data.flows.size.copy()
+        if len(self._result.sizes) > 0:
+            combined_size = combined_size.fillna(self._result.sizes)
+
+        with xr.set_options(keep_attrs=True):
+            flh = self.total_flow_hours / combined_size
+            flh = flh.where(np.isfinite(flh))
+
+        ds['full_load_hours'] = flh
+        return ds

tests/test_stats.py

@@ -0,0 +1,17 @@
+import numpy as np
+import xarray as xr
+
+from fluxopt import FlowSystem, Flow, Effect
+
+def test_stats_summary_quickstart():
+    time = xr.DataArray(np.arange(2), dims=['time'], coords={'time': np.arange(2)})
+    sys = FlowSystem(time=time, dt=1.0)
+    sys.build(flows=[Flow(id='f1', size=10)], effects=[Effect(id='cost')])
+    res = sys.solve()
+
+    summary = res.stats.summary()
+
+    assert 'objective' in summary
+    assert 'effect_totals' in summary
+    assert 'full_load_hours' in summary
+    assert 'f1' in summary['full_load_hours'].coords['flow'].values