Update documentation

README.md

@@ -1,2 +1,25 @@
-# ECOGEN
-A CFD open source code dedicated to multiphase compressible flows
+ECOGEN
+======
+
+**ECOGEN** is a CFD plateform written in C++ object oriented programming langage. It is dedicated to numerical simulation of compressible multiphase flows. It has the vocation to share academics researches in the multiphase flow field in direction to ohter academics but also for industrials, students, etc.
+
+* Official webSite: https://code-mphi.github.io/ECOGEN/
+* Official documentation: https://code-mphi.github.io/ECOGEN/docs/sphinx_docs/index.html
+* API documentation: https://code-mphi.github.io/ECOGEN/docs/doxygen_docs/index.html
+
+What can I do with ?
+--------------------
+With **ECOGEN** you can solve:
+
+* Interface problems between pure or multicomponents fluids and mixtures of multiphase flows.
+* Flow problems involving surface tension, heat and mass transfers for evaporating and condensing flow, cavitation.
+* Wave propagation problems in strongly unsteady situations using a specific Adaptative Mesh Reffinement.
+* complex flow problems on unstructured grids.
+
+Visit the gallery for examples: https://code-mphi.github.io/ECOGEN/gallery/
+
+Start with ECOGEN
+-----------------
+The better way to start with **ECOGEN** is to follow installation instructions on the official documentation webSite: https://code-mphi.github.io/ECOGEN/docs/sphinx_docs/Chap2_installation_Chapter.html
+
+Then you can follow the dedicated tutorial to run your first test: https://code-mphi.github.io/ECOGEN/docs/sphinx_docs/Chap4_1startWithECOGEN.html

docs/sphinx_docs/source/Biblio.bib

@@ -1,4 +1,13 @@
 % Encoding: UTF-8
+
+@article{euler1757principes,
+  title={Principes g{\'e}n{\'e}raux du mouvement des fluides},
+  author={Euler, Leonhard},
+  journal={M{\'e}moires de l'Acad{\'e}mie des Sciences de Berlin},
+  pages={274--315},
+  year={1757}
+}
+
 @article{pishchalnikov2019lowintensity,
   title={High-speed video microscopy and numerical modeling of microbubbles driven by low-intensity ultrasound and targeting urinary stones},
   author={Pishchalnikov, Y. A. and Behnke-Parks, W. and Schmidmayer, K. and Maeda, K. and Colonius, T. and Kenny, T. and Laser, D. J.},
@@ -7,7 +16,7 @@ @article{pishchalnikov2019lowintensity
 }
 
 @Article{schmidmayer2019adaptive,
-  author    = {Schmidmayer, Kevin and Petitpas, Fabien and Daniel, Eric},
+  author    = {Schmidmayer, K. and Petitpas, F. and Daniel, E.},
   title     = {Adaptive Mesh Refinement algorithm based on dual trees for cells and faces for multiphase compressible flows},
   journal   = {Journal of Computational Physics},
   year      = {2019},
@@ -2712,6 +2721,13 @@ @Book{toro97
   address =  {Berlin}
 }
 
+@book{toro2013riemann,
+  title={Riemann solvers and numerical methods for fluid dynamics: a practical introduction},
+  author={Toro, Eleuterio F},
+  year={2013},
+  publisher={Springer Science \& Business Media}
+}
+
 @Article{toumi,
   author =   {I. Toumi},
   title =    { A weak formulation of \textsc{R}oe's approximate \textsc{R}iemann solver},

docs/sphinx_docs/source/Introduction.rst → docs/sphinx_docs/source/Chap1_introduction.rst

@@ -8,7 +8,7 @@ ECOGEN is a CFD plateform written in C++ object oriented programming langage. It
 - multi-meshes (Cartesian, unstructured, AMR)
 - multi-CPU
 
-ECOGEN is for:
+ECOGEN stands for:
 
 - **E**\ volutive: makes easier future developpements
 - **C**\ ompressible: dedicated to compressible flows
@@ -37,9 +37,9 @@ What is a diffuse interface? In DIM theory, the interfaces between pure phases a
 
 .. _Fig:introduction:diffInterface:
 
-.. figure:: ./img/diffInterface.png
+.. figure:: ./_static/intro/diffInterface.png
 
-	1D extraction of the diffuse interface zone of a water droplet.
+  1D extraction of the diffuse interface zone of a water droplet.
 
 This way is possible thanks to a thermodynamical consistency. Then, the flow solution does no longer requires interface tracking algorithms: It became easy to simulate complex topological shape evolutions between miscible or non miscible fluid. Moreover, pressure waves (shock waves, acoustic waves) can propagate and interact properly in the whole flow.
 

docs/sphinx_docs/source/Start.rst → docs/sphinx_docs/source/Chap2_1installation.rst

@@ -9,7 +9,7 @@ ECOGEN required two mandatory components to be installed on your Ubuntu system :
 
 Installing C++ compiler
 ~~~~~~~~~~~~~~~~~~~~~~~
-Nothing is more easy than installing C and C++ compiler on Ubuntu. In your temrminal just enter the following commands:
+Nothing is more easy than installing C and C++ compiler on Ubuntu. In your terminal just enter the following commands:
 
 .. highlight:: console
 
@@ -44,8 +44,7 @@ Prepare the environnement for using your favorite compiler:
 	export CC=gcc 
 	export CXX=g++ 
 
-Configure and proceed to the installation (you can choose a different directory):
-.. highlight:: console
+Configure and proceed to the installation (you can choose a different directory). The "make" step should take some times (coffee time ?):
 
 .. highlight:: console
 
@@ -81,7 +80,22 @@ If the installation succeed you should use the mpicxx command in your terminal.
 Download
 ========
 
-The last ECOGEN version can be downloaded from Git-hub. The source files are available at the following address: https://github.com/code-mphi/ECOGEN
+The last ECOGEN version can be downloaded from Git-hub. The source files are available at the following address: https://github.com/code-mphi/ECOGEN. 
+
+The package includes:
+
+* ECOGEN/src/ folder including C++ source files.
+* ECOGEN/libMeshes/ folder including examples of unstructured meshes in *.geo* format (gmsh files version 2). See section :ref:`Sec:tuto:generatingMeshes` for details.
+* ECOGEN/libEOS/ folder including some possible parameters for Equation of State in XML files. See section :ref:`Sec:IO:materials` for details.
+* ECOGEN/libTests folder including:
+
+	- ECOGEN/libTests/referenceTestCases/ folder organized in a test cases library according the flow model (Euler Equations ECOGEN solver, Kapila's model for multiphase flow ECOGEN solver, Homogeneous Euler Equation ECOGEN solver, etc.). A detailed list of available test cases is proposed in section :ref:`Chap:TestCases`.
+	- 4 quick-manual XML files to create a new flow calculation with ECOGEN.
+* *ECOGEN.xml* main entry file to select running cases.
+* *Makefile*: for compilation in Unix environment. This file may require some adaptation to the user's environment.
+* *LICENSE*, *COPYRIGHT* and *AUTHORS*: Information files about authors and licensing.
+* *README.md*: Information file.
+* *ECOGEN_documentation.pdf*: The full documentation for ECOGEN.
 
 Compilation/Execution on bash
 =============================
@@ -102,7 +116,25 @@ Executing ECOGEN is really easy on bash (XX is the number of CPU required for ex
 
 	mpirun -np XX ECOGEN
 
-ECOGEN is including a given number of simple prebuild test cases. Each test can be used as a basis for a new one. In the downloaded version, when executing ECOGEN, a simple default test case is running and you should see informations about the test output appering in the terminal output.
+Testing
+=======
+
+Once preceding compiling of the code succeed, the better way to test ECOGEN's installation is to run successively the two simple following commands:
+
+.. highlight:: console
+
+::
+
+	./ECOGEN
+	mpirun -np 2 ECOGEN
+
+This will run the default test case included in the package two times:
+
+* In sequential (single CPU). 
+* In parallele using 2 CPU.
+
+This should print informations in the terminal on the running default test case. If no error message appears, then your installation should be OK. You should use ECOGEN for your own applications.
 
+ECOGEN is including a given number of simple prebuild test cases. Each test can be used as a basis for a new one. Visit the tutorial section :ref:`Chap:Tutorials` for more informations.
 
 .. _openMPI: https://www.open-mpi.org/

docs/sphinx_docs/source/Chap2_installation_Chapter.rst

@@ -0,0 +1,12 @@
+.. _Chap:Start:
+
+Installation instructions
+=========================
+
+This section contains basic instruction for ECOGEN installation on windows / ubuntu systems.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   Chap2_1installation

docs/sphinx_docs/source/Model.rst → docs/sphinx_docs/source/Chap3_1_2model.rst

@@ -85,7 +85,7 @@ Source terms
 
 The additional :xml:`<sourceTerms>` markup can be used to numerically integrate some source terms in the equations. The attribute :xml:`type` selects the source term:
 
-- *heating*: related to a thermal energy heating/cooling. This attribute requires the :xml:`<dataHeating>` node with the attribute :xml:`volumeHeatPower`: a real number corresponding to the power by volume unit added to the flow (unit :W/m3 (SI)).
+- *heating*: related to a thermal energy heating/cooling. This attribute requires the :xml:`<dataHeating>` node with the attribute :xml:`volumeHeatPower`: a real number corresponding to the power by volume unit added to the flow (unit: W/m3 (SI)).
 
 .. code-block:: xml
 

docs/sphinx_docs/source/Mesh.rst → docs/sphinx_docs/source/Chap3_1_3mesh.rst

@@ -97,11 +97,11 @@ Unstructured mesh
 When dealing with unstructured meshes, the :xml:`<unstructuredMesh>` markup **must be** present in the *meshV5.xml* input file and contains the following nodes:
 
 - :xml:`<file>`: this **mandatory** node specifies the path of the mesh file via the attribute :xml:`name`. The file must be located in the folder **ECOGEN/libMeshes/**.
-- :xml:`<modeParallele>`: This node is required only if the file mesh is a multi-CPU file. The attribute :xml:`GMSHPretraitement` can take the following values:
+- :xml:`<modeParallele>` : This node is required only if the file mesh is a multi-CPU file. The attribute :xml:`GMSHPretraitement` can take the following values:
 	- *true*: ECOGEN automatically splits the given mesh file in as many as necessary files according to the number of available CPUs.
 	- *false*: do not redo the split of the given mesh (which has already been split in a precedent simulation).
 
-**Remark:**
+**Remarks:**
 
 1. The attribute :xml:`GMSHPretraitement` must be set as true if it is the first run with the given mesh file.
 2. In the current version of ECOGEN, only mesh files generated with the opensource Gmsh_  software under file format *version 2* can be used.

docs/sphinx_docs/source/InitialConditions.rst → docs/sphinx_docs/source/Chap3_1_4initialConditions.rst

@@ -6,7 +6,7 @@
 InitialConditionsV4.xml
 =======================
 
- The *initialConditionsV4.xml* input file includes the initial conditions and the boundary conditions of the flow simulation. It is *mandatory* located in the folder of the current case. The typical structure of this file is:
+ The *initialConditionsV4.xml* input file includes the initial conditions and the boundary conditions of the flow simulation. It is **mandatory** located in the folder of the current case. The typical structure of this file is:
 
  .. code-block:: xml
 
@@ -264,7 +264,7 @@ This last node :xml:`<dataFluid>` as well as the :xml:`<mixture>` node are depen
 
 .. _Sec:input:euler:
 
-euler
+Euler
 ~~~~~
 Single phase flow. In this case, the :xml:`<mixture>` node is absent and the :xml:`<dataFluid>` node contains the following attributes or nodes:
 

docs/sphinx_docs/source/InputFiles_Chapter.rst → docs/sphinx_docs/source/Chap3_1inputFiles.rst

@@ -1,6 +1,8 @@
 .. role:: xml(code)
 	:language: xml
 
+.. _Chap:input:
+
 Input Files
 ===========
 
@@ -44,9 +46,9 @@ In this section the structure of each input file is detailed. This information i
    :maxdepth: 1
    :caption: Contents:
 
-   Main
-   Model
-   Mesh
-   InitialConditions
+   Chap3_1_1main
+   Chap3_1_2model
+   Chap3_1_3mesh
+   Chap3_1_4initialConditions
 
 

docs/sphinx_docs/source/Materials.rst → docs/sphinx_docs/source/Chap3_2materials.rst

@@ -1,3 +1,5 @@
+.. _Sec:IO:materials:
+
 Materials
 =========
 
@@ -8,13 +10,25 @@ For each phase, an Equation of State is required. The data for a given phase are
 
 Ideal Gas
 ---------
-It is a simple relation linking the pressure (:math:`p`), the temperature (:math:`T`) and the density (:math:`\rho`) or the specific volume (:math:`v=1/ρ`):
-pv=rT
-r is the universal gas constant divided by the molar weight of the gas (unit: J/(K.kg) (SI)). The Gibbs relation as well as Maxwell relations yield the definition of the internal energy: 
-e(p,v)=p/(γ-1) v+e_ref
-One can easily obtain the entropy:
-s(p,T)=c_v ln(T^γ/p^(γ-1) )+s_ref
-The following parameters are assumed constant and  γ,c_v,e_ref  et s_refmust be specified in the material file, as in the following example :
+It is a simple relation linking the pressure (:math:`p`), the temperature (:math:`T`) and the density (:math:`\rho`) or the specific volume (:math:`v=1/ρ`): 
+
+.. math::
+	
+	pv=rT 
+
+:math:`r` is the universal gas constant divided by the molar weight of the gas (unit: :math:`J/(K.kg)` (SI)). The Gibbs relation as well as Maxwell relations yield the definition of the internal energy: 
+
+.. math:: 
+
+	e(p,v) = \frac{p}{\gamma-1} v + e_{ref}
+
+One can easily obtain the entropy: 
+
+.. math::
+
+	s(p,T) = c_v \ln{\left(\frac{T^{\gamma}}{p^{\gamma-1}}\right)} + s_{ref}
+
+The following parameters are assumed constant and :math:`\gamma`, :math:`c_v`, :math:`e_{ref}` and :math:`s_{ref}` must be specified in the material file, as in the following example :
 
 .. code-block:: xml
 
@@ -35,15 +49,25 @@ The following parameters are assumed constant and  γ,c_v,e_ref  et s_refmust be
 
 Stiffened Gas
 -------------
-This Equation of state was first presented in 1971 by Harlow & Amdsen :
-e=(p+γp_∞)/((γ-1) ) v+e_ref
-This EOS takes into account for the molecular attraction within condensed matter. This quite simple EOS is largely used in numerical simulation based on diffuse interface methods because it is able to reproduce shock relation as well as saturation curve  for a liquid-vapor mixture when the phase transition is modeled.
+This Equation of state was first presented in 1971 by Harlow & Amdsen :cite:`harlow1968stiffenedGas`:
+
+.. math::
+	
+	e = \left(\frac{p + \gamma p_{\infty}}{\gamma-1}\right) v + e_{ref}
+
+This EOS takes into account for the molecular attraction within condensed matter. This quite simple EOS is largely used in numerical simulation based on diffuse interface methods because it is able to reproduce shock relation as well as saturation curve for a liquid-vapor mixture when the phase transition is modeled.
 Hereafter some useful relations for the specific volume, the enthalpy and the entropy:
-v(p,T)=((γ-1) c_v T)/(p+p_∞ )
-h(T)=γc_v T+e_ref
-s(p,T)=c_v ln(T^γ/(p+p_∞ )^(γ-1) )+s_ref
-The ideal gas law is recovered if p_∞=0. The following parameters are assumed constant and  γ,p_∞,c_v,e_ref  et s_ref must be specified in the material file, as in the following example:
 
+.. math::
+
+	v(p,T) &= \frac{ (\gamma-1) c_v T}{p + p_{\infty}} \\
+	v(p,T) &= \frac{ (\gamma-1) c_v T}{p + p_{\infty}} \\
+	h(T) &= \gamma c_v T + e_{ref} \\
+	s(p,T) &= c_v \ln{\left(\frac{T^{\gamma}}{\left(p+p_{\infty}\right)^{\gamma-1}} \right)} + s_{ref}
+
+A usefull description of these relations can be found in :cite:`SGEOS`.
+
+The ideal gas law is recovered if :math:`p_{\infty}=0`. The following parameters are assumed constant :math:`\gamma`, :math:`p_{\infty}`, :math:`c_v`, :math:`e_{ref}` and :math:`s_{ref}`. These parameters must be specified in the material file, as in the following example:
 
 .. code-block:: xml
 

docs/sphinx_docs/source/OutputFiles_Chapter.rst → docs/sphinx_docs/source/Chap3_3outputFiles.rst

@@ -1,3 +1,5 @@
+.. _Sec:IO:output:
+
 Output Files
 ============
 
@@ -9,13 +11,13 @@ One can select the following format:
 
 The name of the results files follows the rules:
 
-result(format)_CPU(proc)_AMR(niveau)_TIME(instant). (ext)
+result(format)_CPU(proc)_AMR(level)_TIME(instant). (ext)
 
 that can select results files according:
 
 - (format)	: data format (empty for ASCII, B64 for binary).
 - (instant)	: time of writing results (depends on the selected frequency for writing.
-- (niveau) 	: AMR level (in the case of an AMR simulation).
+- (level) 	: AMR level (in the case of an AMR simulation).
 - (proc) 	: the number of the processor where the results are from (in the case of a parallel simulation).
 - (ext) 	: kind of mesh.
 

docs/sphinx_docs/source/Chap3_IO_Chapter.rst

@@ -0,0 +1,21 @@
+.. _Chap:UserGuide:
+
+I/O descriptions
+================
+ECOGEN settings are managed via INPUT FILES only. The global INPUT FILES and OUTPUT FILES structure is depicted in :numref:`Fig:userGuide:overview`.
+
+.. _Fig:userGuide:overview:
+
+.. figure:: ./_static/IO/overview.png
+  :scale: 70%
+  :align: center
+
+  Structure of input and output files in ECOGEN
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   Chap3_1inputFiles
+   Chap3_2materials
+   Chap3_3outputFiles