Verified Commit e97c9b2b authored by Lars Bilke's avatar Lars Bilke
Browse files

[vale] web/content/docs/userguide.

parent 76470536
......@@ -42,7 +42,7 @@ Simply download an image from the [latest master-branch build](https://gitlab.op
singularity exec ogs-6.x.x-serial.sif ogs some/path/project.prj
```
This starts the container, mounts your home directory inside the container, passes the current working directory and runs the ogs executable (in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When ogs finishes the container stops and returns to the host system.
This starts the container, mounts your home directory inside the container, passes the current working directory and runs the `ogs` executable (in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When OGS finishes the container stops and returns to the host system.
You can also specify the full executable path in the container:
......@@ -124,7 +124,7 @@ Although Singularity is the preferred container runtime you can use [Docker](htt
* Get the container: `docker pull registry.opengeosys.org/ogs/ogs/ogs-serial`
* Start interactive container session: `docker run --rm -it registry.opengeosys.org/ogs/ogs/ogs-serial`
* Run ogs: `/usr/local/ogs/bin/ogs --version`
* Run `ogs`: `/usr/local/ogs/bin/ogs --version`
* Exit the container: `exit`
You will notice that the interactive session in your container is isolated from your host, i.e. you do not have access to files on your host. You need to explicitly [mount](https://docs.docker.com/storage/bind-mounts/) them on `docker run`:
......
......@@ -63,7 +63,7 @@ That applies to all of OpenGeoSys's processes; there are currently no processes
* [Dirichlet BC](https://doxygen.opengeosys.org/d5/d71/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__dirichlet): Boundaries held at a fixed displacement (Units: $\mathrm{L}$, SI: $\mathrm{m}$).
* [Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to apply an external traction at a boundary (Units: $\mathrm{M \cdot L^{-1} \cdot T^{-2}}$, SI: $\mathrm{N} \cdot \mathrm{m}^{-2}$).
* [Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): A body force density acting in the model domain. One example is gravity, but gravitiy can be modeled by other means in OpenGeoSys (Units: $\mathrm{M \cdot L^{-2} \cdot T^{-2}}$, SI: $\mathrm{N} \cdot \mathrm{m}^{-3}$).
* [Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): A body force density acting in the model domain. One example is gravity, but gravity can be modeled by other means in OpenGeoSys (Units: $\mathrm{M \cdot L^{-2} \cdot T^{-2}}$, SI: $\mathrm{N} \cdot \mathrm{m}^{-3}$).
**Pressure:**
......
......@@ -26,20 +26,20 @@ Image `registry.opengeosys.org/ogs/ogs/ogs-serial-jupyter` contains:
- [VTUInterface](https://github.com/joergbuchwald/VTUinterface) — VTU / PVD IO
- [h5py](https://docs.h5py.org/en/latest/index.html) — HDF5 IO
- [MFront python bindings](http://tfel.sourceforge.net/mfront-python.html) – Material model manipulation
- [matplotlib](https://matplotlib.org) — Plotting
- [numpy](https://numpy.org) — Scientific computing
- [Matplotlib](https://matplotlib.org) — Plotting
- [NumPy](https://numpy.org) — Scientific computing
- [pandas](https://pandas.pydata.org) — Data analysis
- [scipy](https://docs.scipy.org/doc/scipy/reference/) — Scientific computing
- [vtk](https://pypi.org/project/vtk/) — Visualization
- [SciPy](https://docs.scipy.org/doc/scipy/reference/) — Scientific computing
- [VTK](https://pypi.org/project/vtk/) — Visualization
- [PyVista][pyvista] — Visualization
- [Snakemake](https://snakemake.github.io) — Workflow management
- [msh2vtu](https://github.com/dominik-kern/msh2vtu)gmsh to VTU conversion, (script in `/opt/conda/lib/python3.9/site-packages/msh2vtu/msh2vtu.py`)
- [msh2vtu](https://github.com/dominik-kern/msh2vtu)Gmsh to VTU conversion, (script in `/opt/conda/lib/python3.9/site-packages/msh2vtu/msh2vtu.py`)
- [meshio](https://github.com/nschloe/meshio) — Mesh conversions between many formats. Pulled in via msh2vtu.
- Jupyter-related tools:
- [nbconvert](https://nbconvert.readthedocs.io) — Format conversion
- [nbdime](https://nbdime.readthedocs.io) — Diffs for notebooks
- [nb2hugo](https://github.com/bilke/nb2hugo/tree/ogs) — Notebook to www.opengeosys.org markdown
- [gmsh](https://gmsh.info) — Mesh generator (incl. Python bindings)
- [nb2hugo](https://github.com/bilke/nb2hugo/tree/ogs) — Notebook to website markdown conversion
- [Gmsh](https://gmsh.info) — Mesh generator (incl. Python bindings)
Image `registry.opengeosys.org/ogs/ogs/ogs-petsc-jupyter` additionally contains:
......@@ -106,7 +106,7 @@ Available images are [listed on GitLab](https://gitlab.opengeosys.org/ogs/ogs/co
### Browsing notebooks on GitLab
In the file browser on the left-hand side of the Jupyter Lab interface there is a GitLab-tab which allows for browsing and opening notebooks from the [ogs/ogs](https://gitlab.opengeosys.org/ogs/ogs)-repository. You can directly modify and execute a notebook, but the notebook is not saved back to GitLab. You can change the browsed repository by typing into the top text field.
In the file browser on the left-hand side of the Jupyter Lab interface there is a GitLab-tab which allows for browsing and opening notebooks from the [`ogs/ogs`](https://gitlab.opengeosys.org/ogs/ogs)-repository. You can directly modify and execute a notebook, but the notebook is not saved back to GitLab. You can change the browsed repository by typing into the top text field.
If you would like to us this with private repositories you have to supply an [access token](https://gitlab.opengeosys.org/-/profile/personal_access_tokens) at container start-up:
......
......@@ -178,7 +178,8 @@ sudo apt-get install libxml2-utils
</div>
<div class='mac'>
`xmllint` is part of the Homebrew xmlstarlet package:
`xmllint` is part of the Homebrew `xmlstarlet` package:
```bash
brew install xmlstarlet
......
......@@ -49,14 +49,14 @@ The columns contain the following data:
| 3-sided prism | 1 | 0 | **1** | 6 | 1 | **3** | 21 | 2 | *3* | 28 | 2 | *5* |
| Pyramid | 1 | 1 | **1** | 5 | 1 | **3** | 13 | 3 | *3* | 13 | 3 | *3* |
Note, that on pyramids det(*J*) varies over the mesh element, even for linear
Note, that on pyramids det($J$) varies over the mesh element, even for linear
elements. Therefore, for pyramids we are actually integrating a polynomial of
higher degree than the degrees P and Q given in the table above.
## Extrapolation of integration point data to mesh nodes
OpenGeoSys can extrapolate integration point data to mesh nodes for easy
postprocessing. **Note, however, that the extrapolation procedures is not exact
post-processing. **Note, however, that the extrapolation procedures is not exact
and can lead to more or less subtle errors that are hard to find!**
Since OpenGeoSys extrapolates integration point data element-wise, the number of
......
......@@ -9,9 +9,11 @@ weight = 2
parent = "basics"
+++
<!-- vale off -->
The executable OGS for MPI parallel computing is compiled with special
build configuration. If you need to compile the source code, please read
[Build configuration for MPI and PETSc]({{<ref "configure_for_mpi_and_petsc.md">}}).
[Build configuration for MPI and PETSc]({{<ref "configure_for_mpi_and_petsc.md">}}
<!-- vale on -->
To conduct DDC enabled parallel computing with OGS, following steps are required:
......@@ -27,11 +29,11 @@ For the domain decomposition approach, an application of OGS using METIS as a no
command line options.
The partitioned meshes are written in binary files for a fast parallel reading
in ogs.
in OGS.
#### 1.2 Configure PETSc solver in project file
Setting PETSc solver is the only change in project file for running parallel ogs with PETSc.
Setting PETSc solver is the only change in project file for running parallel OGS with PETSc.
For linear solver, it is done by adding a tag of `petsc` inside `linear_solver` tag,
e.g:
......@@ -94,16 +96,16 @@ The above example shows that once a prefix is given for PETSc linear solver
keyword, `-`, can be replaced with a new prefix, `-[given prefix string]_`. In the
above example, `-`, is replaced with `-T_` and `-H_`, respectively.
A introduction and a list of of PETSc ksp solvers and preconditioners can be found by
A introduction and a list of PETSc KSP solvers and preconditioners can be found by
[this link](https://petsc.org/main/docs/manual/ksp/).
### 2. Launch MPI OGS
For MPI launcher, either *mpiexec* or *mpirun* can be used to run OGS.
Preferably, *mpiexec* is recommended because it is defined in the MPI standard.
The number of processes to run of *mpiexec* must be identical to the number of
For MPI launcher, either `mpiexec` or `mpirun` can be used to run OGS.
Preferably, `mpiexec` is recommended because it is defined in the MPI standard.
The number of processes to run of `mpiexec` must be identical to the number of
mesh partitions.
For example, if the meshes of a project, foo.prj, are partitioned into 5 partitions,
For example, if the meshes of a project, `foo.prj`, are partitioned into 5 partitions,
OGS can be launched in MPI as
```bash
......@@ -111,24 +113,24 @@ mpiexec -n 5 ogs foo.prj -o [path to the output directory]
```
Running PETSc enabled OGS with one compute thread does not need mesh partitioning.
However, the MPI launcher mpiexc or mpirun is required, e.g.:
However, the MPI launcher `mpiexc` or `mpirun` is required, e.g.:
```bash
mpiexec -n 1 ogs ...
```
Additional PETSc command line options can be given as unlabelled arguments at the end of the ogs run command preceded by two minus-signs
Additional PETSc command line options can be given as unlabelled arguments at the end of the OGS run command preceded by two minus-signs
(`... ogs ... -- [PETSc options]`).
With PETSc command line options, you can
* monitor ksp solver convergence status, e.g.
* monitor KSP solver convergence status, e.g.
```bash
mpiexec -n 5 ogs foo.prj -o output -- -ksp_converged_reason -ksp_monitor_true_residual
```
* change ksp solver setting, e.g.:
* change KSP solver setting, e.g.:
```bash
mpiexec -n 5 ogs foo.prj -o output -- -ksp_type gmres -ksp_rtol 1e-16 -ksp_max_it 2000
......@@ -174,13 +176,13 @@ srun -n "$SLURM_NTASKS" $APP /home/wwang/data_D/project/AREHS/HM_3D/simHM_glaci
```
In the job script for EVE, `module load foss/2020b` must be presented, and
srun is a sort of MPI job launcher.
`srun` is a sort of MPI job launcher.
If a job fails with an error message about shared library not found, you can check
the EVE modules specified in the files in source code directory:
*scripts/env/eve*, and add the corresponding modules to the load list
in the job script.
Once the the job script is ready, you can
Once the job script is ready, you can
* submit the job by command, `sbatch [job script name]`,
* check the job status by command `squeue`,
......@@ -213,20 +215,20 @@ or
#### 3.1 VTK output
The results are output in the partitioned vtu files, which are governed by
a pvtu file. The data in the ghost cells of vtu files are overlapped.
An OGS utility, *RemoveGhostData*, is available to merge the partition vtu files into one vtu file,
The results are output in the partitioned VTU files, which are governed by
a PVTU file. The data in the ghost cells of VTU files are overlapped.
An OGS utility, *RemoveGhostData*, is available to merge the partition VTU files into one VTU file,
meanwhile to eliminate the data overlapping. Here is an example to use that utility:
```bash
RemoveGhostData -i foo.pvtu -o foo.vtu
```
Where the input file name is the name of pvtu file.
Where the input file name is the name of PVTU file.
#### 3.2 XMDF output
With XMDF, ogs gives two files, one XMDF file and one HDF5 file with file name
With XMDF, OGS outputs two files, one XMDF file and one HDF5 file with file name
extension of `h5`. You can use ParaView to open the XDMF file by selecting
`Xdmf3ReaderS` or `Xdmf3ReaderT`. The XMDF output is highly recommended for
running OGS with a large mesh, especially on supercomputers.
......@@ -35,7 +35,7 @@ The port tunneling with ssh is required as these ports are blocked from the fire
## `envinf1`
`envinf1` has a NVidia K20m. Simila instructions as for eve but port tunneling is not necessary:
`envinf1` has a NVidia K20m. Similar instructions as for eve but port tunneling is not necessary:
```bash
ssh 141.65.34.100
......
......@@ -11,12 +11,12 @@ weight = 41
## Description of process Heat_Transport_BHE
Borehole heat exchangers (BHE) are widely applied in Ground Source Heat Pump (GSHP) systems to explore geothermal energy for building heating and cooling purposes. There are more and more engineerings starting to use simulation tools for the performance evaluation and design of GSHP projects.\
Borehole heat exchangers (BHE) are widely applied in Ground Source Heat Pump (GSHP) systems to explore geothermal energy for building heating and cooling purposes. There are more and more engineering companies starting to use simulation tools for the performance evaluation and design of GSHP projects.\
For OGS-6, it allows the users to simulate the subsurface and soil temperature evolution induced by BHE and operation performance of BHE coupled heat pump.
## Mathematical framework
This part aims to give an explanation of the mathematical framework in configuring the Heat_Transport_BHE process provided in OpenGeoSys. The numerical method implemented in OGS-6 is the so-called double-continuum finite element method (`DC-FEM`). This approach was originally proposed by Al-Khoury et al. (2010) and extendend by Diersch et al. (2011a; 2011b). It was then implemented in OpenGeoSys by Shao et al. (2016). This modelling appraoch has the following assumptions.
This part aims to give an explanation of the mathematical framework in configuring the Heat_Transport_BHE process provided in OpenGeoSys. The numerical method implemented in OGS-6 is the so-called double-continuum finite element method (`DC-FEM`). This approach was originally proposed by Al-Khoury et al. (2010) and extended by Diersch et al. (2011a; 2011b). It was then implemented in OpenGeoSys by Shao et al. (2016). This modelling approach has the following assumptions.
* The subsurface is considered to be a 3D continuum, while the BHE is represented by 1D line elements as the second continuum.
* The heat transfer between different BHE components is simulated by the Capacity-Resistance-Model (CaRM) in analogy to the electrical circuits.
......@@ -27,7 +27,7 @@ $$\begin{equation}\frac{\partial}{\partial t} \left[ \epsilon \rho_f c_f + ( 1-
Here, $\Lambda_s$ denotes the tensor of thermal hydrodynamic dispersion and $H_s$ represents the heat source and sink term.
* In the borehole continuum, each pipe is assigned with one governing equation, with the thermal convection in the pipeline simulated. Also, for each grout zone surrounding the pipeline, the thermal conduction equation was simulated. For details of the coupling between different borehole components and continuums, interested readers may refer to Diersch et al. (2011a; 2011b).
* In the borehole continuum, each pipe is assigned with one governing equation, with the thermal convection in the pipeline simulated. Also, for each grout zone surrounding the pipeline, the thermal conduction equation was simulated. For details of the coupling between different borehole components and continua, interested readers may refer to Diersch et al. (2011a; 2011b).
## Input parameters
......@@ -171,7 +171,7 @@ The thermal properties of the circulating fluid is defined here. The parameters
* /viscosity/: dynamic viscosity of circulating media which has the unit of $\mathrm{kg·m^{-1} s^{-1}}$;
* /specific_heat_capacity/: specific heat capacity of circulating fluid, which has the unit of $\mathrm{J·kg^{-1} K^{-1}}$;
* /thermal_conductivity/: thermal conductivity of the circulating fluid, which has the unit of $\mathrm{W·m^{-1} K^{-1}}$;
* /reference_temperature/: When the < flow_and_temperature_control > was not set to TemperatureCurveConstantFlow, OGS needs to have an initial outlet temperature value in the first time step to start the simulation. A reference temperature has to be defined for the calculation of initial inflow temperature. The unit of refenrence temperature is in $^{\circ}$C.
* /reference_temperature/: When the < flow_and_temperature_control > was not set to TemperatureCurveConstantFlow, OGS needs to have an initial outlet temperature value in the first time step to start the simulation. A reference temperature has to be defined for the calculation of initial inflow temperature. The unit of reference temperature is in $^{\circ}$C.
Here is an example in which the circulating fluid is water at about 15 $^{\circ}$C.
......@@ -187,6 +187,8 @@ Here is an example in which the circulating fluid is water at about 15 $^{\circ}
## References
<!-- vale off -->
[1] Al-Khoury, R., Kölbel, T., Schramedei, R.: Efficient numerical modeling of borehole heat exchangers. Comput. Geosci. 36(10), 1301–1315 (2010).
[2] Diersch, H.-J.G., Bauer, D., Heidemann, W., Rühaak, W., Schätzl, P.: Finite element modeling of borehole heat exchanger systems: part 1. Fundamentals. Comput. Geosci. 37(8), 1122–1135 (2011a).
......
......@@ -31,7 +31,7 @@ pip3 install tespy
## Creating a pipeline network model with the software TESPy
Thermal Engineering Systems in Python (software paper: <https://doi.org/10.21105/joss.02178>, software archive: <https://doi.org/10.5281/zenodo.2555866>) is a software package developed by Francesco Witte. It is capable of simulating coupled thermal-hydraulic status of working fluids in thermal engineering applications. Such system typically involves a cirulation network that is composed of pre-defined components including pipes, heat exchangers and different types of turbo machinery. Interested readers may refer to the online documentation (<https://tespy.readthedocs.io/en/master/index.html>) of TESPy for more detailed introduction of the software. The workflow in this part is built based on the benchmark example "A 3-BHE Array Coupled With Pipe Network" from the OpenGeoSys Documentation (<https://www.opengeosys.org/docs/benchmarks/heat-transport-bhe/3d_3bhes_array/>). One can refer to this benchmark and download its latest benchmark files from GitHub (<https://www.opengeosys.org/docs/userguide/basics/introduction/>) for creating the pipeline network TESPy model. The OpenGeoSys and TESPy version used for this tutorial is (OpenGeoSys 6.2.2) and 0.3.3 accordingly.
Thermal Engineering Systems in Python (software paper: <https://doi.org/10.21105/joss.02178>, software archive: <https://doi.org/10.5281/zenodo.2555866>) is a software package developed by Francesco Witte. It is capable of simulating coupled thermal-hydraulic status of working fluids in thermal engineering applications. Such system typically involves a circulation network that is composed of pre-defined components including pipes, heat exchangers and different types of turbo machinery. Interested readers may refer to the online documentation (<https://tespy.readthedocs.io/en/master/index.html>) of TESPy for more detailed introduction of the software. The workflow in this part is built based on the benchmark example "A 3-BHE Array Coupled With Pipe Network" from the OpenGeoSys Documentation (<https://www.opengeosys.org/docs/benchmarks/heat-transport-bhe/3d_3bhes_array/>). One can refer to this benchmark and download its latest benchmark files from GitHub (<https://www.opengeosys.org/docs/userguide/basics/introduction/>) for creating the pipeline network TESPy model. The OpenGeoSys and TESPy version used for this tutorial is (OpenGeoSys 6.2.2) and 0.3.3 accordingly.
The coupled model that is going to be built is demonstrated in Figure 1. It consists of a pipeline network connected with 3 BHEs, a water pump, a virtual heat pump as the consumer, a splitter to split up the feeding fluid flow and a merge to returned flow. These devices are all defined as `components` in TESPy. A full list of available components can be found in the TESPy components module. In the pipeline network, these components are connected with each other through `connections` parts, which are illustrated by the black lines in the figure. With these two main parts, a completely TESPy pipeline network model can be set up.
......@@ -181,7 +181,7 @@ Figure 2: Work flow of the model with BHEs coupled with a pipe network
### < BHE data container >
In order to use the PipeNetwork feature, the pre-built and saved TESPy network model in the above section is required. A csv file `bhe_network.csv` which containing all the OGS-TESPy transferred BHE's information needs to be created. The PipeNetwork feature will access this csv file to initialize the exchange data container between OGS and TESPy during the simulation. All BHEs have to be included in this csv file. Please take notice that all BHE names located in the data_index column have to be identical with the BHE names defined in the corresponding TESPy network model.
In order to use the PipeNetwork feature, the pre-built and saved TESPy network model in the above section is required. A CSV file `bhe_network.csv` which containing all the OGS-TESPy transferred BHE's information needs to be created. The PipeNetwork feature will access this CSV file to initialize the exchange data container between OGS and TESPy during the simulation. All BHEs have to be included in this CSV file. Please take notice that all BHE names located in the data_index column have to be identical with the BHE names defined in the corresponding TESPy network model.
```bash
data_index;BHE_id;Tin_val;Tout_val;Tout_node_id;flowrate
......@@ -281,6 +281,8 @@ After the configuration of the OGS project file, all the required files for usin
## References
<!-- vale off -->
[1] Francesco Witte, Ilja Tuschy, TESPy: Thermal Engineering Systems in Python, 2019. URL: <https://doi.org/10.21105/joss.02178>. doi:10.21105/joss.02178.
[2] Haibing Shao, Philipp Hein, Agnes Sachse, and Olaf Kolditz. Geoenergy modeling II: shallow geothermal systems. Springer International Publishing, 2016.
......
......@@ -11,7 +11,7 @@ weight = 43
+++
This documentation gives an overview of the multiphase flow processes (except `TH2M`) in OGS6. Currently all processes assume two-phase flow (The `Richards Flow` process is not considered as a "two-phase flow" process since the gas phase is assumed static). A comparison of the process-specific features is listed in the following table.
This documentation gives an overview of the multiphase flow processes (except `TH2M`) in OGS. Currently all processes assume two-phase flow (The `Richards Flow` process is not considered as a "two-phase flow" process since the gas phase is assumed static). A comparison of the process-specific features is listed in the following table.
| Feature | `TwoPhaseFlowWithPP` | `TwoPhaseFlowWithPrho` | `ThermalTwoPhaseFlowWithPP` |
|---|---|---|---|
......
......@@ -37,7 +37,9 @@ where `XXX` can be `CND`, `GLI`, `PRJ` or `STN` depending on the file type.
Now the save the modified file and try to load it again.
<!-- vale off -->
<details>
<summary>Background info:</summary>
The XSD files may be downloaded from a web location. We changed the protocol of our web site to `https://` but due to some weird behaviour of the Qt XML validation code it tries to download the file (even if it is available locally) and does not respect the URL redirection to `https://` of the web server. Simply removing the part solves the problem. The XML is still validated! Newer OGS versions do not write that parameter into files anymore, see https://github.com/ufz/ogs/pull/2198.
The XSD files may be downloaded from a web location. We changed the protocol of our web site to `https://` but due to some weird behaviour of the Qt XML validation code it tries to download the file (even if it is available locally) and does not respect the URL redirection to `https://` of the web server. Simply removing the part solves the problem. The XML is still validated! Newer OGS versions do not write that parameter into files anymore, see <https://github.com/ufz/ogs/pull/2198>.
</details>
......@@ -20,7 +20,7 @@ If you encounter issues using or developing OGS let us know. To help you in the
- Steps to reproduce the issue
- **Full log output** as plain text (-file) (e.g. full compiler output including CMake run or output of a simulation run of OGS)! Please **do not** send screenshots of error messages! Instead copy and paste from your terminal application into the report!
- Information about your environment (e.g. did you used Conan for third-party dependencies or did you installed them by yourself, which library versions)
- Information about the OGS configuration (e.g. debug or release, serial or parallel, mfront?, ...)
- Information about the OGS configuration (e.g. debug or release, serial or parallel, MFront?, ...)
Feel free to skip things from the list if you think they are not related to the issue but in general: the more information the better.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment