Difference between revisions of "SED:SED toolbox"

From SUMOwiki
(Quick start guide)
Line 2: Line 2:
 
[[Image:blindDACE.gif|250 px|right|SED Toolbox]]
 
[[Image:blindDACE.gif|250 px|right|SED Toolbox]]
   
  +
The SED Toolbox (Sequential Experimental Design) is a powerful Matlab toolbox for the sequential design of experiments. In traditional design of experiments, the all the design points are selected at once, and all the experiments are performed at once without selecting any additional design points. This method is prone to over- or undersampling, because it is often very difficult to predict the required number of design points in advance.
The SED toolbox is a versatile Matlab toolbox that implements
 
   
  +
The SED Toolbox solves this problem by providing the user with state-of-the-art algorithms that generate a design of experiments one point at a time, without having to provide the total number of design points in advance. This is called sequential experimental design. The SED Toolbox was designed to be extremely fast and easy to use, yet very powerful.
--TO BE UPDATED--
 
 
the popular Gaussian Process based kriging surrogate models. Kriging is in particular popular for approximating (and optimizing) deterministic computer experiments. Given a dataset the toolbox automatically fits a kriging surrogate model to it. Afterwards the kriging surrogate can be fully exploited instead of the (probably more expensive) simulation code.
 
 
The toolbox is aimed for solving complex applications (expensive simulation codes, physical experiments, ...) and for researching new kriging extensions and techniques.
 
   
 
== Download ==
 
== Download ==
Line 16: Line 12:
 
== Quick start guide ==
 
== Quick start guide ==
   
--TO BE UPDATED--
 
   
  +
'''IMPORTANT''': Before the toolbox can be used, you have to set it up for use, by browsing to the directory in which the toolbox was unpacked and running the startup command:
 
'''IMPORTANT''': Before the toolbox can be used you have to include the toolbox in Matlab's search path. You can do this manually by running startup, or, if Matlab is started in the root toolbox directory, then startup will be run automatically.
 
   
 
<source lang="matlab">
 
<source lang="matlab">
Line 25: Line 19:
 
</source>
 
</source>
   
  +
Now the toolbox is ready to be used. The SED Toolbox can be used in several ways, based on how much freedom you want in configuring and fine-tuning the parameters of the algorithms. We will now describe the three ways the toolbox can be used, in order of complexity, based on your requirements.
Now the toolbox is ready to be used. The blindDACE toolbox is designed in an object oriented (OO) fashion.
 
It is strongly recommended to exploit the OO design directly, i.e., use the Kriging and Optimizer matlab classes.
 
