epyt-flow 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

epyt_flow/VERSION

@@ -1 +1 @@
-0.5.0
+0.7.0

epyt_flow/data/benchmarks/battledim.py

@@ -458,10 +458,14 @@ def load_scenario(return_test_scenario: bool, download_dir: str = None,
         ltown_config = load_ltown(use_realistic_demands=True, include_default_sensor_placement=True,
                                   verbose=verbose)
 
-    # Set simulation duration
+    # Set simulation duration and other general parameters such as the demand model
     general_params = {"simulation_duration": to_seconds(days=365),    # One year
                       "hydraulic_time_step": to_seconds(minutes=5),   # 5min time steps
-                      "reporting_time_step": to_seconds(minutes=5)} | ltown_config.general_params
+                      "reporting_time_step": to_seconds(minutes=5),
+                      "demand_model": {"type": "PDA", "pressure_min": 0,
+                                       "pressure_required": 0.1,
+                                       "pressure_exponent": 0.5}
+                      } | ltown_config.general_params
 
     # Add events
     start_time = START_TIME_TEST if return_test_scenario is True else START_TIME_TRAIN

epyt_flow/data/benchmarks/leakdb.py

@@ -30,7 +30,7 @@ from .leakdb_data import NET1_LEAKAGES, HANOI_LEAKAGES
 from ...utils import get_temp_folder, to_seconds, unpack_zip_archive, create_path_if_not_exist, \
     download_if_necessary
 from ...metrics import f1_score, true_positive_rate, true_negative_rate
-from ...simulation import ScenarioSimulator
+from ...simulation import ScenarioSimulator, ToolkitConstants
 from ...simulation.events import AbruptLeakage, IncipientLeakage
 from ...simulation import ScenarioConfig
 from ...simulation.scada import ScadaData
@@ -424,14 +424,19 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
     download_dir = download_dir if download_dir is not None else get_temp_folder()
     network_config = load_network(download_dir)
 
-    # Set simulation duration
+    # Set simulation duration and other general parameters such as the demand model and flow units
     hydraulic_time_step = to_seconds(minutes=30)    # 30min time steps
     general_params = {"simulation_duration": to_seconds(days=365),   # One year
                       "hydraulic_time_step": hydraulic_time_step,
-                      "reporting_time_step": hydraulic_time_step} | network_config.general_params
+                      "reporting_time_step": hydraulic_time_step,
+                      "flow_units_id": ToolkitConstants.EN_CMH,
+                      "demand_model": {"type": "PDA", "pressure_min": 0,
+                                       "pressure_required": 0.1,
+                                       "pressure_exponent": 0.5}
+                      } | network_config.general_params
 
     # Add demand patterns
-    def gen_dem(download_dir, use_net1):
+    def gen_dem(download_dir):
         # Taken from https://github.com/KIOS-Research/LeakDB/blob/master/CCWI-WDSA2018/Dataset_Generator_Py3/demandGenerator.py
         week_pat = scipy.io.loadmat(os.path.join(download_dir, "weekPat_30min.mat"))
         a_w = week_pat['Aw']
@@ -503,10 +508,7 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
 
         if not os.path.exists(f_inp_in):
             with ScenarioSimulator(f_inp_in=network_config.f_inp_in) as wdn:
-                wdn.epanet_api.setTimeHydraulicStep(general_params["hydraulic_time_step"])
-                wdn.epanet_api.setTimeSimulationDuration(general_params["simulation_duration"])
-                wdn.epanet_api.setTimePatternStep(general_params["hydraulic_time_step"])
-                wdn.epanet_api.setFlowUnitsCMH()
+                wdn.set_general_parameters(**general_params)
 
                 wdn.epanet_api.deletePatternsAll()
 
@@ -519,7 +521,7 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
                     node_idx = wdn.epanet_api.getNodeIndex(node_id)
                     base_demand = wdn.epanet_api.getNodeBaseDemands(node_idx)[1][0]
 
-                    my_demand_pattern = np.array(gen_dem(download_dir, use_net1))
+                    my_demand_pattern = np.array(gen_dem(download_dir))
 
                     wdn.set_node_demand_pattern(node_id=node_id, base_demand=base_demand,
                                                 demand_pattern_id=f"demand_{node_id}",

epyt_flow/data/networks.py

@@ -56,8 +56,7 @@ def get_default_hydraulic_options(flow_units_id: int = None) -> dict:
         Dictionary with default hydraulics options that can be passed to
         :func:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator.set_general_parameters`.
     """
-    params = {"demand_model": {"type": "PDA", "pressure_min": 0, "pressure_required": 0.1,
-                               "pressure_exponent": 0.5}}
+    params = {}
     if flow_units_id is not None:
         params |= {"flow_units_id": flow_units_id}
 

epyt_flow/gym/scenario_control_env.py

@@ -2,7 +2,9 @@
 Module provides a base class for control environments.
 """
 from abc import abstractmethod, ABC
-from copy import deepcopy
+from typing import Union
+import warnings
+import numpy as np
 
 from ..simulation import ScenarioSimulator, ScenarioConfig, ScadaData
 
@@ -32,8 +34,13 @@ class ScenarioControlEnv(ABC):
     def autoreset(self) -> bool:
         """
         True, if environment automatically resets after it terminated.
+
+        Returns
+        -------
+        `bool`
+            True, if environment automatically resets after it terminated.
         """
-        return deepcopy(self.__autoreset)
+        return self.__autoreset
 
     def __enter__(self):
         return self
@@ -58,6 +65,11 @@ class ScenarioControlEnv(ABC):
     def reset(self) -> ScadaData:
         """
         Resets the environment (i.e. simulation).
+
+        Returns
+        -------
+        :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            Current SCADA data (i.e. sensor readings).
         """
         if self._scenario_sim is not None:
             self._scenario_sim.close()
@@ -83,19 +95,102 @@ class ScenarioControlEnv(ABC):
             else:
                 return None, True
 
+    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._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
+        pump_link_idx = self._scenario_sim.epanet_api.getLinkPumpIndex(pump_idx + 1)
+        self._scenario_sim.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._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
+        pattern_idx = self._scenario_sim.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._scenario_sim.epanet_api.addPattern(f"pump_speed_{pump_id}")
+            self._scenario_sim.epanet_api.setLinkPumpPatternIndex(pattern_idx)
+
+        self._scenario_sim.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._scenario_sim.epanet_api.getLinkValveNameID().index(valve_id)
+        valve_link_idx = self._scenario_sim.epanet_api.getLinkValveIndex()[valve_idx]
+        self._scenario_sim.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._scenario_sim.epanet_api.getNodeIndex(node_id)
+        pattern_idx = self._scenario_sim.epanet_api.getPatternIndex(pattern_id)
+        self._scenario_sim.epanet_api.setNodeSourceQuality(node_idx, 1)
+        self._scenario_sim.epanet_api.setPattern(pattern_idx, np.array([qual_value]))
+
     @abstractmethod
-    def step(self) -> tuple[ScadaData, float, bool]:
+    def step(self, *actions) -> Union[tuple[ScadaData, float, bool], tuple[ScadaData, float]]:
         """
         Performs the next step by applying an action and observing
         the consequences (SCADA data, reward, terminated).
 
         Note that `terminated` is only returned if `autoreset=False` otherwise
-        only SCADA data and reward are returned.
+        only the current SCADA data and reward are returned.
 
         Returns
         -------
-        `(ScadaData, float, bool)`
-            Triple of observations (:class:`~epyt_flow.simuation.scada.scada_data.ScadaData`),
+        `(` :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` `, float, bool)` or `(` :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` `, float)`
+            Triple or tuple of observations (:class:`~epyt_flow.simulation.scada.scada_data.ScadaData`),
             reward (`float`), and terminated (`bool`).
         """
         raise NotImplementedError()

epyt_flow/metrics.py

@@ -3,12 +3,74 @@ This module provides different metrics for evaluation.
 """
 import numpy as np
 from sklearn.metrics import roc_auc_score as skelarn_roc_auc_score, f1_score as skelarn_f1_scpre, \
-    mean_absolute_error
+    mean_absolute_error, root_mean_squared_error, r2_score as sklearn_r2_score
 
 
-def running_mse(y_pred: np.ndarray, y: np.ndarray):
+def r2_score(y_pred: np.ndarray, y: np.ndarray) -> float:
     """
-    Computes the running Mean Squared Error (MSE).
+    Computes the R^2 score (also called the coefficient of determination).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `float`
+        R^2 score.
+    """
+    return sklearn_r2_score(y, y_pred)
+
+
+def running_r2_score(y_pred: np.ndarray, y: np.ndarray) -> list[float]:
+    """
+    Computes and returns the running R^2 score -- i.e. the R^2 score for every point in time.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `list[float]`
+        The running R^2 score.
+    """
+    r = []
+
+    for t in range(2, len(y_pred)):
+        r.append(r2_score(y_pred[:t], y[:t]))
+
+    return r
+
+
+def mean_squared_error(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the Mean Squared Error (MSE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `float`
+        MSE.
+    """
+    return root_mean_squared_error(y, y_pred)**2
+
+
+def running_mse(y_pred: np.ndarray, y: np.ndarray) -> list[float]:
+    """
+    Computes the running Mean Squared Error (MSE) -- i.e. the MSE for every point in time.
 
     Parameters
     ----------
@@ -39,7 +101,7 @@ def running_mse(y_pred: np.ndarray, y: np.ndarray):
     r_mse = list(esq for esq in e_sq)
 
     for i in range(1, len(y)):
-        r_mse[i] = ((i * r_mse[i - 1]) / (i + 1)) + (r_mse[i] / (i + 1))
+        r_mse[i] = float((i * r_mse[i - 1]) / (i + 1)) + (r_mse[i] / (i + 1))
 
     return r_mse
 

epyt_flow/serialization.py

@@ -4,6 +4,7 @@ Module provides functions and classes for serialization.
 from typing import Any, Union
 from abc import abstractmethod, ABC
 from io import BufferedIOBase
+import pathlib
 import importlib
 import json
 import gzip
@@ -97,7 +98,9 @@ class Serializable(ABC):
     Base class for a serializable class -- must be used in conjunction with the
     :func:`~epyt_flow.serialization.serializable` decorator.
     """
-    def __init__(self, **kwds):
+    def __init__(self, _parent_path: str = "", **kwds):
+        self._parent_path = _parent_path
+
         super().__init__(**kwds)
 
     @abstractmethod
@@ -306,6 +309,39 @@ class JsonSerializable(Serializable):
         """
         return my_load_from_json(data)
 
+    @staticmethod
+    def load_from_json_file(f_in: str) -> Any:
+        """
+        Deserializes an instance of this class from a JSON file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the JSON file from which to deserialize the object.
+
+        Returns
+        -------
+        `Any`
+            Deserialized object.
+        """
+        with open(f_in, "r", encoding="utf-8") as f:
+            return my_load_from_json(f.read())
+
+    def save_to_json_file(self, f_out: str) -> None:
+        """
+        Serializes this instance and stores it in a JSON file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the JSON file where this serialized object will be stored.
+        """
+        if not f_out.endswith(self.file_ext()):
+            f_out += self.file_ext()
+
+        with open(f_out, "w", encoding="utf-8") as f:
+            f.write(self.to_json())
+
 
 def load(data: Union[bytes, BufferedIOBase]) -> Any:
     """
@@ -376,12 +412,19 @@ def load_from_file(f_in: str, use_compression: bool = True) -> Any:
     `Any`
         Deserialized data.
     """
+    inst = None
+
     if use_compression is False:
         with open(f_in, "rb") as f:
-            return umsgpack.unpack(f, ext_handlers=ext_handler_unpack)
+            inst = load(f.read())
     else:
         with gzip.open(f_in, "rb") as f:
-            return load(f.read())
+            inst = load(f.read())
+
+    if isinstance(inst, Serializable):
+        inst._parent_path = pathlib.Path(f_in).parent.resolve()
+
+    return inst
 
 
 def save_to_file(f_out: str, data: Any, use_compression: bool = True) -> None:

epyt_flow/simulation/scada/advanced_control.py

@@ -98,7 +98,7 @@ class AdvancedControlModule(ABC):
                 - EN_OPEN    = 1
         """
         valve_idx = self._epanet_api.getLinkValveNameID().index(valve_id)
-        valve_link_idx = self._epanet_api.getLinkValveIndex(valve_idx + 1)
+        valve_link_idx = self._epanet_api.getLinkValveIndex()[valve_idx]
         self._epanet_api.setLinkStatus(valve_link_idx, status)
 
     def set_node_quality_source_value(self, node_id: str, pattern_id: str,