Actual source code: options.c

  1: #define PETSC_DLL
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

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

 23: /* 
 24:     For simplicity, we use a static size database
 25: */
 26: #define MAXOPTIONS 512
 27: #define MAXALIASES 25
 28: #define MAXOPTIONSMONITORS 5

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

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

 44: } PetscOptionsTable;


 47: static PetscOptionsTable *options = 0;


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

 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: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
106: {
108:   size_t         len;
109:   PetscTruth     decide,tdefault;

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

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

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

139: PetscErrorCode  PetscOptionsAtol(const char value[], PetscTruth *a)
140: {
141:   PetscTruth     istrue, isfalse;
142:   size_t         len;

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

170: /*@C
171:     PetscGetProgramName - Gets the name of the running program. 

173:     Not Collective

175:     Input Parameter:
176: .   len - length of the string name

178:     Output Parameter:
179: .   name - the name of the running program

181:    Level: advanced

183:     Notes:
184:     The name of the program is copied into the user-provided character
185:     array of length len.  On some machines the program name includes 
186:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
187: @*/
188: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
189: {

193:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
194:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
195:   PetscStrncpy(name,options->programname,len);
196:   return(0);
197: }

201: PetscErrorCode  PetscSetProgramName(const char name[])
202: {

206:   options->namegiven = PETSC_TRUE;
207:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
208:   return(0);
209: }

213: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscTruth *key)
214: {
216:   *key = PETSC_FALSE;
217:   if (!in_str) return(0);
218:   if (in_str[0] != '-') return(0);
219:   if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
220:   *key = PETSC_TRUE;
221:   return(0);
222: }

226: /*@C
227:      PetscOptionsInsertString - Inserts options into the database from a string

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

232:   Input Parameter:
233: .   in_str - string that contains options separated by blanks


236:   Level: intermediate

238:   Contributed by Boyana Norris

240: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
241:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
242:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
243:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
244:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
245:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

247: @*/
248: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
249: {
250:   char           *first,*second;
252:   PetscToken     token;
253:   PetscTruth     key;

256:   PetscTokenCreate(in_str,' ',&token);
257:   PetscTokenFind(token,&first);
258:   while (first) {
259:     PetscOptionsValidKey(first,&key);
260:     if (key) {
261:       PetscTokenFind(token,&second);
262:       PetscOptionsValidKey(second,&key);
263:       if (!key) {
264:         PetscOptionsSetValue(first,second);
265:         PetscTokenFind(token,&first);
266:       } else {
267:         PetscOptionsSetValue(first,PETSC_NULL);
268:         first = second;
269:       }
270:     } else {
271:       PetscTokenFind(token,&first);
272:     }
273:   }
274:   PetscTokenDestroy(token);
275:   return(0);
276: }

278: static char *Petscgetline(FILE * f)
279: {
280:   size_t size = 0;
281:   size_t len  = 0;
282:   size_t last = 0;
283:   char * buf  = PETSC_NULL;

285:   if (feof(f)) return 0;
286:   do {
287:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
288:     buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
289:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
290:     end of the string, so we make sure we overwrite this */
291:     if (!fgets(buf+len,size,f)) buf[len]=0;
292:     PetscStrlen(buf,&len);
293:     last = len - 1;
294:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
295:   if (len) return buf;
296:   free(buf);
297:   return 0;
298: }


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

306:      Collective on MPI_Comm

308:   Input Parameter:
309: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
310: .   file - name of file
311: -   require - if PETSC_TRUE will generate an error if the file does not exist


314:   Level: intermediate

316: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
317:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
318:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
319:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
320:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
321:           PetscOptionsList(), PetscOptionsEList()

323: @*/
324: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
325: {
326:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
328:   size_t         i,len;
329:   FILE           *fd;
330:   PetscToken     token;
331:   int            err;
332:   char           cmt[3]={'#','!','%'},*cmatch;
333:   PetscMPIInt    rank,cnt=0,acnt=0;

336:   MPI_Comm_rank(comm,&rank);
337:   if (!rank) {
338:     /* Warning: assume a maximum size for all options in a string */
339:     PetscMalloc(128000*sizeof(char),&vstring);
340:     vstring[0] = 0;
341:     PetscMalloc(64000*sizeof(char),&astring);
342:     astring[0] = 0;
343:     cnt     = 0;
344:     acnt    = 0;

346:     PetscFixFilename(file,fname);
347:     fd   = fopen(fname,"r");
348:     if (fd) {
349:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
350:       PetscInfo1(0,"Opened options file %s\n",file);
351:       while ((string = Petscgetline(fd))) {
352:         /* eliminate comments from each line */
353:         for (i=0; i<3; i++){
354:           PetscStrchr(string,cmt[i],&cmatch);
355:           if (cmatch) *cmatch = 0;
356:         }
357:         PetscStrlen(string,&len);
358:         /* replace tabs, ^M, \n with " " */
359:         for (i=0; i<len; i++) {
360:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
361:             string[i] = ' ';
362:           }
363:         }
364:         PetscTokenCreate(string,' ',&token);
365:         free(string);
366:         PetscTokenFind(token,&first);
367:         if (!first) {
368:           goto destroy;
369:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
370:           PetscTokenFind(token,&first);
371:         }
372:         PetscTokenFind(token,&second);
373:         if (!first) {
374:           goto destroy;
375:         } else if (first[0] == '-') {
376:           /* warning: should be making sure we do not overfill vstring */
377:           PetscStrcat(vstring,first);
378:           PetscStrcat(vstring," ");
379:           if (second) {
380:             /* protect second with quotes in case it contains strings */
381:             PetscStrcat(vstring,"\"");
382:             PetscStrcat(vstring,second);
383:             PetscStrcat(vstring,"\"");
384:           }
385:           PetscStrcat(vstring," ");
386:         } else {
387:           PetscTruth match;

389:           PetscStrcasecmp(first,"alias",&match);
390:           if (match) {
391:             PetscTokenFind(token,&third);
392:             if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
393:             PetscStrcat(astring,second);
394:             PetscStrcat(astring," ");
395:             PetscStrcat(astring,third);
396:             PetscStrcat(astring," ");
397:           } else {
398:             SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
399:           }
400:         }
401:         destroy:
402:         PetscTokenDestroy(token);
403:       }
404:       err = fclose(fd);
405:       if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
406:       PetscStrlen(astring,&len);
407:       acnt = PetscMPIIntCast(len);
408:       PetscStrlen(vstring,&len);
409:       cnt  = PetscMPIIntCast(len);
410:     } else if (require) {
411:       SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
412:     }
413:   }

415:   MPI_Bcast(&acnt,1,MPI_INT,0,comm);
416:   if (acnt) {
417:     PetscToken token;
418:     char       *first,*second;

420:     if (rank) {
421:       PetscMalloc((acnt+1)*sizeof(char),&astring);
422:     }
423:     MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
424:     astring[acnt] = 0;
425:     PetscTokenCreate(astring,' ',&token);
426:     PetscTokenFind(token,&first);
427:     while (first) {
428:       PetscTokenFind(token,&second);
429:       PetscOptionsSetAlias(first,second);
430:       PetscTokenFind(token,&first);
431:     }
432:     PetscTokenDestroy(token);
433:   }

435:   MPI_Bcast(&cnt,1,MPI_INT,0,comm);
436:   if (cnt) {
437:     if (rank) {
438:       PetscMalloc((cnt+1)*sizeof(char),&vstring);
439:     }
440:     MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
441:     vstring[cnt] = 0;
442:     PetscOptionsInsertString(vstring);
443:   }
444:   PetscFree(astring);
445:   PetscFree(vstring);
446:   return(0);
447: }

451: /*@C
452:    PetscOptionsInsert - Inserts into the options database from the command line,
453:                    the environmental variable and a file.

455:    Input Parameters:
456: +  argc - count of number of command line arguments
457: .  args - the command line arguments
458: -  file - optional filename, defaults to ~username/.petscrc

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

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

468:    Level: advanced

470:    Concepts: options database^adding

472: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
473:           PetscInitialize()
474: @*/
475: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
476: {
478:   PetscMPIInt    rank;
479:   char           pfile[PETSC_MAX_PATH_LEN];
480:   PetscTruth     flag;

483:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

485:   options->argc     = (argc) ? *argc : 0;
486:   options->args     = (args) ? *args : PETSC_NULL;

488:   if (file) {
489:     PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
490:   }
491:   PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
492:   if (!flag) {
493:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
494:     /* warning: assumes all processes have a home directory or none, but nothing in between */
495:     if (pfile[0]) {
496:       PetscStrcat(pfile,"/.petscrc");
497:       PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
498:     }
499:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
500:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
501:   }

503:   /* insert environmental options */
504:   {
505:     char   *eoptions = 0;
506:     size_t len = 0;
507:     if (!rank) {
508:       eoptions = (char*)getenv("PETSC_OPTIONS");
509:       PetscStrlen(eoptions,&len);
510:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
511:     } else {
512:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
513:       if (len) {
514:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
515:       }
516:     }
517:     if (len) {
518:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
519:       if (rank) eoptions[len] = 0;
520:       PetscOptionsInsertString(eoptions);
521:       if (rank) {PetscFree(eoptions);}
522:     }
523:   }

525:   /* insert command line options */
526:   if (argc && args && *argc) {
527:     int        left    = *argc - 1;
528:     char       **eargs = *args + 1;
529:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

531:     while (left) {
532:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
533:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
534:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
535:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
536:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
537:       isp4 = (PetscTruth) (isp4 || tisp4);
538:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
539:       isp4 = (PetscTruth) (isp4 || tisp4);
540:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

542:       if (eargs[0][0] != '-') {
543:         eargs++; left--;
544:       } else if (isoptions_file) {
545:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
546:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
547:         PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
548:         eargs += 2; left -= 2;

550:       /*
551:          These are "bad" options that MPICH, etc put on the command line
552:          we strip them out here.
553:       */
554:       } else if (tisp4 || isp4rmrank) {
555:         eargs += 1; left -= 1;
556:       } else if (isp4 || isp4yourname) {
557:         eargs += 2; left -= 2;
558:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
559:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
560:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
561:         eargs++; left--;
562:       } else {
563:         PetscOptionsSetValue(eargs[0],eargs[1]);
564:         eargs += 2; left -= 2;
565:       }
566:     }
567:   }
568:   return(0);
569: }

573: /*@C
574:    PetscOptionsPrint - Prints the options that have been loaded. This is
575:    useful for debugging purposes.

577:    Collective on PETSC_COMM_WORLD

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

582:    Options Database Key:
583: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

585:    Level: advanced

587:    Concepts: options database^printing

589: .seealso: PetscOptionsAllUsed()
590: @*/
591: PetscErrorCode  PetscOptionsPrint(FILE *fd)
592: {
594:   PetscInt       i;

597:   if (!fd) fd = PETSC_STDOUT;
598:   if (!options) {PetscOptionsInsert(0,0,0);}
599:   if (options->N) {
600:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
601:   } else {
602:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
603:   }
604:   for (i=0; i<options->N; i++) {
605:     if (options->values[i]) {
606:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
607:     } else {
608:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
609:     }
610:   }
611:   if (options->N) {
612:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#End o PETSc Option Table entries\n");
613:   }
614:   return(0);
615: }

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

622:    Not Collective

624:    Output Parameter:
625: .  copts - pointer where string pointer is stored

627:    Level: advanced

629:    Concepts: options database^listing

631: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
632: @*/
633: PetscErrorCode  PetscOptionsGetAll(char *copts[])
634: {
636:   PetscInt       i;
637:   size_t         len = 1,lent;
638:   char           *coptions;

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

643:   /* count the length of the required string */
644:   for (i=0; i<options->N; i++) {
645:     PetscStrlen(options->names[i],&lent);
646:     len += 2 + lent;
647:     if (options->values[i]) {
648:       PetscStrlen(options->values[i],&lent);
649:       len += 1 + lent;
650:     }
651:   }
652:   PetscMalloc(len*sizeof(char),&coptions);
653:   coptions[0] = 0;
654:   for (i=0; i<options->N; i++) {
655:     PetscStrcat(coptions,"-");
656:     PetscStrcat(coptions,options->names[i]);
657:     PetscStrcat(coptions," ");
658:     if (options->values[i]) {
659:       PetscStrcat(coptions,options->values[i]);
660:       PetscStrcat(coptions," ");
661:     }
662:   }
663:   *copts = coptions;
664:   return(0);
665: }

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

672:    Level: developer

674: .seealso: PetscOptionsInsert()
675: @*/
676: PetscErrorCode  PetscOptionsClear(void)
677: {
678:   PetscInt i;

681:   if (!options) return(0);
682:   for (i=0; i<options->N; i++) {
683:     if (options->names[i])  free(options->names[i]);
684:     if (options->values[i]) free(options->values[i]);
685:   }
686:   for (i=0; i<options->Naliases; i++) {
687:     free(options->aliases1[i]);
688:     free(options->aliases2[i]);
689:   }
690:   options->N        = 0;
691:   options->Naliases = 0;
692:   return(0);
693: }

697: /*@C
698:     PetscOptionsDestroy - Destroys the option database. 

700:     Note:
701:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
702:     typically does not need to call this routine.

704:    Level: developer

706: .seealso: PetscOptionsInsert()
707: @*/
708: PetscErrorCode  PetscOptionsDestroy(void)
709: {

713:   if (!options) return(0);
714:   PetscOptionsClear();
715:   free(options);
716:   options = 0;
717:   return(0);
718: }

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

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

729:    Input Parameters:
730: +  name - name of option, this SHOULD have the - prepended
731: -  value - the option value (not used for all options)

733:    Level: intermediate

735:    Note:
736:    Only some options have values associated with them, such as
737:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

739:   Concepts: options database^adding option

741: .seealso: PetscOptionsInsert()
742: @*/
743: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
744: {
745:   size_t         len;
747:   PetscInt       N,n,i;
748:   char           **names;
749:   const char     *name = (char*)iname;
750:   PetscTruth     gt,match;

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

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

759:   name++;
760:   /* first check against aliases */
761:   N = options->Naliases;
762:   for (i=0; i<N; i++) {
763:     PetscStrcasecmp(options->aliases1[i],name,&match);
764:     if (match) {
765:       name = options->aliases2[i];
766:       break;
767:     }
768:   }

770:   N     = options->N;
771:   n     = N;
772:   names = options->names;
773: 
774:   for (i=0; i<N; i++) {
775:     PetscStrcasecmp(names[i],name,&match);
776:     PetscStrgrt(names[i],name,&gt);
777:     if (match) {
778:       if (options->values[i]) free(options->values[i]);
779:       PetscStrlen(value,&len);
780:       if (len) {
781:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
782:         PetscStrcpy(options->values[i],value);
783:       } else { options->values[i] = 0;}
784:       PetscOptionsMonitor(name,value);
785:       return(0);
786:     } else if (gt) {
787:       n = i;
788:       break;
789:     }
790:   }
791:   if (N >= MAXOPTIONS) {
792:     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);
793:   }
794:   /* shift remaining values down 1 */
795:   for (i=N; i>n; i--) {
796:     options->names[i]  = options->names[i-1];
797:     options->values[i] = options->values[i-1];
798:     options->used[i]   = options->used[i-1];
799:   }
800:   /* insert new name and value */
801:   PetscStrlen(name,&len);
802:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
803:   PetscStrcpy(options->names[n],name);
804:   PetscStrlen(value,&len);
805:   if (len) {
806:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
807:     PetscStrcpy(options->values[n],value);
808:   } else {options->values[n] = 0;}
809:   options->used[n] = PETSC_FALSE;
810:   options->N++;
811:   PetscOptionsMonitor(name,value);
812:   return(0);
813: }

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

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

824:    Input Parameter:
825: .  name - name of option, this SHOULD have the - prepended

827:    Level: intermediate

829:    Concepts: options database^removing option
830: .seealso: PetscOptionsInsert()
831: @*/
832: PetscErrorCode  PetscOptionsClearValue(const char iname[])
833: {
835:   PetscInt       N,n,i;
836:   char           **names,*name=(char*)iname;
837:   PetscTruth     gt,match;

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

843:   name++;

845:   N     = options->N; n = 0;
846:   names = options->names;
847: 
848:   for (i=0; i<N; i++) {
849:     PetscStrcasecmp(names[i],name,&match);
850:     PetscStrgrt(names[i],name,&gt);
851:     if (match) {
852:       if (options->names[i])  free(options->names[i]);
853:       if (options->values[i]) free(options->values[i]);
854:       PetscOptionsMonitor(name,"");
855:       break;
856:     } else if (gt) {
857:       return(0); /* it was not listed */
858:     }
859:     n++;
860:   }
861:   if (n == N) return(0); /* it was not listed */

863:   /* shift remaining values down 1 */
864:   for (i=n; i<N-1; i++) {
865:     options->names[i]  = options->names[i+1];
866:     options->values[i] = options->values[i+1];
867:     options->used[i]   = options->used[i+1];
868:   }
869:   options->N--;
870:   return(0);
871: }

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

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

