Update documentation

Author: Matshishkapeu

ECOGEN_documentation.pdf

@@ -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

README.md

@@ -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/Biblio.bib

@@ -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/Introduction.rst renamed to docs/sphinx_docs/source/Chap1_introduction.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/Start.rst renamed to docs/sphinx_docs/source/Chap2_1installation.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/Chap2_installation_Chapter.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/Main.rst renamed to docs/sphinx_docs/source/Chap3_1_1main.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/Model.rst renamed to docs/sphinx_docs/source/Chap3_1_2model.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: