Difference between revisions of "Installation"

Latest revision as of 08:27, 28 August 2014

Introduction

This page will walk you through the SUMO Toolbox installation. Please refer to the system requirements first. See the downloading section on how to download the toolbox.

Quick start

Quick and dirty instructions:

Log into the SUMO lab website with the account information mailed to you and download the toolbox
Unzip the toolbox zip file, it will create a directory (= the toolbox installation directory)
Start Matlab
Go to the toolbox directory
Run 'startup'
Run 'go'

Basic Installation

Toolbox

Unzip the toolbox zip file to a directory somewhere on your harddisk, the full path of the SUMO Toolbox (including installation directory) will be referred to as the toolbox installation directory (e.g., c:\software\SUMO-Toolbox-6.3). Note that you do not have to put the toolbox in the Matlab installation directory, we actually advise against it since it can cause confusing errors.

Once you have unzipped the toolbox zip file the directory structure looks like this:

<toolbox installation directory> (e.g., c:\software\SUMO-Toolbox-6.3)
- bin/ : binaries, executable scripts, ...
- config/ : configuration files, location of default.xml
- config/demo : a couple of demo configuration files that may help you
- doc/ : some documentation
- doc/apidoc : Javadoc and other api docs
- lib/ : required libraries (eg: dom4j)
- output/ : some output may be placed here (e.g., a global log file)
- src/ : all source code
- examples/ : project directories of different examples (you can test with these problems and use them as an example to add your own)

Setup

Setting up the toolbox is very easy. Start Matlab, navigate to the toolbox installation directory (not anywhere else, this is important!!) and run 'startup'.

Test run

To ensure everything is working you can do a simple run of the toolbox with the default configuration. This means the toolbox will use the setting specified in <SUMO-Toolbox-installation-dir>/config/default.xml.

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

The examples directory contains many example simulators that you can use to test the toolbox with. See Running#Running_different_examples.

Ok, the test run works, now what?

See Running page.

Problems

See the reporting problems page.

Optional: Compiling libraries

There are some alternative libraries and simulators available that have to be compiled for your specific platform. Instructions depend on your operating system.

Linux/Unix/OSX

Ensure you have the following environment variables set:
1. MATLABDIR=/path/to/your/matlab/installation
2. JAVA_HOME=/path/to/your/SDK/installation
Ensure you have the usual build tools installed: gcc, g++, autotools, make, etc
From the command line shell (so NOT from inside Matlab): Go to the toolbox installation directory and type 'make'. This will build everything for you (C/C++ files, SVM libraries, ...). If you only want to build certain packages simply 'make Package' in the toolbox installation directory.
1. For Matlab versions R2011a and above, in case your operating system is Mac OS X (version 10.6 - Snow Leopard upwards), and the C compiler being used is Xcode version 4.1 and above, you will need to install a patch from MathWorks, please refer to this. You will also need to update the SDKROOT entry in mexopts.sh file (usually located in ~/.matlab/R2012b/mexopts.sh), according to its location in the filesystem as it has been moved in recent versions of OS X. For example, for OS X Lion the updated entry should be,
  1. SDKROOT='/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk/'
  2. It is also advisable to change the entry for CC from gcc-4.2 to just gcc.
2. If you encounter the message "This process is attempting to exclude an item from Time Machine by path without administrator privileges. This is not supported." on Mac OS X while building the code, building it as a super-user by using the command 'sudo make' instead of only 'make' will solve the problem.
A complete list of available packages follows:

Package	Description
contrib	Builds the FANN, SVM (libsvm) and NNSYSID libraries
cexamples	Builds the binaries for several C/C++ simulators

Note: if you want to use FANN you will have to ensure Matlab knows of the FANN libraries. See the FAQ.

Windows

Compiling C/C++ codes (examples):
1. You will have to do this on your own using a C/C++ compiler of your choice: Dev-c++/Visual Studio/...
Compiling LS-SVM libraries:
1. In order to use the LS-SVM backend, you will have to compile the LS-SVM mex files (it will work if you dont but you will get a lot of warning messages about a missing CFile implementation).
2. This can be done using the built-in LCC compiler of matlab, by calling 'makeLSSVM' from the Matlab command prompt (make sure the SUMO Toolbox is in your path)
Compiling ANN libraries:
1. In order to use the FANN backend, you will have to compile the FANN library and mex files.
2. So far nobody has yet got it to work under Windows, but don't let that stop you.
Compiling Java classes using Eclipse (only for SVN version of the Toolbox, on linux you can just use the make command)
1. open Eclipse
2. import ant buildfile
  1. File->New->Other
  2. Java->Java Project from Existing Ant Buildfile
  3. Select build.xml in the SUMO root directory
  4. click 'Finish'
  5. Add external jars from Matlab install to buildpath if necessary