881:    Input Parameters:
882: +  name - the option one is seeking 
883: -  mess - error message (may be PETSC_NULL)

885:    Level: advanced

887:    Concepts: options database^rejecting option

889: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
890:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
891:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
892:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
893:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
894:           PetscOptionsList(), PetscOptionsEList()
895: @*/
896: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
897: {
899:   PetscInt       n = options->Naliases;
900:   size_t         len;
901:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

904:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
905:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
906:   if (n >= MAXALIASES) {
907:     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);
908:   }

910:   newname++; oldname++;
911:   PetscStrlen(newname,&len);
912:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
913:   PetscStrcpy(options->aliases1[n],newname);
914:   PetscStrlen(oldname,&len);
915:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
916:   PetscStrcpy(options->aliases2[n],oldname);
917:   options->Naliases++;
918:   return(0);
919: }

923: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
924: {
926:   PetscInt       i,N;
927:   size_t         len;
928:   char           **names,tmp[256];
929:   PetscTruth     match;

932:   if (!options) {PetscOptionsInsert(0,0,0);}
933:   N = options->N;
934:   names = options->names;

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

938:   /* append prefix to name */
939:   if (pre) {
940:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
941:     PetscStrncpy(tmp,pre,256);
942:     PetscStrlen(tmp,&len);
943:     PetscStrncat(tmp,name+1,256-len-1);
944:   } else {
945:     PetscStrncpy(tmp,name+1,256);
946:   }

948:   /* slow search */
949:   *flg = PETSC_FALSE;
950:   for (i=0; i<N; i++) {
951:     PetscStrcasecmp(names[i],tmp,&match);
952:     if (match) {
953:        *value           = options->values[i];
954:        options->used[i] = PETSC_TRUE;
955:        *flg             = PETSC_TRUE;
956:        break;
957:      }
958:   }
959:   if (!*flg) {
960:     PetscInt j,cnt = 0,locs[16],loce[16];
961:     size_t   n;
962:     PetscStrlen(tmp,&n);
963:     /* determine the location and number of all _%d_ in the key */
964:     for (i=0; i< (PetscInt)n; i++) {
965:       if (tmp[i] == '_') {
966:         for (j=i+1; j< (PetscInt)n; j++) {
967:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
968:           if (tmp[j] == '_' && j > i+1) { /* found a number */
969:             locs[cnt]   = i+1;
970:             loce[cnt++] = j+1;
971:           }
972:           break;
973:         }
974:       }
975:     }
976:     if (cnt) {
977:       char tmp2[256];
978:       for (i=0; i<cnt; i++) {
979:         PetscStrcpy(tmp2,"-");
980:         PetscStrncat(tmp2,tmp,locs[i]);
981:         PetscStrcat(tmp2,tmp+loce[i]);
982:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
983:         if (*flg) break;
984:       }
985:     }
986:   }
987:   return(0);
988: }

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

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

