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

sierra/plugins/compare/graphs/preprocess.py

@@ -0,0 +1,172 @@
+#
+# Copyright 2024 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""Preprocess inter-experiment outputs for stage 5.
+
+Basically, gather statistics generated from controllers for graph generation in
+previous stages into the correct files(s) for comparison.
+"""
+
+# Core packages
+import pathlib
+import typing as tp
+
+# 3rd party packages
+import pandas as pd
+
+# Project packages
+from sierra.core import utils, config, storage
+from sierra.core.variables import batch_criteria as bc
+
+
+class IntraExpPreparer:
+    """
+    Collate generated stats from previous stages into files(s) for comparison.
+    """
+
+    def __init__(
+        self,
+        ipath_stem: pathlib.Path,
+        ipath_leaf: str,
+        opath_stem: pathlib.Path,
+        criteria: bc.XVarBatchCriteria,
+    ):
+        self.ipath_stem = ipath_stem
+        self.ipath_leaf = ipath_leaf
+        self.opath_stem = opath_stem
+        self.criteria = criteria
+
+    def for_cc(
+        self,
+        controller: str,
+        opath_leaf: str,
+        index: int,
+        inc_exps: tp.Optional[str],
+    ) -> None:
+        """
+        Take batch-level dataframes and creates a new dataframe.
+
+        Has:
+
+        - Experiment names for the index.
+
+        - Controller names as column names (guaranteed to be unique, since
+          that's what we are comparing).
+
+        - df[controller] columns as timeslices *across* columns (i.e., across
+          experiments in the batch) in the source dataframe.
+        """
+        exts = config.kStats["mean"].exts
+        exts.update(config.kStats["conf95"].exts)
+        exts.update(config.kStats["bw"].exts)
+
+        for k in exts:
+            stat_ipath = pathlib.Path(self.ipath_stem, self.ipath_leaf + exts[k])
+            stat_opath = pathlib.Path(self.opath_stem, opath_leaf + exts[k])
+            df = self._cc_for_stat(stat_ipath, stat_opath, index, inc_exps, controller)
+
+            if df is not None:
+                storage.df_write(
+                    df,
+                    self.opath_stem / (opath_leaf + exts[k]),
+                    "storage.csv",
+                    index=True,
+                )
+
+    def for_sc(
+        self,
+        scenario: str,
+        opath_leaf: str,
+        index: int,
+        inc_exps: tp.Optional[str],
+    ) -> None:
+        """
+        Take batch-level dataframes and creates a new dataframe.
+
+        Has:
+
+        - Experiment names for the index.
+
+        - Scenario names as column names (guaranteed to be unique, since
+          that's what we are comparing).
+
+        - df[scenario] columns as timeslices *across* columns (i.e., across
+          experiments in the batch) in the source dataframe.
+        """
+        exts = config.kStats["mean"].exts
+        exts.update(config.kStats["conf95"].exts)
+        exts.update(config.kStats["bw"].exts)
+
+        for k in exts:
+            stat_ipath = pathlib.Path(self.ipath_stem, self.ipath_leaf + exts[k])
+            stat_opath = pathlib.Path(self.opath_stem, opath_leaf + exts[k])
+            df = self._sc_for_stat(stat_ipath, stat_opath, index, inc_exps, scenario)
+
+            if df is not None:
+                storage.df_write(
+                    df,
+                    self.opath_stem / (opath_leaf + exts[k]),
+                    "storage.csv",
+                    index=True,
+                )
+
+    def _cc_for_stat(
+        self,
+        ipath: pathlib.Path,
+        opath: pathlib.Path,
+        index: int,
+        inc_exps: tp.Optional[str],
+        controller: str,
+    ) -> pd.DataFrame:
+
+        if utils.path_exists(opath):
+            cum_df = storage.df_read(opath, "storage.csv", index_col="Experiment ID")
+        else:
+            cum_df = pd.DataFrame(index=self.criteria.gen_exp_names())
+            cum_df.index.name = "Experiment ID"
+
+        if utils.path_exists(ipath):
+            df = storage.df_read(ipath, "storage.csv")
+
+            # if inc_exps is not None:
+            # cols = utils.exp_include_filter(
+            #     inc_exps, list(df.columns), self.criteria.n_exp()
+            # )
+
+            cum_df[controller] = df.iloc[index]
+            return cum_df
+
+        return None
+
+    def _sc_for_stat(
+        self,
+        ipath: pathlib.Path,
+        opath: pathlib.Path,
+        index: int,
+        inc_exps: tp.Optional[str],
+        scenario: str,
+    ) -> pd.DataFrame:
+        if utils.path_exists(opath):
+            cum_df = storage.df_read(opath, "storage.csv", index_col="Experiment ID")
+        else:
+            cum_df = pd.DataFrame(index=self.criteria.gen_exp_names())
+            cum_df.index.name = "Experiment ID"
+
+        if utils.path_exists(ipath):
+            df = storage.df_read(ipath, "storage.csv")
+
+            # if inc_exps is not None:
+            #     cols = utils.exp_include_filter(
+            #         inc_exps, list(df.columns), self.criteria.n_exp()
+            #     )
+
+            cum_df[scenario] = df.iloc[index]
+
+            return cum_df
+
+        return None
+
+
+__all__ = ["IntraExpPreparer"]

sierra/plugins/compare/graphs/schema.py

@@ -0,0 +1,37 @@
+#
+# Copyright 2025 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""
+YAML schemas for comparison graphs for stage 5.
+
+See :ref:`plugins/compare/graphs` for more details.
+"""
+# Core packages
+
+# 3rd party packages
+import strictyaml
+
+# Project packages
+
+
+cc = strictyaml.Map(
+    {
+        "src_stem": strictyaml.Str(),
+        "dest_stem": strictyaml.Str(),
+        strictyaml.Optional("title"): strictyaml.Str(),
+        strictyaml.Optional("label"): strictyaml.Str(),
+        strictyaml.Optional("primary_axis"): strictyaml.Int(),
+        strictyaml.Optional("include_exp"): strictyaml.Str(),
+        strictyaml.Optional("backend"): strictyaml.Str(),
+    }
+)
+"""
+Schema for controller comparison graphs.
+"""
+
+sc = cc
+"""
+Schema for scenario comparison graphs.
+"""

sierra/plugins/engine/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""
+Container module for plugins related to :term:`Engines <Engine>`.
+
+Driven by ``--engine``.
+"""
+
+# Core packages
+
+# 3rd party packages
+
+# Project packages

sierra/plugins/engine/argos/__init__.py

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

sierra/plugins/{platform → engine}/argos/cmdline.py

@@ -3,7 +3,7 @@
 #  SPDX-License-Identifier: MIT
 #
 """
-Command line parsing and validation for the :term:`ARGoS`.
+Command line definitions for the :term:`ARGoS` :term:`Engine`.
 """
 
 # Core packages
@@ -13,68 +13,43 @@ import argparse
 # 3rd party packages
 
 # Project packages
-from sierra.core import types, config, hpc
-import sierra.core.cmdline as cmd
+from sierra.core import types, config
+from sierra.plugins import PluginCmdline
 
 
-class PlatformCmdline(cmd.BaseCmdline):
-    """Defines :term:`ARGoS` extensions to :class:`~sierra.core.cmdline.CoreCmdline`.
+class EngineCmdline(PluginCmdline):
+    """Defines :term:`ARGoS` cmdline."""
 
-    """
-
-    def __init__(self,
-                 parents: tp.Optional[tp.List[argparse.ArgumentParser]],
-                 stages: tp.List[int]) -> None:
-
-        if parents is not None:
-            self.parser = argparse.ArgumentParser(add_help=False,
-                                                  parents=parents,
-                                                  allow_abbrev=False)
-        else:
-            self.parser = argparse.ArgumentParser(add_help=False,
-                                                  allow_abbrev=False)
-
-        self.scaffold_cli()
-        self.init_cli(stages)
-
-    def scaffold_cli(self) -> None:
-        self.stage1_exp = self.parser.add_argument_group(
-            'Stage1: Experiment generation')
-        self.stage1_physics = self.parser.add_argument_group(
-            'Stage1: Configuring ARGoS physics engines')
-        self.stage1_rendering = self.parser.add_argument_group(
-            'Stage1: Rendering (see also stage4 rendering options)')
-        self.stage1_robots = self.parser.add_argument_group(
-            'Stage1: Configuring robots')
-
-    def init_cli(self, stages: tp.List[int]) -> None:
-        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_stage1(self) -> None:
         # Experiment options
 
-        self.stage1_exp.add_argument("--exp-setup",
-                                     help="""
-
-                                     Defines experiment run length, :term:`Ticks
-                                     <Tick>` per second for the experiment
-                                     (<experiment> tag), # 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.kARGoS['n_secs_per_run'],
-                                         config.kARGoS['n_ticks_per_sec'],
-                                         config.kExperimentalRunData['n_datapoints_1D']))
+        self.stage1.add_argument(
+            "--exp-setup",
+            help="""
+                 Defines experiment run length, :term:`Ticks <Tick>` per second
+                 for the experiment (<experiment> tag).  See
+                 :ref:`usage/vars/expsetup` for a full description.
+                 """
+            + self.stage_usage_doc([1]),
+            default="exp_setup.T{0}.K{1}".format(
+                config.kARGoS["n_secs_per_run"],
+                config.kARGoS["n_ticks_per_sec"],
+            ),
+        )
 
         # Physics engines options
 
-        self.stage1_physics.add_argument("--physics-engine-type2D",
-                                         choices=['dynamics2d'],
-                                         help="""
+        self.stage1.add_argument(
+            "--physics-engine-type2D",
+            choices=["dynamics2d"],
+            help="""
 
                                          The type of 2D physics engine to use
                                          for managing spatial extents within the
@@ -84,12 +59,15 @@ class PlatformCmdline(cmd.BaseCmdline):
                                          controlled by 2D physics engines is
                                          defined on a per ``--project`` basis.
 
-                             """ + self.stage_usage_doc([1]),
-                                         default='dynamics2d')
+                             """
+            + self.stage_usage_doc([1]),
+            default="dynamics2d",
+        )
 
-        self.stage1_physics.add_argument("--physics-engine-type3D",
-                                         choices=['dynamics3d'],
-                                         help="""
+        self.stage1.add_argument(
+            "--physics-engine-type3D",
+            choices=["dynamics3d"],
+            help="""
 
                                          The type of 3D physics engine to use
                                          for managing 3D volumetric extents
@@ -100,13 +78,16 @@ class PlatformCmdline(cmd.BaseCmdline):
                                          engines is defined on a per
                                          ``--project`` basis.
 
-                                         """ + self.stage_usage_doc([1]),
-                                         default='dynamics3d')
+                                         """
+            + self.stage_usage_doc([1]),
+            default="dynamics3d",
+        )
 
