Running

Default run

Once the toolbox is installed you can run the default modeling experiment as follows:

1. Make sure that you are in the toolbox root directory and you have run 'startup.m' (see above)
2. Type 'go' and press enter.
3. The toolbox will start to model the Academic2DTwice simulator. This simulator has 2 inputs and 2 outputs, and will be modeled using Rational functions, scored using crossvalidation, and samples selected using the gradient sample selection method.
4. To see the exact settings used open config/default.xml. Feel free to edit this file and play around with the different options.

Running different examples

Global surrogate modeling

The examples directory contains many example simulators that you can use to test the toolbox with. These examples range from predefined functions, to datasets from various domains, to native simulation code. If you want to try one of the examples, open default.xml and edit the Simulator tag to suit your needs.

See the configuration section on information about the possible options. If you want to add your own example see Adding an example.

If you have updated defaul.xml then simply run 'go' to run the example (making sure that the toolbox is in your Matlab path of course).

Other usages of 'go' are as follows:

	"go"
     	"go('MyConfigFile.xml')"
     	"go('MyConfigFile.xml',xValues, yValues)"
     	"go('MyConfigFile.xml',xValues, yValues, options)"
  
     With options a cell array containing one or more of:
     	"-merge" : merge MyConfigFile.xml with the default configuration
		   Note: the merging process does not support all possible cases,
		         in case of problems, do not specify the "-merge" parameter.

     NB: the default configuraiton file is /path/to/M3/config/default.xml

Surrogate driven optimization

Since version 4.0 the toolbox contains a proof of principle implementation of a Surrogate driven optimization framework. See the Surrogate driven optimization page for more information.

Modeling Complex Outputs

If you do not specify any specific <Output> tags, all outputs will be modeled with complexHandling set to 'complex' This will mean that a real output will be modeled as is and a complex output will be modeled directly. If you don't want this (i.e., you want to model the modulus of a complex output or you want to model real and imaginary parts separately), you explicitly have to set complexHandling to 'modulus' or 'real'. More information on this subject can be found at the Outputs page.

Debugging

To aid understanding and debugging you should set the console logging handler to FINE (or even FINER, FINEST) as follows: (by default it is set to INFO)

<Option key="java.util.logging.ConsoleHandler.level" value="FINE"/>

Remember to always check the log file first! When reporting problems please attach your log file and the xml configuration file you used.

Output

Output is stored in the directory specified in the ContextConfig section of the configuration file (by default this is set to "output"). After completion of a M3-Toolbox run, the following files and directories can be found there:

• config.xml: The xml file that was used by this run. Can be used to reproduce the entire modeling process for that run.
• randstate.dat: contains states of the random number generators, so that it becomes possible to deterministically repeat a modeling loop.
• samples.txt: a list of all the samples that were evaluated and their outputs.
• profilers: contains information and plots about convergence rates, resource usage, and so on.
• best: contains the best models that were constructed during the run and also contains plots of these models. Is continuously updated as the modeling progresses.
• models_outputname: contains a history of all the models and plots for each output that was modelled.

Loading a saved model from disk

As the M3-Toolbox builds models, each current best model is stored as a matlab mat file in the output directory (eg: output/model_0002.mat). In order to load this model from disk and actually use it, do the following:

• Start matlab, make sure the M3-Toolbox is in your path and navigate to the directory where the model file is stored
• Load the model from disk as follows:
  • >> modelFile = load('model_0002.mat');
  • >> model = modelFile.model;

Now the model is available as the variable 'model' in the matlab workspace

As a further tip, say you want to optimize the model. In this case Matlab requires a function handle to the objective function (=the model object). You can construct a function handle from the model object as follows (example for the 3D case):

handle = @(x,y,z) evaluate( model, [x,y,z] );

Afterwards, you can pass that handle to your optimization procedure, or use it through feval:

fmincon( handle, ... ); feval( handle, 0, 1, -1 );

Available methods

Once the model is loaded you can invoke a number methods on it.

>> plotModel(model,[outputName],[outputNumber],[axisLabels],[options])

This plots the model

• ouputName: optional parameter, a string with the name of the output
• outputNumber: optional parameter, an integer specifying which output to plot
• axisLables: optional parameter, a cell array with strings labels, one for each axis
• options: optional parameter, a cell array with options, valid options are: '-nocontour', '-grayscale', '-nosamples'

(see also Model types explained)

>> values = evaluate(model, samples);

This evaluates the model on the given samples

>> samples = getSamples(model);

Returns the samples that were used to fit the model

>> values = getValues(model);

Returns the values that correspond to the samples from getSamples()

>> desc = getDescription(model);

Returns a string with a user friendly description of the model.

>> n = freeParams(model);

Returns the number of free parameters in the model

>> fields(model);

Returns all fields the object has

Portability

The model mat files can shared with other people. In order for somebody else to use your saved model the following conditions need to be satisfied:

• The person has the M3-Toolbox in his Matlab path
• The person should be using a similar Matlab version as was used to create the model file (preferably equal)
• The person should be using a similar toolobx version as was used to create the model file (preferably equal)

Tips

See the Tips page for various tips and gotchas.

Interfacing with the toolbox

To learn how to interface with the toolbox see the Adding an example and Data format pages.

Memory

See the Tips page on dealing with memory problems.

Miscellaneous scripts

See the Sun NG1 page for utility scripts for distributing the differnt runs.