|
SHOGUN
v2.0.0
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
|
SHOGUN
v2.0.0
|
Currently SHOGUN has been confirmed to be fully functional on PowerPC, i386 and AMD64 Linux (tested on debian/ubuntu and gentoo). We also managed to compile SHOGUN on MacOSX and via cygwin on WIN32 platforms. However some manual tweakings of configuration files might be necessary.
SHOGUN is currently pre-packaged for debian (see http://www.debian.org) and available on MacOSX via macports (see http://www.macports.org )
On debian, depending on the interface you want, install the package(s)
libshogun-dev - for C++ developers building extensions using
libshogun
shogun-csharp-modular - for the modular csharp interface
shogun-lua-modular - for the modular lua interface
shogun-java-modular - for the modular java interface
shogun-octave-static - for the static octave interface
shogun-octave-modular - for the modular octave interface
shogun-python-static - for the static python interface
shogun-python-modular - for the modular python interface
shogun-r-static - for the static r interface
shogun-ruby-modular - for the modular ruby interface
shogun-cmdline-static - for the static command-line interface.
shogun-elwms-static - for the static eierlegende wollmilchsau interface
(one interface to r/python/octave allowing
to run commands in non-native languages)
shogun-doc - for the documentation
The mac port is provided by James Kyle (Thanks!!) and makes installations on OSX as easy as under linux. To install shogun you will need macports (see http://www.macports.org). Then issue
sudo port selfupdate sudo port install swig -php5 -ruby -perl +python (shogun users who want the r and octave interfaces should add +octave and/or +r to this list) sudo port install shogun (for r, octave, and elwms interfaces: +r +octave +elwms)
Add
DYLD_FALLBACK_LIBRARY_PATH=${macports_prefix}/lib to your shell profile. Tip the default ${macports_prefix} is /opt/local/. In that case, the library path would be /opt/local/lib.
Download SHOGUN from http://www.shogun-toolbox.org , aswell as its requirements.
SHOGUN requires the standard linux utils like bash, grep, test, sed, cut, ldd, uname gcc g++ and cat python (debian package: python2.4 or python2.5) for the ./configure to work.
Optionally you will need atlas and lapack (debian packages lapack3-dev, atlas3-headers atlas3-base-dev or atlas3-altivec-dev atlas3-sse2-dev) installed. Note that atlas/lapack is only supported under linux (high performance computing should be done under linux only anyway). In case atlas/lapack is unavailable, don't worry most of shogun will work without, though slightly slower versions are used. To enable Multiple Kernel Learning with CPLEX(tm) just make sure cplex can be found in the PATH. If it is not found shogun will resort to GLPK (if version at least 4.29 is found) for 1-norm MKL, p-norm MKL with p>1 will work nonetheless.
On most platforms (Linux,MacOSX,cygwin) it is sufficient to issue
./configure make sudo make install
In case you just want to compile for a single interfaces you can use
./configure --interfaces=libshogun,libshogunui,<interface> make sudo make install
where interface is one of the following
(you don't need to compile libshogunui in case you compile a modular interface)
However, just running
./configure
will autodetect and configure for the available interfaces.
Call
./configure --help
to see the list of additional options detailed below.
Running configure for SHOGUN version r
Usage: ../src/configure [OPTIONS]...
Configuration:
--interfaces=INTERFACE1,INTERFACE2,...
configure shogun for a modular interface (recommended) like
python_modular
r_modular
octave_modular
java_modular
csharp_modular
lua_modular
ruby_modular
or a static one like
cmdline_static
r_static
python_static
octave_static
matlab_static
--datatypes=DATATYPE1,DATATYPE2,...
configure shogun to support these data types (default uint8_t,float32_t,float64_t)
can be any of
char,bool,uint8_t,uint16_t,uint32_t,uint64_t,
int8_t,int16_t,int32_t,int64_t,float32_t,float64_t,floatmax_t
-h, -help, --help display this help and exit
Installation directories:
--destdir=DIR use this as the root dir to install shogun to [/]
--prefix=DIR use this prefix for installing shogun [/usr/local]
--bindir=DIR use this prefix for installing shogun binary
[PREFIX/bin]
--datadir=DIR use this prefix for installing machine independent
data files (fonts, skins) [PREFIX/share/shogun]
--mandir=DIR use this prefix for installing manpages [PREFIX/man]
--confdir=DIR use this prefix for installing configuration files
[same as datadir]
--libdir=DIR use this prefix for object code libraries [PREFIX/lib]
--incdir=DIR use this prefix for include files [PREFIX/include]
--pydir=DIR use this prefix for python files [PREFIX/auto-detected]
--rubydir=DIR use this prefix for python files [PREFIX/auto-detected]
--octdir=DIR use this prefix for octave files [PREFIX/auto-detected]
--rdir=DIR use this prefix for r files [PREFIX/auto-detected]
Optional features:
--enable-hdf5 enable hdf5 file support [auto]
--enable-json enable json file support [auto]
--enable-xml enable xml file support [auto]
--enable-readline enable readline in cmdline interface [auto]
--enable-largefile enable large file support (64bit file acces routines) [enabled]
--enable-spinlocks enable use of spinlocks instead of mutexes [auto]
--enable-lapack enable lapack (fast blas and lapack math routines) and use built in ones (slower!) [auto]
--enable-arpack enable arpack [auto]
--enable-mosek enable MOSEK [auto]
--enable-superlu enable SuperLU [auto]
--enable-nlopt enable NLOPT [auto]
--enable-eigen3 enable Eigen3 [auto]
--enable-cplex enable code using CPLEX [auto]
--enable-lpsolve enable code using lpsolve [auto]
--enable-glpk enable code using GLPK [auto]
--enable-lzo enable code using LZO compression [auto]
--enable-snappy enable code using SNAPPY compression [auto]
--enable-gzip enable code using GZIP compression [auto]
--enable-bzip2 enable code using BZIP2 compression [auto]
--enable-lzma enable code using LZMA compression [auto]
--enable-bigstates enable big (16bit) state [enabled]
--enable-hmmcache enable HMM cache [enabled]
--enable-svm-light enable building of SVM-light and thus result in pure GPLv3 code [enabled]
--enable-logcache enable log (1+exp(x)) log cache (is much faster but less accurate) [disabled]
--enable-shortrealkernelcache enable kernelcache to use 4-byte-floating-point values instead of 8-byte-doubles [enabled]
--enable-logsum-array enable log sum array supposed to be a bit more accurate [disabled]
--enable-hmm-parallel enable parallel structures in hmm training. shogun will then run as many threads as the machine has (much faster) [disabled]
--disable-hdf5 disable hdf5 file support [auto]
--disable-json disable json file support [auto]
--disable-xml disable xml file support [auto]
--disable-readline disable readline in cmdline interface [auto]
--disable-largefile disable large file support (64bit file acces routines) [enabled]
--disable-lapack disable lapack (fast blas and lapack math routines) and use built in ones (slower!) [auto]
--disable-arpack disable arpack [auto]
--disable-mosek disable MOSEK [auto]
--disable-superlu disable SuperLU [auto]
--disable-nlopt disable NLOPT [auto]
--disable-eigen3 disable Eigen3 [auto]
--disable-cplex disable code using CPLEX [auto]
--disable-lpsolve disable code using lpsolve [auto]
--disable-glpk disable code using GLPK [auto]
--disable-lzo disable code using LZO compression [auto]
--disable-snappy disable code using SNAPPY compression [auto]
--disable-gzip disable code using GZIP compression [auto]
--disable-bzip2 disable code using BZIP2 compression [auto]
--disable-lzma disable code using LZMA compression [auto]
--disable-bigstates disable big (16bit) state [enabled]
--disable-hmmcache disable HMM cache [enabled]
--disable-svm-light disable building of SVM-light and thus result in pure GPLv3 code [enabled]
--disable-logcache disable log (1+exp(x)) log cache (is much faster but less accurate) [disabled]
--disable-shortrealkernelcache disable kernelcache to use 4-byte-floating-point values instead of 8-byte-doubles [enabled]
--disable-logsum-array disable log sum array supposed to be a bit more accurate [disabled]
--disable-hmm-parallel disable parallel structures in hmm training. shogun will then run as many threads as the machine has (much faster) [disabled]
Miscellaneous options:
--disable-doxygen disable documentation generation via doxygen for python_modular interface [enabled]
--disable-optimization disable compiler optimizations [enabled]
--disable-cpudetection disable cpu flags detection and corresponding optimization options [enabled]
--enable-debug enable debugging [enabled]
--enable-trace-mallocs enable memory allocation tracing [disabled]
--disable-reference-counting disables reference counting causing severe memory leakage [enabled]
--enable-swig-directors enables swig based director classes [disabled]
--enable-path-debug enable viterbi path debugging [disabled]
--enable-profile compile profiling information into shogun [disable]
--enable-static build a statically linked binary (to the extend possible);
set further linking options with --enable-static="-lm -lglpk"
--python=python use this python executable [python]
--gmock=gmock-config use this gmock-config script [gmock]
--ruby=ruby use this ruby executable [ruby]
--cc=COMPILER use this C compiler to build shogun [autodetected]
--cxx=COMPILER use this C++ compiler to build shogun [autodetected]
--cflags=OPTIONS use these C compiler options
--cxxflags=OPTIONS use these C++ compiler options
--ldflags=OPTIONS use these additional linker options
--target=PLATFORM target platform (i386-linux, arm-linux, etc)
--install-path=PATH the path to a custom install program (useful if
your OS uses a GNU-incompatible install utility by
default and you want to point to the GNU version)
--includes=DIR include DIR when searching for includes
--libs=DIR include DIR when searching for libraries on linking
If this does not work for you, consult the INSTALL file for platform specific build instructions. The INSTALL file is contained in the shogun src distribution and quoted below.
GENERAL
On most platforms (Linux,MacOSX,cygwin) it is sufficient to issue
./configure
make
sudo make install
which will build shogun for the r_static, matlab_static, python_static,
octave_static and octave_modular, python_modular, r_modular and
java_modular interfaces and later install it.
Often you are just interested in one language and we always recommend to
use the more powerful modular interfaces.
If you want specific interfaces use,
e.g
./configure --interfaces=python_static,python_modular
See ./configure --help for additional options.
If this does not work for you, see the SPECIFIC BUILD INSTRUCTIONS below
SPECIAL FEATURES
To enable Multiple Kernel Learning with CPLEX(tm) just make sure cplex can
be found in the PATH. If it is not found shogun will resort to GLPK (if found)
for 1-norm MKL, p-norm MKL with p>1 will work nonetheless.
REQUIREMENTS
The standard linux utils like bash, grep, test, sed, cut, awk, ldd, uname gcc
g++ and cat, python (debian package: python2.5, python2.6) are required
for the ./configure to work.
To compile the R interface you need to have the R developer files
(debian package r-base-dev) installed.
To compile the octave interface you need to have the octave developer files
(debian package octave3.0-headers) installed.
To compile the java interface you need to have the java developer files
(debian package openjdk-6-jdk) installed.
To compile the python interface you need to have the python developer files
installed (debian packages python2.5-dev or python2.6-dev) and numpy
version 1.x installed (debian package python-numpy) installed.
Optionally you will need atlas and lapack (debian packages lapack3-dev,
atlas3-headers atlas3-base-dev or atlas3-altivec-dev atlas3-sse2-dev)
installed. Note that atlas/lapack is only supported under linux (high
performance computing should be done under linux only anyway). In case
atlas/lapack is unavailable, don't worry most of shogun will work without,
though slightly slower versions are used. For standard 1-norm
multiple kernel learning (MKL) the GNU Linear Programming Kit (GLPK) version at
least 4.29 or CPLEX is required. If you want to build the html documentation or
python online help you will need doxygen version 1.6.0 or higher.
SPECIFIC BUILD INSTRUCTIONS
BUILDING ON DEBIAN GNU LINUX
Python (python2.5 or python2.6) need to be installed. To get atlas/lapack
optimizations optionally also install the atlas3-* packages aswell as the
lapack3-* packages.
standalone:
===========
cd src
./configure --interfaces=cmdline_static
make
a shogun executable can be found in cmdline
octave
======
To compile the octave interface you need to have the octave developer files
(debian package octave3.2-headers or octave3.0-headers).
then do a
./configure --interfaces=octave_static
make
make install
a sg.oct file should be created. as a test start octave in the src/ directory
and type
addpath('../examples/documented/octave/graphical')
svr_regression
matlab
======
To compile the matlab interface you need to have matlab installed in the path
(i.e., typing matlab in the shell should start matlab).
then do a
./configure --interfaces=matlab_static
make
make install
a sg.mexglx (or sg.mexa64 or sg.mexmac etc file should be created). As a test
start matlab in the src/matlab directory
and type
addpath('../examples/documented/matlab/graphical')
svr_regression
For permanent use you could add the following line to your matlab/startup.m
addpath('path_to_shogun/trunk/src/matlab');
In case you want to omit the make install step you could run matlab (in gui
mode if you want) with
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:path_to_shogun/trunk/src/libshogun
matlab -desktop
R
=
To compile the R interface you need to have the R developer files
(debian package r-base-dev) installed.
then do the usual
./configure --interfaces=r_static
make
make install
python
======
To compile the python interface you need to have numpy version 1.x installed
(debian package python-numpy and python-numpy-ext) and optionally for plotting
python-matplotlib installed. When using matplotlib, make sure you use numpy as
the underlying numeric toolkit, i.e. you have the line
numerix : numpy
in your /etc/matplotlibrc
then do a
./configure --interfaces=python_static
make
A sg.so file should be created in the src/ directory:
To test whether it is working try
PYTHONPATH=`pwd` python ../examples/documented/python/graphical/svm_classification.py
eierlegendewollmichsau (elwms) interface
========================================
This is a .so file that works with R,python,matlab,octave all in one. To compile
you should have at least python and some other interface enabled:
cd src
./configure --interfaces=octave_static,matlab_static,r_static,python_static,elwms_static
make
cd interfaces/elwms_static
LD_LIBRARY_PATH=/path/to/octave/lib:/path/to/matlab/libs octave
All examples from
examples/documented/{r_static,python_static,matlab_static,octave_static}/*
should work plus the ones in examples/documented/elwms_static/
(that allows lang -> python subcommands).
object oriented python/swig interface:
======================================
proceed as for the python interface but now in addition install the swig package and
configure+compile shogun with:
./configure --interfaces=python_modular
make
sudo make install
to test if it is working try python ../examples/documented/python_modular/graphical/svm.py
BUILDING ON MACOSX
python:
=======
Get the precompiled binary packages
python, matplotlib, NumPy and wxPython from http://pythonmac.org/packages/py24-fat/index.html
Note: On powerpc archs don't use gcc-4.0 / gcc-4.1 as it will fail with an internal compiler
error. Try gcc-4.2 instead or disable optimization (using -O0).
Furthermore there it *may* happen that compiling hangs with an error in
/usr/include/architecture/ppc/math.h:513.
A workaround is to uncomment this in math.h:
typedef struct __complex_s {
double Real;
double Imag;
} __complex_t;
Also make sure you don't mix python versions (i.e. python2.5 and python2.6) on build/runtime.
You can specify the python version as a argument to configure, e.g.: --python=python2.7
./configure --interface=python_static
make
to test if it is working try:
PYTHONPATH=`pwd` python ../examples/documented/python/graphical/svm_classification.py
object oriented python/swig interface:
======================================
Follow the above instructions for python. Then use homebrew/fink/darwinports to install swig.
./configure --interfaces=python-modular
make
sudo make install
to test if it is working try python ../examples/documented/python_modular/graphical/svm.py
octave:
=======
Use fink/darwinports to install octave. For intel-macs octave currently is only in the
unstable repository + it has to be compiled from source. Also note that g77
got replaced by gfortran, so you might need to do a fink install gcc4 first (which takes
an endless amount time to compile).
then do:
./configure --interfaces=octave_modular
make
a sg.oct file should be created. as a test start octave in the src/ directory
and type
addpath('../examples/documented/octave/graphical')
svr_regression
standalone:
===========
cd src
./configure --interfaces=cmdline_modular
make
make install
The shogun executable can be found in /usr/local/bin/shogun and the libraries in
/usr/local/lib/libshogun*.
R:
==
Install the full R package (e.g. the 93MB R-2.4.0.dmg image from
http://cran.r-project.org/bin/macosx/ )
then do the usual
./configure --interfaces=r_modular
make
make install
After starting the R aqua gui, choose File->Source File and select the
../examples/documented/r/graphical/svm_classification.R example
If that does not work out (send us a bug report) and also please try the following:
Enter the src/ directory and do:
./configure --interfaces=r_modular
make
make install
(if that fails attach the configure.log in the bug report)
a sg.so file should be created. To test if that file is OK try in the
r/ directory:
LD_LIBRARY_PATH=../libshogun R
>> dyn.load('sg.so')
sg <- function(...) .External("sg",...,PACKAGE="sg")
sg('help')
if that was still working go to the shogun/R directory and try
make clean
make
if a .tar.gz is successfully created, then the R CMD INSTALL <file>.tar.gz
should go through.
matlab:
=======
BUILDING ON WINDOWS / CYGWIN
install cygwin 1.7 or later
R:
==
I did not try the long and painful way of compiling R to get etc/Makeconf etc.
to be setup correctly. Thus the usual R CMD INSTALL <pkg> won't work (help welcome).
Instead install the R package from cran (i.e. using the R-2.4.0-win32.exe
installer from http://cran.r-project.org/bin/windows/base/ )
Enter the src/ directory and do:
./configure --interfaces=r_modular
(if that fails attach the configure.log in the bug report)
make
a sg.dll file should be created. To test if that file is OK try in the
src/ directory:
R
>> dyn.load('sg.dll')
sg <- function(...) .External("sg",...,PACKAGE="sg")
sg('help')
Instead of using library(sg) in your .R scripts you now have to use
dyn.load('<path_to_shogun>/sg.dll')
sg <- function(...) .External("sg",...,PACKAGE="sg").
After this modification, The examples in examples/documented/r/ should all work. To get
them to go start the R gui, choose File->Source R Code and select
../examples/documented/r/graphical/svr_regression.R (as this example has no other package dependencies).
matlab:
=======
cd src
./configure --interfaces=matlab_static
make
a sg.dll can be found in src/matlab
startup matlab and type sg('help')
standalone:
===========
cd src
./configure
make
make install
a shogun.exe can be found in src/cmdline
octave:
=======
install octave and octave-headers
cd src
./configure --interfaces=octave_static
make
make install
a sg.oct file can be found in src/octave
try
cd src/octave
LD_LIBRARY_PATH=../libshogun octave
addpath('../examples/documented/octave/graphical')
svr_regression
python:
=======
install python2.5 and numpy >1.0
now compile shogun:
./configure --interfaces=python_static
make
make install
this will create a sg.dll in the src/python dir
to test if it is working, try:
cd src
LD_LIBRARY_PATH=./libshogun PYTHONPATH=./python python ../examples/documented/python/graphical/svm_classification.py
object oriented python/swig interface:
======================================
do all of the above you did for python but now in addition install the swig
package and configure+compile shogun with:
./configure --interfaces=python_modular
make
make install
to test if it is working try python ../examples/documented/python_modular/graphical/svm.py
object oriented octave/swig interface:
======================================
do all of the above you did for octave but now in addition install the swig
package and configure+compile shogun with:
./configure --interfaces=octave_modular
make
make install
to test if it is working try octave ../examples/documented/octave_modular/libsvm.m
object oriented r/swig interface:
======================================
do all of the above you did for R but now in addition install the swig
package and configure+compile shogun with:
./configure --interfaces=r_modular
make
make install
to test if it is working try octave ../examples/documented/r_modular/all_classifier.R
object oriented java/swig interface:
======================================
do all of the above you did for java but now in addition install the swig
package and configure+compile shogun with:
./configure --interfaces=java_modular
make
make install
to test if it is working try
export CLASSPATH=/usr/share/java/jblas.jar:SHOGUNDIR/src/java_modular/shogun.jar:.
export LD_LIBRARY_PATH=SHOGUNDIR/src/libshogun:SHOGUNDIR/src/java_modular
javac ../examples/documented/java_modular/classifier_libsvm_minimal_modular.java
and java classifier_libsvm_minimal_modular
PROBLEMS
In case header files or libraries are not at standard locations one needs
to manually adjust the libray/include paths using --includes or --libs
(see configure --help for additional options)
The current mingw version in cygwin is out of date - so R and matlab won't work
until mingw is updated to gcc 4.X.