Surrogate Models

This section documents the surrogate model hierarchy in the Standard Evaluator library. Surrogate models provide trained mathematical approximations of evaluators, supporting training from data, prediction, serialization, and parallel training.

Base Class

class SurrogateModel

Bases: NumpyEvaluator

Defines behavior common to all surrogate models and what behaviors should be defined by the models themselves.

Attributes:

`constant_variables`	The constant variables and the values they take on.
`nonconstant_variables`	The non-constant variables.
`xlb`	The lower left corner of the box that bounds the input sites.
`xub`	The upper right corner of the box that bounds the input sites.
`nind`	The number of nonconstant independent variables.
`sites`	Sites currently used to calibrate the model.
`sites_as_np`	Sites currently used to calibrate the model as a float array.
`sites_input`	Input sites used to calibrate the model.
`sites_output`	Output values used to calibrate the model.
`nsites`	Number of sites in the model.

Methods:

`__init__`(sites[, name, comp_cost, cache, ...])	Initialize the surrogate model.
`__call__`(sites[, names])	Predict the desired response values for the given sites.
`update`(add_sites)	Update the model with additional sites.
`to_dict`()	Save all information necessary to rebuild the model into a dictionary.
`from_dict`(model_info)	Build a model from dictionary information.
`check_consistency_of_sites`(sites)	Validate that sites are consistent with the problem definition.
`remove_constants`(sites)	Strip constant variables from sites and return as a float array.
`check_input_array`(site_inputs)	Validate that site_inputs is an (m x nind) array.
`get_response_indices`([names])	Get the indices of the responses in the names list.
`eval_np`(sites[, names])	Predict the desired response values for the given sites.

property constant_variables: Dict[int, Tuple[str, float]]

The constant variables and the values they take on.

Returns:

A dict with constant variable indices: as keys and (name, value) tuples as values.

Return type:

Dict[int, Tuple[str, float]]

property nonconstant_variables: List[str]

The non-constant variables.

Returns:: A list of the non-constant variables, in order.
Return type:: List[str]

property xlb: ndarray[tuple[Any, ...], dtype[float64]]

The lower left corner of the box that bounds the input sites.

Returns:

An array of length nind containing the lower: left corner of the bounding box.

Return type:

NDArray[np.float64]

property xub: ndarray[tuple[Any, ...], dtype[float64]]

The upper right corner of the box that bounds the input sites.

Returns:

An array of length nind containing the upper: right corner of the bounding box.

Return type:

NDArray[np.float64]

property nind: int

The number of nonconstant independent variables.

Returns:: Count of nonconstant independent variables.
Return type:: int

property sites: DataFrame

Sites currently used to calibrate the model.

Returns:: The calibration sites.
Return type:: pd.DataFrame

property sites_as_np: ndarray[tuple[Any, ...], dtype[float64]]

Sites currently used to calibrate the model as a float array.

Returns:: The calibration sites as a NumPy array.
Return type:: NDArray[np.float64]

property sites_input: ndarray[tuple[Any, ...], dtype[float64]]

Input sites used to calibrate the model.

Returns:: The input portion of the calibration sites.
Return type:: NDArray[np.float64]

property sites_output: ndarray[tuple[Any, ...], dtype[float64]]

Output values used to calibrate the model.

Returns:: The output portion of the calibration sites.
Return type:: NDArray[np.float64]

property nsites: int

Number of sites in the model.

Returns:: The site count.
Return type:: int

__init__(sites, name=None, comp_cost=100, cache=None, cache_options=None, logging=False, interface=None, opt_problem=None, num_independent=None, num_dependent=None, options=None, **kwargs)

Initialize the surrogate model.

Parameters:

sites (DataFrame) – Sites to initialize the model with. Should include both variable and true response values.
name (str | None) – Name to give model for easier identification. Defaults to the model type name.
comp_cost (float) – Computational cost estimate. Defaults to 100.
cache (str) – Path to SQLite database for cached sites.
cache_options (dict) – Options to modify caching behavior.
logging (bool) – When True the evaluator keeps track of every site.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.
num_independent (int) – Number of independent variables.
num_dependent (int) – Number of dependent variables.
options (BaseModel | None) – Pydantic model containing options for this surrogate model.
**kwargs – Additional keyword arguments.

Return type:

None

__call__(sites, names=None)

Predict the desired response values for the given sites.

Note

The passed dataframe will be modified in place.

Parameters:

sites (DataFrame) – Sites to get predicted response values at.
names (List[str]) – Which responses are computed. Defaults to None (all).

Return type:

None

update(add_sites)

Update the model with additional sites.

Parameters:

