Merge pull request #23 from mihsamusev/Add_single_run

Add single run method

Author: magoorden

docs/source/index.rst

@@ -6,7 +6,7 @@ Welcome to strategoutil's documentation!
 provides an interface to perform model-predictive control or online-control.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Contents:
 
    installation

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = strategoutil
-version = 0.0.5
+version = 0.0.6
 author = Mihhail Samusev, Martijn Goorden
 author_email = [email protected]
 description = Python utility functions library for UPPAAL Stratego

strategoutil.py

@@ -43,8 +43,8 @@ def extract_state(text, var, controlperiod):
     :type text: str
     :param var: The variable name.
     :type var: str
-    :param controlperiod: The interval duration after which the controller can change the control setting,
-        given in Uppaal Stratego time units.
+    :param controlperiod: The interval duration after which the controller can change the control
+        setting, given in Uppaal Stratego time units.
     :type controlperiod: int
     :return: The value of the variable at the end of *controlperiod*.
     :rtype: float
@@ -112,7 +112,8 @@ def array_to_stratego(arr):
 
     :param arr: The array string to convert.
     :type arr: str
-    :return: An array string where ``"["`` and ``"]"`` are replaced by ``"{"`` and ``"}"``, respectively.
+    :return: An array string where ``"["`` and ``"]"`` are replaced by ``"{"`` and ``"}"``,
+        respectively.
     :rtype: str
     """
     arrstr = str(arr)
@@ -158,15 +159,15 @@ def run_stratego(modelfile, queryfile="", learning_args=None, verifyta_command="
     Run command line version of Uppaal Stratego.
 
     :param modelfile: The file name of the model.
-    :type model_file: str
+    :type modelfile: str
     :param queryfile: The file name of the query.
     :type queryfile: str
     :param learning_args: Dictionary containing the learning parameters and their values. The
         learning parameter names should be those used in the command line interface of Uppaal
         Stratego. You can also include non-learning command line parameters in this dictionary.
         If a non-learning command line parameter does not take any value, include the empty
         string ``""`` as value.
-    :type learning_arg: dict
+    :type learning_args: dict
     :param verifyta_command: The command name for running Uppaal Stratego at the user's machine.
     :type verifyta_command: str
     :return: The output as produced by Uppaal Stratego.
@@ -201,7 +202,7 @@ def successful_result(text):
     return result is not None
 
 
-def print_progress_bar(i, max, postText):
+def print_progress_bar(i, max, post_text):
     """
     Print a progress bar to sys.stdout.
 
@@ -214,13 +215,13 @@ def print_progress_bar(i, max, postText):
     :type i: int
     :param max: The maximum number of steps for process to be completed.
     :type max: int
