bencher.variables.inputs ======================== .. py:module:: bencher.variables.inputs Attributes ---------- .. autoapisummary:: bencher.variables.inputs.LoadValuesDynamically Classes ------- .. autoapisummary:: bencher.variables.inputs._DynamicValuesSentinel bencher.variables.inputs.SweepSelector bencher.variables.inputs.BoolSweep bencher.variables.inputs.StringSweep bencher.variables.inputs.EnumSweep bencher.variables.inputs.YamlSelection bencher.variables.inputs.YamlSweep bencher.variables.inputs.IntSweep bencher.variables.inputs.FloatSweep Functions --------- .. autoapisummary:: bencher.variables.inputs._make_hashable bencher.variables.inputs.box bencher.variables.inputs.sweep bencher.variables.inputs.p bencher.variables.inputs.with_subsampling_divisions bencher.variables.inputs.with_level Module Contents --------------- .. py:class:: _DynamicValuesSentinel Bases: :py:obj:`str` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. .. py:method:: __repr__() Return repr(self). .. py:data:: LoadValuesDynamically .. py:class:: SweepSelector(units: str = 'ul', samples: int | None = None, optimize: bool = True, **params) Bases: :py:obj:`param.Selector`, :py:obj:`bencher.variables.sweep_base.SweepBase` A class representing a parameter sweep for selectable options. This class extends both Selector and SweepBase to provide parameter sweeping capabilities for categorical variables that have a predefined set of options. .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take from the available options :type: int .. py:attribute:: __slots__ :value: ['units', 'samples', 'optimize'] .. py:attribute:: units :value: 'ul' .. py:attribute:: optimize :value: True .. py:method:: values() -> list[Any] Return all the values for the parameter sweep. :returns: A list of parameter values to sweep through :rtype: list[Any] .. py:method:: _sweep_identity() -> tuple Include ``objects`` so changing the option set busts the cache. Each element is fingerprinted in one of two ways: * If it exposes ``__bencher_hash__`` (e.g. :class:`YamlSelection`), that hook is called — returning something cross-process stable. This is the required contract for arbitrary / user-defined types. * Otherwise we fall back to ``str(o)``. This is safe for primitive option types (``str``, ``bool``, ``Enum``, numeric) whose ``__str__`` is deterministic, but an object inheriting the default ``object.__str__`` will render as ```` — a memory address that changes every process and would silently produce different cache keys on every run. If you put custom instances in a :class:`SweepSelector`, either implement ``__bencher_hash__`` or a deterministic ``__str__``/``__repr__``. .. py:method:: load_values_dynamically(new_objects: list[Any] | tuple[Any, Ellipsis], *, default: Any | None = None, keep_current_if_possible: bool = True, set_on_class: bool = True) -> None Dynamically update selectable objects for this sweep variable. See original implementation for detailed semantics. This refactored version delegates work to smaller helpers for clarity and easier testing. .. py:method:: _ensure_nonempty(new_list: list[Any]) -> None .. py:method:: _choose_default(new_list: list[Any], explicit_default: Any | None, keep_current: bool) -> Any .. py:method:: _update_instance_objects(new_list: list[Any]) -> None .. py:method:: _sync_class_defaults(new_list: list[Any], candidate_default: Any) -> None .. py:method:: _apply_owner_value(candidate_default: Any) -> None .. py:class:: BoolSweep(units: str = 'ul', samples: int | None = None, default: bool = True, optimize: bool = True, **params) Bases: :py:obj:`SweepSelector` A class representing a parameter sweep for boolean values. This class extends SweepSelector to provide parameter sweeping capabilities specifically for boolean values (True and False). .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take (typically 2 for booleans) :type: int .. py:class:: StringSweep(string_list: list[str], units: str = 'ul', samples: int | None = None, optimize: bool = True, **params) Bases: :py:obj:`SweepSelector` A class representing a parameter sweep for string values. This class extends SweepSelector to provide parameter sweeping capabilities specifically for a list of string values. .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take from the available strings :type: int .. py:method:: dynamic(*, placeholder: str | None = None, units: str = 'ul', doc: str | None = None, **params) -> StringSweep :classmethod: Create a StringSweep intended for later population. :param placeholder: Optional text to show before real values are loaded. Defaults to the sentinel's displayed text. :param units: Units label (optional, passed through). :param doc: Documentation string for the parameter. :param params: Additional param overrides. :returns: A sweep with a single sentinel placeholder value. :rtype: StringSweep .. py:class:: EnumSweep(enum_type: enum.Enum | list[enum.Enum], units: str = 'ul', samples: int | None = None, optimize: bool = True, **params) Bases: :py:obj:`SweepSelector` A class representing a parameter sweep for enum values. This class extends SweepSelector to provide parameter sweeping capabilities specifically for enumeration types, supporting both enum types and lists of enum values. .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take from the available enum values :type: int .. py:attribute:: __slots__ :value: ['units', 'samples', 'optimize'] .. py:function:: _make_hashable(value: Any) -> Any Create a deterministic, hashable representation of arbitrary YAML data. .. py:class:: YamlSelection Bases: :py:obj:`str` String-like wrapper that keeps track of the underlying YAML value. .. py:attribute:: __slots__ :value: ('_value',) .. py:method:: key() -> str .. py:method:: value() -> Any .. py:method:: __repr__() -> str Return repr(self). .. py:method:: __eq__(other: Any) -> bool Return self==value. .. py:method:: __lt__(other: Any) -> bool Return self tuple[str, Any] .. py:method:: as_tuple() -> tuple[str, Any] .. py:class:: YamlSweep(yaml_path: str | pathlib.Path, units: str = 'ul', samples: int | None = None, default_key: str | None = None, optimize: bool = True, **params) Bases: :py:obj:`SweepSelector` Sweep over configurations stored in a YAML file. Loads the YAML mapping once during initialisation and exposes each top-level key as a sweep choice. Each sampled value is a :class:`YamlSelection` instance that exposes the underlying YAML content via the ``value`` attribute (and dict-like helpers). .. py:attribute:: __slots__ :value: ['units', 'samples', 'optimize', 'yaml_path', '_entries', 'default_key'] .. py:attribute:: _sweep_hash_exclude :value: ('yaml_path', '_entries', 'default_key') .. py:attribute:: yaml_path :value: '' .. py:attribute:: _entries .. py:attribute:: default_key :value: None .. py:method:: _load_yaml(path: pathlib.Path) -> Any :staticmethod: .. py:method:: keys() -> list[str] .. py:method:: items() -> list[tuple[str, Any]] .. py:method:: values() -> list[Any] Return all the values for the parameter sweep. :returns: A list of parameter values to sweep through :rtype: list[Any] .. py:method:: key_for_value(value: Any) -> str | None .. py:class:: IntSweep(units: str = 'ul', samples: int | None = None, sample_values: list[int] | None = None, optimize: bool = True, **params) Bases: :py:obj:`param.Integer`, :py:obj:`bencher.variables.sweep_base.SweepBase` A class representing a parameter sweep for integer values. This class extends both Integer and SweepBase to provide parameter sweeping capabilities specifically for integer values within specified bounds or with custom sample values. .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take from the range :type: int .. attribute:: sample_values Specific integer values to use as samples instead of generating them from bounds. If provided, overrides the samples parameter. :type: list[int], optional .. py:attribute:: __slots__ :value: ['units', 'samples', 'optimize', 'sample_values'] .. py:attribute:: units :value: 'ul' .. py:attribute:: optimize :value: True .. py:method:: _coerce_bound(value) Override in subclasses to coerce bound values to the correct type. .. py:method:: _sweep_identity() -> tuple Include bounds and sample_values so a reshaped sweep busts the cache. .. py:method:: values() -> list[int] Return all the values for the parameter sweep. If sample_values is provided, returns those values. Otherwise generates values within the specified bounds. :returns: A list of integer values to sweep through :rtype: list[int] .. py:method:: _validate_value(value, allow_None) Validate the parameter value against constraints. :param value: The value to be validated. :type value: Any :param allow_None: Whether `None` is allowed as a valid value. :type allow_None: bool :raises ValueError: If the value does not meet the parameter's constraints. .. py:method:: _validate_step(val, step) .. py:class:: FloatSweep(units: str = 'ul', samples: int = 10, sample_values: list[float] | None = None, step: float | None = None, optimize: bool = True, **params) Bases: :py:obj:`param.Number`, :py:obj:`bencher.variables.sweep_base.SweepBase` A class representing a parameter sweep for floating point values. This class extends both Number and SweepBase to provide parameter sweeping capabilities specifically for floating point values within specified bounds or with custom sample values. .. attribute:: units The units of measurement for the parameter :type: str .. attribute:: samples The number of samples to take from the range :type: int .. attribute:: sample_values Specific float values to use as samples instead of generating them from bounds. If provided, overrides the samples parameter. :type: list[float], optional .. attribute:: step Step size between samples when generating values from bounds :type: float, optional .. py:attribute:: __slots__ :value: ['units', 'samples', 'optimize', 'sample_values'] .. py:attribute:: units :value: 'ul' .. py:attribute:: optimize :value: True .. py:attribute:: sample_values .. py:method:: _coerce_bound(value) Override in subclasses to coerce bound values to the correct type. .. py:method:: _sweep_identity() -> tuple Include bounds, sample_values, and step so a reshaped sweep busts the cache. .. py:method:: values() -> list[float] Return all the values for the parameter sweep. If sample_values is provided, returns those values. Otherwise generates values within the specified bounds, either using linspace (when step is None) or arange. :returns: A list of float values to sweep through :rtype: list[float] .. py:function:: box(name: str, center: float, width: float) -> FloatSweep Create a FloatSweep parameter centered around a value with a given width. This is a convenience function to create a bounded FloatSweep parameter with bounds centered on a specific value, extending by the width in both directions. :param name: The name of the parameter :type name: str :param center: The center value of the parameter :type center: float :param width: The distance from the center to the bounds in both directions :type width: float :returns: A FloatSweep parameter with the specified name, default, and bounds :rtype: FloatSweep .. py:function:: sweep(name: str | bencher.variables.sweep_base.SweepBase, values: list[Any] | None = None, *, samples: int | None = None, bounds: tuple[float, float] | None = None, max_subsampling_divisions: int | None = None, max_level: int | None = None) -> dict[str, Any] | bencher.variables.sweep_base.SweepBase Create a parameter specification for use in plot_sweep input_vars. Accepts either a string parameter name (returns a dict for deferred lookup) or a SweepBase parameter object (returns a configured sweep directly). Examples:: bn.sweep("theta", [0, 0.5, 1.0]) # explicit values bn.sweep("theta", samples=5) # override sample count bn.sweep("theta", bounds=(0, 1)) # override range bn.sweep("theta", bounds=(0, 1), samples=10) # override range + count bn.sweep(Cfg.param.theta, bounds=(0, 1), samples=5) # SweepBase object :param name: The parameter name (str) or a param object (e.g. ``Cfg.param.theta``). :param values: A list of values for the parameter. :param samples: The number of samples. Must be > 0 if provided. :param bounds: ``(low, high)`` tuple to override the sweep range. :param max_subsampling_divisions: The maximum subsampling_divisions. Must be > 0 if provided. :returns: A parameter dict (for string names) or configured sweep object. :rtype: dict[str, Any] | SweepBase .. py:function:: p(name: str | bencher.variables.sweep_base.SweepBase, values: list[Any] | None = None, *, samples: int | None = None, bounds: tuple[float, float] | None = None, max_subsampling_divisions: int | None = None) -> dict[str, Any] | bencher.variables.sweep_base.SweepBase Deprecated: use ``bn.sweep()`` instead. .. py:function:: with_subsampling_divisions(arr: list, subsampling_divisions: int) -> list Apply subsampling_divisions-based sampling to a list of values. Uses the same subsampling_divisions→sample-count table as SweepBase.with_subsampling_divisions and picks evenly spaced items from *arr* by index. :param arr: list of values to sample from :type arr: list :param subsampling_divisions: The sampling subsampling_divisions to apply (higher subsampling_divisions provides more samples) :type subsampling_divisions: int :returns: The subsampling_divisions-sampled values :rtype: list .. py:function:: with_level(arr: list, level: int) -> list Deprecated: use :func:`with_subsampling_divisions` instead.