SunlightLB installation instructions

SunlightLB @

Installation instructions

The basic lattice Boltzmann code is implemented as a set of library routines, coded in vanilla C. The Makefile is configured to build these into a shared object (so) library. A SWIG (Simplified Wrapper and Interface Generator) interface file allows access for scripting languages like perl or python, by building extension modules. Note that the installation steps below may require root priviledges.

To build and install SunlightLB as a shared object library.

Go into the src directory.
Edit the top part of the Makefile (don't worry about the perl- or python-related variables at this point).
Type 'make' to build the libsunlightlb.so* library files.
Type 'make install' to install the header and library files.
Go into the examples directory.
Edit the top part of the Makefile, as above.
Type 'make sphere' to compile the simplest example.
Typing './sphere' runs the code.

Note that the Makefile for the examples assumes that the header file and library will be found by the compiler (eg they are in /usr/local/include and /usr/local/lib respectively). If this is not the case, you may have to specify the locations using the -I and -L compiler options. In addition, you may have to set LD_LIBRARY_PATH so that the linker can find the directory containing the library.
For example, it is possible to compile the examples with purely local header and library files. The library files libsunlightlb.so* should first be built in the src directory, as in the first three steps above, then :

Go into the examples directory.
Edit the top part of the Makefile, in particular add '-I../src -L../src' to the CC_FLAGS variable.
Type 'make sphere' (it should work now).
Extend the load library path by typing the command 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../src/'.
Typing './sphere' runs the code.

If you don't want to work with a shared object library, the source code can be copied into the same directory as the driver code and all compiled together. For example, copy the *.c and sunlight.h files from the src directory, and the sphere.c file from the examples directory, into an empty directory. Then compile with
cc -O3 -ffast-math -Wall *.c -I. -lm -o sphere
The compile options are somewhat peculiar to the GCC compiler: -O3 sets the optimisation level; -ffast-math gives a further speed-up by making some simplifying assumptions about how floating point maths is done; -Wall spits out maximum warnings; -I. is necessary because sphere.c has #include <sunlightlb.h> which means that the compiler will not find the header file unless it is told that the current directory is on the search path; -lm links in the math library.

To build and install SunlightLB as a perl extension module.

Firstly, build and install the shared object library as before.

Go into the src directory.
Edit the perl-related parts of the Makefile.
Type 'make 4perl' to use SWIG to make the perl module files.
Type 'make install4perl' to install the perl module files.
Typing 'perl sphere.pl' in the examples directory runs the code.

It is important to have an up-to-date version of SWIG (v1.3) and perl (v5.8). It is important to have the right perl related variables in the Makefile :

CC_FLAGS_FOR_PERL = $(CC_FLAGS) -D_REENTRANT -D_GNU_SOURCE \
-DTHREADS_HAVE_PIDS -DDEBUGGING -fno-strict-aliasing \
-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
CC_INC_FOR_PERL = /usr/lib/perl5/5.8.0/i386-linux-thread-multi/CORE/
INSTALL_DIR_FOR_PERL = /usr/lib/perl5/site_perl/5.8.0/i386-linux-thread-multi/

If this looks arcane, don't worry. You can get at these things by calling perl itself :

perl -e 'use Config; print "$Config{ccflags}\n";'
perl -e 'use Config; print "$Config{archlib}\n";'

If there are problems with unresolved libraries, don't forget to check LD_LIBRARY_PATH. For other problems, you probably have to start delving into the SWIG documentation.
It is possible to use the perl extension modules without installing them in the perl directory structure. This is very simply done by copying the files SunlightLB.so and SunlightLB.pm to the directory containing the perl script and running the script.
The commands to build the perl extension module assume that basic sunlightlb library files (libsunlightlb.so* and sunlightlb.h) have been installed somewhere where the compiler will find them. If this is not the case, for instance you wish to maintain a purely local version, then you may need to add -I. and -L. options to the compile step as described above; and again it may be necessary to set LD_LIBRARY_PATH.

To build and install SunlightLB as a python module.

This is very similar to building a perl module.

Go into the src directory.
Edit the python-related parts of the Makefile.
Type 'make 4python' to use SWIG to make the python module files.
Type 'make install4python' to install the python module files.
Typing 'python2.2 sphere.py' in the examples directory runs the code.

The Makefile generates a couple of calls to python itself in the 'make 4python' step, in order to generate compiled versions of the SunlightLB.py module (these are SunlightLB.pyc and SunlightLB.pyo). In addition, this step deletes the perl module file SunlightLB.so if present, because this causes problems (see below).
Finding the python include and target directories for installation should be pretty straightforward. A purely local installation can also easily be done, by copying the files _SulightLB.so and SunlightLB.py* to the directory containing the python script (the same caveats about LD_LIBRARY_PATH also apply). Note that there is a potential clash with the perl module file called SunlightLB.so. It appears if this file is present in the same directory as the python script, python won't pick up the right module file.

Other Makefile options.

Typing 'make clean' removes all generated files and clears up clutter.
Typing 'make uninstall' is a fairy dumb method to remove the header files and the library files that were installed in the 'make install', 'make install4perl', and 'make install4python' steps.

Monitor utility

The Tcl/Tk script lbmonitor has been included in the src directory. This provides a GUI to monitor and check-point lattice Boltzmann simulations that generate *.mon files. To run this, you can copy it to the directory in which the LB executables / scripts will be run, and run it with 'wish lbmonitor &' (to put it into background). Alternatively, find out where the Tcl/Tk wish command is and edit the first line of lbmonitor, then put it somewhere that will be found on the path (for example /usr/local/bin).