Actual source code: view.c
petsc-3.13.6 2020-09-29
Report Typos and Errors

      2:  #include <petsc/private/viewerimpl.h>

      4: PetscClassId PETSC_VIEWER_CLASSID;

      6: static PetscBool PetscViewerPackageInitialized = PETSC_FALSE;
      7: /*@C
      8:   PetscViewerFinalizePackage - This function destroys any global objects created in the Petsc viewers. It is
      9:   called from PetscFinalize().

     11:   Level: developer

     13: .seealso: PetscFinalize()
     14: @*/
     15: PetscErrorCode  PetscViewerFinalizePackage(void)
     16: {

     20:   if (Petsc_Viewer_keyval != MPI_KEYVAL_INVALID) {
     21:     MPI_Comm_free_keyval(&Petsc_Viewer_keyval);
     22:   }
     23:   if (Petsc_Viewer_Stdout_keyval != MPI_KEYVAL_INVALID) {
     24:     MPI_Comm_free_keyval(&Petsc_Viewer_Stdout_keyval);
     25:   }
     26:   if (Petsc_Viewer_Stderr_keyval != MPI_KEYVAL_INVALID) {
     27:     MPI_Comm_free_keyval(&Petsc_Viewer_Stderr_keyval);
     28:   }
     29:   if (Petsc_Viewer_Binary_keyval != MPI_KEYVAL_INVALID) {
     30:     MPI_Comm_free_keyval(&Petsc_Viewer_Binary_keyval);
     31:   }
     32:   if (Petsc_Viewer_Draw_keyval != MPI_KEYVAL_INVALID) {
     33:     MPI_Comm_free_keyval(&Petsc_Viewer_Draw_keyval);
     34:   }
     35: #if defined(PETSC_HAVE_HDF5)
     36:   if (Petsc_Viewer_HDF5_keyval != MPI_KEYVAL_INVALID) {
     37:     MPI_Comm_free_keyval(&Petsc_Viewer_HDF5_keyval);
     38:   }
     39: #endif
     40: #if defined(PETSC_USE_SOCKETVIEWER)
     41:   if (Petsc_Viewer_Socket_keyval != MPI_KEYVAL_INVALID) {
     42:     MPI_Comm_free_keyval(&Petsc_Viewer_Socket_keyval);
     43:   }
     44: #endif
     45:   PetscFunctionListDestroy(&PetscViewerList);
     46:   PetscViewerPackageInitialized = PETSC_FALSE;
     47:   PetscViewerRegisterAllCalled  = PETSC_FALSE;
     48:   return(0);
     49: }

     51: /*@C
     52:   PetscViewerInitializePackage - This function initializes everything in the main PetscViewer package.

     54:   Level: developer

     56: .seealso: PetscInitialize()
     57: @*/
     58: PetscErrorCode  PetscViewerInitializePackage(void)
     59: {
     60:   char           logList[256];
     61:   PetscBool      opt,pkg;

     65:   if (PetscViewerPackageInitialized) return(0);
     66:   PetscViewerPackageInitialized = PETSC_TRUE;
     67:   /* Register Classes */
     68:   PetscClassIdRegister("Viewer",&PETSC_VIEWER_CLASSID);
     69:   /* Register Constructors */
     70:   PetscViewerRegisterAll();
     71:   /* Process Info */
     72:   {
     73:     PetscClassId  classids[1];

     75:     classids[0] = PETSC_VIEWER_CLASSID;
     76:     PetscInfoProcessClass("viewer", 1, classids);
     77:   }
     78:   /* Process summary exclusions */
     79:   PetscOptionsGetString(NULL,NULL,"-log_exclude",logList,sizeof(logList),&opt);
     80:   if (opt) {
     81:     PetscStrInList("viewer",logList,',',&pkg);
     82:     if (pkg) {PetscLogEventExcludeClass(PETSC_VIEWER_CLASSID);}
     83:   }
     84: #if defined(PETSC_HAVE_MATHEMATICA)
     85:   PetscViewerMathematicaInitializePackage();
     86: #endif
     87:   /* Register package finalizer */
     88:   PetscRegisterFinalize(PetscViewerFinalizePackage);
     89:   return(0);
     90: }

     92: /*@
     93:    PetscViewerDestroy - Destroys a PetscViewer.

     95:    Collective on PetscViewer

     97:    Input Parameters:
     98: .  viewer - the PetscViewer to be destroyed.

    100:    Level: beginner

    102: .seealso: PetscViewerSocketOpen(), PetscViewerASCIIOpen(), PetscViewerCreate(), PetscViewerDrawOpen()

    104: @*/
    105: PetscErrorCode  PetscViewerDestroy(PetscViewer *viewer)
    106: {

    110:   if (!*viewer) return(0);

    113:   PetscViewerFlush(*viewer);
    114:   if (--((PetscObject)(*viewer))->refct > 0) {*viewer = NULL; return(0);}

    116:   PetscObjectSAWsViewOff((PetscObject)*viewer);
    117:   if ((*viewer)->ops->destroy) {
    118:     (*(*viewer)->ops->destroy)(*viewer);
    119:   }
    120:   PetscHeaderDestroy(viewer);
    121:   return(0);
    122: }

    124: /*@C
    125:    PetscViewerAndFormatCreate - Creates a PetscViewerAndFormat struct.

    127:    Collective on PetscViewer

    129:    Input Parameters:
    130: +  viewer - the viewer
    131: -  format - the format

    133:    Output Parameter:
    134: .   vf - viewer and format object

    136:    Notes:
    137:     This increases the reference count of the viewer so you can destroy the viewer object after this call
    138:    Level: developer

    140:    This is used as the context variable for many of the TS, SNES, and KSP monitor functions

    142: .seealso: PetscViewerSocketOpen(), PetscViewerASCIIOpen(), PetscViewerCreate(), PetscViewerDrawOpen(), PetscViewerAndFormatDestroy()

    144: @*/
    145: PetscErrorCode  PetscViewerAndFormatCreate(PetscViewer viewer, PetscViewerFormat format,PetscViewerAndFormat **vf)
    146: {

    150:   PetscObjectReference((PetscObject)viewer);
    151:   PetscNew(vf);
    152:   (*vf)->viewer = viewer;
    153:   (*vf)->format = format;
    154:   return(0);
    155: }

    158: /*@C
    159:    PetscViewerAndFormatDestroy - Destroys a PetscViewerAndFormat struct.

    161:    Collective on PetscViewer

    163:    Input Parameters:
    164: .  viewer - the PetscViewerAndFormat to be destroyed.

    166:    Level: developer

    168: .seealso: PetscViewerSocketOpen(), PetscViewerASCIIOpen(), PetscViewerCreate(), PetscViewerDrawOpen(), PetscViewerAndFormatCreate()

    170: @*/
    171: PetscErrorCode  PetscViewerAndFormatDestroy(PetscViewerAndFormat **vf)
    172: {

    176:   PetscViewerDestroy(&(*vf)->viewer);
    177:   PetscFree(*vf);
    178:   return(0);
    179: }

    181: /*@C
    182:    PetscViewerGetType - Returns the type of a PetscViewer.

    184:    Not Collective

    186:    Input Parameter:
    187: .   viewer - the PetscViewer

    189:    Output Parameter:
    190: .  type - PetscViewer type (see below)

    192:    Available Types Include:
    193: +  PETSCVIEWERSOCKET - Socket PetscViewer
    194: .  PETSCVIEWERASCII - ASCII PetscViewer
    195: .  PETSCVIEWERBINARY - binary file PetscViewer
    196: .  PETSCVIEWERSTRING - string PetscViewer
    197: -  PETSCVIEWERDRAW - drawing PetscViewer

    199:    Level: intermediate

    201:    Note:
    202:    See include/petscviewer.h for a complete list of PetscViewers.

    204:    PetscViewerType is actually a string

    206: .seealso: PetscViewerCreate(), PetscViewerSetType(), PetscViewerType

    208: @*/
    209: PetscErrorCode  PetscViewerGetType(PetscViewer viewer,PetscViewerType *type)
    210: {
    214:   *type = ((PetscObject)viewer)->type_name;
    215:   return(0);
    216: }

    218: /*@C
    219:    PetscViewerSetOptionsPrefix - Sets the prefix used for searching for all
    220:    PetscViewer options in the database.

    222:    Logically Collective on PetscViewer

    224:    Input Parameter:
    225: +  viewer - the PetscViewer context
    226: -  prefix - the prefix to prepend to all option names

    228:    Notes:
    229:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    230:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    232:    Level: advanced

    234: .seealso: PetscViewerSetFromOptions()
    235: @*/
    236: PetscErrorCode  PetscViewerSetOptionsPrefix(PetscViewer viewer,const char prefix[])
    237: {

    242:   PetscObjectSetOptionsPrefix((PetscObject)viewer,prefix);
    243:   return(0);
    244: }

    246: /*@C
    247:    PetscViewerAppendOptionsPrefix - Appends to the prefix used for searching for all
    248:    PetscViewer options in the database.

    250:    Logically Collective on PetscViewer

    252:    Input Parameters:
    253: +  viewer - the PetscViewer context
    254: -  prefix - the prefix to prepend to all option names

    256:    Notes:
    257:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    258:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    260:    Level: advanced

    262: .seealso: PetscViewerGetOptionsPrefix()
    263: @*/
    264: PetscErrorCode  PetscViewerAppendOptionsPrefix(PetscViewer viewer,const char prefix[])
    265: {

    270:   PetscObjectAppendOptionsPrefix((PetscObject)viewer,prefix);
    271:   return(0);
    272: }

    274: /*@C
    275:    PetscViewerGetOptionsPrefix - Sets the prefix used for searching for all
    276:    PetscViewer options in the database.

    278:    Not Collective

    280:    Input Parameter:
    281: .  viewer - the PetscViewer context

    283:    Output Parameter:
    284: .  prefix - pointer to the prefix string used

    286:    Notes:
    287:     On the fortran side, the user should pass in a string 'prefix' of
    288:    sufficient length to hold the prefix.

    290:    Level: advanced

    292: .seealso: PetscViewerAppendOptionsPrefix()
    293: @*/
    294: PetscErrorCode  PetscViewerGetOptionsPrefix(PetscViewer viewer,const char *prefix[])
    295: {

    300:   PetscObjectGetOptionsPrefix((PetscObject)viewer,prefix);
    301:   return(0);
    302: }

    304: /*@
    305:    PetscViewerSetUp - Sets up the internal viewer data structures for the later use.

    307:    Collective on PetscViewer

    309:    Input Parameters:
    310: .  viewer - the PetscViewer context

    312:    Notes:
    313:    For basic use of the PetscViewer classes the user need not explicitly call
    314:    PetscViewerSetUp(), since these actions will happen automatically.

    316:    Level: advanced

    318: .seealso: PetscViewerCreate(), PetscViewerDestroy()
    319: @*/
    320: PetscErrorCode  PetscViewerSetUp(PetscViewer viewer)
    321: {

    326:   if (viewer->setupcalled) return(0);
    327:   if (viewer->ops->setup) {
    328:     (*viewer->ops->setup)(viewer);
    329:   }
    330:   viewer->setupcalled = PETSC_TRUE;
    331:   return(0);
    332: }

    334: /*@C
    335:    PetscViewerViewFromOptions - View from Options

    337:    Collective on PetscViewer

    339:    Input Parameters:
    340: +  A - the PetscViewer context
    341: .  obj - Optional object
    342: -  name - command line option

    344:    Level: intermediate
    345: .seealso:  PetscViewer, PetscViewerView, PetscObjectViewFromOptions(), PetscViewerCreate()
    346: @*/
    347: PetscErrorCode  PetscViewerViewFromOptions(PetscViewer A,PetscObject obj,const char name[])
    348: {

    353:   PetscObjectViewFromOptions((PetscObject)A,obj,name);
    354:   return(0);
    355: }

    357: /*@C
    358:    PetscViewerView - Visualizes a viewer object.

    360:    Collective on PetscViewer

    362:    Input Parameters:
    363: +  v - the viewer to be viewed
    364: -  viewer - visualization context

    366:   Notes:
    367:   The available visualization contexts include
    368: +    PETSC_VIEWER_STDOUT_SELF - standard output (default)
    369: .    PETSC_VIEWER_STDOUT_WORLD - synchronized standard
    370:         output where only the first processor opens
    371:         the file.  All other processors send their
    372:         data to the first processor to print.
    373: -     PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure

    375:    Level: beginner

    377: .seealso: PetscViewerPushFormat(), PetscViewerASCIIOpen(), PetscViewerDrawOpen(),
    378:           PetscViewerSocketOpen(), PetscViewerBinaryOpen(), PetscViewerLoad()
    379: @*/
    380: PetscErrorCode  PetscViewerView(PetscViewer v,PetscViewer viewer)
    381: {
    382:   PetscErrorCode    ierr;
    383:   PetscBool         iascii;
    384:   PetscViewerFormat format;
    385: #if defined(PETSC_HAVE_SAWS)
    386:   PetscBool         issaws;
    387: #endif

    392:   if (!viewer) {
    393:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)v),&viewer);
    394:   }

    398:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
    399: #if defined(PETSC_HAVE_SAWS)
    400:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERSAWS,&issaws);
    401: #endif
    402:   if (iascii) {
    403:     PetscViewerGetFormat(viewer,&format);
    404:     PetscObjectPrintClassNamePrefixType((PetscObject)v,viewer);
    405:     if (format == PETSC_VIEWER_DEFAULT || format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
    406:       if (v->format) {
    407:         PetscViewerASCIIPrintf(viewer,"  Viewer format = %s\n",PetscViewerFormats[v->format]);
    408:       }
    409:       PetscViewerASCIIPushTab(viewer);
    410:       if (v->ops->view) {
    411:         (*v->ops->view)(v,viewer);
    412:       }
    413:       PetscViewerASCIIPopTab(viewer);
    414:     }
    415: #if defined(PETSC_HAVE_SAWS)
    416:   } else if (issaws) {
    417:     if (!((PetscObject)v)->amsmem) {
    418:       PetscObjectViewSAWs((PetscObject)v,viewer);
    419:       if (v->ops->view) {
    420:         (*v->ops->view)(v,viewer);
    421:       }
    422:     }
    423: #endif
    424:   }
    425:   return(0);
    426: }

    428: /*@C
    429:    PetscViewerRead - Reads data from a PetscViewer

    431:    Collective

    433:    Input Parameters:
    434: +  viewer   - The viewer
    435: .  data     - Location to write the data
    436: .  num      - Number of items of data to read
    437: -  datatype - Type of data to read

    439:    Output Parameters:
    440: .  count - number of items of data actually read, or NULL

    442:    Notes:
    443:    If datatype is PETSC_STRING and num is negative, reads until a newline character is found,
    444:    until a maximum of (-num - 1) chars.

    446:    Level: beginner

    448: .seealso: PetscViewerASCIIOpen(), PetscViewerPushFormat(), PetscViewerDestroy(),
    449:           VecView(), MatView(), VecLoad(), MatLoad(), PetscViewerBinaryGetDescriptor(),
    450:           PetscViewerBinaryGetInfoPointer(), PetscFileMode, PetscViewer
    451: @*/
    452: PetscErrorCode  PetscViewerRead(PetscViewer viewer, void *data, PetscInt num, PetscInt *count, PetscDataType dtype)
    453: {

    458:   if (dtype == PETSC_STRING) {
    459:     PetscInt c, i = 0, cnt;
    460:     char *s = (char *)data;
    461:     if (num >= 0) {
    462:       for (c = 0; c < num; c++) {
    463:         /* Skip leading whitespaces */
    464:         do {(*viewer->ops->read)(viewer, &(s[i]), 1, &cnt, PETSC_CHAR); if (!cnt) break;}
    465:         while (s[i]=='\n' || s[i]=='\t' || s[i]==' ' || s[i]=='\0' || s[i]=='\v' || s[i]=='\f' || s[i]=='\r');
    466:         i++;
    467:         /* Read strings one char at a time */
    468:         do {(*viewer->ops->read)(viewer, &(s[i++]), 1, &cnt, PETSC_CHAR); if (!cnt) break;}
    469:         while (s[i-1]!='\n' && s[i-1]!='\t' && s[i-1]!=' ' && s[i-1]!='\0' && s[i-1]!='\v' && s[i-1]!='\f' && s[i-1]!='\r');
    470:         /* Terminate final string */
    471:         if (c == num-1) s[i-1] = '\0';
    472:       }
    473:     } else {
    474:       /* Read until a \n is encountered (-num is the max size allowed) */
    475:       do {(*viewer->ops->read)(viewer, &(s[i++]), 1, &cnt, PETSC_CHAR); if (i == -num || !cnt) break;}
    476:       while (s[i-1]!='\n');
    477:       /* Terminate final string */
    478:       s[i-1] = '\0';
    479:       c      = i;
    480:     }
    481:     if (count) *count = c;
    482:     else if (c < num) SETERRQ2(PetscObjectComm((PetscObject) viewer), PETSC_ERR_FILE_READ, "Insufficient data, only read %D < %D strings", c, num);
    483:   } else {
    484:     (*viewer->ops->read)(viewer, data, num, count, dtype);
    485:   }
    486:   return(0);
    487: }

    489: /*@
    490:    PetscViewerReadable - Return a flag whether the viewer can be read from

    492:    Not Collective

    494:    Input Parameters:
    495: .  viewer - the PetscViewer context

    497:    Output Parameters:
    498: .  flg - PETSC_TRUE if the viewer is readable, PETSC_FALSE otherwise

    500:    Notes:
    501:    PETSC_TRUE means that viewer's PetscViewerType supports reading (this holds e.g. for PETSCVIEWERBINARY)
    502:    and viewer is in a mode allowing reading, i.e. PetscViewerFileGetMode()
    503:    returns one of FILE_MODE_READ, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE.

    505:    Level: intermediate

    507: .seealso: PetscViewerWritable(), PetscViewerCheckReadable(), PetscViewerCreate(), PetscViewerFileSetMode(), PetscViewerFileSetType()
    508: @*/
    509: PetscErrorCode  PetscViewerReadable(PetscViewer viewer, PetscBool *flg)
    510: {
    511:   PetscErrorCode    ierr;
    512:   PetscFileMode     mode;
    513:   PetscErrorCode    (*f)(PetscViewer,PetscFileMode*) = NULL;

    518:   PetscObjectQueryFunction((PetscObject)viewer, "PetscViewerFileGetMode_C", &f);
    519:   *flg = PETSC_FALSE;
    520:   if (!f) return(0);
    521:   (*f)(viewer, &mode);
    522:   switch (mode) {
    523:     case FILE_MODE_READ:
    524:     case FILE_MODE_UPDATE:
    525:     case FILE_MODE_APPEND_UPDATE:
    526:       *flg = PETSC_TRUE;
    527:     default: break;
    528:   }
    529:   return(0);
    530: }

    532: /*@
    533:    PetscViewerWritable - Return a flag whether the viewer can be written to

    535:    Not Collective

    537:    Input Parameters:
    538: .  viewer - the PetscViewer context

    540:    Output Parameters:
    541: .  flg - PETSC_TRUE if the viewer is writable, PETSC_FALSE otherwise

    543:    Notes:
    544:    PETSC_TRUE means viewer is in a mode allowing writing, i.e. PetscViewerFileGetMode()
    545:    returns one of FILE_MODE_WRITE, FILE_MODE_APPEND, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE.

    547:    Level: intermediate

    549: .seealso: PetscViewerReadable(), PetscViewerCheckWritable(), PetscViewerCreate(), PetscViewerFileSetMode(), PetscViewerFileSetType()
    550: @*/
    551: PetscErrorCode  PetscViewerWritable(PetscViewer viewer, PetscBool *flg)
    552: {
    553:   PetscErrorCode    ierr;
    554:   PetscFileMode     mode;
    555:   PetscErrorCode    (*f)(PetscViewer,PetscFileMode*) = NULL;

    560:   PetscObjectQueryFunction((PetscObject)viewer, "PetscViewerFileGetMode_C", &f);
    561:   *flg = PETSC_TRUE;
    562:   if (!f) return(0);
    563:   (*f)(viewer, &mode);
    564:   if (mode == FILE_MODE_READ) *flg = PETSC_FALSE;
    565:   return(0);
    566: }

    568: /*@
    569:    PetscViewerCheckReadable - Check whether the viewer can be read from

    571:    Collective

    573:    Input Parameters:
    574: .  viewer - the PetscViewer context

    576:    Level: intermediate

    578: .seealso: PetscViewerReadable(), PetscViewerCheckWritable(), PetscViewerCreate(), PetscViewerFileSetMode(), PetscViewerFileSetType()
    579: @*/
    580: PetscErrorCode  PetscViewerCheckReadable(PetscViewer viewer)
    581: {
    582:   PetscBool         flg;
    583:   PetscErrorCode    ierr;

    587:   PetscViewerReadable(viewer, &flg);
    588:   if (!flg) SETERRQ(PetscObjectComm((PetscObject)viewer), PETSC_ERR_SUP, "Viewer doesn't support reading, or is not in reading mode (FILE_MODE_READ, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE)");
    589:   return(0);
    590: }

    592: /*@
    593:    PetscViewerCheckWritable - Check whether the viewer can be written to

    595:    Collective

    597:    Input Parameters:
    598: .  viewer - the PetscViewer context

    600:    Level: intermediate

    602: .seealso: PetscViewerWritable(), PetscViewerCheckReadable(), PetscViewerCreate(), PetscViewerFileSetMode(), PetscViewerFileSetType()
    603: @*/
    604: PetscErrorCode  PetscViewerCheckWritable(PetscViewer viewer)
    605: {
    606:   PetscBool         flg;
    607:   PetscErrorCode    ierr;

    611:   PetscViewerWritable(viewer, &flg);
    612:   if (!flg) SETERRQ(PetscObjectComm((PetscObject)viewer), PETSC_ERR_SUP, "Viewer doesn't support writing, or is in FILE_MODE_READ mode");
    613:   return(0);
    614: }