.. _output-verification:

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

.. code-block:: sierrainput

   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:

.. code-block:: sierrainput

   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:

.. math::

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