SUSHI 3D  1.0
SimUlations of Structures in Hydrodynamic Interactions : a 3D fluid-structure interactions solver
Quick start : how to install and start SUSHI3D

S U S H I 3D v1.0

SimUlations of Structures in Hydrodynamic Interactions

************************************************************************

Copyright ©2013 Inria - Université de Lorraine

This software is under GNU General Public Licence

(http://www.gnu.org/licenses/gpl-3.0.txt)

************************************************************************

For more information about the source code, you can consult the doxygen documentation on :

http://sushi3d.iecl.univ-lorraine.fr

==================================================================================================================

General Purpose of the project :

==================================================================================================================

What it does :

SUSHI3D is a MATLAB solver of 3D Fluid-structure interactions systems. This code will allow you to run 3D fluid mechanics simulations with MATLAB.

The most interesting part is that SUSHI3D will allow you to put solid and deformable objects in the fluid and see how they interact with it. The solver is based on a Finite Element Method with a characteristics method for the nonlinear term in the Navier-Stokes equations. A global fluid-structure formulation is used where the dynamics of the fluid and the structure(s) are computed simultaneously. As a result, a global cartesian mesh is used for the Finite Element solver.

The main executable MATLAB script is matlab/ifs/sushi3d.m which takes a configuration file as a parameter (a file where you describe the physics of the simulation and the objects you want to immerge) and returns... plenty of files :

*.vtu and *.vtp files that represent your fluid and your objects at each time step of the simulation,

*.pvd files that associates VTU and VTP files to the corresponding time step.

All these files have to be handled with usual scientific visualization tools such as PARAVIEW or VISIT, etc.

It also create .data files that store information about your solids behaviour.

The MATLAB solver also uses a collection of C++ files which have to be compiled before running SUSHI3D.

==================================================================================================================

Compiling MEX-Files under Linux (binary functions compiled from C++ code and mandatory to make our code work) :

==================================================================================================================

1) Prerequisites:

- The whole project has been shaped to work efficiently on 64 bits systems. So, ... 64 bits systems are highly recommended !

- MATLAB >= R2011a

- g++ > 4.2.0

{ Optional (if you want to use the graphical interface for solid placement and shape modelling, see 5) -Build GUI for shape modelling-)

- libvtk5-dev

- libgtk2

- libgtk-3-dev

}

2) Start MATLAB :

$ matlab

3) Build MEX-Files (libBL + Mexfunctions) :

>> cd mexfiles

>> sushi3d_clean

>> sushi3d_build

4) --OPTIONAL (and LINUX only)-- ; Build GUI for the shape modelling of a rigid or deformable body :

(assuming you are still in the mexfile directory)

>> GUI_build

The GUI for modelling the shape of a rigid/deformable solid is activated in the configuration file required by SUSHI3D (see e.g. Example.conf).

5) Restart MATLAB

{ KNOWN ISSUE AT RUNTIME:

We experimented an error at runtime with Ubuntu>=13.04. Indeed we had this error : "libharfbuzz.so.0: undefined symbol: FT_Get_Advance".

We found out that there was a problem soon to be fixed in that lib. To avoid using that lib and use the usual freetype lib instead, start MATLAB like this :

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libfreetype.so matlab

}

==================================================================================================================

Starting a SUSHI3D simulation:

==================================================================================================================

1) Start MATLAB in the matlab/ifs directory :

$ cd matlab/ifs

$ matlab

2) Edit your own configuration file (read doc about how to write a configuration file : Example.conf)

OR

Use one of our preset configuration : (for example : fish.conf)

3) Call the executable script sushi3d with your configuration file in argument:

>> sushi3d my_configuration_file.conf

{ KNOWN ISSUE AT RUNTIME:

If any problem occurs involving the libstdc++.so.6.0.XX just go in your MATLAB installation directory and remove or rename matlab/sys/os/glnxa64/libstdc++.so.6.0.XX . Indeed, MATLAB includes this runtime library in case your system doesn-t provide it. But your system DO provide it as it comes with the g++ package (so there is a conflict).

Then restart MATLAB }

This will generate VTK files in the folder specified in the configuration file.

You have to wait the end of the simulation to start the post-treatment phase.

You can prematurely end up your simulation by pressing <Ctrl-C> . The program is shaped to catch such an exception and properly close opened files before exiting. Moreover, you will then be able to continue such an interrupted simulation by passing the generated *.mat file as an argument to sushi3d instead of the *.conf file.

We will now explain how to use these files to visualize the fluid-structure animation.

==================================================================================================================

Post treatments:

==================================================================================================================

There are several things you can do after a simulation. First the simulation will store data concerning each object in files named

fishXX.data or rigidXX.data

in the results directory specified in the configuration file. You can use matlab/ifs/Graphs.m to visualize these data. The syntax is Graphs(-my_data_file.data-);

You can also use GNUPLOT if you prefer (an example is given in matlab/ifs/Graphs.gp)

Then, you can decide you want to visualize your object in the domain and visualize the fluid interacting with them. To do this, you will need a tool to visualize the VTK files produced by the simulation. We recommand PARAVIEW. But if you want to try others you can try...

1) Prerequisites:

- PARAVIEW (with the pvpython interpretor commonly installed with it)

- A set of data properly generated by a simulation

{ Optional (if you want to use the Animation builder Python scripts which can build PARAVIEW animations for you)

- python-tk

}

2) Start PARAVIEW

$ paraview

Then you have 2 choices:

You can open the PVD files included in the VTK folder which has been created by MATLAB and then build your own animation if you know about PARAVIEW.

OR

You can use one of our animation-builder script, to do so, clic "Tools->Python Shell". Then choose to run script and select a script corresponding to the type of simulation you ran (they are stored in /matlab/ifs/animation/Python_anim). If you chose fish.conf for the simulation, you should choose AB_Particle_Tracer.py. The script will ask you the path to the simulation result-s folder (the one where the PVD files are). Just set it.

The script will automatically build the animation (you just should edit colors and minor things).

If you want to record the results of your animation as a video , just clic "File -> Save animation".

KNOWN ISSUE :

PARAVIEW doesn-t fully respect the standards and will expect a comma as a separator for the value of a float (for example if your system is in french) the visible effect is that the animation will load the files but the run button will be innefective because all the timesteps will be set to 0 (you can check it out in the information pannel).

To fix it (without changing your whole system language), just run PARAVIEW with the following command line :

env LC_ALL=C LANG=C paraview

==================================================================================================================

PARAVIEW usefull tricks :

==================================================================================================================

Here are some usefull tricks about PARAVIEW :

- The Full HD resolution is 1920*1080

- The Frame rate should always be a 2^N (PARAVIEW issue?)

- To be smooth, an animation should have a frame rate between 16 and 64 fps (under 16 fps the animation will lag, over 64 fps PARAVIEW will compress the images and that will result in bad quality animation). Compression can also occurs when there are many things to be plotted (for example thousands of glyphs, etc. ). To avoid compression, lower the frame rate.

If your data don-t match these values, (for example, your time step dt is very small and you need a low fps because you plot glyphs, this resulting in a very slow motion animation) you should use the temporal interpolator filter of PARAVIEW to artificially increase your dt and letting PARAVIEW interpolate the data values.

 All Files Functions