.. _Building_from_sources:

******************************************************************************
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:

* Log-in on `gitlab.inria.fr`_ with your inria iLDAP Username or create an account using this `link <https://gitlab-account.inria.fr>`_  if you are an external user.

* 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 <https://docs.gitlab.com/ce/ssh/README.html#ssh>`_.




I - Installation
==============================================================================


I.1 - Get sources from Gitlab repository
------------------------------------------------------------------------------

.. code-block:: bash

    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:

.. code-block:: bash

  sudo apt-get install libmetis-dev swig

On Mac OS with homebrew, type:

.. code-block:: bash

  brew install metis swig

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

For Fedora:

.. code-block:: bash

    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:

.. code-block:: bash

    sudo rpm -Uvh rpmsphere-release*rpm

Finally install the dependencies:

.. code-block:: bash

    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:

.. code-block:: bash

    cd freshkiss3d

Install dependencies in an environment named ``fk``:

.. code-block:: bash
   
   conda config --add channels conda-forge
   conda env create --name fk -f environment.yml

Activate environment:

.. code-block:: bash

   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:

.. code-block:: bash

    source build_fast.sh

.. note::

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

    .. code-block:: bash

        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:

    .. code-block:: bash

        cmake -D CMAKE_BUILD_TYPE=Debug ..

    Other usefull CMake commands:

    .. code-block:: bash

        make test
        make clean

I.4 - Test ``freshkiss3d`` is correctly installed
------------------------------------------------------------------------------

.. code-block:: bash

   python -c 'import freshkiss3d'

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

.. code-block:: bash

   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:

.. code-block:: bash

   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 :ref:`API` you only need to write a
simple python script in which you start with importating Freshkiss3D package
with :code:`import freshkiss3D as fk`. You can then use Freshkiss3D's :ref:`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.

.. figure:: _static/images/script.png
    :width: 900px
    :align: center

    Python script logic using Freshkiss3D's :ref:`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 :ref:`gallery_of_examples` to get ideas and :ref:`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 :ref:`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 :ref:`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 :

.. code-block:: bash

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


.. _gitlab.inria.fr: https://gitlab.inria.fr
.. _freshkiss3d: http://gforge.inria.fr/projects/freshkiss3d
.. _freshkiss3d-dat: http://gforge.inria.fr/projects/freshkiss3d-dat
.. _gforge: http://gforge.inria.fr
.. _Conda: http://conda.pydata.org
.. _miniconda: http://conda.pydata.org/miniconda.html
.. _conda cheat sheet: http://conda.pydata.org/docs/_downloads/conda-cheatsheet.pdf
.. _conda-forge: https://conda-forge.github.io
.. _gmsh: http://gmsh.info/
.. _paraview: https://www.paraview.org/