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

epyt_flow/simulation/scenario_simulator.py

@@ -7,7 +7,7 @@ import pathlib
 import time
 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
@@ -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 = []
@@ -190,9 +189,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 +338,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 +970,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 +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()
@@ -1060,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
@@ -1072,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,
@@ -1110,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:
@@ -1183,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:
         """
@@ -1257,25 +1243,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 +1901,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 +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,
@@ -2159,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,
@@ -2203,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=
@@ -2284,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,
@@ -2385,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]),
@@ -2461,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,
@@ -2582,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,
@@ -2623,8 +2593,6 @@ 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)
 
@@ -2643,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:
         """
@@ -2945,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:
@@ -3057,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)
 
@@ -3065,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
@@ -3098,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`
@@ -3153,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)