Actual source code: viewreg.c

petsc-master 2017-02-22
Report Typos and Errors

  2:  #include <petsc/private/viewerimpl.h>
  3: #if defined(PETSC_HAVE_SAWS)
  4:  #include <petscviewersaws.h>
  5: #endif

  7: PetscFunctionList PetscViewerList = 0;

  9: #include "../src/sys/utils/hash.h"


 12: PetscOptionsHelpPrinted PetscOptionsHelpPrintedSingleton = NULL;
 13: KHASH_SET_INIT_STR(HTPrinted)
 14: struct  _n_PetscOptionsHelpPrinted{
 15:   khash_t(HTPrinted) *printed;
 16:   PetscSegBuffer     strings;
 17: };

 19: PetscErrorCode PetscOptionsHelpPrintedDestroy(PetscOptionsHelpPrinted *hp)
 20: {

 24:   if (!*hp) return(0);
 25:   kh_destroy(HTPrinted,(*hp)->printed);
 26:   PetscSegBufferDestroy(&(*hp)->strings);
 27:   PetscFree(*hp);
 28:   return(0);
 29: }

 31: /*@C
 32:       PetscOptionsHelpPrintedCreate - Creates an object used to manage tracking which help messages have
 33:          been printed so they will not be printed again.

 35:      Not collective

 37:     Level: developer

 39: .seealso: PetscOptionsHelpPrintedCheck(), PetscOptionsHelpPrintChecked()
 40: @*/
 41: PetscErrorCode PetscOptionsHelpPrintedCreate(PetscOptionsHelpPrinted *hp)
 42: {
 43:   PetscErrorCode             ierr;

 46:   PetscNew(hp);
 47:   (*hp)->printed = kh_init(HTPrinted);
 48:   PetscSegBufferCreate(sizeof(char),10000,&(*hp)->strings);
 49:   return(0);
 50: }

 52: /*@C
 53:       PetscOptionsHelpPrintedCheck - Checks if a particular pre, name pair has previous been entered (meaning the help message was printed)

 55:      Not collective

 57:     Input Parameters:
 58: +     hp - the object used to manage tracking what help messages have been printed
 59: .     pre - the prefix part of the string, many be NULL
 60: -     name - the string to look for (cannot be NULL)

 62:     Output Parameter:
 63: .     found - PETSC_TRUE if the string was already set

 65:     Level: intermediate


 68: .seealso: PetscOptionsHelpPrintedCreate()
 69: @*/
 70: PetscErrorCode PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrinted hp,const char *pre,const char* name,PetscBool *found)
 71: {
 72:   size_t          l1,l2;
 73: #if !defined(PETSC_HAVE_THREADSAFETY)
 74:   char            *both;
 75:   khint_t         newitem;
 76: #endif
 77:   PetscErrorCode  ierr;

 80:   PetscStrlen(pre,&l1);
 81:   PetscStrlen(name,&l2);
 82:   if (l1+l2 == 0) {
 83:     *found = PETSC_FALSE;
 84:     return(0);
 85:   }
 86: #if !defined(PETSC_HAVE_THREADSAFETY)
 87:   PetscSegBufferGet(hp->strings,l1+l2+1,&both);
 88:   PetscStrcpy(both,pre);
 89:   PetscStrcat(both,name);
 90:   kh_put(HTPrinted,hp->printed,both,&newitem);
 91:   if (!newitem) {
 92:     PetscSegBufferUnuse(hp->strings,l1+l2+1);
 93:   }
 94:   *found = newitem ? PETSC_FALSE : PETSC_TRUE;
 95: #else
 96:   *found = PETSC_FALSE;
 97: #endif
 98:   return(0);
 99: }

101: static PetscBool noviewer = PETSC_FALSE;
102: static PetscBool noviewers[PETSCVIEWERGETVIEWEROFFPUSHESMAX];
103: static PetscInt  inoviewers = 0;

105: /*@
106:   PetscOptionsPushGetViewerOff - control whether PetscOptionsGetViewer returns a viewer.

108:   Logically Collective

110:   Input Parameter:
111: . flg - PETSC_TRUE to turn off viewer creation, PETSC_FALSE to turn it on.

113:   Level: developer

115:   Notes: Calling XXXViewFromOptions in an inner loop can be very expensive.  This can appear, for example, when using
116:    many small subsolves.  Call this function to control viewer creation in PetscOptionsGetViewer, thus removing the expensive XXXViewFromOptions calls.

118: .seealso: PetscOptionsGetViewer(), PetscOptionsPopGetViewerOff()
119: @*/
120: PetscErrorCode  PetscOptionsPushGetViewerOff(PetscBool flg)
121: {
123:   if (inoviewers > PETSCVIEWERGETVIEWEROFFPUSHESMAX - 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptionsPushGetViewerOff(), perhaps you forgot PetscOptionsPopGetViewerOff()?");

125:   noviewers[inoviewers++] = noviewer;
126:   noviewer = flg;
127:   return(0);
128: }

130: /*@
131:   PetscOptionsPopGetViewerOff - reset whether PetscOptionsGetViewer returns a viewer.

133:   Logically Collective

135:   Level: developer

137:   Notes: Calling XXXViewFromOptions in an inner loop can be very expensive.  This can appear, for example, when using
138:    many small subsolves.  Call this function to control viewer creation in PetscOptionsGetViewer, thus removing the expensive XXXViewFromOptions calls.

140: .seealso: PetscOptionsGetViewer(), PetscOptionsPushGetViewerOff()
141: @*/
142: PetscErrorCode  PetscOptionsPopGetViewerOff()
143: {
145:   if (!inoviewers) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptionsPopGetViewerOff(), perhaps you forgot PetscOptionsPushGetViewerOff()?");
146:   noviewer = noviewers[--inoviewers];
147:   return(0);
148: }

150: /*@
151:   PetscOptionsGetViewerOff - does PetscOptionsGetViewer return a viewer?

153:   Logically Collective

155:   Output Parameter:
156: . flg - whether viewers are returned.

158:   Level: developer

160:   Notes: Calling XXXViewFromOptions in an inner loop can be very expensive.  This can appear, for example, when using
161:    many small subsolves.

163: .seealso: PetscOptionsGetViewer(), PetscOptionsPushGetViewerOff(), PetscOptionsPopGetViewerOff()
164: @*/
165: PetscErrorCode  PetscOptionsGetViewerOff(PetscBool *flg)
166: {
169:   *flg = noviewer;
170:   return(0);
171: }

173: /*@C
174:    PetscOptionsGetViewer - Gets a viewer appropriate for the type indicated by the user

176:    Collective on MPI_Comm

178:    Input Parameters:
179: +  comm - the communicator to own the viewer
180: .  pre - the string to prepend to the name or NULL
181: -  name - the option one is seeking

183:    Output Parameter:
184: +  viewer - the viewer, pass NULL if not needed
185: .  format - the PetscViewerFormat requested by the user, pass NULL if not needed
186: -  set - PETSC_TRUE if found, else PETSC_FALSE

188:    Level: intermediate

190:    Notes: If no value is provided ascii:stdout is used
191: $       ascii[:[filename][:[format][:append]]]    defaults to stdout - format can be one of ascii_info, ascii_info_detail, or ascii_matlab, 
192:                                                   for example ascii::ascii_info prints just the information about the object not all details
193:                                                   unless :append is given filename opens in write mode, overwriting what was already there
194: $       binary[:[filename][:[format][:append]]]   defaults to the file binaryoutput
195: $       draw[:drawtype[:filename]]                for example, draw:tikz, draw:tikz:figure.tex  or draw:x 
196: $       socket[:port]                             defaults to the standard output port
197: $       saws[:communicatorname]                    publishes object to the Scientific Application Webserver (SAWs)

199:    Use PetscViewerDestroy() after using the viewer, otherwise a memory leak will occur

201:    You can control whether calls to this function create a viewer (or return early with *set of PETSC_FALSE) with
202:    PetscOptionsPushGetViewerOff.  This is useful if calling many small subsolves, in which case XXXViewFromOptions can take
203:    an appreciable fraction of the runtime.

205:    If PETSc is configured with --with-viewfromoptions=0 this function always returns with *set of PETSC_FALSE

207: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
208:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
209:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
210:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
211:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
212:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
213:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsPushGetViewerOff(), PetscOptionsPopGetViewerOff(),
214:           PetscOptionsGetViewerOff()
215: @*/
216: PetscErrorCode  PetscOptionsGetViewer(MPI_Comm comm,const char pre[],const char name[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
217: {
218:   char                           *value;
219:   PetscErrorCode                 ierr;
220:   PetscBool                      flag,hashelp;


225:   if (set) *set = PETSC_FALSE;
226: #if defined(PETSC_SKIP_VIEWFROMOPTIONS)
227:   return(0);
228: #endif
229:   PetscOptionsGetViewerOff(&flag);
230:   if (flag) return(0);

232:   PetscOptionsHasName(NULL,NULL,"-help",&hashelp);
233:   if (hashelp) {
234:     PetscBool found;

236:     if (!PetscOptionsHelpPrintedSingleton) {
237:       PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
238:     }
239:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,pre,name,&found);
240:     if (!found) {
241:       if (viewer) {
242:         (*PetscHelpPrintf)(comm,"\n  -%s%s ascii[:[filename][:[format][:append]]]: %s (%s)\n",pre ? pre : "",name+1,"Prints object to stdout or ASCII file","PetscOptionsGetViewer");
243:         (*PetscHelpPrintf)(comm,"    -%s%s binary[:[filename][:[format][:append]]]: %s (%s)\n",pre ? pre : "",name+1,"Saves object to a binary file","PetscOptionsGetViewer");
244:         (*PetscHelpPrintf)(comm,"    -%s%s draw[:drawtype[:filename]] %s (%s)\n",pre ? pre : "",name+1,"Draws object","PetscOptionsGetViewer");
245:         (*PetscHelpPrintf)(comm,"    -%s%s socket[:port]: %s (%s)\n",pre ? pre : "",name+1,"Pushes object to a Unix socket","PetscOptionsGetViewer");
246:         (*PetscHelpPrintf)(comm,"    -%s%s saws[:communicatorname]: %s (%s)\n\n",pre ? pre : "",name+1,"Publishes object to SAWs","PetscOptionsGetViewer");
247:       } else {
248:         (*PetscHelpPrintf)(comm,"    -%s%s\n",pre ? pre : "",name+1);
249:       }
250:     }
251:   }

253:   if (format) *format = PETSC_VIEWER_DEFAULT;
254:   PetscOptionsFindPair_Private(NULL,pre,name,&value,&flag);
255:   if (flag) {
256:     if (set) *set = PETSC_TRUE;
257:     if (!value) {
258:       if (viewer) {
259:         PetscViewerASCIIGetStdout(comm,viewer);
260:         PetscObjectReference((PetscObject)*viewer);
261:       }
262:     } else {
263:       char       *loc0_vtype,*loc1_fname,*loc2_fmt = NULL,*loc3_fmode = NULL;
264:       PetscInt   cnt;
265:       const char *viewers[] = {PETSCVIEWERASCII,PETSCVIEWERBINARY,PETSCVIEWERDRAW,PETSCVIEWERSOCKET,PETSCVIEWERMATLAB,PETSCVIEWERSAWS,PETSCVIEWERVTK,PETSCVIEWERHDF5,0};

267:       PetscStrallocpy(value,&loc0_vtype);
268:       PetscStrchr(loc0_vtype,':',&loc1_fname);
269:       if (loc1_fname) {
270:         *loc1_fname++ = 0;
271:         PetscStrchr(loc1_fname,':',&loc2_fmt);
272:       }
273:       if (loc2_fmt) {
274:         *loc2_fmt++ = 0;
275:         PetscStrchr(loc2_fmt,':',&loc3_fmode);
276:       }
277:       if (loc3_fmode) *loc3_fmode++ = 0;
278:       PetscStrendswithwhich(*loc0_vtype ? loc0_vtype : "ascii",viewers,&cnt);
279:       if (cnt > (PetscInt) sizeof(viewers)-1) SETERRQ1(comm,PETSC_ERR_ARG_OUTOFRANGE,"Unknown viewer type: %s",loc0_vtype);
280:       if (viewer) {
281:         if (!loc1_fname) {
282:           switch (cnt) {
283:           case 0:
284:             PetscViewerASCIIGetStdout(comm,viewer);
285:             break;
286:           case 1:
287:             if (!(*viewer = PETSC_VIEWER_BINARY_(comm))) CHKERRQ(PETSC_ERR_PLIB);
288:             break;
289:           case 2:
290:             if (!(*viewer = PETSC_VIEWER_DRAW_(comm))) CHKERRQ(PETSC_ERR_PLIB);
291:             break;
292: #if defined(PETSC_USE_SOCKET_VIEWER)
293:           case 3:
294:             if (!(*viewer = PETSC_VIEWER_SOCKET_(comm))) CHKERRQ(PETSC_ERR_PLIB);
295:             break;
296: #endif
297: #if defined(PETSC_HAVE_MATLAB_ENGINE)
298:           case 4:
299:             if (!(*viewer = PETSC_VIEWER_MATLAB_(comm))) CHKERRQ(PETSC_ERR_PLIB);
300:             break;
301: #endif
302: #if defined(PETSC_HAVE_SAWS)
303:           case 5:
304:             if (!(*viewer = PETSC_VIEWER_SAWS_(comm))) CHKERRQ(PETSC_ERR_PLIB);
305:             break;
306: #endif
307: #if defined(PETSC_HAVE_HDF5)
308:           case 7:
309:             if (!(*viewer = PETSC_VIEWER_HDF5_(comm))) CHKERRQ(PETSC_ERR_PLIB);
310:             break;
311: #endif
312:           default: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Unsupported viewer %s",loc0_vtype);
313:           }
314:           PetscObjectReference((PetscObject)*viewer);
315:         } else {
316:           if (loc2_fmt && !*loc1_fname && (cnt == 0)) { /* ASCII format without file name */
317:             PetscViewerASCIIGetStdout(comm,viewer);
318:             PetscObjectReference((PetscObject)*viewer);
319:           } else {
320:             PetscFileMode fmode;
321:             PetscViewerCreate(comm,viewer);
322:             PetscViewerSetType(*viewer,*loc0_vtype ? loc0_vtype : "ascii");
323:             fmode = FILE_MODE_WRITE;
324:             if (loc3_fmode && *loc3_fmode) { /* Has non-empty file mode ("write" or "append") */
325:               PetscEnumFind(PetscFileModes,loc3_fmode,(PetscEnum*)&fmode,&flag);
326:               if (!flag) SETERRQ1(comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown file mode: %s",loc3_fmode);
327:             }
328:             if (loc2_fmt) {
329:               PetscBool tk;
330:               PetscStrcmp(loc1_fname,"tikz",&tk);
331:               if (tk) {
332:                 PetscViewerDrawSetInfo(*viewer,NULL,loc2_fmt,0,0,0,0);
333:                 *loc2_fmt = 0;
334:               }
335:             }
336:             PetscViewerFileSetMode(*viewer,flag?fmode:FILE_MODE_WRITE);
337:             PetscViewerFileSetName(*viewer,loc1_fname);
338:             PetscViewerDrawSetDrawType(*viewer,loc1_fname);
339:           }
340:         }
341:       }
342:       if (viewer) {
343:         PetscViewerSetUp(*viewer);
344:       }
345:       if (loc2_fmt && *loc2_fmt) {
346:         PetscEnumFind(PetscViewerFormats,loc2_fmt,(PetscEnum*)format,&flag);
347:         if (!flag) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Unknown viewer format %s",loc2_fmt);
348:       }
349:       PetscFree(loc0_vtype);
350:     }
351:   }
352:   return(0);
353: }

355: /*@
356:    PetscViewerCreate - Creates a viewing context

358:    Collective on MPI_Comm

360:    Input Parameter:
361: .  comm - MPI communicator

363:    Output Parameter:
364: .  inviewer - location to put the PetscViewer context

366:    Level: advanced

368:    Concepts: graphics^creating PetscViewer
369:    Concepts: file input/output^creating PetscViewer
370:    Concepts: sockets^creating PetscViewer

372: .seealso: PetscViewerDestroy(), PetscViewerSetType(), PetscViewerType

374: @*/
375: PetscErrorCode  PetscViewerCreate(MPI_Comm comm,PetscViewer *inviewer)
376: {
377:   PetscViewer    viewer;

381:   *inviewer = 0;
382:   PetscViewerInitializePackage();
383:   PetscHeaderCreate(viewer,PETSC_VIEWER_CLASSID,"PetscViewer","PetscViewer","Viewer",comm,PetscViewerDestroy,NULL);
384:   *inviewer    = viewer;
385:   viewer->data = 0;
386:   return(0);
387: }

389: /*@C
390:    PetscViewerSetType - Builds PetscViewer for a particular implementation.

392:    Collective on PetscViewer

394:    Input Parameter:
395: +  viewer      - the PetscViewer context
396: -  type        - for example, PETSCVIEWERASCII

398:    Options Database Command:
399: .  -draw_type  <type> - Sets the type; use -help for a list
400:     of available methods (for instance, ascii)

402:    Level: advanced

404:    Notes:
405:    See "include/petscviewer.h" for available methods (for instance,
406:    PETSCVIEWERSOCKET)

408: .seealso: PetscViewerCreate(), PetscViewerGetType(), PetscViewerType, PetscViewerPushFormat()
409: @*/
410: PetscErrorCode  PetscViewerSetType(PetscViewer viewer,PetscViewerType type)
411: {
412:   PetscErrorCode ierr,(*r)(PetscViewer);
413:   PetscBool      match;

418:   PetscObjectTypeCompare((PetscObject)viewer,type,&match);
419:   if (match) return(0);

421:   /* cleanup any old type that may be there */
422:   if (viewer->data) {
423:     (*viewer->ops->destroy)(viewer);

425:     viewer->ops->destroy = NULL;
426:     viewer->data         = 0;
427:   }
428:   PetscMemzero(viewer->ops,sizeof(struct _PetscViewerOps));

430:    PetscFunctionListFind(PetscViewerList,type,&r);
431:   if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown PetscViewer type given: %s",type);

433:   PetscObjectChangeTypeName((PetscObject)viewer,type);
434:   (*r)(viewer);
435:   return(0);
436: }

438: /*@C
439:    PetscViewerRegister - Adds a viewer

441:    Not Collective

443:    Input Parameters:
444: +  name_solver - name of a new user-defined viewer
445: -  routine_create - routine to create method context

447:    Level: developer
448:    Notes:
449:    PetscViewerRegister() may be called multiple times to add several user-defined viewers.

451:    Sample usage:
452: .vb
453:    PetscViewerRegister("my_viewer_type",MyViewerCreate);
454: .ve

456:    Then, your solver can be chosen with the procedural interface via
457: $     PetscViewerSetType(viewer,"my_viewer_type")
458:    or at runtime via the option
459: $     -viewer_type my_viewer_type

461:   Concepts: registering^Viewers

463: .seealso: PetscViewerRegisterAll(), PetscViewerRegisterDestroy()
464:  @*/
465: PetscErrorCode  PetscViewerRegister(const char *sname,PetscErrorCode (*function)(PetscViewer))
466: {

470:   PetscFunctionListAdd(&PetscViewerList,sname,function);
471:   return(0);
472: }

474: /*@C
475:    PetscViewerSetFromOptions - Sets the graphics type from the options database.
476:       Defaults to a PETSc X windows graphics.

478:    Collective on PetscViewer

480:    Input Parameter:
481: .     PetscViewer - the graphics context

483:    Level: intermediate

485:    Notes:
486:     Must be called after PetscViewerCreate() before the PetscViewer is used.

488:   Concepts: PetscViewer^setting options

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

492: @*/
493: PetscErrorCode  PetscViewerSetFromOptions(PetscViewer viewer)
494: {
495:   PetscErrorCode    ierr;
496:   char              vtype[256];
497:   PetscBool         flg;


502:   if (!PetscViewerList) {
503:     PetscViewerRegisterAll();
504:   }
505:   PetscObjectOptionsBegin((PetscObject)viewer);
506:   PetscOptionsFList("-viewer_type","Type of PetscViewer","None",PetscViewerList,(char*)(((PetscObject)viewer)->type_name ? ((PetscObject)viewer)->type_name : PETSCVIEWERASCII),vtype,256,&flg);
507:   if (flg) {
508:     PetscViewerSetType(viewer,vtype);
509:   }
510:   /* type has not been set? */
511:   if (!((PetscObject)viewer)->type_name) {
512:     PetscViewerSetType(viewer,PETSCVIEWERASCII);
513:   }
514:   if (viewer->ops->setfromoptions) {
515:     (*viewer->ops->setfromoptions)(PetscOptionsObject,viewer);
516:   }

518:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
519:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)viewer);
520:   PetscViewerViewFromOptions(viewer,NULL,"-viewer_view");
521:   PetscOptionsEnd();
522:   return(0);
523: }

525: PetscErrorCode PetscViewerFlowControlStart(PetscViewer viewer,PetscInt *mcnt,PetscInt *cnt)
526: {
529:   PetscViewerBinaryGetFlowControl(viewer,mcnt);
530:   PetscViewerBinaryGetFlowControl(viewer,cnt);
531:   return(0);
532: }

534: PetscErrorCode PetscViewerFlowControlStepMaster(PetscViewer viewer,PetscInt i,PetscInt *mcnt,PetscInt cnt)
535: {
537:   MPI_Comm       comm;

540:   PetscObjectGetComm((PetscObject)viewer,&comm);
541:   if (i >= *mcnt) {
542:     *mcnt += cnt;
543:     MPI_Bcast(mcnt,1,MPIU_INT,0,comm);
544:   }
545:   return(0);
546: }

548: PetscErrorCode PetscViewerFlowControlEndMaster(PetscViewer viewer,PetscInt *mcnt)
549: {
551:   MPI_Comm       comm;
553:   PetscObjectGetComm((PetscObject)viewer,&comm);
554:   *mcnt = 0;
555:   MPI_Bcast(mcnt,1,MPIU_INT,0,comm);
556:   return(0);
557: }

559: PetscErrorCode PetscViewerFlowControlStepWorker(PetscViewer viewer,PetscMPIInt rank,PetscInt *mcnt)
560: {
562:   MPI_Comm       comm;
564:   PetscObjectGetComm((PetscObject)viewer,&comm);
565:   while (PETSC_TRUE) {
566:     if (rank < *mcnt) break;
567:     MPI_Bcast(mcnt,1,MPIU_INT,0,comm);
568:   }
569:   return(0);
570: }

572: PetscErrorCode PetscViewerFlowControlEndWorker(PetscViewer viewer,PetscInt *mcnt)
573: {
575:   MPI_Comm       comm;
577:   PetscObjectGetComm((PetscObject)viewer,&comm);
578:   while (PETSC_TRUE) {
579:     MPI_Bcast(mcnt,1,MPIU_INT,0,comm);
580:     if (!*mcnt) break;
581:   }
582:   return(0);
583: }