-        self.stage1_physics.add_argument("--physics-n-engines",
-                                         choices=[1, 2, 4, 6, 8, 12, 16, 24],
-                                         type=int,
-                                         help="""
+        self.stage1.add_argument(
+            "--physics-n-engines",
+            choices=[1, 2, 4, 6, 8, 12, 16, 24],
+            type=int,
+            help="""
 
                                          # of physics engines to use during
                                          simulation (yay ARGoS!). If N > 1, the
@@ -130,7 +111,7 @@ class PlatformCmdline(cmd.BaseCmdline):
                                          the arena, and 2 3D engines will manage
                                          the other 2/3 of the arena.
 
-                                         If ``--exec-env`` is something other
+                                         If ``--execenv`` is something other
                                          than ``hpc.local`` then the # physics
                                          engines will be computed from the HPC
                                          environment, and the cmdline value (if
@@ -158,10 +139,13 @@ class PlatformCmdline(cmd.BaseCmdline):
 
                                             This is enforced by SIERRA.
 
-                             """ + self.stage_usage_doc([1]))
-        self.stage1_physics.add_argument("--physics-iter-per-tick",
-                                         type=int,
-                                         help="""
+                             """
+            + self.stage_usage_doc([1]),
+        )
+        self.stage1.add_argument(
+            "--physics-iter-per-tick",
+            type=int,
+            help="""
 
                                          The # of iterations all physics engines
                                          should perform per :term:`Tick` each
@@ -170,29 +154,32 @@ class PlatformCmdline(cmd.BaseCmdline):
                                          control loops is set via
                                          ``--exp-setup``).
 
-                             """ + self.stage_usage_doc([1]),
-                                         default=config.kARGoS['physics_iter_per_tick'])
+                             """
+            + self.stage_usage_doc([1]),
+            default=config.kARGoS["physics_iter_per_tick"],
+        )
 
-        self.stage1_physics.add_argument("--physics-spatial-hash2D",
-                                         help="""
+        self.stage1.add_argument(
+            "--physics-spatial-hash2D",
+            help="""
 
                                          Specify that each 2D physics engine
                                          should use a spatial hash (only applies
                                          to ``dynamics2d`` engine type).
 
                                          """,
-                                         action='store_true')
+            action="store_true",
+        )
 
         # Rendering options
-        self.stage1_rendering.add_argument("--camera-config",
-                                           choices=['overhead',
-                                                    'sw',
-                                                    'sw+interp'],
-                                           help="""
+        self.stage1.add_argument(
+            "--camera-config",
+            choices=["overhead", "sw", "sw+interp"],
+            help="""
 
                                            Select the camera configuration for
                                            simulation. Ignored unless
-                                           ``--platform-vc`` is passed. Valid
+                                           ``--engine-vc`` is passed. Valid
                                            values are:
 
                                            - ``overhead`` - Use a single
@@ -210,16 +197,19 @@ class PlatformCmdline(cmd.BaseCmdline):
                                            - ``sw+interp`` - Same as ``sw``, but
                                              with interpolation between cameras.
 
-                                           """ + self.stage_usage_doc([1]),
-                                           default='overhead')
+                                           """
+            + self.stage_usage_doc([1]),
+            default="overhead",
+        )
 
-        self.stage1_robots.add_argument("--with-robot-rab",
-                                        help="""
+        self.stage1.add_argument(
+            "--with-robot-rab",
+            help="""
 
                                         If passed, do not remove the Range and
                                         Bearing (RAB) sensor, actuator, and
                                         medium XML definitions from
-                                        ``--template-input-file`` before
+                                        ``--expdef-template`` before
                                         generating experimental
                                         inputs. Otherwise, the following XML
                                         tags are removed if they exist:
@@ -228,16 +218,19 @@ class PlatformCmdline(cmd.BaseCmdline):
                                         - ``.//actuators/range_and_bearing``
                                         - ``.//sensors/range_and_bearing``
 
-                                        """ + self.stage_usage_doc([1]),
-                                        action="store_true",
-                                        default=False)
+                                        """
+            + self.stage_usage_doc([1]),
+            action="store_true",
+            default=False,
+        )
 
-        self.stage1_robots.add_argument("--with-robot-leds",
-                                        help="""
+        self.stage1.add_argument(
+            "--with-robot-leds",
+            help="""
 
                                         If passed, do not remove the robot LED
                                         actuator XML definitions from the
-                                        ``--template-input-file`` before
+                                        ``--expdef-template`` before
                                         generating experimental
                                         inputs. Otherwise, the following XML
                                         tags are removed if they exist:
@@ -246,16 +239,19 @@ class PlatformCmdline(cmd.BaseCmdline):
                                         - ``.//medium/leds``
                                         - ``.//sensors/colored_blob_omnidirectional_camera``
 
-                                        """ + self.stage_usage_doc([1]),
-                                        action="store_true",
-                                        default=False)
+                                        """
+            + self.stage_usage_doc([1]),
+            action="store_true",
+            default=False,
+        )
 
-        self.stage1_robots.add_argument("--with-robot-battery",
-                                        help="""
+        self.stage1.add_argument(
+            "--with-robot-battery",
+            help="""
 
                                         If passed, do not remove the robot
                                         battery sensor XML definitions from
-                                        ``--template-input-file`` before
+                                        ``--expdef-template`` before
                                         generating experimental
                                         inputs. Otherwise, the following XML
                                         tags are removed if they exist:
@@ -263,63 +259,60 @@ class PlatformCmdline(cmd.BaseCmdline):
                                         - ``.//entity/*/battery``
                                         - ``.//sensors/battery``
 
-                                        """ + self.stage_usage_doc([1]),
-                                        action="store_true",
-                                        default=False)
-
-        self.stage1_robots.add_argument("--n-robots",
-                                        help="""
-
-                                        The # robots that should be used in the
-                                        simulation. Can be used to override
-                                        batch criteria, or to supplement
-                                        experiments that do not set it so that
-                                        manual modification of input file is
-                                        unneccesary.
-
-                                        """ + self.stage_usage_doc([1]),
-                                        type=int,
-                                        default=None)
-
-    @staticmethod
-    def cmdopts_update(cli_args, cmdopts: types.Cmdopts) -> None:
-        """Update cmdopts with ARGoS-specific cmdline options.
-
-        """
-        hpc.cmdline.HPCCmdline.cmdopts_update(cli_args, cmdopts)
-
-        updates = {
-            # Stage 1
-            'n_robots': cli_args.n_robots,
-
-            'exp_setup': cli_args.exp_setup,
-
-            'physics_n_engines': cli_args.physics_n_engines,
-            'physics_n_threads': cli_args.physics_n_engines,  # alias
-            "physics_engine_type2D": cli_args.physics_engine_type2D,
-            "physics_engine_type3D": cli_args.physics_engine_type3D,
-            "physics_iter_per_tick": cli_args.physics_iter_per_tick,
-            "physics_spatial_hash2D": cli_args.physics_spatial_hash2D,
-
-            "with_robot_rab": cli_args.with_robot_rab,
-            "with_robot_leds": cli_args.with_robot_leds,
-            "with_robot_battery": cli_args.with_robot_battery,
-
-            'camera_config': cli_args.camera_config,
-
-        }
-
-        cmdopts.update(updates)
-
-
-class CmdlineValidator(cmd.CoreCmdlineValidator):
-    pass
+                                        """
+            + self.stage_usage_doc([1]),
+            action="store_true",
+            default=False,
+        )
+
+        self.stage1.add_argument(
+            "--n-agents",
+            help="""
+                                             The # agents (robots) that should
+                                             be used in the simulation.  Can be
+                                             used to override batch criteria, or
+                                             to supplement experiments that do
+                                             not set it so that manual
+                                             modification of input file is
+                                             unneccesary.
+                                             """
+            + self.stage_usage_doc([1]),
+            type=int,
+            default=None,
+        )
+
+
+def build(
+    parents: tp.List[argparse.ArgumentParser], stages: tp.List[int]
+) -> PluginCmdline:
+    """
+    Get a cmdline parser supporting the :term:`ARGoS` engine.
+    """
+    return EngineCmdline(parents=parents, stages=stages)
+
+
+def to_cmdopts(args: argparse.Namespace) -> types.Cmdopts:
+    """Update cmdopts with ARGoS-specific cmdline options."""
+    return {
+        # Stage 1
+        "n_agents": args.n_agents,
+        "exp_setup": args.exp_setup,
+        "physics_n_engines": args.physics_n_engines,
+        "physics_n_threads": args.physics_n_engines,  # alias
+        "physics_engine_type2D": args.physics_engine_type2D,
+        "physics_engine_type3D": args.physics_engine_type3D,
+        "physics_iter_per_tick": args.physics_iter_per_tick,
+        "physics_spatial_hash2D": args.physics_spatial_hash2D,
+        "with_robot_rab": args.with_robot_rab,
+        "with_robot_leds": args.with_robot_leds,
+        "with_robot_battery": args.with_robot_battery,
+        "camera_config": args.camera_config,
+    }
 
 
 def sphinx_cmdline_stage1():
-    return PlatformCmdline(None, [1]).parser
+    return EngineCmdline([], [1]).parser
 
 
 def sphinx_cmdline_stage2():
-    parent = hpc.cmdline.HPCCmdline([2]).parser
-    return PlatformCmdline([parent], [2]).parser
+    return EngineCmdline([], [2]).parser

sierra/plugins/{platform/argos/variables → engine/argos/generators}/__init__.py

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