Get started

This section covers how to build the code from sources and how to run basic examples. But at first you need a valid account on gitlab.inria.fr to be able to access Freshkiss3D’s Gitlab repository:

I - Installation

I.1 - Get sources from Gitlab repository

git clone git@gitlab.inria.fr:freshkiss3d/freshkiss3d.git

This command will create a /freshkiss3d repository containing all source files of Freshkiss3D code.

I.2 - Install Freshkiss3D’s dependencies

Install SWIG and METIS using your system’s package manager. For example, on Ubuntu type:

sudo apt-get install libmetis-dev swig

On Mac OS with homebrew, type:

brew install metis swig

On RPM based-system (RedHat, Fedora), you have to add RPM Fusion repositories to your system.

For Fedora:

  sudo dnf install \
https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E
%fedora).noarch.rpm

Download latest rpmsphere-release rpm from https://github.com/rpmsphere/noarch/tree/master/r

Install rpmsphere-release rpm:

sudo rpm -Uvh rpmsphere-release*rpm

Finally install the dependencies:

sudo dnf install libmetis-edf-devel swig

Install the Conda package manager using the miniconda installer.

Note

If you want to manage different version of python on the computer, we advice to create en development environment, which contains all your librairies you need. “Conda is an open source package management system and environment management system for installing multiple versions of software packages and their dependencies and switching easily between them.” see Conda documentation for more information.

To do so, first open the freshkiss3d repository:

cd freshkiss3d

Install dependencies in an environment named fk:

conda config --add channels conda-forge
conda env create --name fk -f environment.yml

Activate environment:

source activate fk

Warning

Don’t forget to activate environment each time you want to use Freshkiss3D. Distinguish between the environment fk containing the libraries necessary for the proper functioning of Freshkiss3D and Freshkiss3D containing source codes.

I.3 - Configure & build the code

To build the code, simply run the build_fast.sh bash file in /freshkiss3d repository:

source build_fast.sh

Note

This script executes the following commands to configure and build the code:

mkdir build
cd build
cmake ..
make -j 8

The command cmake .. configures Freshkiss3d to be build in release mode by default. To build in debug, use:

cmake -D CMAKE_BUILD_TYPE=Debug ..

Other usefull CMake commands:

make test
make clean

I.4 - Test freshkiss3d is correctly installed

python -c 'import freshkiss3d'

If this test fails, please add the root of freshkiss3d into PYTHONPATH:

export PYTHONPATH=/root/of/freshkiss3d/on/your/computer:$PYTHONPATH

II - Basic examples

Example scripts are stored in /freshkiss3d/examples subfolders, namely:

  • /freshkiss3d/examples/simulations

  • /freshkiss3d/examples/mesh

  • /freshkiss3d/examples/tutorials

  • /freshkiss3d/examples/paraview

To run an example, simply run the script with python in examples subfolders:

python example_water_drop.py

Note

Each folder contains an /inputs subfolder, where are stored meshes and various input files. An /outputs subfolder will be created to store various outputs such as .vtk or .txt or .h5 files.

III - Simulation set-up

To set-up a simulation using Freshkiss3D’s Python API you only need to write a simple python script in which you start with importating Freshkiss3D package with import freshkiss3D as fk. You can then use Freshkiss3D’s Python API to declare all problem classes and parameters as described in the graph below. Some Problem class arguments are completely optional but the following ones are mandatory: SimuTime, TriangularMesh, Layer, Primitives, and all boundary conditions.

_images/script.png

Python script logic using Freshkiss3D’s Python API. Dashed frames indicates optional components.

This graph showing only basic script logic and this documentation being heavily learn by example oriented, there is no detailed step by step tutorial on how to properly set-up a simulation. Instead user should rely on the Gallery of examples to get ideas and Python API to meet requirement of each class parameters’ type.

IV - Useful optional packages

The main external file needed for your simulation is the mesh which cannot be created within Freshkiss3D as there is no meshing tool included in the package. Creating a mesh might be painful if you’re new to numerical simulation, so we recommend to install gmsh which uses simple .geo files to gerenerate meshes. See the Gallery of examples section for more insight on how to use gmsh with Freshkiss3D.

Postprocessing with matplolib might also be a challenge so we advise to use paraview. It allows powerful python scripting which can be very useful. Many examples in the Gallery of examples. Some examples of using paraview`_are in the subfolder `/freshkiss3d/examples/paraview``. All paraview python scripts are stored in /postpro_paraview. But to use the command pvpython, user must install paraview and check the .bashrc, or .bash_profile… and eventually add the two following lines :

export PATH=/root/of/paraview/on/your/computer:$PATH
export PATH=/root/of/pvpython/on/your/computer:$PATH