From 99a80f8d1e17bb80d1918b044bbdecf9543150a9 Mon Sep 17 00:00:00 2001
From: Christoph Lehmann <christoph.lehmann@ufz.de>
Date: Wed, 24 Aug 2016 17:50:37 +0200
Subject: [PATCH] [Doc] added linear solver docu
---
.../ProjectFile/linear_solver/c_linear_solver.md | 6 ++++++
.../ProjectFile/linear_solver/eigen/i_eigen.md | 4 +++-
.../linear_solver/eigen/t_error_tolerance.md | 6 +++++-
.../linear_solver/eigen/t_max_iteration_step.md | 6 +++++-
.../ProjectFile/linear_solver/eigen/t_precon_type.md | 8 +++++++-
.../ProjectFile/linear_solver/eigen/t_solver_type.md | 6 +++++-
.../ProjectFile/linear_solver/petsc/i_petsc.md | 5 ++++-
.../ProjectFile/linear_solver/petsc/t_parameters.md | 9 ++++++++-
.../ProjectFile/linear_solver/petsc/t_prefix.md | 4 +++-
Documentation/ProjectFile/linear_solver/t_lis.md | 12 +++++++++++-
Documentation/ProjectFile/linear_solver/t_name.md | 4 +++-
11 files changed, 60 insertions(+), 10 deletions(-)
diff --git a/Documentation/ProjectFile/linear_solver/c_linear_solver.md b/Documentation/ProjectFile/linear_solver/c_linear_solver.md
index e69de29bb2d..2421001b7de 100644
--- a/Documentation/ProjectFile/linear_solver/c_linear_solver.md
+++ b/Documentation/ProjectFile/linear_solver/c_linear_solver.md
@@ -0,0 +1,6 @@
+In this group the configuration of linear solvers is described.
+
+Unlike all other options, there can be configurations for linear solvers from
+the Eigen, LIS, PETSc, etc. libraries at the same time. Which solver will be
+applied in the end is determined by the build configuration of the OGS
+executable.
diff --git a/Documentation/ProjectFile/linear_solver/eigen/i_eigen.md b/Documentation/ProjectFile/linear_solver/eigen/i_eigen.md
index 576add64edc..dae5722ba94 100644
--- a/Documentation/ProjectFile/linear_solver/eigen/i_eigen.md
+++ b/Documentation/ProjectFile/linear_solver/eigen/i_eigen.md
@@ -1 +1,3 @@
-\ogs_missing_documentation
+Configuration for solvers from the Eigen library.
+
+For details see also the [documentation of the Eigen library](https://eigen.tuxfamily.org/dox/group__Sparse__Reference.html).
diff --git a/Documentation/ProjectFile/linear_solver/eigen/t_error_tolerance.md b/Documentation/ProjectFile/linear_solver/eigen/t_error_tolerance.md
index 576add64edc..a04ed05818f 100644
--- a/Documentation/ProjectFile/linear_solver/eigen/t_error_tolerance.md
+++ b/Documentation/ProjectFile/linear_solver/eigen/t_error_tolerance.md
@@ -1 +1,5 @@
-\ogs_missing_documentation
+The tolerance of the linear solver.
+
+This setting is only applied if an iterative solver is chosen.
+
+Its default values is \f$10^{-16}\f$.
diff --git a/Documentation/ProjectFile/linear_solver/eigen/t_max_iteration_step.md b/Documentation/ProjectFile/linear_solver/eigen/t_max_iteration_step.md
index 576add64edc..bf4f34849e6 100644
--- a/Documentation/ProjectFile/linear_solver/eigen/t_max_iteration_step.md
+++ b/Documentation/ProjectFile/linear_solver/eigen/t_max_iteration_step.md
@@ -1 +1,5 @@
-\ogs_missing_documentation
+Defines the maximum number of iterations of the iterative solver.
+
+This setting is ignored if a direct solver is chosen.
+
+Its default value is \f$10^6\f$.
diff --git a/Documentation/ProjectFile/linear_solver/eigen/t_precon_type.md b/Documentation/ProjectFile/linear_solver/eigen/t_precon_type.md
index 576add64edc..4a19a2c9fe9 100644
--- a/Documentation/ProjectFile/linear_solver/eigen/t_precon_type.md
+++ b/Documentation/ProjectFile/linear_solver/eigen/t_precon_type.md
@@ -1 +1,7 @@
-\ogs_missing_documentation
+Chooses a specific preconditioner for the iterative linear solver.
+
+This setting is ignored if a direct solver is selected.
+
+Possible values are NONE, DIAGONAL and ILUT.
+
+The default is NONE.
diff --git a/Documentation/ProjectFile/linear_solver/eigen/t_solver_type.md b/Documentation/ProjectFile/linear_solver/eigen/t_solver_type.md
index 576add64edc..47d836f7c37 100644
--- a/Documentation/ProjectFile/linear_solver/eigen/t_solver_type.md
+++ b/Documentation/ProjectFile/linear_solver/eigen/t_solver_type.md
@@ -1 +1,5 @@
-\ogs_missing_documentation
+Chooses a specific linear solver.
+
+Possible values are CG, BiCGSTAB, and SparseLU.
+
+The default is SparseLU.
diff --git a/Documentation/ProjectFile/linear_solver/petsc/i_petsc.md b/Documentation/ProjectFile/linear_solver/petsc/i_petsc.md
index 576add64edc..d140d41ce7f 100644
--- a/Documentation/ProjectFile/linear_solver/petsc/i_petsc.md
+++ b/Documentation/ProjectFile/linear_solver/petsc/i_petsc.md
@@ -1 +1,4 @@
-\ogs_missing_documentation
+Configures options for linear solvers from the PETSc library.
+
+For further details see also the
+[documentation of the PETSc library](http://www.mcs.anl.gov/petsc/documentation/)
diff --git a/Documentation/ProjectFile/linear_solver/petsc/t_parameters.md b/Documentation/ProjectFile/linear_solver/petsc/t_parameters.md
index 576add64edc..816c46eb469 100644
--- a/Documentation/ProjectFile/linear_solver/petsc/t_parameters.md
+++ b/Documentation/ProjectFile/linear_solver/petsc/t_parameters.md
@@ -1 +1,8 @@
-\ogs_missing_documentation
+Sets PETSc options from the given parameter string.
+
+The default value is <tt>"-ksp_type cg -pc_type bjacobi -ksp_rtol 1e-16 -ksp_max_it 10000"</tt>
+
+\attention
+PETSc can also receive options from the commandline arguments. However, the
+values from the prj file are applied directly to the linear solver. If
+specifying both, make sure that you check which options take precedence.
diff --git a/Documentation/ProjectFile/linear_solver/petsc/t_prefix.md b/Documentation/ProjectFile/linear_solver/petsc/t_prefix.md
index 576add64edc..3b980ae4330 100644
--- a/Documentation/ProjectFile/linear_solver/petsc/t_prefix.md
+++ b/Documentation/ProjectFile/linear_solver/petsc/t_prefix.md
@@ -1 +1,3 @@
-\ogs_missing_documentation
+Sets the options prefix for this PETSc linear solver.
+
+Cf. the PETSc [KSPSetOptionsPrefix documentation](http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOptionsPrefix.html).
diff --git a/Documentation/ProjectFile/linear_solver/t_lis.md b/Documentation/ProjectFile/linear_solver/t_lis.md
index 576add64edc..f5fa016fbc0 100644
--- a/Documentation/ProjectFile/linear_solver/t_lis.md
+++ b/Documentation/ProjectFile/linear_solver/t_lis.md
@@ -1 +1,11 @@
-\ogs_missing_documentation
+Defines an option string that will be passed to solvers of the LIS library.
+
+The default is <tt>-initx_zeros 0</tt>, i.e., not to overwrite the passed initial
+guess with zeroes. All other options are appended to this default value.
+
+\attention
+LIS can also receive options from the commandline arguments. However, the values
+from the prj file are applied directly to the linear solver. If specifying both,
+make sure that you check which options take precedence.
+
+Refer to the [documentation of LIS](http://www.ssisc.org/lis/index.en.html) for further details.
diff --git a/Documentation/ProjectFile/linear_solver/t_name.md b/Documentation/ProjectFile/linear_solver/t_name.md
index 576add64edc..fe6b18dc8b3 100644
--- a/Documentation/ProjectFile/linear_solver/t_name.md
+++ b/Documentation/ProjectFile/linear_solver/t_name.md
@@ -1 +1,3 @@
-\ogs_missing_documentation
+Name of the linear solver.
+
+Used, e.g., to reference it in the nonlinear solver configuation.
--
GitLab