bencher.variables.inputs

Attributes

LoadValuesDynamically

Classes

`_DynamicValuesSentinel`	str(object='') -> str
`SweepSelector`	A class representing a parameter sweep for selectable options.
`BoolSweep`	A class representing a parameter sweep for boolean values.
`StringSweep`	A class representing a parameter sweep for string values.
`EnumSweep`	A class representing a parameter sweep for enum values.
`YamlSelection`	String-like wrapper that keeps track of the underlying YAML value.
`YamlSweep`	Sweep over configurations stored in a YAML file.
`IntSweep`	A class representing a parameter sweep for integer values.
`FloatSweep`	A class representing a parameter sweep for floating point values.

Functions

`_make_hashable`(→ Any)	Create a deterministic, hashable representation of arbitrary YAML data.
`box`(→ FloatSweep)	Create a FloatSweep parameter centered around a value with a given width.
`sweep`(→ dict[str, ...)	Create a parameter specification for use in plot_sweep input_vars.
`p`(→ dict[str, ...)	Deprecated: use `bn.sweep()` instead.
`with_subsampling_divisions`(→ list)	Apply subsampling_divisions-based sampling to a list of values.
`with_level`(→ list)	Deprecated: use `with_subsampling_divisions()` instead.

Module Contents

class bencher.variables.inputs._DynamicValuesSentinel

Bases: 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’.

__repr__(): Return repr(self).

bencher.variables.inputs.LoadValuesDynamically

class bencher.variables.inputs.SweepSelector(units: str = 'ul', samples: int | None = None, optimize: bool = True, **params)

Bases: param.Selector, 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.

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take from the available options

Type:: int

__slots__ = ['units', 'samples', 'optimize']

units = 'ul'

optimize = True

values() → list[Any]

Return all the values for the parameter sweep.

Returns:: A list of parameter values to sweep through
Return type:: list[Any]

_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. 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 <Foo at 0x7f...> — a memory address that changes every process and would silently produce different cache keys on every run. If you put custom instances in a SweepSelector, either implement __bencher_hash__ or a deterministic __str__/__repr__.

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.

_ensure_nonempty(new_list: list[Any]) → None

_choose_default(new_list: list[Any], explicit_default: Any | None, keep_current: bool) → Any

_update_instance_objects(new_list: list[Any]) → None

_sync_class_defaults(new_list: list[Any], candidate_default: Any) → None

_apply_owner_value(candidate_default: Any) → None

class bencher.variables.inputs.BoolSweep(units: str = 'ul', samples: int | None = None, default: bool = True, optimize: bool = True, **params)

Bases: 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).

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take (typically 2 for booleans)

Type:: int

class bencher.variables.inputs.StringSweep(string_list: list[str], units: str = 'ul', samples: int | None = None, optimize: bool = True, **params)

Bases: 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.

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take from the available strings

Type:: int

classmethod dynamic(*, placeholder: str | None = None, units: str = 'ul', doc: str | None = None, **params) → StringSweep

Create a StringSweep intended for later population.

Parameters:

placeholder – Optional text to show before real values are loaded. Defaults to the sentinel’s displayed text.
units – Units label (optional, passed through).
doc – Documentation string for the parameter.
params – Additional param overrides.

Returns:

A sweep with a single sentinel placeholder value.

Return type:

StringSweep

class bencher.variables.inputs.EnumSweep(enum_type: enum.Enum | list[enum.Enum], units: str = 'ul', samples: int | None = None, optimize: bool = True, **params)

Bases: 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.

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take from the available enum values

Type:: int

__slots__ = ['units', 'samples', 'optimize']

bencher.variables.inputs._make_hashable(value: Any) → Any: Create a deterministic, hashable representation of arbitrary YAML data.

class bencher.variables.inputs.YamlSelection

Bases: str

String-like wrapper that keeps track of the underlying YAML value.

__slots__ = ('_value',)

key() → str

value() → Any

__repr__() → str: Return repr(self).

__eq__(other: Any) → bool: Return self==value.

__lt__(other: Any) → bool: Return self<value.

__iter__(): Implement iter(self).

__reduce__(): Helper for pickle.

__bencher_hash__() → tuple[str, Any]

as_tuple() → tuple[str, Any]

class bencher.variables.inputs.YamlSweep(yaml_path: str | pathlib.Path, units: str = 'ul', samples: int | None = None, default_key: str | None = None, optimize: bool = True, **params)

Bases: 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 YamlSelection instance that exposes the underlying YAML content via the value attribute (and dict-like helpers).

__slots__ = ['units', 'samples', 'optimize', 'yaml_path', '_entries', 'default_key']

_sweep_hash_exclude = ('yaml_path', '_entries', 'default_key')

yaml_path = ''

_entries

default_key = None

static _load_yaml(path: pathlib.Path) → Any

keys() → list[str]

items() → list[tuple[str, Any]]

values() → list[Any]

Return all the values for the parameter sweep.

Returns:: A list of parameter values to sweep through
Return type:: list[Any]

key_for_value(value: Any) → str | None

class bencher.variables.inputs.IntSweep(units: str = 'ul', samples: int | None = None, sample_values: list[int] | None = None, optimize: bool = True, **params)

Bases: param.Integer, 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.

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take from the range

Type:: int

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

__slots__ = ['units', 'samples', 'optimize', 'sample_values']

units = 'ul'

optimize = True

_coerce_bound(value): Override in subclasses to coerce bound values to the correct type.

_sweep_identity() → tuple: Include bounds and sample_values so a reshaped sweep busts the cache.

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
Return type:: list[int]

_validate_value(value, allow_None)

Validate the parameter value against constraints.

Parameters:

value (Any) – The value to be validated.
allow_None (bool) – Whether None is allowed as a valid value.

Raises:

ValueError – If the value does not meet the parameter’s constraints.

_validate_step(val, step)

class bencher.variables.inputs.FloatSweep(units: str = 'ul', samples: int = 10, sample_values: list[float] | None = None, step: float | None = None, optimize: bool = True, **params)

Bases: param.Number, 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.

units

The units of measurement for the parameter

Type:: str

samples

The number of samples to take from the range

Type:: int

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

step

Step size between samples when generating values from bounds

Type:: float, optional

__slots__ = ['units', 'samples', 'optimize', 'sample_values']

units = 'ul'

optimize = True

sample_values

_coerce_bound(value): Override in subclasses to coerce bound values to the correct type.

_sweep_identity() → tuple: Include bounds, sample_values, and step so a reshaped sweep busts the cache.

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
Return type:: list[float]

bencher.variables.inputs.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.

Parameters:

name (str) – The name of the parameter
center (float) – The center value of the parameter
width (float) – The distance from the center to the bounds in both directions

Returns:

A FloatSweep parameter with the specified name, default, and bounds

Return type:

FloatSweep

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

Parameters:

name – The parameter name (str) or a param object (e.g. Cfg.param.theta).
values – A list of values for the parameter.
samples – The number of samples. Must be > 0 if provided.
bounds – (low, high) tuple to override the sweep range.
max_subsampling_divisions – The maximum subsampling_divisions. Must be > 0 if provided.

Returns:

A parameter dict (for string names) or configured sweep object.

Return type:

dict[str, Any] | SweepBase

bencher.variables.inputs.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.

bencher.variables.inputs.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.

Parameters:

arr (list) – list of values to sample from
subsampling_divisions (int) – The sampling subsampling_divisions to apply (higher subsampling_divisions provides more samples)

Returns:

The subsampling_divisions-sampled values

Return type:

list

bencher.variables.inputs.with_level(arr: list, level: int) → list: Deprecated: use with_subsampling_divisions() instead.