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:
Send your login to the project administrator: Jacques.Sainte-Marie@inria.fr who will add you to the freshkiss3d group.
Set up your SSH keys on Gitlab using these instructions.
I - Installation¶
I.1 - Get sources from Gitlab repository¶
git clone firstname.lastname@example.org: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.
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
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
Install dependencies in an environment named
conda config --add channels conda-forge conda env create --name fk -f environment.yml
source activate fk
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
This script executes the following commands to configure and build the code:
mkdir build cd build cmake .. make -j 8
cmake .. configures Freshkiss3d to be build in
release mode by default.
To build in
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:
II - Basic examples¶
Example scripts are stored in /freshkiss3d/examples subfolders, namely:
To run an example, simply run the script with python in examples subfolders:
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
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
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.
Problem class arguments are completely optional but the following ones are
Primitives, and all boundary conditions.
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
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