Actual source code: view.c


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

  5: PetscClassId PETSC_VIEWER_CLASSID;

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

 12:   Level: developer

 14: .seealso: [](sec_viewers), `PetscFinalize()`
 15: @*/
 16: PetscErrorCode PetscViewerFinalizePackage(void)
 17: {
 18:   if (Petsc_Viewer_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_keyval);
 19:   if (Petsc_Viewer_Stdout_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_Stdout_keyval);
 20:   if (Petsc_Viewer_Stderr_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_Stderr_keyval);
 21:   if (Petsc_Viewer_Binary_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_Binary_keyval);
 22:   if (Petsc_Viewer_Draw_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_Draw_keyval);
 23: #if defined(PETSC_HAVE_HDF5)
 24:   if (Petsc_Viewer_HDF5_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_HDF5_keyval);
 25: #endif
 26: #if defined(PETSC_USE_SOCKETVIEWER)
 27:   if (Petsc_Viewer_Socket_keyval != MPI_KEYVAL_INVALID) MPI_Comm_free_keyval(&Petsc_Viewer_Socket_keyval);
 28: #endif
 29:   PetscFunctionListDestroy(&PetscViewerList);
 30:   PetscViewerPackageInitialized = PETSC_FALSE;
 31:   PetscViewerRegisterAllCalled  = PETSC_FALSE;
 32:   return 0;
 33: }

 35: /*@C
 36:   PetscViewerInitializePackage - This function initializes everything in the `PetscViewer` package.

 38:   Level: developer

 40: .seealso: [](sec_viewers), `PetscInitialize()`
 41: @*/
 42: PetscErrorCode PetscViewerInitializePackage(void)
 43: {
 44:   char      logList[256];
 45:   PetscBool opt, pkg;

 47:   if (PetscViewerPackageInitialized) return 0;
 48:   PetscViewerPackageInitialized = PETSC_TRUE;
 49:   /* Register Classes */
 50:   PetscClassIdRegister("Viewer", &PETSC_VIEWER_CLASSID);
 51:   /* Register Constructors */
 52:   PetscViewerRegisterAll();
 53:   /* Process Info */
 54:   {
 55:     PetscClassId classids[1];

 57:     classids[0] = PETSC_VIEWER_CLASSID;
 58:     PetscInfoProcessClass("viewer", 1, classids);
 59:   }
 60:   /* Process summary exclusions */
 61:   PetscOptionsGetString(NULL, NULL, "-log_exclude", logList, sizeof(logList), &opt);
 62:   if (opt) {
 63:     PetscStrInList("viewer", logList, ',', &pkg);
 64:     if (pkg) PetscLogEventExcludeClass(PETSC_VIEWER_CLASSID);
 65:   }
 66: #if defined(PETSC_HAVE_MATHEMATICA)
 67:   PetscViewerMathematicaInitializePackage();
 68: #endif
 69:   /* Register package finalizer */
 70:   PetscRegisterFinalize(PetscViewerFinalizePackage);
 71:   return 0;
 72: }

 74: /*@
 75:    PetscViewerDestroy - Destroys a `PetscViewer`.

 77:    Collective

 79:    Input Parameters:
 80: .  viewer - the `PetscViewer` to be destroyed.

 82:    Level: beginner

 84: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerCreate()`, `PetscViewerDrawOpen()`
 85: @*/
 86: PetscErrorCode PetscViewerDestroy(PetscViewer *viewer)
 87: {
 88:   if (!*viewer) return 0;

 91:   PetscViewerFlush(*viewer);
 92:   if (--((PetscObject)(*viewer))->refct > 0) {
 93:     *viewer = NULL;
 94:     return 0;
 95:   }

 97:   PetscObjectSAWsViewOff((PetscObject)*viewer);
 98:   if ((*viewer)->ops->destroy) (*(*viewer)->ops->destroy)(*viewer);
 99:   PetscHeaderDestroy(viewer);
100:   return 0;
101: }

103: /*@C
104:    PetscViewerAndFormatCreate - Creates a `PetscViewerAndFormat` struct.

106:    Collective

108:    Input Parameters:
109: +  viewer - the viewer
110: -  format - the format

112:    Output Parameter:
113: .   vf - viewer and format object

115:    Level: developer

117:    Notes:
118:    This increases the reference count of the viewer so you can destroy the viewer object after this call

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

122: .seealso: [](sec_viewers), `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerCreate()`, `PetscViewerDrawOpen()`, `PetscViewerAndFormatDestroy()`
123: @*/
124: PetscErrorCode PetscViewerAndFormatCreate(PetscViewer viewer, PetscViewerFormat format, PetscViewerAndFormat **vf)
125: {
126:   PetscObjectReference((PetscObject)viewer);
127:   PetscNew(vf);
128:   (*vf)->viewer = viewer;
129:   (*vf)->format = format;
130:   (*vf)->lg     = NULL;
131:   (*vf)->data   = NULL;
132:   return 0;
133: }

135: /*@C
136:    PetscViewerAndFormatDestroy - Destroys a `PetscViewerAndFormat` struct.

138:    Collective

140:    Input Parameters:
141: .  vf - the `PetscViewerAndFormat` to be destroyed.

143:    Level: developer

145: .seealso: [](sec_viewers), `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerCreate()`, `PetscViewerDrawOpen()`, `PetscViewerAndFormatCreate()`
146: @*/
147: PetscErrorCode PetscViewerAndFormatDestroy(PetscViewerAndFormat **vf)
148: {
149:   PetscViewerDestroy(&(*vf)->viewer);
150:   PetscDrawLGDestroy(&(*vf)->lg);
151:   PetscFree(*vf);
152:   return 0;
153: }

155: /*@C
156:    PetscViewerGetType - Returns the type of a `PetscViewer`.

158:    Not Collective

160:    Input Parameter:
161: .   viewer - the `PetscViewer`

163:    Output Parameter:
164: .  type - PetscViewer type (see below)

166:    Available Types Include:
167: +  `PETSCVIEWERSOCKET` - Socket PetscViewer
168: .  `PETSCVIEWERASCII` - ASCII PetscViewer
169: .  `PETSCVIEWERBINARY` - binary file PetscViewer
170: .  `PETSCVIEWERSTRING` - string PetscViewer
171: -  `PETSCVIEWERDRAW` - drawing PetscViewer

173:    Level: intermediate

175:    Note:
176:    See include/petscviewer.h for a complete list of `PetscViewer`s.

178:    `PetscViewerType` is actually a string

180: .seealso: [](sec_viewers), `PetscViewerType`, `PetscViewer`, `PetscViewerCreate()`, `PetscViewerSetType()`, `PetscViewerType`
181: @*/
182: PetscErrorCode PetscViewerGetType(PetscViewer viewer, PetscViewerType *type)
183: {
186:   *type = ((PetscObject)viewer)->type_name;
187:   return 0;
188: }

190: /*@C
191:    PetscViewerSetOptionsPrefix - Sets the prefix used for searching for all
192:    `PetscViewer` options in the database.

194:    Logically Collective

196:    Input Parameters:
197: +  viewer - the `PetscViewer` context
198: -  prefix - the prefix to prepend to all option names

200:    Note:
201:    A hyphen (-) must NOT be given at the beginning of the prefix name.
202:    The first character of all runtime options is AUTOMATICALLY the hyphen.

204:    Level: advanced

206: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSetFromOptions()`
207: @*/
208: PetscErrorCode PetscViewerSetOptionsPrefix(PetscViewer viewer, const char prefix[])
209: {
211:   PetscObjectSetOptionsPrefix((PetscObject)viewer, prefix);
212:   return 0;
213: }

215: /*@C
216:    PetscViewerAppendOptionsPrefix - Appends to the prefix used for searching for all
217:    `PetscViewer` options in the database.

219:    Logically Collective

221:    Input Parameters:
222: +  viewer - the PetscViewer context
223: -  prefix - the prefix to prepend to all option names

225:    Note:
226:    A hyphen (-) must NOT be given at the beginning of the prefix name.
227:    The first character of all runtime options is AUTOMATICALLY the hyphen.

229:    Level: advanced

231: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerGetOptionsPrefix()`
232: @*/
233: PetscErrorCode PetscViewerAppendOptionsPrefix(PetscViewer viewer, const char prefix[])
234: {
236:   PetscObjectAppendOptionsPrefix((PetscObject)viewer, prefix);
237:   return 0;
238: }

240: /*@C
241:    PetscViewerGetOptionsPrefix - Sets the prefix used for searching for all
242:    PetscViewer options in the database.

244:    Not Collective

246:    Input Parameter:
247: .  viewer - the `PetscViewer` context

249:    Output Parameter:
250: .  prefix - pointer to the prefix string used

252:    Fortran Note:
253:    The user should pass in a string 'prefix' of sufficient length to hold the prefix.

255:    Level: advanced

257: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerAppendOptionsPrefix()`
258: @*/
259: PetscErrorCode PetscViewerGetOptionsPrefix(PetscViewer viewer, const char *prefix[])
260: {
262:   PetscObjectGetOptionsPrefix((PetscObject)viewer, prefix);
263:   return 0;
264: }

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

269:    Collective

271:    Input Parameters:
272: .  viewer - the `PetscViewer` context

274:    Note:
275:    For basic use of the `PetscViewer` classes the user need not explicitly call
276:    `PetscViewerSetUp()`, since these actions will happen automatically.

278:    Level: advanced

280: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerCreate()`, `PetscViewerDestroy()`
281: @*/
282: PetscErrorCode PetscViewerSetUp(PetscViewer viewer)
283: {
285:   if (viewer->setupcalled) return 0;
286:   PetscTryTypeMethod(viewer, setup);
287:   viewer->setupcalled = PETSC_TRUE;
288:   return 0;
289: }

291: /*@C
292:    PetscViewerViewFromOptions - View from the viewer based on the options database values

294:    Collective

296:    Input Parameters:
297: +  A - the `PetscViewer` context
298: .  obj - Optional object that provides the prefix for the option names
299: -  name - command line option

301:    Level: intermediate

303: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerView`, `PetscObjectViewFromOptions()`, `PetscViewerCreate()`
304: @*/
305: PetscErrorCode PetscViewerViewFromOptions(PetscViewer A, PetscObject obj, const char name[])
306: {
308:   PetscObjectViewFromOptions((PetscObject)A, obj, name);
309:   return 0;
310: }

312: /*@C
313:    PetscViewerView - Visualizes a viewer object.

315:    Collective

317:    Input Parameters:
318: +  v - the viewer to be viewed
319: -  viewer - visualization context

321:   Note:
322:   The available visualization contexts include
323: .vb
324:   PETSC_VIEWER_STDOUT_SELF - standard output (default)
325:   PETSC_VIEWER_STDOUT_WORLD - synchronized standard output where only the first rank opens the file. Other processors send their data to the first rank
326:   PETSC_VIEWER_DRAW_WORLD - graphical display of nonzero structure
327: .ve

329:    Level: beginner

331: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerPushFormat()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`,
332:           `PetscViewerSocketOpen()`, `PetscViewerBinaryOpen()`, `PetscViewerLoad()`
333: @*/
334: PetscErrorCode PetscViewerView(PetscViewer v, PetscViewer viewer)
335: {
336:   PetscBool         iascii;
337:   PetscViewerFormat format;
338: #if defined(PETSC_HAVE_SAWS)
339:   PetscBool issaws;
340: #endif

344:   if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)v), &viewer);

348:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &iascii);
349: #if defined(PETSC_HAVE_SAWS)
350:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERSAWS, &issaws);
351: #endif
352:   if (iascii) {
353:     PetscViewerGetFormat(viewer, &format);
354:     PetscObjectPrintClassNamePrefixType((PetscObject)v, viewer);
355:     if (format == PETSC_VIEWER_DEFAULT || format == PETSC_VIEWER_ASCII_INFO || format == PETSC_VIEWER_ASCII_INFO_DETAIL) {
356:       if (v->format) PetscViewerASCIIPrintf(viewer, "  Viewer format = %s\n", PetscViewerFormats[v->format]);
357:       PetscViewerASCIIPushTab(viewer);
358:       PetscTryTypeMethod(v, view, viewer);
359:       PetscViewerASCIIPopTab(viewer);
360:     }
361: #if defined(PETSC_HAVE_SAWS)
362:   } else if (issaws) {
363:     if (!((PetscObject)v)->amsmem) {
364:       PetscObjectViewSAWs((PetscObject)v, viewer);
365:       PetscTryTypeMethod(v, view, viewer);
366:     }
367: #endif
368:   }
369:   return 0;
370: }

372: /*@C
373:    PetscViewerRead - Reads data from a `PetscViewer`

375:    Collective

377:    Input Parameters:
378: +  viewer   - The viewer
379: .  data     - Location to write the data
380: .  num      - Number of items of data to read
381: -  datatype - Type of data to read

383:    Output Parameters:
384: .  count - number of items of data actually read, or NULL

386:    Note:
387:    If datatype is `PETSC_STRING` and num is negative, reads until a newline character is found,
388:    until a maximum of (-num - 1) chars.

390:    Level: beginner

392: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerASCIIOpen()`, `PetscViewerPushFormat()`, `PetscViewerDestroy()`,
393:           `VecView()`, `MatView()`, `VecLoad()`, `MatLoad()`, `PetscViewerBinaryGetDescriptor()`,
394:           `PetscViewerBinaryGetInfoPointer()`, `PetscFileMode`, `PetscViewer`
395: @*/
396: PetscErrorCode PetscViewerRead(PetscViewer viewer, void *data, PetscInt num, PetscInt *count, PetscDataType dtype)
397: {
399:   if (dtype == PETSC_STRING) {
400:     PetscInt c, i = 0, cnt;
401:     char    *s = (char *)data;
402:     if (num >= 0) {
403:       for (c = 0; c < num; c++) {
404:         /* Skip leading whitespaces */
405:         do {
406:           (*viewer->ops->read)(viewer, &(s[i]), 1, &cnt, PETSC_CHAR);
407:           if (!cnt) break;
408:         } while (s[i] == '\n' || s[i] == '\t' || s[i] == ' ' || s[i] == '\0' || s[i] == '\v' || s[i] == '\f' || s[i] == '\r');
409:         i++;
410:         /* Read strings one char at a time */
411:         do {
412:           (*viewer->ops->read)(viewer, &(s[i++]), 1, &cnt, PETSC_CHAR);
413:           if (!cnt) break;
414:         } 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');
415:         /* Terminate final string */
416:         if (c == num - 1) s[i - 1] = '\0';
417:       }
418:     } else {
419:       /* Read until a \n is encountered (-num is the max size allowed) */
420:       do {
421:         (*viewer->ops->read)(viewer, &(s[i++]), 1, &cnt, PETSC_CHAR);
422:         if (i == -num || !cnt) break;
423:       } while (s[i - 1] != '\n');
424:       /* Terminate final string */
425:       s[i - 1] = '\0';
426:       c        = i;
427:     }
428:     if (count) *count = c;
430:   } else PetscUseTypeMethod(viewer, read, data, num, count, dtype);
431:   return 0;
432: }

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

437:    Not Collective

439:    Input Parameters:
440: .  viewer - the `PetscViewer` context

442:    Output Parameters:
443: .  flg - `PETSC_TRUE` if the viewer is readable, `PETSC_FALSE` otherwise

445:    Note:
446:    `PETSC_TRUE` means that viewer's `PetscViewerType` supports reading (this holds e.g. for `PETSCVIEWERBINARY`)
447:    and viewer is in a mode allowing reading, i.e. `PetscViewerFileGetMode()`
448:    returns one of `FILE_MODE_READ`, `FILE_MODE_UPDATE`, `FILE_MODE_APPEND_UPDATE`.

450:    Level: intermediate

452: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerWritable()`, `PetscViewerCheckReadable()`, `PetscViewerCreate()`, `PetscViewerFileSetMode()`, `PetscViewerFileSetType()`
453: @*/
454: PetscErrorCode PetscViewerReadable(PetscViewer viewer, PetscBool *flg)
455: {
456:   PetscFileMode mode;
457:   PetscErrorCode (*f)(PetscViewer, PetscFileMode *) = NULL;

461:   PetscObjectQueryFunction((PetscObject)viewer, "PetscViewerFileGetMode_C", &f);
462:   *flg = PETSC_FALSE;
463:   if (!f) return 0;
464:   (*f)(viewer, &mode);
465:   switch (mode) {
466:   case FILE_MODE_READ:
467:   case FILE_MODE_UPDATE:
468:   case FILE_MODE_APPEND_UPDATE:
469:     *flg = PETSC_TRUE;
470:   default:
471:     break;
472:   }
473:   return 0;
474: }

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

479:    Not Collective

481:    Input Parameters:
482: .  viewer - the `PetscViewer` context

484:    Output Parameters:
485: .  flg - `PETSC_TRUE` if the viewer is writable, `PETSC_FALSE` otherwise

487:    Note:
488:    `PETSC_TRUE` means viewer is in a mode allowing writing, i.e. `PetscViewerFileGetMode()`
489:    returns one of `FILE_MODE_WRITE`, `FILE_MODE_APPEND`, `FILE_MODE_UPDATE`, `FILE_MODE_APPEND_UPDATE`.

491:    Level: intermediate

493: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerReadable()`, `PetscViewerCheckWritable()`, `PetscViewerCreate()`, `PetscViewerFileSetMode()`, `PetscViewerFileSetType()`
494: @*/
495: PetscErrorCode PetscViewerWritable(PetscViewer viewer, PetscBool *flg)
496: {
497:   PetscFileMode mode;
498:   PetscErrorCode (*f)(PetscViewer, PetscFileMode *) = NULL;

502:   PetscObjectQueryFunction((PetscObject)viewer, "PetscViewerFileGetMode_C", &f);
503:   *flg = PETSC_TRUE;
504:   if (!f) return 0;
505:   (*f)(viewer, &mode);
506:   if (mode == FILE_MODE_READ) *flg = PETSC_FALSE;
507:   return 0;
508: }

510: /*@
511:    PetscViewerCheckReadable - Check whether the viewer can be read from, generates an error if not

513:    Collective

515:    Input Parameters:
516: .  viewer - the `PetscViewer` context

518:    Level: intermediate

520: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerReadable()`, `PetscViewerCheckWritable()`, `PetscViewerCreate()`, `PetscViewerFileSetMode()`, `PetscViewerFileSetType()`
521: @*/
522: PetscErrorCode PetscViewerCheckReadable(PetscViewer viewer)
523: {
524:   PetscBool flg;

527:   PetscViewerReadable(viewer, &flg);
529:   return 0;
530: }

532: /*@
533:    PetscViewerCheckWritable - Check whether the viewer can be written to, generates an error if not

535:    Collective

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

540:    Level: intermediate

542: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerWritable()`, `PetscViewerCheckReadable()`, `PetscViewerCreate()`, `PetscViewerFileSetMode()`, `PetscViewerFileSetType()`
543: @*/
544: PetscErrorCode PetscViewerCheckWritable(PetscViewer viewer)
545: {
546:   PetscBool flg;

549:   PetscViewerWritable(viewer, &flg);
551:   return 0;
552: }