3. Open configure.m in the SUMO root directory and change bin/ to src/ for the java paths (the lines below % add java paths)
4. Type in 'go' in the Matlab command line to see whether the compilation worked
5. If the SUMO Toolbox does not start, make sure the java virtual machine of matlab and eclipse are the same
  1. Type in 'version('-java')' in the Matlab command line to find the jvm version used by matlab
  2. In Eclipse, right click the SUMO-Toolbox project -> Properties -> Java Compiler
  3. Change the Java Compiler used by Eclipse by ticking the 'Enable project specific settings' and selecting the same version of the Java Compiler as the Matlab jvm

@@ Line 1: / Line 1: @@
 == Introduction ==
-This page will walk you through the toolbox installation.  Please refer to the [[system requirements]] first. See the [[downloading]] section on how to download the toolbox.
+This page will walk you through the SUMO Toolbox installation. Please refer to the [[system requirements]] first. See the [[downloading]] section on how to download the toolbox.
+== Quick start ==
+Quick and dirty instructions:
+# Log into the SUMO lab website with the account information mailed to you and download the toolbox
+# Unzip the toolbox zip file, it will create a directory (= the toolbox installation directory)
+<!-- # Unzip the activation zip file '''INTO the toolbox installation directory''' (this file was mailed to you after you registered) -->
+# Start Matlab
+# Go to the toolbox directory
+# Run '<code>startup</code>'
+# Run '<code>go</code>'
 == Basic Installation ==
 === Toolbox ===
-Unzip the toolbox zip file to a directory somewhere on your harddisk, the full path of the SUMO toolbox (including installation directory) will be referred to as the toolbox root directory.
+Unzip the toolbox zip file to a directory somewhere on your harddisk, the full path of the SUMO Toolbox (including installation directory) will be referred to as the toolbox installation directory (e.g., c:\software\SUMO-Toolbox-6.3).  Note that you do '''not''' have to put the toolbox in the Matlab installation directory, we actually advise against it since it can cause confusing errors.
-* <installation directory>
+Once you have unzipped the toolbox zip file the directory structure looks like this:
-** bin/			: binaries, executable scripts, ...
-** config/		: configuration files, location of default.xml
+* <code><toolbox installation directory> ''(e.g., c:\software\SUMO-Toolbox-6.3)''</code>
-** doc/ 		: some documentation
+** <code>bin/</code>			: binaries, executable scripts, ...
-** doc/apidoc 		: Javadoc and other api docs
+** <code>config/</code>			: configuration files, location of <code>default.xml</code>
-** lib/ 		: required libraries (eg: dom4j)
+** <code>config/demo</code>		: a couple of demo configuration files that may help you
-** output/		: all output will be placed here, including your logfile
+** <code>doc/</code> 			: some documentation
-** src/			: all source code
+** <code>doc/apidoc</code> 		: Javadoc and other api docs
-** src/c		: C/C++ code for example simulators
+** <code>lib/</code> 			: required libraries (eg: dom4j)
-** src/matlab/examples	: matlab example simulator scripts
+** <code>output/</code>			: some output may be placed here (e.g., a global log file)
-** examples/            : example simulator xml files (you can test with these problems)
+** <code>src/</code>			: all source code
+** <code>examples/</code>		: project directories of different examples (you can test with these problems and use them as an example to [[Adding an example|add your own]])
+<!--
+=== Activation file ===
+Once you have received the activation file simply unzip it '''INTO''' in your toolbox installation directory.  So place the zip file in the toolbox installation directory and unzip it there, it should place all files in the correct places (see also the README file in the activation zip).  DO NOT unzip the activation file into its own directory somewhere else. Make sure you restart Matlab (if it was running) after you have done this.
 === Extension pack ===
-To install the extension pack, download the zip file, and unzip it in your toolbox root directory. The files should be placed in the correct directories.
+There are a number of third party tools and modeling libraries that the SUMO Toolbox can use but that we cannot distribute together with the toolbox. These have been bundled in an extension pack.  Only minor patches have been made to the original code to make them work better with SUMO (e.g., remove debug output).  To install the extension pack, download the zip file, and unzip it INTO your toolbox installation directory. The files should be placed in the correct directories.  Simply re-run 'startup' to make Matlab aware of the new files.
-== Optional: Installation from Source ==
+If you download and/or use these files  please respect their licenses (found in doc/licenses), '''THIS IS YOUR RESPONSIBILITY !!!'''.
+-->
+=== Setup ===
-For a minimal system you will have to compile at least the java files, if you start from the source files. Instructions depend on your operating system.
+Setting up the toolbox is very easy.  Start Matlab, navigate to the toolbox installation directory (not anywhere else, this is important!!) and run '<code>startup</code>'.
-(Note that all java files are already compiled in the toolbox zip file.)
-=== Linux/Unix/OSX ===
+=== Test run ===
-# Ensure you have the following environment variables set:
+To ensure everything is working you can do a simple run of the toolbox with the default configuration. This means the toolbox will use the setting specified in <code><SUMO-Toolbox-installation-dir>/config/default.xml</code>.
-## MATLABDIR=/path/to/your/matlab/installation
-## JAVA_HOME=/path/to/your/SDK/installation
-# Go to toolbox root directory and type 'make'. This will build everything for you (java files, C/C++ files, SVM libraries, binaries for the txt datasets, ...).  If you only want to build the java stuff simply 'make java' (or run 'ant') in the toolbox root.
-=== Windows ===
+# Make sure that you are in the toolbox installation directory and you have run '<code>startup</code>' (see above)
+# Type '<code>go</code>' and press enter.
+# The toolbox will start to model the ''Academic2DTwice'' simulator.  This simulator has 2 inputs and 2 outputs, and will be modeled using Kriging models, scored using [[Measures#CrossValidation| CrossValidation]], and samples selected using a combined sample selection method.
+# To see the exact settings used open <code>config/default.xml</code>.  Feel free to edit this file and play around with the different options.
-# Compiling java:
+The examples directory contains many example simulators that you can use to test the toolbox with.  See [[Running#Running_different_examples]].
-## it is advised you do this using [http://www.eclipse.org Eclipse]. Run Eclipse, and import the build.xml file.
-## Set the output directory to <SUMO-toolbox-installation-dir>/bin/java (see project->properties->Build Path). Once this is done eclipse will automatically compile the java files for you and place them into the right directory.
-Note: if you get errors about a missing jmi.jar, you can find this jar file in <your matlab directory>/java/jar
+== Ok, the test run works, now what? ==
-# Compiling C/C++ codes (examples):
-## You will have to do this on your own using a C/C++ compiler of your choice: Dev-c++/Visual Studio/...
-# Compiling SVM libraries:
-## In order to use the [http://www.esat.kuleuven.be/sista/lssvmlab/ LS-SVM] backend, you will have to compile the LS-SVM mex files (it will work if you dont but you will get a lot of debug output).
-## This can be done using the built-in LCC compiler of matlab, by calling 'makeLSSVM' from the Matlab command prompt. This will only work if the toolbox is already in the Matlab path. If this is not the case, refer to the Binary Installation section for more information.
-# Compiling ANN libraries:
-## In order to use the [http://leenissen.dk/fann/ FANN] backend, you will have to compile the FANN library and mex files.
-## So far nobody has yet got it to work under Windows, but dont let that stop you.
-== Setup ==
+See [[Running]] page.
-Starting the toolbox is very easy, all you basically have to do is run startup.m in Matlab under the toolbox installation directory.
-=== Linux/Unix ===
+== Problems ==
-Navigate to the toolbox installation directory and start matlab there '''OR''' start matlab, once in matlab navigate to the toolbox installation directory and run 'startup.m'.
-=== Macintosh OSX ===
+See the [[reporting problems]] page.
-Follow the instructions for Windows, although the Linux/Unix instructions will work as well.
-=== Windows ===
+== Optional: Compiling libraries ==
-Start matlab, once in matlab navigate to the toolbox installation directory and run 'startup.m'
-''Side Note:'' if you '''dont''' want to run the toolbox in its own directory you will need to make sure Matlab will be able to find the source files for the toolbox regardless of path. This can be accomplished as follows:
+There are some alternative libraries and simulators available that have to be compiled for your specific platform. Instructions depend on your operating system.
-# Copy startup.m (found in the toolbox root directory), to the work directory of Matlab (e.g.: C:\Program files\MATLAB\R2007a\work)
+=== Linux/Unix/OSX ===
-# Open startup.m (This file will be executed automatically whenever Matlab boots)
-# Edit the path so that it points to the toolbox root directory (i.e., where you unzipped the toolbox).
-# Reboot Matlab.
-== Test run ==
+# Ensure you have the following environment variables set:
+## <code>MATLABDIR=/path/to/your/matlab/installation</code>
+## <code>JAVA_HOME=/path/to/your/SDK/installation</code>
+# Ensure you have the usual build tools installed: gcc, g++, autotools, make, etc
+# From the command line shell (so NOT from inside Matlab): Go to the toolbox installation directory and type '<code>make</code>'. This will build everything for you (C/C++ files, SVM libraries, ...).  If you only want to build certain packages simply '<code>make Package</code>' in the toolbox installation directory.
+## For Matlab versions R2011a and above, in case your operating system is Mac OS X (version 10.6 - Snow Leopard upwards), and the C compiler being used is Xcode version 4.1 and above, you will need to install a patch from MathWorks, please refer to [http://www.mathworks.nl/support/solutions/en/data/1-FR6LXJ/ this]. You will also need to update the SDKROOT entry in mexopts.sh file (usually located in ~/.matlab/R2012b/mexopts.sh), according to its location in the filesystem as it has been moved in recent versions of OS X. For example, for OS X Lion the updated entry should be,
+###<code>SDKROOT='/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk/'</code>
+### It is also advisable to change the entry for <code>CC</code> from <code>gcc-4.2</code> to just <code>gcc</code>.
+## If you encounter the message "This process is attempting to exclude an item from Time Machine by path without administrator privileges. This is not supported." on Mac OS X while building the code, building it as a super-user by using the command '<code>sudo make</code>' instead of only '<code>make</code>' will solve the problem.
+# A complete list of available packages follows:
-# Make sure that you are in the toolbox root directory and you have run 'startup.m' (see above)
+{| style="margin: 1em auto 1em auto" border="1"
-# Type 'go' and press enter.
+|-
-# 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.
+! Package
-# To see the exact settings used open config/default.xml.  Feel free to edit this file and play around with the different options.
+! Description
+|-
+| contrib
+| Builds the FANN, SVM (libsvm) and NNSYSID libraries
+|-
+| cexamples
+| Builds the binaries for several C/C++ simulators
+|}
-The examples directory contains many example simulators that you can use to test the toolbox with.  See the [[configuration]] section on information about the possible options.
+Note: if you want to use FANN you will have to ensure Matlab knows of the FANN libraries. See [[FAQ#When_using_FANN_models_I_sometimes_get_.22Invalid_MEX-file_createFann.mexa64.2C_libfann.so.2:_cannot_open_shared_object_file:_No_such_file_or_directory..22 | the FAQ]].
-== Problems ==
+=== Windows ===
-See the [[reporting problems]] page.
+# Compiling C/C++ codes (examples):
+## You will have to do this on your own using a C/C++ compiler of your choice: Dev-c++/Visual Studio/...
+# Compiling LS-SVM libraries:
+## In order to use the [http://www.esat.kuleuven.be/sista/lssvmlab/ LS-SVM] backend, you will have to compile the LS-SVM mex files (it will work if you dont but you will get a lot of warning messages about a missing CFile implementation).
+## This can be done using the built-in LCC compiler of matlab, by calling '<code>makeLSSVM</code>' from the Matlab command prompt (make sure the SUMO Toolbox is in your path)
+# Compiling ANN libraries:
+## In order to use the [http://leenissen.dk/fann/ FANN] backend, you will have to compile the FANN library and mex files.
+## So far nobody has yet got it to work under Windows, but don't let that stop you.
+# Compiling Java classes using Eclipse (only for SVN version of the Toolbox, on linux you can just use the make command)
+## open Eclipse
+## import ant buildfile
+### File->New->Other
+### Java->Java Project from Existing Ant Buildfile
+### Select build.xml in the SUMO root directory
+### click 'Finish'
+### Add external jars from Matlab install to buildpath if necessary
+## Open configure.m in the SUMO root directory and change bin/ to src/ for the java paths (the lines below ''% add java paths'')
+## Type in 'go' in the Matlab command line to see whether the compilation worked
+## If the SUMO Toolbox does not start, make sure the java virtual machine of matlab and eclipse are the same
+### Type in 'version('-java')' in the Matlab command line to find the jvm version used by matlab
+### In Eclipse, right click the SUMO-Toolbox project -> Properties  -> Java Compiler
+### Change the Java Compiler used by Eclipse by ticking the 'Enable project specific settings' and selecting the same version of the Java Compiler as the Matlab jvm

Difference between revisions of "Installation"

Latest revision as of 08:27, 28 August 2014

Contents

Introduction

Quick start

Basic Installation

Toolbox

Setup

Test run

Ok, the test run works, now what?

Problems

Optional: Compiling libraries

Linux/Unix/OSX

Windows

Navigation menu

Page actions

Page actions

Personal tools

SUMO Toolbox

Support

News

Related links

Tools

Search