[ModelicaSystem] split simulate() into two methods

OMPython/ModelicaSystem.py

@@ -867,29 +867,39 @@ def getOptimizationOptions(self, names=None):  # 10
 
         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[int] = None):  # 11
+    def simulate_cmd(
+            self,
+            resultfile: pathlib.Path,
+            simflags: Optional[str] = None,
+            simargs: Optional[dict[str, Optional[str | dict[str, str]]]] = None,
+            timeout: Optional[int] = None,
+    ) -> ModelicaSystemCmd:
         """
-        This method simulates model according to the simulation options.
-        usage
-        >>> simulate()
-        >>> simulate(resultfile="a.mat")
-        >>> simulate(simflags="-noEventEmit -noRestart -override=e=0.3,g=10")  # set runtime simulation flags
-        >>> simulate(simargs={"noEventEmit": None, "noRestart": None, "override": "e=0.3,g=10"})  # using simargs
+        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.
+
+        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.
+
+        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.
+
+        Parameters
+        ----------
+        resultfile
+        simflags
+        simargs
+        timeout
+
+        Returns
+        -------
+            An instance if ModelicaSystemCmd to run the requested simulation.
         """
 
         om_cmd = ModelicaSystemCmd(runpath=self.tempdir, modelname=self.modelName, timeout=timeout)
 
-        if resultfile is None:
-            # default result file generated by OM
-            self.resultfile = self.tempdir / f"{self.modelName}_res.mat"
-        elif os.path.exists(resultfile):
-            self.resultfile = pathlib.Path(resultfile)
-        else:
-            self.resultfile = self.tempdir / resultfile
-        # always define the resultfile to use
-        om_cmd.arg_set(key="r", val=self.resultfile.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:
@@ -925,6 +935,30 @@ def simulate(self, resultfile: Optional[str] = None, simflags: Optional[str] = N
 
             om_cmd.arg_set(key="csvInput", val=self.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[int] = None):  # 11
+        """
+        This method simulates model according to the simulation options.
+        usage
+        >>> simulate()
+        >>> simulate(resultfile="a.mat")
+        >>> simulate(simflags="-noEventEmit -noRestart -override=e=0.3,g=10")  # set runtime simulation flags
+        >>> simulate(simargs={"noEventEmit": None, "noRestart": None, "override": "e=0.3,g=10"})  # using simargs
+        """
+
+        if resultfile is None:
+            # default result file generated by OM
+            self.resultfile = self.tempdir / f"{self.modelName}_res.mat"
+        elif os.path.exists(resultfile):
+            self.resultfile = pathlib.Path(resultfile)
+        else:
+            self.resultfile = self.tempdir / resultfile
+
+        om_cmd = self.simulate_cmd(resultfile=self.resultfile, simflags=simflags, simargs=simargs, timeout=timeout)
+
         # delete resultfile ...
         if self.resultfile.is_file():
             self.resultfile.unlink()