bencher.variables.results

Result variable classes for benchmark outputs.

IMPORTANT — hash_persistent() contract:

Every Result* class MUST implement hash_persistent() using _hash_slots() which hashes ALL __slots__ by default. This is critical for the over_time history cache: BenchCfg.hash_persistent() includes result variable hashes in the cache key, so a non-deterministic hash means historical data can never be found.

The default behavior hashes every slot. If a slot holds a non-deterministic value (runtime objects, callbacks, etc.), add it to _hash_exclude on the class:

class MyResult(param.Parameter):
__slots__ = [“units”, “obj”] _hash_exclude = (“obj”,) # runtime object, not deterministic

def hash_persistent(self) -> str:
return _hash_slots(self)

WRONG — never do this (str(self) includes the memory address for param.Parameter):

def hash_persistent(self) -> str:: return hash_sha1(self)

Tests in test/test_hash_persistent.py auto-discover all Result* classes and verify: - Determinism: two equivalent instances produce the same hash - Slot coverage: every __slots__ entry is either hashed or in _hash_exclude Adding a new class without proper hashing will fail CI.

Attributes

`_PARAM_MODULES`
`PANEL_TYPES`
`SCALAR_RESULT_TYPES`
`XARRAY_MULTIDIM_RESULT_TYPES`
`ALL_RESULT_TYPES`

Classes

`OptDir`	StrEnum is a Python `enum.Enum` that inherits from `str`. The default
`ResultFloat`	A class to represent continuous float result variables and the desired optimisation direction.
`ResultBool`	A result type for binary outcomes (success/failure, pass/fail, reachable/unreachable).
`ResultVec`	A class to represent fixed size vector result variable
`ResultHmap`	A class to represent a holomap return type.
`ResultPath`	Parameter that can be set to a string specifying the path of a file.
`ResultVideo`	Parameter that can be set to a string specifying the path of a file.
`ResultImage`	Parameter that can be set to a string specifying the path of a file.
`ResultString`	A String Parameter with optional regular expression (regex) validation.
`ResultContainer`	Base `Parameter` type to hold any type of Python object.
`ResultRerun`	Result type for rerun .rrd spatial visualizations.
`ResultReference`	Use this class to save arbitrary objects that are not picklable or native to panel. You can pass a container callback that takes the object and returns a panel pane to be displayed
`ResultDataSet`	Base `Parameter` type to hold any type of Python object.
`ResultVolume`	Base `Parameter` type to hold any type of Python object.
`ResultVar`	Deprecated: use ResultFloat instead.

Functions

`_hash_slots`(instance)	Hash all __slots__ from the class hierarchy, excluding non-deterministic attributes.
`curve`(→ holoviews.Curve)

Module Contents

bencher.variables.results._PARAM_MODULES

bencher.variables.results._hash_slots(instance)

Hash all __slots__ from the class hierarchy, excluding non-deterministic attributes.

Walks the MRO from the concrete class up to (but not including) param framework base classes, collecting __slots__ from each ancestor. This supports Result class inheritance (e.g. ResultBool extends ResultFloat). Attributes listed in _hash_exclude on any class in the hierarchy are skipped.

The class name is always included in the hash to prevent collisions between different Result* classes that share the same slot layout and values (e.g. ResultPath, ResultVideo, and ResultImage all have __slots__ = [“units”] with default units=”path”).

class bencher.variables.results.OptDir

Bases: strenum.StrEnum

StrEnum is a Python enum.Enum that inherits from str. The default auto() behavior uses the member name as its value.

Example usage:

class Example(StrEnum):
    UPPER_CASE = auto()
    lower_case = auto()
    MixedCase = auto()

assert Example.UPPER_CASE == "UPPER_CASE"
assert Example.lower_case == "lower_case"
assert Example.MixedCase == "MixedCase"

minimize

maximize

none

class bencher.variables.results.ResultFloat(units='ul', direction: OptDir = OptDir.minimize, share_axis=True, max_time_events=None, default=0, **params)

Bases: param.Number

A class to represent continuous float result variables and the desired optimisation direction.

For boolean (success/failure) outcomes, use ResultBool instead — it locks bounds to [0, 1] and produces correct boolean-style plots.

__slots__ = ['units', 'direction', 'share_axis', 'max_time_events']

_hash_exclude = ('direction', 'share_axis', 'max_time_events')

units = 'ul'

default = 0

direction

share_axis = True

max_time_events = None

as_dim() → holoviews.Dimension

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultBool(units='ratio', direction: OptDir = OptDir.minimize, default=0, **params)

Bases: ResultFloat

A result type for binary outcomes (success/failure, pass/fail, reachable/unreachable).

Bounds are locked to [0, 1] and plots use boolean-style rendering. For continuous scalar metrics (time, distance, score), use ResultFloat instead.

default = 0

bounds = (0, 1)

class bencher.variables.results.ResultVec(size, units='ul', direction: OptDir = OptDir.minimize, max_time_events=None, default=0, **params)

Bases: param.List

A class to represent fixed size vector result variable

__slots__ = ['units', 'direction', 'size', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'ul'

default = 0

direction

size

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

index_name(idx: int) → str

given the index of the vector, return the column name that

Parameters:: idx (int) – index of the result vector
Returns:: column name of the vector for the xarray dataset
Return type:: str

index_names() → list[str]

Returns a list of all the xarray column names for the result vector

Returns:: column names
Return type:: list[str]

class bencher.variables.results.ResultHmap(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

A class to represent a holomap return type.

Note: this class has no __slots__, so _hash_slots hashes only the class name. Every ResultHmap instance produces the same hash. This is intentional — there are no configuration attributes that would differentiate instances. If a slot is added in the future, _hash_slots will automatically include it.

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

bencher.variables.results.curve(x_vals: list[float], y_vals: list[float], x_name: str, y_name: str, label: str | None = None, **kwargs) → holoviews.Curve

class bencher.variables.results.ResultPath(default=None, units='path', max_time_events=None, **params)

Bases: param.Filename

Parameter that can be set to a string specifying the path of a file.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system.

The specified path can be absolute, or relative to either:

any of the paths specified in the search_paths attribute (if search_paths is not None);
any of the paths searched by resolve_path() (if search_paths is None).

__slots__ = ['units', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'path'

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

to_container(): Returns a partial function for creating a FileDownload widget with embedding enabled. This function is used to create a panel container to represent the ResultPath object

class bencher.variables.results.ResultVideo(default=None, units='path', max_time_events=None, **params)

Bases: param.Filename

Parameter that can be set to a string specifying the path of a file.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system.

The specified path can be absolute, or relative to either:

any of the paths specified in the search_paths attribute (if search_paths is not None);
any of the paths searched by resolve_path() (if search_paths is None).

__slots__ = ['units', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'path'

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultImage(default=None, units='path', max_time_events=None, **params)

Bases: param.Filename

Parameter that can be set to a string specifying the path of a file.

The string should be specified in UNIX style, but it will be returned in the format of the user’s operating system.

The specified path can be absolute, or relative to either:

any of the paths specified in the search_paths attribute (if search_paths is not None);
any of the paths searched by resolve_path() (if search_paths is None).

__slots__ = ['units', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'path'

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultString(default=None, units='str', max_time_events=None, **params)

Bases: param.String

A String Parameter with optional regular expression (regex) validation.

The String class extends the Parameter class to specifically handle string values and provides additional support for validating values against a regular expression.

Parameters:

default (str, optional) – The default value of the parameter. Default is an empty string ("").
regex (str or None, optional) – A regular expression used to validate the string value. If None, no regex validation is applied. Default is None.

Examples

Define a String parameter with regex validation:

>>> import param
>>> class MyClass(param.Parameterized):
...     user_name = param.String(default="John Doe", regex=r"^[A-Za-z ]+$", doc="Name of a person.")
>>> instance = MyClass()

Access the default value:

>>> instance.user_name
'John Doe'

Set a valid value:

>>> instance.user_name = "Jane Smith"
>>> instance.user_name
'Jane Smith'

Attempt to set an invalid value (non-alphabetic characters):

>>> instance.user_name = "Jane123"
...
ValueError: String parameter 'MyClass.user_name' value 'Jane123' does not match regex '^[A-Za-z ]+$'.

__slots__ = ['units', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'str'

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultContainer(default=None, units='container', max_time_events=None, **params)

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

__slots__ = ['units', 'max_time_events']

_hash_exclude = ('max_time_events',)

units = 'container'

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultRerun(default=None, units='rerun', width=600, height=600, max_time_events=None, **params)

Bases: ResultContainer

Result type for rerun .rrd spatial visualizations.

Stores a path to an .rrd file (like ResultContainer) but carries viewer sizing metadata and provides a dedicated to_container() that renders the file with the rerun web viewer.

Usage in a ParametrizedSweep:

out_rerun = ResultRerun(width=600, height=600)

def benchmark(self):
    rr.log("boxes", rr.Boxes2D(half_sizes=[self.theta, 1]))
    self.out_rerun = bn.capture_rerun_window(width=600, height=600)

__slots__ = ['width', 'height']

_hash_exclude = ('width', 'height')

width = 600

height = 600

to_container(): Return a callable that renders an .rrd file path as a rerun viewer pane.

class bencher.variables.results.ResultReference(obj: Any | None = None, container: Callable[Any, panel.pane.panel] | None = None, default: Any | None = None, units: str = 'container', max_time_events=None, **params)

Bases: param.Parameter

Use this class to save arbitrary objects that are not picklable or native to panel. You can pass a container callback that takes the object and returns a panel pane to be displayed

__slots__ = ['units', 'obj', 'container', 'max_time_events']

_hash_exclude = ('obj', 'container', 'max_time_events')

units = 'container'

obj = None

container = None

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultDataSet(obj: Any | None = None, default: Any | None = None, units: str = 'dataset', max_time_events=None, **params)

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

__slots__ = ['units', 'obj', 'max_time_events']

_hash_exclude = ('obj', 'max_time_events')

units = 'dataset'

obj = None

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

class bencher.variables.results.ResultVolume(obj=None, default=None, units='container', max_time_events=None, **params)

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

__slots__ = ['units', 'obj', 'max_time_events']

_hash_exclude = ('obj', 'max_time_events')

units = 'container'

obj = None

max_time_events = None

hash_persistent() → str: A hash function that avoids the PYTHONHASHSEED ‘feature’ which returns a different hash value each time the program is run

bencher.variables.results.PANEL_TYPES

bencher.variables.results.SCALAR_RESULT_TYPES

bencher.variables.results.XARRAY_MULTIDIM_RESULT_TYPES

bencher.variables.results.ALL_RESULT_TYPES

class bencher.variables.results.ResultVar(*args, **kwargs)

Bases: ResultFloat

Deprecated: use ResultFloat instead.