add_sites (DataFrame | ndarray[tuple[Any, ...], dtype[float64]]) – Sites to add into the model. Should include variable and true response values.

Raises:

TypeError – If add_sites is not a DataFrame or NumPy array.
ValueError – If the input array has the wrong number of columns or the DataFrame is missing required columns.

Return type:

None

to_dict()

Save all information necessary to rebuild the model into a dictionary.

Returns:

The dictionary containing all the information needed to rebuild: this model.

Return type:

dict

classmethod from_dict(model_info)

Build a model from dictionary information.

Parameters:

model_info (dict) –

Information needed to build the model. Should have the following:

{
    'type': 'TypeOfModel',
    'info': {
        # Parameters needed to build model
    },
    'opt_problem': {
        # OptProblem serialized via model_dump()
    },
    'name': 'name_of_model',
    'version': '6.0.0'
}

Returns:

An instance of the model built using the provided information.

Return type:

SurrogateModel

Raises:

TypeError – model_info is not a dictionary.
KeyError – model_info is missing necessary keys.
NameError – model_info[‘type’] is not a valid model type.
ValueError – Trying to instantiate a model with information from a different model.

check_consistency_of_sites(sites)

Validate that sites are consistent with the problem definition.

Parameters:

sites (DataFrame) – Sites to be checked.

Raises:

TypeError – If sites is not a DataFrame.
ValueError – If sites are missing input variables or fixed variable values do not match their bounds.

remove_constants(sites)

Strip constant variables from sites and return as a float array.

Parameters:: sites (DataFrame) – Sites to be reduced to an array.
Returns:: Array of nonconstant input and output values.
Return type:: NDArray[np.float64]

check_input_array(site_inputs)

Validate that site_inputs is an (m x nind) array.

Parameters:: site_inputs (ndarray) – Array whose rows are sites and columns are nonconstant variables.
Raises:: TypeError – If site_inputs is not an ndarray or has the wrong shape.
Return type:: None

get_response_indices(names=None)

Get the indices of the responses in the names list.

Parameters:: names (List[str]) – List of response names to get indices for. If None, all responses are used.
Returns:: List of indices for the requested responses.
Return type:: List[int]

abstractmethod eval_np(sites, names=None)

Predict the desired response values for the given sites.

Parameters:

sites (ndarray) – Sites to compute predicted response values.
names (list) – Which responses are computed. Defaults to None (all).

Returns:

Predicted response values for the given sites.

Return type:

NDArray[np.float64]

Polynomial Model

class PolynomialModel

Bases: SurrogateModel

Class representing a polynomial response surface model.

degree

The degree of the polynomial model.

Type:: int

coefs

A numpy array (nterms x ndep) containing the coefficients of the polynomial responses.

Type:: numpy.ndarray

nterms

The number of coefficients for an output of the polynomial model.

Type:: int

deg_exp

A numpy array (nterms x nind) containing the degree exponents of the polynomial responses.

Type:: numpy.ndarray

Attributes:

`degree`	The degree of the polynomial model.
`coefs`	Coefficients array (nterms x ndep) of the polynomial model.
`nterms`	The number of terms in the polynomial model.
`deg_exp`	Degree exponents array (nterms x nind) of the polynomial model.

Methods:

`__init__`(sites[, name, options, interface, ...])	Constructor for PolynomialModel.
`eval_np`(x[, names])	Evaluate the polynomial model at given points.
`jacobian`(x)	Compute the jacobian of the polynomial model at a set of points.
`get_response_models`(target_responses)	Restrict the polynomial model to the target set of responses.

property degree: int: The degree of the polynomial model.

property coefs: ndarray: Coefficients array (nterms x ndep) of the polynomial model.

property nterms: int: The number of terms in the polynomial model.

property deg_exp: ndarray: Degree exponents array (nterms x nind) of the polynomial model.

__init__(sites, name=None, options=None, interface=None, opt_problem=None, num_independent=None, num_dependent=None, **kwargs)

Constructor for PolynomialModel.

Parameters:

sites (pd.DataFrame) – Sites to initialize the model with. Should include both variable and true response values.
name (str, optional) – Name to give model for easier identification, by default None.
options (PolynomialModelOptions, optional) – Pydantic model containing options for this polynomial model, by default None.
interface (EvaluatorInfo, optional) – Evaluator interface information, by default None.
opt_problem (OptProblem, optional) – Optimization problem definition, by default None.
num_independent (int, optional) – Number of independent variables, by default None.
num_dependent (int, optional) – Number of dependent variables, by default None.
**kwargs – Additional keyword arguments.

eval_np(x, names=None)

Evaluate the polynomial model at given points.

