epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/simulation/events/system_event.py

@@ -0,0 +1,88 @@
+"""
+Module provides base classes for system events such as leakages, actuator events, etc.
+"""
+from abc import abstractmethod
+import epyt
+
+from .event import Event
+
+
+class SystemEvent(Event):
+    """
+    Base class for a system event -- i.e. an event that affects the EPANET simulation.
+    """
+    def __init__(self, **kwds):
+        self._epanet_api = None
+        self.__exit_called = False
+
+        super().__init__(**kwds)
+
+    def init(self, epanet_api: epyt.epanet) -> None:
+        """
+        Initializes the event.
+
+        Parameters
+        ----------
+        epanet_api : `epyt.epanet`
+            API to EPANET and EPANET-MSX.
+        """
+        self._epanet_api = epanet_api
+
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        if "_epanet_api" in state:
+            # Do not serialize EPyT instance!
+            del state["_epanet_api"]
+
+        return state
+
+    def __call__(self, cur_time) -> None:
+        return self.step(cur_time)
+
+    def step(self, cur_time) -> None:
+        """
+        Is called at every iteration (time step) in the simulation.
+        `apply` or `exit` are called if necessary.
+
+        Parameters
+        ----------
+        cur_time : `int`
+            Current time (seconds since the start) in the simulation.
+        """
+        if self.start_time <= cur_time < self.end_time:
+            self.apply(cur_time)
+        elif cur_time > self.end_time:
+            if self.__exit_called is False:
+                self.exit(cur_time)
+                self.__exit_called = True
+
+    def reset(self) -> None:
+        """
+        Resets this event -- i.e. make it ready for another simulation run.
+        """
+
+    def exit(self, cur_time) -> None:
+        """
+        Is called ONCE after the event is over -- i.e. next time step after `end_time`.
+
+        Any "clean-up" or "exiting" logic should go here.
+
+        Parameters
+        ----------
+        cur_time : `int`
+            Current time (seconds since the start) in the simulation.
+        """
+
+    @abstractmethod
+    def apply(self, cur_time: int) -> None:
+        """
+        Implements the event using EPANET and EPANET-MSX.
+
+        This function is only called when the event is active.
+
+        Parameters
+        ----------
+        cur_time : `int`
+            Current time (seconds since the start) in the simulation.
+        """
+        raise NotImplementedError()

epyt_flow/simulation/parallel_simulation.py

@@ -0,0 +1,147 @@
+"""
+Module provides functions for simulating several scenarios in parallel.
+"""
+from typing import Callable
+import os
+import warnings
+from multiprocess import Pool, cpu_count
+import shutil
+import psutil
+
+from .scenario_config import ScenarioConfig
+from .scada import ScadaData
+from .scenario_simulator import ScenarioSimulator
+
+
+def callback_save_to_file(folder_out: str = "") -> Callable[[ScadaData, ScenarioConfig, int], None]:
+    """
+    Creates a callback for storing the simulation results in a .epytflow_scada_data file.
+    The returned callback can be directly passed to
+    :func:`~epyt_flow.simulation.parallel_simulation.ParallelScenarioSimulation.run`.
+
+    Parameters
+    ----------
+    folder_out : `str`, optional
+        Path to the folder where the simulation results will be stored.
+
+        The default is the current working directory.
+
+    Returns
+    -------
+    `Callable[[ScadaData, ScenarioConfig, int], None]`
+        Callback storing the simulation results.
+    """
+    def callback(scada_data: ScadaData, _, scenario_idx: int) -> None:
+        scada_data.save_to_file(os.path.join(folder_out, f"{scenario_idx}"))
+
+    return callback
+
+
+def _run_scenario_simulation(scenario_config: ScenarioConfig, scenario_idx: int,
+                             callback: Callable[[ScadaData, ScenarioConfig, int], None]) -> None:
+    with ScenarioSimulator(scenario_config=scenario_config) as sim:
+        callback(sim.run_simulation(), scenario_config, scenario_idx)
+
+
+class ParallelScenarioSimulation():
+    """
+    Class providing functions to run scenario simulations in parallel.
+    """
+    @staticmethod
+    def run(scenarios: list[ScenarioConfig], n_jobs: int = -1,
+            max_working_memory_consumption: int = None,
+            callback: Callable[[ScadaData, ScenarioConfig, int], None] = callback_save_to_file()
+            ) -> None:
+        """
+        Simulates multiple scenarios in parallel.
+
+        Parameters
+        ----------
+        scenarios : list[:class:`~epyt_flow.simulation.scenario_config.ScenarioConfig`]
+            List of scenarios to be simulated.
+        n_jobs : `int`, optional
+            Number of CPUs that can be used by the simulations -- usually, this translates to
+            the number of scenarios that are simulated in parallel.
+
+            If -1, all CPUs are used.
+
+            The default is -1
+        max_working_memory_consumption : `int`, optional
+            Maximum amount of working memory in MB that can be used by the simulations.
+            Note that this might limit the number of scenarios that can be simulated in parallel.
+
+            The default is None.
+        callback: `Callable[[ScadaData, ScenarioConfig, int], None]`, optional
+            Callback that is called after the simulation of a scenario finished.
+
+            The callback gets the simulation results as a
+            :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` instance, the scenario
+            configuration as a :class: `epyt_flow.simulation.scenario_config.ScenarioConfig`
+            instance, and the index of the scenario in 'scenarios' as arguments.
+
+            The default is :func:`~epyt_flow.simulation.parallel_simulation.callback_save_to_file`.
+        """
+        if not isinstance(scenarios, list):
+            raise TypeError("'scenarios' must be an instance of 'list[ScenarioConfig]' " +
+                            f"but not of '{type(scenarios)}'")
+        if any(not isinstance(item, ScenarioConfig) for item in scenarios):
+            raise TypeError("Each item in 'scenarios' must be an instance of 'ScenarioConfig'")
+
+        if not isinstance(n_jobs, int):
+            raise TypeError(f"'n_jobs' must be an instance of 'int' but not of '{type(n_jobs)}'")
+        if not (n_jobs == -1 or n_jobs > 0):
+            raise ValueError("'n_jobs' must be either -1 or a positive integer")
+
+        if max_working_memory_consumption is not None:
+            if not isinstance(max_working_memory_consumption, int) or \
+                    max_working_memory_consumption <= 0:
+                raise ValueError("'max_working_memory_consumption' must be a positive integer")
+
+        if not callable(callback):
+            raise TypeError("'callback' mut be a callable " +
+                            "'Callable[[ScadaData, ScenarioConfig, int], None]'")
+
+        # Get free memory in MB
+        ram_free_memory = psutil.virtual_memory().free * .000001
+        if max_working_memory_consumption is not None:
+            ram_free_memory = max(ram_free_memory, max_working_memory_consumption)
+
+        harddisk_free_memory = shutil.disk_usage(".").free * .000001
+
+        # Check memory requirements of each scenario
+        max_memory_required = max(s_config.memory_consumption_estimate
+                                  if s_config.memory_consumption_estimate is not None else 0
+                                  for s_config in scenarios)
+        if max_memory_required > ram_free_memory:
+            raise RuntimeError("Not enough working memory avaialble! " +
+                               f"Requested {max_memory_required} MB but only " +
+                               f"{ram_free_memory} MB are available")
+
+        if sum(s_config.memory_consumption_estimate
+               if s_config.memory_consumption_estimate is not None else 0
+               for s_config in scenarios) >= harddisk_free_memory:
+            warnings.warn("There might not be enough free space on the hard disk " +
+                          "to store all scenario results")
+
+        # Compute number of processes that can run in parallel
+        n_available_cpus = cpu_count()
+        if n_jobs != -1:
+            n_available_cpus = min(n_available_cpus, n_jobs)
+
+        required_memory_bound = min(ram_free_memory, harddisk_free_memory)
+        n_max_parallel_scenarios = n_available_cpus
+        if max_memory_required != 0:
+            n_max_parallel_scenarios = int(required_memory_bound / max_memory_required)
+
+        n_parallel_scenarios = min(n_available_cpus, n_max_parallel_scenarios)
+
+        if any(s_config.f_msx_in is not None for s_config in scenarios):
+            n_parallel_scenarios = 1
+
+        # Run scenario simulations
+        scenarios_task = []
+        for scenario_idx, scenario in enumerate(scenarios):
+            scenarios_task.append((scenario, scenario_idx, callback))
+
+        with Pool(processes=n_parallel_scenarios, maxtasksperchild=1) as pool:
+            pool.starmap(_run_scenario_simulation, scenarios_task)

epyt_flow/simulation/scada/__init__.py

