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

sierra/core/trampoline.py

@@ -0,0 +1,30 @@
+#
+# Copyright 2025 John Harwell, All rights reserved.
+#
+# SPDX-License Identifier: MIT
+#
+
+# Core packages
+import typing as tp
+import argparse
+
+# 3rd party packages
+
+# Project packages
+from sierra.core import plugin as pm
+
+
+def cmdline_parser(
+    plugin: str, parents: tp.List[argparse.ArgumentParser], stages: tp.List[int]
+) -> tp.Optional[argparse.ArgumentParser]:
+    """
+    Dispatches cmdline parser creation to selected plugin.
+
+    If the selected plugin does not define a cmdline, None is returned.
+    """
+    path = "{0}.cmdline".format(plugin)
+    if pm.module_exists(path):
+        module = pm.module_load_tiered(path)
+        return module.build(parents, stages).parser
+
+    return None

sierra/core/types.py

@@ -1,14 +1,21 @@
 # Copyright 2021 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
-"""Custom types defined by SIERRA for more readable type hints.
-
-"""
+"""Custom types defined by SIERRA for more readable type hints."""
 # Core packages
 import typing as tp
-from types import ModuleType
+import sys
+from types import ModuleType  # noqa: F401 pylint: disable=unused-import
+from dataclasses import dataclass
 import pathlib
 
+# 2024-12-03 [JRH]: Once SIERRA moves to 3.10+ this (and many other instances)
+# can be replaced unilaterally with tp.TypeAlias.
+if sys.version_info < (3, 10):
+    from typing_extensions import TypeAlias
+else:
+    from typing import TypeAlias
+
 # 3rd party packages
 
 # Project packages
@@ -17,71 +24,109 @@ import pathlib
 # Type Definitions
 ################################################################################
 
