For a detailed discussion on preconditioning in MOOSE, see the wiki systems page here.

To summarize, an accurate and complete preconditioning matrix can be important for an efficient Preconditioned Jacobian-Free Newton-Krylove (PJFNK) solve. It is absolutely essential for solve_type = NEWTON. MOOSE has multiple options for building the preconditioning matrix:

  • (Default) Block Diagonal Preconditioning
  • Single Matrix Preconditioner (SMP)
  • Finite Difference Preconditioner (FDP)
  • Physics Based Preconditioner (PBP)

Block diagonal preconditioning uses kernels' and integrated boundary conditions' computeQpJacobian methods to build a block diagonal matrix. It will not account for variable coupling. This is the default if a user does not specify a [Preconditioning] block in their input file.

The Single Matrix Preconditioner builds its matrix using kernels' and integrated BCs' computeQpJacobian and computeQpOffDiagJacobian methods, the latter of which is responsible for the contributions of coupled variables. A good, simple example of a computeQpOffDiagJacobian method is in CoupledForce. CoupledForce contributes a weak-form residual equal to

$$$$R_i = -\psi_i v$$$$

To determine the corresponding off-diagonal Jacobian contribution, one must take the deriative:

$$$$\frac{\partial R_i}{\partial v_j} = -\psi_i \frac{\partial v}{\partial v_j} = -\psi_i \phi_j$$$$

To make use of user-specified computeQpOffDiagJacobian methods, one should specify in his/her input file:

    type = SMP
    full = true

The user may also choose to omit certain off-diagonal entries from their SMP matrix; this is outlined in the detailed Preconditioning article.

To build a preconditioning matrix through finite differencing of the residuals, the user can specify in his/her input file:

    type = FDP
    full = true

This will create a near-perfect preconditioning matrix; however, it is extremely slow and will only work in serial. FDP should only be used for debugging purposes.

For information on the last preconditioning option, PBP, which is more nuanced, we refer the reader to the dedicated wiki page.

Complete source files