Edisgo run edisgo

.gitignore

@@ -29,3 +29,24 @@ eDisGo.egg-info/
 .vscode/settings.json
 
 *OEP_TOKEN.*
+
+# local-only notes, not for sharing on this branch
+/CONTEXT.md
+/docs_notes/spatial_reduction_grilling_session.md
+/docs_notes/issue_spatial_complexity_reduction_pipeline_integration.md
+/docs_notes/issue_aggregation_mode_flexibility_bands_not_aggregated.md
+/docs_notes/issue_temporal_reduction_flexibility_bands.md
+analyse_spatial_reduction_executed_example.ipynb
+analyse_spatial_reduction.ipynb
+analyse_uc5_results copy.ipynb
+analyse_uc5_results.ipynb
+handson_edisgo_starter.ipynb
+run_example_04.py
+docs_notes/ego_timeseries_selection_plan.md
+docs_notes/pr_description_spatial_complexity_reduction.md
+docs_notes/timeseries_selection_remaining_tasks.md
+results/uc4_example/main.zip
+results/uc5_select_timesteps/32377_t_168_residual_load.csv
+results/uc5_select_timesteps/main.zip
+results/uc5_spatial_reduction/main.zip
+results/uc6_spatial_reduction/main.zip

edisgo/edisgo.py

@@ -64,10 +64,15 @@
 from edisgo.tools import plots, tools
 from edisgo.tools.config import Config
 from edisgo.tools.geo import find_nearest_bus
-from edisgo.tools.spatial_complexity_reduction import spatial_complexity_reduction
+from edisgo.tools.spatial_complexity_reduction import (
+    apply_reduced_results_to_full_grid,
+    spatial_complexity_reduction,
+)
 from edisgo.tools.tools import (
+    check_timeindex_coverage,
     determine_grid_integration_voltage_level,
     get_path_length_to_station,
+    reduce_timeseries_data_to_given_timeindex,
 )
 
 if "READTHEDOCS" not in os.environ:
@@ -243,6 +248,31 @@ def config(self):
     def config(self, kwargs):
         self._config = Config(**kwargs)
 
+    def run_pipeline(self, config, overlying_grid_data=None):
+        """
+        Run a YAML/JSON task pipeline on this EDisGo instance.
+
+        See :mod:`edisgo.run` for the config schema and task list.
+
+        Parameters
+        ----------
+        config : str, :class:`pathlib.Path`, or dict
+            Pipeline config as path to a YAML/JSON file or as a dict.
+        overlying_grid_data : dict, optional
+            Overlying-grid data (e.g. eTraGo results) consumed by the
+            ``import_overlying_grid_data`` task when
+            ``overlying_grid.source == "etrago"``.
+
+        Returns
+        -------
+        :class:`~.EDisGo`
+            The EDisGo instance after the pipeline has run.
+
+        """
+        from edisgo.run import _run_pipeline_on
+
+        return _run_pipeline_on(self, config, overlying_grid_data=overlying_grid_data)
+
     def import_ding0_grid(self, path, legacy_ding0_grids=True):
         """
         Import ding0 topology data from csv files in the format as
@@ -323,7 +353,11 @@ def set_time_series_manual(
         providing the input parameter 'timeindex' or using the function
         :attr:`~.edisgo.EDisGo.set_timeindex`.
         Also make sure that the time steps for which time series are provided include
-        the set time index.
+        the set time index - this is now enforced: a `ValueError` is raised if a
+        non-empty DataFrame is missing data for a time step in
+        :attr:`~.network.timeseries.TimeSeries.timeindex` when a time index is
+        already set. A DataFrame with no columns is exempt from this check (nothing
+        is being written, so there is nothing to validate coverage for).
 
         """
         # check if time index is already set, otherwise raise warning
@@ -334,6 +368,16 @@ def set_time_series_manual(
                 "upon initialisation of the EDisGo object by providing the input "
                 "parameter 'timeindex' or using the function EDisGo.set_timeindex()."
             )
