Read Me

PaRiDeS (Parallel Real-time Deformation Simulator)
==================================================

System requirements
-------------------

The PaRiDeS allows to run simulation with both off-line and on-line precomputation. To use on-line precomputation on complex models, it is necessary to use tens of processor cores, needing to use large SMP or cluster. If the off-line precomputation is utilized, it is possible to run PaRiDeS at single-processor machine in few processes (the architecture of simulation is same, but the slave processes only loads precomputed states from disk, thus are not computationally demanding and does not to be executed in high number).

The process with MPI rank equal to zero runs graphic and haptic interface -- i.e. it has to run at machine with haptic device and display attached.

The haptic device has to be compatible with OpenHaptics 2.0 or newer.

Installation
------------

Prerequisites:
- gFortran
- MPI (tested with MPICH implementation)
- OpenHaptics (2.0, at x86_64 3.0 or newer)
- OGRE 3D (1.4 or newer, tested with 1.7), download: http://www.ogre3d.org/download/source
- ATLAS, download: http://sourceforge.net/projects/math-atlas/files/
- MUMPS (4.8.4 or newer), download: http://graal.ens-lyon.fr/MUMPS/index.php?page=dwnld
- GetFEM (3.1 or newer), download: http://download.gna.org/getfem/html/homepage/download.html

Build:
- customize pathes to libraries in Makefile
- run make

Running tests
-------------
- set LD_LIBRARY_PATH to include all necessary pathes
- run the ./simulator -c input/liver501 in MPI environment (the graphic and haptic interface runs at machine with rank 0), e.g. mpirun -np 32 ./simulator
- for off-line precomputation, the ./simulator -o directory runs PaRiDeS using precomputed data stored in directory

Configuration
-------------
The example of deformable body (human liver) is in input directory. It is defined by several files:
- liver501.mesh defines 3D mesh structure consisting of tetrahedrons
- liver501.faces defines which faces of the mesh makes its surface
- liver501_fixed16.mat defines, which nodes of the liver are fixed in the space (address DOFs instead of nodes, the translation can be made using allDofCoords file generated by first run of PaRiDeS with given mesh)
- liver501_disp1_13.mat defines the node which is displaced by haptic device
- nonlinear_liver.param configures, which files are used, the material and numerical method properties (simulation configuration file)

How to generate data for off-line interpolation?
------------------------------------------------
- set SAVE_RESULT to 1 in simulation configuration file and DIR_OUT to directory where precomputed states will be stored
- set cloud to large size (e.g. 10)
- run simulator without any haptic movement (the device can be unplugged)
- if the PaRiDeS is executed at distributed environment without shared file system, collect files from directories for output states in particulat machines