Installation

From TomWiki
Revision as of 09:12, 7 December 2011 by Elias (talk | contribs) (→‎Starting TOMLAB)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

This guide describes the installation of the TOMLAB Optimization Environment on the following operating systems: Windows (XP, 2000, XP-64, Vista, 7), Linux (32 and 64-bit), Mac OS X (Intel, Snow Leopard 10.6, 64-bit MATLAB). It is basically the same procedure on all operating systems: Execute the installer, possibly set some environment variables and install the license files.

The first step is to register as a TOMLAB user and download the appropriate distribution. Execute ’ver’ and ’computer’ in MATLAB to find out which version you have.

Make sure the system is supported by TOMLAB in Section requirements, then go to Section download and follow the instruction to obtain a copy of TOMLAB. When the installation file has been downloaded, go to Subsection install for the system in question and follow the instructions. To get some modules of TOMLAB to work, e.g: TOMLAB /CPLEX and TOMLAB /KNITRO, some environment variables may need to be set. How to do this is described in Section environment. The last step is to install the license file(s), which is described in Section license.

Supported platforms

TOMLAB supports the following platforms and MATLAB versions:

  • Windows 32-bit (MATLAB 6.5 and above)
  • Windows 64-bit (MATLAB 7.3 and above)
  • Linux x86 32-bit (MATLAB 7.1 and above)
  • Linux x86 64-bit (MATLAB 7.3 and above)
  • Mac OS X (MATLAB 7.3 and above)

Downloading TOMLAB

In order to download TOMLAB a myTOMLAB account needs to be created at: http://tomopt.com. When a myTOMLAB account exist, login and go to the Download Products section, from where TOMLAB can be downloaded.

Here is a complete list of the files needed:

  • Windows 32-bit,
    • MATLAB ≥ 7.4: tomlab-win32-setup.exe
    • MATLAB 6.x/7.x: tomlab-win32-73-setup.exe
  • Windows 64-bit,
    • MATLAB ≥ 7.3: tomlab-win64-setup.exe
  • Linux
    • MATLAB ≥ 7.4: tomlab-lnx32-gcc41-setup.bin
    • MATLAB 7.1-7.3: tomlab-lnx32-gcc34-setup.bin
  • Linux 64-bit,
    • MATLAB ≥ 7.3: tomlab-lnx64-setup.bin
  • Mac OS X,
    • MATLAB ≥ 7.3: tomlab-osx64-setup.dmg

Installing TOMLAB

This section describes how to install the TOMLAB software. Follow the instructions in the section for your operating system.

Install on Windows

For Windows an installer extracts the TOMLAB files and automatically sets the PATH environment variable to point at directories containing dynamic libraries required by some TOMLAB modules. See Section interactive for more information about the steps.

It is recommended to terminate all instances of MATLAB during the installation to make sure the PATH environment variable is properly set in the MATLAB environment when starting to use TOMLAB. Execute {getenv(’path’)} in MATLAB to confirm the presence of {tomlab/shared}.

As the PATH environment variable is set automatically, one can skip Section environment and go directly to Section license.

If the installer failed to set the PATH environment variable, go to Section environment and read about how to do it manually.

It may be needed to reboot the computer after installation.

Upgrade on Windows

Locate your installation folder. Run the "uninstall_tomlab.exe" utility to remove the TOMLAB installation. Make sure that (only) {tomlab.lic} remains in the installation folder and install the new version in the same location. Files not created by the installer will not be uninstalled. As defaults in TOMLAB may change over time a backup copy of the old version is recommended.

Install on Unix-like systems

The software is installed by a self-extracting executable installer, similar to the one used on Windows systems. The files for each operating system can be found in Section download.

After downloading the installer for your platform and Matlab version, simply execute the tomlab-X-setup.bin file, where X represents your platform and Matlab version. The installer can be run in text mode if no display is available.

Note: Mac OS X users of should always execute {startup.m} when using TOMLAB.

Interactive installation

Execute the installer binary by double clicking it’s icon, or invoke it from a shell:

   [user@host:~] ./tomlab-X-setup.bin

If you are running the installer as a regular user, a warning may be displayed.

image

Currently this warning can be ignored since a manual step (see Setting environment variables environment) is still required to make TOMLAB fully usable.

