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

sierra/core/variables/builtin.py

@@ -0,0 +1,135 @@
+# Copyright 2021 John Harwell, All rights reserved.
+#
+#  SPDX-License-Identifier: MIT
+"""
+Builtin batch criteria which can be used with any :term:`Engine`/:term:`Project`.
+
+Batch criteria in this file are the ONLY ones which come with SIERRA which can
+be used as-is. Other stuff in ``sierra.core.variables`` are base classes which
+require specialization to use as batch criteria, or are just experimental
+variables.
+"""
+# Core packages
+import typing as tp
+import re
+import pathlib
+import numpy as np
+
+# 3rd party packages
+import implements
+
+# Project packages
+from sierra.core import types
+from sierra.core.experiment import definition
+from sierra.core.variables import batch_criteria as bc
+from sierra.core.graphs import bcbridge
+
+
+@implements.implements(bcbridge.IGraphable)
+class MonteCarlo(bc.UnivarBatchCriteria):
+    """
+    Criteria which does nothing put provide a set of experiments via cardinality.
+
+    See :ref:`usage/bc/montecarlo` for documentation.
+
+    """
+
+    def __init__(
+        self,
+        cli_arg: str,
+        main_config: types.YAMLDict,
+        batch_input_root: pathlib.Path,
+        cardinality: int,
+    ) -> None:
+        bc.UnivarBatchCriteria.__init__(self, cli_arg, main_config, batch_input_root)
+        self.attr_changes = []  # type: tp.List[definition.AttrChangeSet]
+        self.cardinality = cardinality  # type: int
+
+    def gen_attr_changelist(self) -> tp.List[definition.AttrChangeSet]:
+        if not self.attr_changes:
+            self.attr_changes = [
+                definition.AttrChangeSet(definition.NullMod())
+                for i in range(0, self.cardinality)
+            ]
+
+        return self.attr_changes
+
+    def n_agents(self, exp_num: int) -> int:
+        return self.size_list[exp_num]
+
+    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 = list(range(0, len(info.exp_names)))
+        info.xticklabels = info.exp_names
+        info.xlabel = "Experiment"
+        return info
+
+
+def _mc_parse(arg: str) -> int:
+    sections = arg.split(".")
+
+    # This is the one builtin batch criteria which exists for now
+    assert (
+        sections[1] == "MonteCarlo"
+    ), f" Only 'MonteCarlo' builtin defined; have {sections[1]}"
+
+    # remove batch criteria variable name, leaving only the spec
+    sections = sections[1:]
+    assert (
+        len(sections) == 2
+    ), f"Spec must have 2 sections separated by '.'; have {len(sections)} from '{arg}'"
+
+    res = re.search("C[0-9]+", sections[1])
+    assert res is not None, "Bad cardinality in criteria section '{sections[1]}'"
+    return int(res.group(0)[1:])
+
+
+def linspace_parse(arg: str, scale_factor: tp.Optional[float] = 1.0) -> tp.List[float]:
+    """
+    Generate an array from a linspace spec of the form ``<min>.<max>.C<cardinality>``.
+
+    Args:
+        arg: The CLI string.
+
+        scale_factor: A linear factor applied to the min/max to shift the
+                      range. This can be used to, e.g., generate ranges like
+                      0.4-0.8 from specs like ``4.8.C8`` instead of having to do
+                      contortions around parsing decimal values out of CLI
+                      strings directly.
+    """
+    regex = r"(\d+)\.(\d+)\s*\.C\s*(\d+)\s*"
+    res = re.match(regex, arg)
+    assert len(res.groups()) == 3, f"Spec must match {regex}, have {arg}"
+
+    # groups(0) is always the full matched string; subsequent groups are the
+    # captured groups from the () expressions.
+    _min = float(res.group(1)) * scale_factor
+    _max = float(res.group(2)) * scale_factor
+    cardinality = int(res.group(3))
+    return list(x for x in np.linspace(_min, _max, cardinality))
+
+
+def factory(
+    cli_arg: str,
+    main_config: types.YAMLDict,
+    cmdopts: types.Cmdopts,
+    batch_input_root: pathlib.Path,
+    **kwargs,
+) -> MonteCarlo:
+    """Create a :class:`MonteCarlo` derived class from the cmdline definition."""
+    cardinality = _mc_parse(cli_arg)
+
+    return MonteCarlo(cli_arg, main_config, batch_input_root, cardinality)
+
+
+__all__ = ["MonteCarlo", "linspace_parse"]

