ReferenceResidualProblem

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 there are some scenarios that are problematic for convergence:

There is a large scaling difference between the solution variables, so taking the $var element = document.getElementById("moose-equation-70fa2ad4-7b7e-4029-9dbe-d19fb0865c1b");katex.render("L^2", element, {displayMode:false,throwOnError:false});$ norm of the combined vector skews the convergence check so that it becomes increasingly dominated by the variable with larger absolute values in the residual vector as the scaling difference increases.
The model conditions have changed very little from the previous step, so the initial residual is very low because the solution is essentially converged before any nonlinear iterations have been performed. The standard convergence check that uses the initial residual as a reference quantity eventually fails after a few steps because the solution is forced to converge to tighter limits with each time step, until numerical roundoff error prevents the solution from converging more tightly.
The state of the problem is such that the values of the residual at all degrees of freedom where Dirichlet boundary conditions are applied are zero in the converged solution. An example of this is a mechanics model that has Dirichlet boundary conditions to prevent rigid body motion, but the model only experiences free thermal expansion, so there are no reaction loads at those points. Another example is if there is a time step when no loading is applied.

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 $var element = document.getElementById("moose-equation-0c1cd1d8-868e-4bdc-bdb2-50b8c7675c74");katex.render("L^2", element, {displayMode:false,throwOnError:false});$ norm of the residual for each solution variable is less than either the relative tolerance times the $var element = document.getElementById("moose-equation-9ab767bb-309e-4414-b2da-6023101810fc");katex.render("L^2", element, {displayMode:false,throwOnError:false});$ norm of the corresponding reference variable or the absolute tolerance, the solution is considered converged.

By checking the convergence of individual variables and comparing to reference quantities that are meaningful even when the solution is not changing, ReferenceResidualProblem addresses the first two issues listed above. The third issue is potentially more of a problem with ReferenceResidualProblem than the standard MOOSE convergence check, and dealing with it is discussed in Dealing with Residuals that are Zero at Boundaries.

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" parameter to the computing objects that you want to add into the reference vector. An explicit example is given in Example Input Syntax below. Alternatively, the "absolute_value_vector_tags"` parameter can be used in the kernels to assemble the absolute value of the contribution to each degree of freedom affected by the kernel.

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.

Dealing with Residuals that are Zero at Boundaries

As mentioned in the third case above where relative convergence checks can fail, the converged solutions for some problems are zero on all boundaries with Dirichlet boundary condition (BC) because of the nature of the loading conditions. This would make the ReferenceResidualProblem convergence checks fail because the norm of the reference vector would be zero in this case. This is manifested when the reference values decrease at the same rate as the residuals, so relative convergence is never achieved.

In some mechanics problems, such as those with symmetry planes, this might happen only in one direction. This situation can be remedied by grouping together the residuals for all components of the displacement variables rather than checking them individually. If the reference vector for one of the variables in the group is zero (because there are no Dirichlet BCs that restrict the solution in that direction), but it is nonzero for the others, the residual for the set of variables will be checked together, and the variable with a zero value will not prevent convergence as it normally would. Grouping variables is accomplished by using the group_variables option, which is used to provide one or more lists of names of variables to group together.

In some cases, however, there may be no degrees of freedom with nonzero residuals at Dirichlet BCs for even a group of variables. This could happen in mechanics problems that only have free expansion, in which the Dirichlet BCs are important for preventing rigid body motion, but do not restrain the deformation of the body. This could also happen if there is simply no loading on a model during a time step.

It is necessary in such cases to also specify an absolute tolerance using nl_abs_tol, which is a problem-specific value that must be higher than the residual below which the solution can no longer converge tighter due to numeric roundoff errors, but sufficiently low to ensure that the solution is converged when that limit is reached.

Alternatively, the "absolute_value_vector_tags" parameter can be used in the kernels or the action that sets them up. This option does not rely on the use of Dirichlet BCs to compute a meaningful reference vector, and can typically remedy this issue.

Example Input Syntax

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
[]

where the "extra_tag_vectors" parameter indicates the additional vectors that should be added to the nonlinear system. This parameter must contain the name of the reference vector, which is defined in the "reference_vector" parameter. 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 specify the name of that reference vector with the "extra_vector_tags" parameter 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'
  []
[]

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

Grouping Variables

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
  group_variables = 'disp_x disp_y;
                     scalar_strain_zz1 scalar_strain_zz2'
[]

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
Unit:(no unit assumed)
Controllable:No
Description:Iterations after which convergence to acceptable limits is accepted
acceptable_multiplier1Multiplier applied to relative tolerance for acceptable limit
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Multiplier applied to relative tolerance for acceptable limit
converge_onIf supplied, use only these variables in the individual variable convergence check
C++ Type:std::vector<NonlinearVariableName>
Unit:(no unit assumed)
Controllable:No
Description:If supplied, use only these variables in the individual variable convergence check
group_variablesName of variables that are grouped together to check convergence. (Multiple groups can be provided, separated by semicolon)
C++ Type:std::vector<std::vector<NonlinearVariableName>>
Unit:(no unit assumed)
Controllable:No
Description:Name of variables that are grouped together to check convergence. (Multiple groups can be provided, separated by semicolon)
linear_sys_namesThe linear system names
C++ Type:std::vector<LinearSystemName>
Unit:(no unit assumed)
Controllable:No
Description:The linear system names
normalization_typeglobal_L2The normalization type used to compare the reference and actual residuals.
Default:global_L2
C++ Type:MooseEnum
Unit:(no unit assumed)
Options:global_L2, local_L2, global_Linf, local_Linf
Controllable:No
Description:The normalization type used to compare the reference and actual residuals.
reference_residual_variablesSet of variables that provide reference residuals for relative convergence check
C++ Type:std::vector<AuxVariableName>
Unit:(no unit assumed)
Controllable:No
Description:Set of variables that provide reference residuals for relative convergence check
reference_vectorThe tag name of the reference residual vector.
C++ Type:TagName
Unit:(no unit assumed)
Controllable:No
Description:The tag name of the reference residual vector.
regard_general_exceptions_as_errorsFalseIf we catch an exception during residual/Jacobian evaluaton for which we don't have specific handling, immediately error instead of allowing the time step to be cut
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:If we catch an exception during residual/Jacobian evaluaton for which we don't have specific handling, immediately error instead of allowing the time step to be cut
solution_variablesSet of solution variables to be checked for relative convergence
C++ Type:std::vector<NonlinearVariableName>
Unit:(no unit assumed)
Controllable:No
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
Unit:(no unit assumed)
Controllable:Yes
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
zero_reference_residual_treatmentrelative_toleranceDetermine behavior if a reference residual value of zero is present for a particular variable.
Default:relative_tolerance
C++ Type:MooseEnum
Unit:(no unit assumed)
Options:zero_tolerance, relative_tolerance
Controllable:No
Description:Determine behavior if a reference residual value of zero is present for a particular variable.

Optional Parameters

allow_initial_conditions_with_restartFalseTrue to allow the user to specify initial conditions when restarting. Initial conditions can override any restarted field
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:True to allow the user to specify initial conditions when restarting. Initial conditions can override any restarted field
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
Unit:(no unit assumed)
Controllable:No
Description:EXPERIMENTAL: If true, a sub_app may use a restart file instead of using of using the master backup file
restart_file_baseFile base name used for restart (e.g. / or /LATEST to grab the latest file available)
C++ Type:FileNameNoExtension
Unit:(no unit assumed)
Controllable:No
Description:File base name used for restart (e.g. / or /LATEST to grab the latest file available)

Restart Parameters

allow_invalid_solutionFalseSet to true to allow convergence even though the solution has been marked as 'invalid'
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to true to allow convergence even though the solution has been marked as 'invalid'
immediately_print_invalid_solutionFalseWhether or not to report invalid solution warnings at the time the warning is produced instead of after the calculation
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Whether or not to report invalid solution warnings at the time the warning is produced instead of after the calculation
show_invalid_solution_consoleTrueSet to true to show the invalid solution occurance summary in console
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to true to show the invalid solution occurance summary in console

Solution Validity Control Parameters

boundary_restricted_elem_integrity_checkTrueSet to false to disable checking of boundary restricted elemental object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to false to disable checking of boundary restricted elemental object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?
boundary_restricted_node_integrity_checkTrueSet to false to disable checking of boundary restricted nodal object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to false to disable checking of boundary restricted nodal object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?
check_uo_aux_stateFalseTrue to turn on a check that no state presents during the evaluation of user objects and aux kernels
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:True to turn on a check that no state presents during the evaluation of user objects and aux kernels
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
Unit:(no unit assumed)
Controllable:No
Description:This causes PETSc to error if it had to reallocate memory in the Jacobian matrix due to not having enough nonzeros
fv_bcs_integrity_checkTrueSet to false to disable checking of overlapping Dirichlet and Flux BCs and/or multiple DirichletBCs per sideset
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to false to disable checking of overlapping Dirichlet and Flux BCs and/or multiple DirichletBCs per sideset
kernel_coverage_block_listList of subdomains for kernel coverage check. The meaning of this list is controlled by the parameter 'kernel_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).
C++ Type:std::vector<SubdomainName>
Unit:(no unit assumed)
Controllable:No
Description:List of subdomains for kernel coverage check. The meaning of this list is controlled by the parameter 'kernel_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).
kernel_coverage_checkTRUEControls, if and how a kernel subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'kernel_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'kernel_coverage_block_list').
Default:TRUE
C++ Type:MooseEnum
Unit:(no unit assumed)
Options:FALSE, TRUE, OFF, ON, SKIP_LIST, ONLY_LIST
Controllable:No
Description:Controls, if and how a kernel subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'kernel_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'kernel_coverage_block_list').
material_coverage_block_listList of subdomains for material coverage check. The meaning of this list is controlled by the parameter 'material_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).
C++ Type:std::vector<SubdomainName>
Unit:(no unit assumed)
Controllable:No
Description:List of subdomains for material coverage check. The meaning of this list is controlled by the parameter 'material_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).
material_coverage_checkTRUEControls, if and how a material subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'material_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'material_coverage_block_list').
Default:TRUE
C++ Type:MooseEnum
Unit:(no unit assumed)
Options:FALSE, TRUE, OFF, ON, SKIP_LIST, ONLY_LIST
Controllable:No
Description:Controls, if and how a material subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'material_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'material_coverage_block_list').
material_dependency_checkTrueSet to false to disable material dependency check
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to false to disable material dependency check
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
Unit:(no unit assumed)
Controllable:No
Description:True to skip the NonlinearSystem check for work to do (e.g. Make sure that there are variables to solve for).

Simulation Checks Parameters

control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
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
Unit:(no unit assumed)
Controllable:No
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
Unit:(no unit assumed)
Controllable:No
Description:Set the enabled status of the MooseObject.

Advanced Parameters

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. The outer index is for which nonlinear system the extra tag vectors should be added for
C++ Type:std::vector<std::vector<TagName>>
Unit:(no unit assumed)
Controllable:No
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. The outer index is for which nonlinear system the extra tag vectors should be added for
extra_tag_solutionsExtra solution vectors to add to the system that can be used by objects for coupling variable values stored in them.
C++ Type:std::vector<TagName>
Unit:(no unit assumed)
Controllable:No
Description:Extra solution vectors to add to the system that can be used by objects for coupling variable values stored in 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. The outer index is for which nonlinear system the extra tag vectors should be added for
C++ Type:std::vector<std::vector<TagName>>
Unit:(no unit assumed)
Controllable:No
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. The outer index is for which nonlinear system the extra tag vectors should be added for

Tagging Parameters

identify_variable_groups_in_nlTrueWhether to identify variable groups in nonlinear systems. This affects dof ordering
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Whether to identify variable groups in nonlinear systems. This affects dof ordering
ignore_zeros_in_jacobianFalseDo not explicitly store zero values in the Jacobian matrix if true
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Do not explicitly store zero values in the Jacobian matrix if true
nl_sys_namesnl0 The nonlinear system names
Default:nl0
C++ Type:std::vector<NonlinearSystemName>
Unit:(no unit assumed)
Controllable:No
Description:The nonlinear system names
previous_nl_solution_requiredFalseTrue to indicate that this calculation requires a solution vector for storing the previous nonlinear iteration.
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:True to indicate that this calculation requires a solution vector for storing the previous nonlinear iteration.
use_nonlinearTrueDetermines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)
Default:True
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Determines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)

Nonlinear System(S) Parameters

near_null_space_dimension0The dimension of the near nullspace
Default:0
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The dimension of the near nullspace
null_space_dimension0The dimension of the nullspace
Default:0
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The dimension of the nullspace
transpose_null_space_dimension0The dimension of the transpose nullspace
Default:0
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The dimension of the transpose nullspace

Null Space Removal Parameters

parallel_barrier_messagingFalseDisplays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Displays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)
verbose_multiappsFalseSet to True to enable verbose screen printing related to MultiApps
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Set to True to enable verbose screen printing related to MultiApps
verbose_setupfalseSet to 'true' to have the problem report on any object created. Set to 'extra' to also display all parameters.
Default:false
C++ Type:MooseEnum
Unit:(no unit assumed)
Options:false, true, extra
Controllable:No
Description:Set to 'true' to have the problem report on any object created. Set to 'extra' to also display all parameters.

Verbosity Parameters

(moose/test/tests/problems/reference_residual_problem/reference_residual.i)

coef=1

[Mesh]
  type = GeneratedMesh
  dim = 1
  nx = 2
[]

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
[]

[Variables]
  [u][]
  [v][]
[]

[Kernels]
  [u_diff]
    type = CoefDiffusion
    variable = u
    coef = ${coef}
  []
  [u_rxn]
    type = PReaction
    variable = u
    coefficient = ${coef}
    power = 2
  []
  [u_f]
    type = BodyForce
    variable = u
    value = ${coef}
  []
  [v_diff]
    type = Diffusion
    variable = v
  []
  [v_rxn]
    type = PReaction
    variable = v
    coefficient = 1
    power = 2
  []
  [v_f]
    type = BodyForce
    variable = v
    value = 1
  []
[]

[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'
  []
[]


[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(moose/test/tests/problems/reference_residual_problem/reference_residual.i)

coef=1

[Mesh]
  type = GeneratedMesh
  dim = 1
  nx = 2
[]

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
[]

[Variables]
  [u][]
  [v][]
[]

[Kernels]
  [u_diff]
    type = CoefDiffusion
    variable = u
    coef = ${coef}
  []
  [u_rxn]
    type = PReaction
    variable = u
    coefficient = ${coef}
    power = 2
  []
  [u_f]
    type = BodyForce
    variable = u
    value = ${coef}
  []
  [v_diff]
    type = Diffusion
    variable = v
  []
  [v_rxn]
    type = PReaction
    variable = v
    coefficient = 1
    power = 2
  []
  [v_f]
    type = BodyForce
    variable = v
    value = 1
  []
[]

[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'
  []
[]


[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(moose/modules/combined/test/tests/reference_residual/group_variables.i)

[Mesh]
  file = 2squares.e
  displacements = 'disp_x disp_y'
[]

[Problem]
  type = ReferenceResidualProblem
  extra_tag_vectors = 'ref'
  reference_vector = 'ref'
  group_variables = 'disp_x disp_y;
                     scalar_strain_zz1 scalar_strain_zz2'
[]

[Variables]
  [./disp_x]
  [../]
  [./disp_y]
  [../]

  [./scalar_strain_zz1]
    order = FIRST
    family = SCALAR
  [../]
  [./scalar_strain_zz2]
    order = FIRST
    family = SCALAR
  [../]
[]

[AuxVariables]
  [./temp]
    order = FIRST
    family = LAGRANGE
  [../]
  [./saved_x]
    order = FIRST
    family = LAGRANGE
  [../]
  [./saved_y]
    order = FIRST
    family = LAGRANGE
  [../]

  [./stress_xx]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./stress_xy]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./stress_yy]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./stress_zz]
    order = CONSTANT
    family = MONOMIAL
  [../]

  [./strain_xx]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./strain_xy]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./strain_yy]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./aux_strain_zz]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./saved_scalar_strain_zz1]
    order = FIRST
    family = SCALAR
  [../]
  [./saved_scalar_strain_zz2]
    order = FIRST
    family = SCALAR
  [../]
[]

[Postprocessors]
  [./react_z1]
    type = MaterialTensorIntegral
    rank_two_tensor = stress
    index_i = 2
    index_j = 2
    block = 1
  [../]
  [./react_z2]
    type = MaterialTensorIntegral
    rank_two_tensor = stress
    index_i = 2
    index_j = 2
    block = 2
  [../]
[]

[Physics]
  [./SolidMechanics]
    [./GeneralizedPlaneStrain]
      [./gps1]
        use_displaced_mesh = true
        displacements = 'disp_x disp_y'
        scalar_out_of_plane_strain = scalar_strain_zz1
        block = '1'
      [../]
      [./gps2]
        use_displaced_mesh = true
        displacements = 'disp_x disp_y'
        scalar_out_of_plane_strain = scalar_strain_zz2
        block = '2'
      [../]
    [../]
  [../]
[]

[Kernels]
  [./TensorMechanics]
    use_displaced_mesh = false
    displacements = 'disp_x disp_y'
    temperature = temp
    save_in = 'saved_x saved_y'
    extra_vector_tags = 'ref'
    block = '1 2'
  [../]
[]

[AuxKernels]
  [./tempfuncaux]
    type = FunctionAux
    variable = temp
    function = tempfunc
    use_displaced_mesh = false
  [../]
  [./stress_xx]
    type = RankTwoAux
    rank_two_tensor = stress
    variable = stress_xx
    index_i = 0
    index_j = 0
  [../]
  [./stress_xy]
    type = RankTwoAux
    rank_two_tensor = stress
    variable = stress_xy
    index_i = 0
    index_j = 1
  [../]
  [./stress_yy]
    type = RankTwoAux
    rank_two_tensor = stress
    variable = stress_yy
    index_i = 1
    index_j = 1
  [../]
  [./stress_zz]
    type = RankTwoAux
    rank_two_tensor = stress
    variable = stress_zz
    index_i = 2
    index_j = 2
  [../]

  [./strain_xx]
    type = RankTwoAux
    rank_two_tensor = total_strain
    variable = strain_xx
    index_i = 0
    index_j = 0
  [../]
  [./strain_xy]
    type = RankTwoAux
    rank_two_tensor = total_strain
    variable = strain_xy
    index_i = 0
    index_j = 1
  [../]
  [./strain_yy]
    type = RankTwoAux
    rank_two_tensor = total_strain
    variable = strain_yy
    index_i = 1
    index_j = 1
  [../]
  [./aux_strain_zz]
    type = RankTwoAux
    rank_two_tensor = total_strain
    variable = aux_strain_zz
    index_i = 2
    index_j = 2
  [../]
[]

[AuxScalarKernels]
  [./saved_scalar_strain_zz1_ref_resid]
    type = GeneralizedPlaneStrainReferenceResidual
    variable = saved_scalar_strain_zz1
    generalized_plane_strain = gps1_GeneralizedPlaneStrainUserObject
  [../]
  [./saved_scalar_strain_zz2_ref_resid]
    type = GeneralizedPlaneStrainReferenceResidual
    variable = saved_scalar_strain_zz2
    generalized_plane_strain = gps2_GeneralizedPlaneStrainUserObject
  [../]
[]

[Functions]
  [./tempfunc]
    type = ParsedFunction
    expression = '(1-x)*t'
  [../]
[]

[BCs]
  [./bottom1x]
    type = DirichletBC
    boundary = 1
    variable = disp_x
    value = 0.0
  [../]
  [./bottom1y]
    type = DirichletBC
    boundary = 1
    variable = disp_y
    value = 0.0
  [../]
  [./bottom2x]
    type = DirichletBC
    boundary = 2
    variable = disp_x
    value = 0.0
  [../]
  [./bottom2y]
    type = DirichletBC
    boundary = 2
    variable = disp_y
    value = 0.0
  [../]
[]

[Materials]
  [./elastic_tensor]
    type = ComputeIsotropicElasticityTensor
    poissons_ratio = 0.3
    youngs_modulus = 1e6
    block = '1 2'
  [../]
  [./strain1]
    type = ComputePlaneSmallStrain
    displacements = 'disp_x disp_y'
    scalar_out_of_plane_strain = scalar_strain_zz1
    block = 1
    eigenstrain_names = eigenstrain
  [../]
  [./strain2]
    type = ComputePlaneSmallStrain
    displacements = 'disp_x disp_y'
    scalar_out_of_plane_strain = scalar_strain_zz2
    block = 2
    eigenstrain_names = eigenstrain
  [../]
  [./thermal_strain]
    type = ComputeThermalExpansionEigenstrain
    temperature = temp
    thermal_expansion_coeff = 0.02
    stress_free_temperature = 0.5
    block = '1 2'
    eigenstrain_name = eigenstrain
  [../]
  [./stress]
    type = ComputeLinearElasticStress
    block = '1 2'
  [../]
[]

[Executioner]
  type = Transient

  solve_type = PJFNK
  line_search = none

# controls for linear iterations
  l_max_its = 100
  l_tol = 1e-10

# controls for nonlinear iterations
  nl_max_its = 15
  nl_rel_tol = 1e-12
  nl_abs_tol = 1e-10

# time control
  start_time = 0.0
  dt = 1.0
  dtmin = 1.0
  end_time = 2.0
  num_steps = 5000
[]

[Outputs]
  exodus = true
[]

Description
Example Input Syntax
Input Parameters