README.md

   1 </center>
   2
   3 | ![logo](logoSOLVERLAB.png) |
   4 |:--:|
   5 | *SOLVERLAB* |
   6
   7 </center>
   8
   9 Introduction
  10 ------------
  11 SOLVERLAB is a geometrical and numerical C++/Python library designed for numerical analysts who work on the discretisation of partial differential equations on general shapes and meshes and would rather focus on high-level scripting. The goal is to provide simple MATLAB style functions for the generation and manipulation of meshes, fields and matrices. The library is based on the [MEDcoupling](https://docs.salome-platform.org/latest/dev/MEDCoupling/tutorial/index.html) C++/python library of the [SALOME](http://www.salome-platform.org/) project for the handling of meshes and fields, and on the C++ library [PETSC](https://www.mcs.anl.gov/petsc/) for the handling of matrices and linear solvers.
  12
  13 SOLVERLAB includes PDE systems
  14 arising from the modeling of nuclear reactor cores which involves fluid dynamics, heat and neutron diffusion as well as solid elasticity. It
  15 is a simple environment meant at students and researchers for teachind and promote new numerical
  16 methods on general geometries with unstructured meshes.
  17 The main research objectives of SOLVERLAB are the study of
  18
  19 - Numerical schemes for compressible flows at low Mach numbers on general meshes
  20 - Well balanced schemes for stiff source terms (heat source, phase change, pressure losses)
  21 - Numerical handling of flow inversion, phase disappearance and counter-currents in two phase flows
  22 - Numerical handling of stiff porosity or cross section functions
  23 - Schemes that preserve the phasic volume fraction α ∈ [0, 1]
  24 - Convergence of finite volume methods
  25 - New preconditioners for implicit methods for two phase flows
  26 - The coupling of fluid models or multiphysics coupling (eg thermal hydraulics and neutronics or thermal hydraulics and solid thermics)
  27
  28 The library is currently maintained and distributed by the SALOME developpement team on various linux distributions (Ubuntu, CentOS, Fedora, Debian) and on Windows10.
  29 The corresponding binary files can be found  [here](https://www.salome-platform.org/downloads/current-version).
  30
  31 Examples of use
  32 ---------------
  33 - [Examples of stable numerical methods for the 1D linear transport equation](CDMATH/tests/doc/1DTransportEquation/RegularGrid/TransportEquation1D_RegularGrid.ipynb)
  34 - [Shock formation and numerical capture issues for the 1D Burgers' equations](CDMATH/tests/doc/1DBurgersEquation/BurgersEquation1D.ipynb)
  35 - [Influence of the mesh on the convergence and low Mach precision for the UPWIND finite volume method applied to the 2D wave system](CDMATH/tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Upwind_SQUARE.ipynb)
  36 - [Influence of the mesh on the convergence and low Mach precision  for the CENTERED finite volume method applied to the 2D wave system](CDMATH/tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Centered_SQUARE.ipynb)
  37 - [Influence of the mesh on the convergence and low Mach precision  for the STAGGERED finite volume method applied to the 2D wave system](CDMATH/tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Staggered_SQUARE_squares.ipynb)
  38 - [Influence of the mesh on the convergence and low Mach precision  for the PSEUDO-STAGGERED (colocated) finite volume method applied to the 2D wave system](CDMATH/tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_PStag_SQUARE.ipynb)
  39 - [Finite elements for the Poisson problem on a cube in 3D (by S. Kameni Ngwamou, PhD student)](CDMATH/tests/doc/3DPoissonEF/FiniteElements3DPoisson_CUBE.ipynb)
  40 - [Finite elements for the stationary diffusion of the temperature in a 3D room. Influence of the radiator position (by S. Kameni Ngwamou, PhD student)](CDMATH/tests/doc/3DRoomCoolingEF/3DRoomCoolingEF.ipynb)
  41 - [Surface Finite elements for the Poisson-Beltrami problem on a sphere in 3D (by M. Nguemfouo, PhD student)](CDMATH/tests/doc/3DPoissonSphereEF/SynthesisConvergenceFESphere.pdf)
  42 - [Surface Finite elements for the Poisson-Beltrami problem on a torus in 3D (by M. Nguemfouo, PhD student)](CDMATH/tests/doc/3DPoissonTorusEF/SynthesisConvergenceFETorus.pdf)
  43
  44 Download SOLVERLAB sources to compile
  45 ----------------------------------
  46
  47 Create your source directory. For instance:
  48 * `mkdir ~/workspace/SOLVERLAB`
  49 * `cd ~/workspace/SOLVERLAB`
  50
  51 Download from GitHub
  52 * click on the following link : `https://github.com/ndjinga/SOLVERLAB/archive/master.zip`, then unzip the file in a directory SOLVERLAB-master
  53 * or type the following in a terminal : `wget https://github.com/ndjinga/SOLVERLAB/archive/master.zip`, then unzip the file in a directory SOLVERLAB-master
  54 * or clone the git repository to a folder SOLVERLAB-master:  `git clone https://github.com/ndjinga/SOLVERLAB.git SOLVERLAB-master`
  55
  56
  57 Set the environment for the compilation of SOLVERLAB
  58 ---------------------------------------------
  59 Dependencies. The following package list is sufficient on Ubuntu 14.04, Ubuntu 16.04, Ubuntu 18.04 :
  60
  61  - `cmake3` (mandatory)
  62  - `g++` or another C++ compiler (mandatory)
  63  - `python-dev`, `python-numpy` and `swig3`for python scripts (mandatory)
  64  - `python-matplotlib` and `paraview` for postprocessing tools such as plotting curves (matplotlib) or generating 3D view images (paraview) (mandatory)
  65  - `ffmpeg` and `ffmpeg-devel` to generate an animation from a set of curves (optional)
  66  - `doxygen`, `graphviz` and `mscgen`, if you want to generate a nice source code documentation in `~/workspace/SOLVERLAB/SOLVERLAB_install/share/doc/`. Use the compilation option `-DSOLVERLAB_WITH_DOCUMENTATION=ON` (optional).
  67  - `libcppunit-dev`, if you want to generate unit tests. Use the compilation option `-DSOLVERLAB_WITH_TESTS=ON` (optional).
  68  - `rpm`, if you want to generate RPM installation packages. Use the compilation option `-DSOLVERLAB_WITH_PACKAGE=ON` (optional).
  69
  70 Directories. Create the suggested build and installation folders:
  71 * `cd ~/workspace/SOLVERLAB`
  72 * `mkdir SOLVERLAB_build`
  73 * `mkdir SOLVERLAB_install`
  74 * `cd SOLVERLAB_build`
  75
  76
  77 Compile and install SOLVERLAB
  78 --------------------------
  79 Simpler build for a minimum version:
  80 * `cmake ../SOLVERLAB-master/ -DCMAKE_INSTALL_PREFIX=../SOLVERLAB_install -DCMAKE_BUILD_TYPE=Release `
  81 > This will download and build the following dependencies
  82 > - PETSc from http://ftp.mcs.anl.gov/pub/petsc/release-snapshots/petsc-3.15.0.tar.gz
  83 > - SLEPc from https://slepc.upv.es/download/distrib/slepc-3.15.0.tar.gz
  84 > - F2CBLASLAPACK from http://ftp.mcs.anl.gov/pub/petsc/externalpackages/f2cblaslapack-3.4.2.q4.tar.gz
  85 > - HDF5 https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.10/hdf5-1.10.3/src/hdf5-1.10.3.tar.gz
  86 > - MEDFILE from http://files.salome-platform.org/Salome/other/med-4.1.0.tar.gz
  87 > - MEDCOUPLING from http://files.salome-platform.org/Salome/other/medCoupling-9.7.0.tar.gz
  88
  89 If you already have an installation of PETSC, MED and MEDCoupling, you may save computational time and memory by using the advanced build version:
  90 * `cmake ../SOLVERLAB-master -DCMAKE_INSTALL_PREFIX=../SOLVERLAB_install -DCMAKE_BUILD_TYPE=Release -G"Eclipse CDT4 - Unix Makefiles" -D_ECLIPSE_VERSION=4.3 -DSOLVERLAB_WITH_DOCUMENTATION=ON -DPETSC_DIR=${PETSC_DIR} -DPETSC_ARCH=${PETSC_ARCH} -DMEDFILE_ROOT_DIR=${MEDFILE_ROOT_DIR} -DMEDCOUPLING_ROOT_DIR=${MEDCOUPLING_ROOT_DIR}`
  91 > This assumes that you have an existing
  92 > - install of PETSc (with submodules SLEPC and HDF5) at the location given by the environment variable PETSC_DIR and the architecture variable PETSC_ARCH
  93 > See the instructions given in [the official documentation](http://www.mcs.anl.gov/petsc/documentation/installation.html)
  94 > - install of MED                                    at the location given by the environment variable MEDFILE_ROOT_DIR
  95 > - install of MEDCOUPLING                            at the location given by the environment variable MEDCOUPLING_ROOT_DIR
  96
  97 The 3 dependencies PETSC, MED and MEDCOUPLING should have been compiled with the same version of HDF5
  98 Warning : the linux package libhdf5-dev is generally not compatible with the libraries MED and MEDCoupling
  99 Compile and install:
 100 * `make`
 101 * `make install`
 102
 103 Run unit and example tests:
 104 * make example
 105
 106 Run validation tests:
 107 * make validation
 108
 109 Generate documentation of CDMATH module
 110 * make docCDMATH
 111
 112 Generate documentation of CoreFlows module
 113 * make docCoreFlows
 114
 115 Use of SOLVERLAB
 116 -------------
 117
 118 To use SOLVERLAB with your Python code, you can load the SOLVERLAB environment in your terminal using the command
 119  * source `~/workspace/SOLVERLAB/SOLVERLAB_install/env_SOLVERLAB.sh`
 120 Then in your terminal simply type
 121 - `python main.py `
 122
 123 If performance or parallelism is an issue for your simulations, you can use SOLVERLAB librairies with your C++ code :
 124  * C++ libraries: `export LD_LIBRARY_PATH=~/workspace/SOLVERLAB/SOLVERLAB_install/lib`
 125  * To know how to include the right libraries for compilation, see the makefiles of the examples. They include the list ` -lmedC -lmedloader -lmedcoupling -lbase -lmesh -llinearsolver`.
 126
 127 The SOLVERLAB environment variables consist in :
 128  * SOLVERLAB C++ library path: `~/workspace/SOLVERLAB/SOLVERLAB_install/lib`
 129  * SOLVERLAB Python library paths: `~/workspace/SOLVERLAB/SOLVERLAB_install/lib/SOLVERLAB:~/workspace/SOLVERLAB/SOLVERLAB_install/bin/SOLVERLAB`
 130  * PETSc, SLEPc and HDF5 library path: `${PETSC_DIR}/${PETSC_ARCH}/lib`
 131  * MED library path: `${MEDFILE_ROOT_DIR}/lib`
 132  * MEDCOUPLING library path: `${MEDCOUPLING_ROOT_DIR}/lib`
 133