bencher.variables.results ========================= .. py:module:: bencher.variables.results .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: bencher.variables.results._PARAM_MODULES bencher.variables.results.PANEL_TYPES bencher.variables.results.SCALAR_RESULT_TYPES bencher.variables.results.XARRAY_MULTIDIM_RESULT_TYPES bencher.variables.results.ALL_RESULT_TYPES Classes ------- .. autoapisummary:: bencher.variables.results.OptDir bencher.variables.results.ResultFloat bencher.variables.results.ResultBool bencher.variables.results.ResultVec bencher.variables.results.ResultHmap bencher.variables.results.ResultPath bencher.variables.results.ResultVideo bencher.variables.results.ResultImage bencher.variables.results.ResultString bencher.variables.results.ResultContainer bencher.variables.results.ResultRerun bencher.variables.results.ResultReference bencher.variables.results.ResultDataSet bencher.variables.results.ResultVolume bencher.variables.results.ResultVar Functions --------- .. autoapisummary:: bencher.variables.results._hash_slots bencher.variables.results.curve Module Contents --------------- .. py:data:: _PARAM_MODULES .. py:function:: _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"). .. py:class:: OptDir Bases: :py:obj:`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" .. py:attribute:: minimize .. py:attribute:: maximize .. py:attribute:: none .. py:class:: ResultFloat(units='ul', direction: OptDir = OptDir.minimize, share_axis=True, max_time_events=None, default=0, **params) Bases: :py:obj:`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. .. py:attribute:: __slots__ :value: ['units', 'direction', 'share_axis', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('direction', 'share_axis', 'max_time_events') .. py:attribute:: units :value: 'ul' .. py:attribute:: default :value: 0 .. py:attribute:: direction .. py:attribute:: share_axis :value: True .. py:attribute:: max_time_events :value: None .. py:method:: as_dim() -> holoviews.Dimension .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultBool(units='ratio', direction: OptDir = OptDir.minimize, default=0, **params) Bases: :py:obj:`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. .. py:attribute:: default :value: 0 .. py:attribute:: bounds :value: (0, 1) .. py:class:: ResultVec(size, units='ul', direction: OptDir = OptDir.minimize, max_time_events=None, default=0, **params) Bases: :py:obj:`param.List` A class to represent fixed size vector result variable .. py:attribute:: __slots__ :value: ['units', 'direction', 'size', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'ul' .. py:attribute:: default :value: 0 .. py:attribute:: direction .. py:attribute:: size .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:method:: index_name(idx: int) -> str given the index of the vector, return the column name that :param idx: index of the result vector :type idx: int :returns: column name of the vector for the xarray dataset :rtype: str .. py:method:: index_names() -> list[str] Returns a list of all the xarray column names for the result vector :returns: column names :rtype: list[str] .. py:class:: 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: :py:obj:`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. .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:function:: curve(x_vals: list[float], y_vals: list[float], x_name: str, y_name: str, label: str | None = None, **kwargs) -> holoviews.Curve .. py:class:: ResultPath(default=None, units='path', max_time_events=None, **params) Bases: :py:obj:`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 :func:`resolve_path` (if ``search_paths`` is ``None``). .. py:attribute:: __slots__ :value: ['units', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'path' .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:method:: 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 .. py:class:: ResultVideo(default=None, units='path', max_time_events=None, **params) Bases: :py:obj:`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 :func:`resolve_path` (if ``search_paths`` is ``None``). .. py:attribute:: __slots__ :value: ['units', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'path' .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultImage(default=None, units='path', max_time_events=None, **params) Bases: :py:obj:`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 :func:`resolve_path` (if ``search_paths`` is ``None``). .. py:attribute:: __slots__ :value: ['units', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'path' .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultString(default=None, units='str', max_time_events=None, **params) Bases: :py:obj:`param.String` A String Parameter with optional regular expression (regex) validation. The ``String`` class extends the :class:`Parameter` class to specifically handle string values and provides additional support for validating values against a regular expression. :param default: The default value of the parameter. Default is an empty string (``""``). :type default: str, optional :param regex: A regular expression used to validate the string value. If ``None``, no regex validation is applied. Default is ``None``. :type regex: str or None, optional .. rubric:: 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 ]+$'. .. py:attribute:: __slots__ :value: ['units', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'str' .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultContainer(default=None, units='container', max_time_events=None, **params) Bases: :py:obj:`param.Parameter` Base :class:`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 :class:`Parameterized` classes. Using them in standalone contexts or with non-:class:`Parameterized` classes will not provide the described behavior. .. rubric:: 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**: - :class:`Parameterized` classes automatically inherit parameters from their superclasses. Attributes can be selectively overridden. **Subclassing**: - The :class:`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. .. rubric:: Examples Define a :class:`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 .. py:attribute:: __slots__ :value: ['units', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('max_time_events',) .. py:attribute:: units :value: 'container' .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultRerun(default=None, units='rerun', width=600, height=600, max_time_events=None, **params) Bases: :py:obj:`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) .. py:attribute:: __slots__ :value: ['width', 'height'] .. py:attribute:: _hash_exclude :value: ('width', 'height') .. py:attribute:: width :value: 600 .. py:attribute:: height :value: 600 .. py:method:: to_container() Return a callable that renders an .rrd file path as a rerun viewer pane. .. py:class:: 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: :py:obj:`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 .. py:attribute:: __slots__ :value: ['units', 'obj', 'container', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('obj', 'container', 'max_time_events') .. py:attribute:: units :value: 'container' .. py:attribute:: obj :value: None .. py:attribute:: container :value: None .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultDataSet(obj: Any | None = None, default: Any | None = None, units: str = 'dataset', max_time_events=None, **params) Bases: :py:obj:`param.Parameter` Base :class:`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 :class:`Parameterized` classes. Using them in standalone contexts or with non-:class:`Parameterized` classes will not provide the described behavior. .. rubric:: 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**: - :class:`Parameterized` classes automatically inherit parameters from their superclasses. Attributes can be selectively overridden. **Subclassing**: - The :class:`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. .. rubric:: Examples Define a :class:`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 .. py:attribute:: __slots__ :value: ['units', 'obj', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('obj', 'max_time_events') .. py:attribute:: units :value: 'dataset' .. py:attribute:: obj :value: None .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:class:: ResultVolume(obj=None, default=None, units='container', max_time_events=None, **params) Bases: :py:obj:`param.Parameter` Base :class:`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 :class:`Parameterized` classes. Using them in standalone contexts or with non-:class:`Parameterized` classes will not provide the described behavior. .. rubric:: 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**: - :class:`Parameterized` classes automatically inherit parameters from their superclasses. Attributes can be selectively overridden. **Subclassing**: - The :class:`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. .. rubric:: Examples Define a :class:`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 .. py:attribute:: __slots__ :value: ['units', 'obj', 'max_time_events'] .. py:attribute:: _hash_exclude :value: ('obj', 'max_time_events') .. py:attribute:: units :value: 'container' .. py:attribute:: obj :value: None .. py:attribute:: max_time_events :value: None .. py:method:: hash_persistent() -> str A hash function that avoids the PYTHONHASHSEED 'feature' which returns a different hash value each time the program is run .. py:data:: PANEL_TYPES .. py:data:: SCALAR_RESULT_TYPES .. py:data:: XARRAY_MULTIDIM_RESULT_TYPES .. py:data:: ALL_RESULT_TYPES .. py:class:: ResultVar(*args, **kwargs) Bases: :py:obj:`ResultFloat` Deprecated: use ResultFloat instead.