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

epyt_flow/simulation/scenario_simulator.py

@@ -5,9 +5,10 @@ import sys
 import os
 import pathlib
 import time
+import itertools
 from datetime import timedelta
 from datetime import datetime
-from typing import Generator, Union
+from typing import Generator, Union, Optional
 from copy import deepcopy
 import shutil
 import warnings
@@ -15,9 +16,8 @@ import random
 import math
 import uuid
 import numpy as np
-from epyt import epanet
-from epyt.epanet import ToolkitConstants
 from tqdm import tqdm
+from epyt.epanet import ToolkitConstants
 
 from .scenario_config import ScenarioConfig
 from .sensor_config import SensorConfig, areaunit_to_id, massunit_to_id, qualityunit_to_id, \
@@ -62,7 +62,7 @@ class ScenarioSimulator():
 
     Attributes
     ----------
-    epanet_api : `epyt.epanet`
+    epanet_api : :class:`~epyt_flow.simulation.backend.my_epyt.EPyT`
         API to EPANET and EPANET-MSX.
     _model_uncertainty : :class:`~epyt_flow.uncertainty.model_uncertainty.ModelUncertainty`, protected
         Model uncertainty.
@@ -112,7 +112,6 @@ class ScenarioSimulator():
         self._model_uncertainty = ModelUncertainty()
         self._sensor_noise = None
         self._sensor_config = None
-        self._advanced_controls = []
         self._custom_controls = []
         self._simple_controls = []
         self._complex_controls = []
@@ -120,6 +119,7 @@ class ScenarioSimulator():
         self._sensor_reading_events = []
         self.__running_simulation = False
 
+        # Check availability of custom EPANET libraries
         custom_epanet_lib = None
         custom_epanetmsx_lib = None
         if sys.platform.startswith("linux") or sys.platform.startswith("darwin") :
@@ -136,48 +136,49 @@ class ScenarioSimulator():
             if os.path.isfile(os.path.join(path_to_custom_libs, libepanetmsx_name)):
                 custom_epanetmsx_lib = os.path.join(path_to_custom_libs, libepanetmsx_name)
 
-        with warnings.catch_warnings():
-            # Treat all warnings as exceptions when trying to load .inp and .msx files
-            warnings.simplefilter('error')
+        # Workaround for EPyT bug concerning parallel simulations (see EPyT issue #54):
+        # 1. Create random tmp folder (make sure it is unique!)
+        # 2. Copy .inp and .msx file there
+        # 3. Use those copies  when loading EPyT
+        tmp_folder_path = os.path.join(get_temp_folder(), f"{random.randint(int(1e5), int(1e7))}{time.time()}")
+        pathlib.Path(tmp_folder_path).mkdir(parents=True, exist_ok=False)
 
-            # Workaround for EPyT bug concerning parallel simulations (see EPyT issue #54):
-            # 1. Create random tmp folder (make sure it is unique!)
-            # 2. Copy .inp and .msx file there
-            # 3. Use those copies  when loading EPyT
-            tmp_folder_path = os.path.join(get_temp_folder(), f"{random.randint(int(1e5), int(1e7))}{time.time()}")
-            pathlib.Path(tmp_folder_path).mkdir(parents=True, exist_ok=False)
+        def __file_exists(file_in: str) -> bool:
+            try:
+                return pathlib.Path(file_in).is_file()
+            except Exception:
+                return False
 
-            def __file_exists(file_in: str) -> bool:
-                try:
-                    return pathlib.Path(file_in).is_file()
-                except Exception:
-                    return False
+        if not __file_exists(self.__f_inp_in):
+            my_f_inp_in = self.__f_inp_in
+            self.__my_f_inp_in = None
+        else:
+            my_f_inp_in = os.path.join(tmp_folder_path, pathlib.Path(self.__f_inp_in).name)
+            shutil.copyfile(self.__f_inp_in, my_f_inp_in)
+            self.__my_f_inp_in = my_f_inp_in
 
