website header
<< Back to previous page

Source files & installation

The code is released under the Apache 2.0 license!

If you have suggestions and/or improvements for this instruction or if something goes wrong, please send an email. There are 2 different versions available:
I really like to ask you to publish your source code or your modifications to my code as well!
It is much easier to compare further changes and improvements with already existing open source versions.

Free surface LBM implementation (latest update: 2012-02-22):

What OS do I need?
Ubuntu, but any other unix based OS should work too. However, Ubuntu 10.10 is recommended. You can also send me patches to get it running on another OS.
What GPU do i need?
The program is able to run on NVIDIA GPUs of type 8xxx ore newer. An NVIDIA driver with version 260.19.12 or higher is recommended.
Requirements / Dependencies:
The program is based on a few libs. Some of them are still experimental and/or under development:
  • libSDL 2.0 to create an OpenGL 3.2 core context
    Download the developer version 2.0 via mercurial: "hg clone"
    Compile and install with './configure --prefix=$HOME/local && make install'
  • libSDL_Image 2.0 to load .png and .jpg files
    Download the developer version 2.0 via mercurial: "hg clone"
    Compile and install with './configure --prefix=$HOME/local --enable-jpg --disable-jpg-shared && make install'
  • Recent versions of the following files and libs:
    SDL image 1.2
    the glx.h file

    On Ubuntu systems you just have to type the following line into a console:
    $ sudo apt-get install g++ libsdl-image1.2-dev libfreetype6-dev
  • libCWiid for the Wii balance board (optional feature).
    You have to patch this version for the Wii balance board or you can download an already patched version cwiid_2010_05_13.tar.bz2
    For a default Ubuntu 10.10 installation, more packages have to be installed:
    $ sudo apt-get install bison flex libbluetooth-dev libgtk2.0-dev python-dev
    The most recent version of CWIID is available via "git clone git://"

Download link:
After you compiled and installed all the required and dependent libs, download the code: lbm_opencl_fs_2012_02_22.tar.bz2.
Installation instructions:
Extract the programs lbm_opencl_fs_2012_02_22.tar.bz2 file in your $HOME/Download folder.
I use eclipse for development and to compile the project, but there is also a simple makefile to allow compiling without running eclipse. Switch to the $HOME/Download directory and type in the following lines into the console:
$ cd lbm_opencl_fs_2012_02_22/
$ make debug
This compiles the source code. Then go down one level to the main source directory and to run the program:
$ ./build/lbm_opencl_fs_debug -n -c -g 
In the case that you only have a single GPU card installed without other OpenCL drivers the program should start. Otherwise scroll down to the point 'Troubleshooting'.
There are plenty command line options available:
usage: ./build/lbm_opencl_fs...
	[-x resolution_x, default: 32]
	[-y resolution_y, default: 32]
	[-z resolution_z, default: 32]
	[-X resolution_ALL, default: 32]
	[-g gravitation in bottom direction, default: -9.81]
	[-t 'time step']	(default: -1 for automatic time step detection)

	[-r 'viscosity, default: 0.005']
	[-q 'maximum gravitation length to limit time step size, default: 0.0001']
	[-u 'length of domain in x direction, default: 1 meter']
	[-v]	(verbose mode on, be verbose)
	[-k 'number of kernels to run' ]	(default: 128)
	[-p]	(pause simulation at start, default:disabled)

	[-P platform_num]	(-1: list available platforms, or select platform)
	[-D device_num]	(-1: list available devices, or select device)

	[-l simulation_loops]	(value: number of simulation loops)
	[-d display] (default: DISPLAY env. variable)
	[-m mass_exchange] (multiplier for mass exchange, default:40)
	[-a lbm_implementation_nr] (select implementation number:)
	                           (0: A-A pattern)
	                           (1: A-B pattern ver. 1)
	                           (2: A-B pattern ver. 2)
	                           (3: A-B pattern ver. 1 and shared memory utilization)

	[-R registers for kernel]	(comma separated list of number of registers per kernel)
	[-T work items per group]	(comma separated list of work items per work group)

	[-c]	(enable loading OpenCL, default:disabled)
	[-n]	(enable LBM simulation, default:disabled)
	[-g]	(enable GUI, default:disabled)

	[-b balance_board_mac_address, default: 0 for auto detection]
The most important ones are:
  • -c: Load OpenCL context
  • -n: Enable the LBM simulation
  • -g: Activate the GUI, you can also run the simulation without the gui for benchmarking purposes
  • -x #, -y #, -z #: set the fluid domain resolution
  • -k #: Setup the default size of a local work group

Troubleshooting for multiple platforms and/or devices:
In case that you have different platforms and compute units available on your workstation, get an overview of the platforms and cards with
$ ./linux_build/lattice_boltzmann_free_surfaces -c -v
You can select the platform with the option "-P #". E. g. to select the platform with the ID 1, use
$ ./linux_build/lattice_boltzmann_free_surfaces -c -v -P 1
After this, the available devices for the according platform are displayed. To select a device, append "-D #" to the command line. E. g.
$ ./linux_build/lattice_boltzmann_free_surfaces -c -v -P 1 -D 1

2010-11-19: License related updates
2010-11-02: Fallback solutions supporting more true type fonts
2010-11-01: Made compatible to NVIDIA drivers 260.19.12
Removed dependency on libcwiid

Basic LBM implementation without free surfaces:

This is the version without free surfaces.
Because the task of the diploma thesis was to develop a free surface version, this code is partly undocumented.
There is also a directory linux_build with a simple make file in the archive.

You can find the source tarball here: lattice_boltzmann_driven_cavity_2010_06_06.tar.bz2