Debug System

Overview

The [Debug] input file block is designed to contain options to enable debugging tools for a simulation. For example, the input file snippet below demonstrates how to enable the material property debugging tool. This tool automatically outputs material properties as fields in the Exodus file. A complete list of the available options is provided in the parameter list at the bottom of this page.

[Debug]
  show_material_props = true
[]

Residual outputs for debugging nonlinear convergence issues

When solving multi-variable or multi-physics problems, it is often the case that the residual for a subset of variables is more problematic to converge than for the others. This may be because the underlying physics are tougher to solve, or because there are issues with the kernels for those variables!

MOOSE provides two convenient debug boolean options to examine the convergence of nonlinear residuals:

"show_var_residual_norms" shows the residual norms for each nonlinear variable equation. The equation with the highest residual is the least converged. This is the norm after scaling if equation scaling, automatic or manual, is used.
"show_top_residuals" shows the residual norms only for the least converged variable equation.

Helpful information on debugging numerical convergence issues is provided in the numerical troubleshooting page.

Execution ordering output

Ordering of the problem set-up

MOOSE parses the input file and executes numerous Actions which progressively load/build the mesh, create the variables, kernels, boundary conditions, output objects etc. The ordering of this process may be shown using the "show_actions" parameter.

note

The dependencies of each Action should be declared in the source code of each Action. This enables MOOSE to perform automatic dependency resolution to correctly order them. To view declared action dependencies, please use the "show_action_dependencies" parameter.

note

For the automatic ordering of the mesh generators, please refer to the mesh documentation page.

Solve and execution ordering

Nearly every solve in MOOSE consists of a succession of operations on nodes, quadrature points, elements and elements' faces. These operations may be for example to compute the contribution of a kernel/boundary condition/etc. to the residual, Jacobian, etc.

The MOOSE Debug system offers the "show_execution_order" parameter to output the order of execution of each of these objects in those loops. This order may depend on local block/boundary restrictions, and local or global dependency resolutions.

This parameter is most helpful to understand if AuxKernels, UserObjects and other systems which can interact in arbitrarily complex ways on a group of variables are indeed executed in the order desired by the modeler. If problematic, object execution may be reordered using various boolean parameters, execute_on flags, and other manual dependency declarations. For example for UserObjects, the execution_order_group parameter lets the modeler select the ordering of executions of user objects.

Viewing objects created by an applications

Numerous applications will use Actions to simplify the user input. This reduces opportunities for mistakes in an input, but has the inconvenience of hiding part of the simulation setup. The "show_actions" will, for most objects, list the objects created by an action. The Debug system also offers several summaries of objects:

"show_material_props" for material properties, created on elements, neighbors and sides
"show_reporters" for reporters, created directly or from systems that derive from Reporters, such as VectorPostprocessors and Positions
"show_functors" for Functors, an abstraction for objects which includes Functions and Variables
"show_block_restriction" for information regarding block-restriction of objects

Additionally, "show_execution_order" will provide the list of objects executed as they are executed. This includes, Kernels (and Interface, Nodal, finite volume, etc kernels), AuxKernels, boundary conditions (including finite volume), UserObjects, Postprocessors and VectorPostprocessors.

Other useful outputs available in other systems

The [Debug] system is not the only system that provides useful debugging information. We summarize these other helpful resources below:

to debug MultiApps and Transfers-related issues, the FEProblem parameter "verbose_multiapps" shows a helpful summary of transfers executed and important metadata about each Transfer.
to debug linear system convergence issues, numerous parameters may be passed to PETSc to make it more verbose. They are summarized on this page about debugging numerical issues and in the PETSc manual.
to debug a Mesh related issue, please see this page for built-in MOOSE mesh generation issues and this page for possible issues from an external mesh.
to debug Controls, there is a command line argument, --show-controls that can be passed to a MOOSE-application executable to show all active Controls and all active objects at all time steps in the simulation.

note

There are currently no convenient debugging options or tools for MultiApps-based fixed point iteration problems. Use the "fixed_point_min_its", "fixed_point_max_its" and "accept_on_max_fixed_point_iteration" to output at the desired fixed point iteration.

Parameters list

Input Parameters

active__all__ If specified only the blocks named will be visited and made active
Default:__all__
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
Description:If specified only the blocks named will be visited and made active
inactiveIf specified blocks matching these identifiers will be skipped.
C++ Type:std::vector<std::string>
Unit:(no unit assumed)
Controllable:No
Description:If specified blocks matching these identifiers will be skipped.
output_process_domainsFalseAdd a AuxVariable named "pid" that shows the partitioning for each process
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Add a AuxVariable named "pid" that shows the partitioning for each process
show_action_dependenciesFalsePrint out the action dependencies
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print out the action dependencies
show_actionsFalsePrint out the actions being executed
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print out the actions being executed
show_block_restrictionnonePrint out active objects like variables supplied for each block.
Default:none
C++ Type:MultiMooseEnum
Unit:(no unit assumed)
Options:none, all, variables, kernels, auxvariables, auxkernels, materials, userobjects
Controllable:No
Description:Print out active objects like variables supplied for each block.
show_execution_orderPrint more information about the order of execution during calculations
C++ Type:ExecFlagEnum
Unit:(no unit assumed)
Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, FINAL, FAILED, CUSTOM, ALWAYS, TRANSFER
Controllable:No
Description:Print more information about the order of execution during calculations
show_functorsFalseWhether to print information about the functors in the problem
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Whether to print information about the functors in the problem
show_material_propsFalsePrint out the material properties supplied for each block, face, neighbor, and/or sideset
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print out the material properties supplied for each block, face, neighbor, and/or sideset
show_mesh_meta_dataFalsePrint out the available mesh meta data
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print out the available mesh meta data
show_parserFalseShows parser block extraction and debugging information
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Shows parser block extraction and debugging information
show_reportersFalsePrint out information about the declared and requested Reporters
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print out information about the declared and requested Reporters
show_top_residuals0The number of top residuals to print out (0 = no output)
Default:0
C++ Type:unsigned int
Unit:(no unit assumed)
Controllable:No
Description:The number of top residuals to print out (0 = no output)
show_var_residual_normsFalsePrint the residual norms of the individual solution variables at each nonlinear iteration
Default:False
C++ Type:bool
Unit:(no unit assumed)
Controllable:No
Description:Print the residual norms of the individual solution variables at each nonlinear iteration
show_var_residualVariables for which residuals will be sent to the output file.
C++ Type:std::vector<NonlinearVariableName>
Unit:(no unit assumed)
Controllable:No
Description:Variables for which residuals will be sent to the output file.

Optional 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.

Advanced Parameters

Syntax list

Available Subsystems

Moose App
MaterialDerivativeTest

Available Actions

Moose App
SetupDebugActionAdds various debugging type output to the simulation system.
SetupResidualDebugActionAdds the necessary objects for computing the residuals for individual variables.

(moose/test/tests/outputs/debug/show_material_props_debug.i)

[Mesh]
  [gen]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 10
    ny = 10
  []
  [./subdomains]
    input = gen
    type = SubdomainBoundingBoxGenerator
    bottom_left = '0.1 0.1 0'
    block_id = 1
    top_right = '0.9 0.9 0'
  [../]
[]

[Variables]
  [./u]
  [../]
[]

[Kernels]
  [./diff]
    type = Diffusion
    variable = u
  [../]
[]

[BCs]
  [./left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  [../]
  [./right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  [../]
[]

[Materials]
  [./block]
    type = GenericConstantMaterial
    block = '0 1'
    prop_names = 'property0 property1 property2 property3 property4 property5 property6 property7 property8 property9 property10'
    prop_values = '0 1 2 3 4 5 6 7 8 9 10'
  [../]
  [./boundary]
    type = GenericConstantMaterial
    prop_names = bnd_prop
    boundary = top
    prop_values = 12345
  [../]
  [./restricted]
    type = GenericConstantMaterial
    block = 1
    prop_names = 'restricted0 restricted1'
    prop_values = '10 11'
  [../]
[]

[Executioner]
  type = Steady

  solve_type = 'PJFNK'


  petsc_options_iname = '-pc_type -pc_hypre_type'
  petsc_options_value = 'hypre boomeramg'
[]

[Outputs]
  execute_on = 'timestep_end'
[]

[Debug]
  show_material_props = true
[]

Overview
Residual outputs for debugging nonlinear convergence issues
Execution ordering output
Viewing objects created by an applications
Other useful outputs available in other systems
Parameters list
Input Parameters
Syntax list
Available Subsystems
Available Actions

Debug System

Overview

Residual outputs for debugging nonlinear convergence issues

Execution ordering output

Ordering of the problem set-up

Solve and execution ordering

Viewing objects created by an applications

Other useful outputs available in other systems

Parameters list

Input Parameters

Optional Parameters

Advanced Parameters

Syntax list

Available Subsystems

Available Actions

(moose/test/tests/outputs/debug/show_material_props_debug.i)

show_var_residual_norms

show_top_residuals

show_actions

show_action_dependencies

show_execution_order

show_actions

show_material_props

show_reporters

show_functors

show_block_restriction

show_execution_order

verbose_multiapps

fixed_point_min_its

fixed_point_max_its

accept_on_max_fixed_point_iteration