-            if not __file_exists(self.__f_inp_in):
-                my_f_inp_in = self.__f_inp_in
-                self.__my_f_inp_in = None
+        if self.__f_msx_in is not None:
+            if not __file_exists(self.__f_msx_in):
+                my_f_msx_in = self.__f_msx_in
             else:
-                my_f_inp_in = os.path.join(tmp_folder_path, pathlib.Path(self.__f_inp_in).name)
-                shutil.copyfile(self.__f_inp_in, my_f_inp_in)
-                self.__my_f_inp_in = my_f_inp_in
+                my_f_msx_in = os.path.join(tmp_folder_path, pathlib.Path(self.__f_msx_in).name)
+                shutil.copyfile(self.__f_msx_in, my_f_msx_in)
+        else:
+            my_f_msx_in = None
 
-            if self.__f_msx_in is not None:
-                if not __file_exists(self.__f_msx_in):
-                    my_f_msx_in = self.__f_msx_in
-                else:
-                    my_f_msx_in = os.path.join(tmp_folder_path, pathlib.Path(self.__f_msx_in).name)
-                    shutil.copyfile(self.__f_msx_in, my_f_msx_in)
-            else:
-                my_f_msx_in = None
+        from .backend import EPyT   # Workaround: Sphinx autodoc "importlib.import_module TypeError: __mro_entries__"
+        self.epanet_api = EPyT(my_f_inp_in, ph=self.__f_msx_in is None,
+                               customlib=custom_epanet_lib, loadfile=True,
+                               display_msg=epanet_verbose,
+                               display_warnings=False)
 
-            self.epanet_api = epanet(my_f_inp_in, ph=self.__f_msx_in is None,
-                                     customlib=custom_epanet_lib, loadfile=True,
-                                     display_msg=epanet_verbose,
-                                     display_warnings=False)
+        if self.__f_msx_in is not None:
+            self.epanet_api.loadMSXFile(my_f_msx_in, customMSXlib=custom_epanetmsx_lib)
 
-            if self.__f_msx_in is not None:
-                self.epanet_api.loadMSXFile(my_f_msx_in, customMSXlib=custom_epanetmsx_lib)
+        # Do not raise exceptions in the case of EPANET warnings and errors
+        self.epanet_api.set_error_handling(False)
 
+        # Parse and initialize scenario
         self._simple_controls = self._parse_simple_control_rules()
         self._complex_controls = self._parse_complex_control_rules()
 
@@ -190,9 +191,6 @@ class ScenarioSimulator():
             self._sensor_noise = scenario_config.sensor_noise
             self._sensor_config = scenario_config.sensor_config
 
-            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:
@@ -342,22 +340,6 @@ class ScenarioSimulator():
 
         self._sensor_config = sensor_config
 
-    @property
-    def advanced_controls(self) -> list:
-        """
-        Returns all advanced control modules.
-
-        Returns
-        -------
-        list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`]
-            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]:
         """
@@ -990,7 +972,6 @@ 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(),
-                              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,
@@ -1041,6 +1022,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()
@@ -1060,21 +1042,29 @@ 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
                 node_info["diameter"] = float(self.epanet_api.getNodeTankDiameter(node_tank_idx))
+                node_info["volume"] = float(self.epanet_api.getNodeTankVolume(node_tank_idx))
+                node_info["max_level"] = float(self.epanet_api.getNodeTankMaximumWaterLevel(node_tank_idx))
+                node_info["min_level"] = float(self.epanet_api.getNodeTankMinimumWaterLevel(node_tank_idx))
+                node_info["mixing_fraction"] = float(self.epanet_api.getNodeTankMixingFraction(node_tank_idx))
+                #node_info["mixing_model"] = int(self.epanet_api.getNodeTankMixingModelCode(node_tank_idx)[0])
 
             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,
@@ -1110,7 +1100,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:
@@ -1155,7 +1145,14 @@ class ScenarioSimulator():
         `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
             The pattern -- i.e. multiplier factors over time.
         """
+        if not isinstance(pattern_id, str):
+            raise TypeError("'pattern_id' must be an instance of 'str' " +
+                            f"but not of '{type(pattern_id)}'")
+
         pattern_idx = self.epanet_api.getPatternIndex(pattern_id)
+        if pattern_idx == 0:
+            raise ValueError(f"Unknown pattern '{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)])
@@ -1183,7 +1180,41 @@ 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_base_demand(self, node_id: str) -> float:
+        """
+        Returns the base demand of a given node. None, if there does not exist any base demand.
+
+        Note that base demands are summed up in the case of different demand categories.
+
+        Parameters
+        ----------
+        node_id : `str`
+            ID of the node.
+
+        Returns
+        -------
+        `float`
+            Base demand.
+        """
+        if node_id not in self._sensor_config.nodes:
+            raise ValueError(f"Unknown node '{node_id}'")
+
+        node_idx = self.epanet_api.getNodeIndex(node_id)
+        n_demand_categories = self.epanet_api.getNodeDemandCategoriesNumber(node_idx)
+
+        if n_demand_categories == 0:
+            return None
+        else:
+            base_demand = 0
+            for demand_category in range(n_demand_categories):
+                base_demand += self.epanet_api.getNodeBaseDemands(node_idx)[demand_category + 1]
+
+            return base_demand
 
     def get_node_demand_pattern(self, node_id: str) -> np.ndarray:
         """
@@ -1200,6 +1231,12 @@ class ScenarioSimulator():
         `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
             The demand pattern -- i.e. multiplier factors over time.
         """
+        if not isinstance(node_id, str):
+            raise TypeError("'node_id' must be an instance of 'str' " +
+                            f"but not of '{type(node_id)}'")
+        if node_id not in self._sensor_config.nodes:
+            raise ValueError(f"Unknown node '{node_id}'")
+
         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]
@@ -1257,25 +1294,6 @@ class ScenarioSimulator():
         self.epanet_api.setNodeJunctionData(node_idx, self.epanet_api.getNodeElevations(node_idx),
                                             base_demand, demand_pattern_id)
 
-    def add_advanced_control(self, control) -> None:
-        """
-        Adds an advanced control module to the scenario simulation.
-
-        Parameters
-        ----------
-        control : :class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`
-            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._advanced_controls.append(control)
-
     def add_custom_control(self, control: CustomControlModule) -> None:
         """
         Adds a custom control module to the scenario simulation.
@@ -1934,9 +1952,6 @@ class ScenarioSimulator():
         for event in self._system_events:
             event.reset()
 
-        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)
@@ -2006,6 +2021,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,
@@ -2069,6 +2085,8 @@ class ScenarioSimulator():
         reporting_time_step = self.epanet_api.getTimeReportingStep()
         hyd_time_step = self.epanet_api.getTimeHydraulicStep()
 
+        network_topo = self.get_topology()
+
         if use_quality_time_step_as_reporting_time_step is True:
             quality_time_step = self.epanet_api.getMSXTimeStep()
             reporting_time_step = quality_time_step
@@ -2159,7 +2177,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=network_topo, 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,
@@ -2203,7 +2221,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=network_topo,
+                                         sensor_config=self._sensor_config,
                                          bulk_species_node_concentration_raw=
                                             bulk_species_node_concentrations,
                                          bulk_species_link_concentration_raw=
@@ -2284,6 +2303,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,
@@ -2343,6 +2363,8 @@ class ScenarioSimulator():
             requested_time_step = quality_time_step
             reporting_time_step = quality_time_step
 
+        network_topo = self.get_topology()
+
         self.epanet_api.useHydraulicFile(hyd_file_in)
 
         self.epanet_api.openQualityAnalysis()
@@ -2371,10 +2393,11 @@ class ScenarioSimulator():
                         pass
 
             # Compute current time step
-            t = self.epanet_api.runQualityAnalysis()
+            t = self.epanet_api.api.ENrunQ()
             total_time = t
 
             # Fetch data
+            error_code = self.epanet_api.get_last_error_code()
             quality_node_data = self.epanet_api.getNodeActualQuality().reshape(1, -1)
             quality_link_data = self.epanet_api.getLinkActualQuality().reshape(1, -1)
 
@@ -2383,12 +2406,15 @@ class ScenarioSimulator():
                 if return_as_dict is True:
                     data = {"node_quality_data_raw": quality_node_data,
                             "link_quality_data_raw": quality_link_data,
-                            "sensor_readings_time": np.array([total_time])}
+                            "sensor_readings_time": np.array([total_time]),
+                            "warnings_code": np.array([error_code])}
                 else:
-                    data = ScadaData(sensor_config=self._sensor_config,
+                    data = ScadaData(network_topo=network_topo,
+                                     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]),
+                                     warnings_code=np.array([error_code]),
                                      sensor_reading_events=self._sensor_reading_events,
                                      sensor_noise=self._sensor_noise,
                                      frozen_sensor_config=frozen_sensor_config)
@@ -2401,9 +2427,9 @@ class ScenarioSimulator():
                 yield data
 
             # Next
-            tstep = self.epanet_api.stepQualityAnalysisTimeLeft()
+            tstep = self.epanet_api.api.ENstepQ()
 
-        self.epanet_api.closeHydraulicAnalysis()
+        self.epanet_api.closeQualityAnalysis()
 
     def run_hydraulic_simulation(self, hyd_export: str = None, verbose: bool = False,
                                  frozen_sensor_config: bool = False) -> ScadaData:
@@ -2461,6 +2487,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,
@@ -2524,8 +2551,8 @@ class ScenarioSimulator():
 
         self.__running_simulation = True
 
-        self.epanet_api.openHydraulicAnalysis()
-        self.epanet_api.openQualityAnalysis()
+        self.epanet_api.api.ENopenH()
+        self.epanet_api.api.ENopenQ()
         self.epanet_api.initializeHydraulicAnalysis(ToolkitConstants.EN_SAVE)
         self.epanet_api.initializeQualityAnalysis(ToolkitConstants.EN_SAVE)
 
@@ -2533,6 +2560,8 @@ class ScenarioSimulator():
         reporting_time_start = self.epanet_api.getTimeReportingStart()
         reporting_time_step = self.epanet_api.getTimeReportingStep()
 
+        network_topo = self.get_topology()
+
         if verbose is True:
             print("Running EPANET ...")
             n_iterations = math.ceil(self.epanet_api.getTimeSimulationDuration() /
@@ -2562,8 +2591,11 @@ class ScenarioSimulator():
                         event.step(total_time + tstep)
 
                 # Compute current time step
-                t = self.epanet_api.runHydraulicAnalysis()
-                self.epanet_api.runQualityAnalysis()
+                t = self.epanet_api.api.ENrunH()
+                error_code = self.epanet_api.get_last_error_code()
+                self.epanet_api.api.ENrunQ()
+                if error_code == 0:
+                    error_code = self.epanet_api.get_last_error_code()
                 total_time = t
 
                 # Fetch data
@@ -2582,7 +2614,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=network_topo,
+                                       sensor_config=self._sensor_config,
                                        pressure_data_raw=pressure_data,
                                        flow_data_raw=flow_data,
                                        demand_data_raw=demand_data,
@@ -2594,6 +2627,7 @@ class ScenarioSimulator():
                                        pumps_energy_usage_data_raw=pumps_energy_usage_data,
                                        pumps_efficiency_data_raw=pumps_efficiency_data,
                                        sensor_readings_time=np.array([total_time]),
+                                       warnings_code=np.array([error_code]),
                                        sensor_reading_events=self._sensor_reading_events,
                                        sensor_noise=self._sensor_noise,
                                        frozen_sensor_config=frozen_sensor_config)
@@ -2611,7 +2645,8 @@ class ScenarioSimulator():
                                 "tanks_volume_data_raw": tanks_volume_data,
                                 "pumps_energy_usage_data_raw": pumps_energy_usage_data,
                                 "pumps_efficiency_data_raw": pumps_efficiency_data,
-                                "sensor_readings_time": np.array([total_time])}
+                                "sensor_readings_time": np.array([total_time]),
+                                "warnings_code": np.array([error_code])}
                     else:
                         data = scada_data
 
@@ -2623,17 +2658,15 @@ class ScenarioSimulator():
                     yield data
 
                 # Apply control modules
-                for control in self._advanced_controls:
-                    control.step(scada_data)
                 for control in self._custom_controls:
                     control.step(scada_data)
 
                 # Next
-                tstep = self.epanet_api.nextHydraulicAnalysisStep()
-                self.epanet_api.nextQualityAnalysisStep()
+                tstep = self.epanet_api.api.ENnextH()
+                self.epanet_api.api.ENnextQ()
 
-            self.epanet_api.closeQualityAnalysis()
-            self.epanet_api.closeHydraulicAnalysis()
+            self.epanet_api.api.ENcloseQ()
+            self.epanet_api.api.ENcloseH()
 
             self.__running_simulation = False
 
@@ -2643,16 +2676,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:
         """
@@ -2760,6 +2783,7 @@ class ScenarioSimulator():
 
     def set_general_parameters(self, demand_model: dict = None, simulation_duration: int = None,
                                hydraulic_time_step: int = None, quality_time_step: int = None,
+                               advanced_quality_time_step: int = None,
                                reporting_time_step: int = None, reporting_time_start: int = None,
                                flow_units_id: int = None, quality_model: dict = None) -> None:
         """
@@ -2792,6 +2816,12 @@ class ScenarioSimulator():
             Quality time step -- i.e. the interval at which qualities are computed.
             Should be much smaller than the hydraulic time step!
 
+            The default is None.
+        advanced_quality_time_step : `ìnt`, optional
+            Time step in the advanced quality simuliation -- i.e. EPANET-MSX simulation.
+            This number specifies the interval at which all species concentrations are.
+            Should be much smaller than the hydraulic time step!
+
             The default is None.
         reporting_time_step : `int`, optional
             Report time step -- i.e. the interval at which hydraulics and quality states are
@@ -2904,6 +2934,14 @@ class ScenarioSimulator():
                                  "greater than the hydraulic time step")
             self.epanet_api.setTimeQualityStep(quality_time_step)
 
+        if advanced_quality_time_step is not None:
+            if not isinstance(advanced_quality_time_step, int) or \
+                    advanced_quality_time_step <= 0 or \
+                    advanced_quality_time_step > self.epanet_api.getTimeHydraulicStep():
+                raise ValueError("'advanced_quality_time_step' must be a positive integer " +
+                                 "that is not greater than the hydraulic time step")
+            self.epanet_api.setMSXTimeStep(advanced_quality_time_step)
+
         if quality_model is not None:
             if quality_model["type"] == "NONE":
                 self.epanet_api.setQualityType("none")
@@ -2945,6 +2983,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:
@@ -3057,7 +3291,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)
 
@@ -3065,11 +3299,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
@@ -3096,7 +3539,9 @@ class ScenarioSimulator():
                                      source_type: int, pattern_id: str = None,
                                      source_strength: int = 1.) -> None:
         """
-        Adds a new external (bulk or surface) species injection source at a particular node.
+        Adds a new external bulk species injection source at a particular node.
+
+        Only for EPANET-MSX scenarios.
 
         Parameters
         ----------
@@ -3107,6 +3552,8 @@ class ScenarioSimulator():
             is placed.
         pattern : `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
             1d source pattern.
+
+            Note that the pattern time step is equivalent to the EPANET pattern time step.
         source_type : `int`,
             Type of the external (bulk or surface) species injection source -- must be one of
             the following EPANET toolkit constants:
@@ -3153,3 +3600,82 @@ 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 list(itertools.chain(*inital_conc.values()))) or \
+                any(not isinstance(node_id, str) or not isinstance(conc, float)
+                    for node_id, conc in list(itertools.chain(*inital_conc.values()))):
+            raise TypeError("'inital_conc' must be an instance of " +
+                            "'dict[str, list[tuple[str, float]]'")
+        inital_conc_values = list(itertools.chain(*inital_conc.values()))
+        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)