epyt-flow 0.8.1__py3-none-any.whl → 0.10.0__py3-none-any.whl

epyt_flow/simulation/scenario_simulator.py

@@ -5,6 +5,8 @@ import sys
 import os
 import pathlib
 import time
+from datetime import timedelta
+from datetime import datetime
 from typing import Generator, Union
 from copy import deepcopy
 import shutil
@@ -28,7 +30,8 @@ from .sensor_config import SensorConfig, areaunit_to_id, massunit_to_id, quality
 from ..uncertainty import ModelUncertainty, SensorNoise
 from .events import SystemEvent, Leakage, ActuatorEvent, SensorFault, SensorReadingAttack, \
     SensorReadingEvent
-from .scada import ScadaData, AdvancedControlModule
+from .scada import ScadaData, CustomControlModule, SimpleControlModule, ComplexControlModule, \
+    RuleCondition, RuleAction, ActuatorConstants, EN_R_ACTION_SETTING
 from ..topology import NetworkTopology, UNITS_SIMETRIC, UNITS_USCUSTOM
 from ..utils import get_temp_folder
 
@@ -67,8 +70,12 @@ class ScenarioSimulator():
         Sensor noise.
     _sensor_config : :class:`~epyt_flow.simulation.sensor_config.SensorConfig`, protected
         Sensor configuration.
-    _controls : list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`], protected
+    _custom_controls : list[:class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`], protected
         List of custom control modules.
+    _simple_controls : list[:class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`], protected
+        List of simle EPANET control rules.
+    _complex_controls : list[:class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`], protected
+        List of complex (IF-THEN-ELSE) EPANET control rules.
     _system_events : list[:class:`~epyt_flow.simulation.events.system_event.SystemEvent`], protected
         Lsit of system events such as leakages.
     _sensor_reading_events : list[:class:`~epyt_flow.simulation.events.sensor_reading_event.SensorReadingEvent`], protected
@@ -105,7 +112,10 @@ class ScenarioSimulator():
         self._model_uncertainty = ModelUncertainty()
         self._sensor_noise = None
         self._sensor_config = None
-        self._controls = []
+        self._advanced_controls = []
+        self._custom_controls = []
+        self._simple_controls = []
+        self._complex_controls = []
         self._system_events = []
         self._sensor_reading_events = []
         self.__running_simulation = False
@@ -168,6 +178,9 @@ class ScenarioSimulator():
             if self.__f_msx_in is not None:
                 self.epanet_api.loadMSXFile(my_f_msx_in, customMSXlib=custom_epanetmsx_lib)
 
+        self._simple_controls = self._parse_simple_control_rules()
+        self._complex_controls = self._parse_complex_control_rules()
+
         self._sensor_config = self._get_empty_sensor_config()
         if scenario_config is not None:
             if scenario_config.general_params is not None:
@@ -177,8 +190,15 @@ class ScenarioSimulator():
             self._sensor_noise = scenario_config.sensor_noise
             self._sensor_config = scenario_config.sensor_config
 
-            for control in scenario_config.controls:
-                self.add_control(control)
+            if scenario_config.advanced_controls is not None:
+                for control in scenario_config.advanced_controls:
+                    self.add_advanced_control(control)
+            for control in scenario_config.custom_controls:
+                self.add_custom_control(control)
+            for control in scenario_config.simple_controls:
+                self.add_simple_control(control)
+            for control in scenario_config.complex_controls:
+                self.add_complex_control(control)
             for event in scenario_config.system_events:
                 self.add_system_event(event)
             for event in scenario_config.sensor_reading_events:
@@ -323,18 +343,62 @@ class ScenarioSimulator():
         self._sensor_config = sensor_config
 
     @property
