# __CUMIN:__ Curved Meshes In Numerical simulations

@author Charles Pierre [![](https://img.shields.io/badge/homepage-blue)](https://cpierre1.perso.univ-pau.fr)

__CUMIN is a finite element library__ including
  - finite elements of order \f$ \ge \f$ 1,
  - curved geometries: meshes of geometrical degrree \f$ \ge \f$ 1,
  - facilities for diffusion and linear elasticity PDEs

- Language: modern Fortran
- API documentation: [![](https://img.shields.io/badge/API-doc-blue.svg)](https://cpierre1.pages.math.cnrs.fr/cumin/index.html)


### SOME ILLUSTRATIONS  
<table border="0">
 <tr>
    <td style="width:250px">
        <img src="https://cpierre1.pages.math.cnrs.fr/cumin/poisson_sphere.png" width="150px" />
    </td>
    <td><b style="font-size:15px">Poisson problem on a sphere</b>

    \f$ ~~~~~~~~~~-~~~ {\large   \Delta_B u  + u= f    \qquad {\rm 
    on} \quad \Omega}\f$

    -  Quadratic mesh of the unit sphere \f$\Omega\f$ with 47 curved triangles,

    -  \f$ P^3 \f$ finite element,

    - \f$ \Delta_B \f$ the Laplace Beltrami operator

    - A posteriori error \f$ \| u - u_h^l \|_{{\rm L}^2(\Omega)} = 0.02 \f$, <br> 
      using a lift \f$u_h^l\f$ of the numerical 
      solution \f$u_h\f$ on the sphere.

    </td>
 </tr>

 <tr>
    <td style="width:250px">
        <img src="https://cpierre1.pages.math.cnrs.fr/cumin/Poisson_disk_Ventcel.png" width="150px%"/>
    </td>
    <td><b style="font-size:15px">Poisson problem on a disk 
    with 2\f$^{\rm nd}\f$ order boundary conditions</b>
    <br>
    \f$ \quad\quad\quad\quad   {\large   \displaystyle{
    \begin{array}{lcl}
      -\Delta u = f    \quad & {\rm on}\quad & \Omega
      \\    
      -\Delta_B u  + \nabla u\cdot n + u= g
      \quad & {\rm on}\quad & \partial\Omega
    \end{array}
    }  }\f$

    -  Quadratic mesh of the unit disk \f$\Omega\f$ with 15 curved triangles,

    -  \f$ P^3 \f$ finite element,

    - A posteriori error \f$ \| u - u_h^l \|_{{\rm L}^2(\Omega)} = 4.1E-3 \f$, <br> 
      using a lift \f$u_h^l\f$ of the numerical 
      solution \f$u_h\f$ on the disk.

    </td>
 </tr>


 <tr>
    <td style="width:250px">
        <img src="https://cpierre1.pages.math.cnrs.fr/cumin/eigenValues_torus.png" width="150px"/>
    </td>
    <td><b style="font-size:15px">Laplace eignefunction on a torus </b>
    <br>

    \f$ ~~~~~~~~~~-~~~ {\large   \Delta_B u  = \lambda u    \qquad {\rm 
    on} \quad \Omega}\f$

    -  Quadratic mesh of a torus \f$\Omega\f$ 

    -  \f$ P^3 \f$ finite element,

    </td>
 </tr>


</table>


### 1 INSTALLATION
- Get the sources [![](https://img.shields.io/badge/here-blue)](https://plmlab.math.cnrs.fr/cpierre1/cumin)
- Installation requires _make_ and _cmake_

1. Move to your project directory and configure with
   ```bash
   cd your_cumin_dir && mkdir build && cd build
   cmake ..
   ```

2. Build with
   ```bash
   make all 
   ```

3. Test with
   ```bash
   ctest 
   ```

4. Defince your installation directory  and install with 
   ```bash
   cmake .. -DCMAKE_INSTALL_PREFIX=your_install_dir
   make install
   ```

#### 1.1 Configuration variables
Configuration variables are set to default values, 
they can be edited and modified wirh 
   ```bash
   ccmake ..
   ```

| Variable  | Desscription  | Default |
| :-- | :-- | :-- |
| DEBUG      | Level of  debug   | 0 |
| REAL_PRECISION  | Real precision   | 8  |
| RUN_INTEG_TESTS | Run integration tests on top of unit tests | OFF  |

#### 1.2 Dependances

| Dependance |     | 
| :-- | :--  |
| OpenMP      | Shared memory parallelism   |
| Blas/lapack |                          |     
| Arpack      | Eigenvalue problem solver     |
| SCOTCH      | Graph reordering           |   
| MUMPS       | Direct linear system solver    |
| GMSH        | Meshing and visualisation  |
| MMG         | Remeshining   |

  - Cumin  dependances are searched when configuring, 
    if not found they are disabled. <br>
    Without any dependencies, you still can install, 
    run the unit tests (tutorial examples and integration tests require GMSH).
  - You can turn-off any dependance using ``ccmake .. ``.
  - Some dependancies are not available when REAL_PRECISION is not set to 8.
  - If not found, you may reset your installation general directory
   ```bash
   cmake .. -DUSER_PREFIX_PATH=your_dependancies_install_dir
   ```
   which can also be reset using _ccmake_
  - More specifically, each dependance has its own  installation directory
    variable, which can be reset with (fer e.g. MUMPS)
   ```bash
   cmake .. -DDIR_MUMPS=your_MUMPS_install_dir
   ```
   which procedure can also be done using _ccmake_ in advanced mode.


### 2 INSTALLATION WITH GUIX

You can avoid to install the dependances using the guix environment.
Guix moreover guarantees fully reproducable results.
<br>
For this you first need to: [![](https://img.shields.io/badge/install-guix-blue.svg)](https://guix.gnu.org/manual/fr/html_node/Installation.html), thzn:

  - update your guix deposit,
   ```bash
   guix pull
   ```
  - open the following guix shell for cumin installation,
   ```bash
   guix shell --pure   arpack-ng mumps openmpi scotch32 mmg mmg:lib gmsh make cmake gcc-toolchain  gfortran-toolchain coreutils sed doxygen -- /bin/bash --norc
   ```
  - configure, build and install with,
   ```bash
   cd your_cumin_dir && mkdir build && cd build
   cmake ..
   make all install
   ```


### 3 TUTORIAL EXAMPLES
- Various tutorial examples are provided in the directory _examples_.
- Try e.g.
  ```bash
  cd build
  make poisson_2d_Neumann_0_expl 
  ./examples/poisson_2d_Neumann_0_expl
  ```
  that compiles and executes the program _poisson_2d_Neumann_0_exp.F90_ 
  which solves a Poisson problem and visualise its solution.
- Tutorial examples are documented in the API documentation 
  [![](https://img.shields.io/badge/API-doc-blue.svg)](https://cpierre1.pages.math.cnrs.fr/cumin/index.html).


### 4 UTILISATION
- To use the cumin library, your fortran codes should look like this:
  ```F90
  program my_program
    use cumin
    ...
  ```
- Linking at compilation is handled with _cmake_ as follows.
  1. In your own project directory, copy the following lines to your
     _CMakeLists.txt_:
  ```cmake
  set(CUMIN_INSTALL_DIR "your_cumin_install_dir" CACHE STRING "")
     if(EXISTS "${CUMIN_INSTALL_DIR}/Findcumin.cmake")
       list(APPEND CMAKE_MODULE_PATH ${CUMIN_INSTALL_DIR}) 
       find_package(cumin)
     else()
       message(FATAL_ERROR "Not found: Findcumin.cmake, reset 'CUMIN_INSTALL_DIR'")
     endif()
  ```
  2. create a target for your code and link it with cumin:
  ```cmake
     add_executable(target_name program_name.F90)
     target_link_libraries(target_name cumin)
  ```
  3. compilation is then done as usual with
  ```bash
     make target_name
  ```

<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>