Dakota  Version 6.20
Explore and Predict with Confidence
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Private Member Functions | Friends | List of all members
Surrogate Class Referenceabstract

Parent class for surrogate models. More...

Inheritance diagram for Surrogate:
GaussianProcess PolynomialRegression Python PyPolyReg

Public Member Functions

 Surrogate ()
 Constructor that uses defaultConfigOptions and does not build.
 
 Surrogate (const ParameterList &param_list)
 Constructor that sets configOptions but does not build. More...
 
 Surrogate (const MatrixXd &samples, const MatrixXd &response, const ParameterList &param_list)
 Constructor for the Surrogate that sets configOptions and builds the surrogate (does nothing in the base class). More...
 
virtual ~Surrogate ()
 Default destructor.
 
virtual void build (const MatrixXd &samples, const MatrixXd &response)=0
 Build the Surrogate using specified build data. More...
 
virtual VectorXd value (const MatrixXd &eval_points, const int qoi)=0
 Evaluate the Surrogate at a set of prediction points for a single QoI. More...
 
VectorXd value (const MatrixXd &eval_points)
 Evaluate the Surrogate at a set of prediction points for QoI index 0. More...
 
virtual MatrixXd gradient (const MatrixXd &eval_points, const int qoi)
 Evaluate the gradient of the Surrogate at a set of prediction points. More...
 
MatrixXd gradient (const MatrixXd &eval_points)
 Evaluate the gradient of the Surrogate at a set of prediction points for QoI index 0. More...
 
virtual MatrixXd hessian (const MatrixXd &eval_point, const int qoi)
 Evaluate the Hessian of the Surrogate at a single point. More...
 
MatrixXd hessian (const MatrixXd &eval_point)
 Evaluate the Hessian of the Surrogate at a single point for QoI index 0. More...
 
void variable_labels (const std::vector< std::string > &var_labels)
 Set the variable/feature names. More...
 
const std::vector< std::string > & variable_labels () const
 Get the (possibly empty) variable/feature names. More...
 
void response_labels (const std::vector< std::string > &resp_labels)
 Set the response/QoI names. More...
 
const std::vector< std::string > & response_labels () const
 Get the (possibly empty) response/QoI names. More...
 
void set_options (const ParameterList &options)
 Set the Surrogate's configOptions. More...
 
void get_options (ParameterList &options)
 Get the Surrogate's configOptions. More...
 
void print_options ()
 Print the Surrogate's configOptions.
 
virtual void default_options ()=0
 Initialize the Surrogate's defaultConfigOptions.
 
VectorXd evaluate_metrics (const StringArray &mnames, const MatrixXd &points, const MatrixXd &ref_values)
 Evalute metrics at specified points (within surrogates)
 
VectorXd cross_validate (const MatrixXd &samples, const MatrixXd &response, const StringArray &mnames, const int num_folds=5, const int seed=20)
 Perform K-folds cross-validation (within surrogates)
 
template<typename DerivedSurr >
void save (const DerivedSurr &surr_out, const std::string &outfile, const bool binary)
 Serialize a derived (i.e. non-base) surrogate model. More...
 
template<typename DerivedSurr >
void load (const std::string &infile, const bool binary, DerivedSurr &surr_in)
 Load a derived (i.e. non-base) surrogate model. More...
 

Static Public Member Functions

template<typename SurrHandle >
static void save (const SurrHandle &surr_out, const std::string &outfile, const bool binary)
 serialize Surrogate to file (typically through shared_ptr<Surrogate>, but Derived& or Derived* okay too)
 
template<typename SurrHandle >
static void load (const std::string &infile, const bool binary, SurrHandle &surr_in)
 serialize Surrogate from file (typically through shared_ptr<Surrogate>, but Derived& or Derived* okay too)
 
static std::shared_ptr< Surrogateload (const std::string &infile, const bool binary)
 serialize Surrogate from file through pointer to base class (must have been saved via same data type)
 

Public Attributes

util::DataScaler dataScaler
 DataScaler class for a Surrogate's build samples.
 
double responseOffset = 0.
 Response offset.
 
