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

sierra/core/generators/generator_factory.py

@@ -1,10 +1,10 @@
 # Copyright 2018 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
-"""Factory for combining controller+scenario XML modification generators.
+"""Factory for combining controller+scenario expdef modification generators.
 
 By combining them together, the result can be easily used to apply modifications
-to the template XML file to scaffold the batch experiment.
+to the template expdef file to scaffold the batch experiment.
 
 """
 # Core packages
@@ -17,213 +17,214 @@ import pathlib
 import yaml
 
 # Project packages
-from sierra.core.experiment import spec, xml, definition
-import sierra.core.plugin_manager as pm
+from sierra.core.experiment import definition
+from sierra.core.experiment import spec as expspec
+import sierra.core.plugin as pm
 from sierra.core import types, config, utils
 
 
-class ControllerGenerator():
-    """Generate XML changes for a selected ``--controller``.
+class ControllerGenerator:
+    """Generate expdef changes for a selected ``--controller``.
 
     If the specified controller is not found in ``controllers.yaml`` for the
-    loaded :term:`Project`, an assert will be triggered.
+    loaded :term:`Project`, a warning will be issued.
     """
 
-    def __init__(self,
-                 controller: str,
-                 config_root: pathlib.Path,
-                 cmdopts: types.Cmdopts,
-                 exp_spec: spec.ExperimentSpec) -> None:
+    def __init__(
+        self,
+        controller: str,
+        config_root: pathlib.Path,
+        cmdopts: types.Cmdopts,
+        spec: expspec.ExperimentSpec,
+    ) -> None:
         controllers_yaml = config_root / config.kYAML.controllers
-        with utils.utf8open(controllers_yaml) as f:
-            self.controller_config = yaml.load(f, yaml.FullLoader)
+        self.logger = logging.getLogger(__name__)
+        self.name = controller
+
+        try:
+            with utils.utf8open(controllers_yaml) as f:
+                self.controller_config = yaml.load(f, yaml.FullLoader)
+        except FileNotFoundError:
+            self.logger.warning("%s does not exist!", controllers_yaml)
+            self.controller_config = {}
 
         main_yaml = config_root / config.kYAML.main
         with utils.utf8open(main_yaml) as f:
             self.main_config = yaml.load(f, yaml.FullLoader)
 
-        self.category, self.name = controller.split('.')
+        # Only check this if controllers.yaml exists. If it doesn't, then user's
+        # can use whatever they want as the controller name (i.e., doesn't need
+        # to conform to the below schema).
+        if self.controller_config is not None:
+            n_components = len(controller.split("."))
+            if n_components != 2:
+                raise RuntimeError(
+                    (
+                        "Expected 2 controller components, got "
+                        f"{n_components}. Arguments to --controller "
+                        "must be of the form CATEGORY.TYPE (i.e., 2 "
+                        "components separated by a '.')."
+                    )
+                )
+
+        self.category, self.name = controller.split(".")
         self.cmdopts = cmdopts
         self.logger = logging.getLogger(__name__)
-        self.spec = exp_spec
+        self.spec = spec
 
-    def generate(self, exp_def: definition.XMLExpDef) -> definition.XMLExpDef:
-        """Generate all modifications to the experiment definition from the controller.
+    def generate(self, exp_def: definition.BaseExpDef) -> definition.BaseExpDef:
+        """Generate all modifications to the expdef from the controller.
 
-        Does not save.
+        Returns a new, modified expdef. Does not save to filesystem.
 
         """
         self._generate_controller_support(exp_def)
         self._generate_controller(exp_def)
         return exp_def
 
-    def _pp_for_tag_add(self,
-                        add: xml.TagAdd,
-                        robot_id: tp.Optional[int] = None) -> xml.TagAdd:
-        module = pm.pipeline.get_plugin_module(self.cmdopts['platform'])
+    def _pp_for_element_add(
+        self, add: definition.ElementAdd, robot_id: tp.Optional[int] = None
+    ) -> definition.ElementAdd:
+        module = pm.pipeline.get_plugin_module(self.cmdopts["engine"])
 
-        if '__UUID__' in add.path:
+        if "__UUID__" in add.path:
             prefix = module.robot_prefix_extract(self.main_config, self.cmdopts)
-            add.path = add.path.replace('__UUID__', f"{prefix}{robot_id}")
+            add.path = add.path.replace("__UUID__", f"{prefix}{robot_id}")
 
         return add
 
-    def _do_tag_add(self,
-                    exp_def: definition.XMLExpDef,
-                    add: xml.TagAdd) -> None:
+    def _do_element_add(
+        self, exp_def: definition.BaseExpDef, add: definition.ElementAdd
+    ) -> None:
 
         # If the user is applying tags for each robot, then they might be added
         # multiple tags with the same name, but different attributes, so we
         # allow that explicitly here. Otherwise, we force all tag adds to be
         # unique.
-        if '__UUID__' in add.path:
-            # We can't use platform.population_size_from_def() here because we
+        if "__UUID__" in add.path:
+            # We can't use engine.population_size_from_def() here because we
             # haven't added any tags to the experiment definition yet, and if
-            # the platform relies on added tags to calculate population sizes,
+            # the engine relies on added tags to calculate population sizes,
             # then this won't work.
             controllers = config.kYAML.controllers
-            assert hasattr(self.spec.criteria, 'n_robots'),\
-                (f"When using __UUID__ and tag_add in {controllers}, the batch "
-                 "criteria must implement bc.IQueryableBatchCriteria")
-            n_robots = self.spec.criteria.n_robots(self.spec.exp_num)
+            assert hasattr(self.spec.criteria, "n_agents"), (
+                f"When using __UUID__ and element_add in {controllers}, the batch "
+                "criteria must implement bc.IQueryableBatchCriteria"
+            )
+            n_agents = self.spec.criteria.n_agents(self.spec.exp_num)
 
-            assert n_robots > 0,\
-                "Batch criteria {self.spec.criteria} returned 0 robots?"
+            assert (
+                n_agents > 0
+            ), "Batch criteria {self.spec.criteria} returned 0 agents?"
 
-            for robot_id in range(0, n_robots):
+            for robot_id in range(0, n_agents):
                 to_pp = copy.deepcopy(add)
-                pp_add = self._pp_for_tag_add(to_pp, robot_id)
-                exp_def.tag_add(pp_add.path,
-                                pp_add.tag,
-                                pp_add.attr,
-                                True)
+                pp_add = self._pp_for_element_add(to_pp, robot_id)
+                exp_def.element_add(pp_add.path, pp_add.tag, pp_add.attr, True)
         else:
             to_pp = copy.deepcopy(add)
-            pp_add = self._pp_for_tag_add(to_pp)
-            exp_def.tag_add(pp_add.path,
-                            pp_add.tag,
-                            pp_add.attr,
-                            False)
-
-    def _generate_controller_support(self,
-                                     exp_def: definition.XMLExpDef) -> None:
+            pp_add = self._pp_for_element_add(to_pp)
+            exp_def.element_add(pp_add.path, pp_add.tag, pp_add.attr, False)
+
+    def _generate_controller_support(self, exp_def: definition.BaseExpDef) -> None:
         # Setup controller support code (if any)
-        xml_mods = self.controller_config.get(self.category, {}).get('xml', {})
+        xml_mods = self.controller_config.get(self.category, {}).get("xml", {})
 
-        chgs = xml_mods.get('attr_change', {})
+        chgs = xml_mods.get("attr_change", {})
         for t in chgs:
             exp_def.attr_change(t[0], t[1], t[2])
 
-        chgs = xml_mods. get('tag_change', {})
+        chgs = xml_mods.get("element_change", {})
         for t in chgs:
-            exp_def.tag_change(t[0], t[1], t[2])
+            exp_def.element_change(t[0], t[1], t[2])
 
-        adds = xml_mods.get('tag_add', {})
+        adds = xml_mods.get("element_add", {})
         for t in adds:
-            self._do_tag_add(exp_def, xml.TagAdd(t[0],
-                                                 t[1],
-                                                 eval(t[2]),
-                                                 False))
+            self._do_element_add(
+                exp_def, definition.ElementAdd(t[0], t[1], eval(t[2]), False)
+            )
 
-    def _generate_controller(self, exp_def: definition.XMLExpDef) -> None:
+    def _generate_controller(self, exp_def: definition.BaseExpDef) -> None:
         if self.category not in self.controller_config:
-            self.logger.fatal("Controller category '%s' not found in YAML configuration",
-                              self.category)
-            raise RuntimeError
-
-        if not any(self.name in config['name'] for config in self.controller_config[self.category]['controllers']):
-            self.logger.fatal("Controller name '%s' not found in YAML configuration",
-                              self.name)
-            raise RuntimeError
-
-        self.logger.debug("Applying changes from %s (all experiments)",
-                          config.kYAML.controllers)
-
-        for controller in self.controller_config[self.category]['controllers']:
-            if controller['name'] != self.name:
+            self.logger.warning(
+                "Controller category '%s' not found in YAML configuration",
+                self.category,
+            )
+            return
+
+        if not any(
+            self.name in config["name"]
+            for config in self.controller_config[self.category]["controllers"]
+        ):
+            self.logger.warning(
+                "Controller name '%s' not found in YAML configuration", self.name
+            )
+            return
+
+        self.logger.debug(
+            "Applying changes from %s (all experiments)", config.kYAML.controllers
+        )
+
+        for controller in self.controller_config[self.category]["controllers"]:
+            if controller["name"] != self.name:
                 continue
 
-            chgs = controller.get('xml', {}).get('attr_change', {})
+            chgs = controller.get("xml", {}).get("attr_change", {})
             for t in chgs:
                 exp_def.attr_change(t[0], t[1], t[2])
 
-            chgs = controller.get('xml', {}).get('tag_change', {})
+            chgs = controller.get("xml", {}).get("element_change", {})
             for t in chgs:
-                exp_def.tag_change(t[0], t[1], t[2])
+                exp_def.element_change(t[0], t[1], t[2])
 
-            adds = controller.get('xml', {}).get('tag_add', {})
+            adds = controller.get("xml", {}).get("element_add", {})
             for t in adds:
-                self._do_tag_add(exp_def, xml.TagAdd(t[0],
-                                                     t[1],
-                                                     eval(t[2]),
-                                                     False))
+                self._do_element_add(
+                    exp_def, definition.ElementAdd(t[0], t[1], eval(t[2]), False)
+                )
 
 
-def joint_generator_create(controller, scenario):
-    """
-    Combine controller and scenario XML modification generators together.
-    """
-    joint_name = '+'.join([controller.__class__.__name__,
-                           scenario.__class__.__name__])
+class ScenarioGenerator:
+    """Generate expdef changes for a selected ``--scenario``."""
 
-    def __init__(self) -> None:
+    def __init__(
+        self, spec: expspec.ExperimentSpec, controller: str, scenario: str, **kwargs
+    ):
+        self.logger = logging.getLogger(__name__)
+        self.spec = spec
         self.controller = controller
-        self.scenario = scenario
-        self.joint_name = joint_name
+        self.name = scenario
+        self.kwargs = kwargs
 
-    def generate(self):
-        exp_def = self.scenario.generate()
-        return self.controller.generate(exp_def)
+        cmdopts = kwargs["cmdopts"]
+        module = pm.module_load_tiered(
+            project=cmdopts["project"], path="generators.scenario"
+        )
+        self.generator = getattr(module, module.to_generator_name(spec.scenario_name))
 
-    return type(joint_name,
-                (object,), {"__init__": __init__, "generate":
-                            generate})()
+    def generate(self):
+        return self.generator(spec=self.spec, controller=self.controller, **self.kwargs)
 
 
-def scenario_generator_create(exp_spec: spec.ExperimentSpec,
-                              controller,
-                              **kwargs):
+class JointGenerator:
     """
