Actual source code: petscerror.h

      1: /*
      2:     Contains all error handling interfaces for PETSc.
      3: */
      4: #if !defined(PETSCERROR_H)
      5: #define PETSCERROR_H

      7: /*
      8:      These are the generic error codes. These error codes are used
      9:      many different places in the PETSc source code. The string versions are
     10:      at src/sys/error/err.c any changes here must also be made there
     11:      These are also define in src/sys/f90-mod/petscerror.h any CHANGES here
     12:      must be also made there.

     14: */
     15: #define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */

     17: #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
     18: #define PETSC_ERR_SUP              56   /* no support for requested operation */
     19: #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
     20: #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
     21: #define PETSC_ERR_SIG              59   /* signal received */
     22: #define PETSC_ERR_FP               72   /* floating point exception */
     23: #define PETSC_ERR_COR              74   /* corrupted PETSc object */
     24: #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
     25: #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
     26: #define PETSC_ERR_MEMC             78   /* memory corruption */
     27: #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
     28: #define PETSC_ERR_USER             83   /* user has not provided needed function */
     29: #define PETSC_ERR_SYS              88   /* error in system call */
     30: #define PETSC_ERR_POINTER          70   /* pointer does not point to valid address */
     31: #define PETSC_ERR_MPI_LIB_INCOMP   87   /* MPI library at runtime is not compatible with MPI user compiled with */

     33: #define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
     34: #define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
     35: #define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
     36: #define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
     37: #define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
     38: #define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
     39: #define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
     40: #define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
     41: #define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
     42: #define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
     43: #define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
     44: #define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
     45: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */

     47: #define PETSC_ERR_FILE_OPEN        65   /* unable to open file */
     48: #define PETSC_ERR_FILE_READ        66   /* unable to read from file */
     49: #define PETSC_ERR_FILE_WRITE       67   /* unable to write to file */
     50: #define PETSC_ERR_FILE_UNEXPECTED  79   /* unexpected data in file */

     52: #define PETSC_ERR_MAT_LU_ZRPVT     71   /* detected a zero pivot during LU factorization */
     53: #define PETSC_ERR_MAT_CH_ZRPVT     81   /* detected a zero pivot during Cholesky factorization */

     55: #define PETSC_ERR_INT_OVERFLOW     84

     57: #define PETSC_ERR_FLOP_COUNT       90
     58: #define PETSC_ERR_NOT_CONVERGED    91  /* solver did not converge */
     59: #define PETSC_ERR_MISSING_FACTOR   92  /* MatGetFactor() failed */
     60: #define PETSC_ERR_OPT_OVERWRITE    93  /* attempted to over write options which should not be changed */
     61: #define PETSC_ERR_WRONG_MPI_SIZE   94  /* example/application run with number of MPI ranks it does not support */
     62: #define PETSC_ERR_USER_INPUT       95  /* missing or incorrect user input */
     63: #define PETSC_ERR_GPU_RESOURCE     96  /* unable to load a GPU resource, for example cuBLAS */
     64: #define PETSC_ERR_GPU              97  /* An error from a GPU call, this may be due to lack of resources on the GPU or a true error in the call */
     65: #define PETSC_ERR_MPI              98  /* general MPI error */
     66: #define PETSC_ERR_MAX_VALUE        99  /* this is always the one more than the largest error code */

     68: #define PetscStringizeArg(a) #a
     69: #define PetscStringize(a) PetscStringizeArg(a)

     72: /*MC
     73:    SETERRQ - Macro to be called when an error has been detected,

     75:    Synopsis:
     76: #include <petscsys.h>
     77:    PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode ierr,char *message)

     79:    Collective

     81:    Input Parameters:
     82: +  comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
     83: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
     84: -  message - error message

     86:   Level: beginner

     88:    Notes:
     89:     Once the error handler is called the calling function is then returned from with the given error code.

     91:     See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments

     93:     Experienced users can set the error handler with PetscPushErrorHandler().

     95:    Fortran Notes:
     96:       SETERRQ() may be called from Fortran subroutines but SETERRA() must be called from the
     97:       Fortran main program.

     99: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), CHKERRMPI()
    100: M*/
    101: #define SETERRQ(comm,ierr,s) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s)

    103: /*
    104:     Returned from PETSc functions that are called from MPI, such as related to attributes
    105:       Do not confuse PETSC_MPI_ERROR_CODE and PETSC_ERR_MPI, the first is registered with MPI and returned to MPI as
    106:       an error code, the latter is a regular PETSc error code passed within PETSc code indicating an error was detected in an MPI call.
    107: */
    108: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CLASS;
    109: PETSC_EXTERN PetscMPIInt PETSC_MPI_ERROR_CODE;

    112: /*MC
    113:    SETERRMPI - Macro to be called when an error has been detected within an MPI callback function

    115:    Synopsis:
    116: #include <petscsys.h>
    117:    PetscErrorCode SETERRMPI(MPI_Comm comm,PetscErrorCode ierr,char *message)

    119:    Collective

    121:    Input Parameters:
    122: +  comm - A communicator, use PETSC_COMM_SELF unless you know all ranks of another communicator will detect the error
    123: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    124: -  message - error message

    126:   Level: developer

    128:    Notes:
    129:     This macro is FOR USE IN MPI CALLBACK FUNCTIONS ONLY, such as those passed to MPI_Comm_create_keyval(). It always returns the error code PETSC_MPI_ERROR_CODE
    130:     which is registered with MPI_Add_error_code() when PETSc is initialized.

    132: .seealso: SETERRQ(), CHKERRQ(), CHKERRMPI(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
    133: M*/
    134: #define SETERRMPI(comm,ierr,s) return (PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s),PETSC_MPI_ERROR_CODE)

    136: /*MC
    137:    SETERRQ1 - Macro that is called when an error has been detected,

    139:    Synopsis:
    140: #include <petscsys.h>
    141:    PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg)

    143:    Collective

    145:    Input Parameters:
    146: +  comm - A communicator, so that the error can be collective
    147: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    148: .  message - error message in the printf format
    149: -  arg - argument (for example an integer, string or double)

    151:   Level: beginner

    153:    Notes:
    154:     Once the error handler is called the calling function is then returned from with the given error code.

    156:    Experienced users can set the error handler with PetscPushErrorHandler().

    158: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
    159: M*/
    160: #define SETERRQ1(comm,ierr,s,a1) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1)

    162: /*MC
    163:    SETERRQ2 - Macro that is called when an error has been detected,

    165:    Synopsis:
    166: #include <petscsys.h>
    167:    PetscErrorCode SETERRQ2(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2)

    169:    Collective

    171:    Input Parameters:
    172: +  comm - A communicator, so that the error can be collective
    173: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    174: .  message - error message in the printf format
    175: .  arg1 - argument (for example an integer, string or double)
    176: -  arg2 - argument (for example an integer, string or double)

    178:   Level: beginner

    180:    Notes:
    181:     Once the error handler is called the calling function is then returned from with the given error code.

    183:    Experienced users can set the error handler with PetscPushErrorHandler().

    185: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
    186: M*/
    187: #define SETERRQ2(comm,ierr,s,a1,a2) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2)

    189: /*MC
    190:    SETERRQ3 - Macro that is called when an error has been detected,

    192:    Synopsis:
    193: #include <petscsys.h>
    194:    PetscErrorCode SETERRQ3(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3)

    196:    Collective

    198:    Input Parameters:
    199: +  comm - A communicator, so that the error can be collective
    200: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    201: .  message - error message in the printf format
    202: .  arg1 - argument (for example an integer, string or double)
    203: .  arg2 - argument (for example an integer, string or double)
    204: -  arg3 - argument (for example an integer, string or double)

    206:   Level: beginner

    208:    Notes:
    209:     Once the error handler is called the calling function is then returned from with the given error code.

    211:     There are also versions for 4, 5, 6 and 7 arguments.

    213:    Experienced users can set the error handler with PetscPushErrorHandler().

    215: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    216: M*/
    217: #define SETERRQ3(comm,ierr,s,a1,a2,a3) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3)

    219: /*MC
    220:    SETERRQ4 - Macro that is called when an error has been detected,

    222:    Synopsis:
    223: #include <petscsys.h>
    224:    PetscErrorCode SETERRQ4(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4)

    226:    Collective

    228:    Input Parameters:
    229: +  comm - A communicator, so that the error can be collective
    230: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    231: .  message - error message in the printf format
    232: .  arg1 - argument (for example an integer, string or double)
    233: .  arg2 - argument (for example an integer, string or double)
    234: .  arg3 - argument (for example an integer, string or double)
    235: -  arg4 - argument (for example an integer, string or double)

    237:   Level: beginner

    239:    Notes:
    240:     Once the error handler is called the calling function is then returned from with the given error code.

    242:     There are also versions for 4, 5, 6 and 7 arguments.

    244:    Experienced users can set the error handler with PetscPushErrorHandler().

    246: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    247: M*/
    248: #define SETERRQ4(comm,ierr,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)

    250: /*MC
    251:    SETERRQ5 - Macro that is called when an error has been detected,

    253:    Synopsis:
    254: #include <petscsys.h>
    255:    PetscErrorCode SETERRQ5(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4,arg5)

    257:    Collective

    259:    Input Parameters:
    260: +  comm - A communicator, so that the error can be collective
    261: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    262: .  message - error message in the printf format
    263: .  arg1 - argument (for example an integer, string or double)
    264: .  arg2 - argument (for example an integer, string or double)
    265: .  arg3 - argument (for example an integer, string or double)
    266: .  arg4 - argument (for example an integer, string or double)
    267: -  arg5 - argument (for example an integer, string or double)

    269:   Level: beginner

    271:    Notes:
    272:     Once the error handler is called the calling function is then returned from with the given error code.

    274:     There are also versions for 4, 5, 6 and 7 arguments.

    276:    Experienced users can set the error handler with PetscPushErrorHandler().

    278: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    279: M*/
    280: #define SETERRQ5(comm,ierr,s,a1,a2,a3,a4,a5) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)

    282: /*MC
    283:    SETERRQ6 - Macro that is called when an error has been detected,

    285:    Synopsis:
    286: #include <petscsys.h>
    287:    PetscErrorCode SETERRQ6(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4,arg5,arg6)

    289:    Collective

    291:    Input Parameters:
    292: +  comm - A communicator, so that the error can be collective
    293: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    294: .  message - error message in the printf format
    295: .  arg1 - argument (for example an integer, string or double)
    296: .  arg2 - argument (for example an integer, string or double)
    297: .  arg3 - argument (for example an integer, string or double)
    298: .  arg4 - argument (for example an integer, string or double)
    299: .  arg5 - argument (for example an integer, string or double)
    300: -  arg6 - argument (for example an integer, string or double)

    302:   Level: beginner

    304:    Notes:
    305:     Once the error handler is called the calling function is then returned from with the given error code.

    307:     There are also versions for 4, 5, 6 and 7 arguments.

    309:    Experienced users can set the error handler with PetscPushErrorHandler().

    311: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    312: M*/
    313: #define SETERRQ6(comm,ierr,s,a1,a2,a3,a4,a5,a6) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)

    315: /*MC
    316:    SETERRQ7 - Macro that is called when an error has been detected,

    318:    Synopsis:
    319: #include <petscsys.h>
    320:    PetscErrorCode SETERRQ7(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4,arg5,arg6,arg7)

    322:    Collective

    324:    Input Parameters:
    325: +  comm - A communicator, so that the error can be collective
    326: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    327: .  message - error message in the printf format
    328: .  arg1 - argument (for example an integer, string or double)
    329: .  arg2 - argument (for example an integer, string or double)
    330: .  arg3 - argument (for example an integer, string or double)
    331: .  arg4 - argument (for example an integer, string or double)
    332: .  arg5 - argument (for example an integer, string or double)
    333: .  arg6 - argument (for example an integer, string or double)
    334: -  arg7 - argument (for example an integer, string or double)

    336:   Level: beginner

    338:    Notes:
    339:     Once the error handler is called the calling function is then returned from with the given error code.

    341:     There are also versions for 4, 5, 6 and 7 arguments.

    343:    Experienced users can set the error handler with PetscPushErrorHandler().

    345: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    346: M*/
    347: #define SETERRQ7(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)

    349: /*MC
    350:    SETERRQ8 - Macro that is called when an error has been detected,

    352:    Synopsis:
    353: #include <petscsys.h>
    354:    PetscErrorCode SETERRQ8(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8)

    356:    Collective

    358:    Input Parameters:
    359: +  comm - A communicator, so that the error can be collective
    360: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    361: .  message - error message in the printf format
    362: .  arg1 - argument (for example an integer, string or double)
    363: .  arg2 - argument (for example an integer, string or double)
    364: .  arg3 - argument (for example an integer, string or double)
    365: .  arg4 - argument (for example an integer, string or double)
    366: .  arg5 - argument (for example an integer, string or double)
    367: .  arg6 - argument (for example an integer, string or double)
    368: .  arg7 - argument (for example an integer, string or double)
    369: -  arg8 - argument (for example an integer, string or double)

    371:   Level: beginner

    373:    Notes:
    374:     Once the error handler is called the calling function is then returned from with the given error code.

    376:     There are also versions for 4, 5, 6 and 7 arguments.

    378:    Experienced users can set the error handler with PetscPushErrorHandler().

    380: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    381: M*/
    382: #define SETERRQ8(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7,a8) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8)

    384: /*MC
    385:    SETERRQ9 - Macro that is called when an error has been detected,

    387:    Synopsis:
    388: #include <petscsys.h>
    389:    PetscErrorCode SETERRQ9(MPI_Comm comm,PetscErrorCode ierr,char *formatmessage,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9)

    391:    Collective

    393:    Input Parameters:
    394: +  comm - A communicator, so that the error can be collective
    395: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    396: .  message - error message in the printf format
    397: .  arg1 - argument (for example an integer, string or double)
    398: .  arg2 - argument (for example an integer, string or double)
    399: .  arg3 - argument (for example an integer, string or double)
    400: .  arg4 - argument (for example an integer, string or double)
    401: .  arg5 - argument (for example an integer, string or double)
    402: .  arg6 - argument (for example an integer, string or double)
    403: .  arg7 - argument (for example an integer, string or double)
    404: .  arg8 - argument (for example an integer, string or double)
    405: -  arg9 - argument (for example an integer, string or double)

    407:   Level: beginner

    409:    Notes:
    410:     Once the error handler is called the calling function is then returned from with the given error code.

    412:     There are also versions for 0 to 9 arguments.

    414:    Experienced users can set the error handler with PetscPushErrorHandler().

    416: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    417: M*/
    418: #define SETERRQ9(comm,ierr,s,a1,a2,a3,a4,a5,a6,a7,a8,a9) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8,a9)

    420: /*MC
    421:    SETERRABORT - Macro that can be called when an error has been detected,

    423:    Synopsis:
    424: #include <petscsys.h>
    425:    PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode ierr,char *message)

    427:    Collective

    429:    Input Parameters:
    430: +  comm - A communicator, so that the error can be collective
    431: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h
    432: -  message - error message in the printf format

    434:   Level: beginner

    436:    Notes:
    437:     This function just calls MPI_Abort().

    439: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
    440: M*/
    441: #define SETERRABORT(comm,ierr,s) do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,ierr);} while (0)

    443: /*MC
    444:    CHKERRQ - Checks error code returned from PETSc function, if non-zero it calls the error handler and then returns. Use CHKERRMPI() for checking errors from MPI calls

    446:    Synopsis:
    447: #include <petscsys.h>
    448:    PetscErrorCode CHKERRQ(PetscErrorCode ierr)

    450:    Not Collective

    452:    Input Parameters:
    453: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

    455:   Level: beginner

    457:    Notes:
    458:     Once the error handler is called the calling function is then returned from with the given error code.

    460:     Experienced users can set the error handler with PetscPushErrorHandler().

    462:     CHKERRQ(ierr) is fundamentally a macro replacement for
    463:          if (ierr) return(PetscError(...,ierr,...));

    465:     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
    466:     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
    467:     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
    468:     you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
    469:          if (ierr) {PetscError(....); return(YourReturnType);}
    470:     where you may pass back a NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
    471:     MPI_Abort() returned immediately.

    473:    Fortran Notes:
    474:       CHKERRQ() may be called from Fortran subroutines but CHKERRA() must be called from the
    475:       Fortran main program.

    477: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
    478: M*/
    479: #define CHKERRQ(ierr)          do {PetscErrorCode ierr__ = (ierr); if (PetscUnlikely(ierr__)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr__,PETSC_ERROR_REPEAT," ");} while (0)
    480: #define CHKERRV(ierr)          do {PetscErrorCode ierr__ = (ierr); if (PetscUnlikely(ierr__)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr__,PETSC_ERROR_REPEAT," ");return;}} while (0)

    482: /*MC
    483:    CHKERRABORT - Checks error code returned from PETSc function. If non-zero it aborts immediately.

    485:    Synopsis:
    486: #include <petscsys.h>
    487:    PetscErrorCode CHKERRABORT(MPI_Comm comm,PetscErrorCode ierr)

    489:    Not Collective

    491:    Input Parameters:
    492: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

    494:   Level: intermediate

    496: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(), SETERRABORT(), CHKERRMPI()
    497: M*/
    498: #define CHKERRABORT(comm,ierr) do {PetscErrorCode ierr__ = (ierr); if (PetscUnlikely(ierr__)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr__,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,ierr);}} while (0)
    499: #define CHKERRCONTINUE(ierr)   do {PetscErrorCode ierr__ = (ierr); if (PetscUnlikely(ierr__)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr__,PETSC_ERROR_REPEAT," ");}} while (0)

    501: PETSC_EXTERN PetscErrorCode PetscAbortFindSourceFile_Private(const char*,PetscInt*);
    502: PETSC_EXTERN PetscBool petscwaitonerrorflg;
    503: PETSC_EXTERN PetscBool petscindebugger;

    505: /*MC
    506:    PETSCABORT - Call MPI_Abort with an informative error code

    508:    Synopsis:
    509: #include <petscsys.h>
    510:    PETSCABORT(MPI_Comm comm, PetscErrorCode ierr)

    512:    Collective

    514:    Input Parameters:
    515: +  comm - A communicator, so that the error can be collective
    516: -  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

    518:    Level: advanced

    520:    Notes:
    521:    We pass MPI_Abort() an error code of format XX_YYYY_ZZZ, where XX, YYYY are an index and line number of the file
    522:    where PETSCABORT is called, respectively. ZZZ is the PETSc error code.

    524:    If XX is zero, this means that the call was made in the routine main().
    525:    If XX is one, that means 1) the file is not in PETSc (it may be in users code); OR 2) the file is in PETSc but PetscAbortSourceFiles[]
    526:      is out of date. PETSc developers have to update it.
    527:    Otherwise, look up the value of XX in the table PetscAbortSourceFiles[] in src/sys/error/err.c to map XX back to the source file where the PETSCABORT() was called.

    529:    If the option -start_in_debugger was used then this calls abort() to stop the program in the debugger.

    531: M*/
    532: #define PETSCABORT(comm,ierr)  \
    533:    do {                                                               \
    534:       PetscInt       idx = 0;                                         \
    535:       PetscMPIInt    errcode;                                         \
    536:       PetscAbortFindSourceFile_Private(__FILE__,&idx);                \
    537:       errcode = (PetscMPIInt)(0*idx*10000000 + 0*__LINE__*1000 + ierr);   \
    538:       if (petscwaitonerrorflg) PetscSleep(1000);                      \
    539:       if (petscindebugger) abort();                                   \
    540:       else MPI_Abort(comm,errcode);                                   \
    541:    } while (0)

    543: /*MC
    544:    CHKERRMPI - Checks error code returned from MPI calls, if non-zero it calls the error handler and then returns

    546:    Synopsis:
    547: #include <petscsys.h>
    548:    PetscErrorCode CHKERRMPI(PetscErrorCode ierr)

    550:    Not Collective

    552:    Input Parameters:
    553: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

    555:   Level: intermediate

    557:    Notes:
    558:     Always returns the error code PETSC_ERR_MPI; the MPI error code and string are embedded in the string error message

    560: .seealso: CHKERRQ(), PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(), SETERRMPI(), SETERRABORT(), CHKERRABORT()
    561: M*/
    562: #define CHKERRMPI(ierr) \
    563: do { \
    564:   PetscErrorCode _7_errorcode = (ierr); \
    565:   if (PetscUnlikely(_7_errorcode)) { \
    566:     char _7_errorstring[MPI_MAX_ERROR_STRING]; \
    567:     PetscMPIInt _7_resultlen; \
    568:     MPI_Error_string(_7_errorcode,(char*)_7_errorstring,&_7_resultlen); (void)_7_resultlen; \
    569:     SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_MPI,"MPI error %d %s",(int)_7_errorcode,_7_errorstring); \
    570:   } \
    571: } while (0)

    573: #ifdef PETSC_CLANGUAGE_CXX

    575: /*MC
    576:    CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception

    578:    Synopsis:
    579: #include <petscsys.h>
    580:    void CHKERRXX(PetscErrorCode ierr)

    582:    Not Collective

    584:    Input Parameters:
    585: .  ierr - nonzero error code, see the list of standard error codes in include/petscerror.h

    587:   Level: beginner

    589:    Notes:
    590:     Once the error handler throws a ??? exception.

    592:     You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
    593:     or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.

    595: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
    596: M*/
    597: #define CHKERRXX(ierr)  do {if (PetscUnlikely(ierr)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,ierr,PETSC_ERROR_IN_CXX,0);}} while (0)

    599: #endif

    601: #if defined(PETSC_HAVE_CUDA)
    602: #include <cusolverDn.h>
    603: #include <cusolverSp.h>
    604: PETSC_EXTERN const char* PetscCUSolverGetErrorName(cusolverStatus_t);
    605: #define CHKERRCUSOLVER(stat)                       \
    606:   do {                 \
    607:    if (PetscUnlikely(stat)) { \
    608:      const char *name = PetscCUSolverGetErrorName(stat);                     \
    609:      if ((stat == CUSOLVER_STATUS_NOT_INITIALIZED) || (stat == CUSOLVER_STATUS_ALLOC_FAILED) || (stat == CUSOLVER_STATUS_INTERNAL_ERROR)) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_GPU_RESOURCE,"cuSolver error %d (%s). This indicates the GPU has run out resources",(int)stat,name); \
    610:      else SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_GPU,"cuSolver error %d (%s)",(int)stat,name); \
    611:    } \
    612: } while (0)
    613: #endif

    615: /* TODO: SEK:  Need to figure out the hipsolver issues */
    616: #if defined(PETSC_HAVE_HIP)
    617: #define CHKERRHIPSOLVER(err) do {if (PetscUnlikely(err)) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"HIPSOLVER error %d",err);} while (0)
    618: #endif
    619: /*MC
    620:    CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected

    622:    Synopsis:
    623: #include <petscsys.h>
    624:    CHKMEMQ;

    626:    Not Collective

    628:   Level: beginner

    630:    Notes:
    631:     We highly recommend using Valgrind https://petsc.org/release/faq/#valgrind or for NVIDIA CUDA systems
    632:     https://docs.nvidia.com/cuda/cuda-memcheck/index.html for finding memory problems. The ``CHKMEMQ`` macro is useful on systems that
    633:     do not have valgrind, but is not as good as valgrind or cuda-memcheck.

    635:     Must run with the option -malloc_debug (-malloc_test in debug mode; or if PetscMallocSetDebug() called) to enable this option

    637:     Once the error handler is called the calling function is then returned from with the given error code.

    639:     By defaults prints location where memory that is corrupted was allocated.

    641:     Use CHKMEMA for functions that return void

    643: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
    644:           PetscMallocValidate()
    645: M*/
    646: #define CHKMEMQ do {PetscErrorCode _7_PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while (0)

    648: #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__)

    650: /*E
    651:   PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers

    653:   Level: advanced

    655:   PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated

    657:   Developer Notes:
    658:     This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler()

    660: .seealso: PetscError(), SETERRXX()
    661: E*/
    662: typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;

    664: #if defined(__clang_analyzer__)
    665: __attribute__((analyzer_noreturn))
    666: #endif
    667: PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...);

    669: PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
    670: PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
    671: PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    672: PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    673: PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    674: PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    675: PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    676: PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    677: PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
    678: PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*);
    679: PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
    680: PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*);
    681: PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
    682: PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);
    684: PETSC_EXTERN void PetscSignalSegvCheckPointerOrMpi(void);
    685: PETSC_DEPRECATED_FUNCTION("Use PetscSignalSegvCheckPointerOrMpi() (since version 3.13)") PETSC_STATIC_INLINE void PetscSignalSegvCheckPointer(void) {PetscSignalSegvCheckPointerOrMpi();}

    687: /*MC
    688:     PetscErrorPrintf - Prints error messages.

    690:    Synopsis:
    691: #include <petscsys.h>
    692:      PetscErrorCode (*PetscErrorPrintf)(const char format[],...);

    694:     Not Collective

    696:     Input Parameters:
    697: .   format - the usual printf() format string

    699:    Options Database Keys:
    700: +    -error_output_stdout - cause error messages to be printed to stdout instead of the  (default) stderr
    701: -    -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.)

    703:    Notes:
    704:     Use
    705: $     PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
    706: $                        error is handled.) and
    707: $     PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function

    709:           Use
    710:      PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
    711:      PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file.

    713:           Use
    714:       PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print

    716:    Level: developer

    718:     Fortran Note:
    719:     This routine is not supported in Fortran.

    722: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscPushErrorHandler(), PetscVFPrintf(), PetscHelpPrintf()
    723: M*/
    724: PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...);

    726: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
    727: PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
    728: PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
    729: PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);
    730: PETSC_EXTERN PetscErrorCode PetscDetermineInitialFPTrap(void);

    732: /*
    733:       Allows the code to build a stack frame as it runs
    734: */

    736: #define PETSCSTACKSIZE 64

    738: typedef struct  {
    739:   const char      *function[PETSCSTACKSIZE];
    740:   const char      *file[PETSCSTACKSIZE];
    741:         int       line[PETSCSTACKSIZE];
    742:         PetscBool petscroutine[PETSCSTACKSIZE];
    743:         int       currentsize;
    744:         int       hotdepth;
    745: } PetscStack;

    747: PETSC_EXTERN PetscStack *petscstack;

    749: PetscErrorCode  PetscStackCopy(PetscStack*,PetscStack*);
    750: PetscErrorCode  PetscStackPrint(PetscStack *,FILE*);
    751: #if defined(PETSC_SERIALIZE_FUNCTIONS)
    752: #include <petsc/private/petscfptimpl.h>
    753: /*
    754:    Registers the current function into the global function pointer to function name table

    756:    Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
    757: */
    758: #define PetscRegister__FUNCT__() do { \
    759:   static PetscBool __chked = PETSC_FALSE; \
    760:   if (!__chked) {\
    761:   void *ptr; PetscDLSym(NULL,PETSC_FUNCTION_NAME,&ptr);\
    762:   __chked = PETSC_TRUE;\
    763:   }} while (0)
    764: #else
    765: #define PetscRegister__FUNCT__()
    766: #endif

    768: #if defined(PETSC_USE_DEBUG)
    769: PETSC_STATIC_INLINE PetscBool PetscStackActive(void)
    770: {
    771:   return(petscstack ? PETSC_TRUE : PETSC_FALSE);
    772: }

    774: /* Stack handling is based on the following two "NoCheck" macros.  These should only be called directly by other error
    775:  * handling macros.  We record the line of the call, which may or may not be the location of the definition.  But is at
    776:  * least more useful than "unknown" because it can distinguish multiple calls from the same function.
    777:  */

    779: #define PetscStackPushNoCheck(funct,petsc_routine,hot)                        \
    780:   do {                                                                        \
    781:     PetscStackSAWsTakeAccess();                                                \
    782:     if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {         \
    783:       petscstack->function[petscstack->currentsize]  = funct;               \
    784:       petscstack->file[petscstack->currentsize]      = __FILE__;            \
    785:       petscstack->line[petscstack->currentsize]      = __LINE__;            \
    786:       petscstack->petscroutine[petscstack->currentsize] = petsc_routine;    \
    787:       petscstack->currentsize++;                                             \
    788:     }                                                                         \
    789:     if (petscstack) {                                                        \
    790:       petscstack->hotdepth += (hot || petscstack->hotdepth);                \
    791:     }                                                                         \
    792:     PetscStackSAWsGrantAccess();                                               \
    793:   } while (0)

    795: #define PetscStackPopNoCheck                                            \
    796:   do {                                                                  \
    797:     PetscStackSAWsTakeAccess();                                          \
    798:     if (petscstack && petscstack->currentsize > 0) {                  \
    799:       petscstack->currentsize--;                                       \
    800:       petscstack->function[petscstack->currentsize]  = NULL;             \
    801:       petscstack->file[petscstack->currentsize]      = NULL;             \
    802:       petscstack->line[petscstack->currentsize]      = 0;             \
    803:       petscstack->petscroutine[petscstack->currentsize] = PETSC_FALSE;\
    804:     }                                                                   \
    805:     if (petscstack) {                                                  \
    806:       petscstack->hotdepth = PetscMax(petscstack->hotdepth-1,0);      \
    807:     }                                                                   \
    808:     PetscStackSAWsGrantAccess();                                         \
    809:   } while (0)

    811: /*MC
    813:       line of PETSc functions should be return(0);

    815:    Synopsis:
    816: #include <petscsys.h>

    819:    Not Collective

    821:    Usage:
    822: .vb
    823:      int something;

    826: .ve

    828:    Notes:

    831:      Not available in Fortran

    833:    Level: developer

    837: M*/
    839:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_FALSE); \
    840:     PetscRegister__FUNCT__();                                          \
    841:   } while (0)

    843: /*MC
    845:    performance-critical circumstances.  Use of this function allows for lighter profiling by default.

    847:    Synopsis:
    848: #include <petscsys.h>

    851:    Not Collective

    853:    Usage:
    854: .vb
    855:      int something;

    858: .ve

    860:    Notes:
    861:      Not available in Fortran

    863:    Level: developer

    867: M*/
    869:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_TRUE);  \
    870:     PetscRegister__FUNCT__();                                          \
    871:   } while (0)

    873: /*MC

    876:    Synopsis:
    877: #include <petscsys.h>

    880:    Not Collective

    882:    Usage:
    883: .vb
    884:      int something;

    887: .ve

    889:    Notes:
    890:       Final line of PETSc functions should be return(0) except for main().

    892:       Not available in Fortran

    895:       routine instead of as a PETSc library routine.

    897:    Level: intermediate

    901: M*/
    903:   do {                                                                  \
    904:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_FALSE,PETSC_FALSE); \
    905:     PetscRegister__FUNCT__();                                           \
    906:   } while (0)

    909: #define PetscStackPush(n) \
    910:   do {                                                                  \
    911:     PetscStackPushNoCheck(n,PETSC_FALSE,PETSC_FALSE);                   \
    912:     CHKMEMQ;                                                            \
    913:   } while (0)

    915: #define PetscStackPop                           \
    916:     do {                                        \
    917:       CHKMEMQ;                                  \
    918:       PetscStackPopNoCheck;                     \
    919:     } while (0)

    921: /*MC
    922:    PetscFunctionReturn - Last executable line of each PETSc function
    923:         used for error handling. Replaces return()

    925:    Synopsis:
    926: #include <petscsys.h>
    927:    void return(0);

    929:    Not Collective

    931:    Usage:
    932: .vb
    933:     ....
    934:      return(0);
    935:    }
    936: .ve

    938:    Notes:
    939:      Not available in Fortran

    941:    Level: developer

    945: M*/
    946: #define PetscFunctionReturn(a) \
    947:   do {                                                                \
    948:     PetscStackPopNoCheck;                                             \
    949:     return(a);} while (0)

    951: #define PetscFunctionReturnVoid() \
    952:   do {                                                                \
    953:     PetscStackPopNoCheck;                                             \
    954:     return;} while (0)

    956: #else

    958: PETSC_STATIC_INLINE PetscBool PetscStackActive(void) {return PETSC_FALSE;}
    959: #define PetscStackPushNoCheck(funct,petsc_routine,hot) do {} while (0)
    960: #define PetscStackPopNoCheck                           do {} while (0)
    964: #define PetscFunctionReturn(a)    return(a)
    965: #define PetscFunctionReturnVoid() return
    966: #define PetscStackPop             CHKMEMQ
    967: #define PetscStackPush(f)         CHKMEMQ

    969: #endif

    971: /*
    972:     PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.

    974:    Input Parameters:
    975: +   name - string that gives the name of the function being called
    976: -   routine - actual call to the routine, including and

    978:    Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes

    980:    Developer Note: this is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.

    984: */
    985: #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while (0)

    987: /*
    988:     PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack.

    990:    Input Parameters:
    991: +   func-  name of the routine
    992: -   args - arguments to the routine surrounded by ()

    994:    Notes:
    995:     This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not.

    997:    Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc.

    999: */
    1000: #define PetscStackCallStandard(func,args) do {                                                            \
    1001:     PetscErrorCode __ierr;                                                                                \
    1002:     PetscStackPush(#func);                                                                                \
    1003:     __func args;                                                                                   \
    1004:     PetscStackPop;                                                                                        \
    1005:     if (__ierr) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s(): error code %d",#func,(int)__ierr); \
    1006:   } while (0)

    1008: PETSC_EXTERN PetscErrorCode PetscStackCreate(void);
    1009: PETSC_EXTERN PetscErrorCode PetscStackView(FILE*);
    1010: PETSC_EXTERN PetscErrorCode PetscStackDestroy(void);

    1012: #endif