Surrogate Functions

A surrogate model is associated with each simulation when its simulation dictionary is added to the MOOP object. This technique is used for generating an approximation to the simulation’s response surface, based on data gathered during the solve.

from parmoo import surrogates

To implement your own custom surrogate function in ParMOO, import and extend the SurrogateFunction ABC.

from parmoo.surrogates.surrogate_function import SurrogateFunction

The SurrogateFunction ABC and the library of existing surrogate functions are documented below.

SurrogateFunction

The abstract base class (ABC) for SurrogateFunction objects.

class surrogates.surrogate_function.SurrogateFunction(m, lb, ub, hyperparams)

ABC describing surrogate functions.

This class contains the following methods.

fit(x, f)
update(x, f)
setTrustRegion(center, radius) (default implementation provided)
evaluate(x)
stdDev(x)
improve(x, global_improv) (default implementation provided)
save(filename)
load(filename)

abstract __init__(m, lb, ub, hyperparams)

Constructor for the SurrogateFunction class.

Parameters:

m (int) – The number of objectives to fit.
lb (ndarray) – A 1D array of lower bounds for the design space.
ub (ndarray) – A 1D array of upper bounds for the design space.
hyperparams (dict) –
A dictionary of hyperparameters to be used by the surrogate models, including:
- des_tols (ndarray, optional): A 1D array whose length matches lb and ub. Each entry is a number (greater than 0) specifying the design space tolerance for that variable.

Returns:

A new SurrogateFunction object.

Return type:

SurrogateFunction

abstract fit(x, f)

Fit a new surrogate to the given data.

Parameters:

x (ndarray) – A 2D array containing the design points to fit.
f (ndarray) – A 2D array of the corresponding objectives values.

abstract update(x, f)

Update an existing surrogate model using new data.

Parameters:

x (ndarray) – A 2D array containing new design points to fit.
f (ndarray) – A 2D array of the corresponding objectives values.

setTrustRegion(center, radius)

Alert the surrogate of the trust-region center and radius.

Default implementation does nothing, which would be the case for a global surrogate model.

Parameters:

center (ndarray) – A 1D array containing the center for a local fit.
radius (ndarray or float) – The radius for the local fit.

abstract evaluate(x)

Evaluate the surrogate at a design point.

Note: For best performance, make sure that jax can jit this method.

Additionally, for compatibility with gradient-based solvers, this method must be implemented in jax and be differentiable via the jax.jacrev() tool.

Parameters:: x (ndarray) – A 1D array containing the design point to evaluate.
Returns:: A 1D array containing the predicted outputs at x.
Return type:: ndarray

stdDev(x)

Evaluate the standard deviation of the surrogate at x.

Note: this method need not be implemented when the acquisition function does not use the model uncertainty.

Additionally, for compatibility with gradient-based solvers, this method must be implemented in jax and be differentiable via the jax.jacrev() tool.

Parameters:: x (ndarray) – A 1D array containing the design point to evaluate.
Returns:: A 1D array containing the output standard deviation at x.
Return type:: ndarray

improve(x, global_improv)

Suggests a design to evaluate to improve the surrogate near x.

A default implementation is given based on random sampling. Re-implement the improve method to overwrite the default policy.

Parameters:

x (ndarray) – A 1D array containing a design point where greater accuracy is needed.
global_improv (Boolean) – When True, ignore the value of x and seek global model improvement.

Returns:

A 2D array containing a list of (at least 1) design points that could be evaluated to improve the surrogate model’s accuracy.

Return type:

ndarray

save(filename)

Save important data from this class so that it can be reloaded.

Note: If this function is left unimplemented, ParMOO will reinitialize a fresh instance after a save/load. If this is the desired behavior, then this method and the load method need not be implemented.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data should be saved.

load(filename)

Reload important data into this class after a previous save.

Note: If this function is left unimplemented, ParMOO will reinitialize a fresh instance after a save/load. If this is the desired behavior, then this method and the save method need not be implemented.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data has been saved.

Gaussian Process (RBF) Models

Implementations of the SurrogateFunction class.

This module contains implementations of the SurrogateFunction ABC, which rely on Gaussian basis functions (i.e., Gaussian processes).

The classes include:

GaussRBF – fits Gaussian radial basis functions (RBFs)

class surrogates.gaussian_proc.GaussRBF(m, lb, ub, hyperparams)

A RBF surrogate model, using a Gaussian basis.