-    Create a scenario generator using the plugin search path.
+    Combine controller and scenario expdef modification generators together.
     """
 
-    def __init__(self, **kwargs) -> None:
-        cmdopts = kwargs['cmdopts']
-        self.logger = logging.getLogger(__name__)
-        module = pm.module_load_tiered(project=cmdopts['project'],
-                                       path='generators.scenario_generators')
-        generator_name = module.gen_generator_name(exp_spec.scenario_name)
-        self.scenario_generator = getattr(module, generator_name)(controller=controller,
-                                                                  exp_spec=exp_spec,
-                                                                  **kwargs)
+    def __init__(
+        self, controller: ControllerGenerator, scenario: ScenarioGenerator
+    ) -> None:
+        self.name = "+".join([controller.name, scenario.name])
+        self.controller = controller
+        self.scenario = scenario
 
     def generate(self):
-        return self.scenario_generator.generate()
-
-    return type(exp_spec.scenario_name,
-                (object,), {"__init__": __init__,
-                            "generate": generate
-                            })(**kwargs)
-
-
-def controller_generator_create(controller: str,
-                                config_root: pathlib.Path,
-                                cmdopts: types.Cmdopts,
-                                exp_spec: spec.ExperimentSpec):
-    """
-    Create a controller generator from the cmdline specification.
-    """
-
-    return type(controller,
-                (ControllerGenerator,), {})(controller,
-                                            config_root,
-                                            cmdopts,
-                                            exp_spec)
+        exp_def = self.scenario.generate()
+        return self.controller.generate(exp_def)
 
 
-__api__ = [
-    'ControllerGenerator',
-    'joint_generator_create',
-    'scenario_generator_create',
-    'controller_generator_create',
+__all__ = [
+    "ControllerGenerator",
+    "ScenarioGenerator",
+    "JointGenerator",
 ]

sierra/core/graphs/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""Container module for things related to graphs."""
+
+# Core packages
+
+# 3rd party packages
+
+# Project packages
+from .stacked_line import generate as stacked_line
+from .summary_line import generate as summary_line
+from .heatmap import generate as heatmap
+from .heatmap import generate2 as dual_heatmap
+from .pathset import PathSet
+
+__all__ = [
+    "stacked_line",
+    "summary_line",
+    "heatmap",
+    "dual_heatmap",
+    "PathSet",
+]

sierra/core/graphs/bcbridge.py

@@ -0,0 +1,94 @@
+#
+# Copyright 2025 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+"""
+Bridge/glue interfaces/bindings for :term:`Batch Criteria` which can be graphed.
+"""
+
+# Core packages
+import pathlib
+import typing as tp
+
+# 3rd party packages
+import implements
+
+# Project packages
+from sierra.core import types
+
+
+class GraphInfo:
+    """
+    Container of info for generating graphs from batch criteria.
+
+    Attributes:
+        cmdopts: Dictionary of parsed command line options. Most batch
+                 criteria will not need this to compute things, BUT it is
+                 available.
+
+        batch_output_root: Root directory for all experimental output in the
+                           batch. Needed in calculating graphs for batch
+                           criteria when ``--exp-range`` is used.
+
+        exp_names: The names of experiment directories to instantiate on the
+                   filesystem.
+
+        xticklabels: Labels for the xticks.
+
+        xticks: The x-axis ticks.
+
+        yticklabels: Labels for the yticks.
+
+        yticks: The y-axis ticks.
+
+    """
+
+    def __init__(
+        self,
+        cmdopts: types.Cmdopts,
+        batch_output_root: tp.Optional[pathlib.Path] = None,
+        exp_names: tp.Optional[tp.List[str]] = None,
+    ) -> None:
+        self.cmdopts = cmdopts
+        self.batch_output_root = batch_output_root
+        self.exp_names = exp_names
+
+        self.xticklabels = []  # type: tp.List[str]
+        self.xticks = []  # type: tp.List[float]
+        self.xlabel = ""
+
+        self.yticklabels = []  # type: tp.List[str]
+        self.yticks = []  # type: tp.List[float]
+        self.ylabel = ""
+
+
+class IGraphable(implements.Interface):
+    """
+    Interface for batch criteria for usage with :ref:`plugins/prod/graphs`.
+    """
+
+    def graph_info(
+        self,
+        cmdopts: types.Cmdopts,
+        batch_output_root: tp.Optional[pathlib.Path] = None,
+        exp_names: tp.Optional[tp.List[str]] = None,
+    ) -> GraphInfo:
+        """
+        Generate graph info for generating graphs from :term:`Batch Criteria`.
+
+        Arguments:
+
+           exp_names: Needed as an optional for bivariate batch
+                      criteria.  When calculating say yticks using criteria2, if
+                      criteria2 uses ``populations()`` in the process,
+                      the criteria's OWN ``gen_exp_names()`` will be used, which
+                      will result in bad directory name calculations.  This can
+                      be overcome by passing the list of exp names to use at
+                      THIS level, which should override the value otherwise
+                      present in :class:`GraphInfo`.
+        """
+        raise NotImplementedError
+
+
+__all__ = ["GraphInfo", "IGraphable"]