15. Error Checking

All TAO commands begin with the Tao prefix and return an integer indicating whether an error has occurred during the call. The error code equals zero after the successful completion of the routine and is set to a nonzero value if an error has been detected. The macro CHKERRQ(info) checks the value of info and calls an error handler upon error detection. CHKERRQ() should be used in all subroutines to enable a complete error traceback.

In Figure we indicate a traceback generated by error detection within a sample program. The error occurred on line 1007 of the file ${}TAO_DIR/src/interface/tao.c in the routine TaoSetUp() and was caused by nonconforming local lengths of the parallel gradient and solution vectors, which must be identically partitioned. The TaoSetUp() routine was called from the TaoSolveApplication() routine, which was in turn called on line 229 of the main() routine in the program ex2.c. The PETSc users manual provides further details regarding error checking, including information about the Fortran interface.


[ember] mpirun -np 2 ex2 -tao_lmvm 
[0]PETSC ERROR: TaoSetUp() line 1007 in src/interface/tao.c 
[0]PETSC ERROR:   Nonconforming object sizes! 
[0]PETSC ERROR:   Gradient and solution vectors must be identically partitioned! 
[0]PETSC ERROR: TaoSolveApplication() line 1739 in src/interface/tao.c 
[0]PETSC ERROR: main() line 229 in src/unconstrained/examples/tutorials/ex2.c 
[0] MPI Abort by user Aborting program ! 
[0] Aborting program! 
p0_911:  p4_error: : 1 
bm_list_912:  p4_error: interrupt SIGINT: 2 

Figure 5: Example of Error Traceback

When running the debugging version of the TAO software (PETSc configured with the --with-debugging option), checking is performed for memory corruption (writing outside of array bounds, etc). The macros CHKMEMQ and CHKMEMA can be called anywhere in the code to check the current status of the memory for corruption. By putting several (or many) of these macros into an application code, one can usually track down the code segment where corruption has occurred.