Actual source code: options.c

  1: #define PETSC_DLL

  3: /* Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
  4: #define _XOPEN_SOURCE 600
  5: #define _BSD_SOURCE
  6: /*
  7:    These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
  8:    This provides the low-level interface, the high level interface is in aoptions.c

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

 14:  #include petscsys.h
 15: #if defined(PETSC_HAVE_STDLIB_H)
 16: #include <stdlib.h>
 17: #endif
 18: #if defined(PETSC_HAVE_MALLOC_H)
 19: #include <malloc.h>
 20: #endif
 21: #if defined(PETSC_HAVE_SYS_PARAM_H)
 22: #include "sys/param.h"
 23: #endif

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

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

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

 46: } PetscOptionsTable;


 49: static PetscOptionsTable      *options = 0;

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

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

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

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

 87:   if (tdefault) {
 88:     *a = PETSC_DEFAULT;
 89:   } else if (decide) {
 90:     *a = PETSC_DECIDE;
 91:   } else if (mouse) {
 92:     *a = -1;
 93:   } else {
 94:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
 95:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 96:     }
 97:     for (i=1; i<len; i++) {
 98:       if (name[i] < '0' || name[i] > '9') {
 99:         SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
100:       }
101:     }
102: #if defined(PETSC_USE_64BIT_INDICES)
103:     *a = atoll(name);
104: #else
105:     *a = atoi(name);
106: #endif
107:   }
108:   return(0);
109: }

113: /*
114:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
115: */
116: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
117: {
119:   size_t         len;
120:   PetscTruth     decide,tdefault;

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

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

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

150: /*
151:    PetscOptionsAtol - Converts string to PetscTruth, handles cases like "yes", "no", "true", "false", "0", "1"
152: */
153: PetscErrorCode  PetscOptionsAtol(const char value[], PetscTruth *a)
154: {
155:   PetscTruth     istrue, isfalse;
156:   size_t         len;

160:   PetscStrlen(value, &len);
161:   if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
162:   PetscStrcasecmp(value,"TRUE",&istrue);
163:   if (istrue) {*a = PETSC_TRUE; return(0);}
164:   PetscStrcasecmp(value,"YES",&istrue);
165:   if (istrue) {*a = PETSC_TRUE; return(0);}
166:   PetscStrcasecmp(value,"1",&istrue);
167:   if (istrue) {*a = PETSC_TRUE; return(0);}
168:   PetscStrcasecmp(value,"on",&istrue);
169:   if (istrue) {*a = PETSC_TRUE; return(0);}
170:   PetscStrcasecmp(value,"FALSE",&isfalse);
171:   if (isfalse) {*a = PETSC_FALSE; return(0);}
172:   PetscStrcasecmp(value,"NO",&isfalse);
173:   if (isfalse) {*a = PETSC_FALSE; return(0);}
174:   PetscStrcasecmp(value,"0",&isfalse);
175:   if (isfalse) {*a = PETSC_FALSE; return(0);}
176:   PetscStrcasecmp(value,"off",&isfalse);
177:   if (isfalse) {*a = PETSC_FALSE; return(0);}
178:   SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
179:   return(0);
180: }

184: /*@C
185:     PetscGetProgramName - Gets the name of the running program. 

187:     Not Collective

189:     Input Parameter:
190: .   len - length of the string name

192:     Output Parameter:
193: .   name - the name of the running program

195:    Level: advanced

197:     Notes:
198:     The name of the program is copied into the user-provided character
199:     array of length len.  On some machines the program name includes 
200:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
201: @*/
202: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
203: {

207:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
208:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
209:   PetscStrncpy(name,options->programname,len);
210:   return(0);
211: }

215: PetscErrorCode  PetscSetProgramName(const char name[])
216: {

220:   options->namegiven = PETSC_TRUE;
221:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
222:   return(0);
223: }

227: /*@
228:     PetscOptionsValidKey - PETSc Options database keys must begin with a - followed by a letter.

230:    Input Parameter:
231: .    in_str - string to check if valid

233:    Output Parameter:
234: .    key - PETSC_TRUE if a valid key

236:   Level: intermediate

238: @*/
239: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscTruth *key)
240: {
242:   *key = PETSC_FALSE;
243:   if (!in_str) return(0);
244:   if (in_str[0] != '-') return(0);
245:   if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
246:   *key = PETSC_TRUE;
247:   return(0);
248: }

252: /*@C
253:      PetscOptionsInsertString - Inserts options into the database from a string

255:      Not collective: but only processes that call this routine will set the options
256:                      included in the file

258:   Input Parameter:
259: .   in_str - string that contains options separated by blanks


262:   Level: intermediate

264:   Contributed by Boyana Norris

266: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
267:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
268:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
269:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
270:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
271:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

273: @*/
274: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
275: {
276:   char           *first,*second;
278:   PetscToken     token;
279:   PetscTruth     key;

282:   PetscTokenCreate(in_str,' ',&token);
283:   PetscTokenFind(token,&first);
284:   while (first) {
285:     PetscOptionsValidKey(first,&key);
286:     if (key) {
287:       PetscTokenFind(token,&second);
288:       PetscOptionsValidKey(second,&key);
289:       if (!key) {
290:         PetscOptionsSetValue(first,second);
291:         PetscTokenFind(token,&first);
292:       } else {
293:         PetscOptionsSetValue(first,PETSC_NULL);
294:         first = second;
295:       }
296:     } else {
297:       PetscTokenFind(token,&first);
298:     }
299:   }
300:   PetscTokenDestroy(token);
301:   return(0);
302: }

