9.14. Solution Verification

Solution verification is the capability to enable the code to check a computed solution versus some reference solution and abort the run if an anomaly is detected. Solution verification is primarily used by the code development team to create automated verification tests for various capabilities. Solution verification can be of use to the code end user to help write tests to verify that a user written subroutine or expression is behaving as expected. Solution verification could also be used to stop a run that has entered an unphysical or unneeded regime.

BEGIN SOLUTION VERIFICATION
  VERIFY GLOBAL <string>gVar {<|<=|=|>|>=}
    <real>gVal [PLUS OR MINUS <real>Tol]
  VERIFY GLOBAL <string>gVar {<|<=|=|>|>=}
    GLOBAL <string>gVar2 [PLUS OR MINUS <real>Tol]
  VERIFY GLOBAL <string>gVar {<|<=|=|>|>=}
    FUNCTION <string>funcName
  VERIFY NODAL  <string>nVar
    AT NODE <integer>nodeNum {<|<=|=|>|>=}
    FUNCTION <string>funcName
  VERIFY NODAL  <string>nVar
    AT NODE <integer>nodeNum {<|<=|=|>|>=}
    <real>val
  VERIFY ELEMENT <string>eVar
    AT ELEMENT <integer>elemNum {<|<=|=|>|>=}
    <real>val
  VERIFY ELEMENT <string>eVar
    AT ELEMENT <integer>elemNum {<|<=|=|>|>=}
    FUNCTION <string>funcName

  # Absolute tolerance
  TOLERANCE = <real>absTol
  # Relative tolerance
  RELATIVE TOLERANCE = <real>relTol
  # Time tolerance
  TIME TOLERANCE = <real>timeTol

  SKIP TIMES = <real>time0 TO <real>time1
  EVALUATION TIMES = <real>time0 TO <real>time1

  COMPLETION FILE = <string>fileName
END

The various forms of the VERIFY GLOBAL, VERIFY NODAL, VERIFY ELEMENT commands check that the named variable has some relation to a defined constant, time history function, or other global variable. For example if creating and debugging a user subroutine based displacement function it may be helpful to ensure that the displacement at some node tracks with the expected analytic displacement given in a time history function. The global variables used in solution verification are often created via a USER OUTPUT based command block. If at any time step at which the solution is verified the VERIFY statement fails, the analysis will immediately abort and report an error.

Tolerances of how close a verification needs to be acceptable can be specified. The TOLERANCE and PLUS OR MINUS verify option both specify absolute tolerances. For example the command:

VERIFY GLOBAL disp1 = 1.0 PLUS OR MINUS 0.1

will verify successfully as long as disp1 is between 0.9 and 1.1.

The RELATIVE TOLERANCE command specifies an acceptable relative error between values being verified. A verification is successful if:

\[\frac{|\mathrm{gVal}-\mathrm{gVar}|}{\mathrm{max}(|\mathrm{gVal}|, |\mathrm{gVar}|)} < \mathrm{relTol}\]

The TIME TOLERANCE is used with the time history function based verify commands. A verification will pass if the gVar is within tolerance to any value of the function that would be computed at the current time plus or minus the timeTol. The time tolerance command is useful for verifying functions that have sharp jumps in time.

The SKIP TIMES command is used to skip verification over the defined time periods, and the EVALUATION TIMES command is used for verification over only the defined time periods. Together, the commands can be used to focus the verification on only the time periods where the solution is known.

The COMPLETION FILE command causes solution verification to output a status file named fileName at successful completion of the code run. Existence of the status file indicates that the run completed as expected. If the run dies due to failing a solution verification, runs into a queue time limit, or other unexpected error, the status file will not be written.