-    :param postText: The text to display after the progress bar.
-    :type postText: str
+    :param post_text: The text to display after the progress bar.
+    :type post_text: str
     """
     n_bar = 20  # Size of progress bar.
     j = i / max
     sys.stdout.write('\r')
-    sys.stdout.write(f"[{'=' * int(n_bar * j):{n_bar}s}] {int(100 * j)}%  {postText}")
+    sys.stdout.write(f"[{'=' * int(n_bar * j):{n_bar}s}] {int(100 * j)}%  {post_text}")
     sys.stdout.flush()
 
 
@@ -247,7 +248,7 @@ class StrategoController:
     def __init__(self, modeltemplatefile, model_cfg_dict, cleanup=True):
         self.templatefile = modeltemplatefile
         self.simulationfile = modeltemplatefile.replace(".xml", "_sim.xml")
-        self.cleanup = cleanup # TODO: this variable seems to be not used. Can it be safely removed?
+        self.cleanup = cleanup  # TODO: this variable seems to be not used. Can it be safely removed?
         self.states = model_cfg_dict.copy()
         self.tagRule = "//TAG_{}"
 
@@ -344,7 +345,7 @@ def run(self, queryfile="", learning_args=None, verifyta_command="verifyta"):
             Stratego. You can also include non-learning command line parameters in this dictionary.
             If a non-learning command line parameter does not take any value, include the empty
             string ``""`` as value.
-        :type learning_arg: dict
+        :type learning_args: dict
         :param verifyta_command: The command name for running Uppaal Stratego at the user's machine.
         :type verifyta_command: str
         :return: The output generated by Uppaal Stratego.
@@ -373,9 +374,9 @@ class MPCsetup:
     :param learning_args: Dictionary containing the learning parameters and their values. The
         learning parameter names should be those used in the command line interface of Uppaal
         Stratego. You can also include non-learning command line parameters in this dictionary. If
-        a non-learning command line parameter does not take any value, include the empty string ``""``
-        as value.
-    :type learning_arg: dict
+        a non-learning command line parameter does not take any value, include the empty string
+        ``""`` as value.
+    :type learning_args: dict
     :param verifyta_command: The command name for running Uppaal Stratego at the user's machine.
     :type verifyta_command: str
     :param external_simulator: Whether an external simulator is used to obtain the true state after
@@ -402,11 +403,83 @@ def __init__(self, modeltemplatefile, output_file_path=None, queryfile="", model
         self.learning_args = {} if learning_args is None else learning_args
         self.verifyta_command = verifyta_command
         self.external_simulator = external_simulator
-        if external_simulator: assert(action_variable in model_cfg_dict.keys())
+        if external_simulator:
+            assert (action_variable in model_cfg_dict.keys())
         self.action_variable = action_variable
         self.debug = debug
         self.controller = StrategoController(self.modeltemplatefile, self.model_cfg_dict)
 
+    def step_without_sim(self, controlperiod, horizon, duration, step, **kwargs):
+        """
+        Perform a step in the basic MPC scheme without the simulation of the synthesized strategy.
+
+        :param controlperiod: The interval duration after which the controller can change the
+            control setting, given in Uppaal Stratego time units.
+        :type controlperiod: int
+        :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
+            each MPC step. Is given in the number of control periods.
+        :type horizon: int
+        :param duration: The number of times (steps) the MPC scheme should be performed, given as
+            the number of control periods. Is only forwarded to
+            :meth:`~MPCsetup.perform_at_start_iteration`.
+        :type duration: int
+        :param step: The current iteration step in the basic MPC loop.
+        :type step: int
+        :param kwargs: Any additional parameters are forwarded to
+            :meth:`~MPCsetup.perform_at_start_iteration`.
+        :return: The output generated by Uppaal Stratego.
+        :rtype: str
+        """
+        # Perform some customizable preprocessing at each step.
+        self.perform_at_start_iteration(controlperiod, horizon, duration, step, **kwargs)
+
+        # At each MPC step we want a clean template copy to insert variables.
+        self.controller.init_simfile()
+
+        # Insert current state into simulation template.
+        self.controller.insert_state()
+
+        # To debug errors from verifyta one can save intermediate simulation file.
+        if self.debug:
+            self.controller.debug_copy(self.modeltemplatefile.replace(".xml", "_debug.xml"))
+
+        # Create the new query file for the next step.
+        final = horizon * controlperiod + self.controller.get_state("t")
+        self.create_query_file(horizon, controlperiod, final)
+
+        # Run a verifyta query to simulate optimal strategy.
+        result = self.run_verifyta(horizon, controlperiod, final)
+
+        return result
+
+    def run_single(self, controlperiod, horizon, **kwargs):
+        """
+        Run the basic MPC scheme a single step where a single controller strategy is calculated,
+        where the strategy synthesis looks the horizon ahead, and continues for the duration of the
+        experiment.
+
+        The control period is in Uppaal Stratego time units. Horizon have control period as time
+        unit.
+
+        :param controlperiod: The interval duration after which the controller can change the
+            control setting, given in Uppaal Stratego time units.
+        :type controlperiod: int
+        :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
+            each MPC step. Is given in the number of control periods.
+        :type horizon: int
+        :param `**kwargs`: Any additional parameters are forwarded to
+            :meth:`~MPCsetup.perform_at_start_iteration`.
+        :return: The control action chosen for the first control period.
+        """
+        if not check_tool_existance(self.verifyta_command):
+            raise RuntimeError(
+                "Cannot find the supplied verifyta command: " + self.verifyta_command)
+
+        result = self.step_without_sim(controlperiod, horizon, 1, 0, **kwargs)
+        chosen_action = self.extract_control_action_from_stratego(result)
+
+        return chosen_action
+
     def run(self, controlperiod, horizon, duration, **kwargs):
         """
         Run the basic MPC scheme where the controller can changes its strategy once every period,
@@ -416,14 +489,14 @@ def run(self, controlperiod, horizon, duration, **kwargs):
         The control period is in Uppaal Stratego time units. Both horizon and duration have control
         period as time unit.
 
-        :param controlperiod: The interval duration after which the controller can change the control setting,
-            given in Uppaal Stratego time units.
+        :param controlperiod: The interval duration after which the controller can change the
+            control setting, given in Uppaal Stratego time units.
         :type controlperiod: int
         :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
             each MPC step. Is given in the number of control periods.
         :type horizon: int
-        :param duration: The number of times (steps) the MPC scheme should be performed, given as the
-            number of control periods.
+        :param duration: The number of times (steps) the MPC scheme should be performed, given as
+            the number of control periods.
         :type duration: int
         :param `**kwargs`: Any additional parameters are forwarded to
             :meth:`~MPCsetup.perform_at_start_iteration`.
@@ -433,50 +506,36 @@ def run(self, controlperiod, horizon, duration, **kwargs):
         self.print_state()
 
         if not check_tool_existance(self.verifyta_command):
-            raise RuntimeError("Cannot find the supplied verifyta command: " + self.verifyta_command)
+            raise RuntimeError(
+                "Cannot find the supplied verifyta command: " + self.verifyta_command)
 
         for step in range(duration):
             # Only print progress to stdout if results are printed to a file.
-            if (self.output_file_path): print_progress_bar(step, duration, "progress")
+            if self.output_file_path:
+                print_progress_bar(step, duration, "progress")
 
-            # Perform some customizable preprocessing at each step.
-            self.perform_at_start_iteration(controlperiod, horizon, duration, step, **kwargs)
-
-            # At each MPC step we want a clean template copy to insert variables.
-            self.controller.init_simfile()
-
-            # Insert current state into simulation template.
-            self.controller.insert_state()
-
-            # To debug errors from verifyta one can save intermediate simulation file.
-            if self.debug:
-                self.controller.debug_copy(self.modeltemplatefile.replace(".xml", "_debug.xml"))
-
-            # Create the new query file for the next step.
-            final = horizon * controlperiod + self.controller.get_state("t")
-            self.create_query_file(horizon, controlperiod, final)
-
-            # Run a verifyta query to simulate optimal strategy.
-            result = self.run_verifyta(horizon, controlperiod, final)
+            result = self.step_without_sim(controlperiod, horizon, duration, step, **kwargs)
 
             if self.external_simulator:
                 # An external simulator is used to generate the new 'true' state.
-                chosen_action = self.extract_control_action_from_Stratego(result)
-                new_state = self.run_external_simulator(chosen_action, controlperiod, step, **kwargs)
+                chosen_action = self.extract_control_action_from_stratego(result)
+                new_state = self.run_external_simulator(chosen_action, controlperiod, step,
+                                                        **kwargs)
                 self.controller.update_state(new_state)
 
             else:
                 # Extract the state from Uppaal results. This requires that the query file also
                 # includes a simulate query (see default query generator).
-                self.extract_states_from_Stratego(result, controlperiod)
+                self.extract_states_from_stratego(result, controlperiod)
 
             # Print output.
             self.print_state()
-        if(self.output_file_path): print_progress_bar(duration, duration, "finished")
+        if self.output_file_path:
+            print_progress_bar(duration, duration, "finished")
 
     def perform_at_start_iteration(self, *args, **kwargs):
         """
-        Performs some customizable preprocessing steps at the start of each MPC iteration. This
+        Perform some customizable preprocessing steps at the start of each MPC iteration. This
         method can be overritten for specific models.
         """
         pass
@@ -491,8 +550,8 @@ def create_query_file(self, horizon, period, final):
         :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
             each MPC step. Is given in the number of periods.
         :type horizon: int
-        :param period: The interval duration after which the controller can change the control setting,
-            given in Uppaal Stratego time units.
+        :param period: The interval duration after which the controller can change the control
+            setting, given in Uppaal Stratego time units.
         :type period: int
         :param final: The time that should be reached by the synthesized strategy, given in Uppaal
             Stratego time units. Most likely this will be current time + *horizon* x *period*.
@@ -513,24 +572,26 @@ def run_verifyta(self, *args, **kwargs):
             :meth:`~SafeMPCSetup.run_verifyta` in :class:`~SafeMPCSetup`.
         :param `**kwargs`: Is not used in this method; it is used in the overriding method
             :meth:`~SafeMPCSetup.run_verifyta` in :class:`~SafeMPCSetup`.
+        :return: The output generated by Uppaal Stratego.
+        :rtype: str
         """
         result = self.controller.run(queryfile=self.queryfile, learning_args=self.learning_args,
-                                     verifyta_path=self.verifyta_command)
+                                     verifyta_command=self.verifyta_command)
 
         if self.controller.cleanup:
             self.controller.remove_simfile()
         return result
 
-    def extract_states_from_Stratego(self, result, controlperiod):
+    def extract_states_from_stratego(self, result, controlperiod):
         """
         Extract the new state values from the simulation output of Stratego.
 
         The extracted values are directly saved in the :attr:`~MPCsetup.controller`.
 
         :param result: The output as generated by Uppaal Stratego.
         :type result: str
-        :param controlperiod: The interval duration after which the controller can change the control setting,
-            given in Uppaal Stratego time units.
+        :param controlperiod: The interval duration after which the controller can change the
+            control setting, given in Uppaal Stratego time units.
         :type controlperiod: int
         """
         new_state = {}
@@ -541,21 +602,22 @@ def extract_states_from_Stratego(self, result, controlperiod):
             new_state[var] = new_value
         self.controller.update_state(new_state)
 
-    def extract_control_action_from_Stratego(self, result):
+    def extract_control_action_from_stratego(self, result):
         """
         Extract the chosen control action for the first control period from the simulation output
         of Stratego.
 
         :param result: The output as generated by Uppaal Stratego.
         :type result: str
         :return: The control action chosen for the first control period.
+        :rtype: float
         """
         float_re = r"[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?"
         pattern = self.action_variable + r":\n\[0\]:( \(" + float_re + "," + float_re + r"\))*"
         result = re.search(pattern, result)
         float_tuples = get_float_tuples(result.group())
         lastvalue = 0.0
-        
+
         # The last tuple at time 0 represents the chosen control action.
         for t in float_tuples:
             if t[0] == 0:
@@ -588,7 +650,7 @@ def print_state_vars(self):
         printed to the standard output.
         """
         content = self.controller.get_var_names_as_string() + "\n"
-        if(self.output_file_path is None):
+        if self.output_file_path is None:
             sys.stdout.write(content)
         else:
             with open(self.output_file_path, "w") as f:
@@ -600,7 +662,7 @@ def print_state(self):
         standard output.
         """
         content = self.controller.get_state_as_string() + "\n"
-        if(self.output_file_path is None):
+        if self.output_file_path is None:
             sys.stdout.write(content)
         else:
             with open(self.output_file_path, "a") as f:
@@ -628,14 +690,14 @@ def run_verifyta(self, horizon, controlperiod, final, *args, **kwargs):
         :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
             each MPC step. Is given in the number of periods.
         :type horizon: int
-        :param period: The interval duration after which the controller can change the control setting,
-            given in Uppaal Stratego time units.
-        :type period: int
+        :param controlperiod: The interval duration after which the controller can change the
+            control setting, given in Uppaal Stratego time units.
+        :type controlperiod: int
         :param final: The time that should be reached by the synthesized strategy, given in Uppaal
             Stratego time units. Most likely this will be current time + *horizon* x *period*.
         :type final: int
-        :param `*args`: Is not used in this method; it is included here to safely override the original
-            method.
+        :param `*args`: Is not used in this method; it is included here to safely override the
+            original method.
         :param `**kwargs`: Is not used in this method; it is included here to safely override the
             original method.
         """
@@ -659,8 +721,8 @@ def create_alternative_query_file(self, horizon, period, final):
         :param horizon: The inval duration for which Uppaal stratego synthesizes a control strategy
             each MPC step. Is given in the number of periods.
         :type horizon: int
-        :param period: The interval duration after which the controller can change the control setting,
-            given in Uppaal Stratego time units.
+        :param period: The interval duration after which the controller can change the control
+            setting, given in Uppaal Stratego time units.
         :type period: int
         :param final: The time that should be reached by the synthesized strategy, given in Uppaal
             Stratego time units. Most likely this will be current time + *horizon* x *period*.