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
[]
(test/tests/outputs/debug/show_material_props_debug.i)

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.

commentnote

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.

commentnote

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:

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.

commentnote

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>

    Controllable:No

    Description:If specified only the blocks named will be visited and made active

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

    C++ Type:std::vector<std::string>

    Controllable:No

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

  • count_iterationsFalseAdd postprocessors for linear and nonlinear iterations

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Add postprocessors for linear and nonlinear iterations

  • inactiveIf specified blocks matching these identifiers will be skipped.

    C++ Type:std::vector<std::string>

    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

    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

    Controllable:No

    Description:Print out the action dependencies

  • show_actionsFalsePrint out the actions being executed

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Print out the actions being executed

  • show_execution_orderPrint more information about the order of execution during calculations

    C++ Type:ExecFlagEnum

    Options:FORWARD, ADJOINT, HOMOGENEOUS_FORWARD, ADJOINT_TIMESTEP_BEGIN, ADJOINT_TIMESTEP_END, NONE, INITIAL, LINEAR, 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

    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

    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

    Controllable:No

    Description:Print out the available mesh meta data

  • show_parserFalseShows parser block extraction and debugging information

    Default:False

    C++ Type:bool

    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

    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

    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

    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>

    Controllable:No

    Description:Variables for which residuals will be sent to the output file.

  • check_jacobianFalseSet to true to check jacobian

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Set to true to check jacobian

  • print_component_loopsFalseFlag to print component loops

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Flag to print component loops

Syntax list

Available Subsystems

Available Actions