[ModelicaSystem] split simulate() into two methods (#311)

* [ModelicaSystem] split simulate() into two methods

(1) create ModelicasystemCmd instance - simulate_cmd()
(2) run it - simulate()

* [ModelicaSystem] improve docstring for simulate_cmd()

* [ModelicaSystem.simulate] fix header definition

* [ModelicaSystem.simulate_cmd] fix type hints

---------

Co-authored-by: Adeel Asghar <[email protected]>

Author: syntron

OMPython/ModelicaSystem.py

@@ -915,40 +915,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:
@@ -984,6 +983,48 @@ def simulate(self,
 
             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[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()