mlos_bench.tunables package¶

Tunables classes for Environments in mlos_bench.

class mlos_bench.tunables.Tunable(name: str, config: TunableDict)¶

Bases: object

A tunable parameter definition and its current value.

Attributes:

cardinality: Gets the cardinality of elements in this tunable, or else None.
categories: Get the list of all possible values of a categorical tunable.
category: Get the current value of the tunable as a number.
default: Get the default value of the tunable.
distribution: Get the name of the distribution (uniform, normal, or beta) if specified.
distribution_params: Get the parameters of the distribution, if specified.
dtype: Get the actual Python data type of the tunable.
is_categorical: Check if the tunable is categorical.
is_log: Check if numeric tunable is log scale.
is_numerical: Check if the tunable is an integer or float.
is_special: Check if the current value of the tunable is special.
meta: Get the tunable’s metadata.
name: Get the name / string ID of the tunable.
numerical_value: Get the current value of the tunable as a number.
quantization_bins: Get the number of quantization bins, if specified.
quantized_values: Get a sequence of quanitized values for this tunable.
range: Get the range of the tunable if it is numerical, None otherwise.
range_weight: Get weight of the range of the numeric tunable.
span: Gets the span of the range.
special: Get the special values of the tunable.
type: Get the data type of the tunable.
value: Get the current value of the tunable.
values: Gets the categories or quantized values for this tunable.
weights: Get the weights of the categories or special values of the tunable.

Methods

`copy`()	Deep copy of the Tunable object.
`in_range`(value)	Check if the value is within the range of the tunable.
`is_default`()	Checks whether the currently assigned value of the tunable is at its default.
`is_valid`(value)	Check if the value can be assigned to the tunable.
`update`(value)	Assign the value to the tunable.

property cardinality: int | None¶

Gets the cardinality of elements in this tunable, or else None. (i.e., when the tunable is continuous float and not quantized).

If the tunable has quantization set, this

Returns:

cardinalityint: Either the number of points in the tunable or else None.

property categories: List[str | None]¶

Get the list of all possible values of a categorical tunable. Return None if the tunable is not categorical.

Returns:

valuesList[str]: List of all possible values of a categorical tunable.

property category: str | None¶: Get the current value of the tunable as a number.

copy() → Tunable¶

Deep copy of the Tunable object.

Returns:

tunableTunable: A new Tunable object that is a deep copy of the original one.

property default: int | float | str | None¶: Get the default value of the tunable.

property distribution: Literal['uniform', 'normal', 'beta'] | None¶

Get the name of the distribution (uniform, normal, or beta) if specified.

Returns:

distributionstr: Name of the distribution (uniform, normal, or beta) or None.

property distribution_params: Dict[str, float]¶

Get the parameters of the distribution, if specified.

Returns:

distribution_paramsDict[str, float]: Parameters of the distribution or None.

property dtype: Type[int] | Type[float] | Type[str]¶

Get the actual Python data type of the tunable.

This is useful for bulk conversions of the input data.

Returns:

dtypetype: Data type of the tunable - one of {int, float, str}.

in_range(value: int | float | str | None) → bool¶

Check if the value is within the range of the tunable.

Do NOT check for special values. Return False if the tunable or value is categorical or None.

property is_categorical: bool¶

Check if the tunable is categorical.

Returns:

is_categoricalbool: True if the tunable is categorical, False otherwise.

is_default() → int | float | str | None¶: Checks whether the currently assigned value of the tunable is at its default.

property is_log: bool | None¶

Check if numeric tunable is log scale.

Returns:

logbool: True if numeric tunable is log scale, False if linear.

property is_numerical: bool¶

Check if the tunable is an integer or float.

Returns:

is_intbool: True if the tunable is an integer or float, False otherwise.

property is_special: bool¶

Check if the current value of the tunable is special.

Returns:

is_specialbool: True if the current value of the tunable is special, False otherwise.

is_valid(value: int | float | str | None) → bool¶

Check if the value can be assigned to the tunable.

Parameters:

valueUnion[int, float, str]: Value to validate.

Returns:

is_validbool: True if the value is valid, False otherwise.

property meta: Dict[str, Any]¶

Get the tunable’s metadata.

This is a free-form dictionary that can be used to store any additional information about the tunable (e.g., the unit information).

property name: str¶: Get the name / string ID of the tunable.

property numerical_value: int | float¶: Get the current value of the tunable as a number.

property quantization_bins: int | None¶

Get the number of quantization bins, if specified.

Returns:

quantization_binsint | None: Number of quantization bins, or None.

property quantized_values: Iterable[int] | Iterable[float] | None¶

Get a sequence of quanitized values for this tunable.

Returns:

Optional[Union[Iterable[int], Iterable[float]]]: If the Tunable is quantizable, returns a sequence of those elements, else None (e.g., for unquantized float type tunables).

property range: Tuple[int, int] | Tuple[float, float]¶

Get the range of the tunable if it is numerical, None otherwise.

Returns:

range(number, number): A 2-tuple of numbers that represents the range of the tunable. Numbers can be int or float, depending on the type of the tunable.

property range_weight: float | None¶

Get weight of the range of the numeric tunable. Return None if there are no weights or a tunable is categorical.

Returns:

weightfloat: Weight of the range or None.

property span: int | float¶

Gets the span of the range.

Note: this does not take quantization into account.

Returns:

Union[int, float]: (max - min) for numerical tunables.

property special: List[int] | List[float]¶

Get the special values of the tunable. Return an empty list if there are none.

Returns:

special[int] | [float]: A list of special values of the tunable. Can be empty.

property type: Literal['int', 'float', 'categorical']¶

Get the data type of the tunable.

Returns:

typestr: Data type of the tunable - one of {‘int’, ‘float’, ‘categorical’}.

update(value: int | float | str | None) → bool¶

Assign the value to the tunable. Return True if it is a new value, False otherwise.

Parameters:

valueUnion[int, float, str]: Value to assign.

Returns:

is_updatedbool: True if the new value is different from the previous one, False otherwise.

property value: int | float | str | None¶: Get the current value of the tunable.

property values: Iterable[str | None] | Iterable[int] | Iterable[float] | None¶

Gets the categories or quantized values for this tunable.

Returns:

Optional[Union[Iterable[Optional[str]], Iterable[int], Iterable[float]]]: Categories or quantized values.

property weights: List[float] | None¶

Get the weights of the categories or special values of the tunable. Return None if there are none.

Returns:

weights[float]: A list of weights or None.

class mlos_bench.tunables.TunableGroups(config: dict | None = None)¶

Bases: object

A collection of covariant groups of tunable parameters.

Methods

`assign`(param_values)	In-place update the values of the tunables from the dictionary of (key, value) pairs.
`copy`()	Deep copy of the TunableGroups object.
`get_covariant_group_names`()	Get the names of all covariance groups in the collection.
`get_param_values`([group_names, into_params])	Get the current values of the tunables that belong to the specified covariance groups.
`get_tunable`(tunable)	Access the entire Tunable (not just its value) and its covariant group.
`is_defaults`()	Checks whether the currently assigned values of all tunables are at their defaults.
`is_updated`([group_names])	Check if any of the given covariant tunable groups has been updated.
`merge`(tunables)	Merge the two collections of covariant tunable groups.
`reset`([group_names])	Clear the update flag of given covariant groups.
`restore_defaults`([group_names])	Restore all tunable parameters to their default values.
`subgroup`(group_names)	Select the covariance groups from the current set and create a new TunableGroups object that consists of those covariance groups.

assign(param_values: Mapping[str, int | float | str | None]) → TunableGroups¶

In-place update the values of the tunables from the dictionary of (key, value) pairs.

Parameters:

param_valuesMapping[str, TunableValue]: Dictionary mapping Tunable parameter names to new values.

Returns:

selfTunableGroups: Self-reference for chaining.

copy() → TunableGroups¶

Deep copy of the TunableGroups object.

Returns:

tunablesTunableGroups: A new instance of the TunableGroups object that is a deep copy of the original one.

get_covariant_group_names() → Iterable[str]¶

Get the names of all covariance groups in the collection.

Returns:

group_names[str]: IDs of the covariant tunable groups.

Get the current values of the tunables that belong to the specified covariance groups.

Parameters:

group_nameslist of str or None: IDs of the covariant tunable groups. Select parameters from all groups if omitted.
into_paramsdict: An optional dict to copy the parameters and their values into.

Returns:

into_paramsdict: Flat dict of all parameters and their values from given covariance groups.

get_tunable(tunable: str | Tunable) → Tuple[Tunable, CovariantTunableGroup]¶

Access the entire Tunable (not just its value) and its covariant group. Throw KeyError if the tunable is not found.

Parameters:

tunableUnion[str, Tunable]: Name of the tunable parameter.

Returns:

(tunable, group)(Tunable, CovariantTunableGroup): A 2-tuple of an instance of the Tunable parameter and covariant group it belongs to.

is_defaults() → bool¶

Checks whether the currently assigned values of all tunables are at their defaults.

Returns:

bool

is_updated(group_names: Iterable[str] | None = None) → bool¶

Check if any of the given covariant tunable groups has been updated.

Parameters:

group_nameslist of str or None: IDs of the (covariant) tunable groups. Check all groups if omitted.

Returns:

is_updatedbool: True if any of the specified tunable groups has been updated, False otherwise.

merge(tunables: TunableGroups) → TunableGroups¶

Merge the two collections of covariant tunable groups.

Unlike the dict update method, this method does not modify the original when overlapping keys are found. It is expected be used to merge the tunable groups referenced by a standalone Environment config into a parent CompositeEnvironment, for instance. This allows self contained, potentially overlapping, but also overridable configs to be composed together.

Parameters:

tunablesTunableGroups: A collection of covariant tunable groups.

Returns:

selfTunableGroups: Self-reference for chaining.

reset(group_names: Iterable[str] | None = None) → TunableGroups¶

Clear the update flag of given covariant groups.

Parameters:

group_nameslist of str or None: IDs of the (covariant) tunable groups. Reset all groups if omitted.

Returns:

selfTunableGroups: Self-reference for chaining.

restore_defaults(group_names: Iterable[str] | None = None) → TunableGroups¶

Restore all tunable parameters to their default values.

Parameters:

group_nameslist of str or None: IDs of the (covariant) tunable groups. Restore all groups if omitted.

Returns:

selfTunableGroups: Self-reference for chaining.

subgroup(group_names: Iterable[str]) → TunableGroups¶

Select the covariance groups from the current set and create a new TunableGroups object that consists of those covariance groups.

Note: The new TunableGroup will include references (not copies) to original ones, so each will get updated together. This is often desirable to support the use case of multiple related Environments (e.g. Local vs Remote) using the same set of tunables within a CompositeEnvironment.

Parameters:

group_nameslist of str: IDs of the covariant tunable groups.

Returns:

tunablesTunableGroups: A collection of covariant tunable groups.

mlos_bench.tunables package¶

Submodules¶