This class implements a local RBF surrogate with a Gaussian basis, using the SurrogateFunction ABC.

__init__(m, lb, ub, hyperparams)

Constructor for the GaussRBF class.

Parameters:

m (int) – The number of objectives to fit.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) –
A dictionary of hyperparameters for the RBF models, including:
- des_tols (numpy.ndarray, optional): A 1d array whose length matches lb and ub. Each entry is a number (greater than 0) specifying the design space tolerance for that variable. By default, des_tols = [1.0e-8, …, 1.0e-8].
- tail_order (int, optional): Order of the polynomial tail. Can be 0 or 1, defaults to 0.

Returns:

A new GaussRBF object.

Return type:

GaussRBF

fit(x, f)

Fit a new Gaussian RBF to the given data.

Parameters:

x (numpy.ndarray) – A 2d array containing the list of design points.
f (numpy.ndarray) – A 2d array containing the corresponding list of objective values.

update(x, f)

Update an existing Gaussian RBF using new data.

Parameters:

x (numpy.ndarray) – A 2d array containing the list of new design points, with which to update the surrogate models.
f (numpy.ndarray) – A 2d array containing the corresponding list of objective values.

setTrustRegion(center, radius)

Set the new trust-region center and refit the local RBF.

Parameters:

center (numpy.ndarray) – A 1d array containing the new trust- region center.
radius (numpy.ndarray or float) – The trust-region radius.

evaluate(x)

Evaluate the Gaussian RBF at a design point.

Parameters:: x (numpy.ndarray) – A 1d array containing the design point at which to the Gaussian RBF should be evaluated.
Returns:: A 1d array containing the predicted objective value at x.
Return type:: numpy.ndarray

stdDev(x)

Evaluate the standard deviation of the Gaussian RBF at x.

Parameters:: x (numpy.ndarray) – A 1d array containing the design point at which the standard deviation should be evaluated.
Returns:: A 1d array containing the standard deviation at x.
Return type:: numpy.ndarray

save(filename)

Save important data from this class so that it can be reloaded.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data should be saved.

load(filename)

Reload important data into this class after a previous save.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data has been saved.

Polynomial Models

Implementations of the SurrogateFunction class.

This module contains implementations of the SurrogateFunction ABC, which rely on local linear models.

The classes include:

Linear – fits a local linear surrogate

class surrogates.polynomial.Linear(m, lb, ub, hyperparams)

A local linear surrogate model.

This class implements a local (TR constrained) linear surrogate, using the SurrogateFunction ABC.

__init__(m, lb, ub, hyperparams)

Constructor for the Linear class.

Parameters:

m (int) – The number of objectives to fit.
lb (numpy.ndarray) – A 1d array of lower bounds for the design region. The number of design variables is inferred from the dimension of lb.
ub (numpy.ndarray) – A 1d array of upper bounds for the design region. The dimension must match ub.
hyperparams (dict) –
A dictionary of hyperparameters for the RBF models, including:
- des_tols (numpy.ndarray, optional): A 1d array whose length matches lb and ub. Each entry is a number (greater than 0) specifying the design space tolerance for that variable. By default, des_tols = [1.0e-8, …, 1.0e-8].

Returns:

A new Linear surrogate object.

Return type:

Linear

fit(x, f)

Fit a new linear model to the given data.

Parameters:

x (numpy.ndarray) – A 2d array containing the list of design points.
f (numpy.ndarray) – A 2d array containing the corresponding list of objective values.

update(x, f)

Update an existing linear model using new data.

Parameters:

x (numpy.ndarray) – A 2d array containing the list of new design points, with which to update the surrogate models.
f (numpy.ndarray) – A 2d array containing the corresponding list of objective values.

setTrustRegion(center, radius)

Set the new trust-region center and refit the local linear model.

Parameters:

center (numpy.ndarray) – A 1d array containing the new trust-region center.
radius (numpy.ndarray or float) – The trust-region radius.

evaluate(x)

Evaluate the linear model at a design point.

Parameters:: x (numpy.ndarray) – A 1d array containing the design point at which the linear model should be evaluated.
Returns:: A 1d array containing the predicted objective value at x.
Return type:: numpy.ndarray

save(filename)

Save important data from this class so that it can be reloaded.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data should be saved.

load(filename)

Reload important data into this class after a previous save.

Parameters:: filename (string) – The relative or absolute path to the file where all reload data has been saved.