Surrogate Model

surrogate_model

Surrogate model interface and implementation.

Surrogates to be used with the control server have to be defined via he provided ABC interface.

Classes:

Name	Description
BaseSettings	Configuration of a base surrogate object.
SKLearnGPSettings	Additional configuration for a Surrogate based on a scikit-learn Gaussian process regressor.
SKLearnGPCheckpoint	Checkpoint object for a scikit-learn GPR.
BaseSurrogateModel	ABC for surrogate models.
SKLearnGPSurrogateModel	Surrogate implementation based on Gaussian Process Regression in scikit-learn.

surrogate.surrogate_model.BaseSettings dataclass

Configuration of a base surrogate object.

Attributes:

Name	Type	Description
minimum_num_training_points	int	Number of training points below which surrogate is not retrained.
perform_log_transform	bool	Whether the output of the surrogate should be log-transformed.
variance_is_relative	bool	Whether the variance should be normalized, either by a provided reference or by the range of the training data.
variance_reference	float	Reference for normalization of the variance, if wanted.
value_range_underflow_threshold	float	Value below which the data range for normalization is cut off, for numerical stability.
log_mean_underflow_value	float	Value below which the log-transformed output is cut off, for numerical stability.
mean_underflow_value	float	Value below which the not log-transformed output is cut off, for numerical stability.
checkpoint_load_file	Path	Checkpoint file to initialize surrogate from.
checkpoint_save_path	Path	File to save new checkpoint to, automatically appended by an integer id.

surrogate.surrogate_model.SKLearnGPSettings dataclass

Bases: BaseSettings

Additional configuration for a Surrogate based on a scikit-learn Gaussian process regressor.

Attributes:

Name	Type	Description
scaling_kernel	float	Scaling prefactor of the kernel function.
correlation_kernel	float | np.ndarray	Dimension-wise correlation length of the kernel.
data_noise	float	Assumed noise in the data.
num_optimizer_restarts	int	Number of restarts for optimization, can be used to find more reasonable fits during regression.
normalize_output	bool	Normalize the regressor prediction within scikit-learn.
init_seed	int	Seed for initialization of the optimizer.

surrogate.surrogate_model.SKLearnGPCheckpoint dataclass

Checkpoint object for a scikit-learn GPR .

Attributes:

Name	Type	Description
input_data	np.ndarray	Input training data.
output_data	np.ndarray	Output training data.
hyperparameters	dict[str, Any]	Hyperparameters of the trained surrogate.

surrogate.surrogate_model.BaseSurrogateModel

ABC for surrogate models.

The base class provides generic functionality and prescribes an interface compatible with the control server.

Methods:

Name	Description
update_training_data	Update the internal training data storage.
fit	Fit the surrogate from the data in the internal storage.
predict_and_estimate_variance	Predict output (mean and variance) for a given parameter set.
load_checkpoint	Load a checkpoint for the surrogate.
save_checkpoint	Save a checkpoint.

training_data abstractmethod property

training_data: None

Get internal training data.

scale_and_correlation_length property

scale_and_correlation_length: None

Get scale and correlation length (only releveánt for GPRs).

variance_is_relative property

variance_is_relative: bool

Get the variance configuration.

variance_reference property

variance_reference: float

Get the reference variance for normalization.

log_transformed property

log_transformed: bool

Get the flag whether surrogate output is being log-transformed.

output_data_range property

output_data_range: float

Get range of the internal output data.

__init__ abstractmethod

__init__(settings: BaseSettings) -> None

Constructor.

Initializes surrogate with generic settings.

Parameters:

Name	Type	Description	Default
settings	BaseSettings	Configuration of the surrogate model.	required

update_training_data abstractmethod

update_training_data(input_data: np.ndarray, output_data: np.ndarray) -> None

Update the internal training data storage.

Parameters:

Name	Type	Description	Default
input_data	np.ndarray	Input data to be added to the training data.	required
output_data	np.ndarray	Output data to be added to the training data.	required

fit abstractmethod

fit() -> None

Fit the surrogate from the data in the internal storage.

predict_and_estimate_variance abstractmethod

predict_and_estimate_variance(
    parameters: np.ndarray, is_relative: bool
) -> tuple[np.ndarray, np.ndarray]

Predict output (mean and variance) for a given parameter set.

Variance may be normalized by the range of the training data or a provided reference in specific implementations.

Parameters:

Name	Type	Description	Default
parameters	np.ndarray	Input parameters for prediction.	required
is_relative	bool	Whether the variance should be normalized.	required

load_checkpoint abstractmethod

load_checkpoint(checkpoint_load_file: Path) -> None

Load a checkpoint for the surrogate.

save_checkpoint abstractmethod

save_checkpoint(checkpoint_save_path: Path) -> None

Save a checkpoint.

surrogate.surrogate_model.SKLearnGPSurrogateModel

Bases: BaseSurrogateModel

Surrogate implementation based on Gaussian Process Regression in scikit-learn.

Methods:

Name	Description
update_training_data	Update the internal training data storage.
fit	Fit the surrogate from the data in the internal storage.
predict_and_estimate_variance	Predict output (mean and variance) for a given parameter set.
load_checkpoint	Load a checkpoint for the surrogate.
save_checkpoint	Save a checkpoint.
scale_and_correlation_length	Get scale and correlation length of the GPR.

training_data property writable

training_data: tuple[np.ndarray, np.ndarray]

Get the internal training data.

scale_and_correlation_length property

scale_and_correlation_length: tuple[float, np.ndarray]

Get scale and correlation length, hyperparameters of the GPR.

__init__

__init__(settings: SKLearnGPSettings) -> None

Constructor, calls initialization of the GPR and updates with checkpoint data.

Parameters:

Name	Type	Description	Default
settings	SKLearnGPSettings	Configuration of the surrogate	required

update_training_data

update_training_data(input_data: np.ndarray, output_data: np.ndarray) -> None

Update internal training data from external input.

Parameters:

Name	Type	Description	Default
input_data	np.ndarray	Input training data to be stored	required
output_data	np.ndarray	Output training data to be stored	required

fit

fit() -> None

Fit the surrogate .

predict_and_estimate_variance

predict_and_estimate_variance(parameters: np.ndarray) -> tuple[float, float]

Get prediction from the surrogate for given input parameters.

Predictions consist of a mean and a variance, as provided by a GPR. Depending on the configuration of the surrogate, the output may be log-transformed and the variance may be normalized.

Parameters:

Name	Type	Description	Default
parameters	np.ndarray	Input parameters for prediction.	required

Returns:

Type	Description
tuple[float, float]	tuple[float, float]: Mean and variance of the prediction.

load_checkpoint

load_checkpoint(checkpoint_load_file: Path) -> None

Load a checkpoint from a pickle object.

Pickling is performed without checks, so be careful with the data you load.

Parameters:

Name	Type	Description	Default
checkpoint_load_file	Path	File to unpickle checkpoint from.	required

save_checkpoint

save_checkpoint(checkpoint_id: int) -> None

Save a checkpoint with the given id.

Parameters:

Name	Type	Description	Default
checkpoint_id	int	Checkpoint id to append to the save path.	required

_init_gp_model staticmethod

_init_gp_model(settings: SKLearnGPSettings) -> GaussianProcessRegressor

Initialize a GPR from scikit-learn.

Use l-bfgs-b for optimization.

Parameters:

Name	Type	Description	Default
settings	SKLearnGPSettings	Configuration of the GPR.	required

Returns:

Name	Type	Description
GaussianProcessRegressor	GaussianProcessRegressor	GPR object