Application Usage link

Physics and Syntax

Application Development link

Framework Development link

MOOSEDocs link

Infrastructure

Questions

Information and Tools

Reference Residual Problem

Problem that checks for convergence relative to a user-supplied reference quantity rather than the initial residual

Description

By default, MOOSE checks convergence using relative and absolute criteria. Once the residual drops below either an absolute tolerance, or the residual divided by the initial residual for the current time step drops below a relative tolerance, the solution is considered converged. This works well for many problems, but in cases where the solution changes minimally between time steps, the initial residual can be very small, making the relative convergence check much too stringent.

The ReferenceResidualProblem checks for convergence by comparing the residual to a different reference quantity (instead of the initial residual). The user specifies a reference vector that can be used in a relative convergence check. Because the solution variables can have significantly different scaling, the convergence check performed in ReferenceResidualProblem checks convergence of the solution variables individually. When the norm of the residual for each solution variable is less than either the relative tolerance times the norm of the corresponding reference variable or the absolute tolerance, the solution is considered converged.

For some cases, it is more appropriate to group several variables together to check convergence of their grouped solution rather than checking the convergence of the variables individually. For example, in 2D and 3D mechanics solutions, there are multiple displacement variables, and because they have similar physical meaning, it often makes sense to treat them as one vector, which helps avoid issues that may be encountered if the model configuration is such that the reactions in one direction are much lower than in other directions.

When variables are grouped together, the norm of the grouped residual for those variables is used to check convergence. The optional parameter group_variables is used to provide one or more lists of variable names which are to be grouped together.

Use of this procedure requires that the user provide physically meaningful reference quantities. The vector of the reaction loads (in the case of mechanics) or integrated fluxes (in the case of diffusion problems) is typically suitable for this purpose, as it provides a measure of the loading applied to the system. To make these reference quantities, simply add the extra_vector_tags = <reference_vector_name> param/value pair to the computing objects that you want to add into the reference vector. An explicit example is given in Example Input syntax below.

Since relative convergence is computed differently with this approach, the nonlinear relative tolerance required to achieve the same error is typically different than with the default approach in MOOSE, and the differences will vary by the problem. The code user must evaluate the behavior of their model to ensure that appropriate tolerances are being used.

Example Input syntax

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
[]
(test/tests/problems/reference_residual_problem/reference_residual.i)

where the extra_tag_vectors parameter indicates the additional vectors that should be added to the non-linear system. This parameter must contain the name of the vector to be used for the reference_vector. In this example we only create one extra vector, the ref vector, that will be used for holding the reference residuals. To have computing objects add into the reference vector, simply add the extra_vector_tags = <reference_vector_name> param/value pair as illustrated below:

[BCs]
  [u]
    type = RobinBC
    boundary = 'left right'
    coef = ${coef}
    variable = u
    extra_vector_tags = 'ref'
  []
  [v]
    type = RobinBC
    boundary = 'left right'
    coef = 1
    variable = v
    extra_vector_tags = 'ref'
  []
[]
(test/tests/problems/reference_residual_problem/reference_residual.i)

In this example we are using the integrated fluxes as the reference quantites that we will compare the invidual variable residuals to.

Example Input syntax to group variables

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
  group_variables = 'disp_x disp_y;
                     scalar_strain_zz1 scalar_strain_zz2'
[]
(modules/combined/test/tests/reference_residual/group_variables.i)

Multiple groupings of variables can be provided in group_variables by separating them by semicolon. Convergence for those variables that are not given in group_variables is checked individually. A given variable can only be included in one group.

Input Parameters

  • acceptable_iterations0Iterations after which convergence to acceptable limits is accepted

    Default:0

    C++ Type:int

    Options:

    Description:Iterations after which convergence to acceptable limits is accepted

  • acceptable_multiplier1Multiplier applied to relative tolerance for acceptable limit

    Default:1

    C++ Type:double

    Options:

    Description:Multiplier applied to relative tolerance for acceptable limit

  • blockBlock IDs for the coordinate systems

    C++ Type:std::vector

    Options:

    Description:Block IDs for the coordinate systems

  • coord_typeXYZType of the coordinate system per block param

    Default:XYZ

    C++ Type:MultiMooseEnum

    Options:XYZ RZ RSPHERICAL

    Description:Type of the coordinate system per block param

  • error_on_jacobian_nonzero_reallocationFalseThis causes PETSc to error if it had to reallocate memory in the Jacobian matrix due to not having enough nonzeros

    Default:False

    C++ Type:bool

    Options:

    Description:This causes PETSc to error if it had to reallocate memory in the Jacobian matrix due to not having enough nonzeros

  • extra_tag_matricesExtra matrices to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them.

    C++ Type:std::vector

    Options:

    Description:Extra matrices to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them.

  • extra_tag_vectorsExtra vectors to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them.

    C++ Type:std::vector

    Options:

    Description:Extra vectors to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them.

  • force_restartFalseEXPERIMENTAL: If true, a sub_app may use a restart file instead of using of using the master backup file

    Default:False

    C++ Type:bool

    Options:

    Description:EXPERIMENTAL: If true, a sub_app may use a restart file instead of using of using the master backup file

  • group_variablesName of variables that are grouped together to check convergence. (Multiple groups can be provided, separated by semicolon)

    C++ Type:std::vector>

    Options:

    Description:Name of variables that are grouped together to check convergence. (Multiple groups can be provided, separated by semicolon)

  • ignore_zeros_in_jacobianFalseDo not explicitly store zero values in the Jacobian matrix if true

    Default:False

    C++ Type:bool

    Options:

    Description:Do not explicitly store zero values in the Jacobian matrix if true

  • kernel_coverage_checkTrueSet to false to disable kernel->subdomain coverage check

    Default:True

    C++ Type:bool

    Options:

    Description:Set to false to disable kernel->subdomain coverage check

  • material_coverage_checkTrueSet to false to disable material->subdomain coverage check

    Default:True

    C++ Type:bool

    Options:

    Description:Set to false to disable material->subdomain coverage check

  • near_null_space_dimension0The dimension of the near nullspace

    Default:0

    C++ Type:unsigned int

    Options:

    Description:The dimension of the near nullspace

  • null_space_dimension0The dimension of the nullspace

    Default:0

    C++ Type:unsigned int

    Options:

    Description:The dimension of the nullspace

  • parallel_barrier_messagingFalseDisplays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)

    Default:False

    C++ Type:bool

    Options:

    Description:Displays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)

  • reference_residual_variablesSet of variables that provide reference residuals for relative convergence check

    C++ Type:std::vector

    Options:

    Description:Set of variables that provide reference residuals for relative convergence check

  • reference_vectorThe tag name of the reference residual vector.

    C++ Type:TagName

    Options:

    Description:The tag name of the reference residual vector.

  • restart_file_baseFile base name used for restart (e.g. / or /LATEST to grab the latest file available)

    C++ Type:FileNameNoExtension

    Options:

    Description:File base name used for restart (e.g. / or /LATEST to grab the latest file available)

  • rz_coord_axisYThe rotation axis (X | Y) for axisymetric coordinates

    Default:Y

    C++ Type:MooseEnum

    Options:X Y

    Description:The rotation axis (X | Y) for axisymetric coordinates

  • skip_additional_restart_dataFalseTrue to skip additional data in equation system for restart. It is useful for starting a transient calculation with a steady-state solution

    Default:False

    C++ Type:bool

    Options:

    Description:True to skip additional data in equation system for restart. It is useful for starting a transient calculation with a steady-state solution

  • skip_nl_system_checkFalseTrue to skip the NonlinearSystem check for work to do (e.g. Make sure that there are variables to solve for).

    Default:False

    C++ Type:bool

    Options:

    Description:True to skip the NonlinearSystem check for work to do (e.g. Make sure that there are variables to solve for).

  • solution_variablesSet of solution variables to be checked for relative convergence

    C++ Type:std::vector

    Options:

    Description:Set of solution variables to be checked for relative convergence

  • solveTrueWhether or not to actually solve the Nonlinear system. This is handy in the case that all you want to do is execute AuxKernels, Transfers, etc. without actually solving anything

    Default:True

    C++ Type:bool

    Options:

    Description:Whether or not to actually solve the Nonlinear system. This is handy in the case that all you want to do is execute AuxKernels, Transfers, etc. without actually solving anything

  • transpose_null_space_dimension0The dimension of the transpose nullspace

    Default:0

    C++ Type:unsigned int

    Options:

    Description:The dimension of the transpose nullspace

  • use_nonlinearTrueDetermines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)

    Default:True

    C++ Type:bool

    Options:

    Description:Determines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)

Optional Parameters

  • control_tagsAdds user-defined labels for accessing object parameters via control logic.

    C++ Type:std::vector

    Options:

    Description:Adds user-defined labels for accessing object parameters via control logic.

  • default_ghostingFalseWhether or not to use libMesh's default amount of algebraic and geometric ghosting

    Default:False

    C++ Type:bool

    Options:

    Description:Whether or not to use libMesh's default amount of algebraic and geometric ghosting

  • enableTrueSet the enabled status of the MooseObject.

    Default:True

    C++ Type:bool

    Options:

    Description:Set the enabled status of the MooseObject.

Advanced Parameters

Input Files

Child Objects