-Cmdopts = tp.Dict[str, tp.Any]
-YAMLDict = tp.Dict[str, tp.Any]
-SimpleDict = tp.Dict[str, tp.Union[str, int]]
-
-StrDict = tp.Dict[str, str]
-IntDict = tp.Dict[str, int]
-CLIArgSpec = tp.Dict[str, tp.Any]
-PathList = tp.List[pathlib.Path]
-
-
-class ShellCmdSpec():
-    def __init__(self,
-                 cmd: str,
-                 shell: bool,
-                 wait: bool,
-                 env: tp.Optional[bool] = False) -> None:
-        self.cmd = cmd
-        self.shell = shell
-        self.wait = wait
-        self.env = env
-
-
-class YAMLConfigFileSpec():
-    def __init__(self,
-                 main: str,
-                 controllers: str,
-                 models: str,
-                 stage5: str) -> None:
-        self.main = main
-        self.controllers = controllers
-        self.models = models
-        self.stage5 = stage5
-
-
-class ParsedNodefileSpec():
-    def __init__(self,
-                 hostname: str,
-                 n_cores: int,
-                 login: str,
-                 port: int) -> None:
-        self.hostname = hostname
-        self.n_cores = n_cores
-        self.login = login
-        self.port = port
-
-
-class OSPackagesSpec():
-    def __init__(self,
-                 kernel: str,
-                 name: str,
-                 pkgs: tp.Dict[str, bool]) -> None:
-        self.kernel = kernel
-        self.name = name
-        self.pkgs = pkgs
-
-
-class StatisticsSpec():
-    def __init__(self,
-                 exts: StrDict) -> None:
-        self.exts = exts
-
-
-__api__ = [
-    'ShellCmdSpec',
-    'YAMLConfigFileSpec',
-    'ParsedNodefileSpec',
-    'OSPackagesSpec'
+Cmdopts: TypeAlias = tp.Dict[str, tp.Any]
+"""Dictionary of parsed cmdline options."""
+
+YAMLDict: TypeAlias = tp.Union[None, bool, str, float, int, tp.Dict[str, "YAMLDict"]]
+"""Parsed YAML dictionary."""
+
+SimpleDict: TypeAlias = tp.Dict[str, tp.Union[str, int]]
+"""Dictionary str -> {str|int} mappings."""
+
+# 2024-12-03 [JRH]: Once SIERRA moves to 3.10+ this (and many other instances)
+# can be replaced with the '|' syntax, which is much nicer. Also the TypeAlias
+# import from extensions won't be needed/will be part of the tying module.
+JSON: TypeAlias = tp.Union[dict[str, "JSON"], list["JSON"], str, int, float, bool, None]
+"""Dictionary of parsed JSON."""
+
+StrDict: TypeAlias = tp.Dict[str, str]
+"""Dictionary containing str -> str mappings."""
+
+IntDict: TypeAlias = tp.Dict[str, int]
+"""Dictionary containing str -> int mappings."""
+
+CLIArgSpec: TypeAlias = tp.Dict[str, tp.Any]
+"""Dictionary containing str -> anything mappings for parsing stuff from the
+cmdline into components."""
+
+PathList: TypeAlias = tp.List[pathlib.Path]
+"""List of paths."""
+
+
+@dataclass
+class ShellCmdSpec:
+    """
+    Dataclass containing info to run shell cmds.
+
+    Contains:
+
+        - The cmd to run. This should end in a ';' so that multiple commands can
+          be specified to run in sequence.
+
+        - Whether or not it should be strictly run in a shell via
+          ``shell=True``.
+
+        - Whether to wait for it to finish before returning.
+
+        - Whether to inherit the environment from the calling process.
+    """
+
+    cmd: str
+    shell: bool
+    wait: bool
+    env: tp.Optional[bool] = False
+
+
+@dataclass
+class YAMLConfigFileSpec:
+    """Spec for all the .yaml files available for :term:`Projects <Project>`."""
+
+    main: str
+    graphs: str
+    collate: str
+    controllers: str
+    scenarios: str
+    models: str
+
+
+@dataclass
+class ParsedNodefileSpec:
+    """Per line in a GNU parallel style nodefil, containing info a single resource."""
+
+    hostname: str
+    n_cores: int
+    login: str
+    port: int
+
+
+@dataclass
+class OSPackagesSpec:
+    """Info about what packages are required/optional on a given OS."""
+
+    kernel: str
+    name: str
+    pkgs: tp.Dict[str, bool]
+
+
+@dataclass
+class StatisticsSpec:
+    """Spec mapping file types of statistics to file extensions to contain said stats."""
+
+    exts: StrDict
+
+
+__all__ = [
+    "ShellCmdSpec",
+    "YAMLConfigFileSpec",
+    "ParsedNodefileSpec",
+    "OSPackagesSpec",
+    "StatisticsSpec",
+    "Cmdopts",
+    "YAMLDict",
+    "SimpleDict",
+    "JSON",
+    "StrDict",
+    "IntDict",
+    "CLIArgSpec",
+    "PathList",
 ]

sierra/core/utils.py

@@ -2,9 +2,7 @@
 #
 #  SPDX-License-Identifier: MIT
 
-"""Miscellaneous bits used in mutiple places but that don't fit anywhere else.
-
-"""
+"""Miscellaneous bits used in mutiple places but that don't fit anywhere else."""
 
 # Core packages
 import typing as tp
@@ -21,15 +19,16 @@ from retry import retry
 
 # Project packages
 from sierra.core.vector import Vector3D
-from sierra.core.experiment import xml, definition
+from sierra.core.experiment import definition
 from sierra.core import types, config
-from sierra.core import plugin_manager as pm
+from sierra.core import plugin as pm
 
 
-class ArenaExtent():
+class ArenaExtent:
     """Representation of a 2D or 3D section/chunk/volume of the arena."""
+
     @staticmethod
-    def from_corners(ll: Vector3D, ur: Vector3D) -> 'ArenaExtent':
+    def from_corners(ll: Vector3D, ur: Vector3D) -> "ArenaExtent":
         """Initialize an extent via LL and UR corners.
 
         As opposed to an origin and a set of dimensions.
@@ -64,11 +63,11 @@ class ArenaExtent():
         return self._origin
 
     def __str__(self) -> str:
-        return str(self.dims) + '@' + str(self._origin)
+        return str(self.dims) + "@" + str(self._origin)
 
 
-class Sigmoid():
-    """
+class Sigmoid:
+    r"""
     Sigmoid activation function.
 
     .. math::
@@ -89,7 +88,7 @@ class Sigmoid():
             return 1.0 / (1 + np.exp(-self.x))  # type: ignore
 
 
-class ReLu():
+class ReLu:
     r"""
     Rectified Linear Unit (ReLU) activation function.
 
@@ -118,8 +117,7 @@ def scale_minmax(minval: float, maxval: float, val: float) -> float:
     return -1.0 + (val - minval) * (1 - (-1)) / (maxval - minval)
 
 
-def dir_create_checked(path: tp.Union[pathlib.Path, str],
-                       exist_ok: bool) -> None:
+def dir_create_checked(path: tp.Union[pathlib.Path, str], exist_ok: bool) -> None:
     """Create a directory idempotently.
 
     If the directory exists and it shouldn't, raise an error.
@@ -158,51 +156,46 @@ def path_exists(path: tp.Union[pathlib.Path, str]) -> bool:
     return max(set(res), key=res.count)
 
 
-def get_primary_axis(criteria,
-                     primary_axis_bc: tp.List,
-                     cmdopts: types.Cmdopts) -> int:
+def get_primary_axis(criteria, primary_axis_bc: tp.List, cmdopts: types.Cmdopts) -> int:
     """
     Determine axis in a bivariate batch criteria is the primary axis.
 
     This is obtained on a per-query basis depending on the query context, or can
     be overriden on the cmdline.
     """
-    if cmdopts['plot_primary_axis'] == 0:
+    if cmdopts["plot_primary_axis"] == 0:
         return 0
 
-    if cmdopts['plot_primary_axis'] == 1:
+    if cmdopts["plot_primary_axis"] == 1:
         return 1
 
-    if any(isinstance(criteria.criteria1, elt) for elt in primary_axis_bc):
+    if any(isinstance(criteria.criterias[1], elt) for elt in primary_axis_bc):
         return 0
 
     return 1
 
 
-def exp_range_calc(cmdopts: types.Cmdopts,
-                   root_dir: pathlib.Path,
-                   criteria) -> types.PathList:
+def exp_range_calc(
+    exp_range: str, root_dir: pathlib.Path, dirnames: tp.List[str]
+) -> types.PathList:
     """
     Get the range of experiments to run/do stuff with. SUPER USEFUL.
     """
-    exp_all = [root_dir / d for d in criteria.gen_exp_names(cmdopts)]
+    exp_all = [root_dir / d for d in dirnames]
 
-    exp_range = cmdopts['exp_range']
+    if exp_range is not None:
+        min_exp = int(exp_range.split(":")[0])
+        max_exp = int(exp_range.split(":")[1])
+        assert (
+            min_exp <= max_exp
+        ), f"Min batch exp >= max batch exp({min_exp} vs. {max_exp})"
 
-    if cmdopts['exp_range'] is not None:
-        min_exp = int(exp_range.split(':')[0])
-        max_exp = int(exp_range.split(':')[1])
-        assert min_exp <= max_exp, \
-            f"Min batch exp >= max batch exp({min_exp} vs. {max_exp})"
-
-        return exp_all[min_exp: max_exp + 1]
+        return exp_all[min_exp : max_exp + 1]
 
     return exp_all
 
 
-def exp_include_filter(inc_spec: tp.Optional[str],
-                       target: tp.List,
-                       n_exps: int):
+def exp_include_filter(inc_spec: tp.Optional[str], target: tp.List, n_exps: int):
     """Calculate which experiments to include in a calculation for something.
 
     Take a input list of experiment numbers to include, and returns the sublist
@@ -216,9 +209,9 @@ def exp_include_filter(inc_spec: tp.Optional[str],
         start = None
         end = None
     else:
-        r = inc_spec.split(':')
+        r = inc_spec.split(":")
         start = int(r[0])
-        if r[1] == '':
+        if r[1] == "":
             end = len(target)
         else:
             end = int(r[1])
@@ -229,8 +222,9 @@ def exp_include_filter(inc_spec: tp.Optional[str],
     return target[slice(start, end, None)]
 
 
-def bivar_exp_labels_calc(exp_dirs: types.PathList) -> tp.Tuple[tp.List[str],
-                                                                tp.List[str]]:
+def bivar_exp_labels_calc(
+    exp_dirs: types.PathList,
+) -> tp.Tuple[tp.List[str], tp.List[str]]:
     """
     Calculate the labels for bivariant experiment graphs.
     """
@@ -241,7 +235,7 @@ def bivar_exp_labels_calc(exp_dirs: types.PathList) -> tp.Tuple[tp.List[str],
     xlabels_set = set()
     ylabels_set = set()
     for e in exp_dirs:
-        pair = e.name.split('+')
+        pair = e.name.split("+")
         xlabels_set.add(pair[0])
         ylabels_set.add(pair[1])
 
@@ -251,27 +245,28 @@ def bivar_exp_labels_calc(exp_dirs: types.PathList) -> tp.Tuple[tp.List[str],
     return (xlabels, ylabels)
 
 
-def apply_to_expdef(var,
-                    exp_def: definition.XMLExpDef) -> tp.Tuple[tp.Optional[xml.TagRmList],
-                                                               tp.Optional[xml.TagAddList],
-                                                               tp.Optional[xml.AttrChangeSet]]:
+def apply_to_expdef(var, exp_def: definition.BaseExpDef) -> tp.Tuple[
+    tp.Optional[definition.ElementRmList],
+    tp.Optional[definition.ElementAddList],
+    tp.Optional[definition.AttrChangeSet],
+]:
     """
-    Apply a generated XML modifictions to an experiment definition.
+    Apply a generated expdef modifictions to an experiment definition.
 
     In this order:
 
-    #. Remove existing XML tags
-    #. Add new XML tags
-    #. Change existing XML attributes
+    #. Remove existing expdef elements
+    #. Add new expdef elements
+    #. Change existing expdef element attributes
     """
-    rmsl = var.gen_tag_rmlist()  # type: tp.List[xml.TagRmList]
-    addsl = var.gen_tag_addlist()  # type: tp.List[xml.TagAddList]
-    chgsl = var.gen_attr_changelist()  # type: tp.List[xml.AttrChangeSet]
+    rmsl = var.gen_tag_rmlist()  # type: tp.List[definition.ElementRmList]
+    addsl = var.gen_element_addlist()  # type: tp.List[definition.ElementAddList]
+    chgsl = var.gen_attr_changelist()  # type: tp.List[definition.AttrChangeSet]
 
     if rmsl:
         rms = rmsl[0]
         for r in rms:
-            exp_def.tag_remove(r.path, r.tag)
+            exp_def.element_remove(r.path, r.tag)
     else:
         rms = None
 
@@ -279,7 +274,7 @@ def apply_to_expdef(var,
         adds = addsl[0]
         for a in adds:
             assert a.path is not None, "Can't add tag {a.tag} with no parent"
-            exp_def.tag_add(a.path, a.tag, a.attr, a.allow_dup)
+            exp_def.element_add(a.path, a.tag, a.attr, a.allow_dup)
     else:
         adds = None
 
@@ -293,11 +288,13 @@ def apply_to_expdef(var,
     return rms, adds, chgs
 
 
-def pickle_modifications(adds: tp.Optional[xml.TagAddList],
-                         chgs: tp.Optional[xml.AttrChangeSet],
-                         path: pathlib.Path) -> None:
+def pickle_modifications(
+    adds: tp.Optional[definition.ElementAddList],
+    chgs: tp.Optional[definition.AttrChangeSet],
+    path: pathlib.Path,
+) -> None:
     """
-    After applying XML modifications, pickle changes for later retrieval.
+    After applying expdef modifications, pickle changes for later retrieval.
     """
     if adds is not None:
         adds.pickle(path)
@@ -306,29 +303,31 @@ def pickle_modifications(adds: tp.Optional[xml.TagAddList],
         chgs.pickle(path)
 
 
-def exp_template_path(cmdopts: types.Cmdopts,
-                      batch_input_root: pathlib.Path,
-                      dirname: str) -> pathlib.Path:
+def exp_template_path(
+    cmdopts: types.Cmdopts, batch_input_root: pathlib.Path, dirname: str
+) -> pathlib.Path:
     """Calculate the path to the template input file in the batch experiment root.
 
-     The file at this path will be Used as the de-facto template for generating
-     per-run input files.
+    The file at this path will be Used as the de-facto template for generating
+    per-run input files.
 
     """
-    template = pathlib.Path(cmdopts['template_input_file'])
+    template = pathlib.Path(cmdopts["expdef_template"])
     return batch_input_root / dirname / template.stem
 
 
-def get_n_robots(main_config: types.YAMLDict,
-                 cmdopts: types.Cmdopts,
-                 exp_input_root: pathlib.Path,
-                 exp_def: definition.XMLExpDef) -> int:
+def get_n_agents(
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    exp_input_root: pathlib.Path,
+    exp_def: definition.BaseExpDef,
+) -> int:
     """
-    Get the # robots used for a specific :term:`Experiment`.
+    Get the # agents used for a specific :term:`Experiment`.
     """
-    module = pm.pipeline.get_plugin_module(cmdopts['platform'])
+    module1 = pm.pipeline.get_plugin_module(cmdopts["engine"])
 
-    # Get # robots to send to shell cmds generator. We try:
+    # Get # agents to send to shell cmds generator. We try:
     #
     # 1. Getting it from the current experiment definition, which contains all
     #    changes to the template input file EXCEPT those from batch criteria,
@@ -336,29 +335,28 @@ def get_n_robots(main_config: types.YAMLDict,
     #
     # 2. Getting it from the pickled experiment definition (i.e., from the
     #    batch criteria which was used for this experiment).
-    n_robots = module.population_size_from_def(exp_def,
-                                               main_config,
-                                               cmdopts)
-    if n_robots <= 0:
-        pkl_def = definition.unpickle(exp_input_root / config.kPickleLeaf)
-        n_robots = module.population_size_from_pickle(pkl_def,
-                                                      main_config,
-                                                      cmdopts)
+    n_agents = module1.population_size_from_def(exp_def, main_config, cmdopts)
+
+    module2 = pm.pipeline.get_plugin_module(cmdopts["expdef"])
 
-    assert n_robots > 0, "n_robots must be > 0"
+    if n_agents <= 0:
+        pkl_def = module2.unpickle(exp_input_root / config.kPickleLeaf)
+        n_agents = module1.population_size_from_pickle(pkl_def, main_config, cmdopts)
 
-    return n_robots
+    assert n_agents > 0, "n_agents must be > 0"
+
+    return n_agents
 
 
 def df_fill(df: pd.DataFrame, policy: str) -> pd.DataFrame:
     """
     Fill missing cells in a dataframe according to the specified fill policy.
     """
-    if policy == 'none':
+    if policy == "none":
         return df
-    elif policy == 'pad':
-        return df.fillna(method='pad')
-    elif policy == 'zero':
+    elif policy == "pad":
+        return df.fillna(method="pad")
+    elif policy == "zero":
         return df.fillna(value=0)
     else:
         raise RuntimeError(f"Bad fill policy {policy}")
@@ -372,20 +370,19 @@ def pickle_dump(obj: object, f) -> None:
 def gen_scenario_spec(cmdopts: types.Cmdopts, **kwargs) -> tp.Dict[str, tp.Any]:
     # scenario is passed in kwargs during stage 5 (can't be passed via
     # --scenario in general )
-    scenario = kwargs.get('scenario', cmdopts['scenario'])
-
-    sgp = pm.module_load_tiered(project=cmdopts['project'],
-                                path='generators.scenario_generator_parser')
-    kw = sgp.ScenarioGeneratorParser().to_dict(scenario)
+    scenario = kwargs.get("scenario", cmdopts["scenario"])
 
-    return kw
+    module = pm.module_load_tiered(
+        project=cmdopts["project"], path="generators.scenario"
+    )
+    return module.to_dict(scenario)
 
 
 def sphinx_ref(ref: str) -> str:
     try:
         # This is kind of a hack...
         if __sphinx_build_man__:  # type: ignore
-            parts = ref.split('.')
+            parts = ref.split(".")
             stripped = parts[-1]
             return stripped[:-1]
 
@@ -395,25 +392,25 @@ def sphinx_ref(ref: str) -> str:
     return ref
 
 
-utf8open = functools.partial(open, encoding='UTF-8')
+utf8open = functools.partial(open, encoding="UTF-8")
 """
 Explictly specify that the type of file being opened is UTF-8, which is should
 be for almost everything in SIERRA.
 """
 
-__api__ = [
-    'ArenaExtent',
-    'Sigmoid',
-    'ReLu',
-    'dir_create_checked',
-    'path_exists',
-    'get_primary_axis',
-    'exp_range_calc',
-    'exp_include_filter',
-    'apply_to_expdef',
-    'pickle_modifications',
-    'exp_template_path',
-    'get_n_robots',
-    'df_fill',
-    'utf8open',
+__all__ = [
+    "ArenaExtent",
+    "Sigmoid",
+    "ReLu",
+    "dir_create_checked",
+    "path_exists",
+    "get_primary_axis",
+    "exp_range_calc",
+    "exp_include_filter",
+    "apply_to_expdef",
+    "pickle_modifications",
+    "exp_template_path",
+    "get_n_agents",
+    "df_fill",
+    "utf8open",
 ]

sierra/core/variables/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2018 John Harwell, All rights reserved.
 #
 #  SPDX-License-Identifier: MIT
-from sierra.core.variables import batch_criteria
+"""Container module for things related to variables."""