mlos_bench.tunables.tunable

Tunable parameter definition.

Attributes

`DistributionName`	Tunable value distribution type.
`TunableValue`	A tunable parameter value type alias.
`TunableValueType`	Tunable value type.
`TunableValueTypeName`	The string name of a tunable value type.
`TunableValueTypeTuple`	Tunable value type tuple.
`TunableValuesDict`	Tunable values dictionary type.

Classes

`DistributionDict`	A TypedDict for a `Tunable` parameter's required `distribution`'s
`DistributionDictOpt`	A TypedDict for a `Tunable` parameter's optional `distribution`'s
`Tunable`	A tunable parameter definition and its current value.
`TunableDict`	A TypedDict for a `Tunable` parameter's required config parameters.
`TunableDictOpt`	A TypedDict for a `Tunable` parameter's optional config parameters.

Functions

tunable_dict_from_dict(→ TunableDict)

Creates a TunableDict from a regular dict.

Module Contents

class mlos_bench.tunables.tunable.DistributionDict[source]

Bases: DistributionDictOpt

A TypedDict for a Tunable parameter’s required distribution’s config parameters.

Mostly used by type checking. These are the types expected to be received from the json config.

Initialize self. See help(type(self)) for accurate signature.

type: DistributionName[source]

class mlos_bench.tunables.tunable.DistributionDictOpt[source]

Bases: TypedDict

A TypedDict for a Tunable parameter’s optional distribution’s config parameters.

Mostly used by type checking. These are the types expected to be received from the json config.

Initialize self. See help(type(self)) for accurate signature.

params: dict[str, float] | None[source]

class mlos_bench.tunables.tunable.Tunable(name: str, config: dict)[source]

A tunable parameter definition and its current value.

Create an instance of a new tunable parameter.

Parameters:

name (str) – Human-readable identifier of the tunable parameter.
config (dict) – Python dict that represents a Tunable (e.g., deserialized from JSON)

See also

mlos_bench.tunables: for more information on tunable parameters and their configuration.

__eq__(other: object) → bool[source]

Check if two Tunable objects are equal.

Parameters:: other (Tunable) – A tunable object to compare to.
Returns:: is_equal – True if the Tunables correspond to the same parameter and have the same value and type. NOTE: ranges and special values are not currently considered in the comparison.
Return type:: bool

__lt__(other: object) → bool[source]

Compare the two Tunable objects. We mostly need this to create a canonical list of tunable objects when hashing a TunableGroup.

Parameters:: other (Tunable) – A tunable object to compare to.
Returns:: is_less – True if the current Tunable is less then the other one, False otherwise.
Return type:: bool

__repr__() → str[source]

Produce a human-readable version of the Tunable (mostly for logging).

Returns:: string – A human-readable version of the Tunable.
Return type:: str

copy() → Tunable[source]

Deep copy of the Tunable object.

Returns:: tunable – A new Tunable object that is a deep copy of the original one.
Return type:: Tunable

in_range(value: int | float | str | None) → bool[source]

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.

Parameters:: value (int | float | str | None)
Return type:: bool

is_default() → TunableValue[source]

Checks whether the currently assigned value of the tunable is at its default.

Return type:: TunableValue

is_valid(value: TunableValue) → bool[source]

Check if the value can be assigned to the tunable.

Parameters:: value (int | float | str) – Value to validate.
Returns:: is_valid – True if the value is valid, False otherwise.
Return type:: bool

update(value: TunableValue) → bool[source]

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

Parameters:: value (int | float | str) – Value to assign.
Returns:: is_updated – True if the new value is different from the previous one, False otherwise.
Return type:: bool

DTYPE: dict[TunableValueTypeName, TunableValueType][source]: Maps Tunable types to their corresponding Python types by name.

property cardinality: int | None[source]

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:: cardinality – Either the number of points in the tunable or else None.
Return type:: int

property categories: list[str | None][source]

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

Returns:: values – List of all possible values of a categorical tunable.
Return type:: list[str]

property category: str | None[source]

Get the current value of the tunable as a string.

Return type:: str | None

property default: TunableValue[source]

Get the default value of the tunable.

Return type:: TunableValue

property distribution: DistributionName | None[source]

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

Returns:: distribution – Name of the distribution (uniform, normal, or beta) or None.
Return type:: str

property distribution_params: dict[str, float][source]

Get the parameters of the distribution, if specified.

