Merge pull request #2238 from chleh/jac-test

Jacobian tester for local assemblers.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CentralDifferences/c_CentralDifferences.md

@@ -0,0 +1 @@
+Assembles the Jacobian using central differences.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CentralDifferences/t_component_magnitudes.md

@@ -0,0 +1,5 @@
+Representative magnitudes for the components of the solution vector of the
+process being assembled.
+
+E.g., for the HT process there are two components: pressure and temperature,
+thus two values are expected in this case.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CentralDifferences/t_relative_epsilons.md

@@ -0,0 +1,5 @@
+Specifies the magnitudes of the perturbations used to compute the numerical
+Jacobian.
+
+The magnitudes are specified relative to the \c component_magnitudes.
+The number of values given must match the one of the \c component_magnitudes.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/c_CompareJacobians.md

@@ -0,0 +1,31 @@
+A Jacobian assembler that assembles the Jacobian in two different ways, compares
+the resulting local Jacobians and writes extensive logs in the form of a Python
+script if the provided tolerances are exceeded.
+
+Logging (and optionally program termination) is triggered only if both the
+absolute and the relative tolerance are exceeded.
+
+# Configuration example
+
+Code snippet:
+
+\code{xml}
+<OpenGeoSysProject>
+    <processes>
+        <process>
+            <jacobian_assembler>
+                <type>CompareJacobians</type>
+                <jacobian_assembler>
+                    <type>Analytical</type>
+                </jacobian_assembler>
+                <reference_jacobian_assembler>
+                    <type>CentralDifferences</type>
+                    <component_magnitudes>1 1</component_magnitudes>
+                    <relative_epsilons>1e-6 1e-6</relative_epsilons>
+                </reference_jacobian_assembler>
+                <abs_tol>1e-18</abs_tol>
+                <rel_tol>1e-7</rel_tol>
+                <fail_on_error>true</fail_on_error>
+                <log_file>/tmp/test.log</log_file>
+            </jacobian_assembler>
+\endcode

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_abs_tol.md

@@ -0,0 +1,4 @@
+The absolute tolerance (component-wise) for the difference between the two
+assembled local Jacobians.
+
+There is only one absolute tolerance value for all components of the Jacobian.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_fail_on_error.md

@@ -0,0 +1,2 @@
+Whether OGS should be aborted if both the absolute and relative tolerance are
+exceeded.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_jacobian_assembler.md

@@ -0,0 +1,2 @@
+The Jacobian assember whose assembled matrices will be used subsequently in the
+global equation system.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_log_file.md

@@ -0,0 +1,8 @@
+The path to the file to which details of differing Jacobians are written.
+
+Finally, the file will contain a Python script that can be used to conveniently
+examine the differences that occured.
+The given path is an absolute path or a path relative to the working directory
+of OGS.
+The log file will be overwritten, even if no differences exceeding the
+tolerances occur.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_reference_jacobian_assembler.md

@@ -0,0 +1,2 @@
+The Jacobian assembler whose results are used only to check the assembled
+matrices of the other Jacobian assembler.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/CompareJacobians/t_rel_tol.md

@@ -0,0 +1,4 @@
+The relative tolerance (component-wise) for the difference between the two
+assembled local Jacobians.
+
+There is only one relative tolerance value for all components of the Jacobian.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/i_jacobian_assembler.md

@@ -1 +1,2 @@
-\ogs_missing_documentation
+This setting makes it easy to switch between different ways to assemble the
+Jacobian, e.g., analytically or numerically using finite differences.

Documentation/ProjectFile/prj/processes/process/jacobian_assembler/t_type.md

@@ -1 +1 @@
-\ogs_missing_documentation
+The type of the Jacobian assembler to be used.

ProcessLib/AbstractJacobianAssembler.h

@@ -10,6 +10,7 @@
 #pragma once
 
 #include <vector>
+#include "BaseLib/Error.h"
 
 namespace ProcessLib
 {
@@ -41,6 +42,8 @@ class AbstractJacobianAssembler
         std::vector<double>& /*local_Jac_data*/,
         LocalCoupledSolutions const& /*coupled_solutions*/)
     {
+        // TODO make pure virtual.
+        OGS_FATAL("not implemented.");
     }
 
     virtual ~AbstractJacobianAssembler() = default;

ProcessLib/CentralDifferencesJacobianAssembler.cpp

@@ -134,10 +134,10 @@ createCentralDifferencesJacobianAssembler(BaseLib::ConfigTree const& config)
     config.checkConfigParameter("type", "CentralDifferences");
 
     // TODO make non-optional.
-    //! \ogs_file_param{prj__processes__process__jacobian_assembler__relative_epsilons}
+    //! \ogs_file_param{prj__processes__process__jacobian_assembler__CentralDifferences__relative_epsilons}
     auto rel_eps = config.getConfigParameterOptional<std::vector<double>>(
         "relative_epsilons");
-    //! \ogs_file_param{prj__processes__process__jacobian_assembler__component_magnitudes}
+    //! \ogs_file_param{prj__processes__process__jacobian_assembler__CentralDifferences__component_magnitudes}
     auto comp_mag = config.getConfigParameterOptional<std::vector<double>>(
         "component_magnitudes");
 

ProcessLib/CentralDifferencesJacobianAssembler.h

@@ -20,7 +20,8 @@ class ConfigTree;
 namespace ProcessLib
 {
 //! Assembles the Jacobian matrix using central differences.
-class CentralDifferencesJacobianAssembler : public AbstractJacobianAssembler
+class CentralDifferencesJacobianAssembler final
+    : public AbstractJacobianAssembler
 {
 public:
     //! Constructs a new instance.