epyt-flow 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

epyt_flow/simulation/scenario_simulator.py

@@ -94,6 +94,7 @@ class ScenarioSimulator():
         self.__controls = []
         self.__system_events = []
         self.__sensor_reading_events = []
+        self.__running_simulation = False
 
         custom_epanet_lib = None
         custom_epanetmsx_lib = None
@@ -150,7 +151,8 @@ class ScenarioSimulator():
 
             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_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)
@@ -432,7 +434,7 @@ class ScenarioSimulator():
         new_sensor_config.quality_node_sensors = self.__sensor_config.quality_node_sensors
         new_sensor_config.quality_link_sensors = self.__sensor_config.quality_link_sensors
         new_sensor_config.pump_state_sensors = self.__sensor_config.pump_state_sensors
-        new_sensor_config.pump_efficiecy_sensors = self.__sensor_config.pump_efficiency_sensors
+        new_sensor_config.pump_efficiency_sensors = self.__sensor_config.pump_efficiency_sensors
         new_sensor_config.pump_energyconsumption_sensors = self.__sensor_config.\
             pump_energyconsumption_sensors
         new_sensor_config.valve_state_sensors = self.__sensor_config.valve_state_sensors
@@ -456,8 +458,6 @@ class ScenarioSimulator():
 
         if self.__my_f_inp_in is not None:
             shutil.rmtree(pathlib.Path(self.__my_f_inp_in).parent)
-        if self.__my_f_msx_in is not None:
-            shutil.rmtree(pathlib.Path(self.__my_f_msx_in).parent)
 
     def __enter__(self):
         return self
@@ -744,6 +744,19 @@ class ScenarioSimulator():
                 "units": qualityunit_to_id(qual_info.QualityChemUnits),
                 "trace_node_id": qual_info.TraceNode}
 
+    def get_reporting_time_step(self) -> int:
+        """
+        Gets the reporting time steps -- i.e. time steps at which sensor readings are provided.
+
+        Is always a multiple of the hydraulic time step.
+
+        Returns
+        -------
+        `int`
+            Reporting time steps in seconds.
+        """
+        return self.epanet_api.getTimeReportingStep()
+
     def get_scenario_config(self) -> ScenarioConfig:
         """
         Gets the configuration of this scenario -- i.e. all information & elements
@@ -758,7 +771,7 @@ class ScenarioSimulator():
 
         general_params = {"hydraulic_time_step": self.get_hydraulic_time_step(),
                           "quality_time_step": self.get_quality_time_step(),
-                          "reporting_time_step": self.epanet_api.getTimeReportingStep(),
+                          "reporting_time_step": self.get_reporting_time_step(),
                           "simulation_duration": self.get_simulation_duration(),
                           "flow_units_id": self.get_flow_units(),
                           "quality_model": self.get_quality_model(),
@@ -874,6 +887,9 @@ class ScenarioSimulator():
         """
         Randomizes all demand patterns.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         # Get all demand patterns
@@ -996,6 +1012,9 @@ class ScenarioSimulator():
         event : :class:`~epyt_flow.simulation.events.system_event.SystemEvent`
             System event.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(event, SystemEvent):
@@ -1015,6 +1034,9 @@ class ScenarioSimulator():
         sensor_fault_event : :class:`~epyt_flow.simulation.events.sensor_faults.SensorFault`
             Sensor fault specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         sensor_fault_event.validate(self.__sensor_config)
@@ -1035,6 +1057,9 @@ class ScenarioSimulator():
         sensor_reading_attack : :class:`~epyt_flow.simulation.events.sensor_reading_attack.SensorReadingAttack`
             Sensor fault specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         sensor_reading_attack.validate(self.__sensor_config)
@@ -1055,6 +1080,9 @@ class ScenarioSimulator():
         event : :class:`~epyt_flow.simulation.events.sensor_reading_event.SensorReadingEvent`
             Sensor reading event.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         event.validate(self.__sensor_config)
@@ -1134,11 +1162,21 @@ class ScenarioSimulator():
         """
         self.set_sensors(SENSOR_TYPE_NODE_PRESSURE, sensor_locations)
 
-    def place_pressure_sensors_everywhere(self) -> None:
+    def place_pressure_sensors_everywhere(self, junctions_only: bool = False) -> None:
         """
         Places a pressure sensor at every node in the network.
+
+        Parameters
+        ----------
+        junctions_only : `bool`, optional
+            If True, pressure sensors are only placed at junctions but not at tanks and reservoirs.
+
+            The default is False.
         """
-        self.set_pressure_sensors(self.__sensor_config.nodes)
+        if junctions_only is True:
+            self.set_pressure_sensors(self.epanet_api.getNodeJunctionNameID())
+        else:
+            self.set_pressure_sensors(self.__sensor_config.nodes)
 
     def set_flow_sensors(self, sensor_locations: list[str]) -> None:
         """
@@ -1442,6 +1480,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Quality simulation results as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         if self.__f_msx_in is None:
             raise ValueError("No .msx file specified")
 
@@ -1506,6 +1547,9 @@ class ScenarioSimulator():
             Generator containing the current EPANET-MSX simulation results as SCADA data
             (i.e. species concentrations).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         if self.__f_msx_in is None:
             raise ValueError("No .msx file specified")
 
@@ -1522,6 +1566,8 @@ class ScenarioSimulator():
 
         self.epanet_api.initializeMSXQualityAnalysis(ToolkitConstants.EN_NOSAVE)
 
+        self.__running_simulation = True
+
         bulk_species_idx = self.epanet_api.getMSXSpeciesIndex(self.__sensor_config.bulk_species)
         surface_species_idx = self.epanet_api.getMSXSpeciesIndex(
             self.__sensor_config.surface_species)
@@ -1598,63 +1644,75 @@ class ScenarioSimulator():
 
         if reporting_time_start == 0:
             if return_as_dict is True:
-                yield {"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,
-                       "sensor_readings_time": np.array([0])}
+                data = {"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,
+                        "sensor_readings_time": np.array([0])}
             else:
-                yield ScadaData(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,
-                                sensor_readings_time=np.array([0]),
-                                sensor_reading_events=self.__sensor_reading_events,
-                                sensor_noise=self.__sensor_noise,
-                                frozen_sensor_config=frozen_sensor_config)
+                data = ScadaData(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,
+                                 sensor_readings_time=np.array([0]),
+                                 sensor_reading_events=self.__sensor_reading_events,
+                                 sensor_noise=self.__sensor_noise,
+                                 frozen_sensor_config=frozen_sensor_config)
 
-        # Run step-by-step simulation
-        tleft = 1
-        while tleft > 0:
             if support_abort is True:  # Can the simulation be aborted? If so, handle it.
                 abort = yield
-                if abort is not False:
-                    break
+                if abort is True:
+                    return None
 
+            yield data
+
+        # Run step-by-step simulation
+        tleft = 1
+        total_time = 0
+        while tleft > 0:
             # Compute current time step
             total_time, tleft = self.epanet_api.stepMSXQualityAnalysisTimeLeft()
 
-            if verbose is True:
-                try:
-                    next(progress_bar)
-                except StopIteration:
-                    pass
-
             # Fetch data at regular time intervals
             if total_time % hyd_time_step == 0:
+                if verbose is True:
+                    try:
+                        next(progress_bar)
+                    except StopIteration:
+                        pass
+
                 bulk_species_node_concentrations, bulk_species_link_concentrations, \
                     surface_species_concentrations = __get_concentrations()
 
                 # Report results in a regular time interval only!
                 if total_time % reporting_time_step == 0 and total_time >= reporting_time_start:
                     if return_as_dict is True:
-                        yield {"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,
-                               "sensor_readings_time": np.array([total_time])}
+                        data = {"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,
+                                "sensor_readings_time": np.array([total_time])}
                     else:
-                        yield ScadaData(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,
-                                        sensor_readings_time=np.array([total_time]),
-                                        sensor_reading_events=self.__sensor_reading_events,
-                                        sensor_noise=self.__sensor_noise,
-                                        frozen_sensor_config=frozen_sensor_config)
+                        data = ScadaData(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,
+                                         sensor_readings_time=np.array([total_time]),
+                                         sensor_reading_events=self.__sensor_reading_events,
+                                         sensor_noise=self.__sensor_noise,
+                                         frozen_sensor_config=frozen_sensor_config)
+
+                    if support_abort is True:  # Can the simulation be aborted? If so, handle it.
+                        abort = yield
+                        if abort is not False:
+                            break
+
+                    yield data
+
+        self.__running_simulation = False
 
     def run_basic_quality_simulation(self, hyd_file_in: str, verbose: bool = False,
                                      frozen_sensor_config: bool = False) -> ScadaData:
@@ -1681,6 +1739,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Quality simulation results as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         result = None
 
         # Run simulation step-by-step
@@ -1741,6 +1802,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Generator with the current simulation results/states as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         requested_time_step = self.epanet_api.getTimeHydraulicStep()
         reporting_time_start = self.epanet_api.getTimeReportingStart()
         reporting_time_step = self.epanet_api.getTimeReportingStep()
@@ -1761,11 +1825,6 @@ class ScenarioSimulator():
         tstep = 1
         first_itr = True
         while tstep > 0:
-            if support_abort is True:  # Can the simulation be aborted? If so, handle it.
-                abort = yield
-                if abort is not False:
-                    break
-
             if first_itr is True:  # Fix current time in the first iteration
                 tstep = 0
                 first_itr = False
@@ -1788,27 +1847,36 @@ class ScenarioSimulator():
             # Yield results in a regular time interval only!
             if total_time % reporting_time_step == 0 and total_time >= reporting_time_start:
                 if return_as_dict is True:
-                    yield {"node_quality_data_raw": quality_node_data,
-                           "link_quality_data_raw": quality_link_data,
-                           "sensor_readings_time": np.array([total_time])}
+                    data = {"node_quality_data_raw": quality_node_data,
+                            "link_quality_data_raw": quality_link_data,
+                            "sensor_readings_time": np.array([total_time])}
                 else:
-                    yield ScadaData(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]),
-                                    sensor_reading_events=self.__sensor_reading_events,
-                                    sensor_noise=self.__sensor_noise,
-                                    frozen_sensor_config=frozen_sensor_config)
+                    data = ScadaData(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]),
+                                     sensor_reading_events=self.__sensor_reading_events,
+                                     sensor_noise=self.__sensor_noise,
+                                     frozen_sensor_config=frozen_sensor_config)
+
+                if support_abort is True:  # Can the simulation be aborted? If so, handle it.
+                    abort = yield
+                    if abort is True:
+                        break
+
+                yield data
 
             # Next
             tstep = self.epanet_api.nextQualityAnalysisStep()
 
         self.epanet_api.closeHydraulicAnalysis()
 
-    def run_simulation(self, hyd_export: str = None, verbose: bool = False,
-                       frozen_sensor_config: bool = False) -> ScadaData:
+    def run_hydraulic_simulation(self, hyd_export: str = None, verbose: bool = False,
+                                 frozen_sensor_config: bool = False) -> ScadaData:
         """
-        Runs the simulation of this scenario.
+        Runs the hydraulic simulation of this scenario (incl. basic quality if set).
+
+        Note that this function does not call EPANET-MSX even if an .msx file was provided.
 
         Parameters
         ----------
@@ -1834,16 +1902,15 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Simulation results as SCADA data (i.e. sensor readings).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         self.__adapt_to_network_changes()
 
         result = None
 
-        hyd_export_old = hyd_export
-        if self.__f_msx_in is not None:
-            hyd_export = os.path.join(get_temp_folder(), f"epytflow_MSX_{uuid.uuid4()}.hyd")
-
         # Run hydraulic simulation step-by-step
-        gen = self.run_simulation_as_generator
+        gen = self.run_hydraulic_simulation_as_generator
         for scada_data in gen(hyd_export=hyd_export,
                               verbose=verbose,
                               return_as_dict=True,
@@ -1865,32 +1932,18 @@ class ScenarioSimulator():
                            sensor_noise=self.__sensor_noise,
                            frozen_sensor_config=frozen_sensor_config)
 
-        # If necessary, run advanced quality simulation utilizing the computed hydraulics
-        if self.f_msx_in is not None:
-            gen = self.run_advanced_quality_simulation
-            result_msx = gen(hyd_file_in=hyd_export,
-                             verbose=verbose,
-                             frozen_sensor_config=frozen_sensor_config)
-            result.join(result_msx)
-
-            if hyd_export_old is not None:
-                shutil.copyfile(hyd_export, hyd_export_old)
-
-            try:
-                # temp solution
-                os.remove(hyd_export)
-            except:
-                warnings.warn(f"Failed to remove temporary file '{hyd_export}'")
-
         return result
 
-    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]:
+    def run_hydraulic_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]:
         """
-        Runs the simulation of this scenario and provides the results as a generator.
+        Runs the hydraulic simulation of this scenario (incl. basic quality if set) and
+        provides the results as a generator.
+
+        Note that this function does not run EPANET-MSX, even if an .msx file was provided.
 
         Parameters
         ----------
@@ -1928,10 +1981,15 @@ class ScenarioSimulator():
             Generator with the current simulation results/states as SCADA data
             (i.e. sensor readings).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         self.__adapt_to_network_changes()
 
         self.__prepare_simulation()
 
+        self.__running_simulation = True
+
         self.epanet_api.openHydraulicAnalysis()
         self.epanet_api.openQualityAnalysis()
         self.epanet_api.initializeHydraulicAnalysis(ToolkitConstants.EN_SAVE)
@@ -1958,11 +2016,11 @@ class ScenarioSimulator():
                     first_itr = False
 
                 if verbose is True:
-                    #if (total_time + tstep) % requested_time_step == 0:
-                    try:
-                        next(progress_bar)
-                    except StopIteration:
-                        pass
+                    if (total_time + tstep) % requested_time_step == 0:
+                        try:
+                            next(progress_bar)
+                        except StopIteration:
+                            pass
 
                 # Apply system events in a regular time interval only!
                 if (total_time + tstep) % requested_time_step == 0:
@@ -2025,7 +2083,7 @@ class ScenarioSimulator():
 
                     if support_abort is True:  # Can the simulation be aborted? If so, handle it.
                         abort = yield
-                        if abort is not False:
+                        if abort is True:
                             break
 
                     yield data
@@ -2041,11 +2099,77 @@ class ScenarioSimulator():
             self.epanet_api.closeQualityAnalysis()
             self.epanet_api.closeHydraulicAnalysis()
 
+            self.__running_simulation = False
+
             if hyd_export is not None:
                 self.epanet_api.saveHydraulicFile(hyd_export)
         except Exception as ex:
+            self.__running_simulation = False
             raise ex
 
+    def run_simulation(self, hyd_export: str = None, verbose: bool = False,
+                       frozen_sensor_config: bool = False) -> ScadaData:
+        """
+        Runs the simulation of this scenario.
+
+        Parameters
+        ----------
+        hyd_export : `str`, optional
+            Path to an EPANET .hyd file for storing the simulated hydraulics -- these hydraulics
+            can be used later for an advanced quality analysis using EPANET-MSX.
+
+            If None, the simulated hydraulics will NOT be exported to an EPANET .hyd file.
+
+            The default is None.
+        verbose : `bool`, optional
+            If True, method will be verbose (e.g. showing a progress bar).
+
+            The default is False.
+        frozen_sensor_config : `bool`, optional
+            If True, the sensor config can not be changed and only the required sensor nodes/links
+            will be stored -- this usually leads to a significant reduction in memory consumption.
+
+            The default is False.
+
+        Returns
+        -------
+        :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            Simulation results as SCADA data (i.e. sensor readings).
+        """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
+        self.__adapt_to_network_changes()
+
+        result = None
+
+        hyd_export_old = hyd_export
+        if self.__f_msx_in is not None:
+            hyd_export = os.path.join(get_temp_folder(), f"epytflow_MSX_{uuid.uuid4()}.hyd")
+
+        # Run hydraulic simulation step-by-step
+        result = self.run_hydraulic_simulation(hyd_export=hyd_export, verbose=verbose,
+                                               frozen_sensor_config=frozen_sensor_config)
+
+        # If necessary, run advanced quality simulation utilizing the computed hydraulics
+        if self.f_msx_in is not None:
+            gen = self.run_advanced_quality_simulation
+            result_msx = gen(hyd_file_in=hyd_export,
+                             verbose=verbose,
+                             frozen_sensor_config=frozen_sensor_config)
+            result.join(result_msx)
+
+            if hyd_export_old is not None:
+                shutil.copyfile(hyd_export, hyd_export_old)
+
+            try:
+                # temp solution
+                os.remove(hyd_export)
+            except:
+                warnings.warn(f"Failed to remove temporary file '{hyd_export}'")
+
+        return result
+
     def set_model_uncertainty(self, model_uncertainty: ModelUncertainty) -> None:
         """
         Specifies the model uncertainties.
@@ -2055,6 +2179,9 @@ class ScenarioSimulator():
         model_uncertainty : :class:`~epyt_flow.uncertainty.model_uncertainty.ModelUncertainty`
             Model uncertainty specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not set uncertainties when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(model_uncertainty, ModelUncertainty):
@@ -2073,6 +2200,9 @@ class ScenarioSimulator():
         sensor_noise : :class:`~epyt_flow.uncertainties.sensor_noise.SensorNoise`
             Sensor noise specification.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not set sensor noise when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(sensor_noise, SensorNoise):
@@ -2155,6 +2285,9 @@ class ScenarioSimulator():
 
             The default is None.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if flow_units_id is not None:
@@ -2277,6 +2410,9 @@ class ScenarioSimulator():
         Sets water age analysis -- i.e. estimates the water age (in hours) at
         all places in the network.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         self.__warn_if_quality_set()
@@ -2305,6 +2441,9 @@ class ScenarioSimulator():
 
             The default is MASS_UNIT_MG.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         self.__warn_if_quality_set()
@@ -2349,6 +2488,9 @@ class ScenarioSimulator():
 
             The default is 1.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if self.epanet_api.getQualityInfo().QualityCode != ToolkitConstants.EN_CHEM:
@@ -2385,6 +2527,9 @@ class ScenarioSimulator():
         trace_node_id : `str`
             ID of the node traced in the source tracing analysis.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if trace_node_id not in self.__sensor_config.nodes:
@@ -2393,3 +2538,65 @@ class ScenarioSimulator():
         self.__warn_if_quality_set()
         self.set_general_parameters(quality_model={"type": "TRACE",
                                                    "trace_node_id": trace_node_id})
+
+    def add_species_injection_source(self, species_id: str, node_id: str, pattern: np.ndarray,
+                                     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.
+
+        Parameters
+        ----------
+        species_id : `str`
+            ID of the (bulk or surface) species.
+        node_id : `str`
+            ID of the node at which this external (bulk or surface) species injection source
+            is placed.
+        pattern : `numpy.ndarray`
+            1d source pattern.
+        source_type : `int`,
+            Type of the external (bulk or surface) species injection source -- must be one of
+            the following EPANET toolkit constants:
+
+                - EN_CONCEN     = 0
+                - EN_MASS       = 1
+                - EN_SETPOINT   = 2
+                - EN_FLOWPACED  = 3
+
+            Description:
+
+                - E_CONCEN Sets the concentration of external inflow entering a node
+                - EN_MASS Injects a given mass/minute into a node
+                - EN_SETPOINT Sets the concentration leaving a node to a given value
+                - EN_FLOWPACED Adds a given value to the concentration leaving a node
+        pattern_id : `str`, optional
+            ID of the source pattern.
+
+            If None, a pattern_id will be generated automatically -- be aware that this
+            could conflict with existing pattern IDs (in this case, an exception is raised).
+
+            The default is None.
+        source_strength : `int`, optional
+            Injection source strength -- i.e. injection = source_strength * pattern.
+
+            The default is 1.
+        """
+        source_type_ = "None"
+        if source_type == ToolkitConstants.EN_CONCEN:
+            source_type_ = "CONCEN"
+        elif source_type == ToolkitConstants.EN_MASS:
+            source_type_ = "MASS"
+        elif source_type == ToolkitConstants.EN_SETPOINT:
+            source_type_ = "SETPOINT"
+        elif source_type == ToolkitConstants.EN_FLOWPACED:
+            source_type_ = "FLOWPACED"
+
+        if pattern_id is None:
+            pattern_id = f"{species_id}_{node_id}"
+        if pattern_id in self.epanet_api.getMSXPatternsNameID():
+            raise ValueError("Invalid 'pattern_id' -- " +
+                             f"there already exists a pattern with ID '{pattern_id}'")
+
+        self.epanet_api.addMSXPattern(pattern_id, pattern)
+        self.epanet_api.setMSXSources(node_id, species_id, source_type_, source_strength,
+                                      pattern_id)