epyt-flow 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

epyt_flow/simulation/scenario_simulator.py

@@ -5,7 +5,9 @@ import sys
 import os
 import pathlib
 import time
-from typing import Generator, Union
+from datetime import timedelta
+from datetime import datetime
+from typing import Generator, Union, Optional
 from copy import deepcopy
 import shutil
 import warnings
@@ -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,9 @@ class ScenarioSimulator():
         self._model_uncertainty = ModelUncertainty()
         self._sensor_noise = None
         self._sensor_config = None
-        self._controls = []
+        self._custom_controls = []
+        self._simple_controls = []
+        self._complex_controls = []
         self._system_events = []
         self._sensor_reading_events = []
         self.__running_simulation = False
@@ -168,6 +177,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 +189,12 @@ 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)
+            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 +339,46 @@ class ScenarioSimulator():
         self._sensor_config = sensor_config
 
     @property
-    def controls(self) -> list[AdvancedControlModule]:
+    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 control modules.
+        Gets all simple EPANET control rules.
 
         Returns
         -------
-        list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`]
-            All control modules.
+        list[:class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`]
+            All simple EPANET control rules.
         """
         self._adapt_to_network_changes()
 
-        return deepcopy(self._controls)
+        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._complex_controls)
 
     @property
     def leakages(self) -> list[Leakage]:
@@ -422,6 +466,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()
@@ -800,7 +970,10 @@ 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,
+                              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)
@@ -847,6 +1020,7 @@ class ScenarioSimulator():
         nodes_type = [self.epanet_api.TYPENODE[i] for i in self.epanet_api.getNodeTypeIndex()]
         nodes_coord = [self.epanet_api.api.ENgetcoord(node_idx)
                        for node_idx in self.epanet_api.getNodeIndex()]
+        nodes_comments = self.epanet_api.getNodeComment()
         node_tank_names = self.epanet_api.getNodeTankNameID()
 
         links_id = self.epanet_api.getLinkNameID()
@@ -866,10 +1040,12 @@ class ScenarioSimulator():
 
         # Build graph describing the topology
         nodes = []
-        for node_id, node_elevation, node_type, node_coord in zip(nodes_id, nodes_elevation,
-                                                                  nodes_type, nodes_coord):
+        for node_id, node_elevation, node_type, \
+                node_coord, node_comment in zip(nodes_id, nodes_elevation, nodes_type, nodes_coord,
+                                                nodes_comments):
             node_info = {"elevation": node_elevation,
                          "coord": node_coord,
+                         "comment": node_comment,
                          "type": node_type}
             if node_type == "TANK":
                 node_tank_idx = node_tank_names.index(node_id) + 1
@@ -878,9 +1054,10 @@ class ScenarioSimulator():
             nodes.append((node_id, node_info))
 
         links = []
-        for link_id, link_type, link, diameter, length, roughness_coeff, bulk_coeff, wall_coeff, loss_coeff \
-                in zip(links_id, links_type, links_data, links_diameter, links_length,
-                       links_roughness_coeff, links_bulk_coeff, links_wall_coeff, links_loss_coeff):
+        for link_id, link_type, link, diameter, length, roughness_coeff, bulk_coeff, \
+            wall_coeff, loss_coeff in zip(links_id, links_type, links_data, links_diameter,
+                                          links_length, links_roughness_coeff, links_bulk_coeff,
+                                          links_wall_coeff, links_loss_coeff):
             links.append((link_id, list(link),
                           {"type": link_type, "diameter": diameter, "length": length,
                            "roughness_coeff": roughness_coeff,
@@ -916,7 +1093,7 @@ class ScenarioSimulator():
 
             The default is None.
         """
-        from .scenario_visualizer import ScenarioVisualizer
+        from ..visualization import ScenarioVisualizer
         ScenarioVisualizer(self).show_plot(export_to_file)
 
     def randomize_demands(self) -> None:
@@ -989,7 +1166,10 @@ class ScenarioSimulator():
             raise ValueError(f"Inconsistent pattern shape '{pattern.shape}' " +
                              "detected. Expected a one dimensional array!")
 
-        self.epanet_api.addPattern(pattern_id, pattern)
+        pattern_idx = self.epanet_api.addPattern(pattern_id, pattern)
+        if pattern_idx == 0:
+            raise RuntimeError("Failed to add pattern! " +
+                               "Maybe pattern name contains invalid characters or is too long?")
 
     def get_node_demand_pattern(self, node_id: str) -> np.ndarray:
         """
@@ -1063,23 +1243,128 @@ class ScenarioSimulator():
         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_custom_control(self, control: CustomControlModule) -> None:
         """
-        Adds a control module to the scenario simulation.
+        Adds a custom control module to the scenario simulation.
 
         Parameters
         ----------
-        control : :class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`
-            Control module.
+        control : :class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`
+            Custom control module.
         """
         self._adapt_to_network_changes()
 
-        if not isinstance(control, AdvancedControlModule):
+        if not isinstance(control, CustomControlModule):
             raise TypeError("'control' must be an instance of " +
-                            "'epyt_flow.simulation.scada.AdvancedControlModule' not of " +
+                            "'epyt_flow.simulation.scada.CustomControlModule' not of " +
                             f"'{type(control)}'")
 
-        self._controls.append(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:
         """
@@ -1616,12 +1901,14 @@ class ScenarioSimulator():
         for event in self._system_events:
             event.reset()
 
-        if self._controls is not None:
-            for c in self._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.
 
@@ -1638,6 +1925,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
@@ -1657,7 +1951,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():
@@ -1674,6 +1970,7 @@ class ScenarioSimulator():
                 result[data_type] = None
 
         return ScadaData(**result,
+                         network_topo=self.get_topology(),
                          sensor_config=self._sensor_config,
                          sensor_reading_events=self._sensor_reading_events,
                          sensor_noise=self._sensor_noise,
@@ -1682,7 +1979,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.
@@ -1704,6 +2002,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
@@ -1729,6 +2034,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
@@ -1814,7 +2124,7 @@ class ScenarioSimulator():
                         "surface_species_concentration_raw": surface_species_concentrations,
                         "sensor_readings_time": np.array([0])}
             else:
-                data = ScadaData(sensor_config=self._sensor_config,
+                data = ScadaData(network_topo=self.get_topology(), sensor_config=self._sensor_config,
                                  bulk_species_node_concentration_raw=bulk_species_node_concentrations,
                                  bulk_species_link_concentration_raw=bulk_species_link_concentrations,
                                  surface_species_concentration_raw=surface_species_concentrations,
@@ -1858,7 +2168,8 @@ class ScenarioSimulator():
                                 "surface_species_concentration_raw": surface_species_concentrations,
                                 "sensor_readings_time": np.array([total_time])}
                     else:
-                        data = ScadaData(sensor_config=self._sensor_config,
+                        data = ScadaData(network_topo=self.get_topology(),
+                                         sensor_config=self._sensor_config,
                                          bulk_species_node_concentration_raw=
                                             bulk_species_node_concentrations,
                                          bulk_species_link_concentration_raw=
@@ -1880,7 +2191,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.
 
@@ -1897,6 +2210,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
@@ -1914,7 +2234,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():
@@ -1928,6 +2250,7 @@ class ScenarioSimulator():
             result[data_type] = np.concatenate(result[data_type], axis=0)
 
         return ScadaData(**result,
+                         network_topo=self.get_topology(),
                          sensor_config=self._sensor_config,
                          sensor_reading_events=self._sensor_reading_events,
                          sensor_noise=self._sensor_noise,
@@ -1937,6 +2260,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.
@@ -1960,6 +2284,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
@@ -1974,6 +2305,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()
@@ -2016,7 +2352,8 @@ class ScenarioSimulator():
                             "link_quality_data_raw": quality_link_data,
                             "sensor_readings_time": np.array([total_time])}
                 else:
-                    data = ScadaData(sensor_config=self._sensor_config,
+                    data = ScadaData(network_topo=self.get_topology(),
+                                     sensor_config=self._sensor_config,
                                      node_quality_data_raw=quality_node_data,
                                      link_quality_data_raw=quality_link_data,
                                      sensor_readings_time=np.array([total_time]),
@@ -2032,7 +2369,7 @@ class ScenarioSimulator():
                 yield data
 
             # Next
-            tstep = self.epanet_api.nextQualityAnalysisStep()
+            tstep = self.epanet_api.stepQualityAnalysisTimeLeft()
 
         self.epanet_api.closeHydraulicAnalysis()
 
@@ -2092,6 +2429,7 @@ class ScenarioSimulator():
             result[data_type] = np.concatenate(result[data_type], axis=0)
 
         result = ScadaData(**result,
+                           network_topo=self.get_topology(),
                            sensor_config=self._sensor_config,
                            sensor_reading_events=self._sensor_reading_events,
                            sensor_noise=self._sensor_noise,
@@ -2213,7 +2551,8 @@ class ScenarioSimulator():
                 link_valve_idx = self.epanet_api.getLinkValveIndex()
                 valves_state_data = self.epanet_api.getLinkStatus(link_valve_idx).reshape(1, -1)
 
-                scada_data = ScadaData(sensor_config=self._sensor_config,
+                scada_data = ScadaData(network_topo=self.get_topology(),
+                                       sensor_config=self._sensor_config,
                                        pressure_data_raw=pressure_data,
                                        flow_data_raw=flow_data,
                                        demand_data_raw=demand_data,
@@ -2254,7 +2593,7 @@ class ScenarioSimulator():
                     yield data
 
                 # Apply control modules
-                for control in self._controls:
+                for control in self._custom_controls:
                     control.step(scada_data)
 
                 # Next
@@ -2272,16 +2611,6 @@ class ScenarioSimulator():
             self.__running_simulation = False
             raise ex
 
-    def run_simulation_as_generator(self, hyd_export: str = None, verbose: bool = False,
-                                    support_abort: bool = False,
-                                    return_as_dict: bool = False,
-                                    frozen_sensor_config: bool = False,
-                                    ) -> Generator[Union[ScadaData, dict], bool, None]:
-        warnings.warn("'run_simulation_as_generator' is deprecated and will be removed in " +
-                      "future releases -- use 'run_hydraulic_simulation_as_generator' instead")
-        return self.run_hydraulic_simulation_as_generator(hyd_export, verbose, support_abort,
-                                                          return_as_dict, frozen_sensor_config)
-
     def run_simulation(self, hyd_export: str = None, verbose: bool = False,
                        frozen_sensor_config: bool = False) -> ScadaData:
         """
@@ -2574,6 +2903,202 @@ class ScenarioSimulator():
 
         return list(set(events_times))
 
+    def set_pump_energy_price_pattern(self, pump_id: str, pattern: np.ndarray,
+                                      pattern_id: Optional[str] = None) -> None:
+        """
+        Specifies/sets the energy price pattern of a given pump.
+
+        Overwrites any existing (energy price) patterns of the given pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump.
+        pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
+            Pattern of multipliers.
+        pattern_id : `str`, optional
+            ID of the pattern.
+            If not specified, 'energy_price_{pump_id}' will be used as the pattern ID.
+
+            The default is None.
+        """
+        if not isinstance(pump_id, str):
+            raise TypeError(f"'pump_id' must be an instance of 'str' but not of '{type(pump_id)}'")
+        if pump_id not in self._sensor_config.pumps:
+            raise ValueError(f"Unknown pump '{pump_id}'")
+        if not isinstance(pattern, np.ndarray):
+            raise TypeError("'pattern' must be an instance of 'numpy.ndarray' " +
+                            f"but no of '{type(pattern)}'")
+        if len(pattern.shape) > 1:
+            raise ValueError("'pattern' must be 1-dimensional")
+        if pattern_id is not None:
+            if not isinstance(pattern_id, str):
+                raise TypeError("'pattern_id' must be an instance of 'str' " +
+                                f"but not of '{type(pattern_id)}'")
+        else:
+            pattern_id = f"energy_price_{pump_id}"
+
+        pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
+        if pattern_idx != 0:
+            warnings.warn(f"Overwriting existing pattern '{pattern_id}'")
+
+        pump_idx = self.epanet_api.getLinkIndex(pump_id)
+        pattern_idx = self.epanet_api.getLinkPumpEPat(pump_idx)
+        if pattern_idx != 0:
+            warnings.warn(f"Overwriting existing energy price pattern of pump '{pump_id}'")
+
+        self.add_pattern(pattern_id, pattern)
+        pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
+        self.epanet_api.setLinkPumpEPat(pattern_idx)
+
+    def get_pump_energy_price_pattern(self, pump_id: str) -> np.ndarray:
+        """
+        Returns the energy price pattern of a given pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump.
+
+        Returns
+        -------
+        `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
+            Energy price pattern. None, if none exists.
+        """
+        if not isinstance(pump_id, str):
+            raise TypeError(f"'pump_id' must be an instance of 'str' but not of '{type(pump_id)}'")
+        if pump_id not in self._sensor_config.pumps:
+            raise ValueError(f"Unknown pump '{pump_id}'")
+
+        pump_idx = self.epanet_api.getLinkIndex(pump_id)
+        pattern_idx = self.epanet_api.getLinkPumpEPat(pump_idx)
+        if pattern_idx == 0:
+            return None
+        else:
+            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 get_pump_energy_price(self, pump_id: str) -> float:
+        """
+        Returns the energy price of a given pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump.
+
+        Returns
+        -------
+        `float`
+            Energy price.
+        """
+        if not isinstance(pump_id, str):
+            raise TypeError(f"'pump_id' must be an instance of 'str' but not of '{type(pump_id)}'")
+        if pump_id not in self._sensor_config.pumps:
+            raise ValueError(f"Unknown pump '{pump_id}'")
+
+        pump_idx = self.epanet_api.getLinkIndex(pump_id)
+        return self.epanet_api.getLinkPumpECost(pump_idx)
+
+    def set_pump_energy_price(self, pump_id, price: float) -> None:
+        """
+        Sets the energy price of a given pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump.
+        price : `float`
+            Energy price.
+        """
+        if not isinstance(pump_id, str):
+            raise TypeError(f"'pump_id' must be an instance of 'str' but not of '{type(pump_id)}'")
+        if pump_id not in self._sensor_config.pumps:
+            raise ValueError(f"Unknown pump '{pump_id}'")
+        if not isinstance(price, float):
+            raise TypeError(f"'price' must be an instance of 'float' but not of '{type(price)}'")
+        if price <= 0:
+            raise ValueError("'price' must be positive")
+
+        pump_idx = self._sensor_config.pumps.index(pump_id) + 1
+        pumps_energy_price = self.epanet_api.getLinkPumpECost()
+        pumps_energy_price[pump_idx - 1] = price
+
+        self.epanet_api.setLinkPumpECost(pumps_energy_price)
+
+    def set_initial_link_status(self, link_id: str, status: int) -> None:
+        """
+        Sets the initial status (open or closed) of a given link.
+
+        Parameters
+        ----------
+        link_id : `str`
+            ID of the link.
+        status : `int`
+            Initial status of the link. Must be one of the following EPANET constants:
+
+                - EN_CLOSED   = 0
+                - EN_OPEN     = 1
+        """
+        if not isinstance(link_id, str):
+            raise TypeError(f"'link_id' must be an instance of 'str' but not of '{type(link_id)}'")
+        if link_id not in self._sensor_config.pumps:
+            raise ValueError("Invalid link ID '{link_id}'")
+        if not isinstance(status, int):
+            raise TypeError(f"'status' must be an instance of 'int' but not of '{type(status)}'")
+        if status not in [ActuatorConstants.EN_CLOSED, ActuatorConstants.EN_OPEN]:
+            raise ValueError(f"Invalid link status '{status}'")
+
+        link_idx = self.epanet_api.getLinkIndex(link_id)
+        self.epanet_api.setLinkInitialStatus(link_idx, status)
+
+    def set_initial_pump_speed(self, pump_id: str, speed: float) -> None:
+        """
+        Sets the initial pump speed of a given pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump.
+        speed : `float`
+            Initial speed of the pump.
+        """
+        if not isinstance(pump_id, str):
+            raise TypeError(f"'pump_id' must be an instance of 'str' but not of '{type(pump_id)}'")
+        if pump_id not in self._sensor_config.pumps:
+            raise ValueError("Invalid pump ID '{tank_id}'")
+        if not isinstance(speed, float):
+            raise TypeError(f"'speed' must be an instance of 'int' but not of '{type(speed)}'")
+        if speed < 0:
+            raise ValueError("'speed' can not be negative")
+
+        pump_idx = self.epanet_api.getLinkIndex(pump_id)
+        self.epanet_api.setLinkInitialSetting(pump_idx, speed)
+
+    def set_initial_tank_level(self, tank_id, level: int) -> None:
+        """
+        Sets the initial water level of a given tank.
+
+        Parameters
+        ----------
+        tank_id : `str`
+            ID of the tank.
+        level : `int`
+            Initial water level in the tank.
+        """
+        if not isinstance(tank_id, str):
+            raise TypeError(f"'tank_id' must be an instance of 'str' but not of '{type(tank_id)}'")
+        if tank_id not in self._sensor_config.tanks:
+            raise ValueError("Invalid tank ID '{tank_id}'")
+        if not isinstance(level, int):
+            raise TypeError(f"'level' must be an instance of 'int' but not of '{type(level)}'")
+        if level < 0:
+            raise ValueError("'level' can not be negative")
+
+        tank_idx = self.epanet_api.getNodeIndex(tank_id)
+        self.epanet_api.setNodeTankInitialLevel(tank_idx, level)
+
     def __warn_if_quality_set(self):
         qual_info = self.epanet_api.getQualityInfo()
         if qual_info.QualityCode != ToolkitConstants.EN_NONE:
@@ -2686,7 +3211,7 @@ class ScenarioSimulator():
         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}"
+            pattern_id = f"qual_src_pat_{node_id}"
 
         node_idx = self.epanet_api.getNodeIndex(node_id)
 
@@ -2694,11 +3219,220 @@ class ScenarioSimulator():
             pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
         else:
             pattern_idx = self.epanet_api.addPattern(pattern_id, pattern)
+        if pattern_idx == 0:
+            raise RuntimeError("Failed to add/get pattern! " +
+                               "Maybe pattern name contains invalid characters or is too long?")
 
         self.epanet_api.api.ENsetnodevalue(node_idx, ToolkitConstants.EN_SOURCETYPE, source_type)
         self.epanet_api.setNodeSourceQuality(node_idx, source_strength)
         self.epanet_api.setNodeSourcePatternIndex(node_idx, pattern_idx)
 
+    def set_initial_node_quality(self, node_id: str, initial_quality: float) -> None:
+        """
+        Specifies the initial quality at a given node.
+        Quality represents concentration for chemicals, hours for water age,
+        or percent for source tracing.
+
+        Parameters
+        ----------
+        node_id : `str`
+            ID of the node.
+        initial_quality : `float`
+            Initial node quality.
+        """
+        self.set_quality_parameters(initial_quality={node_id, initial_quality})
+
+    def set_quality_parameters(self, initial_quality: Optional[dict[str, float]] = None,
+                               order_wall: Optional[int] = None, order_tank: Optional[int] = None,
+                               order_bulk: Optional[int] = None,
+                               global_wall_reaction_coefficient: Optional[float] = None,
+                               global_bulk_reaction_coefficient: Optional[float] = None,
+                               local_wall_reaction_coefficient: Optional[dict[str, float]] = None,
+                               local_bulk_reaction_coefficient: Optional[dict[str, float]] = None,
+                               local_tank_reaction_coefficient: Optional[dict[str, float]] = None,
+                               limiting_potential: Optional[float] = None) -> None:
+        """
+        Specifies some parameters of the EPANET quality analysis.
+        Note that those parameters are only relevant for EPANET but not for EPANET-MSX.
+
+        Parameters
+        ----------
+        initial_quality : `dict[str, float]`, optional
+            Specifies the initial quality (value in the dictionary) at nodes
+            (key in the dictionary).
+            Quality represents concentration for chemicals, hours for water age,
+            or percent for source tracing.
+
+            The default is None.
+        order_wall : `int`, optional
+            Specifies the order of reactions occurring in the bulk fluid at pipe walls.
+            Value for wall reactions must be either 0 or 1.
+            If not specified, the default reaction order is 1.0.
+
+            The default is None.
+        order_bulk : `int`, optional
+            Specifies the order of reactions occurring in the bulk fluid in tanks.
+            Value must be either 0 or 1.
+            If not specified, the default reaction order is 1.0.
+
+            The default is None.
+        global_wall_reaction_coefficient : `float`, optional
+            Specifies the global value for all pipe wall reaction coefficients (pipes and tanks).
+            If not specified, the default value is zero.
+
+            The default is None.
+        global_bulk_reaction_coefficient : `float`, optional
+            Specifies the global value for all bulk reaction coefficients (pipes and tanks).
+            If not specified, the default value is zero.
+
+            The default is None.
+        local_wall_reaction_coefficient : `dict[str, float]`, optional
+            Overrides the global reaction coefficients for specific pipes (key in dictionary).
+
+            The default is None.
+        local_bulk_reaction_coefficient : `dict[str, float]`, optional
+            Overrides the global reaction coefficients for specific pipes (key in dictionary).
+
+            The default is None.
+        local_tank_reaction_coefficient : `dict[str, float]`, optional
+            Overrides the global reaction coefficients for specific tanks (key in dictionary).
+
+            The default is None.
+        limiting_potential : `float`, optional
+            Specifies that reaction rates are proportional to the difference between the
+            current concentration and some (specified) limiting potential value.
+
+            The default is None.
+        """
+        if initial_quality is not None:
+            if not isinstance(initial_quality, dict):
+                raise TypeError("'initial_quality' must be an instance of 'dict[str, float]' " +
+                                f"but not of '{type(initial_quality)}'")
+            if any(not isinstance(key, str) or not isinstance(value, float)
+                   for key, value in initial_quality):
+                raise TypeError("'initial_quality' must be an instance of 'dict[str, float]'")
+            for node_id, node_init_qual in initial_quality:
+                if node_id not in self._sensor_config.nodes:
+                    raise ValueError(f"Invalid node ID '{node_id}'")
+                if node_init_qual < 0:
+                    raise ValueError(f"{node_id}: Initial node quality can not be negative")
+
+            init_qual = self.epanet_api.getNodeInitialQuality()
+            for node_id, node_init_qual in initial_quality:
+                node_idx = self.epanet_api.getNodeIndex(node_id) - 1
+                init_qual[node_idx] = node_init_qual
+
+            self.epanet_api.setNodeInitialQuality(init_qual)
+
+        if order_wall is not None:
+            if not isinstance(order_wall, int):
+                raise TypeError("'order_wall' must be an instance of 'int' " +
+                                f"but not of '{type(order_wall)}'")
+            if order_wall not in [0, 1]:
+                raise ValueError(f"Invalid value '{order_wall}' for order_wall")
+
+            self.epanet_api.setOptionsPipeWallReactionOrder(order_wall)
+
+        if order_bulk is not None:
+            if not isinstance(order_bulk, int):
+                raise TypeError("'order_bulk' must be an instance of 'int' " +
+                                f"but not of '{type(order_bulk)}'")
+            if order_bulk not in [0, 1]:
+                raise ValueError(f"Invalid value '{order_bulk}' for order_bulk")
+
+            self.epanet_api.setOptionsPipeBulkReactionOrder(order_bulk)
+
+        if order_tank is not None:
+            if not isinstance(order_tank, int):
+                raise TypeError("'order_tank' must be an instance of 'int' " +
+                                f"but not of '{type(order_tank)}'")
+            if order_tank not in [0, 1]:
+                raise ValueError(f"Invalid value '{order_tank}' for order_wall")
+
+            self.epanet_api.setOptionsTankBulkReactionOrder(order_tank)
+
+        if global_wall_reaction_coefficient is not None:
+            if not isinstance(global_wall_reaction_coefficient, float):
+                raise TypeError("'global_wall_reaction_coefficient' must be an instance of " +
+                                f"'float' but not of '{type(global_wall_reaction_coefficient)}'")
+
+            wall_reaction_coeff = self.epanet_api.getLinkWallReactionCoeff()
+            for i in range(len(wall_reaction_coeff)):
+                wall_reaction_coeff[i] = global_wall_reaction_coefficient
+
+            self.epanet_api.setLinkWallReactionCoeff(wall_reaction_coeff)
+
+        if global_bulk_reaction_coefficient is not None:
+            if not isinstance(global_bulk_reaction_coefficient, float):
+                raise TypeError("'global_bulk_reaction_coefficient' must be an instance of " +
+                                f"'float' but not of '{type(global_bulk_reaction_coefficient)}'")
+
+            bulk_reaction_coeff = self.epanet_api.getLinkBulkReactionCoeff()
+            for i in range(len(bulk_reaction_coeff)):
+                bulk_reaction_coeff[i] = global_bulk_reaction_coefficient
+
+            self.epanet_api.setLinkBulkReactionCoeff(bulk_reaction_coeff)
+
+        if local_wall_reaction_coefficient is not None:
+            if not isinstance(local_wall_reaction_coefficient, dict):
+                raise TypeError("'local_wall_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]' but not of " +
+                                f"'{type(local_wall_reaction_coefficient)}'")
+            if any(not isinstance(key, str) or not isinstance(value, float)
+                   for key, value in local_wall_reaction_coefficient):
+                raise TypeError("'local_wall_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]'")
+            for link_id, _ in local_wall_reaction_coefficient:
+                if link_id not in self._sensor_config.links:
+                    raise ValueError(f"Invalid link ID '{link_id}'")
+
+            for link_id, link_reaction_coeff in local_wall_reaction_coefficient:
+                link_idx = self.epanet_api.getLinkIndex(link_id)
+                self.epanet_api.setLinkWallReactionCoeff(link_idx, link_reaction_coeff)
+
+        if local_bulk_reaction_coefficient is not None:
+            if not isinstance(local_bulk_reaction_coefficient, dict):
+                raise TypeError("'local_bulk_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]' but not of " +
+                                f"'{type(local_bulk_reaction_coefficient)}'")
+            if any(not isinstance(key, str) or not isinstance(value, float)
+                   for key, value in local_bulk_reaction_coefficient):
+                raise TypeError("'local_bulk_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]'")
+            for link_id, _ in local_bulk_reaction_coefficient:
+                if link_id not in self._sensor_config.links:
+                    raise ValueError(f"Invalid link ID '{link_id}'")
+
+            for link_id, link_reaction_coeff in local_bulk_reaction_coefficient:
+                link_idx = self.epanet_api.getLinkIndex(link_id)
+                self.epanet_api.setLinkBulkReactionCoeff(link_idx, link_reaction_coeff)
+
+        if local_tank_reaction_coefficient is not None:
+            if not isinstance(local_tank_reaction_coefficient, dict):
+                raise TypeError("'local_tank_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]' but not of " +
+                                f"'{type(local_tank_reaction_coefficient)}'")
+            if any(not isinstance(key, str) or not isinstance(value, float)
+                   for key, value in local_tank_reaction_coefficient):
+                raise TypeError("'local_tank_reaction_coefficient' must be an instance " +
+                                "of 'dict[str, float]'")
+            for tank_id, _ in local_tank_reaction_coefficient:
+                if tank_id not in self._sensor_config.tanks:
+                    raise ValueError(f"Invalid tank ID '{tank_id}'")
+
+            for tank_id, tank_reaction_coeff in local_tank_reaction_coefficient:
+                tank_idx = self.epanet_api.getNodeTankIndex(tank_id)
+                self.epanet_api.setNodeTankBulkReactionCoeff(tank_idx, tank_reaction_coeff)
+
+        if limiting_potential is not None:
+            if not isinstance(limiting_potential, float):
+                raise TypeError("'limiting_potential' must be an instance of 'float' " +
+                                f"but not of '{type(limiting_potential)}'")
+            if limiting_potential < 0:
+                raise ValueError("'limiting_potential' can not be negative")
+
+            self.epanet_api.setOptionsLimitingConcentration(limiting_potential)
+
     def enable_sourcetracing_analysis(self, trace_node_id: str) -> None:
         """
         Set source tracing analysis -- i.e. tracks the percentage of flow from a given node
@@ -2727,6 +3461,8 @@ class ScenarioSimulator():
         """
         Adds a new external (bulk or surface) species injection source at a particular node.
 
+        Only for EPANET-MSX scenarios.
+
         Parameters
         ----------
         species_id : `str`
@@ -2782,3 +3518,81 @@ class ScenarioSimulator():
         self.epanet_api.addMSXPattern(pattern_id, pattern)
         self.epanet_api.setMSXSources(node_id, species_id, source_type_, source_strength,
                                       pattern_id)
+
+    def set_bulk_species_node_initial_concentrations(self,
+                                                     inital_conc: dict[str, list[tuple[str, float]]]
+                                                     ) -> None:
+        """
+        Species the initial bulk species concentration at nodes.
+
+        Only for EPANET-MSX scenarios.
+
+        Parameters
+        ----------
+        inital_conc : `dict[str, list[tuple[str, float]]]`
+            Initial concentration of species (key) at nodes -- i.e.
+            value: list of node ID and initial concentration.
+        """
+        if not isinstance(inital_conc, dict) or \
+                any(not isinstance(species_id, str) or not isinstance(node_initial_conc, list)
+                    for species_id, node_initial_conc in inital_conc.items()) or \
+                any(not isinstance(node_initial_conc, tuple)
+                    for node_initial_conc in inital_conc.values()) or \
+                any(not isinstance(node_id, str) or not isinstance(conc, float)
+                    for node_id, conc in inital_conc.values()):
+            raise TypeError("'inital_conc' must be an instance of " +
+                            "'dict[str, list[tuple[str, float]]'")
+        if any(species_id not in self.sensor_config.bulk_species
+               for species_id in inital_conc.keys()):
+            raise ValueError("Unknown bulk species in 'inital_conc'")
+        if any(node_id not in self.sensor_config.nodes for node_id, _ in inital_conc.values()):
+            raise ValueError("Unknown node ID in 'inital_conc'")
+        if any(conc < 0 for _, conc in inital_conc.values()):
+            raise ValueError("Initial node concentration can not be negative")
+
+        for species_id, node_initial_conc in inital_conc.items():
+            species_idx, = self.epanet_api.getMSXSpeciesIndex([species_id])
+
+            for node_id, initial_conc in node_initial_conc:
+                node_idx = self.epanet_api.getNodeIndex(node_id)
+                self.epanet_api.msx.MSXsetinitqual(ToolkitConstants.MSX_NODE, node_idx, species_idx,
+                                                   initial_conc)
+
+    def set_species_link_initial_concentrations(self,
+                                                inital_conc: dict[str, list[tuple[str, float]]]
+                                                ) -> None:
+        """
+        Species the initial (bulk or surface) species concentration at links.
+
+        Only for EPANET-MSX scenarios.
+
+        Parameters
+        ----------
+        inital_conc : `dict[str, list[tuple[str, float]]]`
+            Initial concentration of species (key) at links -- i.e.
+            value: list of link ID and initial concentration.
+        """
+        if not isinstance(inital_conc, dict) or \
+                any(not isinstance(species_id, str) or not isinstance(link_initial_conc, list)
+                    for species_id, link_initial_conc in inital_conc.items()) or \
+                any(not isinstance(link_initial_conc, tuple)
+                    for link_initial_conc in inital_conc.values()) or \
+                any(not isinstance(link_id, str) or not isinstance(conc, float)
+                    for link_id, conc in inital_conc.values()):
+            raise TypeError("'inital_conc' must be an instance of " +
+                            "'dict[str, list[tuple[str, float]]'")
+        if any(species_id not in self.sensor_config.bulk_species
+               for species_id in inital_conc.keys()):
+            raise ValueError("Unknown bulk species in 'inital_conc'")
+        if any(link_id not in self.sensor_config.links for link_id, _ in inital_conc.values()):
+            raise ValueError("Unknown link ID in 'inital_conc'")
+        if any(conc < 0 for _, conc in inital_conc.values()):
+            raise ValueError("Initial link concentration can not be negative")
+
+        for species_id, link_initial_conc in inital_conc.items():
+            species_idx, = self.epanet_api.getMSXSpeciesIndex([species_id])
+
+            for link_id, initial_conc in link_initial_conc:
+                link_idx = self.epanet_api.getLinkIndex(link_id)
+                self.epanet_api.msx.MSXsetinitqual(ToolkitConstants.MSX_LINK, link_idx, species_idx,
+                                                   initial_conc)