-    def controls(self) -> list[AdvancedControlModule]:
+    def advanced_controls(self) -> list:
         """
-        Gets all control modules.
+        Returns all advanced control modules.
 
         Returns
         -------
         list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`]
-            All control modules.
+            All advanced control modules.
+        """
+        warnings.warn("'AdvancedControlModule' is deprecated and will be removed in a " +
+                      "future release -- use 'CustomControlModule' instead")
+        self._adapt_to_network_changes()
+
+        return deepcopy(self._advanced_controls)
+
+    @property
+    def custom_controls(self) -> list[CustomControlModule]:
+        """
+        Returns all custom control modules.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`]
+            All custom control modules.
+        """
+        self._adapt_to_network_changes()
+
+        return deepcopy(self._custom_controls)
+
+    @property
+    def simple_controls(self) -> list[SimpleControlModule]:
+        """
+        Gets all simple EPANET control rules.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`]
+            All simple EPANET control rules.
+        """
+        self._adapt_to_network_changes()
+
+        return deepcopy(self._simple_controls)
+
+    @property
+    def complex_controls(self) -> list[SimpleControlModule]:
+        """
+        Gets all complex (IF-THEN-ELSE) EPANET control rules.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`]
+            All complex EPANET control rules.
         """
         self._adapt_to_network_changes()
 
-        return deepcopy(self._controls)
+        return deepcopy(self._complex_controls)
 
     @property
     def leakages(self) -> list[Leakage]:
@@ -422,6 +486,132 @@ class ScenarioSimulator():
 
         return deepcopy(self._sensor_reading_events)
 
+    def _parse_simple_control_rules(self) -> list[SimpleControlModule]:
+        controls = []
+
+        for idx in self.epanet_api.getControls():
+            control = self.epanet_api.getControls(idx)
+
+            if control.Setting == "OPEN":
+                link_status = ActuatorConstants.EN_OPEN
+            else:
+                link_status = ActuatorConstants.EN_CLOSED
+
+            if control.Type == "LOWLEVEL":
+                cond_type = ToolkitConstants.EN_LOWLEVEL
+            elif control.Type == "HIGHLEVEL":
+                cond_type = ToolkitConstants.EN_HILEVEL
+            elif control.Type == "TIMER":
+                cond_type = ToolkitConstants.EN_TIMER
+            elif control.Type == "TIMEOFDAY":
+                cond_type = ToolkitConstants.EN_TIMEOFDAY
+
+            if control.NodeID is not None:
+                cond_var_value = control.NodeID
+                cond_comp_value = control.Value
+            else:
+                if cond_type == ToolkitConstants.EN_TIMER:
+                    cond_var_value = int(control.Value / 3600)
+                elif cond_type == ToolkitConstants.EN_TIMEOFDAY:
+                    sec = control.Value
+                    if sec <= 43200:
+                        cond_var_value = \
+                            f"{':'.join(str(timedelta(seconds=sec)).split(':')[:2])} AM"
+                    else:
+                        sec -= 43200
+                        cond_var_value = \
+                            f"{':'.join(str(timedelta(seconds=sec)).split(':')[:2])} PM"
+                cond_comp_value = None
+
+            controls.append(SimpleControlModule(link_id=control.LinkID,
+                                                link_status=link_status,
+                                                cond_type=cond_type,
+                                                cond_var_value=cond_var_value,
+                                                cond_comp_value=cond_comp_value))
+
+        return controls
+
+    def _parse_complex_control_rules(self) -> list[ComplexControlModule]:
+        controls = []
+
+        rules = self.epanet_api.getRules()
+        for rule_idx, rule in rules.items():
+            rule_info = self.epanet_api.getRuleInfo(rule_idx)
+
+            rule_id = rule["Rule_ID"]
+            rule_priority, *_ = rule_info.Priority
+
+            # Parse conditions
+            n_rule_premises, *_ = rule_info.Premises
+
+            condition_1 = None
+            additional_conditions = []
+            for j in range(1, n_rule_premises + 1):
+                [logop, object_type_id, obj_idx, variable_type_id, relop, status, value_premise] = \
+                    self.epanet_api.api.ENgetpremise(rule_idx, j)
+
+                object_id = None
+                if object_type_id == ToolkitConstants.EN_R_NODE:
+                    object_id = self.epanet_api.getNodeNameID(obj_idx)
+                elif object_type_id == ToolkitConstants.EN_R_LINK:
+                    object_id = self.epanet_api.getLinkNameID(obj_idx)
+                elif object_type_id == ToolkitConstants.EN_R_SYSTEM:
+                    object_id = ""
+
+                if variable_type_id >= ToolkitConstants.EN_R_TIME:
+                    value_premise = datetime.fromtimestamp(value_premise)\
+                        .strftime("%I:%M %p")
+                if status != 0:
+                    value_premise = self.epanet_api.RULESTATUS[status - 1]
+
+                condition = RuleCondition(object_type_id, object_id, variable_type_id,
+                                          relop, value_premise)
+                if condition_1 is None:
+                    condition_1 = condition
+                else:
+                    additional_conditions.append((logop, condition))
+
+            # Parse actions
+            n_rule_then_actions, *_ = rule_info.ThenActions
+            actions = []
+            for j in range(1, n_rule_then_actions + 1):
+                [link_idx, link_status, link_setting] = \
+                    self.epanet_api.api.ENgetthenaction(rule_idx, j)
+
+                link_type_id = self.epanet_api.getLinkTypeIndex(link_idx)
+                link_id = self.epanet_api.getLinkNameID(link_idx)
+                if link_status >= 0:
+                    action_type_id = link_status
+                    action_value = link_status
+                else:
+                    action_type_id = EN_R_ACTION_SETTING
+                    action_value = link_setting
+
+                actions.append(RuleAction(link_type_id, link_id, action_type_id, action_value))
+
+            n_rule_else_actions, *_ = rule_info.ElseActions
+            else_actions = []
+            for j in range(1, n_rule_else_actions + 1):
+                [link_idx, link_status, link_setting] = \
+                    self.epanet_api.api.ENgetelseaction(rule_idx, j)
+
+                link_type_id = self.epanet_api.getLinkType(link_idx)
+                link_id = self.epanet_api.getLinkNameID(link_idx)
+                if link_status <= 3:
+                    action_type_id = link_status
+                    action_value = link_status
+                else:
+                    action_type_id = EN_R_ACTION_SETTING
+                    action_value = link_setting
+
+                else_actions.append(RuleAction(link_type_id, link_id, action_type_id, action_value))
+
+            # Create and add control module
+            controls.append(ComplexControlModule(rule_id, condition_1, additional_conditions,
+                                                 actions, else_actions, int(rule_priority)))
+
+        return controls
+
     def _adapt_to_network_changes(self):
         nodes = self.epanet_api.getNodeNameID()
         links = self.epanet_api.getLinkNameID()