304: /*
305:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
306: */
307: static char *Petscgetline(FILE * f)
308: {
309:   size_t size = 0;
310:   size_t len  = 0;
311:   size_t last = 0;
312:   char * buf  = PETSC_NULL;

314:   if (feof(f)) return 0;
315:   do {
316:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
317:     buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
318:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
319:     end of the string, so we make sure we overwrite this */
320:     if (!fgets(buf+len,size,f)) buf[len]=0;
321:     PetscStrlen(buf,&len);
322:     last = len - 1;
323:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
324:   if (len) return buf;
325:   free(buf);
326:   return 0;
327: }


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

335:      Collective on MPI_Comm

337:   Input Parameter:
338: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
339: .   file - name of file
340: -   require - if PETSC_TRUE will generate an error if the file does not exist


343:   Level: intermediate

345: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
346:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
347:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
348:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
349:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
350:           PetscOptionsList(), PetscOptionsEList()

352: @*/
353: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
354: {
355:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
357:   size_t         i,len;
358:   FILE           *fd;
359:   PetscToken     token;
360:   int            err;
361:   char           cmt[3]={'#','!','%'},*cmatch;
362:   PetscMPIInt    rank,cnt=0,acnt=0;

365:   MPI_Comm_rank(comm,&rank);
366:   if (!rank) {
367:     /* Warning: assume a maximum size for all options in a string */
368:     PetscMalloc(128000*sizeof(char),&vstring);
369:     vstring[0] = 0;
370:     PetscMalloc(64000*sizeof(char),&astring);
371:     astring[0] = 0;
372:     cnt     = 0;
373:     acnt    = 0;

375:     PetscFixFilename(file,fname);
376:     fd   = fopen(fname,"r");
377:     if (fd) {
378:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
379:       PetscInfo1(0,"Opened options file %s\n",file);
380:       while ((string = Petscgetline(fd))) {
381:         /* eliminate comments from each line */
382:         for (i=0; i<3; i++){
383:           PetscStrchr(string,cmt[i],&cmatch);
384:           if (cmatch) *cmatch = 0;
385:         }
386:         PetscStrlen(string,&len);
387:         /* replace tabs, ^M, \n with " " */
388:         for (i=0; i<len; i++) {
389:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
390:             string[i] = ' ';
391:           }
392:         }
393:         PetscTokenCreate(string,' ',&token);
394:         free(string);
395:         PetscTokenFind(token,&first);
396:         if (!first) {
397:           goto destroy;
398:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
399:           PetscTokenFind(token,&first);
400:         }
401:         PetscTokenFind(token,&second);
402:         if (!first) {
403:           goto destroy;
404:         } else if (first[0] == '-') {
405:           /* warning: should be making sure we do not overfill vstring */
406:           PetscStrcat(vstring,first);
407:           PetscStrcat(vstring," ");
408:           if (second) {
409:             /* protect second with quotes in case it contains strings */
410:             PetscStrcat(vstring,"\"");
411:             PetscStrcat(vstring,second);
412:             PetscStrcat(vstring,"\"");
413:           }
414:           PetscStrcat(vstring," ");
415:         } else {
416:           PetscTruth match;

418:           PetscStrcasecmp(first,"alias",&match);
419:           if (match) {
420:             PetscTokenFind(token,&third);
421:             if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
422:             PetscStrcat(astring,second);
423:             PetscStrcat(astring," ");
424:             PetscStrcat(astring,third);
425:             PetscStrcat(astring," ");
426:           } else {
427:             SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
428:           }
429:         }
430:         destroy:
431:         PetscTokenDestroy(token);
432:       }
433:       err = fclose(fd);
434:       if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
435:       PetscStrlen(astring,&len);
436:       acnt = PetscMPIIntCast(len);
437:       PetscStrlen(vstring,&len);
438:       cnt  = PetscMPIIntCast(len);
439:     } else if (require) {
440:       SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
441:     }
442:   }

444:   MPI_Bcast(&acnt,1,MPI_INT,0,comm);
445:   if (acnt) {
446:     PetscToken token;
447:     char       *first,*second;

449:     if (rank) {
450:       PetscMalloc((acnt+1)*sizeof(char),&astring);
451:     }
452:     MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
453:     astring[acnt] = 0;
454:     PetscTokenCreate(astring,' ',&token);
455:     PetscTokenFind(token,&first);
456:     while (first) {
457:       PetscTokenFind(token,&second);
458:       PetscOptionsSetAlias(first,second);
459:       PetscTokenFind(token,&first);
460:     }
461:     PetscTokenDestroy(token);
462:   }

464:   MPI_Bcast(&cnt,1,MPI_INT,0,comm);
465:   if (cnt) {
466:     if (rank) {
467:       PetscMalloc((cnt+1)*sizeof(char),&vstring);
468:     }
469:     MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
470:     vstring[cnt] = 0;
471:     PetscOptionsInsertString(vstring);
472:   }
473:   PetscFree(astring);
474:   PetscFree(vstring);
475:   return(0);
476: }

480: /*@C
481:    PetscOptionsInsert - Inserts into the options database from the command line,
482:                    the environmental variable and a file.

484:    Input Parameters:
485: +  argc - count of number of command line arguments
486: .  args - the command line arguments
487: -  file - optional filename, defaults to ~username/.petscrc

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

494:    Options Database Keys:
495: +   -options_monitor <optional filename> - print options names and values as they are set

497:    Level: advanced

499:    Concepts: options database^adding

501: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
502:           PetscInitialize()
503: @*/
504: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
505: {
507:   PetscMPIInt    rank;
508:   char           pfile[PETSC_MAX_PATH_LEN];
509:   PetscTruth     flag = PETSC_FALSE;

512:   if (options == PETSC_NULL) {
513:     fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
514:     MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
515:   }
516:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

518:   options->argc     = (argc) ? *argc : 0;
519:   options->args     = (args) ? *args : PETSC_NULL;

521:   if (file) {
522:     PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
523:   }
524:   PetscOptionsGetTruth(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
525:   if (!flag) {
526:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
527:     /* warning: assumes all processes have a home directory or none, but nothing in between */
528:     if (pfile[0]) {
529:       PetscStrcat(pfile,"/.petscrc");
530:       PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
531:     }
532:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
533:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
534:   }

536:   /* insert environmental options */
537:   {
538:     char   *eoptions = 0;
539:     size_t len = 0;
540:     if (!rank) {
541:       eoptions = (char*)getenv("PETSC_OPTIONS");
542:       PetscStrlen(eoptions,&len);
543:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
544:     } else {
545:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
546:       if (len) {
547:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
548:       }
549:     }
550:     if (len) {
551:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
552:       if (rank) eoptions[len] = 0;
553:       PetscOptionsInsertString(eoptions);
554:       if (rank) {PetscFree(eoptions);}
555:     }
556:   }

558:   /* insert command line options */
559:   if (argc && args && *argc) {
560:     int        left    = *argc - 1;
561:     char       **eargs = *args + 1;
562:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

564:     while (left) {
565:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
566:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
567:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
568:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
569:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
570:       isp4 = (PetscTruth) (isp4 || tisp4);
571:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
572:       isp4 = (PetscTruth) (isp4 || tisp4);
573:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

575:       if (eargs[0][0] != '-') {
576:         eargs++; left--;
577:       } else if (isoptions_file) {
578:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
579:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
580:         PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
581:         eargs += 2; left -= 2;

583:       /*
584:          These are "bad" options that MPICH, etc put on the command line
585:          we strip them out here.
586:       */
587:       } else if (tisp4 || isp4rmrank) {
588:         eargs += 1; left -= 1;
589:       } else if (isp4 || isp4yourname) {
590:         eargs += 2; left -= 2;
591:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
592:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
593:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
594:         eargs++; left--;
595:       } else {
596:         PetscOptionsSetValue(eargs[0],eargs[1]);
597:         eargs += 2; left -= 2;
598:       }
599:     }
600:   }
601:   return(0);
602: }

606: /*@C
607:    PetscOptionsPrint - Prints the options that have been loaded. This is
608:    useful for debugging purposes.

610:    Collective on PETSC_COMM_WORLD

612:    Input Parameter:
613: .  FILE fd - location to print options (usually stdout or stderr)

615:    Options Database Key:
616: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

618:    Level: advanced

620:    Concepts: options database^printing

622: .seealso: PetscOptionsAllUsed()
623: @*/
624: PetscErrorCode  PetscOptionsPrint(FILE *fd)
625: {
627:   PetscInt       i;

630:   if (!fd) fd = PETSC_STDOUT;
631:   if (!options) {PetscOptionsInsert(0,0,0);}
632:   if (options->N) {
633:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
634:   } else {
635:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
636:   }
637:   for (i=0; i<options->N; i++) {
638:     if (options->values[i]) {
639:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
640:     } else {
641:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
642:     }
643:   }
644:   if (options->N) {
645:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#End of PETSc Option Table entries\n");
646:   }
647:   return(0);
648: }

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

655:    Not Collective

657:    Output Parameter:
658: .  copts - pointer where string pointer is stored

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

662:    Level: advanced

664:    Concepts: options database^listing

666: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
667: @*/
668: PetscErrorCode  PetscOptionsGetAll(char *copts[])
669: {
671:   PetscInt       i;
672:   size_t         len = 1,lent;
673:   char           *coptions;

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

678:   /* count the length of the required string */
679:   for (i=0; i<options->N; i++) {
680:     PetscStrlen(options->names[i],&lent);
681:     len += 2 + lent;
682:     if (options->values[i]) {
683:       PetscStrlen(options->values[i],&lent);
684:       len += 1 + lent;
685:     }
686:   }
687:   PetscMalloc(len*sizeof(char),&coptions);
688:   coptions[0] = 0;
689:   for (i=0; i<options->N; i++) {
690:     PetscStrcat(coptions,"-");
691:     PetscStrcat(coptions,options->names[i]);
692:     PetscStrcat(coptions," ");
693:     if (options->values[i]) {
694:       PetscStrcat(coptions,options->values[i]);
695:       PetscStrcat(coptions," ");
696:     }
697:   }
698:   *copts = coptions;
699:   return(0);
700: }

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

707:    Level: developer

709: .seealso: PetscOptionsInsert()
710: @*/
711: PetscErrorCode  PetscOptionsClear(void)
712: {
713:   PetscInt i;

716:   if (!options) return(0);
717:   for (i=0; i<options->N; i++) {
718:     if (options->names[i])  free(options->names[i]);
719:     if (options->values[i]) free(options->values[i]);
720:   }
721:   for (i=0; i<options->Naliases; i++) {
722:     free(options->aliases1[i]);
723:     free(options->aliases2[i]);
724:   }
725:   options->N        = 0;
726:   options->Naliases = 0;
727:   return(0);
728: }

732: /*@C
733:     PetscOptionsDestroy - Destroys the option database. 

735:     Note:
736:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
737:     typically does not need to call this routine.

739:    Level: developer

741: .seealso: PetscOptionsInsert()
742: @*/
743: PetscErrorCode  PetscOptionsDestroy(void)
744: {

748:   if (!options) return(0);
749:   PetscOptionsClear();
750:   free(options);
751:   options = 0;
752:   return(0);
753: }

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

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

764:    Input Parameters:
765: +  name - name of option, this SHOULD have the - prepended
766: -  value - the option value (not used for all options)

768:    Level: intermediate

770:    Note:
771:    Only some options have values associated with them, such as
772:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

774:   Concepts: options database^adding option

776: .seealso: PetscOptionsInsert()
777: @*/
778: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
779: {
780:   size_t         len;
782:   PetscInt       N,n,i;
783:   char           **names;
784:   const char     *name = (char*)iname;
785:   PetscTruth     gt,match;

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

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

794:   name++;
795:   /* first check against aliases */
796:   N = options->Naliases;
797:   for (i=0; i<N; i++) {
798:     PetscStrcasecmp(options->aliases1[i],name,&match);
799:     if (match) {
800:       name = options->aliases2[i];
801:       break;
802:     }
803:   }

805:   N     = options->N;
806:   n     = N;
807:   names = options->names;
808: 
809:   for (i=0; i<N; i++) {
810:     PetscStrcasecmp(names[i],name,&match);
811:     PetscStrgrt(names[i],name,&gt);
812:     if (match) {
813:       if (options->values[i]) free(options->values[i]);
814:       PetscStrlen(value,&len);
815:       if (len) {
816:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
817:         PetscStrcpy(options->values[i],value);
818:       } else { options->values[i] = 0;}
819:       PetscOptionsMonitor(name,value);
820:       return(0);
821:     } else if (gt) {
822:       n = i;
823:       break;
824:     }
825:   }
826:   if (N >= MAXOPTIONS) {
827:     SETERRQ1(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);
828:   }
829:   /* shift remaining values down 1 */
830:   for (i=N; i>n; i--) {
831:     options->names[i]  = options->names[i-1];
832:     options->values[i] = options->values[i-1];
833:     options->used[i]   = options->used[i-1];
834:   }
835:   /* insert new name and value */
836:   PetscStrlen(name,&len);
837:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
838:   PetscStrcpy(options->names[n],name);
839:   PetscStrlen(value,&len);
840:   if (len) {
841:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
842:     PetscStrcpy(options->values[n],value);
843:   } else {options->values[n] = 0;}
844:   options->used[n] = PETSC_FALSE;
845:   options->N++;
846:   PetscOptionsMonitor(name,value);
847:   return(0);
848: }

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

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

859:    Input Parameter:
860: .  name - name of option, this SHOULD have the - prepended

862:    Level: intermediate

864:    Concepts: options database^removing option
865: .seealso: PetscOptionsInsert()
866: @*/
867: PetscErrorCode  PetscOptionsClearValue(const char iname[])
868: {
870:   PetscInt       N,n,i;
871:   char           **names,*name=(char*)iname;
872:   PetscTruth     gt,match;

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

878:   name++;

880:   N     = options->N; n = 0;
881:   names = options->names;
882: 
883:   for (i=0; i<N; i++) {
884:     PetscStrcasecmp(names[i],name,&match);
885:     PetscStrgrt(names[i],name,&gt);
886:     if (match) {
887:       if (options->names[i])  free(options->names[i]);
888:       if (options->values[i]) free(options->values[i]);
889:       PetscOptionsMonitor(name,"");
890:       break;
891:     } else if (gt) {
892:       return(0); /* it was not listed */
893:     }
894:     n++;
895:   }
896:   if (n == N) return(0); /* it was not listed */

898:   /* shift remaining values down 1 */
899:   for (i=n; i<N-1; i++) {
900:     options->names[i]  = options->names[i+1];
901:     options->values[i] = options->values[i+1];
902:     options->used[i]   = options->used[i+1];
903:   }
904:   options->N--;
905:   return(0);
906: }

910: /*@C
911:    PetscOptionsSetAlias - Makes a key and alias for another key

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

916:    Input Parameters:
917: +  inewname - the alias
918: -  ioldname - the name that alias will refer to 

920:    Level: advanced

922: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
923:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
924:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
925:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
926:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
927:           PetscOptionsList(), PetscOptionsEList()
928: @*/
929: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
930: {
932:   PetscInt       n = options->Naliases;
933:   size_t         len;
934:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

937:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
938:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
939:   if (n >= MAXALIASES) {
940:     SETERRQ1(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);
941:   }

943:   newname++; oldname++;
944:   PetscStrlen(newname,&len);
945:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
946:   PetscStrcpy(options->aliases1[n],newname);
947:   PetscStrlen(oldname,&len);
948:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
949:   PetscStrcpy(options->aliases2[n],oldname);
950:   options->Naliases++;
951:   return(0);
952: }

956: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
957: {
959:   PetscInt       i,N;
960:   size_t         len;
961:   char           **names,tmp[256];
962:   PetscTruth     match;

965:   if (!options) {PetscOptionsInsert(0,0,0);}
966:   N = options->N;
967:   names = options->names;

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

971:   /* append prefix to name */
972:   if (pre) {
973:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
974:     PetscStrncpy(tmp,pre,256);
975:     PetscStrlen(tmp,&len);
976:     PetscStrncat(tmp,name+1,256-len-1);
977:   } else {
978:     PetscStrncpy(tmp,name+1,256);
979:   }

981:   /* slow search */
982:   *flg = PETSC_FALSE;
983:   for (i=0; i<N; i++) {
984:     PetscStrcasecmp(names[i],tmp,&match);
985:     if (match) {
986:        *value           = options->values[i];
987:        options->used[i] = PETSC_TRUE;
988:        *flg             = PETSC_TRUE;
989:        break;
990:      }
991:   }
992:   if (!*flg) {
993:     PetscInt j,cnt = 0,locs[16],loce[16];
994:     size_t   n;
995:     PetscStrlen(tmp,&n);
996:     /* determine the location and number of all _%d_ in the key */
997:     for (i=0; i< (PetscInt)n; i++) {
998:       if (tmp[i] == '_') {
999:         for (j=i+1; j< (PetscInt)n; j++) {
1000:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1001:           if (tmp[j] == '_' && j > i+1) { /* found a number */
1002:             locs[cnt]   = i+1;
1003:             loce[cnt++] = j+1;
1004:           }
1005:           break;
1006:         }
1007:       }
1008:     }
1009:     if (cnt) {
1010:       char tmp2[256];
1011:       for (i=0; i<cnt; i++) {
1012:         PetscStrcpy(tmp2,"-");
1013:         PetscStrncat(tmp2,tmp,locs[i]);
1014:         PetscStrcat(tmp2,tmp+loce[i]);
1015:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1016:         if (*flg) break;
1017:       }
1018:     }
1019:   }
1020:   return(0);
1021: }

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

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

1031:    Input Parameters:
1032: +  name - the option one is seeking 
1033: -  mess - error message (may be PETSC_NULL)

1035:    Level: advanced

1037:    Concepts: options database^rejecting option

1039: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1040:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1041:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1042:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1043:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1044:           PetscOptionsList(), PetscOptionsEList()
1045: @*/
1046: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
1047: {
1049:   PetscTruth     flag = PETSC_FALSE;

1052:   PetscOptionsHasName(PETSC_NULL,name,&flag);
1053:   if (flag) {
1054:     if (mess) {
1055:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1056:     } else {
1057:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1058:     }
1059:   }
1060:   return(0);
1061: }

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

1069:    Not Collective

1071:    Input Parameters:
1072: +  name - the option one is seeking 
1073: -  pre - string to prepend to the name or PETSC_NULL

1075:    Output Parameters:
1076: .  flg - PETSC_TRUE if found else PETSC_FALSE.

1078:    Level: beginner

1080:    Concepts: options database^has option name

1082:    Notes: Name cannot be simply -h

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

1086: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1087:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1088:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1089:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1090:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1091:           PetscOptionsList(), PetscOptionsEList()
1092: @*/
1093: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1094: {
1095:   char           *value;
1097:   PetscTruth     flag;

1100:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1101:   if (flg) *flg = flag;
1102:   return(0);
1103: }

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

1110:    Not Collective

1112:    Input Parameters:
1113: +  pre - the string to prepend to the name or PETSC_NULL
1114: -  name - the option one is seeking

1116:    Output Parameter:
1117: +  ivalue - the integer value to return
1118: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1120:    Level: beginner

1122:    Concepts: options database^has int

1124: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1125:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1126:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1127:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1128:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1129:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1130:           PetscOptionsList(), PetscOptionsEList()
1131: @*/
1132: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1133: {
1134:   char           *value;
1136:   PetscTruth     flag;

1141:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1142:   if (flag) {
1143:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1144:     else {
1145:       if (flg) *flg = PETSC_TRUE;
1146:       PetscOptionsAtoi(value,ivalue);
1147:     }
1148:   } else {
1149:     if (flg) *flg = PETSC_FALSE;
1150:   }
1151:   return(0);
1152: }

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

1159:    Not Collective

1161:    Input Parameters:
1162: +  pre - the string to prepend to the name or PETSC_NULL
1163: .  opt - option name
1164: .  list - the possible choices
1165: .  ntext - number of choices

1167:    Output Parameter:
1168: +  value - the index of the value to return
1169: -  set - PETSC_TRUE if found, else PETSC_FALSE
1170:    
1171:    Level: intermediate

1173:    See PetscOptionsList() for when the choices are given in a PetscFList()

1175:    Concepts: options database^list

1177: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1178:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1179:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1180:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1181:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1182:           PetscOptionsList(), PetscOptionsEList()
1183: @*/
1184: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1185: {
1187:   size_t         alen,len = 0;
1188:   char           *svalue;
1189:   PetscTruth     aset,flg = PETSC_FALSE;
1190:   PetscInt       i;

1193:   for ( i=0; i<ntext; i++) {
1194:     PetscStrlen(list[i],&alen);
1195:     if (alen > len) len = alen;
1196:   }
1197:   len += 5; /* a little extra space for user mistypes */
1198:   PetscMalloc(len*sizeof(char),&svalue);
1199:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1200:   if (aset) {
1201:     if (set) *set = PETSC_TRUE;
1202:     for (i=0; i<ntext; i++) {
1203:       PetscStrcasecmp(svalue,list[i],&flg);
1204:       if (flg) {
1205:         *value = i;
1206:         break;
1207:       }
1208:     }
1209:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1210:   } else if (set) {
1211:     *set = PETSC_FALSE;
1212:   }
1213:   PetscFree(svalue);
1214:   return(0);
1215: }

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

1222:    Not Collective

1224:    Input Parameters:
1225: +  pre - option prefix or PETSC_NULL
1226: .  opt - option name
1227: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1228: -  defaultv - the default (current) value

1230:    Output Parameter:
1231: +  value - the  value to return
1232: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1234:    Level: beginner

1236:    Concepts: options database

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

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

1242: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1243:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1244:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1245:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1246:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1247:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1248:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1249: @*/
1250: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscTruth *set)
1251: {
1253:   PetscInt       ntext = 0,tval;
1254:   PetscTruth     fset;

1257:   while (list[ntext++]) {
1258:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1259:   }
1260:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1261:   ntext -= 3;
1262:   PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1263:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1264:   if (fset) *value = (PetscEnum)tval;
1265:   if (set) *set = fset;
1266:   return(0);
1267: }

1271: /*@C
1272:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1273:             option in the database.

1275:    Not Collective

1277:    Input Parameters:
1278: +  pre - the string to prepend to the name or PETSC_NULL
1279: -  name - the option one is seeking

1281:    Output Parameter:
1282: +  ivalue - the logical value to return
1283: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1285:    Level: beginner

1287:    Notes:
1288:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1289:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1294:    Concepts: options database^has logical

1296: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1297:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1298:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1299:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1300:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1301:           PetscOptionsList(), PetscOptionsEList()
1302: @*/
1303: PetscErrorCode  PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1304: {
1305:   char           *value;
1306:   PetscTruth     flag;

1312:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1313:   if (flag) {
1314:     if (flg) *flg = PETSC_TRUE;
1315:     if (!value) {
1316:       *ivalue = PETSC_TRUE;
1317:     } else {
1318:       PetscOptionsAtol(value, ivalue);
1319:     }
1320:   } else {
1321:     if (flg) *flg = PETSC_FALSE;
1322:   }
1323:   return(0);
1324: }

1328: /*@C
1329:    PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular 
1330:    option in the database.  The values must be separated with commas with 
1331:    no intervening spaces. 

1333:    Not Collective

1335:    Input Parameters:
1336: +  pre - string to prepend to each name or PETSC_NULL
1337: .  name - the option one is seeking
1338: -  nmax - maximum number of values to retrieve

1340:    Output Parameter:
1341: +  dvalue - the integer values to return
1342: .  nmax - actual number of values retreived
1343: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1345:    Level: beginner

1347:    Concepts: options database^array of ints

1349:    Notes:
1350:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1351:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1353: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1354:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1355:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1356:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1357:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1358:           PetscOptionsList(), PetscOptionsEList()
1359: @*/
1360: PetscErrorCode  PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1361: {
1362:   char           *value;
1364:   PetscInt       n = 0;
1365:   PetscTruth     flag;
1366:   PetscToken     token;

1371:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1372:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1373:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1375:   if (flg) *flg = PETSC_TRUE;

1377:   PetscTokenCreate(value,',',&token);
1378:   PetscTokenFind(token,&value);
1379:   while (n < *nmax) {
1380:     if (!value) break;
1381:     PetscOptionsAtol(value,dvalue);
1382:     PetscTokenFind(token,&value);
1383:     dvalue++;
1384:     n++;
1385:   }
1386:   PetscTokenDestroy(token);
1387:   *nmax = n;
1388:   return(0);
1389: }

1393: /*@C
1394:    PetscOptionsGetReal - Gets the double precision value for a particular 
1395:    option in the database.

1397:    Not Collective

1399:    Input Parameters:
1400: +  pre - string to prepend to each name or PETSC_NULL
1401: -  name - the option one is seeking

1403:    Output Parameter:
1404: +  dvalue - the double value to return
1405: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1407:    Level: beginner

1409:    Concepts: options database^has double

1411: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1412:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1413:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1414:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1415:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1416:           PetscOptionsList(), PetscOptionsEList()
1417: @*/
1418: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1419: {
1420:   char           *value;
1422:   PetscTruth     flag;

1427:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1428:   if (flag) {
1429:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1430:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1431:   } else {
1432:     if (flg) *flg = PETSC_FALSE;
1433:   }
1434:   return(0);
1435: }

1439: /*@C
1440:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1441:    option in the database.

1443:    Not Collective

1445:    Input Parameters:
1446: +  pre - string to prepend to each name or PETSC_NULL
1447: -  name - the option one is seeking

1449:    Output Parameter:
1450: +  dvalue - the double value to return
1451: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1453:    Level: beginner

1455:    Usage:
1456:    A complex number 2+3i can be specified as 2,3 at the command line.
1457:    or a number 2.0e-10 - 3.3e-20 i  can be specified as 2.0e-10,3.3e-20

1459:    Concepts: options database^has scalar

1461: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1462:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1463:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1464:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1465:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1466:           PetscOptionsList(), PetscOptionsEList()
1467: @*/
1468: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1469: {
1470:   char           *value;
1471:   PetscTruth     flag;

1477:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1478:   if (flag) {
1479:     if (!value) {
1480:       if (flg) *flg = PETSC_FALSE;
1481:     } else {
1482: #if !defined(PETSC_USE_COMPLEX)
1483:       PetscOptionsAtod(value,dvalue);
1484: #else
1485:       PetscReal  re=0.0,im=0.0;
1486:       PetscToken token;
1487:       char       *tvalue = 0;

1489:       PetscTokenCreate(value,',',&token);
1490:       PetscTokenFind(token,&tvalue);
1491:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1492:       PetscOptionsAtod(tvalue,&re);
1493:       PetscTokenFind(token,&tvalue);
1494:       if (!tvalue) { /* Unknown separator used. using only real value */
1495:         *dvalue = re;
1496:       } else {
1497:         PetscOptionsAtod(tvalue,&im);
1498:         *dvalue = re + PETSC_i*im;
1499:       }
1500:       PetscTokenDestroy(token);
1501: #endif
1502:       if (flg) *flg    = PETSC_TRUE;
1503:     }
1504:   } else { /* flag */
1505:     if (flg) *flg = PETSC_FALSE;
1506:   }
1507:   return(0);
1508: }

1512: /*@C
1513:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1514:    particular option in the database.  The values must be separated with 
1515:    commas with no intervening spaces.

1517:    Not Collective

1519:    Input Parameters:
1520: +  pre - string to prepend to each name or PETSC_NULL
1521: .  name - the option one is seeking
1522: -  nmax - maximum number of values to retrieve

1524:    Output Parameters:
1525: +  dvalue - the double value to return
1526: .  nmax - actual number of values retreived
1527: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1529:    Level: beginner

1531:    Concepts: options database^array of doubles

1533: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1534:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1535:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1536:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1537:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1538:           PetscOptionsList(), PetscOptionsEList()
1539: @*/
1540: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1541: {
1542:   char           *value;
1544:   PetscInt       n = 0;
1545:   PetscTruth     flag;
1546:   PetscToken     token;

1551:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1552:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1553:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1555:   if (flg) *flg = PETSC_TRUE;

1557:   PetscTokenCreate(value,',',&token);
1558:   PetscTokenFind(token,&value);
1559:   while (n < *nmax) {
1560:     if (!value) break;
1561:     PetscOptionsAtod(value,dvalue++);
1562:     PetscTokenFind(token,&value);
1563:     n++;
1564:   }
1565:   PetscTokenDestroy(token);
1566:   *nmax = n;
1567:   return(0);
1568: }

1572: /*@C
1573:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1574:    option in the database.  The values must be separated with commas with 
1575:    no intervening spaces. 

1577:    Not Collective

1579:    Input Parameters:
1580: +  pre - string to prepend to each name or PETSC_NULL
1581: .  name - the option one is seeking
1582: -  nmax - maximum number of values to retrieve, can include d-D to indicate d,d+1,..,D-1

1584:    Output Parameter:
1585: +  dvalue - the integer values to return
1586: .  nmax - actual number of values retreived
1587: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1589:    Level: beginner

1591:    Concepts: options database^array of ints

1593: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1594:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1595:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1596:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1597:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1598:           PetscOptionsList(), PetscOptionsEList()
1599: @*/
1600: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1601: {
1602:   char           *value;
1604:   PetscInt       n = 0,i,start,end;
1605:   size_t         len;
1606:   PetscTruth     flag,foundrange;
1607:   PetscToken     token;

1612:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1613:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1614:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1616:   if (flg) *flg = PETSC_TRUE;

1618:   PetscTokenCreate(value,',',&token);
1619:   PetscTokenFind(token,&value);
1620:   while (n < *nmax) {
1621:     if (!value) break;
1622: 
1623:     /* look for form  d-D where d and D are integers */
1624:     foundrange = PETSC_FALSE;
1625:     PetscStrlen(value,&len);
1626:     if (value[0] == '-') i=2;
1627:     else i=1;
1628:     for (;i<(int)len; i++) {
1629:       if (value[i] == '-') {
1630:         if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1631:         value[i] = 0;
1632:         PetscOptionsAtoi(value,&start);
1633:         PetscOptionsAtoi(value+i+1,&end);
1634:         if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1635:         if (n + end - start - 1 >= *nmax) SETERRQ4(PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
1636:         for (;start<end; start++) {
1637:           *dvalue = start; dvalue++;n++;
1638:         }
1639:         foundrange = PETSC_TRUE;
1640:         break;
1641:       }
1642:     }
1643:     if (!foundrange) {
1644:       PetscOptionsAtoi(value,dvalue);
1645:       dvalue++;
1646:       n++;
1647:     }
1648:     PetscTokenFind(token,&value);
1649:   }
1650:   PetscTokenDestroy(token);
1651:   *nmax = n;
1652:   return(0);
1653: }

1657: /*@C
1658:    PetscOptionsGetString - Gets the string value for a particular option in
1659:    the database.

1661:    Not Collective

1663:    Input Parameters:
1664: +  pre - string to prepend to name or PETSC_NULL
1665: .  name - the option one is seeking
1666: -  len - maximum string length

1668:    Output Parameters:
1669: +  string - location to copy string
1670: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1672:    Level: beginner

1674:    Fortran Note:
1675:    The Fortran interface is slightly different from the C/C++
1676:    interface (len is not used).  Sample usage in Fortran follows
1677: .vb
1678:       character *20 string
1679:       integer   flg, ierr
1680:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1681: .ve

1683:    Concepts: options database^string

1685: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1686:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1687:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1688:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1689:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1690:           PetscOptionsList(), PetscOptionsEList()
1691: @*/
1692: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1693: {
1694:   char           *value;
1696:   PetscTruth     flag;

1701:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1702:   if (!flag) {
1703:     if (flg) *flg = PETSC_FALSE;
1704:   } else {
1705:     if (flg) *flg = PETSC_TRUE;
1706:     if (value) {
1707:       PetscStrncpy(string,value,len);
1708:     } else {
1709:       PetscMemzero(string,len);
1710:     }
1711:   }
1712:   return(0);
1713: }

1717: /*@C
1718:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1719:    option in the database. The values must be separated with commas with 
1720:    no intervening spaces. 

1722:    Not Collective

1724:    Input Parameters:
1725: +  pre - string to prepend to name or PETSC_NULL
1726: .  name - the option one is seeking
1727: -  nmax - maximum number of strings

1729:    Output Parameter:
1730: +  strings - location to copy strings
1731: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1733:    Level: beginner

1735:    Notes: 
1736:    The user should pass in an array of pointers to char, to hold all the
1737:    strings returned by this function.

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

1742:    Contributed by Matthew Knepley.

1744:    Concepts: options database^array of strings

1746: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1747:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1748:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1749:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1750:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1751:           PetscOptionsList(), PetscOptionsEList()
1752: @*/
1753: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1754: {
1755:   char           *value;
1757:   PetscInt       n;
1758:   PetscTruth     flag;
1759:   PetscToken     token;
1760: 
1764:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1765:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1766:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1767:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1768:   if (flg) *flg = PETSC_TRUE;

1770:   PetscTokenCreate(value,',',&token);
1771:   PetscTokenFind(token,&value);
1772:   n = 0;
1773:   while (n < *nmax) {
1774:     if (!value) break;
1775:     PetscStrallocpy(value,&strings[n]);
1776:     PetscTokenFind(token,&value);
1777:     n++;
1778:   }
1779:   PetscTokenDestroy(token);
1780:   *nmax = n;
1781:   return(0);
1782: }

1786: /*@C
1787:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1788:    database that have never been selected.

1790:    Not Collective

1792:    Output Parameter:
1793: .   N - count of options not used

1795:    Level: advanced

1797: .seealso: PetscOptionsPrint()
1798: @*/
1799: PetscErrorCode  PetscOptionsAllUsed(int *N)
1800: {
1801:   PetscInt i,n = 0;

1804:   for (i=0; i<options->N; i++) {
1805:     if (!options->used[i]) { n++; }
1806:   }
1807:   *N = n;
1808:   return(0);
1809: }

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

1816:   Not collective

1818:    Options Database Key:
1819: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1821:   Level: advanced

1823: .seealso: PetscOptionsAllUsed()
1824: @*/
1825: PetscErrorCode  PetscOptionsLeft(void)
1826: {
1828:   PetscInt       i;

1831:   for (i=0; i<options->N; i++) {
1832:     if (!options->used[i]) {
1833:       if (options->values[i]) {
1834:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1835:       } else {
1836:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1837:       }
1838:     }
1839:   }
1840:   return(0);
1841: }


1846: /*
1847:     PetscOptionsCreate - Creates the empty options database.

1849: */
1850: PetscErrorCode  PetscOptionsCreate(void)
1851: {

1855:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1856:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1857:   options->namegiven                 = PETSC_FALSE;
1858:   options->N                         = 0;
1859:   options->Naliases                  = 0;
1860:   options->numbermonitors         = 0;

1862:   PetscOptionsObject.prefix = PETSC_NULL;
1863:   PetscOptionsObject.title  = PETSC_NULL;
1864: 
1865:   return(0);
1866: }

1870: /*@
1871:    PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.

1873:    Collective on PETSC_COMM_WORLD

1875:    Options Database Keys:
1876: +  -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not 
1877:                 available for options set through a file, environment variable, or on 
1878:                 the command line. Only options set after PetscInitialize completes will 
1879:                 be monitored.
1880: .  -options_monitor_cancel - cancel all options database monitors    

1882:    Notes:
1883:    To see all options, run your program with the -help option or consult
1884:    the users manual. 

1886:    Level: intermediate

1888: .keywords: set, options, database
1889: @*/
1890: PetscErrorCode  PetscOptionsSetFromOptions(void)
1891: {
1892:   PetscTruth          flgc,flgm;
1893:   PetscErrorCode      ierr;
1894:   char                monfilename[PETSC_MAX_PATH_LEN];
1895:   PetscViewer         monviewer;

1898:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1899:     PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
1900:     PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flgc);
1901:   PetscOptionsEnd();
1902:   if (flgm) {
1903:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1904:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1905:   }
1906:   if (flgc) { PetscOptionsMonitorCancel(); }
1907:   return(0);
1908: }


1913: /*@C
1914:    PetscOptionsMonitorDefault - Print all options set value events.

1916:    Collective on PETSC_COMM_WORLD

1918:    Input Parameters:
1919: +  name  - option name string
1920: .  value - option value string
1921: -  dummy - unused monitor context 

1923:    Level: intermediate

1925: .keywords: PetscOptions, default, monitor

1927: .seealso: PetscOptionsMonitorSet()
1928: @*/
1929: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1930: {
1932:   PetscViewer    viewer = (PetscViewer) dummy;

1935:   if (!viewer) {
1936:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1937:   }
1938:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1939:   return(0);
1940: }

1944: /*@C
1945:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1946:    modified the PETSc options database.
1947:       
1948:    Not collective

1950:    Input Parameters:
1951: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1952: .  mctx    - [optional] context for private data for the
1953:              monitor routine (use PETSC_NULL if no context is desired)
1954: -  monitordestroy - [optional] routine that frees monitor context
1955:           (may be PETSC_NULL)

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

1960: +  name - option name string
1961: .  value - option value string
1962: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1964:    Options Database Keys:
1965: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1966: -    -options_monitor_cancel - cancels all monitors that have
1967:                           been hardwired into a code by 
1968:                           calls to PetscOptionsMonitorSet(), but
1969:                           does not cancel those set via
1970:                           the options database.

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

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

1981:    Level: beginner

1983: .keywords: PetscOptions, set, monitor

1985: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1986: @*/
1987: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1988: {
1990:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1991:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1992:   }
1993:   options->monitor[options->numbermonitors]           = monitor;
1994:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1995:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1996:   return(0);
1997: }

2001: /*@
2002:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2004:    Not collective 

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

2011:    Level: intermediate

2013: .keywords: PetscOptions, set, monitor

2015: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2016: @*/
2017: PetscErrorCode  PetscOptionsMonitorCancel(void)
2018: {
2020:   PetscInt       i;

2023:   for (i=0; i<options->numbermonitors; i++) {
2024:     if (options->monitordestroy[i]) {
2025:       (*options->monitordestroy[i])(options->monitorcontext[i]);
2026:     }
2027:   }
2028:   options->numbermonitors = 0;
2029:   return(0);
2030: }