double responseScaleFactor = 1.
 Response scale factor.
 

Protected Member Functions

virtual std::shared_ptr< Surrogateclone () const =0
 clone derived Surrogate class for use in cross-validation
 

Protected Attributes

int numSamples
 Number of samples in the Surrogate's build samples.
 
int numVariables
 Number of features/variables in the Surrogate's build samples.
 
std::vector< std::string > variableLabels
 Names of the variables/features; need not be populated.
 
int numQOI
 Number of quantities of interest predicted by the surrogate. For scalar-valued surrogates numQOI = 1.
 
std::vector< std::string > responseLabels
 Names of the responses/QoIs; need not be populated.
 
ParameterList defaultConfigOptions
 Default Key/value options to configure the surrogate.
 
ParameterList configOptions
 Key/value options to configure the surrogate - will override defaultConfigOptions.
 

Private Member Functions

template<class Archive >
void serialize (Archive &archive, const unsigned int version)
 Serializer for base class data (call from dervied with base_object)
 

Friends

class boost::serialization::access
 Allow serializers access to private class data.
 

Detailed Description

Parent class for surrogate models.

The Surrogate class defines the API for surrogate models contained in the Dakota surrogates module.

Pure virtual functions include build, value, and default_options. Gradient and Hessian methods are optional.

Configuration options for a surrogate are set through the use of a Teuchos ParameterList named configOptions.

Constructor & Destructor Documentation

◆ Surrogate() [1/2]

Surrogate ( const ParameterList param_list)

Constructor that sets configOptions but does not build.

Parameters
[in]param_listList that overrides entries in defaultConfigOptions.

References Surrogate::numQOI, and dakota::silence_unused_args().

◆ Surrogate() [2/2]

Surrogate ( const MatrixXd samples,
const MatrixXd response,
const ParameterList param_list 
)

Constructor for the Surrogate that sets configOptions and builds the surrogate (does nothing in the base class).

Parameters
[in]samplesMatrix of data for surrogate construction - (num_samples by num_features).
[in]responseVector of targets for surrogate construction - (num_samples by num_qoi = 1; only 1 response is supported currently).
[in]param_listList that overrides entries in defaultConfigOptions.

References Surrogate::numQOI, and dakota::silence_unused_args().

Member Function Documentation

◆ build()

virtual void build ( const MatrixXd samples,
const MatrixXd response 
)
pure virtual

Build the Surrogate using specified build data.

Parameters
[in]samplesMatrix of data for surrogate construction - (num_samples by num_features).
[in]responseVector of responses/targets for surrogate construction - (num_samples by num_qoi = 1).

Implemented in Python, PolynomialRegression, and GaussianProcess.

◆ value() [1/2]

virtual VectorXd value ( const MatrixXd eval_points,
const int  qoi 
)
pure virtual

Evaluate the Surrogate at a set of prediction points for a single QoI.

Parameters
[in]eval_pointsMatrix of prediction points - (num_pts by num_features).
[in]qoiIndex for surrogate QoI.
Returns
Values of the Surrogate at the prediction points - (num_pts).

Implemented in Python, PolynomialRegression, and GaussianProcess.

Referenced by Surrogate::evaluate_metrics(), dakota::surrogates::fd_check_gradient(), dakota::surrogates::fd_check_hessian(), PYBIND11_MODULE(), PyPolyReg::value(), GaussianProcess::value(), PolynomialRegression::value(), and Python::value().

◆ value() [2/2]

VectorXd value ( const MatrixXd eval_points)
inline

Evaluate the Surrogate at a set of prediction points for QoI index 0.

Parameters
[in]eval_pointsVector of prediction points - (num_features).
Returns
Values of the Surrogate at the prediction points - (num_pts).

References Surrogate::value().

Referenced by Surrogate::value().

◆ gradient() [1/2]

MatrixXd gradient ( const MatrixXd eval_points,
const int  qoi 
)
virtual

Evaluate the gradient of the Surrogate at a set of prediction points.