@@ -477,7 +667,8 @@ class ScenarioSimulator():
         self.close()
 
     def save_to_epanet_file(self, inp_file_path: str, msx_file_path: str = None,
-                            export_sensor_config: bool = True) -> None:
+                            export_sensor_config: bool = True, undo_system_events: bool = True
+                            ) -> None:
         """
         Exports this scenario to EPANET files -- i.e. an .inp file
         and (optionally) a .msx file if EPANET-MSX was loaded.
@@ -540,6 +731,10 @@ class ScenarioSimulator():
                 if write_end_section is True:
                     f_in.write("\n[END]")
 
+        if undo_system_events is True:
+            for event in self._system_events:
+                event.cleanup()
+
         if inp_file_path is not None:
             self.epanet_api.saveInputFile(inp_file_path)
             self.__f_inp_in = inp_file_path
@@ -641,6 +836,10 @@ class ScenarioSimulator():
 
                 __override_report_section(msx_file_path, report_desc)
 
+        if undo_system_events is True:
+            for event in self._system_events:
+                event.init(self.epanet_api)
+
     def get_flow_units(self) -> int:
         """
         Gets the flow units.
@@ -791,7 +990,11 @@ class ScenarioSimulator():
         return ScenarioConfig(f_inp_in=self.__f_inp_in, f_msx_in=self.__f_msx_in,
                               general_params=general_params, sensor_config=self.sensor_config,
                               memory_consumption_estimate=self.estimate_memory_consumption(),
-                              controls=self.controls, sensor_noise=self.sensor_noise,
+                              advanced_controls=None if len(self._advanced_controls) == 0 else self.advanced_controls,
+                              custom_controls=self.custom_controls,
+                              simple_controls=self.simple_controls,
+                              complex_controls=self.complex_controls,
+                              sensor_noise=self.sensor_noise,
                               model_uncertainty=self.model_uncertainty,
                               system_events=self.system_events,
                               sensor_reading_events=self.sensor_reading_events)
@@ -938,8 +1141,72 @@ class ScenarioSimulator():
             for t in range(pattern_length):  # Set shuffled/randomized pattern
                 self.epanet_api.setPatternValue(pattern_id, t + 1, pattern[t])
 
