diff --git a/docs/sphinx_docs/source/Biblio.bib b/docs/sphinx_docs/source/Biblio.bib index 1f06090e..fcf72b6a 100644 --- a/docs/sphinx_docs/source/Biblio.bib +++ b/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;} diff --git a/docs/sphinx_docs/source/Chap1_introduction.rst b/docs/sphinx_docs/source/Chap1_introduction.rst index 20fba048..2928c6b6 100644 --- a/docs/sphinx_docs/source/Chap1_introduction.rst +++ b/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. diff --git a/docs/sphinx_docs/source/Chap2_1installation.rst b/docs/sphinx_docs/source/Chap2_1installation.rst index f5d5df65..5213d2fb 100644 --- a/docs/sphinx_docs/source/Chap2_1installation.rst +++ b/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,32 +80,34 @@ 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 @@ -108,7 +115,7 @@ Use the Makefile (can be adapted if necessary) to compile ECOGEN sources directl 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/ \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap2_installation_Chapter.rst b/docs/sphinx_docs/source/Chap2_installation_Chapter.rst index 8c42a8c8..469d99ba 100644 --- a/docs/sphinx_docs/source/Chap2_installation_Chapter.rst +++ b/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 diff --git a/docs/sphinx_docs/source/Chap3_1_1main.rst b/docs/sphinx_docs/source/Chap3_1_1main.rst index a2a8c214..d2ccdbb9 100644 --- a/docs/sphinx_docs/source/Chap3_1_1main.rst +++ b/docs/sphinx_docs/source/Chap3_1_1main.rst @@ -23,6 +23,8 @@ MainV5.xml It contains general parameters for the computation listed below. Some are mandatory, others are optional. +.. _Sec:input:main:runName: + Run name -------- @@ -30,7 +32,7 @@ Run name example -The :xml:`` markup is mandatory. It will be used to create the folder containing the test case results in **ECOGEN/results/**. +The :xml:`` markup is mandatory. It will be used to create the folder containing the test-case results in **ECOGEN/results/**. Output format ------------- @@ -41,10 +43,10 @@ Output format The :xml:`` markup is mandatory. The user can choose the writing output format. Attributes are: -- :xml:`format`: can take the value *GNU* (standard writing in column) or *XML* (XML VTK format ). -- :xml:`binary`: can take the value true or false. *Binary* (true) or *ASCII* (false) format can be chosen. +- :xml:`format`: Can take the value *GNU* (standard writing in column) or *XML* (XML VTK format). +- :xml:`binary`: Can take the value true or false. *Binary* (true) or *ASCII* (false) format can be chosen. -Output results files will be placed in the folder **ECOGEN/results/** into a specific subfolder with the name of the run. +Output result files will be placed in the folder **ECOGEN/results/** into a specific subfolder bearing the name of the run. Time evolution control ---------------------- @@ -56,11 +58,11 @@ Time evolution control -ECOGEN is a CFD tool based on an explicit integration scheme in time. The :xml:`` markup is mandatory and defines the temporal evolution of the current simulation. it contains the +ECOGEN is a CFD tool based on an explicit integration scheme in time. The :xml:`` markup is mandatory and defines the temporal evolution of the current simulation. It contains the :xml:`iterations` attribute that can take the two values: -- *true*: the time control is done thanks to the total number of timesteps and the node must be present. -- *false*: the time control is done thanks to the physical final time and the node must be present. +- *true*: The time control is done thanks to the total number of timesteps and the :xml:`` node must be present. +- *false*: The time control is done thanks to the final physical time and the :xml:`` node must be present. The :xml:`` markup: @@ -70,8 +72,8 @@ The :xml:`` markup: ECOGEN automatically computes the timestep value thanks to a numerical stability criterion (CFL criterion). This markup is defined with following attributes: -- :xml:`number`: Integer equals to the total number of temporal timesteps. -- :xml:`iterFreq`: Integer equal to the frequency of results writing (results are written every iterFeq timestep) +- :xml:`number`: Integer equal to the total number of temporal timesteps. +- :xml:`iterFreq`: Integer equal to the writing frequency of the results (results are written every :xml:`iterFreq` timestep) The :xml:`` markup: @@ -79,12 +81,10 @@ The :xml:`` markup: -If this markup is used ECOGEN automatically determines the total amount of timestep to compute to reach the chosen physical time. Attributes are: - -- :xml:`totalTime`: Real number equals to the physical final time of the simulation. (unit: s (SI)). -- :xml:`timeFreq`: Real number equals to the frequency of results writing (results are written every timeFreq seconds). - +If this markup is used, ECOGEN automatically determines the total amount of timestep to compute to reach the chosen physical time. Attributes are: +- :xml:`totalTime`: Real number equal to the final physical time of the simulation (unit: s (SI)). +- :xml:`timeFreq`: Real number equal to the writing frequency of the results (results are written every :xml:`timeFreq` seconds). CFL criterion ------------- @@ -93,11 +93,11 @@ CFL criterion -The :xml:`` markup is mandatory. It specifies the value of the attribute :xml:`CFL` which ensures the stability of the temporal integration scheme: the value (real number) must be less than 1. +The :xml:`` markup is mandatory. It specifies the value of the attribute :xml:`CFL` which ensures the stability of the temporal integration scheme: The value (real number) must be less than 1. Global accuracy order of the numerical scheme --------------------------------------------- -When it is possible (according to the mesh or to the flow model) ECOGEN can use a second-order scheme (based on MUSCL approach with a TVD slope limiter). In this case the optional markup :xml:`` can be inserted in the *mainV5.xml* input file as in the following example: +When it is possible, according to the mesh or to the flow model, ECOGEN can use a second-order scheme (based on MUSCL approach with a TVD slope limiter; see :cite:`schmidmayer2020ecogen` for details). In this case, the optional markup :xml:`` can be inserted in the *mainV5.xml* input file as in the following example: .. code-block:: xml @@ -108,16 +108,16 @@ When it is possible (according to the mesh or to the flow model) ECOGEN can use thinc -The :xml:`` markup must contain the node :xml:``. The other nodes are optional. The slope limiters available in ECOGEN are the following: minmod :cite:`roe1986superbee`, vanleer :cite:`vanLeer1974`, vanalbada :cite:`vanAlbada1997`, mc :cite:`van1977towards`, superbee :cite:`roe1986superbee`. Markups significations are: +The :xml:`` markup must contain the node :xml:``. The other nodes are optional. The slope limiters available in ECOGEN are the following: minmod :cite:`roe1986superbee`, vanleer :cite:`vanLeer1974`, vanalbada :cite:`vanAlbada1997`, mc :cite:`van1977towards`, superbee :cite:`roe1986superbee` and thinc :cite:`shyue2014thinc` (only for volume fraction at the interface location). Markup significations are: -- :xml:``: applied everywhere and on all variables unless it is overwrite by the following optional limiters. -- :xml:``: applied on all variables but only at the interface location. By default is equal to the global limiter. -- :xml:``: applied everywhere but only on the volume-fraction and transport equations (THINC is only applied on the volume fractions) unless it is overwrite by the interface volume-fraction limiter. By default is equal to the global limiter. -- :xml:``: applied only at the interface location and on the volume-fraction and transport equations (THINC :cite:`shyue2014thinc` is only applied on the volume fractions). By default is equal to the interface limiter. +- :xml:``: Applied everywhere and on all variables unless it is overwritten by the following optional limiters. +- :xml:``: Applied on all variables but only at the interface location. By default is equal to the global limiter. +- :xml:``: Applied everywhere but only on the volume-fraction and transport equations (THINC is only applied on the volume fraction) unless it is overwritten by the interface volume-fraction limiter. By default is equal to the global limiter. +- :xml:``: Applied only at the interface location and on the volume-fraction and transport equations (THINC is only applied on the volume fraction). By default is equal to the interface limiter. Probes ------ -It is possible to record flow variables at given locations in the computational domain against time. This is done by including to the *mainV5.xml* input file the optional :xml:`` markup. +It is possible to record over time flow variables at given locations in the computational domain. This is done by including to the *mainV5.xml* input file the optional :xml:`` markup. .. code-block:: xml @@ -127,12 +127,20 @@ It is possible to record flow variables at given locations in the computational The two following nodes must be included in the :xml:`` markup: -- :xml:``: Specifies the location of the probe into the computational domain in each physical direction corresponding to the attributes: :xml:`x`, :xml:`y` and :xml:`z` (unit: m (SI)). Values must be real numbers. -- :xml:``: permits to specify the probe acquisition frequency (unit: s (SI)). If the value is set to zero or negative, flow values at the probe location are recorded at each time step. +- :xml:``: Specify the location of the probe into the computational domain in each physical direction corresponding to the attributes :xml:`x`, :xml:`y` and :xml:`z` (unit: m (SI)). Values must be real numbers. +- :xml:``: Allow to specify the probe acquisition frequency (unit: s (SI)). If the value is set to zero or negative, flow values at the probe location are recorded at each time step. -Probes output results files will be placed in the specific subfolder **ECOGEN/results/XXX/probes/** where *XXX* represent the name of the run specified in :xml:`` markup. +Probe output-result files will be placed in the specific subfolder **ECOGEN/results/XXX/probes/** where *XXX* represents the name of the run specified in :xml:`` markup. **Remarks:** -1. Recording probe with a high frequency could have a significant impact on computation performances due to the computer memory time access. To prevent that, one should fix a reasonable acquisition frequency. +1. Recording probes with a high frequency could have a significant impact on computation performances due to the computer memory time access. To prevent that, one should fix a reasonable acquisition frequency. 2. Several probes can be added simultaneously. For that, place as many as wanted :xml:`` markups in the *mainV5.xml* input files. + +Simulation restart option +------------------------- +ECOGEN can restart a run from previously written results. To do so, the :xml:`restartFileNumber` attribute of the :xml:`` markup must be specified. Furthermore, this markup can include an :xml:`AMRsaveFreq` attribute which gives the frequency at which the mesh information of an AMR simulation is saved. Therefore, an AMR simulation can only restart from a time coherent combination of result and mesh information files. + +.. code-block:: xml + + \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap3_1_2model.rst b/docs/sphinx_docs/source/Chap3_1_2model.rst index e24b1eb0..4304b0dd 100644 --- a/docs/sphinx_docs/source/Chap3_1_2model.rst +++ b/docs/sphinx_docs/source/Chap3_1_2model.rst @@ -1,10 +1,12 @@ .. role:: xml(code) :language: xml +.. _Sec:input:model: + ModelV4.xml =========== -Fluid mechanics models used in the computation are specified in *modelv4.xml* file. It is **mandatory** located in the folder of the current case. A typical form of this file is: +Fluid mechanics models used in the computation are specified in the *modelv4.xml* file. It is **mandatory** located in the folder of the current case. A typical form of this file is: .. code-block:: xml @@ -24,16 +26,16 @@ Flow model -The :xml:`` markup is **mandatory** to specify the mathematical model to solve during the computation. This markup may contains the following attributes: +The :xml:`` markup is **mandatory** to specify the mathematical model to solve during the computation. This markup may contain the following attributes: -- :xml:`name`: name of the mathematical flow model. This attribute can take the values: *Euler*, *Kapila*, *multip*, *ThermalEq* or *EulerHomogeneous*. -- :xml:`numberPhases`: Integer number corresponding to the number of phases present in the simulations. The total amount of equations is related to this number. This attribute is not necessary for the values of name: *Euler*, *EulerHomogeneous*. -- :xml:`numberTransports`: this attribute is optionnal and is set to 0 as default. It can be used to add specific variable advected in the flow (color function). -- :xml:`alphaNull`: For *Kapila*'s model, the volume fraction can either be null or not and this choice is determined by the parameter alphaNull. default value is *false*. +- :xml:`name`: Name of the mathematical flow model. This attribute can take the values: *Euler* :cite:`euler1757principes`, *Kapila* :cite:`relaxjcp`:cite:`kapila2001`, *multip*, *ThermalEq* :cite:`martelotboiling` or *EulerHomogeneous*. +- :xml:`numberPhases`: Integer number corresponding to the number of phases present in the simulation. The total amount of equations is related to this number. This attribute is not necessary when the values of :xml:`name` are *Euler* or *EulerHomogeneous*. +- :xml:`numberTransports`: This attribute is optionnal and is set to 0 as default. It can be used to add specific variables advected in the flow (color functions). +- :xml:`alphaNull`: For *Kapila*'s model, the volume fraction can either be null (*true*) or not (*false*) and this choice is determined by this parameter. Default value is *false*. -**Remark:** +**Remark:** -if *EulerHomogeneous* model is chosen, two additional attributes may be used: :xml:`liquid` and :xml:`vapor` to specify the number corresponding to the liquid phase and the vapor phase. It is phase 0 (for the first) or 1 (for the second). +If *EulerHomogeneous* model is chosen, two additional attributes may be used: :xml:`liquid` and :xml:`vapor` to specify the number corresponding to the liquid phase and the vapor phase. They are phase 0 for the first and 1 for the second. .. code-block:: xml @@ -48,7 +50,7 @@ Equations of state (EOS) -The *modelV4.xml* input fle **must contain** as many :xml:`` markups as many number of phases specified in the :ref:`Sec:input:FlowModel` markup. Each phase is described thanks to relations and parameters. The values of these parameters are specified in a separate file: the attribute name contains the name of this file that must be placed in the folder **ECOGEN/libEOS/**. Some fluid files are already present in the ECOGEN package. +The *modelV4.xml* input file **must contain** as many :xml:`` markups as number of phases specified in the :ref:`Sec:input:FlowModel` markup. Each phase is described thanks to relations and parameters. The values of these parameters are specified in a separate file: The attribute name contains the name of this file that must be placed in the folder **ECOGEN/libEOS/**. Some fluid files are already present in the ECOGEN package. .. _Sec:input:Transport: @@ -59,7 +61,7 @@ Advected additional variables -The *modelV4.xml* input fle **must contain** as many :xml:`` markups as many number of transport specified in the :ref:`Sec:input:FlowModel` markup. Each transported variable is described by its name. The default number of advected variable is 0. +The *modelV4.xml* input fle **must contain** as many :xml:`` markups as number of transports specified in the :ref:`Sec:input:FlowModel` markup. Each transported variable is described by its name. The default number of advected variable is 0. Relaxation procedures --------------------- @@ -68,11 +70,11 @@ Relaxation procedures -An additional markup :xml:`` may be used to impose some specific equilibrium between the phases depending on the flow model used. The attribute :xml:`type` specifies the kind of equilibrium: +An additional markup :xml:`` may be used to impose some specific equilibrium between the phases depending on the flow model used. The attribute :xml:`type` specifies the type of equilibrium: -- *P*: a pressure equilibrium is imposed at every location of the flow. It does not require additional attributes. +- *P*: A pressure equilibrium is imposed at every location of the flow. It does not require additional attributes. - *PT*: Both pressure and thermal equilibrium are imposed at every location of the flow. It does not require additional attributes. -- *PTMu*: a thermodynamical equilibrium is imposed at every location of the flow. It must be associated to the node :xml:`` with attributes :xml:`liquid` and :xml:`vapor` to specify the name of the EOS of the liquid and the vapor phase. Hereafter the complete node when PTMu is used: +- *PTMu*: A thermodynamical equilibrium is imposed at every location of the flow. It must be associated with the node :xml:`` whose attributes are :xml:`liquid` and :xml:`vapor` to specify the name of the EOS of the liquid and the vapor phase. Hereafter the complete node when *PTMu* is used: .. code-block:: xml @@ -85,7 +87,7 @@ Source terms The additional :xml:`` 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:`` 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:`` 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 @@ -93,7 +95,7 @@ The additional :xml:`` markup can be used to numerically integrate -- *gravity*: if the gravity is considered. The node :xml:`` with the following attributes must be present with the attributes :xml:`x`, :xml:`y` et :xml:`z` giving the coordinates for the gravity acceleration vector in real numbers (unit: m/s2 (SI)) +- *gravity*: If the gravity is considered. The node :xml:`` must be present with the attributes :xml:`x`, :xml:`y` and :xml:`z` giving the coordinates for the gravity acceleration vector in real numbers (unit: m/s2 (SI)). .. code-block:: xml @@ -101,7 +103,7 @@ The additional :xml:`` markup can be used to numerically integrate -- *MRF*: for a simulation in the moving reference frame. Allow to compute solution in a rotating frame. The node :xml:`` requires the attributes :xml:`x`, :xml:`y` et :xml:`z` giving the coordinates for the rotating vector in real numbers (unit: rad/s (SI)). The node :xml:`` is optional and allow to specify a progressing acceleration (linear) to the final rotating velocity (requires the attribute :xml:`tf` for acceleration time). +- *MRF*: For a simulation in a moving reference frame. Allow to compute solution in a rotating frame. The node :xml:`` requires the attributes :xml:`x`, :xml:`y` and :xml:`z` giving the coordinates for the rotating vector in real numbers (unit: rad/s (SI)). The node :xml:`` is optional and allow to specify a progressing acceleration (linear) to the final rotating velocity (requires the attribute :xml:`tf` for acceleration time). .. code-block:: xml @@ -113,35 +115,35 @@ The additional :xml:`` markup can be used to numerically integrate Symmetry terms -------------- -Both cylindrical (2D) and spherical (1D) symmetries are implemented. The additional :xml:`` markup can be used. It requires the attribute :xml:`type` that can take the value *cylindrical* ar *spherical*. It also requires an additional node depending on the symmetry terms: +Both cylindrical (2D) and spherical (1D) symmetries are implemented. The additional :xml:`` markup can be used. It requires the attribute :xml:`type` that can take the value *cylindrical* or *spherical*. It also requires an additional node to specify the radial axis: -- cylindrical: +- Cylindrical: .. code-block:: xml - + -- spherical: +- Spherical: .. code-block:: xml - + Additional physics (dev) -------------------------- +------------------------ -Depending on the model chosen in section :ref:`Sec:input:FlowModel`, tension surface effects can be added. This is the case for surface tension, viscosity and conductive heat transfers. These additional physical effects are obtained thanks to the additional markup :xml:`additionalPhysics` with the attribute :xml:`type` that can take different value according to the chosen effect. +Depending on the model chosen in section :ref:`Sec:input:FlowModel`, additional physical effects can be added. This is the case for surface tension, viscosity and conductive heat transfers. These additional physical effects are obtained thanks to the additional markup :xml:`additionalPhysics` with the attribute :xml:`type` that can take different value according to the chosen effect. Surface tension ~~~~~~~~~~~~~~~ This physical effect is obtained by using the type *surface tension*. Then it requires the node :xml:`dataSurfaceTension` with following attributes: -- :xml:`transport`: this is the name of advected variable used as color function for surface-tension terms. This advected variable has been precised in the section :ref:`Sec:input:Transport`. The name should be the same. -- :xml:`sigma`: a real number for the surface-tension coefficient in N/m. +- :xml:`transport`: This is the name of advected variable used as color function for surface-tension terms. This advected variable has been precised in the section :ref:`Sec:input:Transport`. The name should be the same. +- :xml:`sigma`: A real number for the surface-tension coefficient (unit: N/m (SI)). .. code-block:: xml @@ -149,7 +151,15 @@ This physical effect is obtained by using the type *surface tension*. Then it re +Viscosity +~~~~~~~~~ +This physical effect is obtained by using the type *viscosity* and it needs the attribute :xml:`mu` of the :xml:`` to be set in the EOS files (:ref:`Sec:IO:materials`). + +.. code-block:: xml + + + Others ~~~~~~ -in dev... \ No newline at end of file +In dev... \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap3_1_3mesh.rst b/docs/sphinx_docs/source/Chap3_1_3mesh.rst index a0236725..1d6d6e9d 100644 --- a/docs/sphinx_docs/source/Chap3_1_3mesh.rst +++ b/docs/sphinx_docs/source/Chap3_1_3mesh.rst @@ -1,10 +1,12 @@ .. role:: xml(code) :language: xml +.. _Sec:input:mesh: + MeshV5.xml ========== -Input file *meshV5.xml* is necessary to specify the geometrical characteristics of the computational domain and the kind of mesh used. This file is **mandatory** and must be present in the folder of the current case. The minimalist content of this file is: +Input file *meshV5.xml* is necessary to specify the geometrical characteristics of the computational domain and the type of mesh used. This file is **mandatory** and must be present in the folder of the current case. The minimalist content of this file is: .. code-block:: xml @@ -17,10 +19,10 @@ Input file *meshV5.xml* is necessary to specify the geometrical characteristics -The :xml:`` markup is mandatory and specifies via the attribute :xml:`structure` the kind of mesh used in the current computation: +The :xml:`` markup is mandatory and specifies via the attribute :xml:`structure` the type of mesh used in the current computation: - *cartesian*: ECOGEN automatically generates its own Cartesian mesh. See section :ref:`Sec:input:cartesian` for details. -- *unstructured*: a specific external mesh generator (not provide with ECOGEN) must be used to generate the mesh. See section :ref:`Sec:input:unstructured` for details. +- *unstructured*: A specific external mesh generator (not provide with ECOGEN) must be used to generate the mesh. See section :ref:`Sec:input:unstructured` for details. .. _Sec:input:cartesian: @@ -34,9 +36,9 @@ Cartesian mesh -ECOGEN is able to automatically generate a cartesian mesh according the markup :xml:`` which must contain the two following nodes: +ECOGEN is able to automatically generate a Cartesian mesh according to the markup :xml:`` which must contain the two following nodes: -- :xml:``: Specifies the physical dimensions of the computational domain in each physical direction corresponding to the attributes: :xml:`x`, :xml:`y` and :xml:`z` (unit: m (SI)). Values must be real numbers. +- :xml:``: Specify the physical dimensions of the computational domain in each physical direction corresponding to the attributes :xml:`x`, :xml:`y` and :xml:`z` (unit: m (SI)). Values must be real numbers. - :xml:``: Specify the number of cells in each direction corresponding to the :xml:`x`, :xml:`y` and :xml:`z` attributes. The values are integer numbers. Optional Stretching @@ -51,18 +53,18 @@ Optional Stretching -Stretching can be set optionally adding the :xml:`` node to the :xml:`` parent markup for X stretching. It should contain one or more :xml:`` node(s) equipped with the following attributes: +Stretching can be set optionally by adding the :xml:`` node to the :xml:`` parent markup (in this example for stretching in the *x*-direction). It should contain one or more :xml:`` node(s) equipped with the following attributes: -- :xml:`startAt`: real number giving the beginning position of the stretched zone. -- :xml:`endAt`: real number giving the ending position of the stretched zone. -- :xml:`factor`: real number for the stretch factor (lower than 1 for shrinking, greater than 1 for stretching). -- :xml:`numberCells`: integer for the cell number attributed to the stretched zone. +- :xml:`startAt`: Real number giving the starting position of the stretched region. +- :xml:`endAt`: Real number giving the ending position of the stretched region. +- :xml:`factor`: Real number for the stretch factor (lower than 1 for shrinking, greater than 1 for stretching). +- :xml:`numberCells`: Integer for the cell number attributed to the stretched region. -**Remark:** +**Remarks:** -1. Stretching can be set in each directions using :xml:`` and :xml:``. -2. For each stretched direction, the sum of stretched zones should exactly recover the entire domain without overlaping, but the number of cell can differ than those precised in the :xml:`` initial markup. -3. A particular attention should be paid to the linking between zones that possibily present a bad quality. +1. Stretching can be set in each direction using :xml:``, :xml:`` and :xml:``. +2. For each stretched direction, the sum of stretched regions should exactly recover the entire domain without overlapping, but the number of cells can differ those specified in the :xml:`` initial markup. +3. A particular attention should be paid to the link between regions which can possibly present bad quality. Optional AMR ~~~~~~~~~~~~ @@ -71,12 +73,12 @@ Optional AMR -An efficient Adaptive Mesh refinement (AMR) technology is embedded in ECOGEN. To do that *meshV5.xml* file must content the optional node :xml:`` of the :xml:`` markup to define the following attributes: +An efficient Adaptive Mesh refinement (AMR) technology is embedded in ECOGEN :cite:`schmidmayer2019adaptive`. To use it, the *meshV5.xml* file must contain the optional node :xml:`` of the :xml:`` markup and define the following attributes: -- :xml:`lvlMax`: integer to define the maximal number of refinements. -- :xml:`criteriaVar`: real number that controls the detection of gradients for the location of the refinement. -- :xml:`varRho`, :xml:`varP`, :xml:`varU`, :xml:`varAlpha`: boolean (*true* or *false*) to select the flow quantity on which the gradient operator is applied to detect large gradient. -- :xml:`xiSplit`, :xml:`xiJoin`: normalized real numbers to control if a computational cell, selected by its high gradient value, must be refined or un-refined (values are in the range *0-1*.). +- :xml:`lvlMax`: Integer to define the maximal number of refinements (levels). +- :xml:`criteriaVar`: Real number controlling the detection of gradients for the locations of refinement. +- :xml:`varRho`, :xml:`varP`, :xml:`varU`, :xml:`varAlpha`: Boolean (*true* or *false*) to select the flow quantities on which the gradient operator is applied to detect large gradient. +- :xml:`xiSplit`, :xml:`xiJoin`: Normalized real numbers to control if a computational cell, selected by its high gradient value, must be refined or un-refined (values are in the range *0-1*.). **Remark:** @@ -91,21 +93,22 @@ Unstructured mesh - + -When dealing with unstructured meshes, the :xml:`` markup **must be** present in the *meshV5.xml* input file and contains the following nodes: +When dealing with unstructured meshes, the :xml:`` markup **must be** present in the *meshV5.xml* input file and it contains the following nodes: -- :xml:``: 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:`` : 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). +- :xml:``: 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:``: This node is required only if the mesh file is a multi-core 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 cores. + - *false*: Do not redo the split of the given mesh (which has already been split in a previous simulation). **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. +1. The attribute :xml:`GMSHPretraitement` must be set as *true* if this is the first run with the given mesh file. +2. In the current version |version| of ECOGEN, only mesh files generated with the opensource Gmsh_ software :cite:`geuzaine2009gmsh` under file format *version 2* can be used. -Please refer to the section :ref:`Sec:tuto:generatingMeshes` for learning how to generate a mesh adapted to ECOGEN. +Please refer to the section :ref:`Sec:tuto:generatingMeshes` to learn how to generate a mesh adapted for ECOGEN. .. _Gmsh: http://gmsh.info/ \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap3_1_4initialConditions.rst b/docs/sphinx_docs/source/Chap3_1_4initialConditions.rst index ad37f523..2340339e 100644 --- a/docs/sphinx_docs/source/Chap3_1_4initialConditions.rst +++ b/docs/sphinx_docs/source/Chap3_1_4initialConditions.rst @@ -19,16 +19,16 @@ InitialConditionsV4.xml - - + + - + - + @@ -39,23 +39,25 @@ InitialConditionsV4.xml +.. _Sec:input:physicalDomains: + Physical domains ---------------- -The :xml:`` markup is mandatory. Some different initial conditions can be specified at different zones of the computational domain. This markup must contain as many nodes :xml:`` as necessary to correctly initialize the computational domain (overlaps are possible). A :xml:`` node contains the following attributes: +The :xml:`` markup is mandatory. Different initial conditions can be specified for different regions of the computational domain. This markup must contain as many nodes :xml:`` as necessary to correctly initialize the computational domain (overlaps are possible). A :xml:`` node contains the following attributes: -- :xml:`name`: a name for the domain. This name has no influence on the choices remaining in this file. +- :xml:`name`: A name for the domain. This name has no influence on the choices remaining in this file. - :xml:`state`: This is the state of the fluid which will be specified with the :xml:`` markup further in the file. -- :xml:`type`: to specify the kind of geometrical domain on which the state of the fluid must be attribute: :ref:`Sec:input:entireDomain`, :ref:`Sec:input:halfSpace`, :ref:`Sec:input:disc`, :ref:`Sec:input:rectangle`, :ref:`Sec:input:pavement`, :ref:`Sec:input:sphere`. +- :xml:`type`: Specify the type of geometric domain to which the state of the fluid will be assigned; :ref:`Sec:input:EntireDomain`, :ref:`Sec:input:HalfSpace`, :ref:`Sec:input:Disc`, :ref:`Sec:input:Rectangle`, :ref:`Sec:input:Ellipse`, :ref:`Sec:input:Cuboid`, :ref:`Sec:input:Sphere`, :ref:`Sec:input:Ellipsoid`, :ref:`Sec:input:Cylinder`. **Important remark:** -The initial conditions are attributed on each domain by using a superposition principle. The order is important: in the case of overlapping, the last attributed data are considered in the flow computation. Hence, it is important to attribute at least the entire domain at the first-place thanks to the value entireDomain. +The initial conditions are attributed on each domain by using an overlapping principle. The order is therefore important: in the case of overlapping, the last attributed data are considered in the flow computation. Hence, it is important to attribute at least the entire domain at the first place thanks to the value *entireDomain*. -According to the geometrical shape, additional information is required thanks to the use of the nodes among the list: +Depending on the geometrical shape, additional information is required through the use of the following nodes. -.. _Sec:input:entireDomain: +.. _Sec:input:EntireDomain: -entireDomain +EntireDomain ~~~~~~~~~~~~ Set the initial condition on the entire domain. No more information required. @@ -63,36 +65,36 @@ Set the initial condition on the entire domain. No more information required. -.. _Sec:input:halfSpace: +.. _Sec:input:HalfSpace: -halfSpace +HalfSpace ~~~~~~~~~ -Set the initial condition on a half-domain. The node :xml:`` must be included with the following attributes: +Set the initial condition on a half domain. The node :xml:`` must be included with the following attributes: -- :xml:`axe`: can take the value *x*, *y* or *z*. -- :xml:`origin`: real number, indicates the location of the edge between the two subdomains on the specified axis. -- :xml:`direction`: can take the value positive or negative on the specified axis. +- :xml:`axis`: Can take the value *x*, *y* or *z*. +- :xml:`origin`: Real number indicating the location of the edge between the two subdomains on the specified axis. +- :xml:`direction`: Can take a *positive* or *negative* value on the specified axis. .. code-block:: xml - + -.. _Sec:input:disc: +.. _Sec:input:Disc: -disc +Disc ~~~~ -In 2D allows to define a disc on a plane, in 3D a cylinder with an infinite length is defined. The node :xml:`` must be added with the following attributes: +In 2D, a disc is defined on a plane, while in 3D, a cylinder with an infinite length is defined. The node :xml:`` must be added with the following attributes: -- Attributes :xml:`axe1`, :xml:`axe2`: The name of 2 axes to define the plane on which the disc is defined. Can take two different values among *x*, *y* or *z*. -- Attribute :xml:`radius`: Real number of the radius disc (unit: m (SI)). -- Node :xml:`
`: requires the attributes :xml:`x`, :xml:`y` et :xml:`z` giving the location of the center of the disc in the plan (axe1, axe2) in real numbers (unit: m (SI)). +- :xml:`axis1` and :xml:`axis2`: The name of the 2 axes to define the plane on which the disc is defined. Can take two different values among *x*, *y* and *z*. +- :xml:`radius`: Real number indicating the disc radius (unit: m (SI)). +- Node :xml:`
`: Require the attributes :xml:`x`, :xml:`y` and :xml:`z`, as real numbers (unit: m (SI)), giving the location of the center of the disc in the plane (axis1, axis2). .. code-block:: xml - +
@@ -101,45 +103,63 @@ In 2D allows to define a disc on a plane, in 3D a cylinder with an infinite leng Rectangle ~~~~~~~~~ -In 2D allows to define a rectangle on a plane, in 3D a rectangular beam with an infinite length is defined. The node :xml:`< dataRectangle >` must be added with the following attributes: +In 2D, a rectangle is defined on a plane, while in 3D, a rectangular beam with an infinite length is defined. The node :xml:`< dataRectangle >` must be added with the following attributes: -- Attributes :xml:`axe1`, :xml:`axe2`: The name of 2 axes to define the plane on which the disc is defined. Can take two different values among *x*, *y* or *z*. -- Attributes :xml:`lAxe1`, :xml:`lAxe2`: Length of both sides along (axe1,axe2). -- Node :xml:``: equipped with the attributes :xml:`x`, :xml:`y` and :xml:`z`, real numbers giving the location of the inferior corner in the plane (axe1, axe2). +- :xml:`axis1` and :xml:`axis2`: The name of the 2 axes to define the plane on which the rectangle is defined. Can take two different values among *x*, *y* and *z*. +- :xml:`lAxis1` and :xml:`lAxis2`: Real number indicating the length of both sides along (axis1, axis2). +- Node :xml:``: Require the attributes :xml:`x`, :xml:`y` and :xml:`z`, as real numbers (unit: m (SI)), giving the location of the inferior corner in the plane (axis1, axis2). .. code-block:: xml - + -.. _Sec:input:Pavement: +.. _Sec:input:Ellipse: -Pavement -~~~~~~~~ -Set the initial condition in a pavement. The additional node :xml:`` must be added with the attributes: +Ellipse +~~~~~~~ +In 2D, an ellipse is defined on a plane, while in 3D, an ellipsoid with an infinite length is defined. The node :xml:`` must be added with the following attributes: -- Attributes :xml:`lAxeX`, :xml:`lAxeY`, :xml:`lAxeZ`: Real numbers for length of each side of the pavement along axes (unit: m (SI)). -- Node :xml:``: with the des attributes :xml:`x`, :xml:`y` and :xml:`z`, real numbers corresponding to the location of the inferior corner (unit: m (SI)). +- :xml:`axis1` and :xml:`axis2`: The name of the 2 axes to define the plane on which the ellipse is defined. Can take two different values among *x*, *y* and *z*. +- :xml:`radius1` and :xml:`radius2`: Real numbers indicating the ellipse radii (unit: m (SI)) along the corresponding axes. +- Node :xml:`
`: Require the attributes :xml:`x`, :xml:`y` and :xml:`z`, as real numbers (unit: m (SI)), giving the location of the center of the ellipse in the plane (axis1, axis2). .. code-block:: xml - - + + +
+ + + +.. _Sec:input:Cuboid: + +Cuboid +~~~~~~ +Set the initial condition of a cuboid. The additional node :xml:`` must be added with the attributes: + +- :xml:`lAxisX`, :xml:`lAxisY` and :xml:`lAxisZ`: Real numbers for length of each side of the cuboid along axes (unit: m (SI)). +- Node :xml:``: With the attributes :xml:`x`, :xml:`y` and :xml:`z`, real numbers corresponding to the location of the inferior corner (unit: m (SI)). + +.. code-block:: xml + + + - + -.. _Sec:input:sphere: +.. _Sec:input:Sphere: -sphere +Sphere ~~~~~~ -Set the initial condition in a sphere. The additional node :xml:`` is required with the attributes or nodes: +Set the initial condition of a sphere. The additional node :xml:`` is required with the attributes: -- Attribute radius: real number giving the radius of the sphere (unit: m (SI)). -- Node :xml:`
`: with the attributes :xml:`x`, :xml:`y` et :xml:`z` real numbers giving the ocation on the ceter of the sphere (unit: m (SI)). +- :xml:`radius`: Real number giving the radius of the sphere (unit: m (SI)). +- Node :xml:`
`: With the attributes :xml:`x`, :xml:`y` and :xml:`z`, real numbers giving the location on the center of the sphere (unit: m (SI)). .. code-block:: xml @@ -148,10 +168,47 @@ Set the initial condition in a sphere. The additional node :xml:`` i
- -Initializing using physical Identity + +.. _Sec:input:Ellipsoid: + +Ellipsoid +~~~~~~~~~ +Set the initial condition of an ellipsoid. The additional node :xml:`` is required with the attributes: + +- :xml:`axis1`, :xml:`axis2` and :xml:`axis3`: The name and therefore order of the 3 axes on which the ellipsoid is defined. Can take values among *x*, *y* and *z*. +- :xml:`radius1`, :xml:`radius2` and :xml:`radius3`: Real numbers indicating the ellipsoid radii (unit: m (SI)) along the corresponding axes. +- Node :xml:`
`: Require the attributes :xml:`x`, :xml:`y` and :xml:`z`, as real numbers (unit: m (SI)), giving the location of the center of the ellipsoid. + +.. code-block:: xml + + + +
+ + + +.. _Sec:input:Cylinder: + +Cylinder +~~~~~~~~ +Set the initial condition of a cylinder. The additional node :xml:`` is required with the attributes: + +- :xml:`axis1` and :xml:`axis2`: The name of the 2 axes to define the plane on which the disc surface of the cylinder is defined. Can take two different values among *x*, *y* and *z*. +- :xml:`radius`: Real number indicating the disc-surface radius (unit: m (SI)). +- :xml:`length`: Real number indicating the length of the cylinder (unit: m (SI)). +- Node :xml:`
`: Require the attributes :xml:`x`, :xml:`y` and :xml:`z`, as real numbers (unit: m (SI)), giving the location of the center of the cylinder. + +.. code-block:: xml + + + +
+ + + +Initializing using physical identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Additional feature for geometrical domain: It is possible to use physicalIdentity number coming from mesh software to initialize a geometrical domain. +An additional possible feature for the geometric domain is to use :xml:`physicalIdentity` number coming from mesh software to initialize a geometrical domain. Example: @@ -159,31 +216,43 @@ Example: -In this example the entire computation domain will be initialize accordingly to the physicalEntity 10. +In this example, the entire computation domain will be initialized accordingly to the :xml:`physicalIdentity` 10 from the mesh file. + +.. _Sec:input:boundaryConditions: Boundary conditions ------------------- -The :xml:`` markup is mandatory. The boundary conditions are specified at the boundary of the computational domain. This markup must contain as many nodes :xml:`` as necessary to recover the entire boundary. Each :xml:`` node contains the following attributes: +The :xml:`` markup is mandatory. The boundary conditions are specified at the boundary of the computational domain. This markup must contain as many nodes :xml:`` as necessary to cover the entire boundary. Each :xml:`` node contains the following attributes: -- name: a name for the boundary condition. This name has no influence on the choices remaining in this file. -- type: the kind of boundary condition, to choose among :ref:`Sec:input:abs`, :ref:`Sec:input:wall`, :ref:`Sec:input:tank`, :ref:`Sec:input:outflow` -- numero: integer number that correspond to the number of the boundary. +- :xml:`name`: A name for the boundary condition. This name has no influence on the choices remaining in this file. +- :xml:`type`: The type of boundary condition, to choose among :ref:`Sec:input:NonReflecting`, :ref:`Sec:input:Symmetry`, :ref:`Sec:input:Wall`, :ref:`Sec:input:Injection`, :ref:`Sec:input:Outflow` and :ref:`Sec:input:Tank`. +- :xml:`number`: Integer corresponding to the identifier of the boundary. -According :xml:``, additional information is required thanks the use of the nodes among the list: +Depending on the :xml:``, additional information is required through the use of the following nodes. -.. _Sec:input:abs: +.. _Sec:input:NonReflecting: -abs -~~~ -The numerical treatment corresponds to an outgoing flow with no wave reflection. No more information required. +Non-reflecting +~~~~~~~~~~~~~~ +The numerical treatment corresponds to an in- or out-going flow without any wave reflection. No more information required. .. code-block:: xml - + -.. _Sec:input:wall: +.. _Sec:input:Symmetry: -wall +Symmetry +~~~~~~~~ +The numerical treatment corresponds to a symmetry condition. No more information required. + +.. code-block:: xml + + + +.. _Sec:input:Wall: + +Wall ~~~~ The numerical treatment corresponds to a wall boundary condition. No more information required. @@ -191,35 +260,36 @@ The numerical treatment corresponds to a wall boundary condition. No more inform -.. _Sec:input:tank: +.. _Sec:input:Injection: -tank -~~~~ -The numerical treatment corresponds to the link between the boundary with an infinite tank. An infinite tank is characterized by a null velocity while pressure and temperature are constant). :xml:`` requires the :xml:`` node with the following attributes: +Injection +~~~~~~~~~ +The numerical treatment corresponds to the link between the boundary with a inflow. The inflow is characterized by an incoming mass-flow rate at a given thermodynamical state. :xml:`injection` requires the :xml:`` node with the following attributes: + +- :xml:`m0`: Incoming mass-flow rate, real number (unit: kg/s.m-2 (SI)). +- Node :xml:`` for each phase: It must contain as many nodes :xml:`` as the number of phases in the flow simulation and each contains the attributes: -- :xml:`p0`: Stagnation pressure, real number (unit: Pa(SI)). -- :xml:`T0`: Stagnation pressure, real number (unit: K (SI)). -- An additional :xml:`` node is necessary to define the presence of each phase in the tank. It must contain as many nodes :xml:`` as the number of phases in the flow simulation and contains the attributes: - - :xml:`EOS`: the name of the file corresponding to the choice of the EOS for the phase in the tank. This file must correspond to the one specified in modelV4.xml input file for every fluid. - - :xml:`alpha`: The volume fraction of the fluid in the tank, real number in the range ]0.,1.[ + - :xml:`EOS`: The name of the file corresponding to the choice of the EOS for the phase in the tank. This file must correspond to the one specified in *modelV4.xml* input file for every fluid. + - :xml:`density`: The density of the fluid incoming, real number (unit: kg/m3 (SI)). + - :xml:`pressure`: The pressure of the fluid incoming, real number (unit: Pa (SI)). + - :xml:`alpha`: The volume fraction of the fluid incoming, real number in the range ]0.,1.[. .. code-block:: xml - - - - - - + + + + -.. _Sec:input:outflow: +.. _Sec:input:Outflow: -outflow +Outflow ~~~~~~~ -In the case of a subsonic flow, the pressure is set equal to the ambient pressure at the boundary. The additional :xml:`` node is required with the attributes: +In the case of a subsonic flow, the pressure is set equal to the ambient (distant) pressure at the boundary. The additional :xml:`` node is required with the attributes: -- p0: outside pressure, real number (unit: Pa(SI)). +- :xml:`p0`: Outside pressure, real number (unit: Pa (SI)). +- Node :xml:``: This node is also required for each transport equation used. .. code-block:: xml @@ -229,40 +299,65 @@ In the case of a subsonic flow, the pressure is set equal to the ambient pressur +.. _Sec:input:Tank: + +Tank +~~~~ +The numerical treatment corresponds to the link between the boundary with an infinite tank. An infinite tank is characterized by a null velocity while pressure and temperature are constant. :xml:`tank` requires the :xml:`` node with the following attributes: + +- :xml:`p0`: Stagnation pressure, real number (unit: Pa (SI)). +- :xml:`T0`: Stagnation temperature, real number (unit: K (SI)). +- Node :xml:``: Necessary to define the presence of each phase in the tank. It must contain as many nodes :xml:`` as the number of phases in the flow simulation and each contains the attributes: + + - :xml:`EOS`: The name of the file corresponding to the choice of the EOS for the phase in the tank. This file must correspond to the one specified in *modelV4.xml* input file for every fluid. + - :xml:`alpha`: The volume fraction of the fluid in the tank, real number in the range ]0.,1.[. + +.. code-block:: xml + + + + + + + + + **Important remark** -The choice of the boundary condition number is made according to the kind of mesh given in meshV5.xml input file according to the following rules: +The choice of the boundary-condition number is made according to the type of mesh given in *meshV5.xml* input file and it follows the rules: + +- Cartesian: The boundaries are ordered and labeled from 1 to 6 (in 3D) according to: -- cartesian: The boundaries are ordered and labeled from 1 to 6 (in 3D) according to: - 1. boundary condition at the minimal x location - 2. boundary condition at the maximal x location - 3. boundary condition at the minimal y location - 4. boundary condition at the maximal y location - 5. boundary condition at the minimal z location - 6. boundary condition at the maximal z location -- unStructured: When an unstructured mesh is used, the number of the boundary condition must correspond to the number specified in the mesh file .geo (see example in section :ref:`Sec:tuto:generatingMeshes`). + 1. boundary condition at the minimal x location, + 2. boundary condition at the maximal x location, + 3. boundary condition at the minimal y location, + 4. boundary condition at the maximal y location, + 5. boundary condition at the minimal z location, + 6. boundary condition at the maximal z location. + +- UnStructured: When an unstructured mesh is used, the number of the boundary condition must correspond to the number specified in the mesh file .geo (see example in section :ref:`Sec:tuto:generatingMeshes`). **Remark** -The boundary conditions are dependent on the flow model specified in modelV4.xml input file. Some boundary conditions may be not available for the flow model considered. +The boundary conditions are dependent on the flow model specified in *modelV4.xml* input file. Some boundary conditions may be not available for the flow model considered. Mechanical and thermodynamical states of the fluid -------------------------------------------------- For each physical domain in the :xml:`` markup, a fluid state must correspond. It implies an additional :xml:`` markup for each state of fluid. This :xml:`` markup contains: -- as many :xml:`` nodes as the number of phases involved in the simulation. +- As many :xml:`` nodes as the number of phases involved in the simulation. - A :xml:`` node is required if a multiphase model is used. Each :xml:`` node corresponds to a phase and contains the following attributes or nodes: -- Attribute :xml:`type`: Only the value *fluide* is available in the current ECOGEN version. -- Attribute :xml:`EOS`: the name of the file corresponding to the fluid Equation of State parameters. This file must correspond to the one specified in *modelV4.xml* input file for each phase (see section :ref:`Sec:input:FlowModel`). -- Node :xml:``: contains data related to the considered state of the fluid in the current phase. +- Attribute :xml:`type`: Only the value *fluid* is available in the current ECOGEN version. +- Attribute :xml:`EOS`: The name of the file corresponding to the fluid equation-of-state parameters. This file must correspond to the one specified in *modelV4.xml* input file for each phase (see section :ref:`Sec:input:FlowModel`). +- Node :xml:``: Contain data related to the considered state of the fluid in the current phase. This last node :xml:`` as well as the :xml:`` node are dependent on the flow model according to: -.. _Sec:input:euler: +.. _Sec:input:Euler: Euler ~~~~~ @@ -270,12 +365,11 @@ Single phase flow. In this case, the :xml:`` node is absent and the :xm - Attribute :xml:`temperature`: Initial temperature of the fluid, real number (unit: K (SI)). - Attribute :xml:`pressure`: Initial pressure of the fluid, real number (unit: Pa(SI)). -- Node :xml:``: with :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector, real numbers (unit: m/s (SI)). - +- Node :xml:``: With :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector, real numbers (unit: m/s (SI)). .. code-block:: xml - + @@ -285,22 +379,22 @@ Single phase flow. In this case, the :xml:`` node is absent and the :xm Kapila ~~~~~~ -Multiphase flow at pressure and velocity equilibrium (same velocity and same pressure for every phase). Each :xml:`` node corresponds to a phase with the following attributes: +Multiphase flow at pressure and velocity equilibrium (same velocity and pressure for every phase within each cell). Each :xml:`` node corresponds to a phase with the following attributes: -- :xml:`alpha`: Volume fraction of the phase, real number in the range ]0.,1.[. -- :xml:`density`: Initial specific mass of the fluid, real number (unit: kg/m3 (SI)) or :xml:`temperature`: Initial temperature (unit: K). +- :xml:`alpha`: Volume fraction of the phase, real number in the range ]0.,1.[. The range can be increased to [0.;1.] if the option *alphaNull* is turned on (*true*) in the *modelV4.xml* input file. +- :xml:`density` or :xml:`temperature`: Initial density or temperature of the fluid, real number (unit: kg/m3 or K (SI)), respectively. Moreover, in this case, the :xml:`` node contains: -- the :xml:`` node with :xml:`pressure` attribute for initial pressure of the fluid, real number (unit: Pa(SI)). -- the :xml:`` node with :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector, real number (unit: m/s (SI)). +- Node :xml:``: With :xml:`pressure` attribute for initial pressure of the fluid, real number (unit: Pa (SI)). +- Node :xml:``: With :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector, real numbers (unit: m/s (SI)). .. code-block:: xml - + - + @@ -312,20 +406,19 @@ Moreover, in this case, the :xml:`` node contains: ThermalEq ~~~~~~~~~ -Multiphase flow at pressure, velocity and thermal equilibrium (same velocity, same pressure and same temperature for every phase). In this case, every :xml:`` node corresponds to a phase with only one attribute :xml:`alpha` setting the volume fraction real number in the range ]0.,1.[. +Multiphase flow at pressure, velocity and thermal equilibrium (same velocity, pressure and temperature for every phase within each cell). In this case, every :xml:`` node corresponds to a phase with only one attribute :xml:`alpha` setting the volume-fraction real number in the range ]0.,1.[. The :xml:`` node contains the following attributes and nodes: -- the :xml:`` node with temperature and pressure attributes for initial temperature of the fluid, real number (unit: K (SI)) and initial pressure, real number (unit: Pa). -- Attribute :xml:`pressure`: Initial pressure of the mixture, real number (unit: Pa(SI)). -- Node :xml:``: with :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector of the mixture, real numbers (unit : m/s (SI)). +- Node :xml:``: With :xml:`temperature` and :xml:`pressure` attributes for initial temperature and pressure of the fluid, real numbers (unit: K and Pa (SI)), respectively. +- Node :xml:``: With :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector of the mixture, real numbers (unit: m/s (SI)). .. code-block:: xml - + - + @@ -337,19 +430,19 @@ The :xml:`` node contains the following attributes and nodes: EulerHomogeneous ~~~~~~~~~~~~~~~~ -Multiphase flow at mechanical and thermodynamical equilibrium. In this case, every :xml:`` node corresponds to a phase with only one attribute :xml:`alpha` setting the volume fraction real number in the range ]0.,1.[. +Multiphase flow at mechanical and thermodynamical equilibrium. In this case, every :xml:`` node corresponds to a phase with only one attribute :xml:`alpha` setting the volume-fraction real number in the range ]0.,1.[. Moreover, in this case, the :xml:`` contains the following attributes and nodes: -- the :xml:`` node with :xml:`pressure` attribute for initial pressure of the mixture, real number (unit: Pa(SI)). -- Node :xml:``: with :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector of the mixture, real numbers (unit: m/s (SI)). +- Node :xml:``: With :xml:`pressure` attribute for initial pressure of the mixture, real number (unit: Pa (SI)). +- Node :xml:``: With :xml:`x`, :xml:`y` and :xml:`z` attributes setting the initial values for the components of the velocity vector of the mixture, real numbers (unit: m/s (SI)). .. code-block:: xml - + - + @@ -359,4 +452,4 @@ Moreover, in this case, the :xml:`` contains the following attributes a **Remark** -Be careful to set the volume fraction in the range ]0,.1.[ as well as the sum over the phases equal to 1. +Be careful to set the volume fraction in the range ]0,.1.[ (unless you use the option *alphaNull=true* for Kapila's model) as well as the its sum over all the phases equal to 1. diff --git a/docs/sphinx_docs/source/Chap3_1inputFiles.rst b/docs/sphinx_docs/source/Chap3_1inputFiles.rst index 82964054..12451ebf 100644 --- a/docs/sphinx_docs/source/Chap3_1inputFiles.rst +++ b/docs/sphinx_docs/source/Chap3_1inputFiles.rst @@ -6,9 +6,9 @@ Input Files =========== -The standard XML format is used for ECOGEN input files. This data format is using markups that gives to the input files some interesting flexibility. ECOGEN is using the `TinyXML-2`_ parser to read/write xml files. +The standard XML format is used for ECOGEN input files. This data format is using markups which give to the input files some interesting flexibility. ECOGEN is using the `TinyXML-2`_ parser to read/write XML files. -More information about XML format can be found at: https://www.w3schools.com/xml/ +More information about XML format can be found at: https://www.w3schools.com/xml/. ECOGEN package includes a sample of test cases. Each of them is independent, ready to use and can also be adapted and enriched to develop a new configuration. The test case to be run is chosen in the main input file: *ECOGEN.xml*. The minima structure of this file is: @@ -19,7 +19,7 @@ ECOGEN package includes a sample of test cases. Each of them is independent, rea ./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/ -In this file, the :xml:`` markup indicates the folder containing the test case to be run. It is then possible to run successively several cases by adding as many :xml:`` markup as necessary. +In this file, the :xml:`` markup indicates the folder containing the test case to be run. It is then possible to run successively several cases by adding as many :xml:`` markups as necessary. Each folder indicated in a :xml:`` markup must contain 4 input files: - *mainV5.xml* @@ -29,10 +29,10 @@ Each folder indicated in a :xml:`` markup must contain 4 input files: Additional input files depending on the test case are necessary. They are placed in the following folders: -- **ECOGEN/libEOS/**: contains the files defining the material used in the test case. -- **ECOGEN/libMeshes/**: contains the files defining the mesh used in the test case. +- **ECOGEN/libEOS/**: Contains the files defining the material used in the test case. +- **ECOGEN/libMeshes/**: Contains the files defining the mesh used in the test case (for unstructured grid). -In this section the structure of each input file is detailed. This information is also provided in a condensed form in the "handbook" files at the root folder of test cases library **ECOGEN/libTests/**. These files are named and constitute quick-reference manuals: +In this section, the structure of each input file is detailed. This information is also provided in a condensed form in the "handbook" files at the root folder of the test-case library **ECOGEN/libTests/**. These files constitute quick-reference manuals and are named as follow: - *manualMainV5.xml* - *manualMeshV5.xml* diff --git a/docs/sphinx_docs/source/Chap3_2materials.rst b/docs/sphinx_docs/source/Chap3_2materials.rst index 95bbcb26..90e8b97f 100644 --- a/docs/sphinx_docs/source/Chap3_2materials.rst +++ b/docs/sphinx_docs/source/Chap3_2materials.rst @@ -3,14 +3,17 @@ Materials ========= -For each phase, an Equation of State is required. The data for a given phase are gathered in a file. Every file must be in the folder **ECOGEN/libEOS/** and must follow rules depending on the EOS. Two equations of states are implemented in ECOGEN: +For each phase, an equation of state is required. The data for a given phase are gathered in a file. Every file must be in the folder **ECOGEN/libEOS/** and must follow rules depending on the EOS. Three equations of state are implemented in ECOGEN: -- *Ideal gas*: for gaseous phase only. -- *Stiffened gas*: for condensed matter (liquid, solid) in a pressure range where the compressible assumption is reasonable. +- :ref:`Sec:input:IdealGas`: For gaseous phase only. +- :ref:`Sec:input:StiffenedGas`: For condensed matter (liquid, solid) in a pressure range where the compressible assumption is reasonable. +- :ref:`Sec:input:NobleAbelStiffenedGas`: For condensed matter (liquid, solid) subject to phase change. + +.. _Sec:input:IdealGas: 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/ρ`): +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/\rho`: .. math:: @@ -28,7 +31,7 @@ One can easily obtain the entropy: 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 : +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 @@ -47,27 +50,28 @@ The following parameters are assumed constant and :math:`\gamma`, :math:`c_v`, : +.. _Sec:input:StiffenedGas: + Stiffened Gas ------------- -This Equation of state was first presented in 1971 by Harlow & Amdsen :cite:`harlow1968stiffenedGas`: +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: +This EOS takes into account 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: .. 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: +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 @@ -87,3 +91,45 @@ The ideal gas law is recovered if :math:`p_{\infty}=0`. The following parameters +.. _Sec:input:NobleAbelStiffenedGas: + +Noble-Abel Stiffened Gas +------------------------ + +This equation of state is an improved version of the stiffened-gas equation of state in which a parameter of covolume `b` is introduced. This parameter allows to take into account the repulsive short distance effects linked to molecular motion. The Noble-Abel Stiffened-Gas (NASG) EOS was developed in 2016 by Le Métayer & Saurel :cite:`le2016noble` and it reads: + +.. math:: + + e(p,v) = \frac{p+\gamma p_{\infty}}{\gamma-1}(v-b) + e_{ref} + +As the stiffened-gas EOS, the NASG EOS is able to take into account thermal agitation and attractive effects of condensed matter. This EOS is particularly interesting when phase transition is modeled because it is able to reproduce more accurately saturation curves of a liquid--vapor mixture than the traditionnal stiffened-gas EOS. +Hereafter, some useful relations for the specific volume, the enthalpy and the entropy: + +.. math:: + + v(p,T) &= \frac{ (\gamma-1) c_v T}{p + p_{\infty}} + b \\ + h(p,T) &= \gamma c_v T + + b p +e_{ref} \\ + s(p,T) &= c_v \ln{\left(\frac{T^{\gamma}}{\left(p+p_{\infty}\right)^{\gamma-1}} \right)} + s_{ref} + +A complete description of the obtention of these relations is given in :cite:`le2016noble`. + +The stiffened-gas EOS is recovered if :math:`b=0` and the ideal-gas law is recovered if :math:`b = p_{\infty} = 0`. The parameters :math:`\gamma`, :math:`p_{\infty}`, :math:`b`, :math:`c_v`, :math:`e_{ref}` and :math:`s_{ref}` are assumed constant. These parameters must be specified in the material file, as in the following example: + +.. code-block:: xml + + + + + + + + + \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap3_3outputFiles.rst b/docs/sphinx_docs/source/Chap3_3outputFiles.rst index 23f3e2f1..39dec077 100644 --- a/docs/sphinx_docs/source/Chap3_3outputFiles.rst +++ b/docs/sphinx_docs/source/Chap3_3outputFiles.rst @@ -3,49 +3,67 @@ Output Files ============ -Writing the result files is done according the user’s choice in *mainV5.xml* INPUT FILE of the current test (see section :ref:`Sec:input:main`). For each run, the results are recorded in the specified folder in **ECOGEN/results/XXX/** where XX is the test case *name*. +Writing the result files is done according to the user’s choice in *mainV5.xml* input file of the current test (see section :ref:`Sec:input:main`). For each run, the results are recorded in the specified folder **ECOGEN/results/XXX/** where XXX is the test case *name*. One can select the following format: - *GNU*: Format in ASCII, results are given in column. - *XML*: VTK file format (ASCII or binary). -The name of the results files follows the rules: +The result files are placed within the **ECOGEN/results/XXX/datasets/** subfolder and their names follow the rules: -result(format)_CPU(proc)_AMR(level)_TIME(instant). (ext) +result(format)_CPU(proc)_TIME(instant).(ext) -that can select results files according: +where the variables are: -- (format) : data format (empty for ASCII, B64 for binary). -- (instant) : time of writing results (depends on the selected frequency for writing. -- (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. +- (format): Data format (empty for ASCII, B64 for binary). +- (instant): Timestamp of the written result (depends on the selected frequency for writing). +- (proc): The core number where the results are from (in the case of a parallel simulation). +- (ext): Type of mesh. Using GNU format ---------------- -This format lead to results files with the (ext)=out extension. This format in colon is very useful for a quick visualization of the results when the freeware gnuplot or any other tool. When this format is selected, ECOGEN automatically creates a script file visualisation.gnu at the root of the result folder. This allows a very quick and efficient use for 1D runs. +This format leads to result files with the *(ext)=out* extension. This format in column is very useful for a quick visualization of the results using the freeware `gnuplot`_ or any other tool. When this format is selected, ECOGEN automatically creates a script file *visualization.gnu* at the root of the result folder. This allows a very quick and efficient use for 1D runs. XML VTK file format ------------------- -ECOGEN can provide output using XML files in VTK file format (ASCII or BINARY). Writing files according VTK file format leads to files with the extension: +ECOGEN can provide output using XML files in VTK file format (ASCII or BINARY). Writing files in VTK file format leads to files with the extension: -- (ext)=vtr : cartesian mesh. -- (ext)=vtu : unstructured mesh. +- *(ext)=vtr*: Cartesian mesh. +- *(ext)=vtu*: Unstructured mesh. -ECOGEN also produces a file named *collection.pvd* in order to load only one pack of files when the software PARAVIEW is used. +ECOGEN also produces files named *collectionParaview.pvd* and *collectionVisIt.visit* (or *collectionParaviewB64.pvd* and *collectionParaviewB64.pvd* for BINARY) in order to load only one pack of files when the softwares `PARAVIEW`_ and `VisIt`_ are used, respectively. Saving input files ------------------ -In addition to the results, a copy of the INPUT FILES of the current simulation is done in the subfolder **ECOGEN/results/dossierResExemple/savesEntrees/** to ensure a safe reproduction of the results. +In addition to the results, a copy of the input files of the current simulation is done in the subfolder **ECOGEN/results/XXX/savesInput/** to ensure a safe reproduction of the results. + +Probes and cuts +--------------- +All the output files linked to the probes and cuts of the simulation are placed within the subfolders **ECOGEN/results/XXX/probes/** and **ECOGEN/results/XXX/cuts/**, respectively. + +Mesh information +---------------- +When using AMR, mesh information is saved at a frequency specified in the *mainV5.xml* file to allow a restart of the simulation and the corresponding files are placed within the subfolders **ECOGEN/results/XXX/infoMesh/**. Screen output ------------- -In real time, some data are available during the simulation directly at the terminal screen as soon as ECOGEN starts. hereafter an example of a screenshot: +In real time, some data are available during the simulation directly at the terminal screen as soon as ECOGEN starts. Hereafter is an example of a screenshot: +.. figure:: ./_static/tutos/default/RunECOGEN_Logo.png + :scale: 100% + :align: center + + : Screenshot of the top of ECOGEN's default run console. + One reads: -- number of the results files. -- number of the last timestep. -- Real time in the simulation. -- Value of the last timestep. -- CPU time since the beginning of the simulation. +- number of the result files, +- number of the last timestep, +- physical time in the simulation, +- value of the last timestep, +- CPU time since the beginning of the simulation, +- CPU time spent in AMR routines since the beginning of the simulation. + +.. _gnuplot: http://www.gnuplot.info/ +.. _PARAVIEW: https://www.paraview.org/ +.. _VisIt: https://wci.llnl.gov/simulation/computer-codes/visit/ \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap3_IO_Chapter.rst b/docs/sphinx_docs/source/Chap3_IO_Chapter.rst index 7ed9fa84..8942f5c6 100644 --- a/docs/sphinx_docs/source/Chap3_IO_Chapter.rst +++ b/docs/sphinx_docs/source/Chap3_IO_Chapter.rst @@ -2,7 +2,7 @@ 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`. +ECOGEN settings are managed via input files only. The global input- and output- file structure is depicted in :numref:`Fig:userGuide:overview`. .. _Fig:userGuide:overview: diff --git a/docs/sphinx_docs/source/Chap4_1startWithECOGEN.rst b/docs/sphinx_docs/source/Chap4_1startWithECOGEN.rst index e55f6f67..c376c484 100644 --- a/docs/sphinx_docs/source/Chap4_1startWithECOGEN.rst +++ b/docs/sphinx_docs/source/Chap4_1startWithECOGEN.rst @@ -1,20 +1,22 @@ -.. _Sec:tuto:begin: - .. role:: xml(code) :language: xml +.. _Sec:tuto:begin: + ***************** Start with ECOGEN ***************** -Here is described your first use of ECOGEN: running the *default test case*. This is what user should observe without any change in the downloaded ECOGEN package. +Here is described your first use of ECOGEN: Running the *default test case*. This is what user should observe without any change in the downloaded ECOGEN package. .. important:: - Before beginning with ECOGEN, you should have succeed all steps of installation instructions of section :ref:`Chap:Start`. + Before starting with ECOGEN, you should have passed all steps of installation instructions of section :ref:`Chap:Start`. + +.. _Sec:tuto:mainXML: -The conductor input file -======================== +The main input file +=================== ECOGEN is mainly controled thanks to the input file named *ECOGEN.xml*. This file looks like : .. code-block:: xml @@ -30,15 +32,15 @@ ECOGEN is mainly controled thanks to the input file named *ECOGEN.xml*. This fil Each test case corresponds to specific input files organised in different folders and associated to a markup :xml:``. -When executing ECOGEN, it will run each test case corresponding to the uncommented lines present in the markup :xml:``. +When executing ECOGEN, it runs sequentially each test case corresponding to the uncommented lines present in the markup :xml:``. -A unique line is uncommented in the original file and corresponds to the *default test case*. One should modify the *ECOGEN.xml* input file to run other provided test by uncommenting / commenting lines in this file. New lines can also be added when creating new test cases. +A unique line is uncommented in the original file and corresponds to the *default test case*. One should modify the *ECOGEN.xml* input file to run other provided test by uncommenting/commenting lines in this file. New lines can also be added when creating new test cases. .. _Sec:tuto:default: Running the default test case ============================= -The default test case provided with ECOGEN package is a single flow test which simply advect a density discontinuity with a positive velocity in 1D. Input files for this test case are present in the folder *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/* +The default test case provided with ECOGEN package is a single-phase flow test which simply advect a density discontinuity with a positive velocity in 1D. Input files for this test case are present in the folder *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/*. .. _Fig:tutos:default:CI: @@ -46,7 +48,7 @@ The default test case provided with ECOGEN package is a single flow test which s :scale: 70% :align: center - Initial condition for single phase 1D transport test case. + Initial condition for 1D, single-phase transport test case. The initial characteristics of the run are: @@ -68,7 +70,7 @@ The initial characteristics of the run are: | solution printing frequency | 0.036 ms | +-----------------------------+--------------+ -This test can be executed on single CPU or on XX CPU by one of the commands: +This test can be executed on a single core or on XX cores by one of the commands: .. code-block:: console @@ -77,43 +79,45 @@ This test can be executed on single CPU or on XX CPU by one of the commands: .. note:: - Informations on available CPU can be obtained under linux system using the command: + Information on available cores can be obtained under linux system using the command: .. code-block:: console /usr/bin/nproc -The code is running and at the top of the console output one can read : +The code is running and at the top of the console output one can read: - The console logo of ECOGEN - The name of the test case including the full path of the test case : *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/* - - Information concerning the number of iterations, the elapsed time... + - Information concerning the number of iterations, the elapsed time, etc. -*euler1DTransportPositiveVelocity* is the actual name of the default run. +*euler1DTransportPositiveVelocity* is the name of the default run. .. figure:: ./_static/tutos/default/RunECOGEN_Logo.png :scale: 100% :align: center - : Screenshot of the top of ECOGEN default run console. In this particular run, 8 CPU have been used. + Screenshot of the top of ECOGEN's default run console. In this particular run, 8 cores have been used. -The code ends and the following information comes: +The run ends and the following information comes: .. figure:: ./_static/tutos/default/RunECOGEN_NormalEnding.png :scale: 100% :align: center - : Screenshot of the end of the default run console with 8 CPU used. + Screenshot of the end of ECOGEN's default run console with 8 cores used. -A new folder *results* is created at the first run, (unusefull to remove it). This folder contains a folder named *euler1DTransportPositiveVelocity* containing output files of our test case. Are included in : +A new folder *results* is created at the first run (unusefull to remove it). This folder contains a folder named *euler1DTransportPositiveVelocity* containing output files of our test case: - - *collection.pvd* used in *Paraview* software and the associated *vtu* files - - *infoCalcul.out* - - *infoMesh* folder - - *probes* folder - - *savesInput* folder: a kind of log folder that contains the *xml* files used for this run. + - *collectionParaview.pvd* and *collectionVisIt.visit* used in *Paraview* and *VisIt* softwares, + - *datasets* folder containing the associated *vtu* files, + - *infoCalcul.out*, + - *infoMesh* folder, + - *probes* folder, + - *cuts* folder, + - *savesInput* folder; a kind of log folder that contains the *XML* files used for this run. -By default, output files are recorder in VTK XML format in separate files for each CPU, AMR level and TIME. A way to post-treat this output files is to open the *collection.pvd* file using Paraview_ software. +By default, output files are recorder in VTK XML format in separate files for each core and TIME. A way to post-treat this output files is to open the *collectionParaview.pvd* or *collectionVisIt.visit* file using Paraview_ or VisIt_ software. .. _Fig:tutos:default:results: @@ -121,28 +125,29 @@ By default, output files are recorder in VTK XML format in separate files for ea :scale: 50% :align: center - Results for the single phase transport test + Results for the single-phase transport test. -This basic test shows advection of a contact discontinuity while preserving pressure and velocity uniform conditions. +This basic test shows advection of a contact discontinuity while preserving pressure and velocity uniform. Editing input files ------------------- Input files for this test case are located in the following folder: *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/*. -Computation parameters will easily be modified according to the input file description of section :ref:`Chap:input` +Computation parameters are easily modified according to the input file description of section :ref:`Chap:input`. -For example, one can prefer to visualise results under *gnu* file format. For that simply turn the *xml* option in the xml file *\libTests\referenceTestCases\euler\1D\transport\positiveVelocity\mainV5.xml* into *gnu* and re-run the test case: +For example, one can prefer to visualize results under *gnu* file format. For that, simply turn the *XML* option in the XML file *\libTests\referenceTestCases\euler\1D\transport\positiveVelocity\mainV5.xml* into *gnu* and re-run the test case: .. code-block:: xml -The results can be drawn by loading in the Gnuplot software the file *visualisation.gnu*. +The results can be drawn by loading in the Gnuplot software the file *visualization.gnu*. .. figure:: ./_static/tutos/default/GnuplotScreenshotDefaultUse.png :scale: 75% :align: center - : Screenshot of results in *Gnuplot* + Screenshot of results in *Gnuplot*. -.. _Paraview: https://www.paraview.org/ \ No newline at end of file +.. _Paraview: https://www.paraview.org/ +.. _VisIt: https://wci.llnl.gov/simulation/computer-codes/visit/ \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap4_2generatingMeshes.rst b/docs/sphinx_docs/source/Chap4_2generatingMeshes.rst index 8bee4c33..5bbfeb31 100644 --- a/docs/sphinx_docs/source/Chap4_2generatingMeshes.rst +++ b/docs/sphinx_docs/source/Chap4_2generatingMeshes.rst @@ -3,24 +3,24 @@ Generating Meshes ================= -ECOGEN is able to generate its own Cartesian meshes (see section :ref:`Sec:input:cartesian`), but for structured non Cartesian or unstructured meshes, as seen in section :ref:`Sec:input:unstructured`, an exeternal mesh software is required to generate mesh files. +ECOGEN is able to generate its own Cartesian meshes (see section :ref:`Sec:input:cartesian`), but for structured non Cartesian or unstructured meshes, as seen in section :ref:`Sec:input:unstructured`, an external mesh software is required to generate mesh files. Mesh files with Gmsh -------------------- -ECOGEN can use mesh files for mono- or multiprocessors computations generated with the opensource Gmsh_ software :cite:`geuzaine2009gmsh` with some specific precaution when editing the geometry file (.geo). Only the `MSH file format version 2`_ can be used in the current released version of ECOGEN. +ECOGEN can use mesh files for single- or multi-core computations generated with the open-source Gmsh_ software :cite:`geuzaine2009gmsh` with some specific precautions when editing the geometry file (*.geo*). Only the `MSH file format version 2`_ can be used in the current released version |version| of ECOGEN. Download binaries of Gmsh in version 3.0.6 or lower : http://gmsh.info/bin/. Here are the restrictions that should be used when generating a geometry with Gmsh_: -- Each part of the domain occupied by the fluid should correspond to a physical surface or a physical volume which is attribute to the value *10*. -- Each boundary condition must correspond to a physical line or a physical surface. The values are successively taken from *1* to maximum *9*. This is an important point that will be used to define boundary conditions physical treatment in the *initialConditionsV4.xml* input file described in section :ref:`Sec:input:InitialConditions`. +- Each part of the domain occupied by the fluid should correspond to a physical surface or a physical volume which is attributed to the value *10*. +- Each boundary condition must correspond to a physical line or a physical surface. The values are successively taken from *1* to maximum *9*. This is an important point that will be used to define boundary conditions with physical treatment in the *initialConditionsV4.xml* input file described in section :ref:`Sec:input:InitialConditions`. -Below are presented examples: +Below is presented an example. -Generating a nozzle structured mesh -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Generating a nozzle unstructured mesh +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Consider the geometry file of a simple nozzle depicted below: @@ -28,24 +28,24 @@ Consider the geometry file of a simple nozzle depicted below: .. figure:: ./_static/tutos/gmsh/simpleNozzle.png - Example of geometrical data file - nozzle2D_simple2.geo – for generating a mesh file at .msh format using Gmsh software and usable with ECOGEN. + Example of geometrical data file -- nozzle2D_simple2.geo –- for generating a mesh file with *.msh* format using Gmsh software and usable with ECOGEN. This correponds to the geometry file available in `ECOGEN/libMeshes/nozzles/nozzle2D_simple2.geo`_. -The computational domain is a nozzle, the mesh is unstructured with quadrangles. In that case, one should take care that the fluid surface is defined by the value *10* and that 4 boundaries conditions are set with the following numerotation: +The computational domain is a nozzle, the mesh is unstructured with quadrangles. In that case, one should take care that the fluid surface is defined by the value *10* and that 4 boundary conditions are set with the following numbering: -- Symetrical axis: 1 (condLimAxe =1) -- Wall: 2 (condLimParoi =2) -- Inflow: 3 (condLimEntree =3) -- Outflow: 4 (condLimSortie =3) +- Symmetrical axis: 1 (*condLimAxe = 1*) +- Wall: 2 (*condLimParoi = 2*) +- Inflow: 3 (*condLimEntree = 3*) +- Outflow: 4 (*condLimSortie = 4*) -The corresponding *initialConditionV4.xml* should then contains for example the following markup: +The corresponding *initialConditionV4.xml* file should then contains for example the following markups: .. code-block:: xml - + @@ -55,7 +55,7 @@ The corresponding *initialConditionV4.xml* should then contains for example the -That correponds to initialization of a nozzle connected to a tank on the left and to an outflow at imposed pressure to the right. +This correponds to initialization of a nozzle connected to a tank on the left and to an outflow at imposed pressure to the right. .. _Gmsh: http://gmsh.info/ .. _`MSH file format version 2`: http://gmsh.info/doc/texinfo/gmsh.html#MSH-file-format-version-2-_0028Legacy_0029 diff --git a/docs/sphinx_docs/source/Chap4_3restartRun.rst b/docs/sphinx_docs/source/Chap4_3restartRun.rst new file mode 100644 index 00000000..8e99367a --- /dev/null +++ b/docs/sphinx_docs/source/Chap4_3restartRun.rst @@ -0,0 +1,129 @@ +.. role:: xml(code) + :language: xml + +.. _Sec:tuto:restart: + +************* +Restart a run +************* + +ECOGEN is able to restart a finished computation from given result files. This feature is particularly interesting if a simulation stopped due to computer failure (power cut, unexpected update...) or if the user wants to extent the duration of simulation without restarting from the beginning. + +To illustrate this tutorial, we will use a common test case, based on the shock-tube problem available at :ref:`Chap:TestCases`: + +.. code-block:: xml + + ./libTests/referenceTestCases/euler/1D/shockTubes/HPLeft/ + +Setup of the test case +====================== + +For the purpose of this tutorial we have to do some slight modifications of the test case presented above. We advise you to make a copy of the test case **./libTests/referenceTestCases/euler/1D/shockTubes/HPLeft/** into a new path such as **./libTests/myTests/restartRun/**. + +For the sake of simplicity, we edit the *mainV5.xml* file as following: + +.. code-block:: xml + + + + restartRun + + + + + + + + vanleer + + + + +We removed the probe section and changed the time control mode to iterations with a printing of data each 50 iterations for a total of 500 iterations. + +Following the same idea of simpler test case we edit the file *meshV5.xml* by commenting the AMR feature and add more cells: + +.. code-block:: xml + + + + + + + + + + + +Now everything is all set, we will run this test case a first time and after that, we will extend the duration of the simulation to 1000 iterations. + +.. important:: + + To run this simulation, it is required to update the main input file named *ECOGEN.xml* (see :ref:`Sec:tuto:begin`). To add your new run you can add the line :xml:`./libTests/myTests/restartRun/` to the end of this file. Be aware to check if other test cases are uncommented to avoid other simulations. + +Initial run +=========== + +Run the simulation with **XX** cores: + +.. code-block:: console + + ./ECOGEN + mpirun -np XX ECOGEN + +Once started, the output on the console looks like: + +.. figure:: ./_static/tutos/restartRun/runInit.png + :scale: 75% + :align: center + + Console screenshot of the initial run. + +Once the simulation is done, we can check in the result folder **./results/restartRun/datasets/** the total number of iterations extracted. The last file has the name *results_CPUxx_TIME10.vtr* which indicates that the number of extracted files is indeed 10 as specified in the *mainV5.xml* file (500 physical iterations, results printed every 50 interations giving a total of 500/50 = 10 output files). This number corresponds to the *restartFileNumber* of the the block :xml:``. + +Obviously, in this case we know the total number of time iterations extracted because we waited the end of the simulation. However, it could be useful to get this number if the simulation stopped suddenly, or if the time control mode used was time. + +Resume run +========== + +Now that we know the last time iteration, we can resume this simulation to add 500 additionnal time iterations. To this end, we modify the block :xml:`` of the *mainV5.xml* file to specify the last file number: + +.. code-block:: xml + + + +Accordingly we add the additionnal time iterations: + +.. code-block:: xml + + + +All is left to do is to run again the simulation. + +.. important:: + + When you choose to resume a simulation you have to use the same number of cores as before. + +It is possible to notice on the console output that the simulation is well resumed: + +.. figure:: ./_static/tutos/restartRun/restartRun.png + :scale: 75% + :align: center + + Console screenshot of the run restarted. + +Once the simulation completed, it is possible to compare the initial run with the resumed one: + +.. figure:: ./_static/tutos/restartRun/compareRun.png + :scale: 60% + :align: center + + Pressure visualization for the restarted and initial runs with a maximal number of extracted files of 20 (left) and 10 (right), respectively. + +We can clearly see that at 1000 iterations the expansion fan left the tube on the left side whereas at 500 iterations the initial left state is still present. + +Additionnal remarks +=================== + +* It is essential that the result folder of the initial simulation keeps the same name for the restarted run. +* For AMR simulations, one also needs to specify the frequency :xml:`AMRsaveFreq` at which necessary restart files are saved (default is 0). \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap4_4splitPhysicalDomainsNS.rst b/docs/sphinx_docs/source/Chap4_4splitPhysicalDomainsNS.rst new file mode 100644 index 00000000..efffbe80 --- /dev/null +++ b/docs/sphinx_docs/source/Chap4_4splitPhysicalDomainsNS.rst @@ -0,0 +1,188 @@ +.. role:: xml(code) + :language: xml + +.. _Sec:tuto:splitDomains: + +********************************************** +Split physical domains for unstructured meshes +********************************************** + +ECOGEN is able to initialize fluid domains according to geometrical physical domains for Gmsh_ unstructured mesh (see :ref:`Sec:tuto:generatingMeshes`). Of course, it is also possible to initialize the computational domain with predefined type domain as described in the section :ref:`Sec:input:InitialConditions`. However, in this tutorial, we will focus on how to initialize fluid physical domains in ECOGEN according to geometrical domains defined in the geometry file of Gmsh *.geo*. + +For the purpose of this tutorial, we will use a 2D single-phase shock tube of 1m length and 1m height (more information about this setup can be found at :ref:`Chap:TestCases`). The tube is filled with air (:math:`\rho = 1.225 \, kg /m^3`) initially at rest, the left chamber pressure is :math:`P_L = 5 \, bar` and the right chamber pressure is fixed at :math:`P_R = 1 \, bar`. + +Geometry and mesh +================= + +The 2D tube is defined by a 1x1 square. To design the initial interface between the left and right chamber we create two points on the upper and lower part (**Point(5)** and **Point(6)**) of the domain, that are connected by **Line(7)**: + + +.. figure:: ./_static/tutos/splitPhysicalDomains/meshTube.png + :scale: 30% + :align: center + + Geometry and mesh (triangular elements) of the 2D shock tube on Gmsh_ software. + +The complete geometry configuration file (*.geo*) is the following: + +.. code-block:: none + + //Mesh size + dx = 0.05; + + // Physical domains number + walls = 1; + leftChamber = 2; + rightChamber = 3; + + // Geometry definition + Point(1) = {0, 0, 0, dx}; + Point(2) = {1, 0, 0, dx}; + Point(3) = {1, 1, 0, dx}; + Point(4) = {0, 1, 0, dx}; + Point(5) = {0.5, 0, 0, dx}; + Point(6) = {0.5, 1, 0, dx}; + + Line(1) = {1, 4}; + Line(2) = {4, 6}; + Line(3) = {6, 3}; + Line(4) = {3, 2}; + Line(5) = {2, 5}; + Line(6) = {5, 1}; + + Line(7) = {5,6}; // Interface between chambers + + // Boundary conditions + Physical Line(walls) = {1, 2, 3, 4, 5, 6}; + + // Left Chamber domain + Line Loop(8) = {1, 2, -7, 6}; + Plane Surface(9) = {8}; + Physical Surface(leftChamber) = {9}; + + // Right chamber domain + Line Loop(10) = {3, 4, 5, 7}; + Plane Surface(11) = {10}; + Physical Surface(rightChamber) = {11}; + +Setup of the test case +====================== + +Let's start with the *mainV5.xml* file. We use an *XML* output mode with time control set to *iterations* and a *CFL* number of *0.8*: + +.. code-block:: xml + + + + shockTubeUnstructured + + + + + + + + +To solve this flow we use the model *Euler* with air considered as ideal gas. Thus, the *modelV4.xml* file is: + +.. code-block:: xml + + + + + + + +Reading of the unstructured mesh is done throught the *meshV5.xml* file: + +.. code-block:: xml + + + + + + + + + +All that remains to be done is to initialize the chambers with the corresponding fluid states. To this end, we define two :xml:`physicalDomains` of type *entireDomain*, one for each chamber. The link between the physical domains of the geometry file *.geo* and ECOGEN is made by the attribute :xml:`physicalEntity`. As given above on the *.geo* file, the left chamber has the physical entity number 2 and the right chamber has the number 3. Therefore, the *initialConditionsV4.xml* file is: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Add the new test case to the main input file *ECOGEN.xml*: :xml:`./libTests/myTest/`. + +Run the test case simulation with **XX** cores: + +.. code-block:: console + + ./ECOGEN + mpirun -np XX ECOGEN + +.. important:: + + Be aware to partition the mesh file with the corresponding number of cores used for the simulation if parallel computation is desired. Gmsh pre-treatment attribute :xml:`GMSHPretraitement` of the *meshV5.xml* file might be set to *true* in this case. + +Results +======= + +Initially, the configuration of the shock tube is as follows: + +.. figure:: ./_static/tutos/splitPhysicalDomains/postProcessInit.png + :scale: 30% + :align: center + + Pressure visualization (left) and 1D plot of pressure and velocity along the length of the tube (right) at the initial time. Visualization using Paraview_ software. + +It is clearly visible that the addition of the line along the interface makes it possible to obtain a mesh with a straight separation at this location. In the absence of this line, the initialization of the fluid states using a :xml:`halfSpace` leads to an initial interface deformed by the cells position: + +.. figure:: ./_static/tutos/splitPhysicalDomains/halfSpaceInit.png + :scale: 40% + :align: center + + Pressure visualization at the initial time. Visualization using Paraview_ software. + +Of course, for this test case configuration, it is possible to obtain an equivalent result without declaring two physical domains in the geometry file. By keeping the middle line of the geometry file, the straight separation is ensured and it is therefore possible to define in the *initialConditionsV4.xml* file an :xml:`entireDomain` domain for the left chamber and a :xml:`halfSpace` domain located at :math:`x = 0.5 \, m` with a positive direction for the right chamber. + +However, it can be particularly interesting to use an initialization of the fluid states with the definition of the physical domains from the geometry, in case the fluid regions are too complex to define with the predefined ECOGEN domains. + +After few timesteps, the flow is the following: + +.. figure:: ./_static/tutos/splitPhysicalDomains/postProcess.png + :scale: 30% + :align: center + + Pressure visualization (left) and 1D plot of pressure and velocity along the length of the tube (right) after few timesteps. Visualization using Paraview_ software. + +.. _Gmsh: http://gmsh.info/ +.. _Paraview: https://www.paraview.org/ diff --git a/docs/sphinx_docs/source/Chap4_tutorials_Chapter.rst b/docs/sphinx_docs/source/Chap4_tutorials_Chapter.rst index fc710630..327fc6b0 100644 --- a/docs/sphinx_docs/source/Chap4_tutorials_Chapter.rst +++ b/docs/sphinx_docs/source/Chap4_tutorials_Chapter.rst @@ -3,7 +3,7 @@ Tutorials ========= -Here are presented a collection of tutorials to help using efficiently ECOGEN. One should began with the section :ref:`Sec:tuto:begin` when first use of ECOGEN. +Here are presented a collection of tutorials to help you use ECOGEN efficiently. One should begin with the section :ref:`Sec:tuto:begin` for the first use of ECOGEN. .. toctree:: :maxdepth: 1 @@ -11,3 +11,6 @@ Here are presented a collection of tutorials to help using efficiently ECOGEN. O Chap4_1startWithECOGEN Chap4_2generatingMeshes + Chap4_3restartRun + Chap4_4splitPhysicalDomainsNS + \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap5_1Euler.rst b/docs/sphinx_docs/source/Chap5_1Euler.rst index d2f324d6..94afbf1f 100644 --- a/docs/sphinx_docs/source/Chap5_1Euler.rst +++ b/docs/sphinx_docs/source/Chap5_1Euler.rst @@ -1,11 +1,11 @@ .. role:: xml(code) :language: xml -************************ -Single phase test cases -************************ +*********************** +Single-phase test cases +*********************** -Test cases presented in this section are dealing with single phase compressible problems. In this part, ECOGEN solves the Euler equations :cite:`euler1757principes`: +Test cases presented in this section are dealing with single-phase compressible problems. In this part, ECOGEN solves the Euler equations :cite:`euler1757principes`: .. math:: :nowrap: @@ -21,11 +21,11 @@ Test cases presented in this section are dealing with single phase compressible where :math:`\rho` represents the density, :math:`\mathbf{u}`` the velocity vector, :math:`p` the pressure and :math:`E = e +\frac{\mathbf{u}^2}{2}` the total energy, with :math:`e` the internal energy. The closure relation for this model is ensured by any convex equation of state (EOS) :math:`p = p(\rho,e)` (see section :ref:`Sec:IO:materials` for details about implemented EOS in ECOGEN). -Euler equations are solved thanks to an explicit finite volume Godunov-like scheme :cite:`godunov79` that is coupled with HLLC Riemann :cite:`toro2013riemann` solver for fluxes computation. +Euler equations are solved thanks to an explicit finite-volume Godunov-like scheme :cite:`godunov79` that is coupled with HLLC approximate Riemann solver :cite:`toro2013riemann` for flux computation. Advection test cases ==================== -Basics advection test cases are proposed: +Basic advection test cases are proposed: .. code-block:: xml @@ -33,11 +33,11 @@ Basics advection test cases are proposed: ./libTests/referenceTestCases/euler/1D/transport/negativeVelocity/ ./libTests/referenceTestCases/euler/2D/transports/rectangleDiagonal/ -The first one is the default test case fully described in tutorial section :ref:`Sec:tuto:default`. The second one is the reverse test advecting the contact discontinuity in the opposite direction. +The first one is the default test case fully described in the tutorial section :ref:`Sec:tuto:default`. The second one is the reverse test advecting the contact discontinuity in the opposite direction. The third is described below. rectangleDiagonal ----------------- -This test is a 2D Cartesian test case with advection of a rectangle of high density air into low density air environnement. The computation uses the AMR techniques of :cite:`schmidmayer2019adaptive`. This test is referenced in ./libTests/referenceTestCases/euler/2D/transports/rectangleDiagonal/. A sketch of initial conditions for this test is presented in figure :numref:`Fig:testCases:Euler:2DtransportCI`. +This test is a 2D Cartesian test case with advection of a rectangle of high-density air into low-density air environment. The computation uses the AMR technique of :cite:`schmidmayer2019adaptive`. This test is referenced in *./libTests/referenceTestCases/euler/2D/transports/rectangleDiagonal/*. A sketch of the initial conditions for this test is presented in figure :numref:`Fig:testCases:Euler:2DtransportCI`. .. _Fig:testCases:Euler:2DtransportCI: @@ -45,12 +45,12 @@ This test is a 2D Cartesian test case with advection of a rectangle of high dens :scale: 70% :align: center - Initial condition for single phase 2D transport test case. + Initial conditions for the 2D, single-phase transport test case. The initial characteristics of the run are: +-----------------------------+----------------------+ -| Characteristic | value | +| Characteristic | Value | +=============================+======================+ | dimensions | 1 m x 1 m | +-----------------------------+----------------------+ @@ -60,7 +60,7 @@ The initial characteristics of the run are: +-----------------------------+----------------------+ | rectangle position | 0.2 m, 0.2 m | +-----------------------------+----------------------+ -| boundary conditions | transmittive | +| boundary conditions | non-reflecting | +-----------------------------+----------------------+ | final solution time | 0.36 ms | +-----------------------------+----------------------+ @@ -69,7 +69,7 @@ The initial characteristics of the run are: | precision | 2nd order (superbee) | +-----------------------------+----------------------+ -Bcause of adaptative mesh refinement, the final number of computational cells is 5383. Results are shown on figure :numref:`Fig:testCases:Euler:2Dtransport`. The left picture shows the evolution of mesh during simulation (red color is for high gradients of density). Right top picture represents density contours and bottom right figure is to check for constant pressure preservation along the diagonal. +Because of the adaptative mesh refinement, the final number of computational cells is 5383. Results are shown on figure :numref:`Fig:testCases:Euler:2Dtransport`. The left picture shows the evolution of the mesh during the simulation (red color is for high gradients of density). Upper right picture represents density contours and lower right picture is to check for constant pressure preservation along the diagonal. .. _Fig:testCases:Euler:2Dtransport: @@ -77,11 +77,11 @@ Bcause of adaptative mesh refinement, the final number of computational cells is :scale: 70% :align: center - Advection of a high density rectangle of air. Visualization using Paraview_ software. + Advection of a high-density rectangle of air. Visualization using Paraview_ software. Shock tubes =========== -Single phase shock tubes are proposed in following test cases: +Single-phase shock tubes are proposed in the following test cases: .. code-block:: xml @@ -92,7 +92,7 @@ Single phase shock tubes are proposed in following test cases: HPLeft ------ -This is a classical single phase shock tube filled with air. The test is available in the folder ./libTests/referenceTestCases/euler/1D/shockTubes/HPLeft/ +This is a classical single-phase shock tube filled with air. The test is available in the folder *./libTests/referenceTestCases/euler/1D/shockTubes/HPLeft/*. .. _Fig:testCases:Euler:shockTubeCI: @@ -100,12 +100,12 @@ This is a classical single phase shock tube filled with air. The test is availab :scale: 70% :align: center - Initial condition for single phase shock tube. + Initial condition for single-phase shock tube. The initial characteristics of the run are: +-----------------------------+----------------------+ -| Characteristic | value | +| Characteristic | Value | +=============================+======================+ | dimension | 1 m | +-----------------------------+----------------------+ @@ -115,7 +115,7 @@ The initial characteristics of the run are: +-----------------------------+----------------------+ | diaphragm position | 0.4 m | +-----------------------------+----------------------+ -| boundary conditions | transmittive | +| boundary conditions | non-reflecting | +-----------------------------+----------------------+ | final solution time | 0.6 ms | +-----------------------------+----------------------+ @@ -126,11 +126,11 @@ The initial characteristics of the run are: Solution of this Riemann problem induces 3 waves: -- A fan of rarefaction waves propagating in high pressure chamber -- A Right-facing shock wave propagating in low pressure chamber -- A contact discontinuity +- expansion waves propagating in high-pressure chamber, +- a right-facing shock wave propagating in low-pressure chamber, +- a contact discontinuity. -This three waves are clearly visible on the results: +These waves are clearly observable on the results: .. _Fig:testCases:Euler:shockTube: @@ -148,13 +148,13 @@ This test is also equipped with 3 Eulerian sensors. For example, two sensors are :scale: 70% :align: center - Pressure recorded by sensors at :math:`x = 0.6 m` (pink color) and :math:`x = 0.8 m` (green color). Visualization using gnuplot_ software. + Pressure recorded by sensors at :math:`x = 0.6 m` (pink) and :math:`x = 0.8 m` (green). Visualization using gnuplot_ software. -The first sensor see its pressure rising because of the shock wave before the second one. Because this Riemann problem generates a supersonic flow after the shock wave, the tail of the rarefaction waves fan is seen by the sensor after 0.5 ms. +The first sensor see its pressure rising first because of the shock wave. Because this Riemann problem generates a supersonic flow after the shock wave, the tail of the expansion waves is seen by the sensor after 0.5 ms. Other test cases ================ -Other tests are provided with ECOGEN package. They will be described in details soon. +Other tests are provided within the ECOGEN package. They will soon be described in details. .. code-block:: xml diff --git a/docs/sphinx_docs/source/Chap5_2Kapila.rst b/docs/sphinx_docs/source/Chap5_2Kapila.rst index 13656f1c..8d6b09e0 100644 --- a/docs/sphinx_docs/source/Chap5_2Kapila.rst +++ b/docs/sphinx_docs/source/Chap5_2Kapila.rst @@ -5,7 +5,7 @@ Multiphase mechanical equilibrium flows *************************************** -Mechanical equilibrium flows are solved in ECOGEN using the Kapila model :cite:`kapila2001`. In the particular case of 2 phases invilved, this model reads: +Mechanical equilibrium flows are solved in ECOGEN using Kapila's model :cite:`kapila2001`. In the particular case of 2 phases involved and without any extra physics (surface tension, viscosity...), this model reads: .. math:: :nowrap: @@ -42,7 +42,7 @@ This model is solved thanks to the numerical method presented in :cite:`relaxjcp Advection test cases ==================== -The code is provided with following test cases for advections: +The code is provided with the following test cases for advections: .. code-block:: xml @@ -51,7 +51,7 @@ The code is provided with following test cases for advections: interfaceWaterAir ----------------- -This first test case is important since it validates the capacity of the numerical method to treat simple advection of an interface between pure fluid without creating spurious oscillations on pressure or velocity profiles. Input files for this test are available in ./libTests/referenceTestCases/kapila/1D/transports/interfaceWaterAir/ +This first test case is important since it validates the capacity of the numerical method to treat simple advection of an interface between pure fluid without creating spurious oscillations on pressure or velocity profiles. Input files for this test are available in *./libTests/referenceTestCases/kapila/1D/transports/interfaceWaterAir/*. .. _Fig:testCases:Kapila:advection1DCI: @@ -59,29 +59,29 @@ This first test case is important since it validates the capacity of the numeric :scale: 70% :align: center - Initial condition for 1D advection of water/air interface. + Initial condition for 1D advection of water--air interface. The initial characteristics of the run are: -+-----------------------------+--------------+ -| Characteristic | value | -+=============================+==============+ -| dimension | 1 m | -+-----------------------------+--------------+ -| Mesh size | 800 | -+-----------------------------+--------------+ -| interface position | 0.3 m | -+-----------------------------+--------------+ -| boundary conditions | transmittive | -+-----------------------------+--------------+ -| final solution time | 0.7 ms | -+-----------------------------+--------------+ -| solution printing frequency | 0.025 ms | -+-----------------------------+--------------+ -| precision | 1st order | -+-----------------------------+--------------+ - -In the default case, the computation is performed with a 1st order scheme. We compare this solution with those obtained using the 2nd order scheme with THINC limiter :cite:`shyue2014thinc`. ++-----------------------------+----------------+ +| Characteristic | Value | ++=============================+================+ +| dimension | 1 m | ++-----------------------------+----------------+ +| Mesh size | 800 | ++-----------------------------+----------------+ +| interface position | 0.3 m | ++-----------------------------+----------------+ +| boundary conditions | non-reflecting | ++-----------------------------+----------------+ +| final solution time | 0.7 ms | ++-----------------------------+----------------+ +| solution printing frequency | 0.025 ms | ++-----------------------------+----------------+ +| precision | 1st order | ++-----------------------------+----------------+ + +In the default test case, the computation is performed with a 1st order scheme. We compare this solution with those obtained using the 2nd order scheme with THINC limiter :cite:`shyue2014thinc`. .. _Fig:testCases:Kapila:advection1D: @@ -89,11 +89,11 @@ In the default case, the computation is performed with a 1st order scheme. We co :scale: 50% :align: center - Advection of a water/air interface. Visualization using Paraview_ software. + Advection of a water--air interface. Visualization using Paraview_ software. Shock tubes =========== -The test cases relative to Kapila model are those presented in :cite:`relaxjcp`. They are here reproduced using ECOGEN. +The test cases relative to Kapila's model are those presented in :cite:`relaxjcp`. They are here reproduced using ECOGEN. .. code-block:: xml @@ -102,7 +102,7 @@ The test cases relative to Kapila model are those presented in :cite:`relaxjcp`. interfaceWaterAir shock tube ---------------------------- -A shock tube between a high pressure chamber filled with water and a low pressire chamber filled with air is released. Input files for this test are available in ./libTests/referenceTestCases/kapila/1D/shockTubes/interfaceWaterAir/. +A shock tube between a high-pressure chamber filled with water and a low-pressure chamber filled with air is released. Input files for this test are available in *./libTests/referenceTestCases/kapila/1D/shockTubes/interfaceWaterAir/*. .. _Fig:testCases:Kapila:shockTubeWaterAirCI: @@ -110,12 +110,12 @@ A shock tube between a high pressure chamber filled with water and a low pressir :scale: 70% :align: center - Initial condition for 1D advection of water/air interface. + Initial condition for 1D water--air shock tube. The initial characteristics of the run are: +------------------------------+---------------------------+ -| Characteristic | value | +| Characteristic | Value | +==============================+===========================+ | dimension | 1 m | +------------------------------+---------------------------+ @@ -125,7 +125,7 @@ The initial characteristics of the run are: +------------------------------+---------------------------+ | diaphragm position | 0.7 m | +------------------------------+---------------------------+ -| boundary conditions | transmittive | +| boundary conditions | non-reflecting | +------------------------------+---------------------------+ | final solution time | 0.240 ms | +------------------------------+---------------------------+ @@ -134,7 +134,7 @@ The initial characteristics of the run are: | precision | 2nd order (Vanleer/THINC) | +------------------------------+---------------------------+ -AMR technique of :cite:`schmidmayer2019adaptive` is used with 4 refinement level such that a maximum of 230 computational cells are used for this run. +AMR technique of :cite:`schmidmayer2019adaptive` is used with 4 refinement levels such that a maximum of 230 computational cells are used for this run. .. _Fig:testCases:Kapila:shockTubeWaterAir: @@ -142,11 +142,11 @@ AMR technique of :cite:`schmidmayer2019adaptive` is used with 4 refinement level :scale: 50% :align: center - Shock tube with water and air. Visualization using Paraview_ software. + Water--air shock tube. Visualization using Paraview_ software. epoxySpinel ----------- -This test deals with shocks in mixture of materials. Epoxy and Spinel are supposed mixed such that caracteristic times for wave propagation and drag effects are very small allowing to consider the mixture as evolving in mechanical equilibrium. Input files for this test are available in ./libTests/referenceTestCases/kapila/1D/shockTubes/epoxySpinel/. +This test deals with shocks in mixture of materials. Epoxy and spinel are supposed mixed such that caracteristic times for wave propagation and drag effects are very small, allowing to consider the mixture as evolving in mechanical equilibrium. Input files for this test are available in *./libTests/referenceTestCases/kapila/1D/shockTubes/epoxySpinel/*. .. _Fig:testCases:Kapila:shockTubeEpoSpiCI: @@ -159,7 +159,7 @@ This test deals with shocks in mixture of materials. Epoxy and Spinel are suppos The initial characteristics of the run are: +------------------------------+---------------------+ -| Characteristic | value | +| Characteristic | Value | +==============================+=====================+ | dimension | 1 m | +------------------------------+---------------------+ @@ -169,7 +169,7 @@ The initial characteristics of the run are: +------------------------------+---------------------+ | diaphragm position | 0.6 m | +------------------------------+---------------------+ -| boundary conditions | transmittive | +| boundary conditions | non-reflecting | +------------------------------+---------------------+ | final solution time | 0.1 ms | +------------------------------+---------------------+ @@ -188,7 +188,7 @@ The initial characteristics of the run are: Other tests cases ================= -Other tests are provided with ECOGEN package. They will be described in details soon. +Other tests are provided with ECOGEN package. They will soon be described in details. .. code-block:: xml diff --git a/docs/sphinx_docs/source/Chap5_testCases_Chapter.rst b/docs/sphinx_docs/source/Chap5_testCases_Chapter.rst index 4c40eb3c..7163dc29 100644 --- a/docs/sphinx_docs/source/Chap5_testCases_Chapter.rst +++ b/docs/sphinx_docs/source/Chap5_testCases_Chapter.rst @@ -3,7 +3,7 @@ Test cases ========== -ECOGEN is provided including several test cases. Major part of these tests can be found in companion papers. The full list of available test cases in the package are listed in the conductor input file *ECOGEN.xml*. Description of some provided test cases is presented in this section. We will refer to the test case following the line format to uncomment in *ECOGEN.xml* input file. +ECOGEN is provided with several test cases. Major part of these tests can be found in companion papers. The complete list of available test cases in the package are listed in the main input file *ECOGEN.xml*. Description of few provided test cases is presented in this section. We will refer to the test case following the line format to uncomment in *ECOGEN.xml* input file. .. admonition:: Example @@ -13,7 +13,7 @@ ECOGEN is provided including several test cases. Major part of these tests can b ./libTests/referenceTestCases/euler/1D/transport/positiveVelocity/ - It is presented in details in the tutorial section :ref:`Sec:tuto:default` : + It is presented in details in the tutorial section :ref:`Sec:tuto:default`. .. toctree:: :maxdepth: 2 diff --git a/docs/sphinx_docs/source/Chap6_1buildingSphinxDoc.rst b/docs/sphinx_docs/source/Chap6_1buildingSphinxDoc.rst index 5453e96b..e44adb46 100644 --- a/docs/sphinx_docs/source/Chap6_1buildingSphinxDoc.rst +++ b/docs/sphinx_docs/source/Chap6_1buildingSphinxDoc.rst @@ -1,34 +1,34 @@ Building Sphinx Doc =================== -Prerequisities --------------- +Prerequisites +------------- This documentation uses Sphinx third-party Python package. To generate it locally from the **docs/sphinx_docs/** folder, you need to install additional components. Install Python ~~~~~~~~~~~~~~ To install python, you can install for example the `Anaconda package`_ or the `python offical package`_. -You can also install the packages directly from ubuntu terminal: +You can also install the packages directly from Ubuntu terminal: .. code-block:: console apt-get install python3 - apt-get install python-pip + apt-get install python3-pip Install Sphinx ~~~~~~~~~~~~~~ -From the prompt, it is possible to install sphinx, as well as additional libraries required for building this documentation using pip: +From the prompt, it is possible to install Sphinx, as well as additional libraries required for building this documentation using pip: .. code-block:: console - pip install sphinx - pip install sphinx_rtd_theme - pip install sphinx-numfig - pip install sphinxcontrib-bibtex + pip3 install sphinx + pip3 install sphinx_rtd_theme + pip3 install sphinx-numfig + pip3 install sphinxcontrib-bibtex -Install Latex -~~~~~~~~~~~~~ -If you want to build pdf, you will need Latex installed +Install *LaTeX* +~~~~~~~~~~~~~~~ +If you want to build PDF, you will need *LaTeX* installed: .. code-block:: console @@ -38,28 +38,28 @@ If you want to build pdf, you will need Latex installed Building html doc ----------------- -To build the docuentation as a webpage (as shown on ECOGEN_ webSite), move to the *docs* folder and run under prompt: +To build the documentation as a webpage (as shown on ECOGEN_ website), move to the *docs* folder and run under prompt: .. code-block:: console make html -Building pdf doc +Building PDF doc ---------------- -To build the docuentation as a PDF, move to the *docs* folder and run under prompt: +To build the documentation as a PDF, move to the *docs* folder and run under prompt: .. code-block:: console make latexpdf -This will generate a folder *docs/build/latex* containing source files in *LaTeX* that can be used to generate a pdf. +This will generate a folder *docs/build/latex* containing source files in *LaTeX* that can be used to generate a PDF. Learning Sphinx --------------- -To learn how to developp a documentation using sphinx, here are some usefull links: +To learn how to develop a documentation using Sphinx, here are some usefull links: -- `Sphinx documentation`_ -- Hosting documentation and read the docs theme : `Read the docs website`_ +- `Sphinx documentation`_, +- Hosting documentation and read the docs theme: `Read the docs website`_. .. _`Anaconda package`: https://www.anaconda.com/distribution/ diff --git a/docs/sphinx_docs/source/Chap6_2improvingECOGEN.rst b/docs/sphinx_docs/source/Chap6_2improvingECOGEN.rst index f3ee03c7..c3a93b8c 100644 --- a/docs/sphinx_docs/source/Chap6_2improvingECOGEN.rst +++ b/docs/sphinx_docs/source/Chap6_2improvingECOGEN.rst @@ -2,13 +2,13 @@ Contribute to ECOGEN ******************** -Before contributing, please read the section :ref:`Sec:Licence` informations. +Before contributing, please read the section :ref:`Sec:Licence` information. API documentation ================= -An API_ documentation is available. It is generated thanks to Doxygen_ and special comments in the source code. Interested developer will find informations on the different classes and functions used in ECOGEN. +An API_ documentation is available. It is generated thanks to Doxygen_ and special comments in the source code. Interested developers will find information on the different classes, methods and functions used in ECOGEN. -When contributing to the project and to automatise code documentation using Doxygen, comments should be insert as follow in header files. +When contributing to the project and to automatize the code documentation using Doxygen, comments should be inserted as follow in header files. At the head of files -------------------- @@ -17,7 +17,7 @@ At the head of files //! \file file name //! \author authors names - //! \version 1.0 + //! \version 1.1 //! \date 12 Novembre 2009 //! \brief brief description @@ -43,8 +43,8 @@ Before function and method prototypes //! \param parameter name description //! \return return description -Class member descrption ------------------------ +Class member description +------------------------ .. code-block:: c++ @@ -56,33 +56,33 @@ Coding constraints Developers are thanks to respect some constraints when contributing to the project. -Variable and Classe names -------------------------- +Variable and class names +------------------------ - 1. Variable name should began with lowercase letter and be self-understandable. Each new word began with a uppercase letter. + 1. Variable names should began with lowercase letter and be self-understandable. Each new word began with a uppercase letter. .. code-block:: c++ int myInteger; vector vectorOfDoublePointer; etc. - 2. Class attribute should began by "m\_". + 2. Class attributes should began by "m\_". .. code-block:: c++ int m_myInteger; double * m_doublePointer; etc. - 3. Class name should began with an uppercase Letter. + 3. Class names should began with an uppercase Letter. .. code-block:: c++ class MyClass; Developer personnal comments - flags -------------------------------------- +------------------------------------ Developer personnal comments should be included using the following template: -//Developer//KeyWord// comments +//DeveloperInitials//KeyWord// comments .. code-block:: c++ @@ -93,19 +93,21 @@ Here is the list of keyword to use : .. code-block:: c++ - //DEV// in developement + //DEV// in development //Q// question to dig //TODO// should be done in the future - //ERR// error : to correct ASAP + //ERR// error: To correct ASAP //ID// idea - //ICI// Stop developement position - //VERIF// to verify : is it needed ? - //TEST// test : To delete ASAP + //ICI// stop development position + //VERIF// to verify: Is it needed? + //TEST// test: To delete ASAP -Git-hub submit -============== +GitHub submit +============= For each modification, a comment should be prepared to be included to the commit message for Git. +Issues and contributions to ECOGEN project are possible directly on GitHub_ using pull requests. .. _API: https://code-mphi.github.io/ECOGEN/docs/doxygen_docs/index.html -.. _Doxygen: http://www.doxygen.nl/ \ No newline at end of file +.. _Doxygen: http://www.doxygen.nl/ +.. _`GitHub`: https://github.com/code-mphi/ECOGEN \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap6_developpersGuide_Chapter.rst b/docs/sphinx_docs/source/Chap6_developersGuide_Chapter.rst similarity index 60% rename from docs/sphinx_docs/source/Chap6_developpersGuide_Chapter.rst rename to docs/sphinx_docs/source/Chap6_developersGuide_Chapter.rst index e2a91a3b..d83d32bd 100644 --- a/docs/sphinx_docs/source/Chap6_developpersGuide_Chapter.rst +++ b/docs/sphinx_docs/source/Chap6_developersGuide_Chapter.rst @@ -1,9 +1,9 @@ Developers ========== -ECOGEN is open source, so interested developers are welcome to collaborate improving the software. This section includes various informations on how to easily and efficiently contribute to the project. +ECOGEN is open source, so interested developers are welcome to collaborate in order to improve the software. This section includes various information on how to easily and efficiently contribute to the project. -Access to the `API documentation`_ +Access to the `API documentation`_. .. toctree:: :maxdepth: 2 diff --git a/docs/sphinx_docs/source/Chap7_license.rst b/docs/sphinx_docs/source/Chap7_license.rst index 68722704..20e0eedd 100644 --- a/docs/sphinx_docs/source/Chap7_license.rst +++ b/docs/sphinx_docs/source/Chap7_license.rst @@ -3,13 +3,39 @@ License ======= -ECOGEN is the legal property of its developers, whose names are listed in the copyright file included with the source distribution. Contributors’ names for version 1.0 are listed below: +|License| -- Eric Daniel, -- Sébastien Le Martelot, -- Kevin Schmidmayer, -- Fabien Petitpas +ECOGEN is the legal property of its developers, whose names are listed in the copyright file included with the source distribution. Contributors’ names for version |version| are listed below: -ECOGEN is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + - Sébastien Le Martelot, + - Fabien Petitpas, + - Kevin Schmidmayer, + - Eric Daniel, + - Benedikt Dorschner, + - Joris Caze, + +ECOGEN is a free software: You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. ECOGEN is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details available at the following address: http://www.gnu.org/licenses. +Citations +--------- + +To cite ECOGEN, please use :cite:`schmidmayer2020ecogen` |DOI:ecogen| + +.. code-block:: none + + @article{schmidmayer2020ecogen, + doi = {10.1016/j.cpc.2019.107093}, + url = {https://doi.org/10.1016/j.cpc.2019.107093}, + title={ECOGEN: An open-source tool for multiphase, compressible, multiphysics flows}, + author={Schmidmayer, Kevin and Petitpas, Fabien and Le Martelot, S{\'e}bastien and Daniel, E}, + journal={Computer Physics Communications}, + volume={251}, + year={2020} + } + +.. |License| image:: https://img.shields.io/badge/License-GPLv3-blue.svg + :target: https://www.gnu.org/licenses/gpl-3.0 + +.. |DOI:ecogen| image:: https://img.shields.io/badge/DOI-10.1016/j.cpc.2019.107093-green.svg + :target: https://doi.org/10.1016/j.cpc.2019.107093 diff --git a/docs/sphinx_docs/source/Chap8_1Overview.rst b/docs/sphinx_docs/source/Chap8_1Overview.rst new file mode 100644 index 00000000..16826764 --- /dev/null +++ b/docs/sphinx_docs/source/Chap8_1Overview.rst @@ -0,0 +1,229 @@ +.. role:: xml(code) + :language: xml + +.. _Sec:GUI:overview: + +******** +Overview +******** + +Editing a test case requires deep understanding of input-file structure. To simplify this editing, a beta version of graphical user interface ECOGEN_GUI is proposed. + +Possible actions are: + + * Open, edit and save existing test cases. + * Create new test cases. + * Generate the main input file *ECOGEN.xml* to prepare runs. + * Edit essential settings for one or several test cases: Output format, flow model, fluid models, mesh dimensions (or mesh file choice), initial conditions and boundary conditions. + * Visualize equation-of-state parameter library (editing these parameters is possible directely through the interface). + +.. admonition:: Limitations + + Since this is a beta version of ECOGEN_GUI, only essential computation settings appear. Specific settings are thus not available but can be edited directly via the input files. Please refer to section :ref:`Chap:input` for details. + +************ +Installation +************ + +From self-extracting files +========================== + +ECOGEN_GUI can be installed automatically under Windows 10 (64 bits) from the precompiled binary installer *ECOGEN_GUI_Setup.exe*. + +To install the application, simply follow the installer's instructions (figure :numref:`Fig:GUI:install`). + +.. _Fig:GUI:install: + +.. figure:: ./_static/GUI/install.png + :scale: 70% + :align: center + + ECOGEN_GUI installation window under Windows 10. + +It is preferable to install ECOGEN_GUI in a user folder (by default) so that the application can save its configuration files. + +Source compilation +================== + +The source files of the ECOGEN_GUI application can also be compiled. The compilation nevertheless requires an environment able to compile C++ code using the `Qt`_ library. + +.. _`Qt`: https://www.qt.io/ + +******************** +General presentation +******************** + +First-time running +================== + +The first time you run ECOGEN_GUI, the configuration window appears (figure :numref:`Fig:GUI:config`.)). Afterwards, this window will be accessible via the menu bar of the main application window. + +.. _Fig:GUI:config: + +.. figure:: ./_static/GUI/config.png + :scale: 70% + :align: center + + Configuration window of the ECOGEN_GUI application. + +Before being able to use ECOGEN_GUI, it is necessary to specify the directory in which the ECOGEN code is located, in order to make the association between the application and the code input files. + +.. Caution:: + + The ECOGEN simulation tool must be installed independently. Please refer to the corresponding section :ref:`Chap:Start` for detailed instructions on ECOGEN installation. + +The other fields (*Mesh software*, *Text editor software*, etc.) can be filled in optionally. They will then allow the launching of these applications directly from the ECOGEN_GUI interface. + +Main window +=========== + +The main window of ECOGEN_GUI is presented, as visible at the launch of the application, on the figure :numref:`Fig:GUI:mainWindow`. + +.. _Fig:GUI:mainWindow: + +.. figure:: ./_static/GUI/mainWindow.png + :scale: 30% + :align: center + + ECOGEN_GUI application main window. + +It consists of several areas: + + 1. Menu bar, + 2. **Run controls** dock, + 3. **Models** dock, + 4. **Mesh properties** dock, + 5. **Boundary conditions** dock, + 6. **Physical domains** dock, + 7. **Equations of state** dock. + +Apart from the **Boundary conditions** dock, the other docks are greyed out when the application is launched and will only be activated when a test case is opened. To start editing a test case, choose *File* :math:`\rightarrow` *Open test case* (Ctrl+O) or *File* :math:`\rightarrow` *New test case* (Ctrl+N) from the menu bar (1). + +A first example +--------------- +As an example, open the reference test case located in *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity*. The application then loads the parameters from the ECOGEN input files corresponding to the requested test case (figure :numref:`Fig:GUI:casTestRef`). + +.. _Fig:GUI:casTestRef: + +.. figure:: ./_static/GUI/casTestRef.png + :scale: 30% + :align: center + + Opening the reference test case located in *./libTests/referenceTestCases/euler/1D/transport/positiveVelocity*. + +Loading the test case causes a new tab to appear in the central part of the window (8): + + * The tab title corresponds to the name of the test case being edited. It is also the name of the folder that will contain the results of the corresponding ECOGEN simulation (see section :ref:`Sec:input:main:runName` for more details). + * The white zone of the tab will record all the operations performed on this test case (log). + * If the test case parameters are modified, the tab title will be followed by a star which means that the modifications must be recorded to be applied to the ECOGEN code input files. To do this, select *File* :math:`\rightarrow` *Save test case* (Ctrl+S). + +Multiple test case downloads and preparation of ECOGEN +------------------------------------------------------ +It is possible to open multiple test cases simultaneously. In this case, as many tabs will be present in the central area (figure :numref:`Fig:GUI:zoomOnglets`). + +.. _Fig:GUI:zoomOnglets: + +.. figure:: ./_static/GUI/zoomOnglets.png + :scale: 70% + :align: center + + Here, 3 test cases are opened simultaneously. The test case being edited *kapila2DrichtmyerMeshkov* has been modified and not saved. + +Once the test cases have been loaded into ECOGEN_GUI and all saved, it is possible to generate the main input file of the ECOGEN code from the menu bar (*Run* :math:`\rightarrow` *Prepare* or Ctrl+E). The simulations are ready to run (refer to section :ref:`Sec:installation:compileAndExecute`). + +Reloading a test case +--------------------- +At any time, the input files can be reloaded again within the ECOGEN_GUI interface via the menu command (*View* :math:`\rightarrow` *Refresh* or Ctrl+R). This command is particularly useful to cancel unsaved modifications of the parameters of a test case or during a "manual" modification of the input files. + +******************* +Desription of docks +******************* + +The main window of ECOGEN_GUI consists of docks that can be arranged according to the user's preferences. These different docks gather the settings of a test case by "family". A help on each parameter can be obtained via the appearance of a tooltip on mouse over. + +Any change to a setting of a test case is accompanied by a line in the *log* field (central white area (8)) of the corresponding tab. This allows you to keep a history of the work performed on each test case. + +.. Caution:: + + Some parameters are not yet implemented within ECOGEN_GUI. The specific requirements for these parameters can nevertheless be edited manually within the input files. In this case, refer to section :ref:`Chap:UserGuide`. + +**Run Controls** dock +===================== +The dock **Run controls** (2) gathers all the computation settings initially contained in the input file *mainV5.xml* of the considered test case. +The details of the parameters are presented in section :ref:`Sec:input:main`. + +**Models** dock +=============== +The dock **Models** (3) gathers all the parameters of the mathematical flow model initially contained in the input file *modelV4.xml* of the considered test case. +The details of the parameters are presented in section :ref:`Sec:input:model`. This dock allows, among other things, to: + + * Change the model on the fly. + * Change the number of phases. + * Select for each phase an equation of state present in the ECOGEN directory. + +An interesting feature of ECOGEN_GUI is that any modification linked to the model will automatically be reported on the other docks (**Boundary conditions** and **Physical domains**) and consequently on the input files of the test case during saving. + +**Mesh properties** dock +======================== +The dock **Mesh properties** (4) gathers all the settings related to the mesh. These parameters are initially contained in the input file *meshV5.xml* of the considered test case. +The details of the parameters are presented in section :ref:`Sec:input:mesh`. + +The appearance of this dock depends on the type of mesh considered (Cartesian or unstructured). The two possible aspects of the dock **Mesh properties** are presented on figure :numref:`Fig:GUI:meshDock`. + +.. _Fig:GUI:meshDock: + +.. figure:: ./_static/GUI/meshDock.png + :scale: 70% + :align: center + + Two different aspects of the dock **Mesh properties**. Left: The standalone Cartesian mesh version is fully adaptable. Right: The unstructured version which requires to specify a mesh file from a third-party application. + +It is not possible to change the nature of the mesh on the fly. To change the mesh type, a new test case with the correct initial mesh structure must be created. + +Cartesian mesh +-------------- +When the mesh is Cartesian (figure :numref:`Fig:GUI:meshDock`, left), it is fully adaptable via ECOGEN_GUI (dimensions, number of computation cells, use of AMR for adaptative mesh refinement of discontinuities). + +Unstructured mesh +----------------- +When the mesh is unstructured (figure :numref:`Fig:GUI:meshDock`, right), the mesh must first be prepared using a third-party mesh application. The resulting mesh file must be specified here. Details on the mesh files accepted by ECOGEN are available in section :ref:`Sec:tuto:generatingMeshes`. + +.. Caution:: + + In case of modification of the mesh file, it may be necessary to edit the boundary conditions of the input file *initialConditionsV4.xml* manually, these boundary conditions being dependent on the mesh file. This will be recalled in the *log* area of the test case if needed. + +**Boundary conditions** dock +============================ +The dock **Boundary conditions** (5) gathers all the settings related to the boundary conditions. These parameters are initially contained in the input file *initialConditionsV4.xml* of the considered test case. +The details of the parameters are presented in section :ref:`Sec:input:boundaryConditions`. + +The dock will automatically adjust to the parameters of the other docks (**Mesh properties** and **Models**). +The different boundary conditions available are selectable within the dock list. Once the condition is selected within the list, its parameters can be modified. + +**Physical domains** dock +========================= +The dock **Physical domains** (6) gathers all the settings related to the physical domains to initialize (initial conditions of the computation). These parameters are initially contained in the input file *initialConditionsV4.xml* of the considered test case. +The details of the parameters are presented in section :ref:`Sec:input:physicalDomains`. + +In ECOGEN_GUI, the dock **Physical domains** will automatically adapt to the parameters present in the dock **Models**. + +The **Physical domains** dock is used to define different initialization regions for the thermo-mechanical variables of fluids within the computational domain. These regions operate by accumulation and can therefore overlap each other. It is then possible to create a base region initializing the whole domain and then add as many domains as desired using the :math:`+` button. +Once added, the geometric domains can be removed using the :math:`-` button or moved up or down (the domain at the top of the list being the first initialized, the following ones will be overlapped in order). + +**Equations of state** dock +=========================== +This dock is independent. It indexes all the files of thermodynamic parameters of the fluids available in the directory of ECOGEN. These parameters can be directly modified within the ECOGEN interface by checking the box within the dock (used as a lock). Information on the equations of state can be found in section :ref:`Sec:IO:materials`. + +********************************* +Modify ECOGEN_GUI's configuration +********************************* + +At any time, ECOGEN_GUI can be reconfigured via the menu bar *Edit* :math:`\rightarrow` *Configure*). In this case, the user has access to the configuration window again (:numref:`Fig:GUI:config`). + +ECOGEN's working directory +========================== +In this window, the path to ECOGEN's working directory must be correctly specified to ensure the operation of the ECOGEN_GUI interface. At the time of validation, if the chosen directory does not contain the main input file of the code *ECOGEN.xml*, an error message will appear and the user will again be prompted to modify the directory (see section :ref:`Sec:tuto:mainXML` for details on the main input file *ECOGEN.xml*). + +Links to external tools +======================= +It is an option you can use in ECOGEN_GUI. It is possible to specify the link to external application executables which can be frequently used during a simulation session via ECOGEN. Once these links are effective, it will be possible to call the corresponding applications via the menu (1) of the main window (*Tools*). \ No newline at end of file diff --git a/docs/sphinx_docs/source/Chap8_GUI.rst b/docs/sphinx_docs/source/Chap8_GUI.rst new file mode 100644 index 00000000..e0b69245 --- /dev/null +++ b/docs/sphinx_docs/source/Chap8_GUI.rst @@ -0,0 +1,14 @@ +.. _Chap:GUI: + +Graphical User Interface +======================== + +A beta version of Graphical User Interface (GUI) is available for editing ECOGEN's input files. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + Chap8_1Overview + + \ No newline at end of file diff --git a/docs/sphinx_docs/source/_static/GUI/casTestRef.png b/docs/sphinx_docs/source/_static/GUI/casTestRef.png new file mode 100644 index 00000000..45680aec Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/casTestRef.png differ diff --git a/docs/sphinx_docs/source/_static/GUI/config.png b/docs/sphinx_docs/source/_static/GUI/config.png new file mode 100644 index 00000000..8295b890 Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/config.png differ diff --git a/docs/sphinx_docs/source/_static/GUI/install.png b/docs/sphinx_docs/source/_static/GUI/install.png new file mode 100644 index 00000000..ad1e5ba8 Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/install.png differ diff --git a/docs/sphinx_docs/source/_static/GUI/mainWindow.png b/docs/sphinx_docs/source/_static/GUI/mainWindow.png new file mode 100644 index 00000000..6a061cea Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/mainWindow.png differ diff --git a/docs/sphinx_docs/source/_static/GUI/meshDock.png b/docs/sphinx_docs/source/_static/GUI/meshDock.png new file mode 100644 index 00000000..5ee8ed9b Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/meshDock.png differ diff --git a/docs/sphinx_docs/source/_static/GUI/zoomOnglets.png b/docs/sphinx_docs/source/_static/GUI/zoomOnglets.png new file mode 100644 index 00000000..81efd8d0 Binary files /dev/null and b/docs/sphinx_docs/source/_static/GUI/zoomOnglets.png differ diff --git a/docs/sphinx_docs/source/_static/IO/overview.png b/docs/sphinx_docs/source/_static/IO/overview.png index e1900c80..957f2622 100644 Binary files a/docs/sphinx_docs/source/_static/IO/overview.png and b/docs/sphinx_docs/source/_static/IO/overview.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/restartRun/compareRun.png b/docs/sphinx_docs/source/_static/tutos/restartRun/compareRun.png new file mode 100644 index 00000000..46f601e6 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/restartRun/compareRun.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/restartRun/restartRun.png b/docs/sphinx_docs/source/_static/tutos/restartRun/restartRun.png new file mode 100644 index 00000000..fb219222 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/restartRun/restartRun.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/restartRun/runInit.png b/docs/sphinx_docs/source/_static/tutos/restartRun/runInit.png new file mode 100644 index 00000000..9f0d7f50 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/restartRun/runInit.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/halfSpaceInit.png b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/halfSpaceInit.png new file mode 100644 index 00000000..700a16f5 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/halfSpaceInit.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/meshTube.png b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/meshTube.png new file mode 100644 index 00000000..a7f3fda0 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/meshTube.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcess.png b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcess.png new file mode 100644 index 00000000..ec4bb731 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcess.png differ diff --git a/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcessInit.png b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcessInit.png new file mode 100644 index 00000000..39832b78 Binary files /dev/null and b/docs/sphinx_docs/source/_static/tutos/splitPhysicalDomains/postProcessInit.png differ diff --git a/docs/sphinx_docs/source/conf.py b/docs/sphinx_docs/source/conf.py index ac62a8cf..fa8b8086 100644 --- a/docs/sphinx_docs/source/conf.py +++ b/docs/sphinx_docs/source/conf.py @@ -27,9 +27,9 @@ author = 'code-mphi' # The short X.Y version -version = '1.0' +version = '2.0' # The full version, including alpha/beta/rc tags -release = 'b1.0' +release = '2.0' # -- General configuration --------------------------------------------------- diff --git a/docs/sphinx_docs/source/index.rst b/docs/sphinx_docs/source/index.rst index 9e09622f..5fb15b3d 100644 --- a/docs/sphinx_docs/source/index.rst +++ b/docs/sphinx_docs/source/index.rst @@ -1,18 +1,18 @@ ECOGEN's documentation ====================== -Here is described the documentation of the ECOGEN_ open source plateform dedicated to numerical simulation of compressible multiphase flows. +Here is described the documentation of the ECOGEN_ open-source plateform dedicated to numerical simulation of compressible multiphase flows. -ECOGEN is an open source project distributed under under `GNU GPLv3 License`_ and available on `Git-Hub`_. +ECOGEN is an open-source project distributed under `GNU GPLv3 License`_ and available on `GitHub`_. -It is developped by code-mphi members in partenrship with AMU_, Caltech_ and CNES_. +It is developed by code-mphi members in partnership with AMU_, Caltech_ and CNES_. In this document, ECOGEN's user will find all necessary information to use the software. -Interested developpers are encouraged to contribute in the project and can use the API documentation generated by Doxygen_. +Interested developers are encouraged to contribute in the project using the "pull request" feature on `GitHub`_ and can use the API documentation generated by Doxygen_. -.. _`Git-Hub`: https://github.com/code-mphi/ECOGEN +.. _`GitHub`: https://github.com/code-mphi/ECOGEN .. _ECOGEN: https://code-mphi.github.io/ECOGEN/ .. _`GNU GPLv3 License`: http://www.gnu.org/licenses .. _AMU: https://www.univ-amu.fr/ @@ -29,8 +29,9 @@ Interested developpers are encouraged to contribute in the project and can use t Chap3_IO_Chapter Chap4_tutorials_Chapter Chap5_testCases_Chapter - Chap6_developpersGuide_Chapter + Chap6_developersGuide_Chapter Chap7_license + Chap8_GUI zBibliography diff --git a/docs/sphinx_docs/source/zBibliography.rst b/docs/sphinx_docs/source/zBibliography.rst index f138dae4..2a01ccbf 100644 --- a/docs/sphinx_docs/source/zBibliography.rst +++ b/docs/sphinx_docs/source/zBibliography.rst @@ -1,6 +1,6 @@ Bibliography ============ -A list of the references used in this documentation: +References used in this documentation: .. bibliography:: Biblio.bib \ No newline at end of file