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

sierra/plugins/engine/argos/variables/population_variable_density.py

@@ -0,0 +1,123 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+#
+"""Classes for the variable population density batch criteria.
+
+See :ref:`plugins/engine/argos/bc/population-variable-density` for usage
+documentation.
+
+"""
+
+# Core packages
+import typing as tp
+import logging
+import pathlib
+
+# 3rd party packages
+import implements
+
+# Project packages
+from sierra.core.variables import variable_density as vd
+from sierra.core.vector import Vector3D
+from sierra.core.experiment import definition
+from sierra.core import types, utils
+from sierra.core.graphs import bcbridge
+
+
+@implements.implements(bcbridge.IGraphable)
+class PopulationVariableDensity(vd.VariableDensity):
+    """Defines XML changes for variable population density within a single arena.
+
+    This class is a base class which should (almost) never be used on its
+    own. Instead, the ``factory()`` function should be used to dynamically
+    create derived classes expressing the user's desired density ranges.
+
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        vd.VariableDensity.__init__(self, *args, **kwargs)
+        self.already_added = False
+        self.logger = logging.getLogger(__name__)
+
+    def gen_attr_changelist(self) -> tp.List[definition.AttrChangeSet]:
+        """Generate XML modifications to achieve the desired population densities.
+
+        Robots are approximated as point masses.
+
+        """
+        if not self.already_added:
+            for density in self.densities:
+                # ARGoS won't start if there are 0 robots, so you always
+                # need to put at least 1.
+                n_agents = int(self.extent.area() * (density / 100.0))
+                if n_agents == 0:
+                    n_agents = 1
+                    self.logger.warning(
+                        "n_agents set to 1 even though \
+                    calculated as 0 for area=%d,density=%s",
+                        self.extent.area(),
+                        density,
+                    )
+                changeset = definition.AttrChangeSet(
+                    definition.AttrChange(
+                        ".//arena/distribute/entity", "quantity", str(n_agents)
+                    )
+                )
+                self.attr_changes.append(changeset)
+                self.logger.debug(
+                    "Calculated swarm size=%d for extent=%s,density=%s",
+                    n_agents,
+                    str(self.extent),
+                    density,
+                )
+
+            self.already_added = True
+
+        return self.attr_changes
+
+    def graph_info(
+        self,
+        cmdopts: types.Cmdopts,
+        batch_output_root: tp.Optional[pathlib.Path] = None,
+        exp_names: tp.Optional[tp.List[str]] = None,
+    ) -> bcbridge.GraphInfo:
+        info = bcbridge.GraphInfo(
+            cmdopts,
+            batch_output_root,
+            exp_names if exp_names else self.gen_exp_names(),
+        )
+
+        info.xticks = [
+            p / self.extent.area()
+            for p in self.populations(info.cmdopts, info.exp_names)
+        ]
+        info.xticklabels = list(map(lambda x: str(round(x, 4)), info.xticks))
+        info.xlabel = "Population Density"
+        return info
+
+    def n_agents(self, exp_num: int) -> int:
+        return int(self.extent.area() * self.densities[exp_num] / 100.0)
+
+
+def factory(
+    cli_arg: str,
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    batch_input_root: pathlib.Path,
+    **kwargs,
+) -> PopulationVariableDensity:
+    """
+    Create a :class:`PopulationVariableDensity` derived class.
+    """
+    densities = vd.parse(cli_arg)
+    kw = utils.gen_scenario_spec(cmdopts, **kwargs)
+
+    extent = utils.ArenaExtent(Vector3D(kw["arena_x"], kw["arena_y"], kw["arena_z"]))
+
+    return PopulationVariableDensity(
+        cli_arg, main_config, batch_input_root, densities, extent
+    )
+
+
+__all__ = ["PopulationVariableDensity"]

sierra/plugins/engine/argos/variables/rendering.py

@@ -0,0 +1,108 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+
+"""
+ARGoS headless QT rendering configuration.
+"""
+
+# Core packages
+import typing as tp
+
+# 3rd party packages
+import implements
+
+# Project packages
+from sierra.core.variables.base_variable import IBaseVariable
+from sierra.core.experiment import definition
+import sierra.core.config
+from sierra.core import types
+
+import sierra.plugins.engine.argos.variables.exp_setup as exp
+
+
+@implements.implements(IBaseVariable)
+class ARGoSQTHeadlessRendering:
+    """
+    Sets up ARGoS headless rendering with QT.
+
+    Attributes:
+        tsetup: Simulation time definitions.
+
+        extents: List of (X,Y,Zs) tuple of dimensions of area to assign to
+                 engines of the specified type.
+    """
+
+    kFrameSize = "1600x1200"
+    kQUALITY = 100
+    kFRAME_RATE = 10
+
+    def __init__(self, setup: exp.ExpSetup) -> None:
+        self.setup = setup
+        self.element_adds = []  # type: tp.List[definition.ElementAddList]
+
+    def gen_attr_changelist(self) -> tp.List[definition.AttrChangeSet]:
+        """
+        No effect.
+
+        All tags/attributes are either deleted or added.
+        """
+        return []
+
+    def gen_tag_rmlist(self) -> tp.List[definition.ElementRmList]:
+        """Remove the ``<qt_opengl>`` tag if it exists.
+
+        Obviously you *must* call this function BEFORE adding new definitions.
+
+        """
+        return [
+            definition.ElementRmList(
+                definition.ElementRm("./visualization", "qt-opengl")
+            )
+        ]
+
+    def gen_element_addlist(self) -> tp.List[definition.ElementAddList]:
+        if not self.element_adds:
+            self.element_adds = [
+                definition.ElementAddList(
+                    definition.ElementAdd(".", "visualization", {}, False),
+                    definition.ElementAdd(
+                        "./visualization", "qt-opengl", {"autoplay": "true"}, False
+                    ),
+                    definition.ElementAdd(
+                        "./visualization/qt-opengl",
+                        "frame_grabbing",
+                        {
+                            "directory": "frames",
+                            "base_name": "frame_",
+                            "format": sierra.core.config.kStaticImageType,
+                            "headless_grabbing": "true",
+                            "headless_frame_size": "{0}".format(self.kFrameSize),
+                            "headless_frame_rate": "{0}".format(self.kFRAME_RATE),
+                        },
+                        False,
+                    ),
+                    definition.ElementAdd(
+                        "visualization/qt-opengl",
+                        "user_functions",
+                        {"label": "__EMPTY__"},
+                        False,
+                    ),
+                )
+            ]
+
+        return self.element_adds
+
+    def gen_files(self) -> None:
+        pass
+
+
+def factory(cmdopts: types.Cmdopts) -> ARGoSQTHeadlessRendering:
+    """Set up QT headless rendering for the specified experimental setup."""
+
+    return ARGoSQTHeadlessRendering(exp.factory(cmdopts["exp_setup"]))
+
+
+__all__ = [
+    "ARGoSQTHeadlessRendering",
+]

sierra/plugins/engine/ros1gazebo/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""
+Container module for the :term:`ROS1+Gazebo` engine.
+
+See :ref:`plugins/engine/ros1gazebo`.
+"""
+
+# Core packages
+
+# 3rd party packages
+
+# Project packages
+
+
+def sierra_plugin_type() -> str:
+    return "pipeline"

sierra/plugins/engine/ros1gazebo/cmdline.py

@@ -0,0 +1,175 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+#
+"""
+Command line parsing and validation for the :term:`ROS1+Gazebo` engine.
+"""
+
+# Core packages
+import typing as tp
+import argparse
+
+# 3rd party packages
+
+# Project packages
+from sierra.core import types
+from sierra.core import config
+from sierra.core import ros1
+from sierra.plugins import PluginCmdline
+
+
+class EngineCmdline(ros1.cmdline.ROSCmdline):
+    """Defines :term:`ROS1+Gazebo` extensions to :class:`~sierra.core.cmdline.CoreCmdline`."""
+
+    def __init__(
+        self,
+        parents: tp.List[argparse.ArgumentParser],
+        stages: tp.List[int],
+    ) -> None:
+        super().__init__(parents, stages)
+
+    def init_stage1(self) -> None:
+        super().init_stage1()
+        # Experiment options
+        positions_omitted_doc = (
+            "If omitted: effective arena dimensions must "
+            "be given as part of ``--scenario``."
+        )
+
+        self.stage1.add_argument(
+            "--robot-positions",
+            help="""
+                 A list of space-separated "X,Y,Z" tuples (no quotes) passed on
+                 the command line as valid starting positions for the robots
+                 within the world.
+                 """
+            + self.stage_usage_doc([1], positions_omitted_doc),
+            nargs="+",
+            default=[],
+        )
+
+        # Physics engines options
+        self.stage1.add_argument(
+            "--physics-engine-type",
+            choices=["ode", "bullet", "dart", "simbody"],
+            help="""
+                 The type of 3D physics engine to use for managing spatial
+                 extents within the arena, choosing one of the types that
+                 :term:`Gazebo` supports.  A single engine instance is used to
+                 manage all physics in the arena.
+                 """
+            + self.stage_usage_doc([1]),
+            default="ode",
+        )
+
+        self.stage1.add_argument(
+            "--physics-iter-per-tick",
+            type=int,
+            help="""
+                 The # of iterations all physics engines should perform per tick
+                 each time the controller loops are run (the # of ticks per
+                 second for controller control loops is set via
+                 ``--exp-setup``).
+                 """
+            + self.stage_usage_doc([1]),
+            default=config.kGazebo["physics_iter_per_tick"],
+        )
+
+        self.stage1.add_argument(
+            "--physics-n-threads",
+            type=int,
+            help="""
+                 Gazebo can group non-interacting entities into computational
+                 "islands" and do the physics updates for those islands in
+                 parallel each timestep (islands) are recomputed after each
+                 timestep).  Gazebo can also parallelize the computation of
+                 velocity/position updates with the computation of resolving
+                 collisions (i.e., the timestep impulse results in one entity
+                 "inside" another).  You can assign multiple threads to a pool
+                 for cumulative use for these two parallelization methods
+                 (threads will be allocated evenly between them).  The point at
+                 which adding more threads will start to DECREASE performance
+                 depends on the complexity of your world, the number and type of
+                 robots in it, etc., so don't just set this parameter to the #
+                 of cores for your machine as a default.
+
+                 From the Gazebo Parallel Physics Report, setting the pool size
+                 to the # robots/# joint trees in your simulation usually gives
+                 good results, as long as you have more cores available than you
+                 allocate to this pool (Gazebo has other threads too).
+
+                 This only applies if ``--physics-engine-type``\\=ode.
+
+                 A value of 0=no threads.
+                 """
+            + self.stage_usage_doc([1]),
+            default=0,
+        )
+
+        self.stage1.add_argument(
+            "--physics-ec-threadpool",
+            type=int,
+            help="""
+                 Gazebo can parallelize the computation of velocity/position
+                 updates with the computation of resolving collisions (i.e., the
+                 timestep impulse results in one entity "inside" another).  You
+                 can assign multiple threads to a pool for cumulative use for
+                 this purpose.  The point at which adding more threads will
+                 start to DECREASE performance depends on the complexity of your
+                 world, the number and type of robots in it, etc., so don't just
+                 set this parameter to the # of cores for your machine as a
+                 default.
+
+                 From the Gazebo Parallel Physics Report, setting the pool size
+                 to the # robots/#joint trees in your simulation usually gives
+                 good results, as long as you have more cores than than you
+                 allocate to physics (Gazebo has other threads too).
+
+                 This only applies if ``--physics-engine-type``\\=ode.
+
+                 A value of 0=no threads.
+                 """
+            + self.stage_usage_doc([1]),
+            default=0,
+        )
+
+
+def build(
+    parents: tp.List[argparse.ArgumentParser], stages: tp.List[int]
+) -> PluginCmdline:
+    """
+    Get a cmdline parser supporting the :term:`ROS1+Gazebo` engine.
+
+    Contains:
+
+        - :class:`~sierra.core.ros1.cmdline.ROSCmdline` (ROS1 common)
+
+        - :class:`~sierra.plugins.engine.ros1gazebo.cmdline.EngineCmdline`
+          (ROS1+Gazebo)
+    """
+    return EngineCmdline(parents=parents, stages=stages)
+
+
+def to_cmdopts(args: argparse.Namespace) -> types.Cmdopts:
+    """Update cmdopts with ROS1+Gazebo-specific cmdline options."""
+    opts = ros1.cmdline.to_cmdopts(args)
+
+    for_self = {
+        # stage 1
+        "robot_positions": args.robot_positions,
+        "physics_n_engines": 1,  # Always 1 for gazebo...
+        "physics_n_threads": args.physics_n_threads,
+        "physics_engine_type": args.physics_engine_type,
+        "physics_iter_per_tick": args.physics_iter_per_tick,
+    }
+
+    opts |= for_self
+    return opts
+
+
+def sphinx_cmdline_stage1():
+    return EngineCmdline([], [1]).parser
+
+
+__all__ = ["EngineCmdline"]

sierra/plugins/{platform/ros1robot → engine/ros1gazebo}/generators/__init__.py

@@ -1,6 +1,11 @@
 # Copyright 2022 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
+"""
+Generators module for the :term:`ROS1+Gazebo` engine.
+
+See :ref:`plugins/engine/ros1gazebo`.
+"""
 
 # Core packages
 

sierra/plugins/engine/ros1gazebo/generators/engine.py

@@ -0,0 +1,125 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""Classes for generating common XML modifications for :term:`ROS1+Gazebo`.
+
+I.e., changes which are engine-specific, but applicable to all projects using
+the engine.
+
+"""
+# Core packages
+import logging
+import pathlib
+
+# 3rd party packages
+
+# Project packages
+from sierra.core.experiment import spec as expspec
+from sierra.core.experiment import definition
+from sierra.core import types, ros1, config
+
+_logger = logging.getLogger(__name__)
+
+
+def for_all_exp(spec: expspec.ExperimentSpec,
+                controller: str,
+                cmdopts: types.Cmdopts,
+                expdef_template_fpath: pathlib.Path) -> definition.BaseExpDef:
+    """Generate XML modifications common to all ROS1+Gazebo experiments."""
+    exp_def = ros1.generators.for_all_exp(spec,
+                                          controller,
+                                          cmdopts,
+                                          expdef_template_fpath)
+
+    exp_def.write_config.add({
+        'src_parent': ".",
+        'src_tag': "master",
+        'opath_leaf': "_master" + config.kROS['launch_file_ext'],
+        'new_children': None,
+        'new_children_parent': None,
+        'rename_to': 'launch'
+    })
+
+    exp_def.write_config.add({
+        'src_parent': ".",
+        'src_tag': "robot",
+        'opath_leaf': "_robots" + config.kROS['launch_file_ext'],
+        'new_children': None,
+        'new_children_parent': None,
+        'rename_to': 'launch'
+    })
+
+    # Setup gazebo experiment
+    _generate_all_exp_gazebo_core(exp_def)
+
+    # Setup gazebo visualization
+    _generate_all_exp_gazebo_vis(exp_def)
+
+    return exp_def
+
+
+def _generate_all_exp_gazebo_core(exp_def: definition.BaseExpDef) -> None:
+    """
+    Generate XML tag changes to setup Gazebo core experiment parameters.
+
+    Does not write generated changes to the run definition pickle
+    file.
+    """
+    _logger.debug("Generating Gazebo experiment changes (all runs)")
+
+    # Start Gazebo/ROS in debug mode to make post-mortem analysis easier.
+    exp_def.element_add("./master/include",
+                        "arg",
+                        {
+                            "name": "verbose",
+                            "value": "true"
+                        })
+
+    # Terminate Gazebo server whenever the launch script that invoked it
+    # exits.
+    exp_def.element_add("./master/include",
+                        "arg",
+                        {
+                            "name": "server_required",
+                            "value": "true"
+                        })
+
+    # Don't record stuff
+    exp_def.element_remove("./master/include", "arg/[@name='headless']")
+    exp_def.element_remove("./master/include", "arg/[@name='recording']")
+
+    # Don't start paused
+    exp_def.element_remove("./master/include", "arg/[@name='paused']")
+
+    # Don't start gazebo under gdb
+    exp_def.element_remove("./master/include", "arg/[@name='debug']")
+
+
+def _generate_all_exp_gazebo_vis(exp_def: definition.BaseExpDef) -> None:
+    """
+    Generate XML changes to configure Gazebo visualizations.
+
+    Does not write generated changes to the simulation definition pickle
+    file.
+    """
+    exp_def.element_remove_all("./master/include", "arg/[@name='gui']")
+    exp_def.element_add("./master/include",
+                        "arg",
+                        {
+                            "name": "gui",
+                            "value": "false"
+                        })
+
+
+def for_single_exp_run(*args, **kwargs) -> None:
+    """Generate XML changes unique to each experimental run.
+
+    Wraps :py:func:`sierra.core.ros1.generators.for_single_exp_run`.
+    """
+    return ros1.generators.for_single_exp_run(*args, **kwargs)
+
+
+__all__ = [
+    'for_all_exp',
+    'for_single_exp_run'
+]