998:    Input Parameters:
999: +  name - the option one is seeking 
1000: -  mess - error message (may be PETSC_NULL)

1002:    Level: advanced

1004:    Concepts: options database^rejecting option

1006: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1007:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1008:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1009:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1010:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1011:           PetscOptionsList(), PetscOptionsEList()
1012: @*/
1013: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
1014: {
1016:   PetscTruth     flag;

1019:   PetscOptionsHasName(PETSC_NULL,name,&flag);
1020:   if (flag) {
1021:     if (mess) {
1022:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1023:     } else {
1024:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1025:     }
1026:   }
1027:   return(0);
1028: }

1032: /*@C
1033:    PetscOptionsHasName - Determines whether a certain option is given in the database.

1035:    Not Collective

1037:    Input Parameters:
1038: +  name - the option one is seeking 
1039: -  pre - string to prepend to the name or PETSC_NULL

1041:    Output Parameters:
1042: .  flg - PETSC_TRUE if found else PETSC_FALSE.

1044:    Level: beginner

1046:    Concepts: options database^has option name

1048:    Notes: Name cannot be simply -h

1050: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1051:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1052:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1053:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1054:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1055:           PetscOptionsList(), PetscOptionsEList()
1056: @*/
1057: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1058: {
1059:   char           *value;
1061:   PetscTruth     isfalse,flag;

1064:   PetscOptionsFindPair_Private(pre,name,&value,&flag);

1066:   /* remove if turned off */
1067:   if (flag) {
1068:     PetscStrcasecmp(value,"FALSE",&isfalse);
1069:     if (isfalse) flag = PETSC_FALSE;
1070:     PetscStrcasecmp(value,"NO",&isfalse);
1071:     if (isfalse) flag = PETSC_FALSE;
1072:     PetscStrcasecmp(value,"0",&isfalse);
1073:     if (isfalse) flag = PETSC_FALSE;
1074:   }
1075:   if (flg) *flg = flag;
1076:   return(0);
1077: }

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

1084:    Not Collective

1086:    Input Parameters:
1087: +  pre - the string to prepend to the name or PETSC_NULL
1088: -  name - the option one is seeking

1090:    Output Parameter:
1091: +  ivalue - the integer value to return
1092: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1094:    Level: beginner

1096:    Concepts: options database^has int

1098: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1099:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1100:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1101:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1102:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1103:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1104:           PetscOptionsList(), PetscOptionsEList()
1105: @*/
1106: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1107: {
1108:   char           *value;
1110:   PetscTruth     flag;

1115:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1116:   if (flag) {
1117:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1118:     else {
1119:       if (flg) *flg = PETSC_TRUE;
1120:       PetscOptionsAtoi(value,ivalue);
1121:     }
1122:   } else {
1123:     if (flg) *flg = PETSC_FALSE;
1124:   }
1125:   return(0);
1126: }

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

1133:    Not Collective

1135:    Input Parameters:
1136: +  pre - the string to prepend to the name or PETSC_NULL
1137: .  opt - option name
1138: .  list - the possible choices
1139: .  ntext - number of choices

1141:    Output Parameter:
1142: +  value - the index of the value to return
1143: -  set - PETSC_TRUE if found, else PETSC_FALSE
1144:    
1145:    Level: intermediate

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

1149:    Concepts: options database^list

1151: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1152:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1153:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1154:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1155:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1156:           PetscOptionsList(), PetscOptionsEList()
1157: @*/
1158: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1159: {
1161:   size_t         alen,len = 0;
1162:   char           *svalue;
1163:   PetscTruth     aset,flg = PETSC_FALSE;
1164:   PetscInt       i;

1167:   for ( i=0; i<ntext; i++) {
1168:     PetscStrlen(list[i],&alen);
1169:     if (alen > len) len = alen;
1170:   }
1171:   len += 5; /* a little extra space for user mistypes */
1172:   PetscMalloc(len*sizeof(char),&svalue);
1173:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1174:   if (aset) {
1175:     if (set) *set = PETSC_TRUE;
1176:     for (i=0; i<ntext; i++) {
1177:       PetscStrcasecmp(svalue,list[i],&flg);
1178:       if (flg) {
1179:         *value = i;
1180:         break;
1181:       }
1182:     }
1183:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1184:   } else if (set) {
1185:     *set = PETSC_FALSE;
1186:   }
1187:   PetscFree(svalue);
1188:   return(0);
1189: }

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

1196:    Not Collective

1198:    Input Parameters:
1199: +  pre - option prefix or PETSC_NULL
1200: .  opt - option name
1201: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1202: -  defaultv - the default (current) value

1204:    Output Parameter:
1205: +  value - the  value to return
1206: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1208:    Level: beginner

1210:    Concepts: options database

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

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

1216: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1217:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1218:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1219:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1220:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1221:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1222:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1223: @*/
1224: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1225: {
1227:   PetscInt       ntext = 0;

1230:   while (list[ntext++]) {
1231:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1232:   }
1233:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1234:   ntext -= 3;
1235:   PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1236:   return(0);
1237: }

1241: /*@C
1242:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1243:             option in the database.

1245:    Not Collective

1247:    Input Parameters:
1248: +  pre - the string to prepend to the name or PETSC_NULL
1249: -  name - the option one is seeking

1251:    Output Parameter:
1252: +  ivalue - the logical value to return
1253: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1255:    Level: beginner

1257:    Notes:
1258:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1259:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1264:    Concepts: options database^has logical

1266: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1267:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1268:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1269:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1270:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1271:           PetscOptionsList(), PetscOptionsEList()
1272: @*/
1273: PetscErrorCode  PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1274: {
1275:   char           *value;
1276:   PetscTruth     flag;

1282:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1283:   if (flag) {
1284:     if (flg) *flg = PETSC_TRUE;
1285:     if (!value) {
1286:       *ivalue = PETSC_TRUE;
1287:     } else {
1288:       PetscOptionsAtol(value, ivalue);
1289:     }
1290:   } else {
1291:     if (flg) *flg = PETSC_FALSE;
1292:   }
1293:   return(0);
1294: }

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

1303:    Not Collective

1305:    Input Parameters:
1306: +  pre - string to prepend to each name or PETSC_NULL
1307: .  name - the option one is seeking
1308: -  nmax - maximum number of values to retrieve

1310:    Output Parameter:
1311: +  dvalue - the integer values to return
1312: .  nmax - actual number of values retreived
1313: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1315:    Level: beginner

1317:    Concepts: options database^array of ints

1319:    Notes:
1320:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1321:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1323: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1324:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1325:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1326:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1327:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1328:           PetscOptionsList(), PetscOptionsEList()
1329: @*/
1330: PetscErrorCode  PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1331: {
1332:   char           *value;
1334:   PetscInt       n = 0;
1335:   PetscTruth     flag;
1336:   PetscToken     token;

1341:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1342:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1343:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1345:   if (flg) *flg = PETSC_TRUE;

1347:   PetscTokenCreate(value,',',&token);
1348:   PetscTokenFind(token,&value);
1349:   while (n < *nmax) {
1350:     if (!value) break;
1351:     PetscOptionsAtol(value,dvalue);
1352:     PetscTokenFind(token,&value);
1353:     dvalue++;
1354:     n++;
1355:   }
1356:   PetscTokenDestroy(token);
1357:   *nmax = n;
1358:   return(0);
1359: }

1363: /*@C
1364:    PetscOptionsGetReal - Gets the double precision value for a particular 
1365:    option in the database.

1367:    Not Collective

1369:    Input Parameters:
1370: +  pre - string to prepend to each name or PETSC_NULL
1371: -  name - the option one is seeking

1373:    Output Parameter:
1374: +  dvalue - the double value to return
1375: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1377:    Level: beginner

1379:    Concepts: options database^has double

1381: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1382:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1383:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1384:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1385:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1386:           PetscOptionsList(), PetscOptionsEList()
1387: @*/
1388: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1389: {
1390:   char           *value;
1392:   PetscTruth     flag;

1397:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1398:   if (flag) {
1399:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1400:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1401:   } else {
1402:     if (flg) *flg = PETSC_FALSE;
1403:   }
1404:   return(0);
1405: }

1409: /*@C
1410:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1411:    option in the database.

1413:    Not Collective

1415:    Input Parameters:
1416: +  pre - string to prepend to each name or PETSC_NULL
1417: -  name - the option one is seeking

1419:    Output Parameter:
1420: +  dvalue - the double value to return
1421: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1423:    Level: beginner

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

1429:    Concepts: options database^has scalar

1431: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1432:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1433:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1434:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1435:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1436:           PetscOptionsList(), PetscOptionsEList()
1437: @*/
1438: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1439: {
1440:   char           *value;
1441:   PetscTruth     flag;

1447:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1448:   if (flag) {
1449:     if (!value) {
1450:       if (flg) *flg = PETSC_FALSE;
1451:     } else {
1452: #if !defined(PETSC_USE_COMPLEX)
1453:       PetscOptionsAtod(value,dvalue);
1454: #else
1455:       PetscReal  re=0.0,im=0.0;
1456:       PetscToken token;
1457:       char       *tvalue = 0;

1459:       PetscTokenCreate(value,',',&token);
1460:       PetscTokenFind(token,&tvalue);
1461:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1462:       PetscOptionsAtod(tvalue,&re);
1463:       PetscTokenFind(token,&tvalue);
1464:       if (!tvalue) { /* Unknown separator used. using only real value */
1465:         *dvalue = re;
1466:       } else {
1467:         PetscOptionsAtod(tvalue,&im);
1468:         *dvalue = re + PETSC_i*im;
1469:       }
1470:       PetscTokenDestroy(token);
1471: #endif
1472:       if (flg) *flg    = PETSC_TRUE;
1473:     }
1474:   } else { /* flag */
1475:     if (flg) *flg = PETSC_FALSE;
1476:   }
1477:   return(0);
1478: }

1482: /*@C
1483:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1484:    particular option in the database.  The values must be separated with 
1485:    commas with no intervening spaces.

1487:    Not Collective

1489:    Input Parameters:
1490: +  pre - string to prepend to each name or PETSC_NULL
1491: .  name - the option one is seeking
1492: -  nmax - maximum number of values to retrieve

1494:    Output Parameters:
1495: +  dvalue - the double value to return
1496: .  nmax - actual number of values retreived
1497: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1499:    Level: beginner

1501:    Concepts: options database^array of doubles

1503: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1504:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1505:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1506:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1507:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1508:           PetscOptionsList(), PetscOptionsEList()
1509: @*/
1510: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1511: {
1512:   char           *value;
1514:   PetscInt       n = 0;
1515:   PetscTruth     flag;
1516:   PetscToken     token;

1521:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1522:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1523:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1525:   if (flg) *flg = PETSC_TRUE;

1527:   PetscTokenCreate(value,',',&token);
1528:   PetscTokenFind(token,&value);
1529:   while (n < *nmax) {
1530:     if (!value) break;
1531:     PetscOptionsAtod(value,dvalue++);
1532:     PetscTokenFind(token,&value);
1533:     n++;
1534:   }
1535:   PetscTokenDestroy(token);
1536:   *nmax = n;
1537:   return(0);
1538: }

1542: /*@C
1543:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1544:    option in the database.  The values must be separated with commas with 
1545:    no intervening spaces. 

1547:    Not Collective

1549:    Input Parameters:
1550: +  pre - string to prepend to each name or PETSC_NULL
1551: .  name - the option one is seeking
1552: -  nmax - maximum number of values to retrieve

1554:    Output Parameter:
1555: +  dvalue - the integer values to return
1556: .  nmax - actual number of values retreived
1557: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1559:    Level: beginner

1561:    Concepts: options database^array of ints

1563: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1564:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1565:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1566:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1567:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1568:           PetscOptionsList(), PetscOptionsEList()
1569: @*/
1570: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1571: {
1572:   char           *value;
1574:   PetscInt       n = 0,i,start,end;
1575:   size_t         len;
1576:   PetscTruth     flag,foundrange;
1577:   PetscToken     token;

1582:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1583:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1584:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1586:   if (flg) *flg = PETSC_TRUE;

1588:   PetscTokenCreate(value,',',&token);
1589:   PetscTokenFind(token,&value);
1590:   while (n < *nmax) {
1591:     if (!value) break;
1592: 
1593:     /* look for form  d-D where d and D are integers */
1594:     foundrange = PETSC_FALSE;
1595:     PetscStrlen(value,&len);
1596:     if (value[0] == '-') i=2;
1597:     else i=1;
1598:     for (;i<(int)len; i++) {
1599:       if (value[i] == '-') {
1600:         if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1601:         value[i] = 0;
1602:         PetscOptionsAtoi(value,&start);
1603:         PetscOptionsAtoi(value+i+1,&end);
1604:         if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1605:         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);
1606:         for (;start<end; start++) {
1607:           *dvalue = start; dvalue++;n++;
1608:         }
1609:         foundrange = PETSC_TRUE;
1610:         break;
1611:       }
1612:     }
1613:     if (!foundrange) {
1614:       PetscOptionsAtoi(value,dvalue);
1615:       dvalue++;
1616:       n++;
1617:     }
1618:     PetscTokenFind(token,&value);
1619:   }
1620:   PetscTokenDestroy(token);
1621:   *nmax = n;
1622:   return(0);
1623: }

1627: /*@C
1628:    PetscOptionsGetString - Gets the string value for a particular option in
1629:    the database.

1631:    Not Collective

1633:    Input Parameters:
1634: +  pre - string to prepend to name or PETSC_NULL
1635: .  name - the option one is seeking
1636: -  len - maximum string length

1638:    Output Parameters:
1639: +  string - location to copy string
1640: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1642:    Level: beginner

1644:    Fortran Note:
1645:    The Fortran interface is slightly different from the C/C++
1646:    interface (len is not used).  Sample usage in Fortran follows
1647: .vb
1648:       character *20 string
1649:       integer   flg, ierr
1650:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1651: .ve

1653:    Concepts: options database^string

1655: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1656:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1657:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1658:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1659:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1660:           PetscOptionsList(), PetscOptionsEList()
1661: @*/
1662: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1663: {
1664:   char           *value;
1666:   PetscTruth     flag;

1671:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1672:   if (!flag) {
1673:     if (flg) *flg = PETSC_FALSE;
1674:   } else {
1675:     if (flg) *flg = PETSC_TRUE;
1676:     if (value) {
1677:       PetscStrncpy(string,value,len);
1678:     } else {
1679:       PetscMemzero(string,len);
1680:     }
1681:   }
1682:   return(0);
1683: }

1687: /*@C
1688:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1689:    option in the database. The values must be separated with commas with 
1690:    no intervening spaces. 

1692:    Not Collective

1694:    Input Parameters:
1695: +  pre - string to prepend to name or PETSC_NULL
1696: .  name - the option one is seeking
1697: -  nmax - maximum number of strings

1699:    Output Parameter:
1700: +  strings - location to copy strings
1701: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1703:    Level: beginner

1705:    Notes: 
1706:    The user should pass in an array of pointers to char, to hold all the
1707:    strings returned by this function.

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

1712:    Contributed by Matthew Knepley.

1714:    Concepts: options database^array of strings

1716: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1717:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1718:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1719:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1720:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1721:           PetscOptionsList(), PetscOptionsEList()
1722: @*/
1723: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1724: {
1725:   char           *value;
1727:   PetscInt       n;
1728:   PetscTruth     flag;
1729:   PetscToken     token;
1730: 
1734:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1735:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1736:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1737:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1738:   if (flg) *flg = PETSC_TRUE;

1740:   PetscTokenCreate(value,',',&token);
1741:   PetscTokenFind(token,&value);
1742:   n = 0;
1743:   while (n < *nmax) {
1744:     if (!value) break;
1745:     PetscStrallocpy(value,&strings[n]);
1746:     PetscTokenFind(token,&value);
1747:     n++;
1748:   }
1749:   PetscTokenDestroy(token);
1750:   *nmax = n;
1751:   return(0);
1752: }

1756: /*@C
1757:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1758:    database that have never been selected.

1760:    Not Collective

1762:    Output Parameter:
1763: .   N - count of options not used

1765:    Level: advanced

1767: .seealso: PetscOptionsPrint()
1768: @*/
1769: PetscErrorCode  PetscOptionsAllUsed(int *N)
1770: {
1771:   PetscInt i,n = 0;

1774:   for (i=0; i<options->N; i++) {
1775:     if (!options->used[i]) { n++; }
1776:   }
1777:   *N = n;
1778:   return(0);
1779: }

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

1786:   Not collective

1788:    Options Database Key:
1789: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1791:   Level: advanced

1793: .seealso: PetscOptionsAllUsed()
1794: @*/
1795: PetscErrorCode  PetscOptionsLeft(void)
1796: {
1798:   PetscInt       i;

1801:   for (i=0; i<options->N; i++) {
1802:     if (!options->used[i]) {
1803:       if (options->values[i]) {
1804:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1805:       } else {
1806:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1807:       }
1808:     }
1809:   }
1810:   return(0);
1811: }


1814: /*
1815:     PetscOptionsCreate - Creates the empty options database.

1817: */
1820: PetscErrorCode  PetscOptionsCreate(void)
1821: {

1825:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1826:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1827:   options->namegiven                 = PETSC_FALSE;
1828:   options->N                         = 0;
1829:   options->Naliases                  = 0;
1830:   options->numbermonitors         = 0;

1832:   PetscOptionsObject.prefix = PETSC_NULL;
1833:   PetscOptionsObject.title  = PETSC_NULL;
1834: 
1835:   return(0);
1836: }

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

1843:    Collective on PETSC_COMM_WORLD

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

1853:    Notes:
1854:    To see all options, run your program with the -help option or consult
1855:    the users manual. 

1857:    Level: intermediate

1859: .keywords: set, options, database
1860: @*/
1861: PetscErrorCode  PetscOptionsSetFromOptions(void)
1862: {
1863:   PetscTruth          flg;
1864:   PetscErrorCode      ierr;
1865:   char                monfilename[PETSC_MAX_PATH_LEN];
1866:   PetscViewer         monviewer;


1870:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1871:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1872:   if (flg && (!options->numbermonitors)) {
1873:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1874:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1875:   }
1876: 
1877:   PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1878:   if (flg) { PetscOptionsMonitorCancel(); }
1879: 
1880:   PetscOptionsEnd();

1882:   return(0);
1883: }


1888: /*@C
1889:    PetscOptionsMonitorDefault - Print all options set value events.

1891:    Collective on PETSC_COMM_WORLD

1893:    Input Parameters:
1894: +  name  - option name string
1895: .  value - option value string
1896: -  dummy - unused monitor context 

1898:    Level: intermediate

1900: .keywords: PetscOptions, default, monitor

1902: .seealso: PetscOptionsMonitorSet()
1903: @*/
1904: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1905: {
1907:   PetscViewer    viewer = (PetscViewer) dummy;

1910:   if (!viewer) {
1911:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1912:   }
1913:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1914:   return(0);
1915: }

1919: /*@C
1920:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1921:    modified the PETSc options database.
1922:       
1923:    Not collective

1925:    Input Parameters:
1926: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1927: .  mctx    - [optional] context for private data for the
1928:              monitor routine (use PETSC_NULL if no context is desired)
1929: -  monitordestroy - [optional] routine that frees monitor context
1930:           (may be PETSC_NULL)

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

1935: +  name - option name string
1936: .  value - option value string
1937: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1939:    Options Database Keys:
1940: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1941: -    -options_monitor_cancel - cancels all monitors that have
1942:                           been hardwired into a code by 
1943:                           calls to PetscOptionsMonitorSet(), but
1944:                           does not cancel those set via
1945:                           the options database.

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

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

1956:    Level: beginner

1958: .keywords: PetscOptions, set, monitor

1960: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1961: @*/
1962: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1963: {
1965:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1966:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1967:   }
1968:   options->monitor[options->numbermonitors]           = monitor;
1969:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1970:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1971:   return(0);
1972: }

1976: /*@
1977:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1979:    Not collective 

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

1986:    Level: intermediate

1988: .keywords: PetscOptions, set, monitor

1990: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1991: @*/
1992: PetscErrorCode  PetscOptionsMonitorCancel(void)
1993: {
1995:   PetscInt       i;

1998:   for (i=0; i<options->numbermonitors; i++) {
1999:     if (options->monitordestroy[i]) {
2000:       (*options->monitordestroy[i])(options->monitorcontext[i]);
2001:     }
2002:   }
2003:   options->numbermonitors = 0;
2004:   return(0);
2005: }