sierra/core/variables/exp_setup.py

@@ -15,55 +15,35 @@ import re
 from sierra.core import types
 
 
-class Parser():
+def parse(arg: str, dflts: types.SimpleDict) -> types.CLIArgSpec:
     """Enforces the cmdline definition of ``--exp-setup``.
 
-    See :ref:`ln-sierra-vars-expsetup` for documentation.
+    See :ref:`usage/vars/expsetup` for documentation.
 
     """
+    ret = dflts
 
-    def __init__(self, dflts: types.SimpleDict):
-        self.dflts = dflts
+    regex = r"T(\d+)(?:\.K(\d+))?"
 
-    def __call__(self, arg: str) -> types.CLIArgSpec:
-        ret = self.dflts
+    sections = arg.split(".")
+    # remove variable name, leaving only the spec
+    sections = sections[1:]
 
-        sections = arg.split('.')
-        # remove variable name, leaving only the spec
-        sections = sections[1:]
+    # Get pretty name for logging
+    ret["pretty_name"] = ".".join(sections)
+    res = re.match(regex, ret["pretty_name"])
 
-        assert len(sections) >= 1 and len(sections) <= 3,\
-            ("Spec must have between 1 and 3 sections separated by '.'; "
-             f"have {len(sections)} from '{arg}'")
+    assert (
+        len(res.groups()) >= 1 and len(res.groups()) <= 3
+    ), f"Spec must match {regex}, have {arg}"
 
-        # Get pretty name for logging
-        ret['pretty_name'] = '.'.join(sections)
+    ret["n_secs_per_run"] = int(res.group(1))
 
-        # Parse duration, which must be present
-        res = re.search(r"T\d+", sections[0])
-        assert res is not None, \
-            f"Bad duration spec in section '{sections[0]}'"
-        ret['n_secs_per_run'] = int(res.group(0)[1:])
+    # Parse # ticks per second for controllers, which can be absent
+    if res.group(2) is not None:
+        ret["n_ticks_per_sec"] = int(res.group(2))
 
-        # Parse # ticks per second for controllers, which can be absent
-        if len(sections) >= 2:
-            res = re.search(r"K\d+", sections[1])
-            assert res is not None, \
-                f"Bad ticks per second spec in section '{sections[1]}'"
-            ret['n_ticks_per_sec'] = int(res.group(0)[1:])
+    return ret
 
-        # Parse # datapoints to capture, which can be absent
-        if len(sections) == 3:
-            res = re.search(r"N\d+", sections[2])
-            assert res is not None, \
-                f"Bad # datapoints spec in section '{sections[2]}'"
-            ret['n_datapoints'] = int(res.group(0)[1:])
 
-        return ret
-
-
-__api__ = [
-    'Parser'
-
-
-]
+__all__ = ["parse"]

sierra/core/variables/population_size.py

@@ -8,6 +8,7 @@ Reusable classes related to the homogeneous populations of agents.
 import typing as tp
 import re
 import math
+import pathlib
 
 # 3rd party packages
 
@@ -16,7 +17,7 @@ from sierra.core import types
 from sierra.core.variables import batch_criteria as bc
 
 
-class BasePopulationSize(bc.UnivarBatchCriteria):
+class PopulationSize(bc.UnivarBatchCriteria):
     """
     Base class for changing the # agents/robots to reduce code duplication.
     """
@@ -24,101 +25,96 @@ class BasePopulationSize(bc.UnivarBatchCriteria):
     def __init__(self, *args, **kwargs) -> None:
         bc.UnivarBatchCriteria.__init__(self, *args, *kwargs)
 
-    def graph_xticks(self,
-                     cmdopts: types.Cmdopts,
-                     exp_names: tp.Optional[tp.List[str]] = None) -> tp.List[float]:
-
-        if exp_names is None:
-            exp_names = self.gen_exp_names(cmdopts)
+    def graph_xticks(
+        self,
+        cmdopts: types.Cmdopts,
+        batch_output_root: pathlib.Path,
+        exp_names: tp.List[str],
+    ) -> tp.List[float]:
 
         ret = list(map(float, self.populations(cmdopts, exp_names)))
 
-        if cmdopts['plot_log_xscale']:
+        if cmdopts["plot_log_xscale"]:
             return [int(math.log2(x)) for x in ret]
-        elif cmdopts['plot_enumerated_xscale']:
+        elif cmdopts["plot_enumerated_xscale"]:
             return list(range(0, len(ret)))
         else:
             return ret
 
-    def graph_xticklabels(self,
-                          cmdopts: types.Cmdopts,
-                          exp_names: tp.Optional[tp.List[str]] = None) -> tp.List[str]:
+    def graph_xticklabels(
+        self,
+        cmdopts: types.Cmdopts,
+        batch_output_root: pathlib.Path,
+        exp_names: tp.List[str],
+    ) -> tp.List[str]:
 
         if exp_names is None:
-            exp_names = self.gen_exp_names(cmdopts)
+            exp_names = self.gen_exp_names()
 
         ret = map(float, self.populations(cmdopts, exp_names))
 
         return list(map(lambda x: str(int(round(x, 4))), ret))
 
     def graph_xlabel(self, cmdopts: types.Cmdopts) -> str:
-        if cmdopts['plot_log_xscale']:
+        if cmdopts["plot_log_xscale"]:
             return r"$\log$(System Size)"
 
         return "System Size"
 
 
-class Parser():
-    """A base parser for use in changing the # robots/agents.
-
-    """
-
-    def __call__(self, arg: str) -> types.CLIArgSpec:
-        ret = {
-            'max_size': int(),
-            'model': str(),
-            'cardinality': None
-        }  # type: tp.Dict[str, tp.Union[str, tp.Optional[int]]]
-
-        sections = arg.split('.')
-
-        # remove batch criteria variable name, leaving only the spec
-        sections = sections[1:]
-        assert len(sections) >= 1 and len(sections) <= 2,\
-            ("Spec must have 1 or 2 sections separated by '.'; "
-             f"have {len(sections)} from '{arg}'")
-
-        # Parse increment type
-        res = re.search("Log|Linear", sections[0])
-        assert res is not None, \
-            f"Bad size increment spec in criteria section '{sections[0]}'"
-        ret['model'] = res.group(0)
-
-        # Parse max size
-        res = re.search("[0-9]+", sections[0])
-        assert res is not None, \
-            "Bad population max in criteria section '{sections[0]}'"
-        max_size = int(res.group(0))
-        ret['max_size'] = max_size
-
-        # Parse cardinality for linear models
-        if ret['model'] == 'Linear':
-            if len(sections) == 2:
-                res = re.search("C[0-9]+", sections[1])
-                assert res is not None, \
-                    "Bad cardinality in criteria section '{sections[1]}'"
-                ret['cardinality'] = int(res.group(0)[1:])
-            else:
-                ret['cardinality'] = int(ret['max_size'] / 10.0)   # type: ignore
-        elif ret['model'] == 'Log':
-            ret['cardinality'] = len(range(0, int(math.log2(max_size)) + 1))
-
-        return ret
-
-    def to_sizes(self, attr: types.CLIArgSpec) -> tp.List[int]:
-        """
-        Generate the system sizes for each experiment in a batch.
-        """
-        if attr["model"] == 'Linear':
-            increment = int(attr['max_size'] / attr['cardinality'])
-            return [increment * x for x in range(1, attr['cardinality'] + 1)]
-        elif attr["model"] == 'Log':
-            return [int(2 ** x) for x in range(0, attr['cardinality'])]
+def parse(arg: str) -> tp.List[int]:
+    """Generate the system sizes for each experiment in a batch."""
+    spec = {
+        "max_size": int(),
+        "model": str(),
+        "cardinality": None,
+    }  # type: tp.Dict[str, tp.Union[str, tp.Optional[int]]]
+
+    sections = arg.split(".")
+
+    # remove batch criteria variable name, leaving only the spec
+    sections = sections[1:]
+    assert len(sections) >= 1 and len(sections) <= 2, (
+        "Spec must have 1 or 2 sections separated by '.'; "
+        f"have {len(sections)} from '{arg}'"
+    )
+
+    # Parse increment type
+    res = re.search("Log|Linear", sections[0])
+    assert (
+        res is not None
+    ), f"Bad size increment spec in criteria section '{sections[0]}'"
+    spec["model"] = res.group(0)
+
+    # Parse max size
+    res = re.search("[0-9]+", sections[0])
+    assert res is not None, "Bad population max in criteria section '{sections[0]}'"
+    max_size = int(res.group(0))
+    spec["max_size"] = max_size
+
+    # Parse cardinality for linear models
+    if spec["model"] == "Linear":
+        if len(sections) == 2:
+            res = re.search("C[0-9]+", sections[1])
+            assert (
+                res is not None
+            ), "Bad cardinality in criteria section '{sections[1]}'"
+            spec["cardinality"] = int(res.group(0)[1:])
         else:
-            raise AssertionError
-
-
-__api__ = [
-    'BasePopulationSize',
-    'Parser',
+            spec["cardinality"] = int(spec["max_size"] / 10.0)  # type: ignore
+    elif spec["model"] == "Log":
+        spec["cardinality"] = len(range(0, int(math.log2(max_size)) + 1))
+
+    if spec["model"] == "Linear":
+        increment = int(spec["max_size"] / spec["cardinality"])
+        return [increment * x for x in range(1, spec["cardinality"] + 1)]
+    elif spec["model"] == "Log":
+        return [int(2**x) for x in range(0, spec["cardinality"])]
+    else:
+        raise AssertionError
+
+
+__all__ = [
+    "PopulationSize",
+    "parse",
 ]

sierra/core/variables/variable_density.py

@@ -9,12 +9,13 @@ import typing as tp
 import pathlib
 
 # 3rd party packages
+import numpy as np
 
 # Project packages
 from sierra.core.variables.batch_criteria import UnivarBatchCriteria
 from sierra.core.utils import ArenaExtent
 from sierra.core import types
-from sierra.core.experiment import xml
+from sierra.core.experiment import definition  # noqa: F401
 
 
 class VariableDensity(UnivarBatchCriteria):
@@ -23,90 +24,65 @@ class VariableDensity(UnivarBatchCriteria):
     # THINGS is varied as arena size is held constant. This class is a base
     class which should NEVER be used on its own.
 
-    Attributes:
-
-        densities: List of densities to use.
-
-        dist_type: The type of block distribution to use.
-
-        changes: List of sets of changes to apply to generate the specified
-                 arena sizes.
-
     """
 
-    def __init__(self,
-                 cli_arg: str,
-                 main_config: types.YAMLDict,
-                 batch_input_root: pathlib.Path,
-                 densities: tp.List[float],
-                 extent: ArenaExtent) -> None:
-        UnivarBatchCriteria.__init__(
-            self, cli_arg, main_config, batch_input_root)
+    def __init__(
+        self,
+        cli_arg: str,
+        main_config: types.YAMLDict,
+        batch_input_root: pathlib.Path,
+        densities: tp.List[float],
+        extent: ArenaExtent,
+    ) -> None:
+        UnivarBatchCriteria.__init__(self, cli_arg, main_config, batch_input_root)
         self.densities = densities
         self.extent = extent
-        self.attr_changes = []  # type: tp.List[xml.AttrChangeSet]
-
-
-class Parser():
-    """Enforces specification of a :class:`VariableDensity` derived batch criteria.
-
-    """
-
-    def __call__(self, arg: str) -> types.CLIArgSpec:
-        """
-        Parse the cmdline argument.
-
-        Returns:
+        self.attr_changes = []  # type: tp.List[definition.AttrChangeSet]
 
-            dict:
-                density_min: Floating point value of target minimum density.
-                density_max: Floating point value of target maximum density.
-                cardinality: # densities in [min,max] that should be created.
 
-        """
-        ret = {}
-        sections = arg.split('.')
+def parse(arg: str) -> tp.List[float]:
+    """Enforces specification of a :class:`VariableDensity` derived batch criteria."""
+    spec = {}  # type: tp.Dict[str, tp.Union[float, int]]
+    sections = arg.split(".")
 
-        # remove batch criteria variable name, leaving only the spec
-        sections = sections[1:]
-        assert len(sections) == 3,\
-            ("Spec must have 3 sections separated by '.'; "
-             f"have {len(sections)} from '{arg}'")
+    # remove batch criteria variable name, leaving only the spec
+    sections = sections[1:]
+    assert len(sections) == 3, (
+        "Spec must have 3 sections separated by '.'; "
+        f"have {len(sections)} from '{arg}'"
+    )
 
-        # Parse density min
-        ret['density_min'] = self._parse_density(sections[0], 'minimum')
+    # Parse density min
+    spec["min"] = _parse_density(sections[0], "minimum")
 
-        # Parse density pmax
-        ret['density_max'] = self._parse_density(sections[1], 'maximum')
+    # Parse density pmax
+    spec["max"] = _parse_density(sections[1], "maximum")
 
-        # Parse cardinality
-        res = re.search('C[0-9]+', sections[2])
-        assert res is not None, \
-            "Bad cardinality specification in '{sections[2]}'"
+    # Parse cardinality
+    res = re.search("C[0-9]+", sections[2])
+    assert res is not None, "Bad cardinality specification in '{sections[2]}'"
 
-        ret['cardinality'] = int(res.group(0)[1:])
+    spec["cardinality"] = int(res.group(0)[1:])
 
-        return ret
+    return list(
+        x for x in np.linspace(spec["min"], spec["max"], num=spec["cardinality"])
+    )
 
-    @staticmethod
-    def _parse_density(chunk: str, which: str) -> float:
-        res = re.search('[0-9]+', chunk)
-        assert res is not None, \
-            f"Bad {which} density characteristic specification in '{chunk}'"
 
-        characteristic = float(res.group(0))
+def _parse_density(chunk: str, which: str) -> float:
+    res = re.search("[0-9]+", chunk)
+    assert (
+        res is not None
+    ), f"Bad {which} density characteristic specification in '{chunk}'"
 
-        res = re.search('p[0-9]+', chunk)
-        assert res is not None, \
-            f"Bad {which} density mantissa specification in '{chunk}'"
+    characteristic = float(res.group(0))
 
-        mantissa = float("0." + res.group(0)[1:])
+    res = re.search("p[0-9]+", chunk)
+    assert res is not None, f"Bad {which} density mantissa specification in '{chunk}'"
 
-        return characteristic + mantissa
+    mantissa = float("0." + res.group(0)[1:])
 
+    return characteristic + mantissa
 
-__api__ = [
-    'VariableDensity',
-    'Parser'
 
-]
+__all__ = ["VariableDensity", "parse"]

sierra/core/vector.py

@@ -122,4 +122,4 @@ class Vector3D:
         return m
 
 
-__api__ = ['Vector3D']
+__all__ = ['Vector3D']