sierra-research 1.3.11__py3-none-any.whl → 1.5.0__py3-none-any.whl

sierra/core/ros1/callbacks.py

@@ -2,9 +2,7 @@
 #
 #  SPDX-License-Identifier: MIT
 #
-"""Common classes and callbacks :term:`Platforms <Platform>` using :term:`ROS1`.
-
-"""
+"""Common classes and callbacks :term:`Engines <Engine>` using :term:`ROS1`."""
 
 # Core packages
 import typing as tp
@@ -13,33 +11,36 @@ import typing as tp
 
 # Project packages
 from sierra.core import types
-from sierra.core.experiment import xml, definition
+from sierra.core.experiment import definition
 
 
-def population_size_from_pickle(adds_def: tp.Union[xml.AttrChangeSet,
-                                                   xml.TagAddList],
-                                main_config: types.YAMLDict,
-                                cmdopts: types.Cmdopts) -> int:
+def population_size_from_pickle(
+    adds_def: tp.Union[definition.AttrChangeSet, definition.ElementAddList],
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+) -> int:
+    """Extract population size from unpickled experiment definition."""
     for add in adds_def:
-        if 'name' in add.attr and 'n_robots' in add.attr['name']:
-            return int(add.attr['value'])
+        if "name" in add.attr and "n_agents" in add.attr["name"]:
+            return int(add.attr["value"])
 
     return 0
 
 
-def population_size_from_def(exp_def: definition.XMLExpDef,
-                             main_config: types.YAMLDict,
-                             cmdopts: types.Cmdopts) -> int:
-    return population_size_from_pickle(exp_def.tag_adds, main_config, cmdopts)
+def population_size_from_def(
+    exp_def: definition.BaseExpDef, main_config: types.YAMLDict, cmdopts: types.Cmdopts
+) -> int:
+    """Extract population size from experiment definition."""
+    return population_size_from_pickle(exp_def.element_adds, main_config, cmdopts)
 
 
-def robot_prefix_extract(main_config: types.YAMLDict,
-                         cmdopts: types.Cmdopts) -> str:
-    return main_config['ros']['robots'][cmdopts['robot']]['prefix']
+def robot_prefix_extract(main_config: types.YAMLDict, cmdopts: types.Cmdopts) -> str:
+    """Extract the common robot prefix based on cmdline opts + YAML config."""
+    return str(main_config["ros"]["robots"][cmdopts["robot"]]["prefix"])
 
 
-__api__ = [
-    'population_size_from_pickle',
-    'population_size_from_def',
-    'robot_prefix_extract'
+__all__ = [
+    "population_size_from_pickle",
+    "population_size_from_def",
+    "robot_prefix_extract",
 ]

sierra/core/ros1/cmdline.py

@@ -2,9 +2,7 @@
 #
 #  SPDX-License-Identifier: MIT
 #
-"""Common cmdline classes :term:`Platforms <Platform>` using :term:`ROS1`.
-
-"""
+"""Common cmdline classes :term:`Engines <Engine>` using :term:`ROS1`."""
 
 # Core packages
 import typing as tp
@@ -14,37 +12,23 @@ import argparse
 
 # Project packages
 from sierra.core import types, config
-import sierra.core.cmdline as cmd
-
-
-class ROSCmdline(cmd.BaseCmdline):
-    """Defines :term:`ROS1` common command line arguments.
-
-    """
-
-    def __init__(self,
-                 stages: tp.List[int]) -> None:
-        self.parser = argparse.ArgumentParser(add_help=False,
-                                              allow_abbrev=False)
-        self.scaffold_cli()
-        self.init_cli(stages)
+from sierra.plugins import PluginCmdline
 
-    def scaffold_cli(self) -> None:
-        self.multistage = self.parser.add_argument_group('Multi-stage options',
-                                                         'Options which are used in multiple pipeline stages')
-        self.stage1_exp = self.parser.add_argument_group(
-            'Stage1: Experiment generation')
 
-    def init_cli(self, stages: tp.List[int]) -> None:
-        if -1 in stages:
-            self.init_multistage()
+class ROSCmdline(PluginCmdline):
+    """Defines :term:`ROS1` common command line arguments."""
 
-        if 1 in stages:
-            self.init_stage1()
+    def __init__(
+        self,
+        parents: tp.List[argparse.ArgumentParser],
+        stages: tp.List[int],
+    ) -> None:
+        super().__init__(parents, stages)
 
     def init_multistage(self) -> None:
-        self.multistage.add_argument("--no-master-node",
-                                     help="""
+        self.multistage.add_argument(
+            "--no-master-node",
+            help="""
 
                                      Do not generate commands for/start a ROS1
                                      master node on the SIERRA host
@@ -52,7 +36,7 @@ class ROSCmdline(cmd.BaseCmdline):
 
                                      This is useful when:
 
-                                     - Using the :term:`ROS1+Robot` platform and
+                                     - Using the :term:`ROS1+Robot` engine and
                                        each robot outputs their own metrics to a
                                        shared filesystem.
 
@@ -60,66 +44,53 @@ class ROSCmdline(cmd.BaseCmdline):
                                        installed, and you are doing
                                        testing/bringup of robots.
 
-                                     """ + self.stage_usage_doc([1, 2]),
-                                     action='store_true')
+                                     """
+            + self.stage_usage_doc([1, 2]),
+            action="store_true",
+        )
 
     def init_stage1(self) -> None:
         # Experiment options
 
-        self.stage1_exp.add_argument("--exp-setup",
-                                     help="""
-
-                                     Defines experiment run length, ticks per
-                                     second for the experiment, # of datapoints
-                                     to capture/capture interval for each
-                                     simulation. See :ref:`ln-sierra-vars-expsetup` for
-                                     a full description.
-
-                            """ + self.stage_usage_doc([1]),
-                                     default="exp_setup.T{0}.K{1}.N{2}".format(
-                                         config.kROS['n_secs_per_run'],
-                                         config.kROS['n_ticks_per_sec'],
-                                         config.kExperimentalRunData['n_datapoints_1D']))
-
-        self.stage1_exp.add_argument("--robot",
-                                     help="""
-
-                                     The key name of the robot model, which must
-                                     be present in the appropriate section of
-                                     ``{0}`` for the :term:`Project`. See
-                                     :ref:`ln-sierra-tutorials-project-main-config`
-                                     for details.
-
-                            """.format(config.kYAML.main) + self.stage_usage_doc([1]))
-
-    @staticmethod
-    def cmdopts_update(cli_args, cmdopts: types.Cmdopts) -> None:
-        """Update cmdopts with ROS-specific cmdline options.
-        """
-        updates = {
-            # multistagev
-            'no_master_node': cli_args.no_master_node,
-
-            # stage 1
-            'robot': cli_args.robot,
-            'exp_setup': cli_args.exp_setup,
-
-        }
-
-        cmdopts.update(updates)
-
-
-class ROSCmdlineValidator():
-    """
-    Perform checks on parsed ROS cmdline arguments.
-    """
-
-    def __call__(self, args: argparse.Namespace) -> None:
-        assert args.robot is not None,\
-            "You must specify the --robot to use"
-
-
-__api__ = [
-    'ROSCmdline',
-    'ROSCmdlineValidator'
+        self.stage1.add_argument(
+            "--exp-setup",
+            help="""
+                 Defines experiment run length, ticks per second for the
+                 experiment.  See :ref:`usage/vars/expsetup` for a full
+                 description.
+                 """
+            + self.stage_usage_doc([1]),
+            default="exp_setup.T{0}.K{1}".format(
+                config.kROS["n_secs_per_run"],
+                config.kROS["n_ticks_per_sec"],
+            ),
+        )
+
+        self.stage1.add_argument(
+            "--robot",
+            required=True,
+            help="""
+                 The key name of the robot model, which must be present in the
+                 appropriate section of ``{0}`` for the :term:`Project`.  See
+                 :ref:`tutorials/project/config` for details.
+                 """.format(
+                config.kYAML.main
+            )
+            + self.stage_usage_doc([1]),
+        )
+
+
+def to_cmdopts(args: argparse.Namespace) -> types.Cmdopts:
+    """Update cmdopts with ROS-specific cmdline options."""
+    return {
+        # multistage
+        "no_master_node": args.no_master_node,
+        # stage 1
+        "robot": args.robot,
+        "exp_setup": args.exp_setup,
+    }
+
+
+__all__ = [
+    "ROSCmdline",
 ]

sierra/core/ros1/generators.py

@@ -1,9 +1,9 @@
 # Copyright 2021 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
-"""Classes for generating XML changes common to all :term:`ROS1` platforms.
+"""Classes for generating XML changes common to all :term:`ROS1` engines.
 
-I.e., changes which are platform-specific, but applicable to all projects using
+I.e., changes which are engine-specific, but applicable to all projects using
 ROS1.
 
 """
@@ -14,118 +14,105 @@ import pathlib
 # 3rd party packages
 
 # Project packages
-from sierra.core.experiment import definition, spec, xml
+from sierra.core.experiment import definition
+from sierra.core.experiment import spec as expspec
 import sierra.core.utils as scutils
 from sierra.core import types, config
 import sierra.core.ros1.variables.exp_setup as exp
+from sierra.core import plugin as pm
 
+_logger = logging.getLogger(__name__)
 
-class ROSExpDefGenerator():
-    """Generates XML changes to input files that common to all ROS experiments.
 
-     ROS1 requires up to 2 input files per run:
+def for_all_exp(
+    spec: expspec.ExperimentSpec,
+    controller: str,
+    cmdopts: types.Cmdopts,
+    expdef_template_fpath: pathlib.Path,
+) -> definition.BaseExpDef:
+    """Generate XML changes to input files that common to all ROS experiments.
 
-    - The launch file containing robot definitions, world definitions (for
-      simulations only).
+    ROS1 requires up to 2 input files per run:
 
-    - The parameter file for project code (optional).
+        - The launch file containing robot definitions, world definitions (for
+          simulations only).
+
+        - The parameter file for project code (optional).
 
     Putting everything in 1 file would require extensively using the ROS1
     parameter server which does NOT accept parameters specified in XML--only
-    YAML. So requiring some conventions on the .launch input file seemed more
+    YAML.  So requiring some conventions on the .launch input file seemed more
     reasonable.
+    """
+    module = pm.pipeline.get_plugin_module(cmdopts["expdef"])
+
+    exp_def = module.ExpDef(input_fpath=expdef_template_fpath, write_config=None)
+
+    wr_config = definition.WriterConfig([])
+
+    if exp_def.has_element("./params"):
+        _logger.debug("Using shared XML parameter file")
+        wr_config.add(
+            {
+                "src_parent": ".",
+                "src_tag": "params",
+                "opath_leaf": config.kROS["param_file_ext"],
+                "new_children": None,
+                "new_children_parent": None,
+                "rename_to": None,
+            }
+        )
+
+    exp_def.write_config_set(wr_config)
+
+    # Add <master> tag
+    if not exp_def.has_element("./master"):
+        exp_def.element_add(".", "master", {})
+    if not exp_def.has_element("./master/group/[@ns='sierra']"):
+        exp_def.element_add("./master", "group", {"ns": "sierra"})
+    # Add <robot> tag
+    if not exp_def.has_element("./robot"):
+        exp_def.element_add(".", "robot", {})
+    if not exp_def.has_element("./robot/group/[@ns='sierra']"):
+        exp_def.element_add("./robot", "group", {"ns": "sierra"})
+
+    # Generate core experiment definitions
+    _generate_all_exp_experiment(exp_def, spec, cmdopts)
+
+    return exp_def
+
+
+def _generate_all_exp_experiment(
+    exp_def: definition.BaseExpDef, spec: expspec.ExperimentSpec, cmdopts: types.Cmdopts
+) -> None:
+    """
+    Generate XML tag changes to setup basic experiment parameters.
+
+    Writes generated changes to the simulation definition pickle file.
+    """
+    _logger.debug("Applying exp_setup=%s", cmdopts["exp_setup"])
+    robots_need_timekeeper = "ros1robot" in cmdopts["engine"]
 
-    Attributes:
+    # Barrier start not needed in simulation
+    use_barrier_start = (
+        "ros1robot" in cmdopts["engine"] and not cmdopts["no_master_node"]
+    )
 
-        controller: The controller used for the experiment.
-        cmdopts: Dictionary of parsed cmdline parameters.
+    setup = exp.factory(cmdopts["exp_setup"], use_barrier_start, robots_need_timekeeper)
+    _, adds, chgs = scutils.apply_to_expdef(setup, exp_def)
 
-    """
+    # Write setup info to file for later retrieval
+    scutils.pickle_modifications(adds, chgs, spec.exp_def_fpath)
 
-    def __init__(self,
-                 exp_spec: spec.ExperimentSpec,
-                 controller: str,
-                 cmdopts: types.Cmdopts,
-                 **kwargs) -> None:
-        self.controller = controller
-        self.spec = exp_spec
-        self.cmdopts = cmdopts
-        self.template_input_file = kwargs['template_input_file']
-        self.kwargs = kwargs
-        self.ros_param_server = False
-        self.logger = logging.getLogger(__name__)
-
-    def generate(self) -> definition.XMLExpDef:
-        exp_def = definition.XMLExpDef(input_fpath=self.template_input_file)
-        wr_config = xml.WriterConfig([])
-
-        if exp_def.has_tag('./params'):
-            self.logger.debug("Using shared XML parameter file")
-            wr_config.add({
-                'src_parent': '.',
-                'src_tag': 'params',
-                'opath_leaf': config.kROS['param_file_ext'],
-                'create_tags': None,
-                'dest_parent': None,
-                'rename_to': None
-            })
-
-        else:
-            self.ros_param_server = True
-
-        exp_def.write_config_set(wr_config)
-
-        # Add <master> tag
-        if not exp_def.has_tag("./master"):
-            exp_def.tag_add(".",
-                            "master",
-                            {})
-        if not exp_def.has_tag("./master/group/[@ns='sierra']"):
-            exp_def.tag_add("./master",
-                            "group",
-                            {
-                                'ns': 'sierra'
-                            })
-        # Add <robot> tag
-        if not exp_def.has_tag("./robot"):
-            exp_def.tag_add(".",
-                            "robot",
-                            {})
-        if not exp_def.has_tag("./robot/group/[@ns='sierra']"):
-            exp_def.tag_add("./robot",
-                            "group",
-                            {
-                                'ns': 'sierra'
-                            })
-
-        # Generate core experiment definitions
-        self._generate_experiment(exp_def)
-
-        return exp_def
-
-    def _generate_experiment(self, exp_def: definition.XMLExpDef) -> None:
-        """
-        Generate XML tag changes to setup basic experiment parameters.
-
-        Writes generated changes to the simulation definition pickle file.
-        """
-        self.logger.debug("Applying exp_setup=%s", self.cmdopts['exp_setup'])
-        robots_need_timekeeper = 'ros1robot' in self.cmdopts['platform']
-
-        # Barrier start not needed in simulation
-        use_barrier_start = ('ros1robot' in self.cmdopts['platform'] and
-                             not self.cmdopts["no_master_node"])
-
-        setup = exp.factory(self.cmdopts["exp_setup"],
-                            use_barrier_start,
-                            robots_need_timekeeper)()
-        rms, adds, chgs = scutils.apply_to_expdef(setup, exp_def)
-
-        # Write setup info to file for later retrieval
-        scutils.pickle_modifications(adds, chgs, self.spec.exp_def_fpath)
-
-
-class ROSExpRunDefUniqueGenerator:
+
+def for_single_exp_run(
+    exp_def: definition.BaseExpDef,
+    run_num: int,
+    run_output_path: pathlib.Path,
+    launch_stem_path: pathlib.Path,
+    random_seed: int,
+    cmdopts: types.Cmdopts,
+) -> None:
     """
     Generate XML changes unique to a experimental runs for ROS experiments.
 
@@ -135,80 +122,77 @@ class ROSExpRunDefUniqueGenerator:
 
     - Unique parameter file for each: term: `Experimental Run`.
     """
-
-    def __init__(self,
-                 run_num: int,
-                 run_output_path: pathlib.Path,
-                 launch_stem_path: pathlib.Path,
-                 random_seed: int,
-                 cmdopts: types.Cmdopts) -> None:
-
-        self.run_output_path = run_output_path
-        self.launch_stem_path = launch_stem_path
-        self.random_seed = random_seed
-        self.cmdopts = cmdopts
-        self.run_num = run_num
-        self.logger = logging.getLogger(__name__)
-
-    def generate(self, exp_def: definition.XMLExpDef):
-        return exp_def
-
-    def generate_random(self, exp_def: definition.XMLExpDef) -> None:
-        """Generate XML changes for random seeding for an experimental run.
-
-        """
-        self.logger.trace("Generating random seed changes for run%s",  # type: ignore
-                          self.run_num)
-
-        # Master gets the random seed
-        exp_def.tag_add("./master/group/[@ns='sierra']",
-                        "param",
-                        {
-                            "name": "experiment/random_seed",
-                            "value": str(self.random_seed)
-                        })
-
-        # Each robot gets the random seed
-        exp_def.tag_add("./robot/group/[@ns='sierra']",
-                        "param",
-                        {
-                            "name": "experiment/random_seed",
-                            "value": str(self.random_seed)
-                        })
-
-    def generate_paramfile(self, exp_def: definition.XMLExpDef) -> None:
-        """Generate XML changes for the parameter file for an experimental run.
-
-        """
-        self.logger.trace("Generating parameter file changes for run%s",  # type: ignore
-                          self.run_num)
-
-        param_file = self.launch_stem_path.with_suffix(config.kROS['param_file_ext'])
-
-        # Master node gets a copy of the parameter file
-        exp_def.tag_add("./master/group/[@ns='sierra']",
-                        "param",
-                        {
-                            "name": "experiment/param_file",
-                            "value": str(param_file)
-                        })
-
-        # Each robot gets a copy of the parameter file
-        if not exp_def.has_tag("./robot/group/[@ns='sierra']"):
-            exp_def.tag_add("./robot",
-                            "group",
-                            {
-                                "ns": "sierra",
-                            })
-        exp_def.tag_add("./robot/group/[@ns='sierra']",
-                        "param",
-                        {
-                            "name": "experiment/param_file",
-                            "value": str(param_file)
-                        })
-
-
-__api__ = [
-    'ROSExpDefGenerator',
-    'ROSExpRunDefUniqueGenerator'
-]
+    _generate_single_exp_run_random(
+        exp_def, run_num, run_output_path, launch_stem_path, random_seed, cmdopts
+    )
+
+    _generate_single_exp_run_paramfile(
+        exp_def, run_num, run_output_path, launch_stem_path, random_seed, cmdopts
+    )
+
+
+def _generate_single_exp_run_random(
+    exp_def: definition.BaseExpDef,
+    run_num: int,
+    run_output_path: pathlib.Path,
+    launch_stem_path: pathlib.Path,
+    random_seed: int,
+    cmdopts: types.Cmdopts,
+) -> None:
+    """Generate XML changes for random seeding for an experimental run."""
+    _logger.trace("Generating random seed changes for run%s", run_num)  # type: ignore
+
+    # Master gets the random seed
+    exp_def.element_add(
+        "./master/group/[@ns='sierra']",
+        "param",
+        {"name": "experiment/random_seed", "value": str(random_seed)},
+    )
+
+    # Each robot gets the random seed
+    exp_def.element_add(
+        "./robot/group/[@ns='sierra']",
+        "param",
+        {"name": "experiment/random_seed", "value": str(random_seed)},
+    )
+
+
+def _generate_single_exp_run_paramfile(
+    exp_def: definition.BaseExpDef,
+    run_num: int,
+    run_output_path: pathlib.Path,
+    launch_stem_path: pathlib.Path,
+    random_seed: int,
+    cmdopts: types.Cmdopts,
+) -> None:
+    """Generate XML changes for the parameter file for an experimental run."""
+    _logger.trace(
+        "Generating parameter file changes for run%s", run_num  # type: ignore
+    )
+
+    param_file = launch_stem_path.with_suffix(config.kROS["param_file_ext"])
+
+    # Master node gets a copy of the parameter file
+    exp_def.element_add(
+        "./master/group/[@ns='sierra']",
+        "param",
+        {"name": "experiment/param_file", "value": str(param_file)},
+    )
+
+    # Each robot gets a copy of the parameter file
+    if not exp_def.has_element("./robot/group/[@ns='sierra']"):
+        exp_def.element_add(
+            "./robot",
+            "group",
+            {
+                "ns": "sierra",
+            },
+        )
+    exp_def.element_add(
+        "./robot/group/[@ns='sierra']",
+        "param",
+        {"name": "experiment/param_file", "value": str(param_file)},
+    )
+
+
+__all__ = ["for_all_exp", "for_single_exp_run"]

sierra/core/ros1/variables/__init__.py

@@ -1,6 +1,9 @@
 # Copyright 2022 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
+"""
+Common variables module for the :term:`ROS1` engine.
+"""
 
 # Core packages