============
Jlabos
============

:Author: Yann Sagon <yann.sagon@unige.ch>
:Version: 0.1 of 2012/01/05

***************
Introduction
***************
Jlabos is a java wrapper of the CFD C++ opensource library `Palabos <http://www.palabos.org>`_ 
It is now part of Palabos but optionaly compiled.

***************
Installation
***************

Requirement
===============

- ``swig1.3``
- ``javac + java (for example openjdk-6-jdk``
- ``mpicxx (for example libopenmpi-dev``
- ``mpirun (for example openmpi-bin``
- ``python``

Optional:

- ``octave``
- ``subversion``
- ``convert``
- ``inkscape``


Installation
===============

You need to have Palabos installed and configured. Short explanation:
`download Palabos <http://www.palabos.org/download-ql>`_

Define env variable ``PALABOS_ROOT``. For example add this line in ``~/.bashrc``: ``export PALABOS_ROOT=~/location_of_palabos``

``cd $PALABOS_ROOT/jlabos/src``
edit the ``Makefile``
nbOfCore     = 4 // Number of CPU core used to do the compilation. Do not specify more than you realy have or it will be very slow.
swigCompiler = swig // you can specify an alternate swig executable
includePaths = // specify the location of the file ``jni.h`` and ``jni_md.h``

Compile Jlabos : ``cd $PALABOS_ROOT/jlabos/src; make`` This will take a lot of time because it will compile Palabos at the same time.

Running the examples
======================
go to the choosen example directory and type ``make``. This will compile and launch the program.
You can customize some elements in the Makefile. Do not launch directly the SConstruct file.
If you need to specify another place for the shared libs, edit the file ``launch`` accordingly.

To clean the directory, you can use ``make clean``

See the result
===============
If needed you can plot the results with Octave or Matlab like this:
``./plot.m``
Jlabos can as well directly produce jpg files using the embeded library MLplot. See the examples code source.
MLplot need the program ``convert`` from ``ImageMagick``

Customize the wrapper
=======================
Jlabos is the Palabos wrapper but it is not complete. If you need more functionalities there are two places to go:

$PALABOS_ROOT/jlabos/src/jlabos => here you find high level java files that wrap to the autogenerated files here:
$PALABOS_ROOT/jlabos/src/swig/pre_compiled => Swig generated files from the ``.i`` files present at the same place. Do not edit the java files here but instead modify the ``.i`` files and re-run the make process. But be warned, it's not easy to obtain something that is working!

If the functionality that you want is present in the second place, you can modify the files in the first place to wrap nicely the self generateds java files.

Files
------------------

::

  │── examples
  │   ├── Cavity2d
  │   ├── Cavity3d
  │   ├── Cylinder2d
  │   ├── Cylinder3d
  │   └── Porous
  └── src
      ├── compilePalabos
      ├── jlabos
      │   └── plb
      │       └── jlabos
      ├── lib
      ├── plbWrapper
      │   ├── block
      │   │   ├── double
      │   │   ├── float
      │   │   └── int
      │   ├── lattice
      │   │   ├── d2q9_double
      │   │   ├── d2q9_float
      │   │   ├── d3q19_double
      │   │   └── d3q19_float
      │   └── utils
      ├── precompiled
      │   ├── floatOnly
      │   │   ├── double
      │   │   └── float
      │   ├── intOrFloat
      │   │   ├── double
      │   │   ├── float
      │   │   └── int
      │   └── lattice
      │       ├── d2q9_double
      │       ├── d2q9_float
      │       ├── d3q19_double
      │       └── d3q19_float
      ├── swig
      │   ├── pre_processed
      ├── testing
      └── util

Modified files
--------------

::

  M    src/core/globalDefs.h
  M    src/parallelism/mpiManager.cpp (ok)
  M    src/io/serializerIO_3D.h (ok)
  M    pythonic/src/pypal/boundary.py
  M    pythonic/src/pypal/plb/__init__.py
  M    pythonic/src/pypal/pout.py
  M    pythonic/src/preprocess
  M    pythonic/src/compilePalabos/Makefile
  M    pythonic/src/Makefile
  M    pythonic/examples/cylinder2d.py
  M    pythonic/examples/cavity2d.py
  M    pythonic/examples/cavity3d.py
  M    pythonic/examples/porous.py

Technical details
-----------------

One part of the wrapper is generated using the Swig library (Simplified Wrapper and Interface Generator). This step produce not very usable Java files. This is why we had to write a second wrapper in Java to hide this first layer to the end user. Jlabos is not a complete wrapper for Palabos, but will evolve over time. 

The directory `compilepalabos` is just a dummy project to force the compilation of `Palabos`

jlabos 

In the `swig` directory we have all the `.i` files needed by swig.

`plbwrapper` contains some Palabos wrappers written in C++ and used by swig.