Returns:: distribution_params – Parameters of the distribution or None.
Return type:: dict[str, float]

property dtype: TunableValueType[source]

Get the actual Python data type of the tunable.

This is useful for bulk conversions of the input data.

Returns:: dtype – Data type of the tunable - one of {int, float, str}.
Return type:: type

property is_categorical: bool[source]

Check if the tunable is categorical.

Returns:: is_categorical – True if the tunable is categorical, False otherwise.
Return type:: bool

property is_log: bool | None[source]

Check if numeric tunable is log scale.

Returns:: log – True if numeric tunable is log scale, False if linear.
Return type:: bool

property is_numerical: bool[source]

Check if the tunable is an integer or float.

Returns:: is_int – True if the tunable is an integer or float, False otherwise.
Return type:: bool

property is_special: bool[source]

Check if the current value of the tunable is special.

Returns:: is_special – True if the current value of the tunable is special, False otherwise.
Return type:: bool

property meta: dict[str, Any][source]

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).

Return type:: dict[str, Any]

property name: str[source]

Get the name / string ID of the tunable.

Return type:: str

property numerical_value: int | float[source]

Get the current value of the tunable as a number.

Return type:: int | float

property quantization_bins: int | None[source]

Get the number of quantization bins, if specified.

Returns:: quantization_bins – Number of quantization bins, or None.
Return type:: int | None

property quantized_values: collections.abc.Iterable[int] | collections.abc.Iterable[float] | None[source]

Get a sequence of quantized values for this tunable.

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

property range: tuple[int, int] | tuple[float, float][source]

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

Returns:: range – 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.
Return type:: Union[tuple[int, int], tuple[float, float]]

property range_weight: float | None[source]

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

Returns:: weight – Weight of the range or None.
Return type:: float

property span: int | float[source]

Gets the span of the range.

Note: this does not take quantization into account.

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

property special: list[int] | list[float][source]

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

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

property type: TunableValueTypeName[source]

Get the data type of the tunable.

Returns:: type – Data type of the tunable - one of {‘int’, ‘float’, ‘categorical’}.
Return type:: str

property value: TunableValue[source]

Get the current value of the tunable.

Return type:: TunableValue

property values: collections.abc.Iterable[str | None] | collections.abc.Iterable[int] | collections.abc.Iterable[float] | None[source]

Gets the categories or quantized values for this tunable.

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

property weights: list[float] | None[source]

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

Returns:: weights – A list of weights or None.
Return type:: [float]

class mlos_bench.tunables.tunable.TunableDict[source]

Bases: TunableDictOpt

A TypedDict for a Tunable parameter’s required config parameters.

Mostly used for mypy type checking. These are the types expected to be received from the json config.

Initialize self. See help(type(self)) for accurate signature.

default: TunableValue[source]

type: TunableValueTypeName[source]

class mlos_bench.tunables.tunable.TunableDictOpt[source]

Bases: TypedDict

A TypedDict for a Tunable parameter’s optional config parameters.

Mostly used for mypy type checking. These are the types expected to be received from the json config.

Initialize self. See help(type(self)) for accurate signature.

description: str | None[source]

distribution: DistributionDict | None[source]

log: bool | None[source]

meta: dict[str, Any][source]

quantization_bins: int | None[source]

range: collections.abc.Sequence[int] | collections.abc.Sequence[float] | None[source]

range_weight: float | None[source]

special: list[int] | list[float] | None[source]

special_weights: list[float] | None[source]

values: list[str | None] | None[source]: Return an object providing a view on the dict’s values.

values_weights: list[float] | None[source]

mlos_bench.tunables.tunable.tunable_dict_from_dict(config: dict[str, Any]) → TunableDict[source]

Creates a TunableDict from a regular dict.

Parameters:: config (dict[str, Any]) – A regular dict that represents a TunableDict.
Return type:: TunableDict

mlos_bench.tunables.tunable.DistributionName[source]: Tunable value distribution type.

mlos_bench.tunables.tunable.TunableValue[source]: A tunable parameter value type alias.

mlos_bench.tunables.tunable.TunableValueType[source]: Tunable value type.

mlos_bench.tunables.tunable.TunableValueTypeName[source]: The string name of a tunable value type.

mlos_bench.tunables.tunable.TunableValueTypeTuple[source]

Tunable value type tuple.

For checking with isinstance()

mlos_bench.tunables.tunable.TunableValuesDict[source]: Tunable values dictionary type.