At the welcome screen, simply press Forward.

image

The TOMLAB license agreement will be displayed. Please read it and mark the "I accept the agreement" if you agree to be bound by it. Press Forward.

image

Enter the directory in which to install TOMLAB. Please note that a ’tomlab’ directory will be added to the path you specify here.

image

The default location for single user installations is in the $HOME directory.

The default location if installing with super-user privileges is in /opt/tomlab (will show as /opt) in the dialogue.

Press Forward after entering the desired path.

At the Component Selection screen, it is safe to leave everything selected. Only deselect packages if you know you need to do so.

Press Forward to proceed.

image

During installation, a progress bar will appear.

image

At the final page, simply press the Finish button to exit the installer.

image

Text mode interactive installation

Execute the installer from the shell.

   [user@host:~]$ ./tomlab-X-setup.bin --mode text

If you are running the installer as a regular user, a warning may be displayed:

 Warning: Setup is not running with administrative privileges.
 This means TOMLAB will be fully usable only by the current user.
 If this is not desired, please abort the installation and rerun
 it as an Administrator Press [Enter] to continue :

Currently this warning can be ignored since a manual step is still required to make TOMLAB fully usable by anyone.

The TOMLAB license agreement will be displayed - press Enter several times to read the agreement and at the question if you accept the license, press "y" if you accept, or "n" otherwise.

   Do you accept this license? [y/n]:

Enter the location where TOMLAB will be installed. Please note that a directory ’tomlab’ will be created in this location, i.e. do not enter a trailing ’tomlab’ dir yourself.

The default location for single user installations is in the $HOME directory.

The default location if installing with super-user privileges is in /opt/tomlab (will show as /opt) in the dialogue.

   Please choose where to install TOMLAB.
   A 'tomlab' directory will be created in this location.
   Installation Directory [/home/user]:

The next questions concern package selection. You can safely leave all packages selected by simply pressing Enter at each prompt.

At the next question, press Y to install TOMLAB:

   Setup is now ready to begin installing TOMLAB Optimization
   Environment on your computer.
   Do you want to continue? [Y/n]: Y

An installation progress bar will be shown during installation. After installation, the installer program will exit.

 ----------------------------------------------------------------
 Please wait while Setup installs TOMLAB Optimization Environment
 on your computer. Installing
 0% ______________ 50% ______________ 100%
 #########################################
 ----------------------------------------------------------------
 Setup has finished installing TOMLAB Optimization Environment on
 your computer.

Unattended installation

TOMLAB can be installed without any user interaction at all. To perform an unattended installation, execute the installer binary with the following options:

   [user@host:~]$ [sudo] ./tomlab-X-setup.bin --mode unattended
   --prefix /path/to/installation_dir

The argument to the –prefix option should not include a trailing /tomlab directory - one will be added automatically.

Upgrade on Unix-like systems

The first step is to save a copy of the license file (and make a backup copy of the old version if needed). Assuming that TOMLAB is installed in {/usr/local/matlab7/tomlab} execute the follow commands:

   $ cd /usr/local/matlab7/tomlab
   $ mv tomlab.lic ../

Then remove the old version:

   $ cd ..
   $ rm -f -r tomlab

Install the new version as described in section install:unix and move back the license:

   $ mv tomlab.lic ./tomlab

Setting environment variables

For Windows TOMLAB requires the directory {tomlab/shared} to be included in the environment variable PATH.

For all other operating systems TOMLAB requires the tomlab/shared folder to be present in the LD_LIBRARY_PATH environment variable before invoking MATLAB (DYLD_LIBRARY_PATH on Mac OS X). It is possible to set this in several ways.

Shared libraries path

The library search path environment variable name differs between different systems. On Linux it is called {LD_LIBRARY_PATH}, while on Mac OS X it is {DYLD_LIBRARY_PATH}. On Windows, it is the {PATH} variable.

The way environment variables are set varies depending on operating systems and shells.

Windows

To set the PATH environment variable permanently on Windows, do: Control Panel System Advanced Environment Variables. Assuming TOMLAB was installed in {C:tomlab}, append (or prepend) {C:tomlabshared} separated to the other entries with a semi-colon ({;}) to the PATH environment variable.

One can also set the PATH environment variable temporarily in a running command shell. This is done by doing

  C:\> set PATH=%PATH%;C:\tomlab\shared

This change will only be applied in that command shell, and will therefore be discarded when the command shell is terminated.

Unix-like systems

Set on command line when invoking MATLAB:

 [user@host:~]$ LD_LIBRARY_PATH=[$LD_LIBRARY_PATH:]/tpath/shared <ml> &

where ml is the name of your MATLAB executable and tpath is the TOMLAB installation path. If LD_LIBRARY_PATH is already set to something and you wish to preserve this, include the part in [ ].

Set in $HOME/.bashrc, $HOME/.profile, $HOME/.cshrc (or $HOME/.matlab7rc.sh if it exists):

 export LD_LIBRARY_PATH=/tpath/shared # bash
 setenv LD_LIBRARY_PATH /tpath/shared # csh and similar

If you have an existing value in LD_LIBRARY_PATH, use a colon : to separate directories when adding the TOMLAB directory:

 export LD_LIBRARY_PATH=/tpath/shared:$LD_LIBRARY_PATH # bash
 setenv LD_LIBRARY_PATH /tpath/shared:$LD_LIBRARY_PATH # csh and similar

If installing for multiple users, you can add similar settings to /etc/profile, or optionally to $MATLAB/bin /.matlab7rc.sh.

Mac OS X users should set DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH.

MATLAB 7.8+ on 64-bit Linux

A potential problem concerning shared library versions may lead to crashes when running certain TOMLAB MEX files. This is related to MATLAB and/or the runtime linker loading the wrong version of a support library.

The following workaround is suggested:

Start Matlab 7.8+ from a shell prompt with the following option:

 [user@host:~] LD_PRELOAD=$TOMLAB/shared/libgfortran.so.1.0.0 \
 LD_LIBRARY_PATH=$TOMLAB/shared \
 $MATLAB78 &

In the above command, replace $TOMLAB with the path to your TOMLAB installation, and $MATLAB78 with the name of your MATLAB 7.8 binary. This may vary depending on your particular setup, e.g. if having a symbolic link to the MATLAB binary or not. You may need to specify the full path to the MATLAB installation. For example:

 [user@host:~]$ LD_PRELOAD=/home/user/tomlab/shared/libgfortran.so.1.0.0 \
 LD_LIBRARY_PATH=/home/user/tomlab/shared \
 /usr/local/matlab78/bin/matlab &

Installing TOMLAB license files

In order to run the TOMLAB solvers a valid license file is needed (a plain text file called {tomlab.lic}). This file should normally be placed in the TOMLAB root directory {tomlab}. In case of a demo license, there may be an additional file {tomlab.dat} which also should be put in the TOMLAB root directory.

It is important that {tomlab.dat} is writable for the user running TOMLAB.

An environment variable ({TOMLAB_LICENSE_FILE}) need to point to the location of this file (if not placed in the TOMLAB root directory).

For Windows 2000/XP/Vista/7 go to the Control Panel, click on System, select the Advanced Tab, and click on Environment variables. Click on New under user variables. Variable name should be set to {TOMLAB_LICENSE_FILE} and variable value to the location of the file (including file name), for example: {C:tomlabtomlab.lic}.

If using a UNIX-like system the following command (depending on Shell) archives the same result:

For CSH-like shells:

   $ setenv TOMLAB_LICENSE_FILE /usr/local/tomlab/tomlab.lic

For Bourne-like shells:

   $ export TOMLAB_LICENSE_FILE=/usr/local/tomlab/tomlab.lic

Setting up CPLEX

For information on non-standard CPLEX license please contact the TOMLAB support team.

Starting TOMLAB

When the files are installed and the license is setup correctly, MATLAB can be started. Change directory to the root directory of TOMLAB (where TOMLAB was installed, that is) and run

>> startup

This command checks the installation and makes sure the license is properly installed. If everything is ok one can start using TOMLAB. If something is wrong, go back and check every step covered in this guide. If that cannot solve your problem, don’t hesitate to contact support at Support.png.

The QUICKSTART GUIDE (available at http://tomopt.com) is good for getting started with TOMLAB.