bencher.variables.sweep_base ============================ .. py:module:: bencher.variables.sweep_base Attributes ---------- .. autoapisummary:: bencher.variables.sweep_base.shared_slots bencher.variables.sweep_base.SUBSAMPLING_DIVISIONS_SAMPLES Classes ------- .. autoapisummary:: bencher.variables.sweep_base.SweepBase Functions --------- .. autoapisummary:: bencher.variables.sweep_base.__getattr__ bencher.variables.sweep_base.describe_variable Module Contents --------------- .. py:data:: shared_slots :value: ['units', 'samples', 'optimize'] .. py:data:: SUBSAMPLING_DIVISIONS_SAMPLES :value: [0, 1, 2, 3, 5, 9, 17, 33, 65, 129, 257, 513, 1025, 2049] .. py:function:: __getattr__(name: str) .. py:function:: describe_variable(v: param.Parameterized, include_samples: bool, value: Any | None = None) -> list[str] Generate a string description of a variable :param v: parameter to describe :type v: param.Parameterized :param debug: Generate a reduced number of samples from the variable :type debug: bool :param include_samples: Include a description of the samples :type include_samples: bool :returns: String description of the variable :rtype: str .. py:class:: 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: :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:property:: sweep_bounds :type: 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. .. py:method:: values() -> list[Any] :abstractmethod: 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 :rtype: list[Any] .. py:attribute:: _sweep_hash_exclude :type: tuple[str, Ellipsis] :value: ('optimize',) .. py:method:: _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 :class:`bencher.worker_job.WorkerJob`) and is unaffected by this hash, so widening a sweep range still reuses per-sample cache entries for overlapping inputs. .. py:method:: hash_persistent() -> str Deterministic hash based on :meth:`_sweep_identity`. Avoids Python's per-process hash randomisation so two Bench runs (or two processes) compute identical cache keys for equivalent sweeps. .. py:method:: sampling_str() -> str Generate a string representation of the of the sampling procedure .. py:method:: as_slider() -> panel.widgets.slider.DiscreteSlider given a sweep variable (self), return the range of values as a panel slider :param debug: pass to the sweepvar to produce a full set of variables, or when debug=True, a reduces number of sweep vars. Defaults to False. :type debug: bool, optional :returns: A panel slider with the values() of the sweep variable :rtype: pn.widgets.slider.DiscreteSlider .. py:method:: as_dim(compute_values=False) -> holoviews.Dimension Takes a sweep variable and turns it into a holoview dimension :rtype: hv.Dimension .. py:method:: indices_to_samples(desires_num_samples, sample_values) .. py:method:: with_samples(samples: int) -> SweepBase .. py:method:: _coerce_bound(value) Override in subclasses to coerce bound values to the correct type. .. py:method:: with_bounds(low: float, high: float, samples: int | None = None) -> SweepBase Create a copy with overridden sweep bounds (and optionally sample count). :param low: Lower bound of the sweep range. :param high: Upper bound of the sweep range. :param samples: Number of samples. When *None* the existing sample count is kept. :returns: A new sweep with the specified bounds. :rtype: SweepBase :raises ValueError: If *low* >= *high* or the sweep has no bounds attributes. .. py:method:: with_sample_values(sample_values: list) -> SweepBase .. py:method:: __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 :param values: Explicit list of values to sweep through. :param samples: Number of samples to take from the sweep range. :param bounds: ``(low, high)`` tuple to override the sweep range. :returns: A copy of this sweep with the specified configuration. :rtype: SweepBase .. py:method:: with_const(const_value: Any) -> tuple[SweepBase, Any] Create a new instance of SweepBase with a constant value. :param const_value: The constant value to be associated with the new instance. :type const_value: Any :returns: A tuple containing the new instance of SweepBase and the constant value. :rtype: tuple[SweepBase, Any] .. py:method:: with_subsampling_divisions(subsampling_divisions: int = 1, max_subsampling_divisions: int = 12) -> SweepBase .. py:method:: with_level(level: int = 1, max_level: int = 12) -> SweepBase Deprecated: use :meth:`with_subsampling_divisions` instead.