However, for convenience wrapper scripts (dacefit, predictor) are provided that emulate the DACE toolbox interface (see [[#DACE toolbox interface|wrapper scripts]] for more information).
 
   
Assume you want to fit a dataset of n samples in d dimensions.
+
=== You want an ND design of X points ===
   
  +
In order to quickly generate a good ND design in X points, you can use the following code:
<b>samples</b> holds the input parameters n-by-d array (each row is one observation) and <b>values</b> is the corresponding n-by-1 array containing the output values.
 
<b>lb</b> and <b>ub</b> are 1-by-d arrays defining the lower bounds and upper bounds, respectively, needed to optimize the hyperparameters (<b>theta</b>). In addition, a set of starting values for <b>theta</b> has to be specified (i.e., <b>theta0</b> is also an 1-by-d array)
 
   
As of version 0.2 of the blindDACE toolbox a script is provided, blinddacefit, that just takes your dataset (a <b>samples</b> and <b>values</b> matrix) and returns a fitted kriging object, all other parameters (<b>theta0</b>, etc.) are set to some sensible defaults.
 
 
For more flexibility the full example code to fit the dataset is:
 
 
<source lang="matlab">
 
<source lang="matlab">
  +
startup % configure the toolbox
...
 
  +
config.inputs.nInputs = N; % set the number of inputs in the config struct
% Generate kriging options structure
 
  +
generator = SequentialDesign(config); % set up the sequential design
opts = getDefaultOptions();
 
  +
generator = generator.generateTotalPoints(X); % generate a total of X points
opts.hpBounds = [lb ; ub]; % hyperparameter optimization bounds
 
  +
points = generator.getAllPoints(); % return the entire design
   
  +
% optional:
% configure the optimization algorithm (only one optimizer is included)
 
  +
generator.plot(); % plot the design
% the Matlab Optimization toolbox is REQUIRED
 
  +
generator.getMetrics(); % get some metrics about the quality of the design
optimopts.GradObj = 'on';
 
  +
</source>
optimopts.DerivativeCheck = 'off';
 
optimopts.Diagnostics = 'off';
 
optimopts.Algorithm = 'active-set';
 
opts.hpOptimizer = MatlabOptimizer( dim, 1, optimopts );
 
   
  +
=== You want to use the more advanced features of the SED Toolbox ===
% build and fit Kriging object
 
k = Kriging( opts, theta0, 'regpoly0', @corrgauss );
 
k = k.fit( samples, values );
 
   
  +
If you want to use some of the more advanced features of the SED Toolbox, such as input ranges and weights and constraints, you have two options. The first one is to use Matlab structs as in the previous example. The second one is to use simple XML files to configure the toolbox. Note that constraints will only work with XML configuration. You can open the 'problem.xml' file in the SED directory to get an idea of how a problem configuration looks like. You can edit this file to suit your needs and use it to configure the toolbox using the following command:
% k represents the approximation and can now be used, e.g.,
 
  +
[y mse] = k.predict( [1 2] )
 
  +
<source lang="matlab">
...
 
  +
% generate a sequential design for the problem defined in problem.xml:
  +
generator = SequentialDesign('problem.xml');
  +
  +
% generate a sequential design using the specified method for the problem defined in problem.xml:
  +
generator = SequentialDesign('problem.xml', 'methods/mc-intersite-projected-threshold.xml');
 
</source>
 
</source>
   
  +
If you instead prefer to use Matlab structs, you can use the following code to configure the toolbox:
See the included demo.m script for more example code on how to use the blindDACE toolbox (including more advanced features such as using blind kriging or how to use regression instead of interpolation). For more information on the classes and their methods please refer to the source files.
 
  +
  +
<source lang="matlab">
  +
config.inputs.nInputs = 2; % this is a 2D example
  +
config.inputs.minima = [-1 -1]; % define the minimum of each input
  +
config.inputs.maxima = [3 1]; % define the maximum of each input
  +
config.inputs.weights = [2 0]; % the first input is twice as important as the second one
  +
generator = SequentialDesign(config); % set up the sequential design
  +
</source>
   
 
== SED toolbox interface ==
 
== SED toolbox interface ==

Revision as of 16:23, 20 January 2011

Introduction

The SED Toolbox (Sequential Experimental Design) is a powerful Matlab toolbox for the sequential design of experiments. In traditional design of experiments, the all the design points are selected at once, and all the experiments are performed at once without selecting any additional design points. This method is prone to over- or undersampling, because it is often very difficult to predict the required number of design points in advance.

The SED Toolbox solves this problem by providing the user with state-of-the-art algorithms that generate a design of experiments one point at a time, without having to provide the total number of design points in advance. This is called sequential experimental design. The SED Toolbox was designed to be extremely fast and easy to use, yet very powerful.

Download

See: download page

Quick start guide

IMPORTANT: Before the toolbox can be used, you have to set it up for use, by browsing to the directory in which the toolbox was unpacked and running the startup command:

startup

Now the toolbox is ready to be used. The SED Toolbox can be used in several ways, based on how much freedom you want in configuring and fine-tuning the parameters of the algorithms. We will now describe the three ways the toolbox can be used, in order of complexity, based on your requirements.

You want an ND design of X points

In order to quickly generate a good ND design in X points, you can use the following code:

startup % configure the toolbox
% set the number of inputs in the config struct
% set up the sequential design
% generate a total of X points
% return the entire design
 
% optional:
% plot the design
% get some metrics about the quality of the design

You want to use the more advanced features of the SED Toolbox

If you want to use some of the more advanced features of the SED Toolbox, such as input ranges and weights and constraints, you have two options. The first one is to use Matlab structs as in the previous example. The second one is to use simple XML files to configure the toolbox. Note that constraints will only work with XML configuration. You can open the 'problem.xml' file in the SED directory to get an idea of how a problem configuration looks like. You can edit this file to suit your needs and use it to configure the toolbox using the following command:

% generate a sequential design for the problem defined in problem.xml:
% generate a sequential design using the specified method for the problem defined in problem.xml:

If you instead prefer to use Matlab structs, you can use the following code to configure the toolbox:

span class="co1">% this is a 2D example
% define the minimum of each input
% define the maximum of each input
% the first input is twice as important as the second one
% set up the sequential design

SED toolbox interface

The SED toolbox provides

--TO BE UPDATED--

two scripts dacefit.m and predictor.m that emulate the behavior of the DACE toolbox ([1]). Note, that full compatibility between blindDACE and the DACE toolbox is not provided. The scripts merely aim to ease the transition from the DACE toolbox to the blindDACE toolbox.

Example code:

 

Obviously, a lot less code is used to copy the setup described above. However, less code means less flexibility (e.g., blind kriging and regression kriging are not available using the wrapper scripts). Hence, it is suggested to learn the object oriented interface of SED and use it instead.

Contribute

Suggestions on how to improve the SED toolbox are always welcome. For more information please see the feedback page.