Actual source code: options.c

  1: #define PETSC_DLL
  2: /*
  3:    These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
  4:    This provides the low-level interface, the high level interface is in aoptions.c

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

 10:  #include petscsys.h
 11: #if defined(PETSC_HAVE_STDLIB_H)
 12: #include <stdlib.h>
 13: #endif
 14: #if defined(PETSC_HAVE_MALLOC_H)
 15: #include <malloc.h>
 16: #endif
 17: #if defined(PETSC_HAVE_SYS_PARAM_H)
 18: #include "sys/param.h"
 19: #endif

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

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

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

 42: } PetscOptionsTable;


 45: static PetscOptionsTable      *options = 0;

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

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

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

 73:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 74:   if (!tdefault) {
 75:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 76:   }
 77:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 78:   if (!decide) {
 79:     PetscStrcasecmp(name,"DECIDE",&decide);
 80:   }
 81:   PetscStrcasecmp(name,"mouse",&mouse);

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

105: /*
106:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
107: */
108: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
109: {
111:   size_t         len;
112:   PetscTruth     decide,tdefault;

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

118:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
119:   if (!tdefault) {
120:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
121:   }
122:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
123:   if (!decide) {
124:     PetscStrcasecmp(name,"DECIDE",&decide);
125:   }

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

142: /*
143:    PetscOptionsAtol - Converts string to PetscTruth, handles cases like "yes", "no", "true", "false", "0", "1"
144: */
145: PetscErrorCode  PetscOptionsAtol(const char value[], PetscTruth *a)
146: {
147:   PetscTruth     istrue, isfalse;
148:   size_t         len;

152:   PetscStrlen(value, &len);
153:   if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
154:   PetscStrcasecmp(value,"TRUE",&istrue);
155:   if (istrue) {*a = PETSC_TRUE; return(0);}
156:   PetscStrcasecmp(value,"YES",&istrue);
157:   if (istrue) {*a = PETSC_TRUE; return(0);}
158:   PetscStrcasecmp(value,"1",&istrue);
159:   if (istrue) {*a = PETSC_TRUE; return(0);}
160:   PetscStrcasecmp(value,"on",&istrue);
161:   if (istrue) {*a = PETSC_TRUE; return(0);}
162:   PetscStrcasecmp(value,"FALSE",&isfalse);
163:   if (isfalse) {*a = PETSC_FALSE; return(0);}
164:   PetscStrcasecmp(value,"NO",&isfalse);
165:   if (isfalse) {*a = PETSC_FALSE; return(0);}
166:   PetscStrcasecmp(value,"0",&isfalse);
167:   if (isfalse) {*a = PETSC_FALSE; return(0);}
168:   PetscStrcasecmp(value,"off",&isfalse);
169:   if (isfalse) {*a = PETSC_FALSE; return(0);}
170:   SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
171:   return(0);
172: }

176: /*@C
177:     PetscGetProgramName - Gets the name of the running program. 

179:     Not Collective

181:     Input Parameter:
182: .   len - length of the string name

184:     Output Parameter:
185: .   name - the name of the running program

187:    Level: advanced

189:     Notes:
190:     The name of the program is copied into the user-provided character
191:     array of length len.  On some machines the program name includes 
192:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
193: @*/
194: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
195: {

199:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
200:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
201:   PetscStrncpy(name,options->programname,len);
202:   return(0);
203: }

207: PetscErrorCode  PetscSetProgramName(const char name[])
208: {

212:   options->namegiven = PETSC_TRUE;
213:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
214:   return(0);
215: }

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

222:    Input Parameter:
223: .    in_str - string to check if valid

225:    Output Parameter:
226: .    key - PETSC_TRUE if a valid key

228:   Level: intermediate

230: @*/
231: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscTruth *key)
232: {
234:   *key = PETSC_FALSE;
235:   if (!in_str) return(0);
236:   if (in_str[0] != '-') return(0);
237:   if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
238:   *key = PETSC_TRUE;
239:   return(0);
240: }

244: /*@C
245:      PetscOptionsInsertString - Inserts options into the database from a string

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

250:   Input Parameter:
251: .   in_str - string that contains options separated by blanks


254:   Level: intermediate

256:   Contributed by Boyana Norris

258: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
259:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
260:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
261:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
262:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
263:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

265: @*/
266: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
267: {
268:   char           *first,*second;
270:   PetscToken     token;
271:   PetscTruth     key;

274:   PetscTokenCreate(in_str,' ',&token);
275:   PetscTokenFind(token,&first);
276:   while (first) {
277:     PetscOptionsValidKey(first,&key);
278:     if (key) {
279:       PetscTokenFind(token,&second);
280:       PetscOptionsValidKey(second,&key);
281:       if (!key) {
282:         PetscOptionsSetValue(first,second);
283:         PetscTokenFind(token,&first);
284:       } else {
285:         PetscOptionsSetValue(first,PETSC_NULL);
286:         first = second;
287:       }
288:     } else {
289:       PetscTokenFind(token,&first);
290:     }
291:   }
292:   PetscTokenDestroy(token);
293:   return(0);
294: }

296: /*
297:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
298: */
299: static char *Petscgetline(FILE * f)
300: {
301:   size_t size = 0;
302:   size_t len  = 0;
303:   size_t last = 0;
304:   char * buf  = PETSC_NULL;

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


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

327:      Collective on MPI_Comm

329:   Input Parameter:
330: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
331: .   file - name of file
332: -   require - if PETSC_TRUE will generate an error if the file does not exist


335:   Level: intermediate

337: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
338:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
339:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
340:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
341:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
342:           PetscOptionsList(), PetscOptionsEList()

344: @*/
345: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
346: {
347:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
349:   size_t         i,len;
350:   FILE           *fd;
351:   PetscToken     token;
352:   int            err;
353:   char           cmt[3]={'#','!','%'},*cmatch;
354:   PetscMPIInt    rank,cnt=0,acnt=0;

357:   MPI_Comm_rank(comm,&rank);
358:   if (!rank) {
359:     /* Warning: assume a maximum size for all options in a string */
360:     PetscMalloc(128000*sizeof(char),&vstring);
361:     vstring[0] = 0;
362:     PetscMalloc(64000*sizeof(char),&astring);
363:     astring[0] = 0;
364:     cnt     = 0;
365:     acnt    = 0;

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

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

436:   MPI_Bcast(&acnt,1,MPI_INT,0,comm);
437:   if (acnt) {
438:     PetscToken token;
439:     char       *first,*second;

441:     if (rank) {
442:       PetscMalloc((acnt+1)*sizeof(char),&astring);
443:     }
444:     MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
445:     astring[acnt] = 0;
446:     PetscTokenCreate(astring,' ',&token);
447:     PetscTokenFind(token,&first);
448:     while (first) {
449:       PetscTokenFind(token,&second);
450:       PetscOptionsSetAlias(first,second);
451:       PetscTokenFind(token,&first);
452:     }
453:     PetscTokenDestroy(token);
454:   }

456:   MPI_Bcast(&cnt,1,MPI_INT,0,comm);
457:   if (cnt) {
458:     if (rank) {
459:       PetscMalloc((cnt+1)*sizeof(char),&vstring);
460:     }
461:     MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
462:     vstring[cnt] = 0;
463:     PetscOptionsInsertString(vstring);
464:   }
465:   PetscFree(astring);
466:   PetscFree(vstring);
467:   return(0);
468: }

472: /*@C
473:    PetscOptionsInsert - Inserts into the options database from the command line,
474:                    the environmental variable and a file.

476:    Input Parameters:
477: +  argc - count of number of command line arguments
478: .  args - the command line arguments
479: -  file - optional filename, defaults to ~username/.petscrc

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

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

489:    Level: advanced

491:    Concepts: options database^adding

493: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
494:           PetscInitialize()
495: @*/
496: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
497: {
499:   PetscMPIInt    rank;
500:   char           pfile[PETSC_MAX_PATH_LEN];
501:   PetscTruth     flag = PETSC_FALSE;

504:   if (options == PETSC_NULL) {
505:     fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
506:     MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
507:   }
508:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

510:   options->argc     = (argc) ? *argc : 0;
511:   options->args     = (args) ? *args : PETSC_NULL;

513:   if (file) {
514:     PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
515:   }
516:   PetscOptionsGetTruth(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
517:   if (!flag) {
518:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
519:     /* warning: assumes all processes have a home directory or none, but nothing in between */
520:     if (pfile[0]) {
521:       PetscStrcat(pfile,"/.petscrc");
522:       PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
523:     }
524:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
525:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
526:   }

528:   /* insert environmental options */
529:   {
530:     char   *eoptions = 0;
531:     size_t len = 0;
532:     if (!rank) {
533:       eoptions = (char*)getenv("PETSC_OPTIONS");
534:       PetscStrlen(eoptions,&len);
535:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
536:     } else {
537:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
538:       if (len) {
539:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
540:       }
541:     }
542:     if (len) {
543:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
544:       if (rank) eoptions[len] = 0;
545:       PetscOptionsInsertString(eoptions);
546:       if (rank) {PetscFree(eoptions);}
547:     }
548:   }

550:   /* insert command line options */
551:   if (argc && args && *argc) {
552:     int        left    = *argc - 1;
553:     char       **eargs = *args + 1;
554:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

556:     while (left) {
557:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
558:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
559:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
560:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
561:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
562:       isp4 = (PetscTruth) (isp4 || tisp4);
563:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
564:       isp4 = (PetscTruth) (isp4 || tisp4);
565:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

567:       if (eargs[0][0] != '-') {
568:         eargs++; left--;
569:       } else if (isoptions_file) {
570:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
571:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
572:         PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
573:         eargs += 2; left -= 2;

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

598: /*@C
599:    PetscOptionsPrint - Prints the options that have been loaded. This is
600:    useful for debugging purposes.

602:    Collective on PETSC_COMM_WORLD

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

607:    Options Database Key:
608: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

610:    Level: advanced

612:    Concepts: options database^printing

614: .seealso: PetscOptionsAllUsed()
615: @*/
616: PetscErrorCode  PetscOptionsPrint(FILE *fd)
617: {
619:   PetscInt       i;

622:   if (!fd) fd = PETSC_STDOUT;
623:   if (!options) {PetscOptionsInsert(0,0,0);}
624:   if (options->N) {
625:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
626:   } else {
627:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
628:   }
629:   for (i=0; i<options->N; i++) {
630:     if (options->values[i]) {
631:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
632:     } else {
633:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
634:     }
635:   }
636:   if (options->N) {
637:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#End of PETSc Option Table entries\n");
638:   }
639:   return(0);
640: }

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

647:    Not Collective

649:    Output Parameter:
650: .  copts - pointer where string pointer is stored

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

654:    Level: advanced

656:    Concepts: options database^listing

658: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
659: @*/
660: PetscErrorCode  PetscOptionsGetAll(char *copts[])
661: {
663:   PetscInt       i;
664:   size_t         len = 1,lent;
665:   char           *coptions;

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

670:   /* count the length of the required string */
671:   for (i=0; i<options->N; i++) {
672:     PetscStrlen(options->names[i],&lent);
673:     len += 2 + lent;
674:     if (options->values[i]) {
675:       PetscStrlen(options->values[i],&lent);
676:       len += 1 + lent;
677:     }
678:   }
679:   PetscMalloc(len*sizeof(char),&coptions);
680:   coptions[0] = 0;
681:   for (i=0; i<options->N; i++) {
682:     PetscStrcat(coptions,"-");
683:     PetscStrcat(coptions,options->names[i]);
684:     PetscStrcat(coptions," ");
685:     if (options->values[i]) {
686:       PetscStrcat(coptions,options->values[i]);
687:       PetscStrcat(coptions," ");
688:     }
689:   }
690:   *copts = coptions;
691:   return(0);
692: }

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

699:    Level: developer

701: .seealso: PetscOptionsInsert()
702: @*/
703: PetscErrorCode  PetscOptionsClear(void)
704: {
705:   PetscInt i;

708:   if (!options) return(0);
709:   for (i=0; i<options->N; i++) {
710:     if (options->names[i])  free(options->names[i]);
711:     if (options->values[i]) free(options->values[i]);
712:   }
713:   for (i=0; i<options->Naliases; i++) {
714:     free(options->aliases1[i]);
715:     free(options->aliases2[i]);
716:   }
717:   options->N        = 0;
718:   options->Naliases = 0;
719:   return(0);
720: }

724: /*@C
725:     PetscOptionsDestroy - Destroys the option database. 

727:     Note:
728:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
729:     typically does not need to call this routine.

731:    Level: developer

733: .seealso: PetscOptionsInsert()
734: @*/
735: PetscErrorCode  PetscOptionsDestroy(void)
736: {

740:   if (!options) return(0);
741:   PetscOptionsClear();
742:   free(options);
743:   options = 0;
744:   return(0);
745: }

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

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

756:    Input Parameters:
757: +  name - name of option, this SHOULD have the - prepended
758: -  value - the option value (not used for all options)

760:    Level: intermediate

762:    Note:
763:    Only some options have values associated with them, such as
764:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

766:   Concepts: options database^adding option

768: .seealso: PetscOptionsInsert()
769: @*/
770: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
771: {
772:   size_t         len;
774:   PetscInt       N,n,i;
775:   char           **names;
776:   const char     *name = (char*)iname;
777:   PetscTruth     gt,match;

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

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

786:   name++;
787:   /* first check against aliases */
788:   N = options->Naliases;
789:   for (i=0; i<N; i++) {
790:     PetscStrcasecmp(options->aliases1[i],name,&match);
791:     if (match) {
792:       name = options->aliases2[i];
793:       break;
794:     }
795:   }

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

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

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

851:    Input Parameter:
852: .  name - name of option, this SHOULD have the - prepended

854:    Level: intermediate

856:    Concepts: options database^removing option
857: .seealso: PetscOptionsInsert()
858: @*/
859: PetscErrorCode  PetscOptionsClearValue(const char iname[])
860: {
862:   PetscInt       N,n,i;
863:   char           **names,*name=(char*)iname;
864:   PetscTruth     gt,match;

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

870:   name++;

872:   N     = options->N; n = 0;
873:   names = options->names;
874: 
875:   for (i=0; i<N; i++) {
876:     PetscStrcasecmp(names[i],name,&match);
877:     PetscStrgrt(names[i],name,&gt);
878:     if (match) {
879:       if (options->names[i])  free(options->names[i]);
880:       if (options->values[i]) free(options->values[i]);
881:       PetscOptionsMonitor(name,"");
882:       break;
883:     } else if (gt) {
884:       return(0); /* it was not listed */
885:     }
886:     n++;
887:   }
888:   if (n == N) return(0); /* it was not listed */

890:   /* shift remaining values down 1 */
891:   for (i=n; i<N-1; i++) {
892:     options->names[i]  = options->names[i+1];
893:     options->values[i] = options->values[i+1];
894:     options->used[i]   = options->used[i+1];
895:   }
896:   options->N--;
897:   return(0);
898: }

902: /*@C
903:    PetscOptionsSetAlias - Makes a key and alias for another key

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

908:    Input Parameters:
909: +  inewname - the alias
910: -  ioldname - the name that alias will refer to 

912:    Level: advanced

914: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
915:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
916:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
917:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
918:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
919:           PetscOptionsList(), PetscOptionsEList()
920: @*/
921: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
922: {
924:   PetscInt       n = options->Naliases;
925:   size_t         len;
926:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

929:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
930:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
931:   if (n >= MAXALIASES) {
932:     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);
933:   }

935:   newname++; oldname++;
936:   PetscStrlen(newname,&len);
937:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
938:   PetscStrcpy(options->aliases1[n],newname);
939:   PetscStrlen(oldname,&len);
940:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
941:   PetscStrcpy(options->aliases2[n],oldname);
942:   options->Naliases++;
943:   return(0);
944: }

948: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
949: {
951:   PetscInt       i,N;
952:   size_t         len;
953:   char           **names,tmp[256];
954:   PetscTruth     match;

957:   if (!options) {PetscOptionsInsert(0,0,0);}
958:   N = options->N;
959:   names = options->names;

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

963:   /* append prefix to name */
964:   if (pre) {
965:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
966:     PetscStrncpy(tmp,pre,256);
967:     PetscStrlen(tmp,&len);
968:     PetscStrncat(tmp,name+1,256-len-1);
969:   } else {
970:     PetscStrncpy(tmp,name+1,256);
971:   }

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

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

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

1023:    Input Parameters:
1024: +  name - the option one is seeking 
1025: -  mess - error message (may be PETSC_NULL)

1027:    Level: advanced

1029:    Concepts: options database^rejecting option

1031: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1032:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1033:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1034:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1035:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1036:           PetscOptionsList(), PetscOptionsEList()
1037: @*/
1038: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
1039: {
1041:   PetscTruth     flag = PETSC_FALSE;

1044:   PetscOptionsHasName(PETSC_NULL,name,&flag);
1045:   if (flag) {
1046:     if (mess) {
1047:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1048:     } else {
1049:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1050:     }
1051:   }
1052:   return(0);
1053: }

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

1061:    Not Collective

1063:    Input Parameters:
1064: +  name - the option one is seeking 
1065: -  pre - string to prepend to the name or PETSC_NULL

1067:    Output Parameters:
1068: .  flg - PETSC_TRUE if found else PETSC_FALSE.

1070:    Level: beginner

1072:    Concepts: options database^has option name

1074:    Notes: Name cannot be simply -h

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

1078: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1079:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1080:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1081:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1082:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1083:           PetscOptionsList(), PetscOptionsEList()
1084: @*/
1085: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1086: {
1087:   char           *value;
1089:   PetscTruth     flag;

1092:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1093:   if (flg) *flg = flag;
1094:   return(0);
1095: }

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

1102:    Not Collective

1104:    Input Parameters:
1105: +  pre - the string to prepend to the name or PETSC_NULL
1106: -  name - the option one is seeking

1108:    Output Parameter:
1109: +  ivalue - the integer value to return
1110: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1112:    Level: beginner

1114:    Concepts: options database^has int

1116: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1117:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1118:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1119:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1120:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1121:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1122:           PetscOptionsList(), PetscOptionsEList()
1123: @*/
1124: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1125: {
1126:   char           *value;
1128:   PetscTruth     flag;

1133:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1134:   if (flag) {
1135:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1136:     else {
1137:       if (flg) *flg = PETSC_TRUE;
1138:       PetscOptionsAtoi(value,ivalue);
1139:     }
1140:   } else {
1141:     if (flg) *flg = PETSC_FALSE;
1142:   }
1143:   return(0);
1144: }

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

1151:    Not Collective

1153:    Input Parameters:
1154: +  pre - the string to prepend to the name or PETSC_NULL
1155: .  opt - option name
1156: .  list - the possible choices
1157: .  ntext - number of choices

1159:    Output Parameter:
1160: +  value - the index of the value to return
1161: -  set - PETSC_TRUE if found, else PETSC_FALSE
1162:    
1163:    Level: intermediate

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

1167:    Concepts: options database^list

1169: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1170:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1171:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1172:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1173:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1174:           PetscOptionsList(), PetscOptionsEList()
1175: @*/
1176: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1177: {
1179:   size_t         alen,len = 0;
1180:   char           *svalue;
1181:   PetscTruth     aset,flg = PETSC_FALSE;
1182:   PetscInt       i;

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

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

1214:    Not Collective

1216:    Input Parameters:
1217: +  pre - option prefix or PETSC_NULL
1218: .  opt - option name
1219: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1220: -  defaultv - the default (current) value

1222:    Output Parameter:
1223: +  value - the  value to return
1224: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1226:    Level: beginner

1228:    Concepts: options database

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

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

1234: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1235:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1236:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1237:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1238:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1239:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1240:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1241: @*/
1242: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscTruth *set)
1243: {
1245:   PetscInt       ntext = 0,tval;
1246:   PetscTruth     fset;

1249:   while (list[ntext++]) {
1250:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1251:   }
1252:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1253:   ntext -= 3;
1254:   PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1255:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1256:   if (fset) *value = (PetscEnum)tval;
1257:   if (set) *set = fset;
1258:   return(0);
1259: }

1263: /*@C
1264:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1265:             option in the database.

1267:    Not Collective

1269:    Input Parameters:
1270: +  pre - the string to prepend to the name or PETSC_NULL
1271: -  name - the option one is seeking

1273:    Output Parameter:
1274: +  ivalue - the logical value to return
1275: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1277:    Level: beginner

1279:    Notes:
1280:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1281:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1286:    Concepts: options database^has logical

1288: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1289:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1290:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1291:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1292:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1293:           PetscOptionsList(), PetscOptionsEList()
1294: @*/
1295: PetscErrorCode  PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1296: {
1297:   char           *value;
1298:   PetscTruth     flag;

1304:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1305:   if (flag) {
1306:     if (flg) *flg = PETSC_TRUE;
1307:     if (!value) {
1308:       *ivalue = PETSC_TRUE;
1309:     } else {
1310:       PetscOptionsAtol(value, ivalue);
1311:     }
1312:   } else {
1313:     if (flg) *flg = PETSC_FALSE;
1314:   }
1315:   return(0);
1316: }

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

1325:    Not Collective

1327:    Input Parameters:
1328: +  pre - string to prepend to each name or PETSC_NULL
1329: .  name - the option one is seeking
1330: -  nmax - maximum number of values to retrieve

1332:    Output Parameter:
1333: +  dvalue - the integer values to return
1334: .  nmax - actual number of values retreived
1335: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1337:    Level: beginner

1339:    Concepts: options database^array of ints

1341:    Notes:
1342:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1343:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1345: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1346:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1347:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1348:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1349:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1350:           PetscOptionsList(), PetscOptionsEList()
1351: @*/
1352: PetscErrorCode  PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1353: {
1354:   char           *value;
1356:   PetscInt       n = 0;
1357:   PetscTruth     flag;
1358:   PetscToken     token;

1363:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1364:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1365:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1367:   if (flg) *flg = PETSC_TRUE;

1369:   PetscTokenCreate(value,',',&token);
1370:   PetscTokenFind(token,&value);
1371:   while (n < *nmax) {
1372:     if (!value) break;
1373:     PetscOptionsAtol(value,dvalue);
1374:     PetscTokenFind(token,&value);
1375:     dvalue++;
1376:     n++;
1377:   }
1378:   PetscTokenDestroy(token);
1379:   *nmax = n;
1380:   return(0);
1381: }

1385: /*@C
1386:    PetscOptionsGetReal - Gets the double precision value for a particular 
1387:    option in the database.

1389:    Not Collective

1391:    Input Parameters:
1392: +  pre - string to prepend to each name or PETSC_NULL
1393: -  name - the option one is seeking

1395:    Output Parameter:
1396: +  dvalue - the double value to return
1397: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1399:    Level: beginner

1401:    Concepts: options database^has double

1403: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1404:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1405:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1406:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1407:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1408:           PetscOptionsList(), PetscOptionsEList()
1409: @*/
1410: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1411: {
1412:   char           *value;
1414:   PetscTruth     flag;

1419:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1420:   if (flag) {
1421:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1422:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1423:   } else {
1424:     if (flg) *flg = PETSC_FALSE;
1425:   }
1426:   return(0);
1427: }

1431: /*@C
1432:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1433:    option in the database.

1435:    Not Collective

1437:    Input Parameters:
1438: +  pre - string to prepend to each name or PETSC_NULL
1439: -  name - the option one is seeking

1441:    Output Parameter:
1442: +  dvalue - the double value to return
1443: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1445:    Level: beginner

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

1451:    Concepts: options database^has scalar

1453: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1454:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1455:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1456:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1457:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1458:           PetscOptionsList(), PetscOptionsEList()
1459: @*/
1460: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1461: {
1462:   char           *value;
1463:   PetscTruth     flag;

1469:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1470:   if (flag) {
1471:     if (!value) {
1472:       if (flg) *flg = PETSC_FALSE;
1473:     } else {
1474: #if !defined(PETSC_USE_COMPLEX)
1475:       PetscOptionsAtod(value,dvalue);
1476: #else
1477:       PetscReal  re=0.0,im=0.0;
1478:       PetscToken token;
1479:       char       *tvalue = 0;

1481:       PetscTokenCreate(value,',',&token);
1482:       PetscTokenFind(token,&tvalue);
1483:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1484:       PetscOptionsAtod(tvalue,&re);
1485:       PetscTokenFind(token,&tvalue);
1486:       if (!tvalue) { /* Unknown separator used. using only real value */
1487:         *dvalue = re;
1488:       } else {
1489:         PetscOptionsAtod(tvalue,&im);
1490:         *dvalue = re + PETSC_i*im;
1491:       }
1492:       PetscTokenDestroy(token);
1493: #endif
1494:       if (flg) *flg    = PETSC_TRUE;
1495:     }
1496:   } else { /* flag */
1497:     if (flg) *flg = PETSC_FALSE;
1498:   }
1499:   return(0);
1500: }

1504: /*@C
1505:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1506:    particular option in the database.  The values must be separated with 
1507:    commas with no intervening spaces.

1509:    Not Collective

1511:    Input Parameters:
1512: +  pre - string to prepend to each name or PETSC_NULL
1513: .  name - the option one is seeking
1514: -  nmax - maximum number of values to retrieve

1516:    Output Parameters:
1517: +  dvalue - the double value to return
1518: .  nmax - actual number of values retreived
1519: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1521:    Level: beginner

1523:    Concepts: options database^array of doubles

1525: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1526:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1527:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1528:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1529:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1530:           PetscOptionsList(), PetscOptionsEList()
1531: @*/
1532: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1533: {
1534:   char           *value;
1536:   PetscInt       n = 0;
1537:   PetscTruth     flag;
1538:   PetscToken     token;

1543:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1544:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1545:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1547:   if (flg) *flg = PETSC_TRUE;

1549:   PetscTokenCreate(value,',',&token);
1550:   PetscTokenFind(token,&value);
1551:   while (n < *nmax) {
1552:     if (!value) break;
1553:     PetscOptionsAtod(value,dvalue++);
1554:     PetscTokenFind(token,&value);
1555:     n++;
1556:   }
1557:   PetscTokenDestroy(token);
1558:   *nmax = n;
1559:   return(0);
1560: }

1564: /*@C
1565:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1566:    option in the database.  The values must be separated with commas with 
1567:    no intervening spaces. 

1569:    Not Collective

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

1576:    Output Parameter:
1577: +  dvalue - the integer values to return
1578: .  nmax - actual number of values retreived
1579: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1581:    Level: beginner

1583:    Concepts: options database^array of ints

1585: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1586:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1587:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1588:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1589:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1590:           PetscOptionsList(), PetscOptionsEList()
1591: @*/
1592: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1593: {
1594:   char           *value;
1596:   PetscInt       n = 0,i,start,end;
1597:   size_t         len;
1598:   PetscTruth     flag,foundrange;
1599:   PetscToken     token;

1604:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1605:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1606:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1608:   if (flg) *flg = PETSC_TRUE;

1610:   PetscTokenCreate(value,',',&token);
1611:   PetscTokenFind(token,&value);
1612:   while (n < *nmax) {
1613:     if (!value) break;
1614: 
1615:     /* look for form  d-D where d and D are integers */
1616:     foundrange = PETSC_FALSE;
1617:     PetscStrlen(value,&len);
1618:     if (value[0] == '-') i=2;
1619:     else i=1;
1620:     for (;i<(int)len; i++) {
1621:       if (value[i] == '-') {
1622:         if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1623:         value[i] = 0;
1624:         PetscOptionsAtoi(value,&start);
1625:         PetscOptionsAtoi(value+i+1,&end);
1626:         if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1627:         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);
1628:         for (;start<end; start++) {
1629:           *dvalue = start; dvalue++;n++;
1630:         }
1631:         foundrange = PETSC_TRUE;
1632:         break;
1633:       }
1634:     }
1635:     if (!foundrange) {
1636:       PetscOptionsAtoi(value,dvalue);
1637:       dvalue++;
1638:       n++;
1639:     }
1640:     PetscTokenFind(token,&value);
1641:   }
1642:   PetscTokenDestroy(token);
1643:   *nmax = n;
1644:   return(0);
1645: }

1649: /*@C
1650:    PetscOptionsGetString - Gets the string value for a particular option in
1651:    the database.

1653:    Not Collective

1655:    Input Parameters:
1656: +  pre - string to prepend to name or PETSC_NULL
1657: .  name - the option one is seeking
1658: -  len - maximum string length

1660:    Output Parameters:
1661: +  string - location to copy string
1662: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1664:    Level: beginner

1666:    Fortran Note:
1667:    The Fortran interface is slightly different from the C/C++
1668:    interface (len is not used).  Sample usage in Fortran follows
1669: .vb
1670:       character *20 string
1671:       integer   flg, ierr
1672:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1673: .ve

1675:    Concepts: options database^string

1677: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1678:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1679:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1680:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1681:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1682:           PetscOptionsList(), PetscOptionsEList()
1683: @*/
1684: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1685: {
1686:   char           *value;
1688:   PetscTruth     flag;

1693:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1694:   if (!flag) {
1695:     if (flg) *flg = PETSC_FALSE;
1696:   } else {
1697:     if (flg) *flg = PETSC_TRUE;
1698:     if (value) {
1699:       PetscStrncpy(string,value,len);
1700:     } else {
1701:       PetscMemzero(string,len);
1702:     }
1703:   }
1704:   return(0);
1705: }

1709: /*@C
1710:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1711:    option in the database. The values must be separated with commas with 
1712:    no intervening spaces. 

1714:    Not Collective

1716:    Input Parameters:
1717: +  pre - string to prepend to name or PETSC_NULL
1718: .  name - the option one is seeking
1719: -  nmax - maximum number of strings

1721:    Output Parameter:
1722: +  strings - location to copy strings
1723: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1725:    Level: beginner

1727:    Notes: 
1728:    The user should pass in an array of pointers to char, to hold all the
1729:    strings returned by this function.

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

1734:    Contributed by Matthew Knepley.

1736:    Concepts: options database^array of strings

1738: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1739:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1740:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1741:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1742:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1743:           PetscOptionsList(), PetscOptionsEList()
1744: @*/
1745: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1746: {
1747:   char           *value;
1749:   PetscInt       n;
1750:   PetscTruth     flag;
1751:   PetscToken     token;
1752: 
1756:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1757:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1758:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1759:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1760:   if (flg) *flg = PETSC_TRUE;

1762:   PetscTokenCreate(value,',',&token);
1763:   PetscTokenFind(token,&value);
1764:   n = 0;
1765:   while (n < *nmax) {
1766:     if (!value) break;
1767:     PetscStrallocpy(value,&strings[n]);
1768:     PetscTokenFind(token,&value);
1769:     n++;
1770:   }
1771:   PetscTokenDestroy(token);
1772:   *nmax = n;
1773:   return(0);
1774: }

1778: /*@C
1779:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1780:    database that have never been selected.

1782:    Not Collective

1784:    Output Parameter:
1785: .   N - count of options not used

1787:    Level: advanced

1789: .seealso: PetscOptionsPrint()
1790: @*/
1791: PetscErrorCode  PetscOptionsAllUsed(int *N)
1792: {
1793:   PetscInt i,n = 0;

1796:   for (i=0; i<options->N; i++) {
1797:     if (!options->used[i]) { n++; }
1798:   }
1799:   *N = n;
1800:   return(0);
1801: }

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

1808:   Not collective

1810:    Options Database Key:
1811: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1813:   Level: advanced

1815: .seealso: PetscOptionsAllUsed()
1816: @*/
1817: PetscErrorCode  PetscOptionsLeft(void)
1818: {
1820:   PetscInt       i;

1823:   for (i=0; i<options->N; i++) {
1824:     if (!options->used[i]) {
1825:       if (options->values[i]) {
1826:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1827:       } else {
1828:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1829:       }
1830:     }
1831:   }
1832:   return(0);
1833: }


1838: /*
1839:     PetscOptionsCreate - Creates the empty options database.

1841: */
1842: PetscErrorCode  PetscOptionsCreate(void)
1843: {

1847:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1848:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1849:   options->namegiven                 = PETSC_FALSE;
1850:   options->N                         = 0;
1851:   options->Naliases                  = 0;
1852:   options->numbermonitors         = 0;

1854:   PetscOptionsObject.prefix = PETSC_NULL;
1855:   PetscOptionsObject.title  = PETSC_NULL;
1856: 
1857:   return(0);
1858: }

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

1865:    Collective on PETSC_COMM_WORLD

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

1874:    Notes:
1875:    To see all options, run your program with the -help option or consult
1876:    the users manual. 

1878:    Level: intermediate

1880: .keywords: set, options, database
1881: @*/
1882: PetscErrorCode  PetscOptionsSetFromOptions(void)
1883: {
1884:   PetscTruth          flgc,flgm;
1885:   PetscErrorCode      ierr;
1886:   char                monfilename[PETSC_MAX_PATH_LEN];
1887:   PetscViewer         monviewer;

1890:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1891:     PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
1892:     PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flgc);
1893:   PetscOptionsEnd();
1894:   if (flgm) {
1895:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1896:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1897:   }
1898:   if (flgc) { PetscOptionsMonitorCancel(); }
1899:   return(0);
1900: }


1905: /*@C
1906:    PetscOptionsMonitorDefault - Print all options set value events.

1908:    Collective on PETSC_COMM_WORLD

1910:    Input Parameters:
1911: +  name  - option name string
1912: .  value - option value string
1913: -  dummy - unused monitor context 

1915:    Level: intermediate

1917: .keywords: PetscOptions, default, monitor

1919: .seealso: PetscOptionsMonitorSet()
1920: @*/
1921: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1922: {
1924:   PetscViewer    viewer = (PetscViewer) dummy;

1927:   if (!viewer) {
1928:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1929:   }
1930:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1931:   return(0);
1932: }

1936: /*@C
1937:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1938:    modified the PETSc options database.
1939:       
1940:    Not collective

1942:    Input Parameters:
1943: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1944: .  mctx    - [optional] context for private data for the
1945:              monitor routine (use PETSC_NULL if no context is desired)
1946: -  monitordestroy - [optional] routine that frees monitor context
1947:           (may be PETSC_NULL)

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

1952: +  name - option name string
1953: .  value - option value string
1954: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1956:    Options Database Keys:
1957: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1958: -    -options_monitor_cancel - cancels all monitors that have
1959:                           been hardwired into a code by 
1960:                           calls to PetscOptionsMonitorSet(), but
1961:                           does not cancel those set via
1962:                           the options database.

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

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

1973:    Level: beginner

1975: .keywords: PetscOptions, set, monitor

1977: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1978: @*/
1979: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1980: {
1982:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1983:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1984:   }
1985:   options->monitor[options->numbermonitors]           = monitor;
1986:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1987:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1988:   return(0);
1989: }

1993: /*@
1994:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1996:    Not collective 

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

2003:    Level: intermediate

2005: .keywords: PetscOptions, set, monitor

2007: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2008: @*/
2009: PetscErrorCode  PetscOptionsMonitorCancel(void)
2010: {
2012:   PetscInt       i;

2015:   for (i=0; i<options->numbermonitors; i++) {
2016:     if (options->monitordestroy[i]) {
2017:       (*options->monitordestroy[i])(options->monitorcontext[i]);
2018:     }
2019:   }
2020:   options->numbermonitors = 0;
2021:   return(0);
2022: }