Parameters
[in]eval_pointsMatrix of prediction points - (num_pts by num_features).
[in]qoiIndex of the quantity of interest for gradient evaluation - 0 for scalar-valued surrogates.
Returns
Matrix of gradient vectors at the prediction points - (num_pts by num_features).

Reimplemented in Python, PolynomialRegression, and GaussianProcess.

References dakota::silence_unused_args().

Referenced by dakota::surrogates::fd_check_gradient(), Surrogate::gradient(), GaussianProcess::gradient(), PolynomialRegression::gradient(), Python::gradient(), and PYBIND11_MODULE().

◆ gradient() [2/2]

MatrixXd gradient ( const MatrixXd eval_points)
inline

Evaluate the gradient of the Surrogate at a set of prediction points for QoI index 0.

Parameters
[in]eval_pointsMatrix of prediction points
  • (num_pts by num_features).
Returns
Matrix of gradient vectors at the prediction points - (num_pts by num_features).

References Surrogate::gradient().

◆ hessian() [1/2]

MatrixXd hessian ( const MatrixXd eval_point,
const int  qoi 
)
virtual

Evaluate the Hessian of the Surrogate at a single point.

Parameters
[in]eval_pointCoordinates of the prediction point - (1 by num_features).
[in]qoiIndex of the quantity of interest for Hessian evaluation - 0 for scalar-valued surrogates.
Returns
Hessian matrix at the prediction point - (num_features by num_features).

Reimplemented in Python, PolynomialRegression, and GaussianProcess.

References dakota::silence_unused_args().

Referenced by dakota::surrogates::fd_check_hessian(), Surrogate::hessian(), GaussianProcess::hessian(), PolynomialRegression::hessian(), Python::hessian(), and PYBIND11_MODULE().

◆ hessian() [2/2]

MatrixXd hessian ( const MatrixXd eval_point)
inline

Evaluate the Hessian of the Surrogate at a single point for QoI index 0.

Parameters
[in]eval_pointCoordinates of the prediction point - (1 by num_features).
Returns
Hessian matrix at the prediction point - (num_features by num_features).

References Surrogate::hessian().

◆ variable_labels() [1/2]

void variable_labels ( const std::vector< std::string > &  var_labels)

Set the variable/feature names.

Parameters
[in]var_labelsVector of strings, one per input variable

References Surrogate::variableLabels.

◆ variable_labels() [2/2]

const std::vector< std::string > & variable_labels ( ) const

Get the (possibly empty) variable/feature names.

Returns
Vector of strings, one per input variable; empty if not set

References Surrogate::variableLabels.

Referenced by PYBIND11_MODULE().

◆ response_labels() [1/2]

void response_labels ( const std::vector< std::string > &  resp_labels)

Set the response/QoI names.

Parameters
[in]resp_labelsVector of strings, one per surrogate response

References Surrogate::responseLabels.

◆ response_labels() [2/2]

const std::vector< std::string > & response_labels ( ) const

Get the (possibly empty) response/QoI names.

Returns
Vector of strings, one per surrogate response; empty if not set

References Surrogate::responseLabels.

Referenced by PYBIND11_MODULE().

◆ set_options()

void set_options ( const ParameterList options)

Set the Surrogate's configOptions.

Parameters
[in]optionsParameterList of configuration options.

References Surrogate::configOptions.

◆ get_options()

void get_options ( ParameterList options)

Get the Surrogate's configOptions.

Parameters
[out]optionsParameterList of configuration options.

References Surrogate::configOptions.

◆ save()

void save ( const DerivedSurr &  surr_out,
const std::string &  outfile,
const bool  binary 
)

Serialize a derived (i.e. non-base) surrogate model.

Parameters
[in]surr_outSurrogate to seralize.
[in]outfileName of the output text or binary file.
[in]binaryFlag for binary or text format.

◆ load()

void load ( const std::string &  infile,
const bool  binary,
DerivedSurr &  surr_in 
)

Load a derived (i.e. non-base) surrogate model.

Parameters
[in]infileFilename for serialized surrogate.
[in]binaryFlag for binary or text format.
[in]surr_inDerived surrogate class to be populated with serialized data.

The documentation for this class was generated from the following files: