Merge branch 'master' into ModelicaSystem_csvfile

Author: adeas31

OMPython/ModelicaSystem.py

@@ -49,7 +49,7 @@
 import warnings
 import xml.etree.ElementTree as ET
 
-from OMPython.OMCSession import OMCSessionException, OMCSessionZMQ
+from OMPython.OMCSession import OMCSessionException, OMCSessionZMQ, OMCProcessLocal
 
 # define logger using the current module name as ID
 logger = logging.getLogger(__name__)
@@ -303,7 +303,7 @@ def __init__(
             variableFilter: Optional[str] = None,
             customBuildDirectory: Optional[str | os.PathLike | pathlib.Path] = None,
             omhome: Optional[str] = None,
-            session: Optional[OMCSessionZMQ] = None,
+            omc_process: Optional[OMCProcessLocal] = None,
             build: bool = True,
     ) -> None:
         """Initialize, load and build a model.
@@ -331,8 +331,8 @@ def __init__(
               directory will be created.
             omhome: OPENMODELICAHOME value to be used when creating the OMC
               session.
-            session: OMC session to be used. If unspecified, a new session
-              will be created.
+            omc_process: definition of a (local) OMC process to be used. If
+              unspecified, a new local session will be created.
             build: Boolean controlling whether or not the model should be
               built when constructor is called. If False, the constructor
               simply loads the model without compiling.
@@ -367,10 +367,10 @@ def __init__(
         self._linearized_outputs: list[str] = []  # linearization output list
         self._linearized_states: list[str] = []  # linearization states list
 
-        if session is not None:
-            if not isinstance(session, OMCSessionZMQ):
-                raise ModelicaSystemError("Invalid session data provided!")
-            self._getconn = session
+        if omc_process is not None:
+            if not isinstance(omc_process, OMCProcessLocal):
+                raise ModelicaSystemError("Invalid (local) omc process definition provided!")
+            self._getconn = OMCSessionZMQ(omc_process=omc_process)
         else:
             self._getconn = OMCSessionZMQ(omhome=omhome)
 
@@ -914,40 +914,39 @@ def getOptimizationOptions(self, names: Optional[str | list[str]] = None) -> dic
 
         raise ModelicaSystemError("Unhandled input for getOptimizationOptions()")
 
-    def simulate(self,
-                 resultfile: Optional[str] = None,
-                 simflags: Optional[str] = None,
-                 simargs: Optional[dict[str, Optional[str | dict[str, str]]]] = None,
-                 timeout: Optional[float] = None) -> None:
-        """Simulate the model according to simulation options.
+    def simulate_cmd(
+            self,
+            resultfile: pathlib.Path,
+            simflags: Optional[str] = None,
+            simargs: Optional[dict[str, Optional[str | dict[str, str]]]] = None,
+            timeout: Optional[float] = None,
+    ) -> ModelicaSystemCmd:
+        """
+        This method prepares the simulates model according to the simulation options. It returns an instance of
+        ModelicaSystemCmd which can be used to run the simulation.
 
-        See setSimulationOptions().
+        Due to the tempdir being unique for the ModelicaSystem instance, *NEVER* use this to create several simulations
+        with the same instance of ModelicaSystem! Restart each simulation process with a new instance of ModelicaSystem.
 
-        Args:
-            resultfile: Path to a custom result file
-            simflags: String of extra command line flags for the model binary.
-              This argument is deprecated, use simargs instead.
-            simargs: Dict with simulation runtime flags.
-            timeout: Maximum execution time in seconds.
+        However, if only non-structural parameters are used, it is possible to reuse an existing instance of
+        ModelicaSystem to create several version ModelicaSystemCmd to run the model using different settings.
 
-        Examples:
-            mod.simulate()
-            mod.simulate(resultfile="a.mat")
-            mod.simulate(simflags="-noEventEmit -noRestart -override=e=0.3,g=10")  # set runtime simulation flags, deprecated
-            mod.simulate(simargs={"noEventEmit": None, "noRestart": None, "override": "override": {"e": 0.3, "g": 10}})  # using simargs
+        Parameters
+        ----------
+        resultfile
+        simflags
+        simargs
+        timeout
+
+        Returns
+        -------
+            An instance if ModelicaSystemCmd to run the requested simulation.
         """
 
         om_cmd = ModelicaSystemCmd(runpath=self._tempdir, modelname=self._model_name, timeout=timeout)
 
-        if resultfile is None:
-            # default result file generated by OM
-            self._result_file = self._tempdir / f"{self._model_name}_res.mat"
-        elif os.path.exists(resultfile):
-            self._result_file = pathlib.Path(resultfile)
-        else:
-            self._result_file = self._tempdir / resultfile
-        # always define the resultfile to use
-        om_cmd.arg_set(key="r", val=self._result_file.as_posix())
+        # always define the result file to use
+        om_cmd.arg_set(key="r", val=resultfile.as_posix())
 
         # allow runtime simulation flags from user input
         if simflags is not None:
@@ -988,6 +987,48 @@ def simulate(self,
 
             om_cmd.arg_set(key="csvInput", val=csvfile.as_posix())
 
+        return om_cmd
+
+    def simulate(
+            self,
+            resultfile: Optional[str] = None,
+            simflags: Optional[str] = None,
+            simargs: Optional[dict[str, Optional[str | dict[str, str]]]] = None,
+            timeout: Optional[float] = None,
+    ) -> None:
+        """Simulate the model according to simulation options.
+
+        See setSimulationOptions().
+
+        Args:
+            resultfile: Path to a custom result file
+            simflags: String of extra command line flags for the model binary.
+              This argument is deprecated, use simargs instead.
+            simargs: Dict with simulation runtime flags.
+            timeout: Maximum execution time in seconds.
+
+        Examples:
+            mod.simulate()
+            mod.simulate(resultfile="a.mat")
+            mod.simulate(simflags="-noEventEmit -noRestart -override=e=0.3,g=10")  # set runtime simulation flags, deprecated
+            mod.simulate(simargs={"noEventEmit": None, "noRestart": None, "override": "override": {"e": 0.3, "g": 10}})  # using simargs
+        """
+
+        if resultfile is None:
+            # default result file generated by OM
+            self._result_file = self._tempdir / f"{self._model_name}_res.mat"
+        elif os.path.exists(resultfile):
+            self._result_file = pathlib.Path(resultfile)
+        else:
+            self._result_file = self._tempdir / resultfile
+
+        om_cmd = self.simulate_cmd(
+            resultfile=self._result_file,
+            simflags=simflags,
+            simargs=simargs,
+            timeout=timeout,
+        )
+
         # delete resultfile ...
         if self._result_file.is_file():
             self._result_file.unlink()