CoreFlows/README.md

   1 CDMATH-CoreFlows
   2 ================
   3
   4 CDMATH-CoreFlows is an open source C++/Python library intended at solving PDE systems
   5 arising from the thermalhydraulics of two phase flows in power plant boilers. It
   6 is a simple environment meant at students and researchers to test new numerical
   7 methods on general geometries with unstructured meshes. It is developped by
   8 CEA Saclay since 2014 and proposes a few
   9 basic models and finite volume numerical methods. Some of the main objectives
  10 are the study of
  11
  12 - Numerical schemes for compressible flows at low Mach numbers
  13 - Well balanced schemes for stiff source terms (heat source, phase change, pressure losses)
  14 - Flow inversion and counter-current two phase flows
  15 - Schemes that preserve the phasic volume fraction α ∈ [0, 1]
  16 - Convergence of finite volume methods
  17 - New preconditioners for implicit methods for two phase flows
  18 - The coupling of fluid models or multiphysics coupling (eg thermal hydraulics and neutronics or thermal hydraulics and solid thermics)
  19
  20 CDMATH-CoreFlows relies on the numerical toolbox [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) of the project [CDMATH](http://cdmath.jimdo.com) for the handling of meshes and fields, and on the library [PETSC](https://www.mcs.anl.gov/petsc/) for the handling of large sparse matrices.
  21 You will need the packages 'doxygen' if you want to generate de documentation and 'swig' if you want to use python scripts.  The software 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 and 29.
  22
  23 User guide
  24 ----------
  25 The user guide is organized as follows :
  26 - [The physical models](./Documentation/PhysicalModels.md)
  27     - [The linear scalar problems](./Documentation/PhysicalModels/ScalarModelsPage.ipynb)
  28         - [The transport equation](./Documentation/PhysicalModels/TransportEq.ipynb) for pure advection phenomena
  29         - [The diffusion equation](./Documentation/PhysicalModels/DiffusionEq.ipynb) for pure diffusion phenomena
  30     - [The compressible Navier-Stokes equations](./Documentation/PhysicalModels/NSModelsPage.ipynb)
  31     - [The two-phase flow models](./Documentation/PhysicalModels/TwoPhasePage.ipynb)
  32         - [The drift model](./Documentation/PhysicalModels/TwoPhase/DriftModelPage.ipynb) with two partial masses, one momentum and one energy equation
  33         - [The isothermal two-fluid model](./Documentation/PhysicalModels/TwoPhase/IsothermalPage.ipynb) with two partial masses and two momentum equations (no energy equation)
  34         - [The five equation two-fluid model](./Documentation/PhysicalModels/TwoPhase/FiveEqPage.ipynb) with two partial masses, two momentum equations and one energy equation
  35 - [Software structure](Documentation/software.md)
  36 - [The numerical methods](Documentation/numericalPage.ipynb)
  37 - [Summary of  available functionalities](Documentation/functionalities.ipynb)
  38 - [CDMATH-CoreFlows example scripts](Documentation/examples.md)
  39
  40 Download and compilation of CDMATH and PETSc
  41 --------------------------------------------
  42 [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) can be downloaded and compiled together with [PETSC](https://www.mcs.anl.gov/petsc/) in a single process, thanks to the cmake option -DCDMATH_WITH_PETSC=ON.
  43 We summarise the installation procedure that you can find in detailed form here
  44 - https://github.com/ndjinga/CDMATH
  45
  46 In order to compile [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) you will need the packages 'cmake', 'gcc', 'gfortran', 'hdf5' plus 'numpy' and 'swig'.
  47 In a linux terminal, first create and access a working directory :
  48 - `mkdir -p ~/workspace/cdmath `
  49 - `cd ~/workspace/cdmath `
  50
  51 Then create build and install repositories:
  52 - `mkdir cdmath_build cdmath_install `
  53
  54 In order to download the approriate branch of [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) either unzip the following file to a directory cdmath-master
  55 - `https://github.com/ndjinga/CDMATH/archive/master.zip`
  56 or clone the git repository to a folder cdmath-master
  57 - `git clone https://github.com/ndjinga/CDMATH.git cdmath-master`
  58
  59 This latter command results in the creation of a directory `~/workspace/cdmath/cdmath-master` containing the source files of [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH).
  60
  61 Go to the build directory
  62 - `cd cdmath_build `
  63
  64 Then run the commands
  65 - `cmake ../cdmath-master/ -DCMAKE_INSTALL_PREFIX=../cdmath_install -DCMAKE_BUILD_TYPE=Release -DCDMATH_WITH_PYTHON=ON -DCDMATH_WITH_PETSC=ON`
  66 - `make`
  67 - `make install`
  68
  69 By default, [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) will compile a new sequential installation of [PETSC](https://www.mcs.anl.gov/petsc/). If an installation of [PETSC](https://www.mcs.anl.gov/petsc/) (version 3.4 or later) is already available in the system, it is possible to save time by first setting the environment variables PETSC_DIR and PETSC_ARCH to the appropriate values as can be found in petscconf.h, and then running the above cmake command.
  70
  71 Download and compilation of CoreFlows
  72 ---------------------------------------------
  73 First create and access a working directory :
  74 - `mkdir -p ~/workspace/CDMATH-CoreFlows `
  75 - `cd ~/workspace/CDMATH-CoreFlows `
  76 Now create build and install repositories:
  77 - `mkdir CDMATH-CoreFlows_build CDMATH-CoreFlows_install `
  78
  79 In order to download CDMATH-CoreFlows either unzip the following file to a directory CDMATH-CoreFlows-master
  80 - `https://github.com/ndjinga/CDMATH-CoreFlows/archive/master.zip`
  81 or clone the git repository to a folder CDMATH-CoreFlows-master
  82 - `git clone https://github.com/ndjinga/CDMATH-CoreFlows.git CDMATH-CoreFlows-master`
  83 Either of these latter commands results in the creation of a directory `~/workspace/CDMATH-CoreFlows/CDMATH-CoreFlows-master`  containing the source files.
  84
  85 In the following steps we assume that [PETSC](https://www.mcs.anl.gov/petsc/) (version 3.4 or more recent) has been installed with CDMATH with the process described above.
  86 You need to set the following variables
  87 - `CDMATH_INSTALL`, the path to your CDMATH installation, for example  `~/workspace/cdmath/cdmath_install//share/petsc-3.8.3 `
  88 - `PETSC_DIR`, the path to your PETSc installation. If [PETSC](https://www.mcs.anl.gov/petsc/) was installed by CDMATH then [CDMATH-Toolbox](https://github.com/ndjinga/CDMATH) can be defined as `~/workspace/cdmath/cdmath_install`
  89 - `PETSC_ARCH`, the type of installation used (usually arch-linux2-c-opt or linux-gnu-c-opt)
  90
  91 In order to do so, it is sufficient to source the 'CDMATH' environment file. Type in you linux terminal
  92 - `source ~/workspace/cdmath/cdmath_install/env_CDMATH.sh`
  93
  94 then create build and install repositories next to CoreFlows-master :
  95 - `mkdir CoreFlows_build CoreFlows_install`
  96
  97 Go to the build directory
  98 - `cd CoreFlows_build `
  99
 100 Then run the command
 101 - `../CDMATH-CoreFlows-master/configure  --prefix=../CDMATH-CoreFlows_install/ --with-petsc-dir=$PETSC_DIR --with-petsc-arch=$PETSC_ARCH --with-cdmath-dir=$CDMATH_INSTALL --with-python --with-doc`
 102 - `make doc install`
 103
 104 You can add the following optional commands
 105 - `--with-gui`, if you want to use CDMATH-CoreFlows as a Salomé module (you will need to use a Salomé shell)
 106 - `--with-debug`, if you want to use CDMATH-CoreFlows in debug mode instead of the default optimised mode
 107
 108 Use of CDMATH-CoreFlows
 109 -----------------------
 110 First load CDMATH-CoreFlows environment from the CoreFlows-master directory
 111 - `source ~/workspace/CDMATH-CoreFlows/CDMATH-CoreFlows_install/env_CoreFlows.sh `
 112
 113 If you use C language: edit the file CoreFlows-master/CoreFlows_src/main.cxx then in a terminal type
 114 - `cd ~/workspace/CDMATH-CoreFlows/CDMATH-CoreFlows_build  `
 115 - `make`
 116 - `make install`
 117 Then you can run the simulation in any directory with the command line
 118 - `$CoreFlows `
 119
 120 If you use python language: edit your own python file `my_file.py` following for example the pattern of the file `CDMATH-CoreFlows-master/main.py`. Then in a terminal type
 121 - `python my_file.py `
 122
 123 If you use the graphic interface, you need to run a [SALOME](https://www.salome-platform.org/) Unix shell
 124 - `./salome shell`
 125 and type the command line
 126 - `runSalome -mCOREFLOWS`
 127 then click on new study to open CoreFlows interface
 128
 129 The complete documentation is available in the directory `~/workspace/CDMATH-CoreFlows/CDMATH-CoreFlows_install/share/doc/`