Parameters:

x (np.array) – An array (npts x nind) containing the desired evaluation locations.
names (List[str], optional) – Which responses are computed, by default None.

Returns:

An array (npts x ndep) of model output values.

Return type:

np.ndarray

jacobian(x)

Compute the jacobian of the polynomial model at a set of points.

Parameters:: x (array) – Array (npts x nind) of evaluation locations.
Returns:: Array (npts x nind x ndep) of jacobian values.
Return type:: np.ndarray

get_response_models(target_responses)

Restrict the polynomial model to the target set of responses.

Parameters:: target_responses (List[str]) – A list of desired response names.
Returns:: A new model restricted to the target responses.
Return type:: PolynomialModel
Raises:: ValueError – If target responses are not in the model.

SMT-Based Models

The following models require the smt optional dependency. Install with: pip install standard-evaluator[smt]

Radial Basis Function Model (RBFModel)

class RadialBasisFunctionModel

Bases: AbstractSmtModel

Class representing a RadialBasisFunction model.

#Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/rbf.html

Methods:

__init__(sites[, options, name, interface, ...])

Initializes a RBF model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes a RBF model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with RBF model options.
name (str | None) – Name of the RBF model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None

Inverse Distance Weighting Model (IDWModel)

class InverseDistanceWeightingModel

Bases: AbstractSmtModel

Class representing a InverseDistanceWeighting model.

#Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/idw.html

Methods:

__init__(sites[, options, name, interface, ...])

Initializes an InverseDistanceWeighting model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes an InverseDistanceWeighting model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with IDW model options.
name (str | None) – Name of the IDW model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None

Gradient-Enhanced Neural Networks Model (GENNModel)

class GradientEnhancedNeuralNetworksModel

Bases: AbstractSmtModel

Class representing a GradientEnhancedNeuralNetworks model.

Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/genn.html ToDo: Implement the test cases for GENN model after implementing the derivative method for it

Methods:

__init__(sites[, options, name, interface, ...])

Initializes a GradientEnhancedNeuralNetworks model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes a GradientEnhancedNeuralNetworks model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with GENN model options.
name (str | None) – Name of the GENN model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None

Least Squares Approximation Model (LSModel)

class LeastSquaresApproximationModel

Bases: AbstractSmtModel

Class representing a LeastSquaredApproximation model.

#Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/ls.html

Methods:

__init__(sites[, options, name, interface, ...])

Initializes a LeastSquares Approximation model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes a LeastSquares Approximation model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with LS model options.
name (str | None) – Name of the LS model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None

Regularized Minimal-Energy Tensor-Product B-Splines (RMTSModel)

class RegularizedMinimalEnergyTensorProductBSplines

Bases: AbstractSmtModel

Class representing a Regularized minimal-energy tensor-product splines model RMTS is implemented in SMT with two choices of splines:

B-splines (RMTB): RMTB uses B-splines with a uniform knot vector in each dimension. The number of B-spline control points and the B-spline order in each dimension are options that trade off efficiency and precision of the interpolant.
Cubic Hermite splines (RMTC): RMTC divides the domain into tensor-product cubic elements. For adjacent elements, the values and derivatives are continuous. The number of elements in each dimension is an option that trades off efficiency and precision.

#Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/rmts.html

Methods:

__init__(sites[, options, name, interface, ...])

Initializes a RMTB model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes a RMTB model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with RMTB model options.
name (str | None) – Name of the RMTB model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None

Second Order Polynomial Approximation Model (SOPAModel)

class SecondOrderPolynomialApproximationModel

Bases: AbstractSmtModel

Class representing a SecondOrderPolynomialApproximationModel. #No.of sites in the dataframe should be greater than equal to (self.nx + 1) * (self.nx + 2) / 2.0:, where nx is the number of variables i.e X.shape[0] < (self.nx + 1) * (self.nx + 2) / 2.0:, where nx is the number of variables Reference link: https://smt.readthedocs.io/en/latest/_src_docs/surrogate_models/qp.html

Methods:

__init__(sites[, options, name, interface, ...])

Initializes a SecondOrder Polynomial approximation model from an OptProblem and site data.

__init__(sites, options=None, name=None, interface=None, opt_problem=None)

Initializes a SecondOrder Polynomial approximation model from an OptProblem and site data.

Parameters:

sites (DataFrame) – The site data.
options (BaseModel | None) – Pydantic BaseModel instance with QP model options.
name (str | None) – Name of the QP model. Defaults to None.
interface (EvaluatorInfo) – EvaluatorInfo defining inputs and outputs.
opt_problem (OptProblem) – OptProblem defining the optimization problem.

Return type:

None