+        else:
+            for name, df in (
+                ("generators_p", generators_p),
+                ("loads_p", loads_p),
+                ("storage_units_p", storage_units_p),
+                ("generators_q", generators_q),
+                ("loads_q", loads_q),
+                ("storage_units_q", storage_units_q),
+            ):
+                check_timeindex_coverage(self.timeseries.timeindex, name, df)
         self.timeseries.set_active_power_manual(
             self,
             ts_generators=generators_p,
@@ -2162,6 +2206,14 @@ def apply_charging_strategy(
         match the SimBEV data frequency and after determining the charging demand time
         series resampled back to the original frequency.
 
+        The written charging point time series are trimmed to
+        :attr:`~.network.timeseries.TimeSeries.timeindex` when no such frequency
+        mismatch occurs. When it does occur, the resample round-trip above
+        currently fabricates a contiguous timeindex, which can reopen a gap
+        left by a prior manual/auto time step selection - the trim is skipped
+        in that case rather than risk operating on the wrong window. See
+        :func:`~.flex_opt.charging_strategies.charging_strategy` for details.
+
         """
         charging_strategy(
             self, strategy=strategy, charging_park_ids=charging_park_ids, **kwargs
@@ -2340,6 +2392,16 @@ def apply_heat_pump_operating_strategy(
             pumps for which COP information in :attr:`~.edisgo.EDisGo.heat_pump` is
             given are used. Default: None.
 
+        Notes
+        -----
+        The written load time series are scoped to
+        :attr:`~.network.timeseries.TimeSeries.timeindex`, regardless of
+        whether :attr:`~.edisgo.EDisGo.heat_pump`'s COP/heat demand time
+        series currently span a wider or different range. Raises
+        ``KeyError`` if they are missing data for a time step in the active
+        timeindex - see :func:`~.flex_opt.heat_pump_operation.operating_strategy`
+        for details.
+
         """
         hp_operating_strategy(self, strategy=strategy, heat_pump_names=heat_pump_names)
 
@@ -3551,6 +3613,65 @@ def spatial_complexity_reduction(
         )
         return edisgo_obj, busmap_df, linemap_df
 
+    def map_reduced_results_to_full_grid(
+        self,
+        reduced_grid: EDisGo,
+        flexible_cps: list | None = None,
+        flexible_hps: list | None = None,
+        flexible_loads: list | None = None,
+        flexible_storage_units: list | None = None,
+    ) -> EDisGo:
+        """
+        Writes optimized flexible-component dispatch from a spatially-reduced
+        grid back onto this (full) grid.
+
+        Counterpart to :meth:`spatial_complexity_reduction`: where that
+        method shrinks this grid for a faster OPF, this method maps the OPF's
+        active-power results from ``reduced_grid`` back onto ``self`` so
+        reinforcement can run on the full topology. Only components the OPF
+        actually rewrites are touched — flexible charging points, heat pumps,
+        DSM loads, and storage units. Inflexible loads/generators are
+        untouched, since the OPF never changed their series and ``self``
+        already holds the correct values for them.
+
+        See
+        :func:`~.tools.spatial_complexity_reduction.apply_reduced_results_to_full_grid`
+        for the full matching/disaggregation rules and the reactive-power
+        recompute this method triggers as a side effect.
+
+        Parameters
+        ----------
+        reduced_grid : :class:`~.EDisGo`
+            The spatially-reduced EDisGo instance the OPF ran on. Supplies
+            the optimized active-power series and, if aggregated, the
+            ``old_name`` provenance for disaggregation.
+        flexible_cps : list of str, optional
+            Names of flexible charging points in ``reduced_grid`` to map
+            back.
+        flexible_hps : list of str, optional
+            Names of flexible heat-pump loads in ``reduced_grid`` to map
+            back.
+        flexible_loads : list of str, optional
+            Names of flexible DSM loads in ``reduced_grid`` to map back.
+        flexible_storage_units : list of str, optional
+            Names of flexible storage units in ``reduced_grid`` to map back.
+
+        Returns
+        -------
+        :class:`~.EDisGo`
+            ``self``, with active power written for the given flexible
+            components and reactive power recomputed.
+
+        """
+        return apply_reduced_results_to_full_grid(
+            full_grid=self,
+            reduced_grid=reduced_grid,
+            flexible_cps=flexible_cps,
+            flexible_hps=flexible_hps,
+            flexible_loads=flexible_loads,
+            flexible_storage_units=flexible_storage_units,
+        )
+
     def check_integrity(self):
         """
         Method to check the integrity of the EDisGo object.
@@ -3691,8 +3812,8 @@ def resample_timeseries(
         """
         Resamples time series data in
         :class:`~.network.timeseries.TimeSeries`, :class:`~.network.heat.HeatPump`,
-        :class:`~.network.electromobility.Electromobility` and
-        :class:`~.network.overlying_grid.OverlyingGrid`.
+        :class:`~.network.electromobility.Electromobility`,
+        :class:`~.network.dsm.DSM` and :class:`~.network.overlying_grid.OverlyingGrid`.
 
         Both up- and down-sampling methods are possible.
 
@@ -3716,6 +3837,14 @@ def resample_timeseries(
 
         * :attr:`~.network.heat.HeatPump.heat_demand_df`
 
+        * :attr:`~.network.dsm.DSM.p_min`
+
+        * :attr:`~.network.dsm.DSM.p_max`
+
+        * :attr:`~.network.dsm.DSM.e_min`
+
+        * :attr:`~.network.dsm.DSM.e_max`
+
         * All data in :class:`~.network.overlying_grid.OverlyingGrid`
 
         Parameters
@@ -3748,8 +3877,77 @@ def resample_timeseries(
         self.timeseries.resample(method=method, freq=freq)
         self.electromobility.resample(freq=freq)
         self.heat_pump.resample_timeseries(method=method, freq=freq)
+        self.dsm.resample(method=method, freq=freq)
         self.overlying_grid.resample(method=method, freq=freq)
 
+    def reduce_timeseries_data_to_given_timeindex(
+        self,
+        timeindex,
+        freq="1H",
+        timeseries=True,
+        electromobility=True,
+        save_ev_soc_initial=True,
+        heat_pump=True,
+        dsm=True,
+        overlying_grid=True,
+    ):
+        """
+        Reduces timeseries data in this EDisGo object to given time index.
+
+        Thin wrapper around
+        :func:`edisgo.tools.tools.reduce_timeseries_data_to_given_timeindex`,
+        exposed here for discoverability - the underlying implementation is
+        otherwise only importable directly from ``edisgo.tools.tools``, which
+        made it easy to miss for anyone using :class:`~.EDisGo` outside the
+        ``run`` pipeline (its only prior callers).
+
+        Parameters
+        -----------
+        timeindex : :pandas:`pandas.DatetimeIndex<DatetimeIndex>`
+            Time index to set.
+        freq : str or :pandas:`pandas.Timedelta<Timedelta>`, optional
+            Frequency of time series data. This is only needed if it cannot be
+            inferred from the given `timeindex` and if electromobility data
+            and/or overlying grid data is reduced, as the initial SoC is
+            tried to be set using the time step before the first time step in
+            the given `timeindex`. Offset aliases can be found here:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases.
+            Default: '1H'.
+        timeseries : bool
+            Indicates whether timeseries in
+            :class:`~.network.timeseries.TimeSeries` are reduced to given
+            time index. Default: True.
+        electromobility : bool
+            Indicates whether timeseries in
+            :class:`~.network.electromobility.Electromobility` are reduced to
+            given time index. Default: True.
+        save_ev_soc_initial : bool
+            Indicates whether to save initial EV SOC from timestep before
+            first timestep of given time index. Default: True.
+        heat_pump : bool
+            Indicates whether timeseries in :class:`~.network.heat.HeatPump`
+            are reduced to given time index. Default: True.
+        dsm : bool
+            Indicates whether timeseries in :class:`~.network.dsm.DSM` are
+            reduced to given time index. Default: True.
+        overlying_grid : bool
+            Indicates whether timeseries in
+            :class:`~.network.overlying_grid.OverlyingGrid` are reduced to
+            given time index. Default: True.
+
+        """
+        reduce_timeseries_data_to_given_timeindex(
+            self,
+            timeindex,
+            freq=freq,
+            timeseries=timeseries,
+            electromobility=electromobility,
+            save_ev_soc_initial=save_ev_soc_initial,
+            heat_pump=heat_pump,
+            dsm=dsm,
+            overlying_grid=overlying_grid,
+        )
+
 
 def import_edisgo_from_pickle(filename, path=""):
     """