@@ -0,0 +1,3 @@
+from .scada_data import *
+from .scada_data_export import *
+from .advanced_control import *

epyt_flow/simulation/scada/advanced_control.py

@@ -0,0 +1,134 @@
+"""
+Module provides a base class for control modules.
+"""
+from abc import abstractmethod, ABC
+import warnings
+import numpy as np
+import epyt
+
+from . import ScadaData
+
+
+class AdvancedControlModule(ABC):
+    """
+    Base class for a control module.
+
+    Attributes
+    ----------
+    epanet_api : `epyt.epanet`
+        API to EPANET and EPANET-MSX. Is set in :func:`init`.
+    """
+    def __init__(self, **kwds):
+        self._epanet_api = None
+
+        super().__init__(**kwds)
+
+    def init(self, epanet_api: epyt.epanet) -> None:
+        """
+        Initializes the control module.
+
+        Parameters
+        ----------
+        epanet_api : `epyt.epanet`
+            API to EPANET for implementing the control module.
+        """
+        if not isinstance(epanet_api, epyt.epanet):
+            raise TypeError("'epanet_api' must be an instance of 'epyt.epanet' but not of " +
+                            f"'{type(epanet_api)}'")
+
+        self._epanet_api = epanet_api
+
+    def set_pump_status(self, pump_id: str, status: int) -> None:
+        """
+        Sets the status of a pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump for which the status is set.
+        status : `int`
+            New status of the pump -- either active (i.e. open) or inactive (i.e. closed).
+
+            Must be one of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED  = 0
+                - EN_OPEN    = 1
+        """
+        pump_idx = self._epanet_api.getLinkPumpNameID().index(pump_id)
+        pump_link_idx = self._epanet_api.getLinkPumpIndex(pump_idx + 1)
+        self._epanet_api.setLinkStatus(pump_link_idx, status)
+
+    def set_pump_speed(self, pump_id: str, speed: float) -> None:
+        """
+        Sets the speed of a pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump for which the pump speed is set.
+        speed : `float`
+            New pump speed.
+        """
+        pump_idx = self._epanet_api.getLinkPumpNameID().index(pump_id)
+        pattern_idx = self._epanet_api.getLinkPumpPatternIndex(pump_idx + 1)
+
+        if pattern_idx == 0:
+            warnings.warn(f"No pattern for pump '{pump_id}' found -- a new pattern is created")
+            pattern_idx = self._epanet_api.addPattern(f"pump_speed_{pump_id}")
+            self._epanet_api.setLinkPumpPatternIndex(pattern_idx)
+
+        self._epanet_api.setPattern(pattern_idx, np.array([speed]))
+
+    def set_valve_status(self, valve_id: str, status: int) -> None:
+        """
+        Sets the status of a valve.
+
+        Parameters
+        ----------
+        valve_id : `str`
+            ID of the valve for which the status is set.
+        status : `int`
+            New status of the valve -- either open or closed.
+
+            Must be one of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED  = 0
+                - EN_OPEN    = 1
+        """
+        valve_idx = self._epanet_api.getLinkValveNameID().index(valve_id)
+        valve_link_idx = self._epanet_api.getLinkValveIndex(valve_idx + 1)
+        self._epanet_api.setLinkStatus(valve_link_idx, status)
+
+    def set_node_quality_source_value(self, node_id: str, pattern_id: str,
+                                      qual_value: float) -> None:
+        """
+        Sets the quality source at a particular node to a specific value -- e.g.
+        setting the chlorine concentration injection to a specified value.
+
+        Parameters
+        ----------
+        node_id : `str`
+            ID of the node.
+        pattern_id : `str`
+            ID of the quality pattern at the specific node.
+        qual_value : `float`
+            New quality source value.
+        """
+        node_idx = self._epanet_api.getNodeIndex(node_id)
+        pattern_idx = self._epanet_api.getPatternIndex(pattern_id)
+        self._epanet_api.setNodeSourceQuality(node_idx, 1)
+        self._epanet_api.setPattern(pattern_idx, np.array([qual_value]))
+
+    @abstractmethod
+    def step(self, scada_data: ScadaData) -> None:
+        """
+        Implements the control algorithm -- i.e. mapping of sensor reading to actions.
+
+        Parameters
+        ----------
+        scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            Sensor readings.
+        """
+        raise NotImplementedError()