Difference between revisions of "OoDACE:ooDACE toolbox"

From SUMOwiki
Jump to navigationJump to search
(New page: == blindDACE: A versatile kriging Matlab Toolbox == From the [http://fann.sf.net FANN website]: ''Fast Artificial Neural Network Library is a free open source neural network library, whi...)
 
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== blindDACE: A versatile kriging Matlab Toolbox ==
+
== Introduction ==
 +
[[Image:ooDACE.png|250 px|right|ooDACE Toolbox]]
  
From the [http://fann.sf.net FANN website]:
+
The ooDACE toolbox is a versatile Matlab toolbox that implements 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.
  
''Fast Artificial Neural Network Library is a free open source neural network library, which implements multilayer artificial neural networks in C with support for both fully connected and sparsely connected networks. Cross-platform execution in both fixed and floating point are supported. It includes a framework for easy handling of training data sets. It is easy to use, versatile, well documented, and fast. PHP, C++, .NET, Ada, Python, Delphi, Octave, Ruby, Prolog Pure Data and Mathematica bindings are available. A reference manual accompanies the library with examples and recommendations on how to use the library. A graphical user interface is also available for the library.''
+
The toolbox is aimed for solving complex applications (expensive simulation codes, physical experiments, ...) and for researching new kriging extensions and techniques.
  
== FANN Matlab bindings ==
+
== Download ==
  
The Matlab Neural Network toolbox is a great piece of software but unfortunately much too slow. Therefore I decided to add the FANN library as an optional backend. Unfortunately there were no Matlab bindings available so I quickly hacked some together. I'd never written Mex files before and my C skills are very rusty to say the least so I thought it would be a good exercise. I'm putting them online in the hope somebody will pick them up and improve/extend them (since they are pretty basic).
+
See: [http://sumo.intec.ugent.be/?q=ooDACE download page]
  
Note that I am only interested in regression (function approximation) so my bindings only reflect that tiny subset of the total FANN features.
+
== Quick start guide ==
  
== Download ==
+
'''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">
 +
startup
 +
</source>
 +
 
 +
Now the toolbox is ready to be used. The ooDACE 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.
  
'''Use these bindings at your own risk! They work for me but don't expect me to guarantee anything!'''
+
<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)
  
License: GPL v2 or later
+
As of version 0.2 of the ooDACE toolbox a script is provided, oodacefit, 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.
  
Download: [[Media:fann-matlab-bindings-1.0.zip]]
+
For more flexibility the full example code to fit the dataset is:
 +
<source lang="matlab">
 +
...
 +
% Generate kriging options structure
 +
opts = getDefaultOptions();
 +
opts.hpBounds = [lb ; ub]; % hyperparameter optimization bounds
  
== Installation ==
+
% configure the optimization algorithm (only one optimizer is included)
 +
% the Matlab Optimization toolbox is REQUIRED
 +
optimopts.GradObj = 'on';
 +
optimopts.DerivativeCheck = 'off';
 +
optimopts.Diagnostics = 'off';
 +
optimopts.Algorithm = 'active-set';
 +
opts.hpOptimizer = MatlabOptimizer( dim, 1, optimopts );
  
Version of the FANN library required: 2.1beta
+
% build and fit Kriging object
 +
k = Kriging( opts, theta0, 'regpoly0', @corrgauss );
 +
k = k.fit( samples, values );
  
Enclosed is a GNU makefile that builds the mex files (you may have to edit the makefile a little to accommodate for your environment). If anybody is willing to contribute windows binaries or Makefiles please do!
+
% k represents the approximation and can now be used, e.g.,
 +
[y mse] = k.predict( [1 2] )
 +
...
 +
</source>
  
Make sure the mex files are in your Matlab path and Matlab knows where to find the FANN library (e.g., see LD_LIBRARY_PATH on unix systems).
+
See the included demo.m script for more example code on how to use the ooDACE 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.
  
== Usage ==
+
== DACE toolbox interface ==
  
* Create a network
+
The ooDACE toolbox provides two scripts dacefit.m and predictor.m that emulate the behavior of the DACE toolbox ([http://www2.imm.dtu.dk/~hbn/dace/]). Note, that full compatibility between ooDACE and the DACE toolbox is not provided. The scripts merely aim to ease the transition from the DACE toolbox to the ooDACE toolbox.
<code><pre>ann = createFann([2 5 3 1],connectivity)</pre></code>
 
* Train a network
 
<code><pre>ann = trainFann(ann,samples,values,[desired error],[max epochs])</pre></code>
 
* Use a network
 
<code><pre>values = testFann(ann,samples)</pre></code>
 
  
Where samples are the input data points and values the output values, both in column format (1 column per dimension).
+
Example code:
 +
<source lang="matlab">
 +
krige = dacefit(samples, values, 'regpoly0', 'corrgauss', theta0, lb, ub )
 +
y = predictor([1 2], krige)
 +
</source>
  
'''Note: do not use a connectivity different from 1 for else you will get wrong results''' (I hope this can be fixed with the new fann library)
+
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 ooDACE and use it instead.
  
 
== Contribute ==
 
== Contribute ==
  
These bindings are very basic but they work for me. Please improve, extend, provide binaries, and of course contribute back.
+
Suggestions on how to improve the ooDACE toolbox are always welcome. For more information please see the [[Feedback | feedback]] page.

Latest revision as of 11:32, 26 March 2012

Introduction

ooDACE Toolbox

The ooDACE toolbox is a versatile Matlab toolbox that implements 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

See: download page

Quick start guide

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.

startup

Now the toolbox is ready to be used. The ooDACE 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 wrapper scripts for more information).

Assume you want to fit a dataset of n samples in d dimensions.

samples holds the input parameters n-by-d array (each row is one observation) and values is the corresponding n-by-1 array containing the output values. lb and ub are 1-by-d arrays defining the lower bounds and upper bounds, respectively, needed to optimize the hyperparameters (theta). In addition, a set of starting values for theta has to be specified (i.e., theta0 is also an 1-by-d array)

As of version 0.2 of the ooDACE toolbox a script is provided, oodacefit, that just takes your dataset (a samples and values matrix) and returns a fitted kriging object, all other parameters (theta0, etc.) are set to some sensible defaults.

For more flexibility the full example code to fit the dataset is:

...
% Generate kriging options structure
opts = getDefaultOptions();
opts.hpBounds = [lb ; ub]; % hyperparameter optimization bounds

% configure the optimization algorithm (only one optimizer is included)
% the Matlab Optimization toolbox is REQUIRED
optimopts.GradObj = 'on';
optimopts.DerivativeCheck = 'off';
optimopts.Diagnostics = 'off';
optimopts.Algorithm = 'active-set';
opts.hpOptimizer = MatlabOptimizer( dim, 1, optimopts );

% build and fit Kriging object
k = Kriging( opts, theta0, 'regpoly0', @corrgauss );
k = k.fit( samples, values );

% k represents the approximation and can now be used, e.g.,
[y mse] = k.predict( [1 2] )
...

See the included demo.m script for more example code on how to use the ooDACE 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.

DACE toolbox interface

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

Example code:

krige = dacefit(samples, values, 'regpoly0', 'corrgauss', theta0, lb, ub )
y = predictor([1 2], krige)

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 ooDACE and use it instead.

Contribute

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