Running

Getting started

If you are just getting started with the toolbox and you have no idea how everything works, do the following:

1. Go through the presentation available here, paying specific attention to the control flow
2. Read through as much documentation on the wiki as you can
3. Print out default.xml (in the config directory) and take your time to read it through and understand the structure and the way things work. This is very important.
4. If you are unfamiliar with XML, its best to go through a quick tutorial first, though its really quite easy.
5. Do a default run (see next section) and understand what is going on.
6. Change default.xml to run a different example. If you can do that you should have mastered all the basic skills needed to use the toolbox.

If you get stuck or have any problems you can contact us.

We are well aware that documentation is not always complete and possibly even out of date in some cases. We try to document everything as best we can but much is limited by available time and manpower. We are are a university research group after all. The most up to date documentation can always be found (if not here) in the default.xml configuration file and, of course, in the source files.

Example run

Once the SUMO Toolbox is installed you can do a simple test run to check if everything is working as expected. See the installation page for more information.

Running different examples

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 config/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 default.xml then simply run 'go' to run the example (making sure that the toolbox is in your Matlab path of course).

Always make sure that the example you use matches the selected sample evaluator (SampleEvaluator tag). For example, its no use running an example that is implemented as a static dataset using the 'matlab' or 'local' sample evaluators. Doing this will result in an error. In this case you should use 'scatteredDataset'. See also Toolbox configuration#Structure.

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.

Note: the default configuration file is <SUMO-Toolbox-installation-dir>/config/default.xml.

Running optimization examples

The SUMO toolbox can also be used for minimizing the simulator in an intelligent way. There are 2 examples in included in config/Optimization. To run these examples is exactly the same as always, e.g. go('config/optimization/Branin.xml'). The only difference is in the sample selector which is specified in the configuration file itself.

• 

The example configuration files are well documented, it is advised to go through them for more detailed information.

Modeling complex outputs

If you do not specify any specific <Output> tags, all outputs will be modeled with complexHandling set to 'complex'. This means that a real output will be modeled as a real value, and a complex output will be modeled as a complex value (with a real and imaginary part). 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', 'real' or 'imaginary'. More information on this subject can be found at the Outputs page.

Debugging

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

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

version 5.0

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

By default it is set to INFO.

version 6.0

Change the level of the ConsoleHandler tag to FINE, FINER or FINEST.

<!-- Configure ConsoleHandler instances -->
<ConsoleHandler>
	<Option key="Level" value="FINE"/>
</ConsoleHandler>

Output

All output is stored under the directory specified in the Config:ContextConfig section of the configuration file (by default this is set to "output").

After completion of a SUMO Toolbox run, the following files and directories can be found there (e.g. : in output/<run_name+date+time>/ subdirectory) :

• 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 run (see the Random state page).
• samples.txt: a list of all the samples that were evaluated, and their outputs.
• profilers-dir: contains information and plots about convergence rates, resource usage, and so on.
• best-dir: contains the best models (+ plots) of all outputs that were constructed during the run. This is continuously updated as the modeling progresses.
• models_outputName-dir: contains a history of all intermediate models (+ plots + movie) for each output that was modeled.

Loading a saved model from disk

As the SUMO Toolbox builds models, each current best model is stored as a Matlab mat file in the output directory (e.g.: output/Academic_2D_Twice_rep01_run00_2008.05.20_10-27-18/models_out/model_0002.mat).

In order to load this model from disk and actually use it, do the following:

• Start Matlab, make sure the SUMO 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. See the Using a model page.

Model portability

The other person has the SUMO Toolbox installed

The model 'mat' files can be 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 SUMO 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 SUMO Toolbox version as was used to create the model file (preferably equal)

The other person does NOT have the SUMO Toolbox installed

In this case you can use the getExpression and exportToMFile (from v6.0) methods. See Using a model.

Tips

See the Tips page for various tips and gotchas.

Interfacing with the SUMO Toolbox

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