4 CDMATH is a geometrical and numerical toolbox 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 library originates from [CDMATH](http://cdmath.jimdo.com), a collaborative workgroup with the same name. It 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. The library is currently developed for linux distributions and is maintained on Ubuntu 14.04 LTS, 16.04 LTS and 18.04 LTS, as well as on Fedora 24, 26, 28, 30 and 32.
6 - [The physical models](./Documentation/PhysicalModels.md)
7 - [The linear scalar problems](./Documentation/PhysicalModels/ScalarModelsPage.ipynb)
8 - [The transport equation](./Documentation/PhysicalModels/TransportEq.ipynb) for pure advection phenomena
9 - [The diffusion equation](./Documentation/PhysicalModels/DiffusionEq.ipynb) for pure diffusion phenomena
10 - [The compressible Navier-Stokes equations](./Documentation/PhysicalModels/NSModelsPage.ipynb)
11 - [The two-phase flow models](./Documentation/PhysicalModels/TwoPhasePage.ipynb)
12 - [The drift model](./Documentation/PhysicalModels/TwoPhase/DriftModelPage.ipynb) with two partial masses, one momentum and one energy equation
13 - [The isothermal two-fluid model](./Documentation/PhysicalModels/TwoPhase/IsothermalPage.ipynb) with two partial masses and two momentum equations (no energy equation)
14 - [The five equation two-fluid model](./Documentation/PhysicalModels/TwoPhase/FiveEqPage.ipynb) with two partial masses, two momentum equations and one energy equation
15 - [Software structure](Documentation/software.md)
16 - [Summary of available functionalities](Documentation/functionalities.ipynb)
17 - [Some example scripts](Documentation/examples.md)
21 - [Examples of stable numerical methods for the 1D linear transport equation](tests/doc/1DTransportEquation/RegularGrid/TransportEquation1D_RegularGrid.ipynb)
22 - [Example of stable numerical scheme for the 1D heat equation](tests/doc/1DHeatEquation/HeatEquation1D_RegularGrid.ipynb)
23 - [Examples of unstable numerical methods for the 1D linear transport equation](tests/doc/1DTransportEquation/UnstableSchemes/TransportEquation1D_UnstableSchemes.ipynb)
24 - [Shock formation and numerical capture issues for the 1D Burgers' equations](tests/doc/1DBurgersEquation/BurgersEquation1D.ipynb)
25 - [Numerical convergence and maximum principle analysis for the linear finite element method applied to the 2D Poisson equation](tests/doc/2DPoissonEF/Convergence_Poisson_FE_SQUARE.ipynb)
26 - [Numerical convergence analysis for the FV5 finite volume method applied to the 2D Poisson equation](tests/doc/2DPoissonVF/Convergence_Poisson_FV5_SQUARE.ipynb)
27 - [Numerical convergence analysis for the linear finite element and FV5 finite volume methods applied to the 2D Poisson equation with discontinuous boundary conditions](tests/doc/2DPoisson_StiffBC_DISK/2DPoisson_StiffBC_DISK.ipynb)
28 - [Numerical convergence analysis for the FV5 finite volume method applied to a 2D anisotropic diffusion equation](tests/doc/2DDiffusionVF/Convergence_Diffusion_FV5_SQUARE.ipynb)
29 - [Influence of the mesh on the convergence and low Mach precision for the UPWIND finite volume method applied to the 2D wave system](tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Upwind_SQUARE.ipynb)
30 - [Influence of the mesh on the convergence and low Mach precision for the CENTERED finite volume method applied to the 2D wave system](tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Centered_SQUARE.ipynb)
31 - [Influence of the mesh on the convergence and low Mach precision for the STAGGERED finite volume method applied to the 2D wave system](tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_Staggered_SQUARE_squares.ipynb)
32 - [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](tests/doc/2DWaveSystemVF_stationary/Convergence_WaveSystem_PStag_SQUARE.ipynb)
33 - [Finite elements for the Poisson problem on a cube in 3D (by S. Kameni Ngwamou, PhD student)](tests/doc/3DPoissonEF/FiniteElements3DPoisson_CUBE.ipynb)
34 - [Finite elements for the stationary diffusion of the temperature in a 3D room. Influence of the radiator position (by S. Kameni Ngwamou, PhD student)](tests/doc/3DRoomCoolingEF/3DRoomCoolingEF.ipynb)
35 - [Surface Finite elements for the Poisson-Beltrami problem on a sphere in 3D (by M. Nguemfouo, PhD student)](tests/doc/3DPoissonSphereEF/SynthesisConvergenceFESphere.pdf)
36 - [Surface Finite elements for the Poisson-Beltrami problem on a torus in 3D (by M. Nguemfouo, PhD student)](tests/doc/3DPoissonTorusEF/SynthesisConvergenceFETorus.pdf)
38 Download CDMATH sources to compile
39 ----------------------------------
41 Create your source directory. For instance:
42 * `mkdir ~/workspace/cdmath`
43 * `cd ~/workspace/cdmath`
46 * click on the following link : `https://github.com/ndjinga/CDMATH/archive/master.zip`, then unzip the file in a directory cdmath-master
47 * or type the following in a terminal : `wget https://github.com/ndjinga/CDMATH/archive/master.zip`, then unzip the file in a directory cdmath-master
48 * or clone the git repository to a folder cdmath-master: `git clone https://github.com/ndjinga/CDMATH.git cdmath-master`
51 Set environment for the compilation of CDMATH
52 ---------------------------------------------
53 Dependencies. The following package list is sufficient on Ubuntu 14.04, Ubuntu 16.04, Ubuntu 18.04 :
55 - `cmake3` (mandatory)
56 - `g++` or another C++ compiler (mandatory)
57 - `python-dev`, `python-numpy` and `swig`, if you want to use CDMATH commands in Python scripts. Use the compilation option `-DCDMATH_WITH_PYTHON=ON`. (highly recommended)
58 - `python-matplotlib` and `paraview` for postprocessing tools such as plotting curves (matplotlib) or generating 3D view images (paraview). Use the compilation option `-DCDMATH_WITH_POSTPRO=ON` (recommended).
59 - `jupyter`, in order to generate and visualise nice reports from test case simulations (optional)
60 - `doxygen`, `graphviz` and `mscgen`, if you want to generate a nice source code documentation in `~/workspace/cdmath/cdmath_install/doc/`. Use the compilation option `-DCDMATH_WITH_DOCUMENTATION=ON` (optional).
61 - `libcppunit-dev`, if you want to generate unit tests. Use the compilation option `-DCDMATH_WITH_TESTS=ON` (optional).
62 - `rpm`, if you want to generate RPM installation packages. Use the compilation option `-DCDMATH_WITH_PACKAGE=ON` (optional).
64 Directories. Create the suggested build and installation folders:
65 * `cd ~/workspace/cdmath`
66 * `mkdir cdmath_build`
67 * `mkdir cdmath_install`
71 Compile and install CDMATH
72 --------------------------
73 Simpler build for a minimum version:
74 * `cmake ../cdmath-master/ -DCMAKE_INSTALL_PREFIX=../cdmath_install -DCMAKE_BUILD_TYPE=Release -DCDMATH_WITH_PETSC=ON -DCDMATH_WITH_PYTHON=ON `
75 > This will download and build the following dependencies
76 > - PETSc from http://ftp.mcs.anl.gov/pub/petsc/release-snapshots/petsc-3.13.2.tar.gz
77 > - SLEPc from https://slepc.upv.es/download/distrib/slepc-3.13.2.tar.gz
78 > - HDF5 http://files.salome-platform.org/Salome/other/med-4.0.0.tar.gz
79 > - MEDFILE from http://files.salome-platform.org/Salome/other/med-4.0.0.tar.gz
80 > - MEDCOUPLING from http://files.salome-platform.org/Salome/other/medCoupling-9.4.0.tar.gz
82 Advanced build for an all-options version:
83 * `cmake ../cdmath-master -DCMAKE_INSTALL_PREFIX=../cdmath_install -DCMAKE_BUILD_TYPE=Release -G"Eclipse CDT4 - Unix Makefiles" -D_ECLIPSE_VERSION=4.3 -DCDMATH_WITH_PETSC=ON -DCDMATH_WITH_PYTHON=ON -DCDMATH_WITH_POSTPRO=ON -DCDMATH_WITH_TESTS=ON -DCDMATH_WITH_DOCUMENTATION=ON -DPETSC_DIR=${PETSC_DIR} -DMEDFILE_ROOT_DIR=${MEDFILE_ROOT_DIR} -DMEDCOUPLING_ROOT_DIR=${MEDCOUPLING_ROOT_DIR}`
84 > This assumes that you have an existing
85 > - install of PETSc (with submodules SLEPC and HDF5) at the location given by the environment variable PETSC_DIR and the architecture variable PETSC_ARCH
86 > See the instructions given in [the official documentation](http://www.mcs.anl.gov/petsc/documentation/installation.html)
87 > - install of MED at the location given by the environment variable MEDFILE_ROOT_DIR
88 > - install of MEDCOUPLING at the location given by the environment variable MEDCOUPLING_ROOT_DIR
90 The 3 dependencies PETSC, MED and MEDCOUPLING should have been compiled with the same version of HDF5
91 Warning : the linux package libhdf5-dev is generally not compatible with the libraries MED and MEDCoupling
96 Run unit and example tests:
104 We recommend using CDMATH in python scripts which avoids the hassle of having to edit Makefile files and compiling every C++ scripts.
106 To use CDMATH with your Python code, you can load the CDMATH environment in your terminal using the command
107 * source `~/workspace/cdmath/cdmath_install/env_CDMATH.sh`
108 Then in your terminal simply type
111 If performance or parallelism is an issue for your simulations, you can use CDMATH librairies with your C++ code :
112 * C++ libraries: `export LD_LIBRARY_PATH=~/workspace/cdmath/cdmath_install/lib`
113 * 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`.
115 The CDMATH environment variables consist in :
116 * CDMATH C++ library path: `~/workspace/cdmath/cdmath_install/lib`
117 * CDMATH Python library paths: `~/workspace/cdmath/cdmath_install/lib/cdmath:~/workspace/cdmath/cdmath_install/bin/cdmath`
118 * PETSc, SLEPc and HDF5 library path: `${PETSC_DIR}/${PETSC_ARCH}/lib`
119 * MED library path: `${MEDFILE_ROOT_DIR}/lib`
120 * MEDCOUPLING library path: `${MEDCOUPLING_ROOT_DIR}/lib`
122 Create Linux installation packages for CDMATH
123 ---------------------------------------------
124 After popular request, here is how you can create packages for Debian and Red Hat-based Linux distributions:
126 1. Download CDMATH as explained hereabove.
127 2. Set the environment as explained hereabove (in particular, make sure you have `rpm` installed).
128 3. Generate a makefile with `cmake -DCMAKE_INSTALL_PREFIX=../cdmath_install -DCMAKE_BUILD_TYPE=Release -DCDMATH_WITH_PACKAGE=ON ../cdmath-master/` and eventually other options (documentation, tests, swig, etc).
129 4. Compile with `make package`.
131 You will then find a Debian package in the build directory; you may install it on Ubuntu 14.04 or Ubuntu 16.04. You will also find an RPM package, which you may install on Red Hat-based distributions. This way, the packages you generate may include all the compilation options you want.
133 Unfortunately, the Debian package may be said to be of “bad quality” for Debian standards as far as ownership is concerned. This is true and due to limitations in CMake/CPack. The package should still install nonetheless.
