When developing MOOSE Kernels bugs in the implementation of the On- and Off-Diagonal Jacobian may lead to bad (or no) convergence of problems utilizing the new kernel. MOOSE comes with a Jacobian Debugger script to assist the developers with this task.
The Jacobian debugger uses internal PETSc functionality to create a finite differenced Jacobian matrix from the residuals and compares it to the implemented Jacobian (usually found in
Note that MOOSE by default only uses the on-diagonal Jacobian entries and will not call your
computeQpOffDiagJacobian implementations at all. To test those add the following block to your input:
[Preconditioning] [./SMP] type = SMP full = true [../] 
Then simply run the Jacobian Debugger on your input file as follows:
This runs the moose application (same autodetection peacock uses) and computes the Jacobian using the user supplied
compute[..]Jacobian() methods and through finite differencing the residuals. If both Jacobian matrices agree the analyzer outputs.
No errors detected. :-)
Otherwise it outputs a human readable diagnosis of the input file, which could look like this:
Kernel for variable 's': (0,0) On-diagonal Jacobian is slightly off (by 0.500073 %) Kernel for variable 't': (1,1) On-diagonal Jacobian is wrong (off by 100.0 %) (1,2) Off-diagonal Jacobian for variable 'u' is questionable (off by 4.5 %) Kernel for variable 'u': (2,2) On-diagonal Jacobian needs to be implemented Kernel for variable 'u2': (3,3) On-diagonal Jacobian should just return zero
Note how the analyzer puts relative discrepancies between the hand coded and finite differenced into natural language.
During the Jacobian analysis no solve is being performed. The Jacobian is checked at exactly the given initial conditions. Set this IC carefully.
The Jacobian analyzer is still under development and a major feature that is being worked on is the output of the faulty kernel class names. This is not straightforward as in an input file multiple kernels can be contributing to the residual/Jacobian of any given variable.
RandomICon each variable to make sure that the values and gradients of your variables are non-zero to avoid trivial Jacobians.
Reduce the mesh in size to greatly speed up the analysis. This can be done with the
To view the available commandline options for the Jacobian Debugger run the script with the
Notable options are:
Perform resizing of generated meshs to speed up the testing.
This option will attempt to reduce the number of elements in a
type = GeneratedMeshmesh by setting the
nzvalues to either 1 or the value given by option
Set the mesh dimensions to this number of elements along each dimension (defaults to 1, requires
The executable you would like to build an input file for. If not supplied an executable will be searched for. The searched for executable will default to the optimized version of the executable (if available).
As in peacock executables are first search in the current directory, and then in the parent directories.
Output the command line used to run the application.
This shows exactly which commands are run to acquire the data needed to analyze the Jacobian matrix. Useful to debug the analyzer itself in case of failures.
analyzejacobian.pywill not work if you have
solve_type = PJFNKin an active
Preconditioningblock (having it in the
Executionerblock is fine).
analyzejacobian.pyturns off boundary all conditions, e.g. it currently tests kernels only and not integrated boundary conditions.