Sphinx docu of TPZPardisoSolver (and a bit of other solvers)

labmec · May 17, 2021 · ac51f34 · ac51f34
1 parent 5a5b1b8
commit ac51f34
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 6 deletions.
diff --git a/Matrix/doxmatrix.h b/Matrix/doxmatrix.h
@@ -1,6 +1,6 @@
 /**
  * @file
- * @brief Creates matrix, matrixutility, solver and frontal groups for Doxygen documentation.
+ * @brief Creates matrix, matrixutility and frontal groups for Doxygen documentation.
  */
 
 /** 
@@ -14,11 +14,6 @@
  * @brief Implements helper classes for matrices
  */
 
-/**
- * @defgroup solver The Solver classes
- * @brief This module contains all classes that represent a matrix inversion procedure. \n
- * Representing a inversion procedure as an object gives the user great flexibility to combine solution procedures
- */
 /**
  * @defgroup frontal The Frontal Matrix classes
  * @brief This module contains all classes involved in the frontal process

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -6,6 +6,7 @@ list(APPEND PZ_PUBLIC_HEADERS
     "${CMAKE_CURRENT_SOURCE_DIR}/pzmainpage.h"
     "${CMAKE_CURRENT_SOURCE_DIR}/structmatrix/doxstrmatrix.h"
     "${CMAKE_CURRENT_SOURCE_DIR}/material/doxmaterial.h"
+    "${CMAKE_CURRENT_SOURCE_DIR}/solver/doxsolver.h"
     )
 
 if(DOXYGEN_ADD_ALL)
@@ -30,4 +31,5 @@ set(docs_sources
     "${CMAKE_CURRENT_SOURCE_DIR}/references.bib")
 add_subdirectory(material)
 add_subdirectory(structmatrix)
+add_subdirectory(solver)
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,6 +12,7 @@ Welcome to NeoPZ's documentation!
 
    material/index.rst
    structmatrix/index.rst
+   solver/index.rst
    util/index.rst
 
 
@@ -22,6 +23,7 @@ This documentation is an ongoing work. The following sections have been written:
 
 - :doc:`material/index` How weak formulations are implemented
 - :doc:`structmatrix/index` How different matrix storage formats can be used
+- :doc:`solver/index` Available solvers in NeoPZ
 - :doc:`util/index` Utility classes available in NeoPZ
 
 About

diff --git a/docs/solver/CMakeLists.txt b/docs/solver/CMakeLists.txt
@@ -0,0 +1,6 @@
+list(APPEND docs_sources
+    "${CMAKE_CURRENT_SOURCE_DIR}/doxsolver.h"
+    "${CMAKE_CURRENT_SOURCE_DIR}/index.rst"
+    )
+
+set(docs_sources ${docs_sources} PARENT_SCOPE)
diff --git a/docs/solver/doxsolver.h b/docs/solver/doxsolver.h
@@ -0,0 +1,5 @@
+/**
+ * @defgroup solver The Solver classes
+ * @brief This module contains all classes that represent a matrix inversion procedure. \n
+ * Representing a inversion procedure as an object gives the user great flexibility to combine solution procedures
+ */
diff --git a/docs/solver/index.rst b/docs/solver/index.rst
@@ -0,0 +1,59 @@
+The Solver hierarchy
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+.. contents:: Table of Contents
+   :local:
+
+
+TPZSolver
+---------
+
+The :cpp:expr:`TPZSolver` defines the hierarchy of solvers to be used.
+
+.. note::
+   Since the availability of a given solver might depend on the chosen matrix storage format, the choice of solver is directly connected with the choice of :doc:`../structmatrix/structoptions`. Currently this only applies for the class :cpp:expr:`TPZPardisoSolver`, which is only compatible with sparse matrix storage.
+
+The NeoPZ solvers can be divided in two main groups: the :cpp:expr:`TPZMatrixSolver` hierarchy, for solving algebraic equation systems, and the (soon to be implemented) solvers for eigenvalue problems.
+
+.. doxygenclass:: TPZSolver
+   :members:
+
+TPZMatrixSolver
+^^^^^^^^^^^^^^^
+
+The :cpp:expr:`TPZMatrixSolver` represents a solver for algebraic equation systems in which the matrix has entries with the type :cpp:type:`TVar`, where :cpp:expr:`TVar=STATE`, for real problems, and :cpp:expr:`TVar=CSTATE`, for complex problems.
+
+The available solvers are
+
+.. doxygenenum:: TPZMatrixSolver::MSolver
+   :no-link:
+
+
+Further documentation
+"""""""""""""""""""""
+.. doxygenclass:: TPZMatrixSolver
+   :members:
+
+
+TPZStepSolver
+^^^^^^^^^^^^^
+.. doxygenclass:: TPZStepSolver
+   :members:
+
+TPZPardisoSolver
+^^^^^^^^^^^^^^^^
+
+The :cpp:expr:`TPZPardisoSolver` class acts as an wrapper for controlling the Intel MKL PARDISO Solver. Therefore, for one to use it, NeoPZ should have been configured using :code:`USING_MKL=ON`. While the PARDISO solver can still be used through :cpp:expr:`TPZStepSolver`, using an instance of :cpp:expr:`TPZPardisoSolver` directly provides a finer control of the PARDISO parameters.
+
+.. note::
+   The PARDISO solver is a solver for both symmetric and non-symmetric sparse matrices,
+   so it should be used with either :cpp:expr:`TPZSSpStructMatrix` or :cpp:expr:`TPZSpStructMatrix`.
+
+.. note::
+   There is still plenty of tuning options to be implemented in this class. Please contact us or submit a Pull Request if you think this class could be improved.
+
+.. doxygenclass:: TPZPardisoSolver
+   :members: