Actual source code: options.c

petsc-master 2015-05-31
Report Typos and Errors
  2: /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
  3: #define PETSC_DESIRE_FEATURE_TEST_MACROS

  5: /*
  6:    These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
  7:    This provides the low-level interface, the high level interface is in aoptions.c

  9:    Some routines use regular malloc and free because it cannot know  what malloc is requested with the
 10:    options database until it has already processed the input.
 11: */

 13: #include <petsc/private/petscimpl.h>        /*I  "petscsys.h"   I*/
 14: #include <petscviewer.h>
 15: #include <ctype.h>
 16: #if defined(PETSC_HAVE_MALLOC_H)
 17: #include <malloc.h>
 18: #endif
 19: #if defined(PETSC_HAVE_YAML)
 20: #include <yaml.h>
 21: #endif

 23: /*
 24:     This table holds all the options set by the user. For simplicity, we use a static size database
 25: */
 26: #define MAXOPTIONS 512
 27: #define MAXALIASES 25
 28: #define MAXOPTIONSMONITORS 5
 29: #define MAXPREFIXES 25

 31: typedef struct {
 32:   int            N,argc,Naliases;
 33:   char           **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
 34:   char           *aliases1[MAXALIASES],*aliases2[MAXALIASES];
 35:   PetscBool      used[MAXOPTIONS];
 36:   PetscBool      namegiven;
 37:   char           programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */

 39:   /* --------User (or default) routines (most return -1 on error) --------*/
 40:   PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
 41:   PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**);         /* */
 42:   void           *monitorcontext[MAXOPTIONSMONITORS];                  /* to pass arbitrary user data into monitor */
 43:   PetscInt       numbermonitors;                                       /* to, for instance, detect options being set */

 45:   /* Prefixes */
 46:   PetscInt prefixind,prefixstack[MAXPREFIXES];
 47:   char     prefix[2048];
 48: } PetscOptionsTable;


 51: static PetscOptionsTable      *options = 0;

 53: /*
 54:     Options events monitor
 55: */
 56: #define PetscOptionsMonitor(name,value)                              \
 57:   { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
 58:     for (_i=0; _i<_im; _i++) { \
 59:       _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
 60:     } \
 61:   }

 65: /*
 66:    PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
 67: */
 68: PetscErrorCode  PetscOptionsStringToInt(const char name[],PetscInt *a)
 69: {
 71:   size_t         i,len;
 72:   PetscBool      decide,tdefault,mouse;

 75:   PetscStrlen(name,&len);
 76:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

 78:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 79:   if (!tdefault) {
 80:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 81:   }
 82:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 83:   if (!decide) {
 84:     PetscStrcasecmp(name,"DECIDE",&decide);
 85:   }
 86:   PetscStrcasecmp(name,"mouse",&mouse);

 88:   if (tdefault)    *a = PETSC_DEFAULT;
 89:   else if (decide) *a = PETSC_DECIDE;
 90:   else if (mouse)  *a = -1;
 91:   else {
 92:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);

 94:     for (i=1; i<len; i++) {
 95:       if (name[i] < '0' || name[i] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 96:     }

 98: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
 99:     *a = atoll(name);
100: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
101:     *a = _atoi64(name);
102: #else
103:     *a = (PetscInt)atoi(name);
104: #endif
105:   }
106:   return(0);
107: }

111: /*
112:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
113: */
114: PetscErrorCode  PetscOptionsStringToReal(const char name[],PetscReal *a)
115: {
117:   size_t         len;
118:   PetscBool      decide,tdefault;

121:   PetscStrlen(name,&len);
122:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

124:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
125:   if (!tdefault) {
126:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
127:   }
128:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
129:   if (!decide) {
130:     PetscStrcasecmp(name,"DECIDE",&decide);
131:   }

133:   if (tdefault)    *a = PETSC_DEFAULT;
134:   else if (decide) *a = PETSC_DECIDE;
135:   else {
136:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
137:     *a = atof(name);
138:   }
139:   return(0);
140: }

144: /*
145:    Converts a string to PetscScalar value. Handles
146:       [-][2].0
147:       [-][2].0i
148:       [-][2].0+/-2.0i

150: */
151: PetscErrorCode  PetscOptionsStringToScalar(const char name[],PetscScalar *a)
152: {
154:   size_t         len;

157:   PetscStrlen(name,&len);
158:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

160:   if (name[0] == '+') name++;
161:   if (name[0] == 'i') {
162: #if defined(PETSC_USE_COMPLEX)
163:     *a = PETSC_i;
164: #else
165:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
166: #endif
167:   } else {
168:     PetscToken token;
169:     char       *tvalue1,*tvalue2;
170:     PetscBool  neg = PETSC_FALSE, negim = PETSC_FALSE;
171:     PetscReal  re = 0.0,im = 0.0;

173:     if (name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
174:     if (name[0] == '-') {
175:       neg = PETSC_TRUE;
176:       name++;
177:     }
178:     if (name[0] == 'i') {
179: #if defined(PETSC_USE_COMPLEX)
180:       *a = -PETSC_i;
181: #else
182:      SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
183: #endif
184:       return(0);
185:     }

187:     PetscTokenCreate(name,'+',&token);
188:     PetscTokenFind(token,&tvalue1);
189:     PetscTokenFind(token,&tvalue2);
190:     if (!tvalue2) {
191:       negim = PETSC_TRUE;
192:       PetscTokenDestroy(&token);
193:       PetscTokenCreate(name,'-',&token);
194:       PetscTokenFind(token,&tvalue1);
195:       PetscTokenFind(token,&tvalue2);
196:     }
197:     if (!tvalue2) {
198:       PetscBool isim;
199:       PetscStrendswith(tvalue1,"i",&isim);
200:       if (isim) {
201:         tvalue2 = tvalue1;
202:         tvalue1 = NULL;
203:         negim   = neg;
204:       }
205:     } else {
206:       PetscBool isim;
207:       PetscStrendswith(tvalue2,"i",&isim);
208:       if (!isim) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
209:     }
210:     if (tvalue1) {
211:       PetscOptionsStringToReal(tvalue1,&re);
212:       if (neg) re = -re;
213:     }
214:     if (tvalue2) {
215:       PetscStrlen(tvalue2,&len);
216:       tvalue2[len-1] = 0;
217:       PetscOptionsStringToReal(tvalue2,&im);
218:       if (negim) im = -im;
219:     }
220:     PetscTokenDestroy(&token);
221: #if defined(PETSC_USE_COMPLEX)
222:     *a = re + im*PETSC_i;
223: #else
224:     if (im != 0.0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is complex but complex not supported ",name);
225:     *a = re;
226: #endif
227:   }
228:   return(0);
229: }

233: /*
234:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
235: */
236: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
237: {
238:   PetscBool      istrue, isfalse;
239:   size_t         len;

243:   PetscStrlen(value, &len);
244:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
245:   PetscStrcasecmp(value,"TRUE",&istrue);
246:   if (istrue) {*a = PETSC_TRUE; return(0);}
247:   PetscStrcasecmp(value,"YES",&istrue);
248:   if (istrue) {*a = PETSC_TRUE; return(0);}
249:   PetscStrcasecmp(value,"1",&istrue);
250:   if (istrue) {*a = PETSC_TRUE; return(0);}
251:   PetscStrcasecmp(value,"on",&istrue);
252:   if (istrue) {*a = PETSC_TRUE; return(0);}
253:   PetscStrcasecmp(value,"FALSE",&isfalse);
254:   if (isfalse) {*a = PETSC_FALSE; return(0);}
255:   PetscStrcasecmp(value,"NO",&isfalse);
256:   if (isfalse) {*a = PETSC_FALSE; return(0);}
257:   PetscStrcasecmp(value,"0",&isfalse);
258:   if (isfalse) {*a = PETSC_FALSE; return(0);}
259:   PetscStrcasecmp(value,"off",&isfalse);
260:   if (isfalse) {*a = PETSC_FALSE; return(0);}
261:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
262: }

266: /*@C
267:     PetscGetProgramName - Gets the name of the running program.

269:     Not Collective

271:     Input Parameter:
272: .   len - length of the string name

274:     Output Parameter:
275: .   name - the name of the running program

277:    Level: advanced

279:     Notes:
280:     The name of the program is copied into the user-provided character
281:     array of length len.  On some machines the program name includes
282:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
283: @*/
284: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
285: {

289:   if (!options) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
290:   if (!options->namegiven) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Unable to determine program name");
291:   PetscStrncpy(name,options->programname,len);
292:   return(0);
293: }

297: PetscErrorCode  PetscSetProgramName(const char name[])
298: {

302:   options->namegiven = PETSC_TRUE;

304:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
305:   return(0);
306: }

310: /*@
311:     PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter.

313:    Input Parameter:
314: .    in_str - string to check if valid

316:    Output Parameter:
317: .    key - PETSC_TRUE if a valid key

319:   Level: intermediate

321: @*/
322: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
323: {
324:   PetscBool      inf,INF;

328:   *key = PETSC_FALSE;
329:   if (!in_str) return(0);
330:   if (in_str[0] != '-') return(0);
331:   if (in_str[1] == '-') in_str++;
332:   if (!isalpha((int)(in_str[1]))) return(0);
333:   PetscStrncmp(in_str+1,"inf",3,&inf);
334:   PetscStrncmp(in_str+1,"INF",3,&INF);
335:   if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
336:   *key = PETSC_TRUE;
337:   return(0);
338: }

342: /*@C
343:      PetscOptionsInsertString - Inserts options into the database from a string

345:      Not collective: but only processes that call this routine will set the options
346:                      included in the string

348:   Input Parameter:
349: .   in_str - string that contains options separated by blanks


352:   Level: intermediate

354:   Contributed by Boyana Norris

356: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
357:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
358:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
359:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
360:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
361:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()

363: @*/
364: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
365: {
366:   char           *first,*second;
368:   PetscToken     token;
369:   PetscBool      key,ispush,ispop;

372:   PetscTokenCreate(in_str,' ',&token);
373:   PetscTokenFind(token,&first);
374:   while (first) {
375:     PetscStrcasecmp(first,"-prefix_push",&ispush);
376:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
377:     PetscOptionsValidKey(first,&key);
378:     if (ispush) {
379:       PetscTokenFind(token,&second);
380:       PetscOptionsPrefixPush(second);
381:       PetscTokenFind(token,&first);
382:     } else if (ispop) {
383:       PetscOptionsPrefixPop();
384:       PetscTokenFind(token,&first);
385:     } else if (key) {
386:       PetscTokenFind(token,&second);
387:       PetscOptionsValidKey(second,&key);
388:       if (!key) {
389:         PetscOptionsSetValue(first,second);
390:         PetscTokenFind(token,&first);
391:       } else {
392:         PetscOptionsSetValue(first,NULL);
393:         first = second;
394:       }
395:     } else {
396:       PetscTokenFind(token,&first);
397:     }
398:   }
399:   PetscTokenDestroy(&token);
400:   return(0);
401: }

403: /*
404:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
405: */
406: static char *Petscgetline(FILE * f)
407: {
408:   size_t size  = 0;
409:   size_t len   = 0;
410:   size_t last  = 0;
411:   char   *buf  = NULL;

413:   if (feof(f)) return 0;
414:   do {
415:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
416:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
417:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
418:     end of the string, so we make sure we overwrite this */
419:     if (!fgets(buf+len,size,f)) buf[len]=0;
420:     PetscStrlen(buf,&len);
421:     last = len - 1;
422:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
423:   if (len) return buf;
424:   free(buf);
425:   return 0;
426: }


431: /*@C
432:      PetscOptionsInsertFile - Inserts options into the database from a file.

434:      Collective on MPI_Comm

436:   Input Parameter:
437: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
438: .   file - name of file
439: -   require - if PETSC_TRUE will generate an error if the file does not exist


442:   Notes: Use  # for lines that are comments and which should be ignored.

444:   Level: developer

446: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
447:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
448:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
449:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
450:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
451:           PetscOptionsFList(), PetscOptionsEList()

453: @*/
454: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
455: {
456:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
458:   size_t         i,len,bytes;
459:   FILE           *fd;
460:   PetscToken     token;
461:   int            err;
462:   char           cmt[1]={'#'},*cmatch;
463:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];

466:   MPI_Comm_rank(comm,&rank);
467:   if (!rank) {
468:     cnt        = 0;
469:     acnt       = 0;

471:     PetscFixFilename(file,fname);
472:     fd   = fopen(fname,"r");
473:     if (fd) {
474:       PetscSegBuffer vseg,aseg;
475:       PetscSegBufferCreate(1,4000,&vseg);
476:       PetscSegBufferCreate(1,2000,&aseg);

478:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
479:       PetscInfo1(0,"Opened options file %s\n",file);

481:       while ((string = Petscgetline(fd))) {
482:         /* eliminate comments from each line */
483:         for (i=0; i<1; i++) {
484:           PetscStrchr(string,cmt[i],&cmatch);
485:           if (cmatch) *cmatch = 0;
486:         }
487:         PetscStrlen(string,&len);
488:         /* replace tabs, ^M, \n with " " */
489:         for (i=0; i<len; i++) {
490:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
491:             string[i] = ' ';
492:           }
493:         }
494:         PetscTokenCreate(string,' ',&token);
495:         PetscTokenFind(token,&first);
496:         if (!first) {
497:           goto destroy;
498:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
499:           PetscTokenFind(token,&first);
500:         }
501:         PetscTokenFind(token,&second);
502:         if (!first) {
503:           goto destroy;
504:         } else if (first[0] == '-') {
505:           PetscStrlen(first,&len);
506:           PetscSegBufferGet(vseg,len+1,&vstring);
507:           PetscMemcpy(vstring,first,len);
508:           vstring[len] = ' ';
509:           if (second) {
510:             PetscStrlen(second,&len);
511:             PetscSegBufferGet(vseg,len+3,&vstring);
512:             vstring[0] = '"';
513:             PetscMemcpy(vstring+1,second,len);
514:             vstring[len+1] = '"';
515:             vstring[len+2] = ' ';
516:           }
517:         } else {
518:           PetscBool match;

520:           PetscStrcasecmp(first,"alias",&match);
521:           if (match) {
522:             PetscTokenFind(token,&third);
523:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
524:             PetscStrlen(second,&len);
525:             PetscSegBufferGet(aseg,len+1,&astring);
526:             PetscMemcpy(astring,second,len);
527:             astring[len] = ' ';

529:             PetscStrlen(third,&len);
530:             PetscSegBufferGet(aseg,len+1,&astring);
531:             PetscMemcpy(astring,third,len);
532:             astring[len] = ' ';
533:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
534:         }
535: destroy:
536:         free(string);
537:         PetscTokenDestroy(&token);
538:       }
539:       err = fclose(fd);
540:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
541:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
542:       PetscMPIIntCast(bytes,&acnt);
543:       PetscSegBufferGet(aseg,1,&astring);
544:       astring[0] = 0;
545:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
546:       PetscMPIIntCast(bytes,&cnt);
547:       PetscSegBufferGet(vseg,1,&vstring);
548:       vstring[0] = 0;
549:       PetscMalloc1(2+acnt+cnt,&packed);
550:       PetscSegBufferExtractTo(aseg,packed);
551:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
552:       PetscSegBufferDestroy(&aseg);
553:       PetscSegBufferDestroy(&vseg);
554:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
555:   }

557:   counts[0] = acnt;
558:   counts[1] = cnt;
559:   MPI_Bcast(counts,2,MPI_INT,0,comm);
560:   acnt = counts[0];
561:   cnt = counts[1];
562:   if (rank) {
563:     PetscMalloc1(2+acnt+cnt,&packed);
564:   }
565:   if (acnt || cnt) {
566:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
567:     astring = packed;
568:     vstring = packed + acnt + 1;
569:   }

571:   if (acnt) {
572:     PetscToken token;
573:     char       *first,*second;

575:     PetscTokenCreate(astring,' ',&token);
576:     PetscTokenFind(token,&first);
577:     while (first) {
578:       PetscTokenFind(token,&second);
579:       PetscOptionsSetAlias(first,second);
580:       PetscTokenFind(token,&first);
581:     }
582:     PetscTokenDestroy(&token);
583:   }

585:   if (cnt) {
586:     PetscOptionsInsertString(vstring);
587:   }
588:   PetscFree(packed);
589:   return(0);
590: }

594: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
595: {
597:   int            left    = argc - 1;
598:   char           **eargs = args + 1;

601:   while (left) {
602:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
603:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
604:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
605:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
606:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
607:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
608:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
609:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
610:     isp4 = (PetscBool) (isp4 || tisp4);
611:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
612:     isp4 = (PetscBool) (isp4 || tisp4);
613:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
614:     PetscOptionsValidKey(eargs[0],&key);

616:     if (!key) {
617:       eargs++; left--;
618:     } else if (isoptions_file) {
619:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
620:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
621:       PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
622:       eargs += 2; left -= 2;
623:     } else if (isprefixpush) {
624:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
625:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
626:       PetscOptionsPrefixPush(eargs[1]);
627:       eargs += 2; left -= 2;
628:     } else if (isprefixpop) {
629:       PetscOptionsPrefixPop();
630:       eargs++; left--;

632:       /*
633:        These are "bad" options that MPICH, etc put on the command line
634:        we strip them out here.
635:        */
636:     } else if (tisp4 || isp4rmrank) {
637:       eargs += 1; left -= 1;
638:     } else if (isp4 || isp4yourname) {
639:       eargs += 2; left -= 2;
640:     } else {
641:       PetscBool nextiskey = PETSC_FALSE;
642:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
643:       if (left < 2 || nextiskey) {
644:         PetscOptionsSetValue(eargs[0],NULL);
645:         eargs++; left--;
646:       } else {
647:         PetscOptionsSetValue(eargs[0],eargs[1]);
648:         eargs += 2; left -= 2;
649:       }
650:     }
651:   }
652:   return(0);
653: }


658: /*@C
659:    PetscOptionsInsert - Inserts into the options database from the command line,
660:                    the environmental variable and a file.

662:    Input Parameters:
663: +  argc - count of number of command line arguments
664: .  args - the command line arguments
665: -  file - optional filename, defaults to ~username/.petscrc

667:    Note:
668:    Since PetscOptionsInsert() is automatically called by PetscInitialize(),
669:    the user does not typically need to call this routine. PetscOptionsInsert()
670:    can be called several times, adding additional entries into the database.

672:    Options Database Keys:
673: +   -options_monitor <optional filename> - print options names and values as they are set
674: .   -options_file <filename> - read options from a file

676:    Level: advanced

678:    Concepts: options database^adding

680: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
681:           PetscInitialize()
682: @*/
683: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
684: {
686:   PetscMPIInt    rank;
687:   char           pfile[PETSC_MAX_PATH_LEN];
688:   PetscBool      flag = PETSC_FALSE;

691:   if (!options) {
692:     fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
693:     MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
694:   }
695:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

697:   options->argc = (argc) ? *argc : 0;
698:   options->args = (args) ? *args : NULL;

700:   if (file && file[0]) {
701:     char fullpath[PETSC_MAX_PATH_LEN];

703:     PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
704:     PetscOptionsInsertFile(PETSC_COMM_WORLD,fullpath,PETSC_TRUE);
705:   }
706:   /*
707:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
708:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
709:   */
710:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
711:   PetscOptionsGetBool(NULL,"-skip_petscrc",&flag,NULL);
712:   if (!flag) {
713:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
714:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
715:     if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
716:     PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
717:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
718:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
719:   }

721:   /* insert environmental options */
722:   {
723:     char   *eoptions = 0;
724:     size_t len       = 0;
725:     if (!rank) {
726:       eoptions = (char*)getenv("PETSC_OPTIONS");
727:       PetscStrlen(eoptions,&len);
728:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
729:     } else {
730:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
731:       if (len) {
732:         PetscMalloc1(len+1,&eoptions);
733:       }
734:     }
735:     if (len) {
736:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
737:       if (rank) eoptions[len] = 0;
738:       PetscOptionsInsertString(eoptions);
739:       if (rank) {PetscFree(eoptions);}
740:     }
741:   }

743: #if defined(PETSC_HAVE_YAML)
744:   char      yaml_file[PETSC_MAX_PATH_LEN];
745:   PetscBool yaml_flg = PETSC_FALSE;
746:   PetscOptionsGetString(NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
747:   if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
748: #endif

750:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
751:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
752:   return(0);
753: }

757: /*@C
758:    PetscOptionsView - Prints the options that have been loaded. This is
759:    useful for debugging purposes.

761:    Logically Collective on PetscViewer

763:    Input Parameter:
764: .  viewer - must be an PETSCVIEWERASCII viewer

766:    Options Database Key:
767: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

769:    Level: advanced

771:    Concepts: options database^printing

773: .seealso: PetscOptionsAllUsed()
774: @*/
775: PetscErrorCode  PetscOptionsView(PetscViewer viewer)
776: {
778:   PetscInt       i;
779:   PetscBool      isascii;

782:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
783:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
784:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

786:   if (!options) {PetscOptionsInsert(0,0,0);}
787:   if (options->N) {
788:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
789:   } else {
790:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
791:   }
792:   for (i=0; i<options->N; i++) {
793:     if (options->values[i]) {
794:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
795:     } else {
796:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
797:     }
798:   }
799:   if (options->N) {
800:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
801:   }
802:   return(0);
803: }

807: /*
808:    Called by error handlers to print options used in run
809: */
810: PetscErrorCode  PetscOptionsViewError(void)
811: {
812:   PetscInt       i;

815:   if (options->N) {
816:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
817:   } else {
818:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
819:   }
820:   for (i=0; i<options->N; i++) {
821:     if (options->values[i]) {
822:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
823:     } else {
824:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
825:     }
826:   }
827:   return(0);
828: }

832: /*@C
833:    PetscOptionsGetAll - Lists all the options the program was run with in a single string.

835:    Not Collective

837:    Output Parameter:
838: .  copts - pointer where string pointer is stored

840:    Notes: the array and each entry in the array should be freed with PetscFree()

842:    Level: advanced

844:    Concepts: options database^listing

846: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
847: @*/
848: PetscErrorCode  PetscOptionsGetAll(char *copts[])
849: {
851:   PetscInt       i;
852:   size_t         len       = 1,lent = 0;
853:   char           *coptions = NULL;

856:   if (!options) {PetscOptionsInsert(0,0,0);}

858:   /* count the length of the required string */
859:   for (i=0; i<options->N; i++) {
860:     PetscStrlen(options->names[i],&lent);
861:     len += 2 + lent;
862:     if (options->values[i]) {
863:       PetscStrlen(options->values[i],&lent);
864:       len += 1 + lent;
865:     }
866:   }
867:   PetscMalloc1(len,&coptions);
868:   coptions[0] = 0;
869:   for (i=0; i<options->N; i++) {
870:     PetscStrcat(coptions,"-");
871:     PetscStrcat(coptions,options->names[i]);
872:     PetscStrcat(coptions," ");
873:     if (options->values[i]) {
874:       PetscStrcat(coptions,options->values[i]);
875:       PetscStrcat(coptions," ");
876:     }
877:   }
878:   *copts = coptions;
879:   return(0);
880: }

884: /*@
885:    PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.

887:    Not Collective, but prefix will only be applied on calling ranks

889:    Input Parameter:
890: .  prefix - The string to append to the existing prefix

892:    Options Database Keys:
893:  +   -prefix_push <some_prefix_> - push the given prefix
894:  -   -prefix_pop - pop the last prefix

896:    Notes:
897:    It is common to use this in conjunction with -options_file as in

899:  $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop

901:    where the files no longer require all options to be prefixed with -system2_.

903: Level: advanced

905: .seealso: PetscOptionsPrefixPop()
906: @*/
907: PetscErrorCode  PetscOptionsPrefixPush(const char prefix[])
908: {
910:   size_t         n;
911:   PetscInt       start;
912:   char           buf[2048];
913:   PetscBool      key;

917:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
918:   buf[0] = '-';
919:   PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
920:   buf[sizeof(buf) - 1] = 0;
921:   PetscOptionsValidKey(buf,&key);
922:   if (!key) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Given prefix \"%s\" not valid (the first character must be a letter, do not include leading '-')",prefix);

924:   if (!options) {PetscOptionsInsert(0,0,0);}
925:   if (options->prefixind >= MAXPREFIXES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum depth of prefix stack %d exceeded, recompile \n src/sys/objects/options.c with larger value for MAXPREFIXES",MAXPREFIXES);
926:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
927:   PetscStrlen(prefix,&n);
928:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
929:   PetscMemcpy(options->prefix+start,prefix,n+1);
930:   options->prefixstack[options->prefixind++] = start+n;
931:   return(0);
932: }

936: /*@
937:    PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details

939:    Not  Collective, but prefix will only be popped on calling ranks

941:    Level: advanced

943: .seealso: PetscOptionsPrefixPush()
944: @*/
945: PetscErrorCode  PetscOptionsPrefixPop(void)
946: {
947:   PetscInt offset;

950:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
951:   options->prefixind--;
952:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
953:   options->prefix[offset] = 0;
954:   return(0);
955: }

959: /*@C
960:     PetscOptionsClear - Removes all options form the database leaving it empty.

962:    Level: developer

964: .seealso: PetscOptionsInsert()
965: @*/
966: PetscErrorCode  PetscOptionsClear(void)
967: {
968:   PetscInt i;

971:   if (!options) return(0);
972:   for (i=0; i<options->N; i++) {
973:     if (options->names[i])  free(options->names[i]);
974:     if (options->values[i]) free(options->values[i]);
975:   }
976:   for (i=0; i<options->Naliases; i++) {
977:     free(options->aliases1[i]);
978:     free(options->aliases2[i]);
979:   }
980:   options->prefix[0] = 0;
981:   options->prefixind = 0;
982:   options->N         = 0;
983:   options->Naliases  = 0;
984:   return(0);
985: }

989: /*@C
990:     PetscOptionsDestroy - Destroys the option database.

992:     Note:
993:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user
994:     typically does not need to call this routine.

996:    Level: developer

998: .seealso: PetscOptionsInsert()
999: @*/
1000: PetscErrorCode  PetscOptionsDestroy(void)
1001: {

1005:   if (!options) return(0);
1006:   PetscOptionsClear();
1007:   free(options);
1008:   options = 0;
1009:   return(0);
1010: }

1014: /*@C
1015:    PetscOptionsSetValue - Sets an option name-value pair in the options
1016:    database, overriding whatever is already present.

1018:    Not collective, but setting values on certain processors could cause problems
1019:    for parallel objects looking for options.

1021:    Input Parameters:
1022: +  name - name of option, this SHOULD have the - prepended
1023: -  value - the option value (not used for all options)

1025:    Level: intermediate

1027:    Note:
1028:    Only some options have values associated with them, such as
1029:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

1031:   Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized

1033:   Concepts: options database^adding option

1035: .seealso: PetscOptionsInsert()
1036: @*/
1037: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
1038: {
1039:   size_t         len;
1041:   PetscInt       N,n,i;
1042:   char           **names;
1043:   char           fullname[2048];
1044:   const char     *name = iname;
1045:   PetscBool      gt,match;

1048:   if (!options) {PetscOptionsInsert(0,0,0);}

1050:   /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
1051:   PetscStrcasecmp(name,"-h",&match);
1052:   if (match) name = "-help";

1054:   name++; /* skip starting hyphen */
1055:   if (options->prefixind > 0) {
1056:     PetscStrncpy(fullname,options->prefix,sizeof(fullname));
1057:     PetscStrncat(fullname,name,sizeof(fullname));
1058:     name = fullname;
1059:   }

1061:   /* check against aliases */
1062:   N = options->Naliases;
1063:   for (i=0; i<N; i++) {
1064:     PetscStrcasecmp(options->aliases1[i],name,&match);
1065:     if (match) {
1066:       name = options->aliases2[i];
1067:       break;
1068:     }
1069:   }

1071:   N     = options->N;
1072:   n     = N;
1073:   names = options->names;

1075:   for (i=0; i<N; i++) {
1076:     PetscStrcasecmp(names[i],name,&match);
1077:     PetscStrgrt(names[i],name,&gt);
1078:     if (match) {
1079:       if (options->values[i]) free(options->values[i]);
1080:       PetscStrlen(value,&len);
1081:       if (len) {
1082:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
1083:         PetscStrcpy(options->values[i],value);
1084:       } else options->values[i] = 0;
1085:       PetscOptionsMonitor(name,value);
1086:       return(0);
1087:     } else if (gt) {
1088:       n = i;
1089:       break;
1090:     }
1091:   }
1092:   if (N >= MAXOPTIONS) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);

1094:   /* shift remaining values down 1 */
1095:   for (i=N; i>n; i--) {
1096:     options->names[i]  = options->names[i-1];
1097:     options->values[i] = options->values[i-1];
1098:     options->used[i]   = options->used[i-1];
1099:   }
1100:   /* insert new name and value */
1101:   PetscStrlen(name,&len);
1102:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
1103:   PetscStrcpy(options->names[n],name);
1104:   PetscStrlen(value,&len);
1105:   if (len) {
1106:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
1107:     PetscStrcpy(options->values[n],value);
1108:   } else options->values[n] = 0;
1109:   options->used[n] = PETSC_FALSE;
1110:   options->N++;
1111:   PetscOptionsMonitor(name,value);
1112:   return(0);
1113: }

1117: /*@C
1118:    PetscOptionsClearValue - Clears an option name-value pair in the options
1119:    database, overriding whatever is already present.

1121:    Not Collective, but setting values on certain processors could cause problems
1122:    for parallel objects looking for options.

1124:    Input Parameter:
1125: .  name - name of option, this SHOULD have the - prepended

1127:    Level: intermediate

1129:    Concepts: options database^removing option
1130: .seealso: PetscOptionsInsert()
1131: @*/
1132: PetscErrorCode  PetscOptionsClearValue(const char iname[])
1133: {
1135:   PetscInt       N,n,i;
1136:   char           **names,*name=(char*)iname;
1137:   PetscBool      gt,match;

1140:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1141:   if (!options) {PetscOptionsInsert(0,0,0);}

1143:   name++;

1145:   N     = options->N; n = 0;
1146:   names = options->names;

1148:   for (i=0; i<N; i++) {
1149:     PetscStrcasecmp(names[i],name,&match);
1150:     PetscStrgrt(names[i],name,&gt);
1151:     if (match) {
1152:       if (options->names[i])  free(options->names[i]);
1153:       if (options->values[i]) free(options->values[i]);
1154:       PetscOptionsMonitor(name,"");
1155:       break;
1156:     } else if (gt) return(0); /* it was not listed */

1158:     n++;
1159:   }
1160:   if (n == N) return(0); /* it was not listed */

1162:   /* shift remaining values down 1 */
1163:   for (i=n; i<N-1; i++) {
1164:     options->names[i]  = options->names[i+1];
1165:     options->values[i] = options->values[i+1];
1166:     options->used[i]   = options->used[i+1];
1167:   }
1168:   options->N--;
1169:   return(0);
1170: }

1174: /*@C
1175:    PetscOptionsSetAlias - Makes a key and alias for another key

1177:    Not Collective, but setting values on certain processors could cause problems
1178:    for parallel objects looking for options.

1180:    Input Parameters:
1181: +  inewname - the alias
1182: -  ioldname - the name that alias will refer to

1184:    Level: advanced

1186: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1187:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1188:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1189:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1190:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1191:           PetscOptionsFList(), PetscOptionsEList()
1192: @*/
1193: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
1194: {
1196:   PetscInt       n = options->Naliases;
1197:   size_t         len;
1198:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

1201:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1202:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1203:   if (n >= MAXALIASES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n  src/sys/objects/options.c with larger value for MAXALIASES",MAXALIASES);

1205:   newname++; oldname++;
1206:   PetscStrlen(newname,&len);
1207:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1208:   PetscStrcpy(options->aliases1[n],newname);
1209:   PetscStrlen(oldname,&len);
1210:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1211:   PetscStrcpy(options->aliases2[n],oldname);
1212:   options->Naliases++;
1213:   return(0);
1214: }

1218: PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool  *flg)
1219: {
1221:   PetscInt       i,N;
1222:   size_t         len;
1223:   char           **names,tmp[256];
1224:   PetscBool      match;

1227:   if (!options) {PetscOptionsInsert(0,0,0);}
1228:   N     = options->N;
1229:   names = options->names;

1231:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);

1233:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1234:   if (pre) {
1235:     char       *ptr   = tmp;
1236:     const char *namep = name;
1237:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1238:     if (name[1] == '-') {
1239:       *ptr++ = '-';
1240:       namep++;
1241:     }
1242:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1243:     tmp[sizeof(tmp)-1] = 0;
1244:     PetscStrlen(tmp,&len);
1245:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1246:   } else {
1247:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1248:     tmp[sizeof(tmp)-1] = 0;
1249:   }
1250: #if defined(PETSC_USE_DEBUG)
1251:   {
1252:     PetscBool valid;
1253:     char      key[sizeof(tmp)+1] = "-";

1255:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1256:     PetscOptionsValidKey(key,&valid);
1257:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1258:   }
1259: #endif

1261:   /* slow search */
1262:   *flg = PETSC_FALSE;
1263:   for (i=0; i<N; i++) {
1264:     PetscStrcasecmp(names[i],tmp,&match);
1265:     if (match) {
1266:       *value           = options->values[i];
1267:       options->used[i] = PETSC_TRUE;
1268:       *flg             = PETSC_TRUE;
1269:       break;
1270:     }
1271:   }
1272:   if (!*flg) {
1273:     PetscInt j,cnt = 0,locs[16],loce[16];
1274:     size_t   n;
1275:     PetscStrlen(tmp,&n);
1276:     /* determine the location and number of all _%d_ in the key */
1277:     for (i=0; i< (PetscInt)n; i++) {
1278:       if (tmp[i] == '_') {
1279:         for (j=i+1; j< (PetscInt)n; j++) {
1280:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1281:           if (tmp[j] == '_' && j > i+1) { /* found a number */
1282:             locs[cnt]   = i+1;
1283:             loce[cnt++] = j+1;
1284:           }
1285:           break;
1286:         }
1287:       }
1288:     }
1289:     if (cnt) {
1290:       char tmp2[256];
1291:       for (i=0; i<cnt; i++) {
1292:         PetscStrcpy(tmp2,"-");
1293:         PetscStrncat(tmp2,tmp,locs[i]);
1294:         PetscStrcat(tmp2,tmp+loce[i]);
1295:         PetscOptionsFindPair_Private(NULL,tmp2,value,flg);
1296:         if (*flg) break;
1297:       }
1298:     }
1299:   }
1300:   return(0);
1301: }

1305: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(const char pre[], const char name[], char *value[], PetscBool *flg)
1306: {
1308:   PetscInt       i,N;
1309:   size_t         len;
1310:   char           **names,tmp[256];
1311:   PetscBool      match;

1314:   if (!options) {PetscOptionsInsert(0,0,0);}
1315:   N     = options->N;
1316:   names = options->names;

1318:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);

1320:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1321:   if (pre) {
1322:     char       *ptr   = tmp;
1323:     const char *namep = name;
1324:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1325:     if (name[1] == '-') {
1326:       *ptr++ = '-';
1327:       namep++;
1328:     }
1329:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1330:     tmp[sizeof(tmp)-1] = 0;
1331:     PetscStrlen(tmp,&len);
1332:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1333:   } else {
1334:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1335:     tmp[sizeof(tmp)-1] = 0;
1336:   }
1337: #if defined(PETSC_USE_DEBUG)
1338:   {
1339:     PetscBool valid;
1340:     char      key[sizeof(tmp)+1] = "-";

1342:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1343:     PetscOptionsValidKey(key,&valid);
1344:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1345:   }
1346: #endif

1348:   /* slow search */
1349:   *flg = PETSC_FALSE;
1350:   PetscStrlen(tmp,&len);
1351:   for (i = 0; i < N; ++i) {
1352:     PetscStrncmp(names[i], tmp, len, &match);
1353:     if (match) {
1354:       if (value) *value = options->values[i];
1355:       options->used[i]  = PETSC_TRUE;
1356:       if (flg)   *flg   = PETSC_TRUE;
1357:       break;
1358:     }
1359:   }
1360:   return(0);
1361: }

1365: /*@C
1366:    PetscOptionsReject - Generates an error if a certain option is given.

1368:    Not Collective, but setting values on certain processors could cause problems
1369:    for parallel objects looking for options.

1371:    Input Parameters:
1372: +  name - the option one is seeking
1373: -  mess - error message (may be NULL)

1375:    Level: advanced

1377:    Concepts: options database^rejecting option

1379: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1380:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1381:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1382:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1383:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1384:           PetscOptionsFList(), PetscOptionsEList()
1385: @*/
1386: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
1387: {
1389:   PetscBool      flag = PETSC_FALSE;

1392:   PetscOptionsHasName(NULL,name,&flag);
1393:   if (flag) {
1394:     if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1395:     else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1396:   }
1397:   return(0);
1398: }

1402: /*@C
1403:    PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1404:                       its value is set to false.

1406:    Not Collective

1408:    Input Parameters:
1409: +  name - the option one is seeking
1410: -  pre - string to prepend to the name or NULL

1412:    Output Parameters:
1413: .  set - PETSC_TRUE if found else PETSC_FALSE.

1415:    Level: beginner

1417:    Concepts: options database^has option name

1419:    Notes: Name cannot be simply -h

1421:           In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.

1423: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1424:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1425:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1426:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1427:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1428:           PetscOptionsFList(), PetscOptionsEList()
1429: @*/
1430: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscBool  *set)
1431: {
1432:   char           *value;
1434:   PetscBool      flag;

1437:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1438:   if (set) *set = flag;
1439:   return(0);
1440: }

1444: /*@C
1445:    PetscOptionsGetInt - Gets the integer value for a particular option in the database.

1447:    Not Collective

1449:    Input Parameters:
1450: +  pre - the string to prepend to the name or NULL
1451: -  name - the option one is seeking

1453:    Output Parameter:
1454: +  ivalue - the integer value to return
1455: -  set - PETSC_TRUE if found, else PETSC_FALSE

1457:    Level: beginner

1459:    Concepts: options database^has int

1461: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1462:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1463:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1464:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1465:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1466:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1467:           PetscOptionsFList(), PetscOptionsEList()
1468: @*/
1469: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool  *set)
1470: {
1471:   char           *value;
1473:   PetscBool      flag;

1478:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1479:   if (flag) {
1480:     if (!value) {
1481:       if (set) *set = PETSC_FALSE;
1482:     } else {
1483:       if (set) *set = PETSC_TRUE;
1484:       PetscOptionsStringToInt(value,ivalue);
1485:     }
1486:   } else {
1487:     if (set) *set = PETSC_FALSE;
1488:   }
1489:   return(0);
1490: }

1494: /*@C
1495:      PetscOptionsGetEList - Puts a list of option values that a single one may be selected from

1497:    Not Collective

1499:    Input Parameters:
1500: +  pre - the string to prepend to the name or NULL
1501: .  opt - option name
1502: .  list - the possible choices (one of these must be selected, anything else is invalid)
1503: .  ntext - number of choices

1505:    Output Parameter:
1506: +  value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1507: -  set - PETSC_TRUE if found, else PETSC_FALSE

1509:    Level: intermediate

1511:    See PetscOptionsFList() for when the choices are given in a PetscFunctionList()

1513:    Concepts: options database^list

1515: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1516:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1517:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1518:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1519:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1520:           PetscOptionsFList(), PetscOptionsEList()
1521: @*/
1522: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool  *set)
1523: {
1525:   size_t         alen,len = 0;
1526:   char           *svalue;
1527:   PetscBool      aset,flg = PETSC_FALSE;
1528:   PetscInt       i;

1531:   for (i=0; i<ntext; i++) {
1532:     PetscStrlen(list[i],&alen);
1533:     if (alen > len) len = alen;
1534:   }
1535:   len += 5; /* a little extra space for user mistypes */
1536:   PetscMalloc1(len,&svalue);
1537:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1538:   if (aset) {
1539:     PetscEListFind(ntext,list,svalue,value,&flg);
1540:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1541:     if (set) *set = PETSC_TRUE;
1542:   } else if (set) *set = PETSC_FALSE;
1543:   PetscFree(svalue);
1544:   return(0);
1545: }

1549: /*@C
1550:    PetscOptionsGetEnum - Gets the enum value for a particular option in the database.

1552:    Not Collective

1554:    Input Parameters:
1555: +  pre - option prefix or NULL
1556: .  opt - option name
1557: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1558: -  defaultv - the default (current) value

1560:    Output Parameter:
1561: +  value - the  value to return
1562: -  set - PETSC_TRUE if found, else PETSC_FALSE

1564:    Level: beginner

1566:    Concepts: options database

1568:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1570:           list is usually something like PCASMTypes or some other predefined list of enum names

1572: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1573:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1574:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1575:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1576:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1577:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1578:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1579: @*/
1580: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool  *set)
1581: {
1583:   PetscInt       ntext = 0,tval;
1584:   PetscBool      fset;

1587:   while (list[ntext++]) {
1588:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1589:   }
1590:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1591:   ntext -= 3;
1592:   PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1593:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1594:   if (fset) *value = (PetscEnum)tval;
1595:   if (set) *set = fset;
1596:   return(0);
1597: }

1601: /*@C
1602:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1603:             option in the database.

1605:    Not Collective

1607:    Input Parameters:
1608: +  pre - the string to prepend to the name or NULL
1609: -  name - the option one is seeking

1611:    Output Parameter:
1612: +  ivalue - the logical value to return
1613: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1615:    Level: beginner

1617:    Notes:
1618:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1619:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1621:        If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1622:      you NEED TO ALWAYS initialize the ivalue.

1624:    Concepts: options database^has logical

1626: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1627:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1628:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1629:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1630:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1631:           PetscOptionsFList(), PetscOptionsEList()
1632: @*/
1633: PetscErrorCode  PetscOptionsGetBool(const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
1634: {
1635:   char           *value;
1636:   PetscBool      flag;

1642:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1643:   if (flag) {
1644:     if (set) *set = PETSC_TRUE;
1645:     if (!value) *ivalue = PETSC_TRUE;
1646:     else {
1647:       PetscOptionsStringToBool(value, ivalue);
1648:     }
1649:   } else {
1650:     if (set) *set = PETSC_FALSE;
1651:   }
1652:   return(0);
1653: }

1657: /*@C
1658:    PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1659:    option in the database.  The values must be separated with commas with
1660:    no intervening spaces.

1662:    Not Collective

1664:    Input Parameters:
1665: +  pre - string to prepend to each name or NULL
1666: .  name - the option one is seeking
1667: -  nmax - maximum number of values to retrieve

1669:    Output Parameter:
1670: +  dvalue - the integer values to return
1671: .  nmax - actual number of values retreived
1672: -  set - PETSC_TRUE if found, else PETSC_FALSE

1674:    Level: beginner

1676:    Concepts: options database^array of ints

1678:    Notes:
1679:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1680:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1682: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1683:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1684:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1685:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1686:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1687:           PetscOptionsFList(), PetscOptionsEList()
1688: @*/
1689: PetscErrorCode  PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
1690: {
1691:   char           *value;
1693:   PetscInt       n = 0;
1694:   PetscBool      flag;
1695:   PetscToken     token;

1700:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1701:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1702:   if (!value) {if (set) *set = PETSC_TRUE;  *nmax = 0; return(0);}

1704:   if (set) *set = PETSC_TRUE;

1706:   PetscTokenCreate(value,',',&token);
1707:   PetscTokenFind(token,&value);
1708:   while (n < *nmax) {
1709:     if (!value) break;
1710:     PetscOptionsStringToBool(value,dvalue);
1711:     PetscTokenFind(token,&value);
1712:     dvalue++;
1713:     n++;
1714:   }
1715:   PetscTokenDestroy(&token);
1716:   *nmax = n;
1717:   return(0);
1718: }

1722: /*@C
1723:    PetscOptionsGetReal - Gets the double precision value for a particular
1724:    option in the database.

1726:    Not Collective

1728:    Input Parameters:
1729: +  pre - string to prepend to each name or NULL
1730: -  name - the option one is seeking

1732:    Output Parameter:
1733: +  dvalue - the double value to return
1734: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

1736:    Note: if the option is given but no value is provided then set is given the value PETSC_FALSE

1738:    Level: beginner

1740:    Concepts: options database^has double

1742: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1743:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1744:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1745:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1746:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1747:           PetscOptionsFList(), PetscOptionsEList()
1748: @*/
1749: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
1750: {
1751:   char           *value;
1753:   PetscBool      flag;

1758:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1759:   if (flag) {
1760:     if (!value) {
1761:       if (set) *set = PETSC_FALSE;
1762:     } else {
1763:       if (set) *set = PETSC_TRUE;
1764:       PetscOptionsStringToReal(value,dvalue);
1765:     }
1766:   } else {
1767:     if (set) *set = PETSC_FALSE;
1768:   }
1769:   return(0);
1770: }

1774: /*@C
1775:    PetscOptionsGetScalar - Gets the scalar value for a particular
1776:    option in the database.

1778:    Not Collective

1780:    Input Parameters:
1781: +  pre - string to prepend to each name or NULL
1782: -  name - the option one is seeking

1784:    Output Parameter:
1785: +  dvalue - the double value to return
1786: -  set - PETSC_TRUE if found, else PETSC_FALSE

1788:    Level: beginner

1790:    Usage:
1791:    A complex number 2+3i must be specified with NO spaces

1793:    Note: if the option is given but no value is provided then set is given the value PETSC_FALSE

1795:    Concepts: options database^has scalar

1797: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1798:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1799:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1800:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1801:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1802:           PetscOptionsFList(), PetscOptionsEList()
1803: @*/
1804: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
1805: {
1806:   char           *value;
1807:   PetscBool      flag;

1813:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1814:   if (flag) {
1815:     if (!value) {
1816:       if (set) *set = PETSC_FALSE;
1817:     } else {
1818: #if !defined(PETSC_USE_COMPLEX)
1819:       PetscOptionsStringToReal(value,dvalue);
1820: #else
1821:       PetscOptionsStringToScalar(value,dvalue);
1822: #endif
1823:       if (set) *set = PETSC_TRUE;
1824:     }
1825:   } else { /* flag */
1826:     if (set) *set = PETSC_FALSE;
1827:   }
1828:   return(0);
1829: }

1833: /*@C
1834:    PetscOptionsGetRealArray - Gets an array of double precision values for a
1835:    particular option in the database.  The values must be separated with
1836:    commas with no intervening spaces.

1838:    Not Collective

1840:    Input Parameters:
1841: +  pre - string to prepend to each name or NULL
1842: .  name - the option one is seeking
1843: -  nmax - maximum number of values to retrieve

1845:    Output Parameters:
1846: +  dvalue - the double values to return
1847: .  nmax - actual number of values retreived
1848: -  set - PETSC_TRUE if found, else PETSC_FALSE

1850:    Level: beginner

1852:    Concepts: options database^array of doubles

1854: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1855:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1856:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1857:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1858:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1859:           PetscOptionsFList(), PetscOptionsEList()
1860: @*/
1861: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool  *set)
1862: {
1863:   char           *value;
1865:   PetscInt       n = 0;
1866:   PetscBool      flag;
1867:   PetscToken     token;

1872:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1873:   if (!flag) {
1874:     if (set) *set = PETSC_FALSE;
1875:     *nmax = 0;
1876:     return(0);
1877:   }
1878:   if (!value) {
1879:     if (set) *set = PETSC_TRUE;
1880:     *nmax = 0;
1881:     return(0);
1882:   }

1884:   if (set) *set = PETSC_TRUE;

1886:   PetscTokenCreate(value,',',&token);
1887:   PetscTokenFind(token,&value);
1888:   while (n < *nmax) {
1889:     if (!value) break;
1890:     PetscOptionsStringToReal(value,dvalue++);
1891:     PetscTokenFind(token,&value);
1892:     n++;
1893:   }
1894:   PetscTokenDestroy(&token);
1895:   *nmax = n;
1896:   return(0);
1897: }

1901: /*@C
1902:    PetscOptionsGetScalarArray - Gets an array of scalars for a
1903:    particular option in the database.  The values must be separated with
1904:    commas with no intervening spaces.

1906:    Not Collective

1908:    Input Parameters:
1909: +  pre - string to prepend to each name or NULL
1910: .  name - the option one is seeking
1911: -  nmax - maximum number of values to retrieve

1913:    Output Parameters:
1914: +  dvalue - the scalar values to return
1915: .  nmax - actual number of values retreived
1916: -  set - PETSC_TRUE if found, else PETSC_FALSE

1918:    Level: beginner

1920:    Concepts: options database^array of doubles

1922: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1923:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1924:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1925:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1926:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1927:           PetscOptionsFList(), PetscOptionsEList()
1928: @*/
1929: PetscErrorCode  PetscOptionsGetScalarArray(const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
1930: {
1931:   char           *value;
1933:   PetscInt       n = 0;
1934:   PetscBool      flag;
1935:   PetscToken     token;

1940:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1941:   if (!flag) {
1942:     if (set) *set = PETSC_FALSE;
1943:     *nmax = 0;
1944:     return(0);
1945:   }
1946:   if (!value) {
1947:     if (set) *set = PETSC_TRUE;
1948:     *nmax = 0;
1949:     return(0);
1950:   }

1952:   if (set) *set = PETSC_TRUE;

1954:   PetscTokenCreate(value,',',&token);
1955:   PetscTokenFind(token,&value);
1956:   while (n < *nmax) {
1957:     if (!value) break;
1958:     PetscOptionsStringToScalar(value,dvalue++);
1959:     PetscTokenFind(token,&value);
1960:     n++;
1961:   }
1962:   PetscTokenDestroy(&token);
1963:   *nmax = n;
1964:   return(0);
1965: }

1969: /*@C
1970:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
1971:    option in the database.

1973:    Not Collective

1975:    Input Parameters:
1976: +  pre - string to prepend to each name or NULL
1977: .  name - the option one is seeking
1978: -  nmax - maximum number of values to retrieve

1980:    Output Parameter:
1981: +  dvalue - the integer values to return
1982: .  nmax - actual number of values retreived
1983: -  set - PETSC_TRUE if found, else PETSC_FALSE

1985:    Level: beginner

1987:    Notes:
1988:    The array can be passed as
1989:    a comma separated list:                                 0,1,2,3,4,5,6,7
1990:    a range (start-end+1):                                  0-8
1991:    a range with given increment (start-end+1:inc):         0-7:2
1992:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

1994:    There must be no intervening spaces between the values.

1996:    Concepts: options database^array of ints

1998: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1999:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2000:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2001:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2002:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2003:           PetscOptionsFList(), PetscOptionsEList()
2004: @*/
2005: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
2006: {
2007:   char           *value;
2009:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2010:   size_t         len;
2011:   PetscBool      flag,foundrange;
2012:   PetscToken     token;

2017:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
2018:   if (!flag) {
2019:     if (set) *set = PETSC_FALSE;
2020:     *nmax = 0;
2021:     return(0);
2022:   }
2023:   if (!value) {
2024:     if (set) *set = PETSC_TRUE;
2025:     *nmax = 0;
2026:     return(0);
2027:   }

2029:   if (set) *set = PETSC_TRUE;

2031:   PetscTokenCreate(value,',',&token);
2032:   PetscTokenFind(token,&value);
2033:   while (n < *nmax) {
2034:     if (!value) break;

2036:     /* look for form  d-D where d and D are integers */
2037:     foundrange = PETSC_FALSE;
2038:     PetscStrlen(value,&len);
2039:     if (value[0] == '-') i=2;
2040:     else i=1;
2041:     for (;i<(int)len; i++) {
2042:       if (value[i] == '-') {
2043:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2044:         value[i] = 0;

2046:         PetscOptionsStringToInt(value,&start);
2047:         inc  = 1;
2048:         j    = i+1;
2049:         for (;j<(int)len; j++) {
2050:           if (value[j] == ':') {
2051:             value[j] = 0;

2053:             PetscOptionsStringToInt(value+j+1,&inc);
2054:             if (inc <= 0) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry,%s cannot have negative increment",n,value+j+1);
2055:             break;
2056:           }
2057:         }
2058:         PetscOptionsStringToInt(value+i+1,&end);
2059:         if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
2060:         nvalues = (end-start)/inc + (end-start)%inc;
2061:         if (n + nvalues  > *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
2062:         for (;start<end; start+=inc) {
2063:           *dvalue = start; dvalue++;n++;
2064:         }
2065:         foundrange = PETSC_TRUE;
2066:         break;
2067:       }
2068:     }
2069:     if (!foundrange) {
2070:       PetscOptionsStringToInt(value,dvalue);
2071:       dvalue++;
2072:       n++;
2073:     }
2074:     PetscTokenFind(token,&value);
2075:   }
2076:   PetscTokenDestroy(&token);
2077:   *nmax = n;
2078:   return(0);
2079: }

2083: /*@C
2084:    PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.

2086:    Not Collective

2088:    Input Parameters:
2089: +  pre - option prefix or NULL
2090: .  name - option name
2091: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2092: -  nmax - maximum number of values to retrieve

2094:    Output Parameters:
2095: +  dvalue - the  enum values to return
2096: .  nmax - actual number of values retreived
2097: -  set - PETSC_TRUE if found, else PETSC_FALSE

2099:    Level: beginner

2101:    Concepts: options database

2103:    Notes:
2104:    The array must be passed as a comma separated list.

2106:    There must be no intervening spaces between the values.

2108:    list is usually something like PCASMTypes or some other predefined list of enum names.

2110: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2111:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2112:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2113:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2114:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2115:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2116: @*/
2117: PetscErrorCode PetscOptionsGetEnumArray(const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2118: {
2119:   char           *svalue;
2120:   PetscInt       n = 0;
2121:   PetscEnum      evalue;
2122:   PetscBool      flag;
2123:   PetscToken     token;


2132:   PetscOptionsFindPair_Private(pre,name,&svalue,&flag);
2133:   if (!flag) {
2134:     if (set) *set = PETSC_FALSE;
2135:     *nmax = 0;
2136:     return(0);
2137:   }
2138:   if (!svalue) {
2139:     if (set) *set = PETSC_TRUE;
2140:     *nmax = 0;
2141:     return(0);
2142:   }
2143:   if (set) *set = PETSC_TRUE;

2145:   PetscTokenCreate(svalue,',',&token);
2146:   PetscTokenFind(token,&svalue);
2147:   while (svalue && n < *nmax) {
2148:     PetscEnumFind(list,svalue,&evalue,&flag);
2149:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2150:     dvalue[n++] = evalue;
2151:     PetscTokenFind(token,&svalue);
2152:   }
2153:   *nmax = n;
2154:   PetscTokenDestroy(&token);
2155:   return(0);
2156: }

2160: /*@C
2161:    PetscOptionsGetString - Gets the string value for a particular option in
2162:    the database.

2164:    Not Collective

2166:    Input Parameters:
2167: +  pre - string to prepend to name or NULL
2168: .  name - the option one is seeking
2169: -  len - maximum length of the string including null termination

2171:    Output Parameters:
2172: +  string - location to copy string
2173: -  set - PETSC_TRUE if found, else PETSC_FALSE

2175:    Level: beginner

2177:    Fortran Note:
2178:    The Fortran interface is slightly different from the C/C++
2179:    interface (len is not used).  Sample usage in Fortran follows
2180: .vb
2181:       character *20 string
2182:       integer   flg, ierr
2183:       call PetscOptionsGetString(NULL_CHARACTER,'-s',string,flg,ierr)
2184: .ve

2186:    Notes: if the option is given but no string is provided then an empty string is returned and set is given the value of PETSC_TRUE

2188:    Concepts: options database^string

2190:     Note:
2191:       Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls).

2193: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2194:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2195:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2196:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2197:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2198:           PetscOptionsFList(), PetscOptionsEList()
2199: @*/
2200: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
2201: {
2202:   char           *value;
2204:   PetscBool      flag;

2209:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
2210:   if (!flag) {
2211:     if (set) *set = PETSC_FALSE;
2212:   } else {
2213:     if (set) *set = PETSC_TRUE;
2214:     if (value) {
2215:       PetscStrncpy(string,value,len);
2216:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
2217:     } else {
2218:       PetscMemzero(string,len);
2219:     }
2220:   }
2221:   return(0);
2222: }

2226: char *PetscOptionsGetStringMatlab(const char pre[],const char name[])
2227: {
2228:   char           *value;
2230:   PetscBool      flag;

2233:   PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
2234:   if (flag) PetscFunctionReturn(value);
2235:   else return(0);
2236: }


2241: /*@C
2242:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2243:    option in the database. The values must be separated with commas with
2244:    no intervening spaces.

2246:    Not Collective

2248:    Input Parameters:
2249: +  pre - string to prepend to name or NULL
2250: .  name - the option one is seeking
2251: -  nmax - maximum number of strings

2253:    Output Parameter:
2254: +  strings - location to copy strings
2255: -  set - PETSC_TRUE if found, else PETSC_FALSE

2257:    Level: beginner

2259:    Notes:
2260:    The user should pass in an array of pointers to char, to hold all the
2261:    strings returned by this function.

2263:    The user is responsible for deallocating the strings that are
2264:    returned. The Fortran interface for this routine is not supported.

2266:    Contributed by Matthew Knepley.

2268:    Concepts: options database^array of strings

2270: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2271:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2272:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2273:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2274:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2275:           PetscOptionsFList(), PetscOptionsEList()
2276: @*/
2277: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
2278: {
2279:   char           *value;
2281:   PetscInt       n;
2282:   PetscBool      flag;
2283:   PetscToken     token;

2288:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
2289:   if (!flag) {
2290:     *nmax = 0;
2291:     if (set) *set = PETSC_FALSE;
2292:     return(0);
2293:   }
2294:   if (!value) {
2295:     *nmax = 0;
2296:     if (set) *set = PETSC_FALSE;
2297:     return(0);
2298:   }
2299:   if (!*nmax) {
2300:     if (set) *set = PETSC_FALSE;
2301:     return(0);
2302:   }
2303:   if (set) *set = PETSC_TRUE;

2305:   PetscTokenCreate(value,',',&token);
2306:   PetscTokenFind(token,&value);
2307:   n    = 0;
2308:   while (n < *nmax) {
2309:     if (!value) break;
2310:     PetscStrallocpy(value,&strings[n]);
2311:     PetscTokenFind(token,&value);
2312:     n++;
2313:   }
2314:   PetscTokenDestroy(&token);
2315:   *nmax = n;
2316:   return(0);
2317: }

2321: /*@C
2322:    PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database

2324:    Not Collective

2326:    Input Parameter:
2327: .    option - string name of option

2329:    Output Parameter:
2330: .   used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database

2332:    Level: advanced

2334: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2335: @*/
2336: PetscErrorCode  PetscOptionsUsed(const char *option,PetscBool *used)
2337: {
2338:   PetscInt       i;

2342:   *used = PETSC_FALSE;
2343:   for (i=0; i<options->N; i++) {
2344:     PetscStrcmp(options->names[i],option,used);
2345:     if (*used) {
2346:       *used = options->used[i];
2347:       break;
2348:     }
2349:   }
2350:   return(0);
2351: }

2355: /*@C
2356:    PetscOptionsAllUsed - Returns a count of the number of options in the
2357:    database that have never been selected.

2359:    Not Collective

2361:    Output Parameter:
2362: .   N - count of options not used

2364:    Level: advanced

2366: .seealso: PetscOptionsView()
2367: @*/
2368: PetscErrorCode  PetscOptionsAllUsed(PetscInt *N)
2369: {
2370:   PetscInt i,n = 0;

2373:   for (i=0; i<options->N; i++) {
2374:     if (!options->used[i]) n++;
2375:   }
2376:   *N = n;
2377:   return(0);
2378: }

2382: /*@
2383:     PetscOptionsLeft - Prints to screen any options that were set and never used.

2385:   Not collective

2387:    Options Database Key:
2388: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

2390:   Level: advanced

2392: .seealso: PetscOptionsAllUsed()
2393: @*/
2394: PetscErrorCode  PetscOptionsLeft(void)
2395: {
2397:   PetscInt       i;

2400:   for (i=0; i<options->N; i++) {
2401:     if (!options->used[i]) {
2402:       if (options->values[i]) {
2403:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2404:       } else {
2405:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2406:       }
2407:     }
2408:   }
2409:   return(0);
2410: }


2415: /*
2416:     PetscOptionsCreate - Creates the empty options database.

2418: */
2419: PetscErrorCode  PetscOptionsCreate(void)
2420: {

2424:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
2425:   PetscMemzero(options,sizeof(PetscOptionsTable));

2427:   options->namegiven      = PETSC_FALSE;
2428:   options->N              = 0;
2429:   options->Naliases       = 0;
2430:   options->numbermonitors = 0;

2432:   return(0);
2433: }

2437: /*@
2438:    PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc

2440:    Collective on PETSC_COMM_WORLD

2442:    Options Database Keys:
2443: +  -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2444:                 available for options set through a file, environment variable, or on
2445:                 the command line. Only options set after PetscInitialize() completes will
2446:                 be monitored.
2447: .  -options_monitor_cancel - cancel all options database monitors

2449:    Notes:
2450:    To see all options, run your program with the -help option or consult Users-Manual: Introduction

2452:    Level: intermediate

2454: .keywords: set, options, database
2455: @*/
2456: PetscErrorCode  PetscOptionsSetFromOptions(void)
2457: {
2458:   PetscBool      flgc = PETSC_FALSE,flgm;
2460:   char           monfilename[PETSC_MAX_PATH_LEN];
2461:   PetscViewer    monviewer;

2464:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2465:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2466:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2467:   PetscOptionsEnd();
2468:   if (flgm) {
2469:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2470:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2471:   }
2472:   if (flgc) { PetscOptionsMonitorCancel(); }
2473:   return(0);
2474: }


2479: /*@C
2480:    PetscOptionsMonitorDefault - Print all options set value events.

2482:    Logically Collective on PETSC_COMM_WORLD

2484:    Input Parameters:
2485: +  name  - option name string
2486: .  value - option value string
2487: -  dummy - unused monitor context

2489:    Level: intermediate

2491: .keywords: PetscOptions, default, monitor

2493: .seealso: PetscOptionsMonitorSet()
2494: @*/
2495: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2496: {
2498:   PetscViewer    viewer = (PetscViewer) dummy;

2501:   if (!viewer) {
2502:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
2503:   }
2504:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2505:   return(0);
2506: }

2510: /*@C
2511:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2512:    modified the PETSc options database.

2514:    Not collective

2516:    Input Parameters:
2517: +  monitor - pointer to function (if this is NULL, it turns off monitoring
2518: .  mctx    - [optional] context for private data for the
2519:              monitor routine (use NULL if no context is desired)
2520: -  monitordestroy - [optional] routine that frees monitor context
2521:           (may be NULL)

2523:    Calling Sequence of monitor:
2524: $     monitor (const char name[], const char value[], void *mctx)

2526: +  name - option name string
2527: .  value - option value string
2528: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

2530:    Options Database Keys:
2531: +    -options_monitor    - sets PetscOptionsMonitorDefault()
2532: -    -options_monitor_cancel - cancels all monitors that have
2533:                           been hardwired into a code by
2534:                           calls to PetscOptionsMonitorSet(), but
2535:                           does not cancel those set via
2536:                           the options database.

2538:    Notes:
2539:    The default is to do nothing.  To print the name and value of options
2540:    being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2541:    with a null monitoring context.

2543:    Several different monitoring routines may be set by calling
2544:    PetscOptionsMonitorSet() multiple times; all will be called in the
2545:    order in which they were set.

2547:    Level: beginner

2549: .keywords: PetscOptions, set, monitor

2551: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2552: @*/
2553: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2554: {
2556:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2557:   options->monitor[options->numbermonitors]          = monitor;
2558:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
2559:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2560:   return(0);
2561: }

2565: /*@
2566:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2568:    Not collective

2570:    Options Database Key:
2571: .  -options_monitor_cancel - Cancels all monitors that have
2572:     been hardwired into a code by calls to PetscOptionsMonitorSet(),
2573:     but does not cancel those set via the options database.

2575:    Level: intermediate

2577: .keywords: PetscOptions, set, monitor

2579: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2580: @*/
2581: PetscErrorCode  PetscOptionsMonitorCancel(void)
2582: {
2584:   PetscInt       i;

2587:   for (i=0; i<options->numbermonitors; i++) {
2588:     if (options->monitordestroy[i]) {
2589:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
2590:     }
2591:   }
2592:   options->numbermonitors = 0;
2593:   return(0);
2594: }

2596: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }

2600: /*@C
2601:   PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed. 

2603:   Collective on PetscObject

2605:   Input Parameters:
2606: + obj   - the object
2607: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
2608: - optionname - option to activate viewing

2610:   Level: intermediate

2612: @*/
2613: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2614: {
2615:   PetscErrorCode    ierr;
2616:   PetscViewer       viewer;
2617:   PetscBool         flg;
2618:   static PetscBool  incall = PETSC_FALSE;
2619:   PetscViewerFormat format;
2620:   char              *prefix;

2623:   if (incall) return(0);
2624:   incall = PETSC_TRUE;
2625:   prefix = bobj ? bobj->prefix : obj->prefix;
2626:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2627:   if (flg) {
2628:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2629:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2630:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2631:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2632:   }
2633:   incall = PETSC_FALSE;
2634:   return(0);
2635: }