@@ -17,11 +17,11 @@ To set up a model domain, the project file `*.prj` requires additional files for
The bulk mesh must be provided in VTK's `*.vtu` format, whereas the boundary and source term domains can be provided either in OGS' internal geometry file format (filename extension: `*.gml`, not to be confused with the Geography Markup Language) or as a `*.vtu` file as well, containing a subdomain of the bulk mesh. Multiple `*.vtu` files can be provided in the project file using the `<meshes>` tag. We recommend the usage of the first method for simple 2D meshes with constant boundary conditions, whereas more complicated geometries and conditions might require the latter method. One general advantage in the utilization of `*.vtu` files is that they allow a definition of additional field variables at each mesh node/element in order to implement spatially varying boundary conditions in a similar manner as, e.g., defining inhomogeneous material properties in the bulk mesh.
The finite-element mesh must be created using external mesh generators. Simple meshes can be created using the [generateStructuredMesh]({{<ref"structured-mesh-generation">}}) tool. More complicated geometries can be generated and meshed using, e.g., [SALOME Platform](https://www.salome-platform.org) or [GMSH](http://gmsh.info).
The finite-element mesh must be created using external mesh generators. Simple meshes can be created using the OGS utility [generateStructuredMesh]({{<ref"structured-mesh-generation">}}) or [PyVista](https://docs.pyvista.org). More complicated geometries can be generated and meshed using, e.g., [SALOME Platform](https://www.salome-platform.org) or [GMSH](http://gmsh.info).
To use a mesh created by SALOME it must be converted to the GMSH file format first. To exchange mesh files between SALOME and GMSH one can use the `*.unv` file format. Finally, the tool GMSH2OGS can be used for the creation of `*.vtu` files (Attention: GMSH2OGS currently accepts the GMSH v2. ASCII format only. It might be also necessary to use the `-e` option to exclude lines before using the mesh files in OGS).
To use a mesh created by SALOME, it must be converted to the GMSH file format first. To exchange mesh files between SALOME and GMSH, one can use the `*.unv` file format. Finally, the tool GMSH2OGS can be used for the creation of `*.vtu` files (Attention: GMSH2OGS currently accepts the GMSH v2. ASCII format only. It might also be necessary to use the `-e` option to exclude lines before using the mesh files in OGS).
To extract a surface mesh (in order to define appropriate boundary conditions) one can use the tool [ExtractSurface]({{<ref"extract-surface">}}) for different kinds of 3D meshes. Different tools like [ParaView](https://www.paraview.org/) are suited as well. Care must be taken to make sure that all element types are of dimension `d-1`, where `d` is the dimension of the bulk mesh. Furthermore, one needs to ensure that no degenerated elements are left in the mesh and all nodes are connected appropriately.
To extract a surface mesh (in order to define appropriate boundary conditions) one can use the tool [ExtractSurface]({{<ref"extract-surface">}}) for different kinds of 3D meshes. Different tools like [ParaView](https://www.paraview.org/) are suited as well. Care must be taken to make sure that all element types are of dimension `d-1`, where `d` is the dimension of the bulk mesh, and that no degenerated elements are left in the mesh and all nodes are connected appropriately. Furthermore, ensure that the element orders match. In the current version ExtractSurface stores meshes of first order (linear elements), even when the input mesh was of second order (quadratic elements).
Alternatively, the tool [msh2vtu](https://github.com/dominik-kern/msh2vtu) can be used to convert GMSH meshes to VTU and to extract boundary meshes directly from physical groups defined in GMSH.
In general OpenGeoSys is not using any intrinsic units, i.e. all equations are [non-dimensionalized](https://en.wikipedia.org/wiki/Nondimensionalization).
However, there are some exceptions to the rule as for instance some empirical laws
like some expressions for the vapor diffusion and latent heat that assume the temperature to be given in Kelvin.
In general OpenGeoSys is not using any intrinsic units, i.e. OGS assumes that a self-consistent set of units (SI for example) is used for all quantities.
However, there are some exceptions to the rule as for instance some empirical laws like some expressions for the vapor diffusion and latent heat that assume the temperature to be given in Kelvin.
Therefore, we recommend using SI base units.
### Dimensional analysis of source and boundary terms based on their primary variables
__Units:__
| Quantity name | Dimension symbol |
| ------------- | ----------------- |
| time | $\mathrm{T}$ |
| length | $\mathrm{L}$ |
| mass | $\mathrm{M}$ |
| temperature | $\mathrm{\Theta}$ |
| Quantity name | Dimension symbol | SI base units |
| temperature | $\mathrm{\Theta}$ | $\mathrm{K}$ |
__Temperature:__
*[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 temperature (Units: $\mathrm{\Theta}$).
*[Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to impose a heat flux through a boundary domain (Units: $\mathrm{M \cdot L^{3-d} \cdot T^{-3}}$).
*[Nodal ST](https://doxygen.opengeosys.org/d0/d2c/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__nodal): Representing a heat source in the model domain (Units: $\mathrm{M \cdot L^{2} \cdot T^{-3}}$).
*[Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): Representing a volumetric heat source in the model domain (Units: $\mathrm{M \cdot L^{2-d} \cdot T^{-3}}$).
*[Line ST](https://doxygen.opengeosys.org/d9/d4a/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__line): Representing a heat source on a line shaped subdomain (Units: $\mathrm{M \cdot L^{2-1} \cdot T^{-3}}$).
*[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 temperature (Units: $\mathrm{\Theta}$, SI: $\mathrm{K}$).
*[Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to impose a heat flux through a boundary domain (Units: $\mathrm{M \cdot L^{3-d} \cdot T^{-3}}$, SI: $\mathrm{W}\cdot \mathrm{m}^{d-1}$).
*[Nodal ST](https://doxygen.opengeosys.org/d0/d2c/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__nodal): Representing a heat source in the model domain (Units: $\mathrm{M \cdot L^{2} \cdot T^{-3}}$, SI: $\mathrm{W}$).
*[Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): Representing a volumetric heat source in the model domain (Units: $\mathrm{M \cdot L^{2-d} \cdot T^{-3}}$, SI: $\mathrm{W} \cdot \mathrm{m}^{-d}$).
*[Line ST](https://doxygen.opengeosys.org/d9/d4a/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__line): Representing a heat source on a line shaped subdomain (Units: $\mathrm{M \cdot L^{1} \cdot T^{-3}}$, SI: $\mathrm{W} \cdot \mathrm{m}^{-1}$).
__Displacement__
*[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}$).
*[Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to apply external loads at a boundary (Units: $\mathrm{M \cdot L^{2-d} \cdot T^{-2}}$).
*[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^{2-d} \cdot T^{-2}}$, SI: $\mathrm{N} \cdot \mathrm{m}^{d-1}$).
__Pressure__
*[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 pressure (Units: $\mathrm{M \cdot L^{-1} \cdot T^{-2}}$).
*[Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to impose a mass flux through a boundary domain (Units: $\mathrm{M \cdot L^{1-d} \cdot T^{-1}}$).
*[Nodal ST](https://doxygen.opengeosys.org/d0/d2c/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__nodal): Representing a mass production rate in the model domain (Units: $\mathrm{M \cdot T^{-1}}$).
*[Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): Representing a volumetric mass source in the model domain (Units: $\mathrm{ M \cdot L^{-d} \cdot T^{-1}}$).
*[Line ST](https://doxygen.opengeosys.org/d9/d4a/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__line): Representing a mass source on a line shaped subdomain (Units: $\mathrm{ M \cdot L^{-1} \cdot T^{-1}}$).
*[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 pressure (Units: $\mathrm{M \cdot L^{-1} \cdot T^{-2}}$, SI: $\mathrm{Pa}$).
*[Neumann BC](https://doxygen.opengeosys.org/d1/d2e/ogs_file_param__prj__process_variables__process_variable__boundary_conditions__boundary_condition__neumann): Used to impose a mass flux through a boundary domain (Units: $\mathrm{M \cdot L^{1-d} \cdot T^{-1}}$, SI: $\mathrm{kg} \cdot \mathrm{m}^{1-d} \cdot \mathrm{s}^{-1}$).
*[Nodal ST](https://doxygen.opengeosys.org/d0/d2c/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__nodal): Representing a mass production rate in the model domain (Units: $\mathrm{M \cdot T^{-1}}$, SI: $\mathrm{kg} \cdot \mathrm{s}^{-1}$).
*[Volumetric ST](https://doxygen.opengeosys.org/d0/d89/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__volumetric): Representing a volumetric mass source in the model domain (Units: $\mathrm{ M \cdot L^{-d} \cdot T^{-1}}$, SI: $\mathrm{kg} \cdot \mathrm{m}^{-d} \cdot \mathrm{s}^{-1}$).
*[Line ST](https://doxygen.opengeosys.org/d9/d4a/ogs_file_param__prj__process_variables__process_variable__source_terms__source_term__line): Representing a mass source on a line shaped subdomain (Units: $\mathrm{ M \cdot L^{-1} \cdot T^{-1}}$, SI: $\mathrm{kg} \cdot \mathrm{m}^{-1} \cdot \mathrm{s}^{-1}$).
## Stress sign
OpenGeoSys uses the positive sign convention for tensile stresses, whereas compressional stresses carry a negative sign.
## Stress-strain assumption for 2D simulations
OpenGeoSys assumes plane strain conditions as default for 2D simulations.
## Order of process variables/global components
OpenGeoSys uses internally a vector of primary vector components ("global component vector").
...
...
@@ -64,12 +68,12 @@ This order is used, e.g., to display the per component convergence of the non-li
@@ -86,7 +90,7 @@ This order is used, e.g., to display the per component convergence of the non-li
## Kelvin mapping
To map the elastic tensor OpenGeoSys internally uses a Kelvin mapping with an adapted component ordering for computational reasons \[[1](https://arxiv.org/abs/1605.09606)\].
To map the elasticity/stiffness tensor OpenGeoSys internally uses a Kelvin mapping with an adapted component ordering for computational reasons \[[1](https://arxiv.org/abs/1605.09606)\].
For 2D, the Kelvin-Vector of the stress tensor looks like $\sigma=(\sigma_{xx},\sigma_{yy},\sigma_{zz},\sqrt{2}\sigma_{xy})$ whereas the 3D version reads as $\sigma=(\sigma_{xx},\sigma_{yy},\sigma_{zz},\sqrt{2}\sigma_{xy}, \sqrt{2}\sigma_{yz},\sqrt{2}\sigma_{xz})$. The actual output consists of the full (symmetric) tensor elements (without the factor $\sqrt{2}$) retaining the same order.
For Kelvin mapping also see the [conversion function documentation](https://doxygen.opengeosys.org/d6/dce/namespacemathlib_1_1kelvinvector#ad78b122c10e91732e95181b6c9a92486).
