SunlightCBM - installation

[ top :: introduction :: installation :: tutorial ]

SunlightCBM @

SunlightCBM has been designed and tested to work with perl inside a modern version of the GNU/Linux operating system. The scripts are intended to be used with unix pipes for example. These installation notes are therefore only tested with GNU/Linux, although they may also work in Windows (try using Cygwin) and in other unix-like operating systems. SunlightCBM uses libSBML to read and write the SBML models, and GLPK to solve linear programming problems. These software packages should therefore be installed first.

Installing LibSBML

The present version of SunlightCBM is known to work with libSBML version 5.6.0 although it will very likely work with earlier releases >= 3.0. LibSBML should be installed with the perl bindings enabled, using for example ./configure --with-perl. For testing the installation, one can use the sample perl scripts supplied with libSBML. However it is a good idea to test these outside the libSBML source code directory since you may find it necessary to set the PERL5LIB environmental variable, thus for Bourne shell users (ie bash)



% export
PERL5LIB=/usr/local/lib/perl5/site_perl/5.8.8/i386-linux-thread-multi

or for C shell users (ie csh)



% setenv PERL5LIB
/usr/local/lib/perl5/site_perl/5.8.8/i386-linux-thread-multi

may be required (adjust these to reflect the actual directory where the libSBML perl module is installed). This commands can be added to your .bashrc or equivalent shell startup script.

Installing the GLPK library

The present version of SunlightCBM is known to work with GLPK version 4.43 (and may work with later versions). GLPK should be installed and tested as per the instructions. Make a note of the locations of where the header file (glpk.h) and the libraries (libglpk.so and friends) end up, as these are required to build the perl-GLPK interface described next.

Installing the Perl-GLPK interface

To make a locally usable version of SunlightCBM, the dynamically-linked library GLPK.so must be generated. This is most easily done using the provided Makefile. First check that the top couple of lines of the Makefile point to the GLPK header file (glpk.h) and libraries (libglpk.so and friends). Then type 'make' to generate a local copy of GLPK.so. Now try the following test script glpk_test.pl :

% perl glpk_test.pl 

*    
0:  
objval =  
0.000000000e+00   infeas =   0.000000000e+00 (0)

*    
2:  
objval =  
7.333333333e+02   infeas =   0.000000000e+00 (0)

OPTIMAL
SOLUTION FOUND

z = 733.333;
x1 = 33.3333; x2 =
66.6667; x3 = 0

This test script re-implements the example code in the GLPK documentation as a perl script ('% ' is the command line prompt). If you get this output then congratulations, the perl-GLPK interface is working!

A common problem is that perl is unable to find the libraries at run-time, for example :

% perl glpk_test.pl 

Can't load
'./GLPK.so' for module
GLPK: libglpk.so.0: cannot open
shared object file: No such file or directory at
/usr/lib/perl5/5.8.8/i386-linux-thread-multi/DynaLoader.pm line 230.

 at
GLPK.pm line 11

Compilation
failed in require at
glpk_test.pl line 2.

BEGIN
failed--compilation aborted
at glpk_test.pl line 2.

If you get this then try again with '

LD_LIBRARY_PATH=/usr/local/lib
perl
glpk_test.pl

' (obviously, substitute the location of libglpk.so and friends in here). If this now works, you can fix it more permanently by

% export LD_LIBRARY_PATH=/usr/local/lib

or similar (this can be added to your .bashrc or equivalent shell startup script).

Testing out SunlightCBM

At this point SunlightCBM should work from within the current directory. Try the following :

% perl singleopt.pl simple_network.xml "EX_A=(-10,--)"

6.25

If you get this output, then congratulations! SunlightCBM is now working.

You might also wish to try this with './singleopt.pl' rather than 'perl singleopt.pl'. This should work provided the scripts are executable and /usr/bin/perl is the full pathname to the perl executable, otherwise edit the first line of the scripts to point to your perl executable.

The SunlightCBM perl scripts can be copied to and run from another directory, provided that SunlightCBM.pm, GLPK.pm and GLPK.so are copied with them.

Implementation notes

The main complication is the perl-GLPK interface. Here SWIG is used to generate the perl module (GLPK.pm) and wrapper code (GLPK_wrap.c) automatically from header files (these two files are included in the SunlightCBM package). The GLPK library itself is supplemented by some hand-written 'helper' functions to handle sparse arrays (glpk_interface.c and glpk_interface.h). A modern version of SWIG is required since extensive use is made of the shadow class features. To build GLPK.so, perl's ExtUtils::MakeMaker is used to generate Makefile.perl from Makefile.PL, which in turn is used to generate GLPK.so although at this point buried deep in a perl-generated directory structure. In the final step, GLPK.so is copied into the current directory and the perl-generated directory structure is cleaned up. Using ExtUtils::MakeMaker should make this approach pretty robust and implementation independent.

There is a short test script sparse_array_test.pl which can be used to test the sparse array implementation (this functionality being part of SunlightCBM and not GLPK).

The perl module (GLPK.pm) and a wrapper code (GLPK_wrap.c) can be regenerated from GLPK.i using 'make swigclean; make GLPK.pm'. Note that 'make clean' removes the local copy of GLPK.so; '

make
swigclean

' removes the SWIG-generated files; and '

make
realclean

' does both.

Global installation

Firstly I should say that I don't tend to do this, therefore these notes are for guidance and have not necessarily been thoroughly tested. Firstly ExtUtils::MakeMaker capabilities can be used to do a global install of the perl-GLPK interface. The following should work :



% make clean



% make Makefile.perl



% make -f Makefile.perl



% make -f Makefile.perl install

This should result in the perl-GLPK interface being installed into the correct place. The last of these may require root access to write into the desired directories. You can tidy up afterwards with :



% make -f Makefile.perl realclean



% rm Makefile.old

You can test the installation by either of the test scripts glpk_test.pl or sparse_array_test.pl. It might be necessary to set globally the PERL5LIB environment variable or equivalent; and the LD_LIRARY_PATH or equivalent (expert users might want to edit /etc/ld.so.conf or something fancy like that).

Next SunlightCBM.pm should be copied to somewhere on perl's module search path (perhaps motivated by where GLPK.pm ends up). The perl scripts singleopt.pl etc can be made executable (use 'which perl' to check that '#!/usr/bin/perl' is correct on the first lines). They can then be copied somewhere such as /usr/local/bin that is on a typical users path. At this point, SunlightCBM is installed globally and you can test it by copying simple_network.xml into an empty directory and running singleopt.pl as described above.

TO DO: review the relevant perl documentation like perlmodinstall and make all this work better!

Dependencies

Here is a summary of the software versions that are known to work with SunlightCBM.

	package	version
	perl	5.12.4
	libSBML	5.6.0
	GLPK	4.43
	SWIG*	2.0.1

*only needed if rebuilding GLPK.pm and GLPK_wrap.c

Any reasonably up-to-date GNU/Linux distribution (such as Fedora 14 :-) should provide a suitable perl, and the make command and C compiler required for installation. LibSBML, GLPK and SWIG should compile and install in these distributions without any problems (it is first worth checking whether prebuilt packages are available).