documentation update 2.0

Author: Matshishkapeu

docs/sphinx_docs/source/Biblio.bib

@@ -2,39 +2,48 @@
 
 @article{euler1757principes,
   title={Principes g{\'e}n{\'e}raux du mouvement des fluides},
-  author={Euler, Leonhard},
+  author={Euler, L.},
   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.},
-  journal={Submitted},
+  title={High-speed video microscopy and numerical modeling of bubble dynamics near a surface of urinary stone},
+  author={Pishchalnikov, Y. A. and Behnke-Parks, W. M. and Schmidmayer, K. and Maeda, K. and Colonius, T. and Kenny, T. W. and Laser, D. J.},
+  journal={Journal of the Acoustical Society of America},
+  volume={146},
+  pages={516--531},
   year={2019}
 }
 
 @Article{schmidmayer2019adaptive,
   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},
+  title     = {{A}daptive {M}esh {R}efinement algorithm based on dual trees for cells and faces for multiphase compressible flows},
   journal   = {Journal of Computational Physics},
+  volume={388},
+  pages={252--278},
   year      = {2019},
   publisher = {Elsevier},
 }
 
-@article{schmidmayer2019ecogen,
-  title={{ECOGEN}: {A}n open-source tool for multiphase, compressible, multiphysics flows},
+@article{schmidmayer2020ecogen,
+  doi = {10.1016/j.cpc.2019.107093},
+  url = {https://doi.org/10.1016/j.cpc.2019.107093},
+  title={{ECOGEN: A}n open-source tool for multiphase, compressible, multiphysics flows},
   author={Schmidmayer, K. and Petitpas, F. and Le Martelot, S. and Daniel, E.},
-  journal={Submitted},
-  year={2019}
+  journal={Computer Physics Communications},
+  volume={251},
+  year={2020}
 }
 
 @article{schmidmayer2019comparativeStudy,
-  title={Interface-capturing models and schemes to solve bubble dynamics and cavitation: {A} comparative study},
-  author={Schmidmayer, K. and Colonius, T.},
-  journal={In preparation},
-  year={2019}
+  title={An assessment of multicomponent flow models and interface capturing schemes for spherical bubble dynamics},
+  author={Schmidmayer, K. and Bryngelson, S. H. and Colonius, T.},
+  journal={J. Comp. Phys.},
+  volume={402},
+  pages={109080},
+  year={2020}
 }
 
 @article{schmidmayer2019heat,
@@ -1002,16 +1011,6 @@ @article{chiapolino2017phaseTransition
   year={2017}
 }
 
-@article{gmsh,
-  title={Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities},
-  author={Geuzaine, C. and Remacle, J.-F.},
-  journal={International Journal for Numerical Methods in Engineering},
-  volume={79},
-  number={11},
-  pages={1309--1331},
-  year={2009}
-}
-
 @article{igra2003experimental,
   title={Experimental investigation of two cylindrical water columns subjected to planar shock wave loading},
   author={Igra, D. and Takayama, K.},
@@ -2586,7 +2585,7 @@ @Article{lefloch
 
 @Article{kapila97,
   author =   {A. Kapila and S. Son and J. Bdzil and R. Menikoff and D. Stewart},
-  title =    {Two-phase modeling of \textsc{DDT}: \textsc{S}tructure of the velocity-relaxation zone},
+  title =    {Two-phase modeling of {DDT}: {S}tructure of the velocity-relaxation zone},
   journal =    {Physics of Fluids},
   year =   1997,
   volume =   9,
@@ -2596,7 +2595,7 @@ @Article{kapila97
 
 @Article{kapila2001,
   author =   {A. Kapila and R. Menikoff and J. Bdzil and S. Son and D. Stewart},
-  title =    {Two-phase modeling of \textsc{DDT} in granular materials: \textsc{R}educed equations},
+  title =    {Two-phase modeling of {DDT} in granular materials: {R}educed equations},
   journal =    {Physics of Fluids},
   year =   2001,
   volume =   13,
@@ -2723,7 +2722,7 @@ @Book{toro97
 
 @book{toro2013riemann,
   title={Riemann solvers and numerical methods for fluid dynamics: a practical introduction},
-  author={Toro, Eleuterio F},
+  author={Toro, E.F.},
   year={2013},
   publisher={Springer Science \& Business Media}
 }
@@ -3173,8 +3172,8 @@ @Article{titarev2007
   pages =  {897--926}
 }
 @Article{van1977towards,
-  author    = {Van Leer, Bram},
-  title     = {Towards the ultimate conservative difference scheme. IV. A new approach to numerical convection},
+  author    = {Van Leer, B.},
+  title     = {Towards the ultimate conservative difference scheme. {IV. A} new approach to numerical convection},
   journal   = {Journal of computational physics},
   year      = {1977},
   volume    = {23},
@@ -3183,4 +3182,15 @@ @Article{van1977towards
   publisher = {Elsevier},
 }
 
+@article{le2016noble,
+  title={The {Noble-Abel Stiffened-Gas} equation of state},
+  author={Le M{\'e}tayer, O. and Saurel, R.},
+  journal={Physics of Fluids},
+  volume={28},
+  number={4},
+  pages={046102},
+  year={2016},
+  publisher={AIP Publishing}
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}

docs/sphinx_docs/source/Chap1_introduction.rst

@@ -1,47 +1,50 @@
 Introduction
 ============
 
-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.
+ECOGEN is a CFD
 
-- multi-models (single phase, multiphase with or without equilibrium)
-- multi-physics (thermal transfers, viscosity, surface tension, mass transfers)
-- multi-meshes (Cartesian, unstructured, AMR)
-- multi-CPU
+- multi-model (single phase, multiphase with or without equilibriums),
+- multi-physics (thermal transfers, viscosity, surface tension, mass transfers),
+- multi-mesh (Cartesian, unstructured, AMR),
+- multi-core,
+
+plateform written in C++ object-oriented-programming language. It is dedicated to numerical simulation of compressible multiphase flows. It has the vocation to share academics research in the multiphase flow field in direction to other academics but also for industrials, students, etc.
 
 ECOGEN stands for:
 
-- **E**\ volutive: makes easier future developpements
-- **C**\ ompressible: dedicated to compressible flows
-- **O**\ penSource: Distributed under GPLv3 Licence
-- **G**\ enuine: Uses the "Diffuse Interface Method" (DIM)
-- **E**\asy: simple to install and use (C++ compiler and MPI)
-- **N**-phase: liquids, vapors, inert gases and/or reactives 
+- **E**\ volutive: Made for easier future developments.
+- **C**\ ompressible: Dedicated to compressible flows.
+- **O**\ pen-source: Distributed under `GNU GPLv3 License`_.
+- **G**\ enuine: Uses the "Diffuse Interface Method" (DIM).
+- **E**\ asy: Simple to install and use (C++ compiler and MPI).
+- **N**\ -phase: Liquids, vapors, inert gases and/or reactives.
+
+.. _`GNU GPLv3 License`: http://www.gnu.org/licenses
 
-What kind of physical problems ?
---------------------------------
+What kind of physical problems?
+-------------------------------
 
-ECOGEN is designed for following applications:
+ECOGEN is designed for the following:
 
-- Solving interface problems between pure or multicomponents fluids and mixtures of multiphase flows.
-- Treating surface tension, heat and mass transfers for evaporating and condensing flow, cavitation.
-- Computing wave propagation in strongly unsteady situations using a specific Adaptative Mesh Reffinement .
+- Solving interface problems between pure or multicomponent fluids and mixtures of multiphase flows.
+- Treating surface tension, heat and mass transfers for cavitation, evaporating and condensing flows.
+- Computing wave propagation in strongly unsteady situations using a specific Adaptive Mesh Refinement.
 - Computing on unstructured grids to simulate complex geometries.
 - Parallel computing using open MPI libraries.
 
-What about the engine ?
------------------------
+What about the engine?
+----------------------
 
-ECOGEN is a receptacle of a story of diffuse interface method (DIM) theory that started in the late 90s. DIM summarizes more than 20 years of researches on multiphase flow modelling with the objective to develop mathematical models as well as their associated numerical methods.
+ECOGEN is a receptacle of a story of diffuse-interface-method (DIM) theory that started in the late 90s. DIM summarizes more than 20 years of researches on multiphase flow modelling with the goal to develop mathematical models as well as their associated numerical methods.
 
-What is a diffuse interface? In DIM theory, the interfaces between pure phases are captured as diffuse numerical zones meaning that one goes continuously from one phase to another.
+What is a diffuse interface? In DIM theory, the interfaces between pure phases are captured as diffuse numerical regions, meaning that one goes continuously from one phase to another.
 
 .. _Fig:introduction:diffInterface:
 
 .. figure:: ./_static/intro/diffInterface.png
 
-  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.
+  1D extraction of the diffuse interface region of a water droplet.
 
-The basic research on DIM is now matured enough to propose ECOGEN, a numerical tool that can be largely cast and use to solve industrial as well as research multiphase flow problems.
+This way is possible thanks to a thermodynamics consistency. Then, the flow solution does no longer requires interface tracking algorithms: It becomes easy to simulate complex topological-shape evolutions between miscible or non-miscible fluids. Moreover, pressure waves (shock waves, acoustic waves) can propagate and interact properly in the whole flow.
 
+The base research on DIM is now matured enough to propose ECOGEN, a numerical tool that can be largely cast and use to solve industrial as well as research multiphase flow problems.

docs/sphinx_docs/source/Chap2_1installation.rst

@@ -1,15 +1,15 @@
-Prerequisities
-==============
+Prerequisites
+=============
 
-ECOGEN must be compiled with C++. It also requires a functional system implementation of MPI library (not provided in this package). Depending on your operating system, you can follow the instructions below to set a full open source installation:
+ECOGEN must be compiled with C++. It also requires a functional system implementation of MPI library (not provided in this package). Depending on your operating system, you can follow the instructions below to set a full open-source installation.
 
-Installing prerequisities on Ubuntu system
-------------------------------------------
-ECOGEN required two mandatory components to be installed on your Ubuntu system : a C++ compiler and an effective implementation of MPI.
+Installing prerequisites on Ubuntu system
+-----------------------------------------
+ECOGEN requires two mandatory components to be installed on your Ubuntu system: A C++ compiler and an effective implementation of MPI.
 
 Installing C++ compiler
 ~~~~~~~~~~~~~~~~~~~~~~~
-Nothing is more easy than installing C and C++ compiler on Ubuntu. In your terminal just enter the following commands:
+Nothing is easier than installing C and C++ compiler on Ubuntu. In your terminal, just enter the following commands:
 
 .. highlight:: console
 
@@ -20,13 +20,14 @@ Nothing is more easy than installing C and C++ compiler on Ubuntu. In your termi
 	sudo apt-get install gcc
 	sudo apt-get install g++
 	sudo apt-get install build-essential
+	sudo apt-get install make
 
-More information on the ubuntu doc page https://doc.ubuntu-fr.org/gcc
+More information on the Ubuntu doc page https://doc.ubuntu-fr.org/gcc.
 
 Installing openMPI
 ~~~~~~~~~~~~~~~~~~
 
-Dowload the latest stable version of openMPI_ under compressed format. At the time this page is written, it corresponds to the compressed file : openmpi-4.0.1.tar.gz. Uncompresse and move into the directory:
+Download the latest stable version of openMPI_ under compressed format. At the time this page was written, it corresponded to the compressed file: openmpi-4.0.1.tar.gz. Uncompresse and move it into the directory:
 
 .. highlight:: console
 
@@ -35,7 +36,7 @@ Dowload the latest stable version of openMPI_ under compressed format. At the ti
 	tar -xvf openmpi-4.0.1.tar.gz 
 	cd openmpi-4.0.1/
 
-Prepare the environnement for using your favorite compiler:
+Prepare the environment to use your favorite compiler:
 
 .. highlight:: console
 
@@ -44,7 +45,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). The "make" step should take some times (coffee time ?):
+Configure and proceed to the installation (you can choose a different directory). The "make" step should take some time (coffee time?):
 
 .. highlight:: console
 
@@ -63,9 +64,13 @@ Cleaning
 	cd .. 
 	rm -rf openmpi-4.0.1/ 
 
-Modify the /etc/bash.bashrc by adding the line:
+Add openMPI library to the environment variable PATH (might be required to be root):
 
-*export PATH=/opt/openmpi/bin:$PATH*
+.. highlight:: console
+
+:: 
+
+	sudo echo 'export PATH=/opt/openmpi/bin:$PATH' >> /etc/bash.bashrc
 
 Then source the file to take into consideration the modifications:
 
@@ -75,40 +80,42 @@ Then source the file to take into consideration the modifications:
 
 	source /etc/bash.bashrc
 
-If the installation succeed you should use the mpicxx command in your terminal. Then proceed to the download step below.
+If the installation succeeds you should be able to use the "mpicxx" command in your terminal. Then proceed to the download step below.
 
 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 |version| can be downloaded from GitHub. The source files are available at the following address: https://github.com/code-mphi/ECOGEN/releases. 
 
 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/libEOS/ folder including some possible parameters for the equation-of-states 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.
+	- ECOGEN/libTests/referenceTestCases/ folder organized as a test-case library according to the flow model (Euler-equation 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 computation 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.
+* *ECOGEN_V1.0_documentation.pdf*: The full documentation for ECOGEN.
+
+.. _Sec:installation:compileAndExecute:
 
 Compilation/Execution on bash
 =============================
 
-Use the Makefile (can be adapted if necessary) to compile ECOGEN sources directly on bash (XX is the number of CPU required for compilation):
+Use the Makefile (can be adapted if necessary) to compile ECOGEN sources directly on bash (XX is the number of cores required for compilation):
 
 .. highlight:: console
 
 ::
 
 	make -j XX
 
-Executing ECOGEN is really easy on bash (XX is the number of CPU required for execution):
+Executing ECOGEN is really easy on bash (XX is the number of cores required for execution):
 
 .. highlight:: console
 
@@ -119,7 +126,7 @@ Executing ECOGEN is really easy on bash (XX is the number of CPU required for ex
 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:
+Once ECOGEN has been successfully compiled, the best way to test ECOGEN's installation is to run successively the two simple following commands:
 
 .. highlight:: console
 
@@ -128,13 +135,13 @@ Once preceding compiling of the code succeed, the better way to test ECOGEN's in
 	./ECOGEN
 	mpirun -np 2 ECOGEN
 
-This will run the default test case included in the package two times:
+These will run the default test case included in the package two times:
 
-* In sequential (single CPU). 
-* In parallele using 2 CPU.
+* Once in sequential (single core). 
+* Once in parallel using 2 cores.
 
-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.
+These should print information in the terminal on the running default test case. If no error message appears, then your installation should be OK and you should be able to 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.
+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 information.
 
 .. _openMPI: https://www.open-mpi.org/

docs/sphinx_docs/source/Chap2_installation_Chapter.rst

@@ -3,7 +3,7 @@
 Installation instructions
 =========================
 
-This section contains basic instruction for ECOGEN installation on windows / ubuntu systems.
+This section contains base instructions for ECOGEN installation on Windows and Ubuntu operating systems.
 
 .. toctree::
    :maxdepth: 1