+    def get_pattern(self, pattern_id: str) -> np.ndarray:
+        """
+        Returns the EPANET pattern (i.e. all multiplier factors over time) given its ID.
+
+        Parameters
+        ----------
+        pattern_id : `str`
+            ID of the pattern.
+
+        Returns
+        -------
+        `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
+            The pattern -- i.e. multiplier factors over time.
+        """
+        pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
+        pattern_length = self.epanet_api.getPatternLengths(pattern_idx)
+        return np.array([self.epanet_api.getPatternValue(pattern_idx, t+1)
+                         for t in range(pattern_length)])
+
+    def add_pattern(self, pattern_id: str, pattern: np.ndarray) -> None:
+        """
+        Adds a pattern to the EPANET scenario.
+
+        Parameters
+        ----------
+        pattern_id : `str`
+            ID of the pattern.
+        pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
+            Pattern of multipliers over time.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(pattern_id, str):
+            raise TypeError("'pattern_id' must be an instance of 'str' " +
+                            f"but not of '{type(pattern_id)}'")
+        if not isinstance(pattern, np.ndarray):
+            raise TypeError("'pattern' must be an instance of 'numpy.ndarray' " +
+                            f"but not of '{type(pattern)}'")
+        if len(pattern.shape) > 1:
+            raise ValueError(f"Inconsistent pattern shape '{pattern.shape}' " +
+                             "detected. Expected a one dimensional array!")
+
+        self.epanet_api.addPattern(pattern_id, pattern)
+
+    def get_node_demand_pattern(self, node_id: str) -> np.ndarray:
+        """
+        Returns the values of the demand pattern of a given node --
+        i.e. multiplier factors that are applied to the base demand.
+
+        Parameters
+        ----------
+        node_id : `str`
+            ID of the node.
+
+        Returns
+        -------
+        `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
+            The demand pattern -- i.e. multiplier factors over time.
+        """
+        node_idx = self.epanet_api.getNodeIndex(node_id)
+        demand_category = self.epanet_api.getNodeDemandCategoriesNumber()[node_idx]
+        demand_pattern_id = self.epanet_api.getNodeDemandPatternNameID()[demand_category][node_idx - 1]
+        return self.get_pattern(demand_pattern_id)
+
     def set_node_demand_pattern(self, node_id: str, base_demand: float, demand_pattern_id: str,
-                                demand_pattern: np.ndarray) -> None:
+                                demand_pattern: np.ndarray = None) -> None:
         """
         Sets the demand pattern (incl. base demand) at a given node.
 
@@ -950,9 +1217,12 @@ class ScenarioSimulator():
         base_demand : `float`
             Base demand.
         demand_pattern_id : `str`
-            ID of the new demand pattern.
-        demand_pattern : `numpy.ndarray`
+            ID of the (new) demand pattern. Existing demand pattern will be overriden if it already exisits.
+        demand_pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_, optional
             Demand pattern over time. Final demand over time = base_demand * demand_pattern
+            If None, the pattern demand_pattern_id is assumed to already exist.
+
+            The default is None.
         """
         self._adapt_to_network_changes()
 
@@ -964,35 +1234,170 @@ class ScenarioSimulator():
         if not isinstance(demand_pattern_id, str):
             raise TypeError("'demand_pattern_id' must be an instance of 'str' " +
                             f"but not of '{type(demand_pattern_id)}'")
-        if not isinstance(demand_pattern, np.ndarray):
-            raise TypeError("'demand_pattern' must be an instance of 'numpy.ndarray' " +
-                            f"but not of '{type(demand_pattern)}'")
-        if len(demand_pattern.shape) > 1:
-            raise ValueError(f"Inconsistent demand pattern shape '{demand_pattern.shape}' " +
-                             "detected. Expected a one dimensional array!")
+        if demand_pattern is not None:
+            if not isinstance(demand_pattern, np.ndarray):
+                raise TypeError("'demand_pattern' must be an instance of 'numpy.ndarray' " +
+                                f"but not of '{type(demand_pattern)}'")
+            if len(demand_pattern.shape) > 1:
+                raise ValueError(f"Inconsistent demand pattern shape '{demand_pattern.shape}' " +
+                                 "detected. Expected a one dimensional array!")
 
         node_idx = self.epanet_api.getNodeIndex(node_id)
-        self.epanet_api.addPattern(demand_pattern_id, demand_pattern)
+
+        if demand_pattern_id not in self.epanet_api.getPatternNameID():
+            if demand_pattern is None:
+                raise ValueError("'demand_pattern' can not be None if " +
+                                 "'demand_pattern_id' does not already exist.")
+            self.epanet_api.addPattern(demand_pattern_id, demand_pattern)
+        else:
+            if demand_pattern is not None:
+                pattern_idx = self.epanet_api.getPatternIndex(demand_pattern_id)
+                self.epanet_api.setPattern(pattern_idx, demand_pattern)
+
         self.epanet_api.setNodeJunctionData(node_idx, self.epanet_api.getNodeElevations(node_idx),
                                             base_demand, demand_pattern_id)
 
-    def add_control(self, control: AdvancedControlModule) -> None:
+    def add_advanced_control(self, control) -> None:
         """
-        Adds a control module to the scenario simulation.
+        Adds an advanced control module to the scenario simulation.
 
         Parameters
         ----------
         control : :class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`
-            Control module.
+            Advanced control module.
         """
         self._adapt_to_network_changes()
 
+        from .scada.advanced_control import AdvancedControlModule
         if not isinstance(control, AdvancedControlModule):
             raise TypeError("'control' must be an instance of " +
                             "'epyt_flow.simulation.scada.AdvancedControlModule' not of " +
                             f"'{type(control)}'")
 
-        self._controls.append(control)
+        self._advanced_controls.append(control)
+
+    def add_custom_control(self, control: CustomControlModule) -> None:
+        """
+        Adds a custom control module to the scenario simulation.
+
+        Parameters
+        ----------
+        control : :class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`
+            Custom control module.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(control, CustomControlModule):
+            raise TypeError("'control' must be an instance of " +
+                            "'epyt_flow.simulation.scada.CustomControlModule' not of " +
+                            f"'{type(control)}'")
+
+        self._custom_controls.append(control)
+
+    def add_simple_control(self, control: SimpleControlModule) -> None:
+        """
+        Adds a simple EPANET control rule to the scenario simulation.
+
+        Parameters
+        ----------
+        control : :class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`
+            Simple EPANET control module.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(control, SimpleControlModule):
+            raise TypeError("'control' must be an instance of " +
+                            "'epyt_flow.simulation.scada.SimpleControlModule' not of " +
+                            f"'{type(control)}'")
+
+        if not any(c == control for c in self._simple_controls):
+            self._simple_controls.append(control)
+            self.epanet_api.addControls(str(control))
+
+    def remove_all_simple_controls(self) -> None:
+        """
+        Removes all simple EPANET controls from the scenario.
+        """
+        self.epanet_api.deleteControls()
+        self._simple_controls = []
+
+    def remove_simple_control(self, control: SimpleControlModule) -> None:
+        """
+        Removes a given simple EPANET control rule from the scenario.
+
+        Parameters
+        ----------
+        control : :class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`
+            Simple EPANET control module to be removed.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(control, SimpleControlModule):
+            raise TypeError("'control' must be an instance of " +
+                            "'epyt_flow.simulation.scada.SimpleControlModule' not of " +
+                            f"'{type(control)}'")
+
+        control_idx = None
+        for idx, c in enumerate(self._simple_controls):
+            if c == control:
+                control_idx = idx + 1
+                break
+        if control_idx is None:
+            raise ValueError("Invalid/Unknown control module.")
+
+        self.epanet_api.deleteControls(control_idx)
+        self._simple_controls.remove(control)
+
+    def add_complex_control(self, control: ComplexControlModule) -> None:
+        """
+        Adds an complex (IF-THEN-ELSE) EPANET control rule to the scenario simulation.
+
+        Parameters
+        ----------
+        control : :class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`
+            Complex EPANET control module.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(control, ComplexControlModule):
+            raise TypeError("'control' must be an instance of " +
+                            "'epyt_flow.simulation.scada.ComplexControlModule' not of " +
+                            f"'{type(control)}'")
+
+        if not any(c == control for c in self._complex_controls):
+            self._complex_controls.append(control)
+            self.epanet_api.addRules(str(control))
+
+    def remove_all_complex_controls(self) -> None:
+        """
+        Removes all complex EPANET controls from the scenario.
+        """
+        self.epanet_api.deleteRules()
+        self._complex_controls = []
+
+    def remove_complex_control(self, control: ComplexControlModule) -> None:
+        """
+        Removes a given complex (IF-THEN-ELSE) EPANET control rule from the scenario.
+
+        Parameters
+        ----------
+        control : :class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`
+            Complex EPANET control module to be removed.
+        """
+        self._adapt_to_network_changes()
+
+        if not isinstance(control, ComplexControlModule):
+            raise TypeError("'control' must be an instance of " +
+                            "'epyt_flow.simulation.scada.ComplexControlModule' not of " +
+                            f"'{type(control)}'")
+
+        if control.rule_id not in self.epanet_api.getRuleID():
+            raise ValueError("Invalid/Unknown control module. " +
+                             f"Can not find rule ID '{control.rule_id}'")
+
+        rule_idx = self.epanet_api.getRuleID().index(control.rule_id) + 1
+        self.epanet_api.deleteRules(rule_idx)
+        self._complex_controls.remove(control)
 
     def add_leakage(self, leakage_event: Leakage) -> None:
         """
@@ -1529,12 +1934,17 @@ class ScenarioSimulator():
         for event in self._system_events:
             event.reset()
 
-        if self._controls is not None:
-            for c in self._controls:
+        if self._advanced_controls is not None:
+            for c in self._advanced_controls:
                 c.init(self.epanet_api)
+        if self._custom_controls is not None:
+            for control in self._custom_controls:
+                control.init(self.epanet_api)
 
     def run_advanced_quality_simulation(self, hyd_file_in: str, verbose: bool = False,
-                                        frozen_sensor_config: bool = False) -> ScadaData:
+                                        frozen_sensor_config: bool = False,
+                                        use_quality_time_step_as_reporting_time_step: bool = False
+                                        ) -> ScadaData:
         """
         Runs an advanced quality analysis using EPANET-MSX.
 
@@ -1551,6 +1961,13 @@ class ScenarioSimulator():
             If True, the sensor config can not be changed and only the required sensor nodes/links
             will be stored -- this usually leads to a significant reduction in memory consumption.
 
+            The default is False.
+        use_quality_time_step_as_reporting_time_step : `bool`, optional
+            If True, the water quality time step will be used as the reporting time step.
+
+            As a consequence, the simualtion results can not be merged
+            with the hydraulic simulation.
+
             The default is False.
 
         Returns
@@ -1570,7 +1987,9 @@ class ScenarioSimulator():
         for scada_data in gen(hyd_file_in=hyd_file_in,
                               verbose=verbose,
                               return_as_dict=True,
-                              frozen_sensor_config=frozen_sensor_config):
+                              frozen_sensor_config=frozen_sensor_config,
+                              use_quality_time_step_as_reporting_time_step=
+                              use_quality_time_step_as_reporting_time_step):
             if result is None:
                 result = {}
                 for data_type, data in scada_data.items():
@@ -1595,7 +2014,8 @@ class ScenarioSimulator():
     def run_advanced_quality_simulation_as_generator(self, hyd_file_in: str, verbose: bool = False,
                                                      support_abort: bool = False,
                                                      return_as_dict: bool = False,
-                                                     frozen_sensor_config: bool = False
+                                                     frozen_sensor_config: bool = False,
+                                                     use_quality_time_step_as_reporting_time_step: bool = False,
                                                      ) -> Generator[Union[ScadaData, dict], bool, None]:
         """
         Runs an advanced quality analysis using EPANET-MSX.
@@ -1617,6 +2037,13 @@ class ScenarioSimulator():
             If True, the sensor config can not be changed and only the required sensor nodes/links
             will be stored -- this usually leads to a significant reduction in memory consumption.
 
+            The default is False.
+        use_quality_time_step_as_reporting_time_step : `bool`, optional
+            If True, the water quality time step will be used as the reporting time step.
+
+            As a consequence, the simualtion results can not be merged
+            with the hydraulic simulation.
+
             The default is False.
 
         Returns
@@ -1642,6 +2069,11 @@ class ScenarioSimulator():
         reporting_time_step = self.epanet_api.getTimeReportingStep()
         hyd_time_step = self.epanet_api.getTimeHydraulicStep()
 
+        if use_quality_time_step_as_reporting_time_step is True:
+            quality_time_step = self.epanet_api.getMSXTimeStep()
+            reporting_time_step = quality_time_step
+            hyd_time_step = quality_time_step
+
         self.epanet_api.initializeMSXQualityAnalysis(ToolkitConstants.EN_NOSAVE)
 
         self.__running_simulation = True
@@ -1654,7 +2086,7 @@ class ScenarioSimulator():
             print("Running EPANET-MSX ...")
             n_iterations = math.ceil(self.epanet_api.getTimeSimulationDuration() /
                                      hyd_time_step)
-            progress_bar = iter(tqdm(range(n_iterations + 1), desc="Time steps"))
+            progress_bar = iter(tqdm(range(n_iterations + 1), ascii=True, desc="Time steps"))
 
         def __get_concentrations(init_qual=False):
             if init_qual is True:
@@ -1793,7 +2225,9 @@ class ScenarioSimulator():
         self.__running_simulation = False
 
     def run_basic_quality_simulation(self, hyd_file_in: str, verbose: bool = False,
-                                     frozen_sensor_config: bool = False) -> ScadaData:
+                                     frozen_sensor_config: bool = False,
+                                     use_quality_time_step_as_reporting_time_step: bool = False
+                                     ) -> ScadaData:
         """
         Runs a basic quality analysis using EPANET.
 
@@ -1810,6 +2244,13 @@ class ScenarioSimulator():
             If True, the sensor config can not be changed and only the required sensor nodes/links
             will be stored -- this usually leads to a significant reduction in memory consumption.
 
+            The default is False.
+        use_quality_time_step_as_reporting_time_step : `bool`, optional
+            If True, the water quality time step will be used as the reporting time step.
+
+            As a consequence, the simualtion results can not be merged
+            with the hydraulic simulation.
+
             The default is False.
 
         Returns
@@ -1827,7 +2268,9 @@ class ScenarioSimulator():
         for scada_data in gen(hyd_file_in=hyd_file_in,
                               verbose=verbose,
                               return_as_dict=True,
-                              frozen_sensor_config=frozen_sensor_config):
+                              frozen_sensor_config=frozen_sensor_config,
+                              use_quality_time_step_as_reporting_time_step=
+                              use_quality_time_step_as_reporting_time_step):
             if result is None:
                 result = {}
                 for data_type, data in scada_data.items():
@@ -1850,6 +2293,7 @@ class ScenarioSimulator():
                                                   support_abort: bool = False,
                                                   return_as_dict: bool = False,
                                                   frozen_sensor_config: bool = False,
+                                                  use_quality_time_step_as_reporting_time_step: bool = False
                                                   ) -> Generator[Union[ScadaData, dict], bool, None]:
         """
         Runs a basic quality analysis using EPANET.
@@ -1873,6 +2317,13 @@ class ScenarioSimulator():
             If True, the sensor config can not be changed and only the required sensor nodes/links
             will be stored -- this usually leads to a significant reduction in memory consumption.
 
+            The default is False.
+        use_quality_time_step_as_reporting_time_step : `bool`, optional
+            If True, the water quality time step will be used as the reporting time step.
+
+            As a consequence, the simualtion results can not be merged
+            with the hydraulic simulation.
+
             The default is False.
 
         Returns
@@ -1887,6 +2338,11 @@ class ScenarioSimulator():
         reporting_time_start = self.epanet_api.getTimeReportingStart()
         reporting_time_step = self.epanet_api.getTimeReportingStep()
 
+        if use_quality_time_step_as_reporting_time_step is True:
+            quality_time_step = self.epanet_api.getTimeQualityStep()
+            requested_time_step = quality_time_step
+            reporting_time_step = quality_time_step
+
         self.epanet_api.useHydraulicFile(hyd_file_in)
 
         self.epanet_api.openQualityAnalysis()
@@ -1896,7 +2352,7 @@ class ScenarioSimulator():
             print("Running basic quality analysis using EPANET ...")
             n_iterations = math.ceil(self.epanet_api.getTimeSimulationDuration() /
                                      requested_time_step)
-            progress_bar = iter(tqdm(range(n_iterations + 1), desc="Time steps"))
+            progress_bar = iter(tqdm(range(n_iterations + 1), ascii=True, desc="Time steps"))
 
         # Run simulation step by step
         total_time = 0
@@ -1945,7 +2401,7 @@ class ScenarioSimulator():
                 yield data
 
             # Next
-            tstep = self.epanet_api.nextQualityAnalysisStep()
+            tstep = self.epanet_api.stepQualityAnalysisTimeLeft()
 
         self.epanet_api.closeHydraulicAnalysis()
 
@@ -2081,7 +2537,7 @@ class ScenarioSimulator():
             print("Running EPANET ...")
             n_iterations = math.ceil(self.epanet_api.getTimeSimulationDuration() /
                                      requested_time_step)
-            progress_bar = iter(tqdm(range(n_iterations + 1), desc="Time steps"))
+            progress_bar = iter(tqdm(range(n_iterations + 1), ascii=True, desc="Time steps"))
 
         try:
             # Run simulation step by step
@@ -2167,7 +2623,9 @@ class ScenarioSimulator():
                     yield data
 
                 # Apply control modules
-                for control in self._controls:
+                for control in self._advanced_controls:
+                    control.step(scada_data)
+                for control in self._custom_controls:
                     control.step(scada_data)
 
                 # Next
@@ -2538,7 +2996,7 @@ class ScenarioSimulator():
         self.set_general_parameters(quality_model={"type": "CHEM", "chemical_name": chemical_name,
                                                    "units": chemical_units})
 
-    def add_quality_source(self, node_id: str, pattern: np.ndarray, source_type: int,
+    def add_quality_source(self, node_id: str, source_type: int, pattern: np.ndarray = None,
                            pattern_id: str = None, source_strength: int = 1.) -> None:
         """
         Adds a new external water quality source at a particular node.
@@ -2547,8 +3005,6 @@ class ScenarioSimulator():
         ----------
         node_id : `str`
             ID of the node at which this external water quality source is placed.
-        pattern : `numpy.ndarray`
-            1d source pattern.
         source_type : `int`,
             Types of the external water quality source -- must be of the following
             EPANET toolkit constants:
@@ -2564,6 +3020,12 @@ class ScenarioSimulator():
                 - EN_MASS Injects a given mass/minute into a node
                 - EN_SETPOINT Sets the concentration leaving a node to a given value
                 - EN_FLOWPACED Adds a given value to the concentration leaving a node
+        pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_, optional
+            1d source pattern multipiers over time -- i.e. quality-source = source_strength * pattern.
+
+            If None, the pattern pattern_id is assume to already exist.
+
+            The default is None.
         pattern_id : `str`, optional
             ID of the source pattern.
 
@@ -2586,20 +3048,23 @@ class ScenarioSimulator():
                                "call 'enable_chemical_analysis()' before calling this function.")
         if node_id not in self._sensor_config.nodes:
             raise ValueError(f"Unknown node '{node_id}'")
-        if not isinstance(pattern, np.ndarray):
-            raise TypeError("'pattern' must be an instance of 'numpy.ndarray' " +
-                            f"but not of '{type(pattern)}'")
         if not isinstance(source_type, int) or not 0 <= source_type <= 3:
             raise ValueError("Invalid type of water quality source")
-
+        if pattern is not None:
+            if not isinstance(pattern, np.ndarray):
+                raise TypeError("'pattern' must be an instance of 'numpy.ndarray' " +
+                                f"but not of '{type(pattern)}'")
+        if pattern is None and pattern_id is None:
+            raise ValueError("'pattern_id' and 'pattern' can not be None at the same time")
         if pattern_id is None:
             pattern_id = f"quality_source_pattern_node={node_id}"
-        if pattern_id in self.epanet_api.getPatternNameID():
-            raise ValueError("Invalid 'pattern_id' -- " +
-                             f"there already exists a pattern with ID '{pattern_id}'")
 
         node_idx = self.epanet_api.getNodeIndex(node_id)
-        pattern_idx = self.epanet_api.addPattern(pattern_id, pattern)
+
+        if pattern is None:
+            pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
+        else:
+            pattern_idx = self.epanet_api.addPattern(pattern_id, pattern)
 
         self.epanet_api.api.ENsetnodevalue(node_idx, ToolkitConstants.EN_SOURCETYPE, source_type)
         self.epanet_api.setNodeSourceQuality(node_idx, source_strength)
@@ -2640,7 +3105,7 @@ class ScenarioSimulator():
         node_id : `str`
             ID of the node at which this external (bulk or surface) species injection source
             is placed.
-        pattern : `numpy.ndarray`
+        pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
             1d source pattern.
         source_type : `int`,
             Type of the external (bulk or surface) species injection source -- must be one of