Surrogates System

Overview

The Stochastic Tools module contains a system for training and running surrogate models. These objects inherit from the SurrogateModel class and are added to a simulation using the [Surrogates] block in the input file. SurrogateModel objects are standalone utilities designed to be directly called by other objects in similar fashion to MOOSE Function objects, refer to Using a SurrogateModel for more information.

Creating a SurrogateModel

A model is created by inheriting from SurrogateModel and overriding the evaluate method. This same method is also what should be called by other objects requiring data. However, the model classes can implement an arbitrary interface as needed.

Using a SurrogateModel

Model objects are obtained by other objects using the getSurrogateModel and getSurrogateModelByName methods. The first expects an input parameter name from which the desired object name is determined. The later function simply accepts the actual name of the object.

For example, the PolynomialChaosReporter object requires a PolynomialChaos object. In the header a reference to the desired model is declare and in the source this reference is initialized with a get method.

  std::vector<const PolynomialChaos *> _pc;
(modules/stochastic_tools/include/reporters/PolynomialChaosReporter.h)
    _pc.push_back(&getSurrogateModelByName<PolynomialChaos>(nm));
(modules/stochastic_tools/src/reporters/PolynomialChaosReporter.C)

Getting Training Data

Training data computed by a trainer object is gathered using the getModelData method. It has a template argument that gives the data type and a single argument, the name of the training data. This name should match the name given in the associated training object(s). For example, the "order" mentioned in the PolynomialChaosTrainer is needed in the actual model. In the header a constant reference to the desired type is declared and this reference is initialized in the source.

  const unsigned int & _order;
(modules/stochastic_tools/include/surrogates/PolynomialChaos.h)
    _order(getModelData<unsigned int>("_order")),
(modules/stochastic_tools/src/surrogates/PolynomialChaos.C)

The training data can be supplied in one of two ways: using a file or directly from a trainer.

File based data initialization happens by using the "filename". The supplied file must have declared data with the same names and types as the get methods used within this class. Refer to SurrogateTrainerOutput for more information.

It is also possible to use data directly from a trainer object by using the "trainer" parameter. This method directly shares the same training data, so if the trainer updates the data the model has a reference to the same data.

Example Input File Syntax

The following input file snippet adds a PolynomialChaos surrogate model for evaluation. Please refer to the documentation on the individual models for more details.

[Surrogates]
  [poly_chaos]
    type = PolynomialChaos
    trainer = poly_chaos
  []
[]
(modules/stochastic_tools/test/tests/surrogates/poly_chaos/main_2d_mc.i)

Available Objects

Available Actions

  • Stochastic Tools App
  • AddSurrogateActionAdds SurrogateTrainer and SurrogateModel objects contained within the [Trainers] and [Surrogates] input blocks.