bencher.variables.sweep_base

Attributes

`shared_slots`
`SUBSAMPLING_DIVISIONS_SAMPLES`

Classes

SweepBase

Base Parameter type to hold any type of Python object.

Functions

`__getattr__`(name)
`describe_variable`(→ list[str])	Generate a string description of a variable

Module Contents

bencher.variables.sweep_base.shared_slots = ['units', 'samples', 'optimize']

bencher.variables.sweep_base.SUBSAMPLING_DIVISIONS_SAMPLES = [0, 1, 2, 3, 5, 9, 17, 33, 65, 129, 257, 513, 1025, 2049]

bencher.variables.sweep_base.__getattr__(name: str)

bencher.variables.sweep_base.describe_variable(v: param.Parameterized, include_samples: bool, value: Any | None = None) → list[str]

Generate a string description of a variable

Parameters:

v (param.Parameterized) – parameter to describe
debug (bool) – Generate a reduced number of samples from the variable
include_samples (bool) – Include a description of the samples

Returns:

String description of the variable

Return type:

str

class bencher.variables.sweep_base.SweepBase(default: Any = ..., *, doc: str | None = None, label: str | None = None, precedence: float | None = None, instantiate: bool = False, constant: bool = False, readonly: bool = False, pickle_default_value: bool = True, allow_None: Literal[False] = False, per_instance: bool = True, allow_refs: bool = False, nested_refs: bool = False, default_factory: collections.abc.Callable[[], Any] | None = None, metadata: dict[str, Any] | None = None)

Bases: param.Parameter

Base Parameter type to hold any type of Python object.

Parameters are a special kind of class attribute implemented as descriptor. Setting a Parameterized class attribute to a Parameter instance enables enhanced functionality, including type and range validation at assignment, support for constant and read-only parameters, documentation strings and dynamic parameter values.

Parameters can only be used as class attributes of Parameterized classes. Using them in standalone contexts or with non-Parameterized classes will not provide the described behavior.

Notes

Parameters provide lots of features.

Dynamic Behavior:

Parameters provide support for dynamic values, type validation, and range checking.
Parameters can be declared as constant or read-only.

Automatic Initialization:

Parameters can be set during object construction using keyword arguments. For example: myfoo = Foo(alpha=0.5); print(myfoo.alpha).
If custom constructors are implemented, they can still pass keyword arguments to the superclass to allow Parameter initialization.

Inheritance:

Parameterized classes automatically inherit parameters from their superclasses. Attributes can be selectively overridden.

Subclassing:

The Parameter class can be subclassed to create custom behavior, such as validating specific ranges or generating values dynamically.

GUI Integration:

Parameters provide sufficient metadata for auto-generating property sheets in graphical user interfaces, enabling user-friendly parameter editing.

Examples

Define a Parameterized class with parameters:

>>> import param
>>> class Foo(param.Parameterized):
...     alpha = param.Parameter(default=0.1, doc="The starting value.")
...     beta = param.Parameter(default=0.5, doc="The standard deviation.", constant=True)

When no initial value is provided the default is used:

>>> Foo().alpha
0.1

When an initial value is provided it is used:

>>> foo = Foo(alpha=0.5)
>>> foo.alpha
0.5

Constant parameters cannot be modified:

>>> foo.beta = 0.1  # Cannot be changed since it's constant
...
TypeError: Constant parameter 'beta' cannot be modified

property sweep_bounds: tuple | None

Return the sweep range (low, high).

FloatSweep/IntSweep store user-supplied bounds as param softbounds (not hard bounds) so that values outside the range are not rejected. This property provides a single access point.

abstract values() → list[Any]

All sweep classes must implement this method. This generates sample values from based on the parameters bounds and sample number.

Returns:: A list of samples from the variable
Return type:: list[Any]

_sweep_hash_exclude: tuple[str, Ellipsis] = ('optimize',)

_sweep_identity() → tuple

Return the tuple of values that uniquely identifies this sweep for the benchmark-level and over_time history caches.

Subclasses MUST override and call super()._sweep_identity() + (...) to append any shape-affecting fields: bounds, sample_values, step, objects, etc. Any field that changes the set of sampled values or the coordinate labels of the resulting xarray must contribute here, otherwise the benchmark-level cache and over_time history will silently serve stale data for a reshaped sweep.

The class name is included so that different Sweep subclasses with the same identity tuple do not collide.

Note: the sample cache is keyed solely by concrete input values (see bencher.worker_job.WorkerJob) and is unaffected by this hash, so widening a sweep range still reuses per-sample cache entries for overlapping inputs.

hash_persistent() → str

Deterministic hash based on _sweep_identity().

Avoids Python’s per-process hash randomisation so two Bench runs (or two processes) compute identical cache keys for equivalent sweeps.

sampling_str() → str: Generate a string representation of the of the sampling procedure

as_slider() → panel.widgets.slider.DiscreteSlider

given a sweep variable (self), return the range of values as a panel slider

Parameters:: debug (bool, optional) – pass to the sweepvar to produce a full set of variables, or when debug=True, a reduces number of sweep vars. Defaults to False.
Returns:: A panel slider with the values() of the sweep variable
Return type:: pn.widgets.slider.DiscreteSlider

as_dim(compute_values=False) → holoviews.Dimension

Takes a sweep variable and turns it into a holoview dimension

Return type:: hv.Dimension

indices_to_samples(desires_num_samples, sample_values)

with_samples(samples: int) → SweepBase

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

with_bounds(low: float, high: float, samples: int | None = None) → SweepBase

Create a copy with overridden sweep bounds (and optionally sample count).

Parameters:

low – Lower bound of the sweep range.
high – Upper bound of the sweep range.
samples – Number of samples. When None the existing sample count is kept.

Returns:

A new sweep with the specified bounds.

Return type:

SweepBase

Raises:

ValueError – If low >= high or the sweep has no bounds attributes.

with_sample_values(sample_values: list) → SweepBase

__call__(values: list | None = None, *, samples: int | None = None, bounds: tuple[float, float] | None = None) → SweepBase

Shorthand for creating a sweep with specific values, sample count, or bounds.

Usage:

Cfg.param.theta([0, 0.5, 1.0])            # explicit values
Cfg.param.theta(samples=5)                  # override sample count
Cfg.param.theta(bounds=(0, 1))              # override range
Cfg.param.theta(bounds=(0, 1), samples=10)  # override range and count

Parameters:

values – Explicit list of values to sweep through.
samples – Number of samples to take from the sweep range.
bounds – (low, high) tuple to override the sweep range.

Returns:

A copy of this sweep with the specified configuration.

Return type:

SweepBase

with_const(const_value: Any) → tuple[SweepBase, Any]

Create a new instance of SweepBase with a constant value.

Parameters:: const_value (Any) – The constant value to be associated with the new instance.
Returns:: A tuple containing the new instance of SweepBase and the constant value.
Return type:: tuple[SweepBase, Any]

with_subsampling_divisions(subsampling_divisions: int = 1, max_subsampling_divisions: int = 12) → SweepBase

with_level(level: int = 1, max_level: int = 12) → SweepBase: Deprecated: use with_subsampling_divisions() instead.