Automated Surrogate Construction Procedure

Collaboration diagram for Automated Surrogate Construction Procedure:

Typedefs
using	TasGrid::ModelSignature = std::function< void(std::vector< double > const &x, std::vector< double > &y, size_t thread_id)>
	Signature of a model function to be used in the construction procedures. More...

Functions
template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>
void	TasGrid::constructSurrogate (ModelSignature model, size_t max_num_points, size_t num_parallel_jobs, size_t max_samples_per_job, TasmanianSparseGrid &grid, double tolerance, TypeRefinement criteria, int output=-1, std::vector< int > const &level_limits=std::vector< int >(), std::string const &checkpoint_filename=std::string())
	Construct a sparse grid surrogate to the model defined by the lambda. More...
template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>
void	TasGrid::constructSurrogate (ModelSignature model, size_t max_num_points, size_t num_parallel_jobs, size_t max_samples_per_job, TasmanianSparseGrid &grid, TypeDepth type, std::vector< int > const &anisotropic_weights=std::vector< int >(), std::vector< int > const &level_limits=std::vector< int >(), std::string const &checkpoint_filename=std::string())
	Construct a sparse grid surrogate to the model defined by the lambda. More...
template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>
void	TasGrid::constructSurrogate (ModelSignature model, size_t max_num_points, size_t num_parallel_jobs, size_t max_samples_per_job, TasmanianSparseGrid &grid, TypeDepth type, int output, std::vector< int > const &level_limits=std::vector< int >(), std::string const &checkpoint_filename=std::string())
	Construct a sparse grid surrogate to the model defined by the lambda. More...

Variables
constexpr bool	TasGrid::mode_parallel = true
	Allows for expressive calls to TasGrid::constructSurrogate().
constexpr bool	TasGrid::mode_sequential = false
	Allows for expressive calls to TasGrid::constructSurrogate().
constexpr bool	TasGrid::with_initial_guess = true
	Allows for expressive calls to TasGrid::constructSurrogate().
constexpr bool	TasGrid::no_initial_guess = false
	Allows for expressive calls to TasGrid::constructSurrogate().

Detailed Description

Templates that perform an automated surrogate construction to a model defined by a lambda expression. This allows for a one-click (or one function call) grid construction where the samples can be computed either sequentially or in parallel. The procedure is carried out until either a target accuracy is reached or a computational budget is exhausted.

Typedef Documentation

ModelSignature

using TasGrid::ModelSignature = typedef std::function<void(std::vector<double> const &x, std::vector<double> &y, size_t thread_id)>

Signature of a model function to be used in the construction procedures.

This types describes an abstract model with inputs, outputs and a specific thread-id.

Parameters

x	is the model inputs, the vector is logically organized in strips each containing a set of model inputs.
y	is the model outputs, the vector must be logically organized in strips each containing a set of model outputs corresponding to a set of inputs (the order must match, first set of inputs to first set outputs and so on). In most cases, y will have the correct size before the call, the exception is when there is insufficient data to compute an initial guess in a context that asks for an initial guess, then y will be empty and must be resized.
thread_id	is a unique identifier of the thread associated with this model call, useful in multi-threaded context e.g., to assign a GPU accelerator to the current call.

The call to TasGrid::constructSurrogate() will control the maximum number of inputs in a single model call, the total number of threads, and whether y will have the correct size and/or contain an initial guess.

Function Documentation

constructSurrogate() [1/3]

template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>

void TasGrid::constructSurrogate	(	ModelSignature	model,
		size_t	max_num_points,
		size_t	num_parallel_jobs,
		size_t	max_samples_per_job,
		TasmanianSparseGrid &	grid,
		double	tolerance,
		TypeRefinement	criteria,
		int	output = -1,
		std::vector< int > const &	level_limits = std::vector<int>(),
		std::string const &	checkpoint_filename = std::string()
	)

Construct a sparse grid surrogate to the model defined by the lambda.

Creates a two way feedback between the model and the grid, samples from the model are collected and loaded into the grid, while algorithms from the grid propose new samples according to estimated importance. The procedure is carried out until either tolerance is reached, the budget is exhausted, or no more samples satisfy the level limits. If set to parallel mode, the lambda will be called in separate threads concurrently up to the specified maximum number.

Two notable options are the ability to call the model with batches of samples and the ability to assign an initial guess for each sample.

• In some cases, model evaluations can be performed much more efficiently using batches of samples, e.g., by allowing the usage of BLAS level 3 methods (as opposed to level 2), better occupancy on GPU accelerators, or better memory cohesion in sparse linear algebra. For more details, see the work by:
  E. Phipps, M. D'Elia, H. Edwards, M. Hoemmen, J. Hu, Embedded Ensemble Propagation for Improving Performance, Portability, and Scalability of Uncertainty Quantification on Emerging Computational Architectures, SIAM Journal on Scientific Computing, vol. 39, num. 2, pp. C162–C193, 2017.
  M. D'Elia, E. Phipps, A. Rushdi, M. Ebeida, Surrogate-based Ensemble Grouping Strategies for Embedded Sampling-based Uncertainty Quantification, arXiv:1705.02003.
• Some models can utilize (or even require) a good initial guess to perform a simulation, e.g., when using linear or non-linear iterative solvers. As the sparse grid surrogate becomes closer and closer to the model, increasingly better guess can be computes, effectively relying on the model to solve only for the correction between the current sparse grid approximation and the actual model. For more details and examples see the work of:
  D. Galindo, P. Jantsch, C. G. Webster, and G. Zhang, Accelerating Stochastic Collocation Methods for Partial Differential Equations with Random Input Data, SIAM/ASA Journal on Uncertainty Quantification, vol. 4, num. 1, pp. 1111–1137, 2016.

The template can be instantiated in either parallel or single threaded mode, with or without an initial guess feedback, and sampling can be performed in batches or single point. The rest of the parameters control the computational budget and the specifics of the refinement scheme.

Template Parameters

parallel_construction

defines the use of parallel or sequential mode. The variable is of type bool but the constexpr constants TasGrid::mode_parallel and TasGrid::mode_sequential can be used to for more expressive calls.

initial_guess

defines the state of the output vector y when the model is called. If the initial guess is set to true (or TasGrid::with_initial_guess), then the input will be filled with the best guess for y based on the current grid, i.e., the previously computed samples. This mode is useful when the model can benefit from a good initial guess, e.g., when using an iterative solver. If the model cannot use an initial guess, then use false or TasGrid::no_initial_guess to avoid extraneous calls to grid.evaluateBatch().

Parameters

model	defines the input-output relation to be approximated by the surrogate. Entering each call, x will have size equal to an even multiple of the dimension of the gird and will hold the required sample inputs for a set of points; the number of points is controlled by max_samples_per_job. Exiting the call, y must have size equal to the number of samples time the number of outputs and must be loaded the outputs corresponding to x. If running with initial_guess, on entry, y will be either loaded with the best guess based on the previously computed samples or empty which will indicate that there are not enough samples to make even a coarse grid. If running without initial_guess, the vector will always have the correct size, but the values will be unspecified and should be overwritten. If using the parallel mode, thread_id will be a number between 0 and max_num_samples -1, all threads running simultaneously will be given a different thread id.
max_num_points	defines the computational budget for the surrogate construction. The construction procedure will terminate after the grid has reached the maximum number of points.
num_parallel_jobs	defined the maximum number of concurent thread executing different calls to the model. In sequential mode, i.e., when parallel_construction is false, this number will loosely control the frequency of recalculating the list of candidate "most important" samples. If set to 0, it will be used as if set to 1.
max_samples_per_job	defines the largest number of samples per call to model. In some cases, outputs can be more efficiently computed when the samples are lumped together. If the model evaluations are not oprimized for batching then this can be simply set to one. If set to 0, it will be used as if set to 1.
grid	is the resulting surrogate model. The grid must be initialized with the appropriate type, number of dimensions, number of outputs, and sufficiently large number of initial points (e.g., there are enough candidates to load all threads). This template works with local polynomial grids.
tolerance	defines the target tolerance, identical to TasmanianSparseGrid::setSurplusRefinement().
criteria	defines the refinement algorithm, identical to TasmanianSparseGrid::setSurplusRefinement().
output	defines the output to use in the algorithm, identical to TasmanianSparseGrid::setSurplusRefinement().
level_limits	defines the maximum level to use in each direction, identical to TasmanianSparseGrid::setSurplusRefinement(). If level limits are already set in the construction and/or refinement those weights will be used, this parameter can overwrite them.
checkpoint_filename	defines the two filenames to be used in to store the intermediate constructed grids so that the procedure can be restarted in case of a system crash. If the filename is "foo" then the files will be called "foo" and "foo_old". No intermediate saves will be made if the string is empty. If the string is not empty, the procedure will first attempt to recover from "foo" and "foo_old".

WARNING: if the checkpoint files contain data from an older runs, the files must be deleted to avoid recovering from the old executing.

Exceptions

std::runtime_error

if called for a grid that is not local polynomial.

Example

Constructing a surrogate to a simple exponential function with budget of 100 points and running on 4 threads with one sample per thread:

auto grid = TasGrid::makeLocalPolynomialGrid(2, ..); // sync the dimensions with number of model inputs
TasGrid::constructSurrogate([&](std::vector<double> const &x, std::vector<double> &y)
                            ->void{ y[0] = std::exp(x[0] + x[1]); },
                            100, 4, 1, grid, 1.E-6, TasGrid::refine_classic);

The procedure will terminate after 100 samples or after the tolerance of 1.E-6 has been reached.

Checkpoint Restart

Large scale simulations that take long time to complete, run a significant risk of system failure which can waste significant computing resources. Checkpoint-restart is a technique to periodically save the computed result and, in case of a crash, restart from the last saved point. For example, suppose the following call crashes mid-way:

// original call
TasGrid::TasmanianSparseGrid grid = TasGrid::makeLocalPolynomialGrid(...);
constructSurrogate(model, budget, num_parallel, grid, 1.E-6, TasGrid::refine_classic, -1,
                   std::vector<int>(), std::vector<double>(), "foo");

After the crash, Tasmanian will attempt to recover the computed samples from files "foo" and "foo_old", if the files don't exist or do not contain valid recovery data, the procedure will restart from scratch. However, if the files were saved successfully the procedure will restart mid-way and samples will not have to be recomputed.

constructSurrogate() [2/3]

template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>

void TasGrid::constructSurrogate	(	ModelSignature	model,
		size_t	max_num_points,
		size_t	num_parallel_jobs,
		size_t	max_samples_per_job,
		TasmanianSparseGrid &	grid,
		TypeDepth	type,
		std::vector< int > const &	anisotropic_weights = std::vector<int>(),
		std::vector< int > const &	level_limits = std::vector<int>(),
		std::string const &	checkpoint_filename = std::string()
	)

Construct a sparse grid surrogate to the model defined by the lambda.

Uses the user provided anisotropic_weights to order the samples by importance and calles the anisotropic overload of TasmanianSparseGrid::getCandidateConstructionPoints(). Otherwise the function is identical to TasGrid::constructSurrogate().

WARNING: anisotropic refinement does not target a tolerance, thus sampling will continue until the budget is exhausted or the level limits are reached (which will produce a full tensor grid).

constructSurrogate() [3/3]

template<bool parallel_construction = TasGrid::mode_parallel, bool initial_guess = no_initial_guess>

void TasGrid::constructSurrogate	(	ModelSignature	model,
		size_t	max_num_points,
		size_t	num_parallel_jobs,
		size_t	max_samples_per_job,
		TasmanianSparseGrid &	grid,
		TypeDepth	type,
		int	output,
		std::vector< int > const &	level_limits = std::vector<int>(),
		std::string const &	checkpoint_filename = std::string()
	)

Construct a sparse grid surrogate to the model defined by the lambda.

Uses anisotropic weights to order the samples by importance, starts with a fully isotropic grid until enough points are loaded to allow to estimate the weights. The procedure uses the anisotropic overload of TasmanianSparseGrid::getCandidateConstructionPoints(), otherwise the function is identical to TasGrid::constructSurrogate().

WARNING: anisotropic refinement does not target a tolerance, thus sampling will continue until the budget is exhausted or the level limits are reached (which will produce a full tensor grid).