Utilities

utilities

Utilities module.

The module is a collection of utility functions used in different components of the package.

Classes:

Name	Description
SimulationModelSettings	Configuration for an UM-Bridge simulation model server
LoggerSettings	Generic Logger configuration
BaseLogger	Logger base class

Functions:

Name	Description
save_checkpoint_pickle	Save a checkpoint object via pickle
find_checkpoints_in_dir	Find all checkpoint objects in a given directory
convert_list_to_array	Convert a simple list (not nested) to a numpy array
request_umbridge_server	Robust request of an UM-Bridge server
process_mean_std	Get the mean an reference of a surrogate for a given input parameter array
generate_lhs_samples	Generate Latin Hypercube samples within the prescribed hypercube

surrogate.utilities.SimulationModelSettings dataclass

Configuration for a simulation model server.

Attributes:

Name	Type	Description
url	str	str: URL of the UM-Bridge simulation model server
name	str	str: Name of the UM-Bridge simulation model server

surrogate.utilities.LoggerSettings dataclass

Generic Logger configuration.

Attributes:

Name	Type	Description
do_printing	bool	bool: Whether to print log messages to the console
logfile_path	str	str: File to save log data to, if wanted
write_mode	str	str: Write mode, standard options for file writes

surrogate.utilities.BaseLogger

Logger base class.

Provides the generic functionalities of a logger, based on Python's built-in logging module. Enables logging to console and file, with the option to configure the file path and write mode. The logger is thread-safe.

Methods:

Name	Description
info	Thread-safe call to Python's logging.info
exception	Thread-safe call to Python's logging.exception

__init__

__init__(logger_settings: LoggerSettings) -> None

Constructor.

Sets up the Python built-in log handles, based on the input configuration.

Parameters:

Name	Type	Description	Default
logger_settings	LoggerSettings	Configuration of the logger	required

info

info(message: str) -> None

Thread-safe call to Python's logging.exception.

exception

exception(message: str) -> None

Thread-safe call to Python's logging.info.

_process_value_str

_process_value_str(value: float | Iterable, str_format: str) -> str

Convert values to unified format, with format string given by the user.

surrogate.utilities.save_checkpoint_pickle

save_checkpoint_pickle(path: Path, filename: str, checkpoint: Any, checkpoint_id: int) -> None

Save a checkpoint object via pickle.

Pickling is implemented without checks, so be careful with the data you save.

Parameters:

Name	Type	Description	Default
path	Path	Directory to save to	required
filename	str	Name under which to save the checkpoint, may be automatically equipped with an Id if provided	required
checkpoint	Any	Checkpoint object to save	required
checkpoint_id	int	Id to eqiuip the filename with, if wanted	required

surrogate.utilities.find_checkpoints_in_dir

find_checkpoints_in_dir(filestub: Path) -> dict[int, os.DirEntry]

Find all checkpoint objects in a given directory.

This method is used for visualization only. It relies on the naming convention of a presctibed name stub, appended by integer checkpoint ids in increasing order.

Parameters:

Name	Type	Description	Default
filestub	Path	File name stub to search for in directory	required

Returns:

Type	Description
dict[int, os.DirEntry]	dict[str, os.DirEntry]: Found entries, associated with corresponding IDs

surrogate.utilities.convert_list_to_array

convert_list_to_array(input_list: list) -> np.ndarray

Convert a simple list (not nested) to a numpy array.

This conversion is used as an adapter between the surrogate model and the control. The first operates on numpy arrays, the latter on lists of lists, as prescribed by the UM-Bridge interface.

Parameters:

Name	Type	Description	Default
input_list	list	List to convert	required

Returns:

Type	Description
np.ndarray	np.ndarray: Converted input

surrogate.utilities.request_umbridge_server

request_umbridge_server(address: str, name: str) -> ub.HTTPModel

Robust request of an UM-Bridge server.

Parameters:

Name	Type	Description	Default
address	str	URL of the server to call	required
name	str	Name of the server to call	required

Returns:

Type	Description
ub.HTTPModel	ub.HTTPModel: UM-Bridge server object (callable)

surrogate.utilities.process_mean_std

process_mean_std(surrogate: Any, params: np.ndarray) -> tuple[np.ndarray, np.ndarray]

Get the mean an reference of a surrogate for a given input parameter array.

Variance can either be absolute or relative, depending on the configuration of the surrogate. A reference variance can be provided for normalization, otherwise the output data range is used. The mean is transformed back from log space if necessary. This is also part of the configuration of the surrogate.

Parameters:

Name	Type	Description	Default
surrogate	Any	Surrogate model object	required
params	np.ndarray	Input parameters	required

Returns:

Type	Description
tuple[np.ndarray, np.ndarray]	tuple[np.ndarray, np.ndarray]: Mean and standard deviation of the surrogate prediction, processed according to the surrogate's configuration

surrogate.utilities.generate_lhs_samples

generate_lhs_samples(
    dimension: int,
    num_samples: int,
    lower_bounds: list[float],
    upper_bounds: list[float],
    seed: int,
) -> np.ndarray

Generate Latin Hypercube samples within the prescribed hypercube.

Parameters:

Name	Type	Description	Default
dimension	int	Dimension of the parameter space	required
num_samples	int	Number of samples to generate	required
lower_bounds	list[float]	dimension-wise lower bounds of the hypercube	required
upper_bounds	list[float]	dimension-wise upper bounds of the hypercube	required
seed	int	Seed for initialization of the LHS algorithm	required

Returns:

Type	Description
np.ndarray	np.ndarray: Generated samples in parameter space