Exodiff

Exodiff tests compare Exodus output(s) for the test to a reference in the specified gold_dir folder. Exodus output(s) contains both field variables, scalar variables and postprocessors, the latter two defined as global variables. This tester picks up any difference between all fields at any spatial location, at any time step included in the output(s). Complete documentation for the Exodiff utility may be found here.

Options

Test configuration options are added to the tests file.

  • abs_zero: sets an absolute zero cutoff used in comparisons, defaults to 1e-10.

  • rel_err: sets a relative error tolerance. Defaults to 5.5e-6.

  • exodiff_opts: additional options passed to the Exodiff utility on the command line. Their list may be found in its documentation

  • custom_cmp: use a custom comparison. The output of the comparison must match the specified file. See below for more details

  • map: use geometrical mapping to match up elements. This is usually a good idea because it makes files comparable between runs with Serial and Parallel Mesh. Defaults to True.

  • partial: invokes a matching algorithm similar to the -m option when running exodiff on the command line. However this option ignores unmatched nodes and elements. This allows comparison of files that only partially overlap. Defaults to False.

  • use_old_floor: Use Exodiff old floor option. Defaults to False

Other test commands & restrictions may be found in the TestHarness documentation.

Generating custom comparison files

A custom comparison file may be generated by running in the command line:

${MOOSE_DIR}/framework/contrib/exodiff/exodiff -summary moose_simulation_out.e

This generates a summary of the simulation which can be edited to make the custom comparison file, where the tolerances for each variable may be set individually. In the example below, the tolerances are adjusted for local comparisons of field variables, both nodal and elemental. The relative error criteria is set to 1e-6 and the absolute error criteria is strongly tightened by setting it to 0. These modifications apply to variable u and distance, and any variable that is not listed in the comparison file is not compared. The time step and nodal coordinates tolerances are also modified to 1e-6.

COORDINATES absolute 1.e-6

TIME STEPS relative 1.e-6 floor 0.0

NODAL VARIABLES relative 1.e-6 floor 0.0
	u

ELEMENT VARIABLES relative 1.e-6 floor 0.0
	distance
(contrib/moose/test/tests/geomsearch/quadrature_nearest_node_locator/qnnl_ad.cmp)

A field may be ignored by either setting a loose tolerance, or if it may be present in only one of the files by deleting the line for the field in the comparison file.

Example test configuration in the MOOSE test suite

In this example, four tests are set up using an Exodiff tester. The third one uses the same input file as the second one, with additional arguments passed on the command line to run a different configuration. The Exodus files compared here mainly contain the values of the array variables on the mesh.

[Tests]
  issues = '#19564'
  design = 'ArrayMooseVariable.md'

  [block_aux_kernel_test]
    type = 'Exodiff'
    input = 'array_variable_test.i'
    exodiff = 'array_variable_test_out.e'
    requirement = 'The system shall provide an ability to add array variables with constant initial conditions.'
  []
  [size_one]
    type = 'Exodiff'
    input = 'array_variable_size_one_test.i'
    exodiff = 'array_variable_size_one_test_out.e'
    requirement = 'The system shall be able to define an array variable with component size one.'
  []
  [array_false_error]
    type = 'RunException'
    input = 'array_variable_size_one_test.i'
    cli_args = 'Variables/u/components=2 Variables/u/array=false'
    requirement = 'The system shall report a reasonable error when defining a variable with multiple components not as an array variable.'
    expect_err = "'array' is set to false."
  []
  [action]
    type = 'Exodiff'
    input = 'array_variable_action.i'
    exodiff = 'array_variable_action_out.e'
    requirement = 'The system shall support the automated creation of array variables.'
  []
[]
(contrib/moose/test/tests/variables/array_variable/tests)