mlos_bench.util

Various helper functions for mlos_bench.

Attributes

BaseTypeVar	BaseTypeVar is a generic with a constraint of the main base classes (e.g.,
BaseTypes	Similar to BaseTypeVar, BaseTypes is a Union of the main base classes.

Functions

check_required_params(→ None)	Check if all required parameters are present in the configuration. Raise ValueError
datetime_parser(→ pandas.Series)	Attempt to convert a pandas column to a datetime format.
get_class_from_name(→ type)	Gets the class from the fully qualified name.
get_git_info(→ Tuple[str, str, str])	Get the git repository, commit hash, and local path of the given file.
instantiate_from_config(→ BaseTypeVar)	Factory method for a new class instantiated from config.
merge_parameters(→ dict)	Merge the source config dict into the destination config. Pick from the source
nullable(→ Optional[Any])	Poor man's Maybe monad: apply the function to the value if it's not None.
path_join(→ str)	Joins the path components and normalizes the path.
prepare_class_load(→ Tuple[str, Dict[str, Any]])	Extract the class instantiation parameters from the configuration.
preprocess_dynamic_configs(→ dict)	Replaces all $name values in the destination config with the corresponding value
strtobool(→ bool)	Convert a string representation of truth to true (1) or false (0).
try_parse_val(→ Optional[Union[int, float, str]])	Try to parse the value as an int or float, otherwise return the string.
utcify_nullable_timestamp(→ Optional[datetime.datetime])	A nullable version of utcify_timestamp.
utcify_timestamp(→ datetime.datetime)	Augment a timestamp with zoneinfo if missing and convert it to UTC.

Module Contents

mlos_bench.util.check_required_params(config: Mapping[str, Any], required_params: Iterable[str]) → None

Check if all required parameters are present in the configuration. Raise ValueError if any of the parameters are missing.

Parameters:

• config (dict) – Free-format dictionary with the configuration of the service or benchmarking environment.

• required_params (Iterable[str]) – A collection of identifiers of the parameters that must be present in the configuration.

Return type:

None

mlos_bench.util.datetime_parser(datetime_col: pandas.Series, *, origin: Literal['utc', 'local']) → pandas.Series

Attempt to convert a pandas column to a datetime format.

Parameters:

• datetime_col (pandas.Series) – The column to convert.

• origin (Literal["utc", "local"]) – Whether to interpret naive timestamps as originating from UTC or local time.

Returns:

The converted datetime column.

Return type:

pandas.Series

Raises:

ValueError – On parse errors.

mlos_bench.util.get_class_from_name(class_name: str) → type

Gets the class from the fully qualified name.

Parameters:

class_name (str) – Fully qualified class name.

Returns:

Class object.

Return type:

type

mlos_bench.util.get_git_info(path: str = __file__) → Tuple[str, str, str]

Get the git repository, commit hash, and local path of the given file.

Parameters:

path (str) – Path to the file in git repository.

Returns:

(git_repo, git_commit, git_path) – Git repository URL, last commit hash, and relative file path.

Return type:

Tuple[str, str, str]

mlos_bench.util.instantiate_from_config(base_class: Type[BaseTypeVar], class_name: str, *args: Any, **kwargs: Any) → BaseTypeVar

Factory method for a new class instantiated from config.

Parameters:

• base_class (type) – Base type of the class to instantiate. Currently it’s one of {Environment, Service, Optimizer}.

• class_name (str) – FQN of a Python class to instantiate, e.g., “mlos_bench.environments.remote.HostEnv”. Must be derived from the base_class.

• args (list) – Positional arguments to pass to the constructor.

• kwargs (dict) – Keyword arguments to pass to the constructor.

Returns:

inst – An instance of the class_name class.

Return type:

Union[Environment, Service, Optimizer, Storage]

mlos_bench.util.merge_parameters(*, dest: dict, source: dict | None = None, required_keys: Iterable[str] | None = None) → dict

Merge the source config dict into the destination config. Pick from the source configs ONLY the keys that are already present in the destination config.

Parameters:

• dest (dict) – Destination config.

• source (Optional[dict]) – Source config.

• required_keys (Optional[Iterable[str]]) – An optional list of keys that must be present in the destination config.

Returns:

dest – A reference to the destination config after the merge.

Return type:

dict

mlos_bench.util.nullable(func: Callable, value: Any | None) → Any | None

Poor man’s Maybe monad: apply the function to the value if it’s not None.

Parameters:

• func (Callable) – Function to apply to the value.

• value (Optional[Any]) – Value to apply the function to.

Returns:

value – The result of the function application or None if the value is None.

Return type:

Optional[Any]

mlos_bench.util.path_join(*args: str, abs_path: bool = False) → str

Joins the path components and normalizes the path.

Parameters:

• args (str) – Path components.

• abs_path (bool) – If True, the path is converted to be absolute.

Returns:

Joined path.

Return type:

str

mlos_bench.util.prepare_class_load(config: dict, global_config: Dict[str, Any] | None = None) → Tuple[str, Dict[str, Any]]

Extract the class instantiation parameters from the configuration.

Parameters:

• config (dict) – Configuration of the optimizer.

• global_config (dict) – Global configuration parameters (optional).

Returns:

(class_name, class_config) – Name of the class to instantiate and its configuration.

Return type:

(str, dict)

mlos_bench.util.preprocess_dynamic_configs(*, dest: dict, source: dict | None = None) → dict

Replaces all $name values in the destination config with the corresponding value from the source config.

Parameters:

• dest (dict) – Destination config.

• source (Optional[dict]) – Source config.

Returns:

dest – A reference to the destination config after the preprocessing.

Return type:

dict

mlos_bench.util.strtobool(val: str) → bool

Convert a string representation of truth to true (1) or false (0).

Parameters:

val (str) – True values are ‘y’, ‘yes’, ‘t’, ‘true’, ‘on’, and ‘1’; False values are ‘n’, ‘no’, ‘f’, ‘false’, ‘off’, and ‘0’.

Raises:

ValueError – If ‘val’ is anything else.

Return type:

bool

mlos_bench.util.try_parse_val(val: str | None) → int | float | str | None

Try to parse the value as an int or float, otherwise return the string.

This can help with config schema validation to make sure early on that the args we’re expecting are the right type.

Parameters:

val (str) – The initial cmd line arg value.

Returns:

The parsed value.

Return type:

TunableValue

mlos_bench.util.utcify_nullable_timestamp(timestamp: datetime.datetime | None, *, origin: Literal['utc', 'local']) → datetime.datetime | None

A nullable version of utcify_timestamp.

Parameters:

• timestamp (Optional[datetime.datetime])

• origin (Literal['utc', 'local'])

Return type:

Optional[datetime.datetime]

mlos_bench.util.utcify_timestamp(timestamp: datetime.datetime, *, origin: Literal['utc', 'local']) → datetime.datetime

Augment a timestamp with zoneinfo if missing and convert it to UTC.

Parameters:

• timestamp (datetime.datetime) – A timestamp to convert to UTC. Note: The original datetime may or may not have tzinfo associated with it.

• origin (Literal["utc", "local"]) – Whether the source timestamp is considered to be in UTC or local time. In the case of loading data from storage, where we intentionally convert all timestamps to UTC, this can help us retrieve the original timezone when the storage backend doesn’t explicitly store it. In the case of receiving data from a client or other source, this can help us convert the timestamp to UTC if it’s not already.

Returns:

A datetime with zoneinfo in UTC.

Return type:

datetime.datetime

mlos_bench.util.BaseTypeVar

BaseTypeVar is a generic with a constraint of the main base classes (e.g., Environment, Optimizer, Scheduler, Service, Storage, etc.).

mlos_bench.util.BaseTypes

Similar to BaseTypeVar, BaseTypes is a Union of the main base classes.