Actual source code: options.c

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

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

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

 13: #include <petscsys.h>        /*I  "petscsys.h"   I*/
 14: #include <ctype.h>
 15: #if defined(PETSC_HAVE_STDLIB_H)
 16: #include <stdlib.h>
 17: #endif
 18: #if defined(PETSC_HAVE_MALLOC_H)
 19: #include <malloc.h>
 20: #endif
 21: #if defined(PETSC_HAVE_SYS_PARAM_H)
 22: #include <sys/param.h>
 23: #endif
 24: #if defined(PETSC_HAVE_YAML)
 25: #include <yaml.h>
 26: #endif

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

 36: typedef struct {
 37:   int            N,argc,Naliases;
 38:   char           **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
 39:   char           *aliases1[MAXALIASES],*aliases2[MAXALIASES];
 40:   PetscBool      used[MAXOPTIONS];
 41:   PetscBool      namegiven;
 42:   char           programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */

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

 50:   /* Prefixes */
 51:   PetscInt prefixind,prefixstack[MAXPREFIXES];
 52:   char prefix[2048];
 53: } PetscOptionsTable;


 56: static PetscOptionsTable      *options = 0;

 59: /*
 60:     Options events monitor
 61: */
 62: #define PetscOptionsMonitor(name,value)                                     \
 63:         { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
 64:           for (_i=0; _i<_im; _i++) {\
 65:             _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
 66:           } \
 67:         }

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

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

 84:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 85:   if (!tdefault) {
 86:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 87:   }
 88:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 89:   if (!decide) {
 90:     PetscStrcasecmp(name,"DECIDE",&decide);
 91:   }
 92:   PetscStrcasecmp(name,"mouse",&mouse);

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

110: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
111:     *a = atoll(name);
112: #else
113:     *a = (PetscInt)atoi(name);
114: #endif
115:   }
116:   return(0);
117: }

121: /*
122:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
123: */
124: PetscErrorCode  PetscOptionsStringToReal(const char name[],PetscReal *a)
125: {
127:   size_t         len;
128:   PetscBool      decide,tdefault;

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

134:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
135:   if (!tdefault) {
136:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
137:   }
138:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
139:   if (!decide) {
140:     PetscStrcasecmp(name,"DECIDE",&decide);
141:   }

143:   if (tdefault) {
144:     *a = PETSC_DEFAULT;
145:   } else if (decide) {
146:     *a = PETSC_DECIDE;
147:   } else {
148:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
149:       SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
150:     }
151:     *a  = atof(name);
152:   }
153:   return(0);
154: }

158: /*
159:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
160: */
161: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
162: {
163:   PetscBool      istrue, isfalse;
164:   size_t         len;

168:   PetscStrlen(value, &len);
169:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
170:   PetscStrcasecmp(value,"TRUE",&istrue);
171:   if (istrue) {*a = PETSC_TRUE; return(0);}
172:   PetscStrcasecmp(value,"YES",&istrue);
173:   if (istrue) {*a = PETSC_TRUE; return(0);}
174:   PetscStrcasecmp(value,"1",&istrue);
175:   if (istrue) {*a = PETSC_TRUE; return(0);}
176:   PetscStrcasecmp(value,"on",&istrue);
177:   if (istrue) {*a = PETSC_TRUE; return(0);}
178:   PetscStrcasecmp(value,"FALSE",&isfalse);
179:   if (isfalse) {*a = PETSC_FALSE; return(0);}
180:   PetscStrcasecmp(value,"NO",&isfalse);
181:   if (isfalse) {*a = PETSC_FALSE; return(0);}
182:   PetscStrcasecmp(value,"0",&isfalse);
183:   if (isfalse) {*a = PETSC_FALSE; return(0);}
184:   PetscStrcasecmp(value,"off",&isfalse);
185:   if (isfalse) {*a = PETSC_FALSE; return(0);}
186:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
187:   return(0);
188: }

192: /*@C
193:     PetscGetProgramName - Gets the name of the running program. 

195:     Not Collective

197:     Input Parameter:
198: .   len - length of the string name

200:     Output Parameter:
201: .   name - the name of the running program

203:    Level: advanced

205:     Notes:
206:     The name of the program is copied into the user-provided character
207:     array of length len.  On some machines the program name includes 
208:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
209: @*/
210: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
211: {

215:   if (!options) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
216:   if (!options->namegiven) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Unable to determine program name");
217:   PetscStrncpy(name,options->programname,len);
218:   return(0);
219: }

223: PetscErrorCode  PetscSetProgramName(const char name[])
224: {

228:   options->namegiven = PETSC_TRUE;
229:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
230:   return(0);
231: }

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

238:    Input Parameter:
239: .    in_str - string to check if valid

241:    Output Parameter:
242: .    key - PETSC_TRUE if a valid key

244:   Level: intermediate

246: @*/
247: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
248: {
250:   *key = PETSC_FALSE;
251:   if (!in_str) return(0);
252:   if (in_str[0] != '-') return(0);
253:   if (!(isalpha(in_str[1]))) return(0);
254:   if ((!strncmp(in_str+1,"inf",3) || !strncmp(in_str+1,"INF",3)) && !(in_str[4] == '_' || isalnum(in_str[4]))) return(0);
255:   *key = PETSC_TRUE;
256:   return(0);
257: }

261: /*@C
262:      PetscOptionsInsertString - Inserts options into the database from a string

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

267:   Input Parameter:
268: .   in_str - string that contains options separated by blanks


271:   Level: intermediate

273:   Contributed by Boyana Norris

275: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
276:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
277:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
278:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
279:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
280:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

282: @*/
283: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
284: {
285:   char           *first,*second;
287:   PetscToken     token;
288:   PetscBool      key,ispush,ispop;

291:   PetscTokenCreate(in_str,' ',&token);
292:   PetscTokenFind(token,&first);
293:   while (first) {
294:     PetscStrcasecmp(first,"-prefix_push",&ispush);
295:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
296:     PetscOptionsValidKey(first,&key);
297:     if (ispush) {
298:       PetscTokenFind(token,&second);
299:       PetscOptionsPrefixPush(second);
300:       PetscTokenFind(token,&first);
301:     } else if (ispop) {
302:       PetscOptionsPrefixPop();
303:       PetscTokenFind(token,&first);
304:     } else if (key) {
305:       PetscTokenFind(token,&second);
306:       PetscOptionsValidKey(second,&key);
307:       if (!key) {
308:         PetscOptionsSetValue(first,second);
309:         PetscTokenFind(token,&first);
310:       } else {
311:         PetscOptionsSetValue(first,PETSC_NULL);
312:         first = second;
313:       }
314:     } else {
315:       PetscTokenFind(token,&first);
316:     }
317:   }
318:   PetscTokenDestroy(token);
319:   return(0);
320: }

322: /*
323:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
324: */
325: static char *Petscgetline(FILE * f)
326: {
327:   size_t size = 0;
328:   size_t len  = 0;
329:   size_t last = 0;
330:   char * buf  = PETSC_NULL;

332:   if (feof(f)) return 0;
333:   do {
334:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
335:     buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
336:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
337:     end of the string, so we make sure we overwrite this */
338:     if (!fgets(buf+len,size,f)) buf[len]=0;
339:     PetscStrlen(buf,&len);
340:     last = len - 1;
341:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
342:   if (len) return buf;
343:   free(buf);
344:   return 0;
345: }


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

353:      Collective on MPI_Comm

355:   Input Parameter:
356: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
357: .   file - name of file
358: -   require - if PETSC_TRUE will generate an error if the file does not exist


361:   Level: developer

363: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
364:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
365:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
366:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
367:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
368:           PetscOptionsList(), PetscOptionsEList()

370: @*/
371: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
372: {
373:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
375:   size_t         i,len;
376:   FILE           *fd;
377:   PetscToken     token;
378:   int            err;
379:   char           cmt[3]={'#','!','%'},*cmatch;
380:   PetscMPIInt    rank,cnt=0,acnt=0;

383:   MPI_Comm_rank(comm,&rank);
384:   if (!rank) {
385:     /* Warning: assume a maximum size for all options in a string */
386:     PetscMalloc(128000*sizeof(char),&vstring);
387:     vstring[0] = 0;
388:     PetscMalloc(64000*sizeof(char),&astring);
389:     astring[0] = 0;
390:     cnt     = 0;
391:     acnt    = 0;

393:     PetscFixFilename(file,fname);
394:     fd   = fopen(fname,"r");
395:     if (fd) {
396:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
397:       PetscInfo1(0,"Opened options file %s\n",file);
398:       while ((string = Petscgetline(fd))) {
399:         /* eliminate comments from each line */
400:         for (i=0; i<3; i++){
401:           PetscStrchr(string,cmt[i],&cmatch);
402:           if (cmatch) *cmatch = 0;
403:         }
404:         PetscStrlen(string,&len);
405:         /* replace tabs, ^M, \n with " " */
406:         for (i=0; i<len; i++) {
407:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
408:             string[i] = ' ';
409:           }
410:         }
411:         PetscTokenCreate(string,' ',&token);
412:         free(string);
413:         PetscTokenFind(token,&first);
414:         if (!first) {
415:           goto destroy;
416:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
417:           PetscTokenFind(token,&first);
418:         }
419:         PetscTokenFind(token,&second);
420:         if (!first) {
421:           goto destroy;
422:         } else if (first[0] == '-') {
423:           /* warning: should be making sure we do not overfill vstring */
424:           PetscStrcat(vstring,first);
425:           PetscStrcat(vstring," ");
426:           if (second) {
427:             /* protect second with quotes in case it contains strings */
428:             PetscStrcat(vstring,"\"");
429:             PetscStrcat(vstring,second);
430:             PetscStrcat(vstring,"\"");
431:           }
432:           PetscStrcat(vstring," ");
433:         } else {
434:           PetscBool  match;

436:           PetscStrcasecmp(first,"alias",&match);
437:           if (match) {
438:             PetscTokenFind(token,&third);
439:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
440:             PetscStrcat(astring,second);
441:             PetscStrcat(astring," ");
442:             PetscStrcat(astring,third);
443:             PetscStrcat(astring," ");
444:           } else {
445:             SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
446:           }
447:         }
448:         destroy:
449:         PetscTokenDestroy(token);
450:       }
451:       err = fclose(fd);
452:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
453:       PetscStrlen(astring,&len);
454:       acnt = PetscMPIIntCast(len);
455:       PetscStrlen(vstring,&len);
456:       cnt  = PetscMPIIntCast(len);
457:     } else if (require) {
458:       SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
459:     }
460:   }

462:   MPI_Bcast(&acnt,1,MPI_INT,0,comm);
463:   if (acnt) {
464:     PetscToken token;
465:     char       *first,*second;

467:     if (rank) {
468:       PetscMalloc((acnt+1)*sizeof(char),&astring);
469:     }
470:     MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
471:     astring[acnt] = 0;
472:     PetscTokenCreate(astring,' ',&token);
473:     PetscTokenFind(token,&first);
474:     while (first) {
475:       PetscTokenFind(token,&second);
476:       PetscOptionsSetAlias(first,second);
477:       PetscTokenFind(token,&first);
478:     }
479:     PetscTokenDestroy(token);
480:   }

482:   MPI_Bcast(&cnt,1,MPI_INT,0,comm);
483:   if (cnt) {
484:     if (rank) {
485:       PetscMalloc((cnt+1)*sizeof(char),&vstring);
486:     }
487:     MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
488:     vstring[cnt] = 0;
489:     PetscOptionsInsertString(vstring);
490:   }
491:   PetscFree(astring);
492:   PetscFree(vstring);
493:   return(0);
494: }

498: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
499: {
501:   int            left    = argc - 1;
502:   char           **eargs = args + 1;

505:   while (left) {
506:     PetscBool  isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank;
507:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
508:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
509:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
510:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
511:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
512:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
513:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
514:     isp4 = (PetscBool) (isp4 || tisp4);
515:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
516:     isp4 = (PetscBool) (isp4 || tisp4);
517:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

519:     if (eargs[0][0] != '-') {
520:       eargs++; left--;
521:     } else if (isoptions_file) {
522:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
523:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
524:       PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
525:       eargs += 2; left -= 2;
526:     } else if (isprefixpush) {
527:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
528:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
529:       PetscOptionsPrefixPush(eargs[1]);
530:       eargs += 2; left -= 2;
531:     } else if (isprefixpop) {
532:       PetscOptionsPrefixPop();
533:       eargs++; left--;

535:       /*
536:        These are "bad" options that MPICH, etc put on the command line
537:        we strip them out here.
538:        */
539:     } else if (tisp4 || isp4rmrank) {
540:       eargs += 1; left -= 1;
541:     } else if (isp4 || isp4yourname) {
542:       eargs += 2; left -= 2;
543:     } else {
544:       PetscBool nextiskey = PETSC_FALSE;
545:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
546:       if (left < 2 || nextiskey) {
547:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
548:         eargs++; left--;
549:       } else {
550:         PetscOptionsSetValue(eargs[0],eargs[1]);
551:         eargs += 2; left -= 2;
552:       }
553:     }
554:   }
555:   return(0);
556: }


561: /*@C
562:    PetscOptionsInsert - Inserts into the options database from the command line,
563:                    the environmental variable and a file.

565:    Input Parameters:
566: +  argc - count of number of command line arguments
567: .  args - the command line arguments
568: -  file - optional filename, defaults to ~username/.petscrc

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

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

579:    Level: advanced

581:    Concepts: options database^adding

583: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
584:           PetscInitialize()
585: @*/
586: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
587: {
589:   PetscMPIInt    rank;
590:   char           pfile[PETSC_MAX_PATH_LEN];
591:   PetscBool      flag = PETSC_FALSE;

594:   if (!options) {
595:     fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
596:     MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
597:   }
598:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

600:   options->argc     = (argc) ? *argc : 0;
601:   options->args     = (args) ? *args : PETSC_NULL;

603:   if (file && file[0]) {
604:     PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
605:   }
606:   /*
607:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
608:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
609:   */
610:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
611:   PetscOptionsGetBool(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
612:   if (!flag) {
613:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
614:     /* warning: assumes all processes have a home directory or none, but nothing in between */
615:     if (pfile[0]) {
616:       PetscStrcat(pfile,"/.petscrc");
617:       PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
618:     }
619:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
620:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
621:   }

623:   /* insert environmental options */
624:   {
625:     char   *eoptions = 0;
626:     size_t len = 0;
627:     if (!rank) {
628:       eoptions = (char*)getenv("PETSC_OPTIONS");
629:       PetscStrlen(eoptions,&len);
630:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
631:     } else {
632:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
633:       if (len) {
634:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
635:       }
636:     }
637:     if (len) {
638:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
639:       if (rank) eoptions[len] = 0;
640:       PetscOptionsInsertString(eoptions);
641:       if (rank) {PetscFree(eoptions);}
642:     }
643:   }

645: #if defined(PETSC_HAVE_YAML)
646:   char yaml_file[PETSC_MAX_PATH_LEN];
647:   PetscBool yaml_flg = PETSC_FALSE;
648:   PetscOptionsGetString(PETSC_NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
649:   if (yaml_flg) PetscOptionsInsertFile_YAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
650: #endif

652:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
653:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}

655:   return(0);
656: }

660: /*@C
661:    PetscOptionsView - Prints the options that have been loaded. This is
662:    useful for debugging purposes.

664:    Logically Collective on PetscViewer

666:    Input Parameter:
667: .  viewer - must be an PETSCVIEWERASCII viewer

669:    Options Database Key:
670: .  -optionstable - Activates PetscOptionsView() within PetscFinalize()

672:    Level: advanced

674:    Concepts: options database^printing

676: .seealso: PetscOptionsAllUsed()
677: @*/
678: PetscErrorCode  PetscOptionsView(PetscViewer viewer)
679: {
681:   PetscInt       i;
682:   PetscBool      isascii;

685:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
686:   PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
687:   if (!isascii) SETERRQ(((PetscObject)viewer)->comm,PETSC_ERR_SUP,"Only supports ASCII viewer");

689:   if (!options) {PetscOptionsInsert(0,0,0);}
690:   if (options->N) {
691:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
692:   } else {
693:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
694:   }
695:   for (i=0; i<options->N; i++) {
696:     if (options->values[i]) {
697:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
698:     } else {
699:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
700:     }
701:   }
702:   if (options->N) {
703:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
704:   }
705:   return(0);
706: }

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

713:    Not Collective

715:    Output Parameter:
716: .  copts - pointer where string pointer is stored

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

720:    Level: advanced

722:    Concepts: options database^listing

724: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
725: @*/
726: PetscErrorCode  PetscOptionsGetAll(char *copts[])
727: {
729:   PetscInt       i;
730:   size_t         len = 1,lent;
731:   char           *coptions;

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

736:   /* count the length of the required string */
737:   for (i=0; i<options->N; i++) {
738:     PetscStrlen(options->names[i],&lent);
739:     len += 2 + lent;
740:     if (options->values[i]) {
741:       PetscStrlen(options->values[i],&lent);
742:       len += 1 + lent;
743:     }
744:   }
745:   PetscMalloc(len*sizeof(char),&coptions);
746:   coptions[0] = 0;
747:   for (i=0; i<options->N; i++) {
748:     PetscStrcat(coptions,"-");
749:     PetscStrcat(coptions,options->names[i]);
750:     PetscStrcat(coptions," ");
751:     if (options->values[i]) {
752:       PetscStrcat(coptions,options->values[i]);
753:       PetscStrcat(coptions," ");
754:     }
755:   }
756:   *copts = coptions;
757:   return(0);
758: }

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

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

767:    Input Parameter:
768: .  prefix - The string to append to the existing prefix

770:    Options Database Keys:
771:  +   -prefix_push <some_prefix_> - push the given prefix
772:  -   -prefix_pop - pop the last prefix

774:    Notes:
775:    It is common to use this in conjunction with -options_file as in

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

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

781: Level: advanced

783: .seealso: PetscOptionsPrefixPop()
784: @*/
785: PetscErrorCode  PetscOptionsPrefixPush(const char prefix[])
786: {
788:   size_t n;
789:   PetscInt start;
790:   char buf[2048];
791:   PetscBool  key;

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

802:   if (!options) {PetscOptionsInsert(0,0,0);}
803:   if (options->prefixind >= MAXPREFIXES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum depth of prefix stack %d exceeded, recompile \n src/sys/objects/options.c with larger value for MAXPREFIXES",MAXPREFIXES);
804:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
805:   PetscStrlen(prefix,&n);
806:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
807:   PetscMemcpy(options->prefix+start,prefix,n+1);
808:   options->prefixstack[options->prefixind++] = start+n;
809:   return(0);
810: }

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

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

819:    Level: advanced

821: .seealso: PetscOptionsPrefixPush()
822: @*/
823: PetscErrorCode  PetscOptionsPrefixPop(void)
824: {
825:   PetscInt offset;

828:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
829:   options->prefixind--;
830:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
831:   options->prefix[offset] = 0;
832:   return(0);
833: }

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

840:    Level: developer

842: .seealso: PetscOptionsInsert()
843: @*/
844: PetscErrorCode  PetscOptionsClear(void)
845: {
846:   PetscInt i;

849:   if (!options) return(0);
850:   for (i=0; i<options->N; i++) {
851:     if (options->names[i])  free(options->names[i]);
852:     if (options->values[i]) free(options->values[i]);
853:   }
854:   for (i=0; i<options->Naliases; i++) {
855:     free(options->aliases1[i]);
856:     free(options->aliases2[i]);
857:   }
858:   options->prefix[0] = 0;
859:   options->prefixind = 0;
860:   options->N        = 0;
861:   options->Naliases = 0;
862:   return(0);
863: }

867: /*@C
868:     PetscOptionsDestroy - Destroys the option database. 

870:     Note:
871:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
872:     typically does not need to call this routine.

874:    Level: developer

876: .seealso: PetscOptionsInsert()
877: @*/
878: PetscErrorCode  PetscOptionsDestroy(void)
879: {

883:   if (!options) return(0);
884:   PetscOptionsClear();
885:   free(options);
886:   options = 0;
887:   return(0);
888: }

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

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

899:    Input Parameters:
900: +  name - name of option, this SHOULD have the - prepended
901: -  value - the option value (not used for all options)

903:    Level: intermediate

905:    Note:
906:    Only some options have values associated with them, such as
907:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

909:   Concepts: options database^adding option

911: .seealso: PetscOptionsInsert()
912: @*/
913: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
914: {
915:   size_t         len;
917:   PetscInt       N,n,i;
918:   char           **names;
919:   char           fullname[2048];
920:   const char     *name = iname;
921:   PetscBool      gt,match;

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

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

930:   name++; /* skip starting hyphen */
931:   if (options->prefixind > 0) {
932:     PetscStrncpy(fullname,options->prefix,sizeof fullname);
933:     PetscStrncat(fullname,name,sizeof fullname);
934:     name = fullname;
935:   }

937:   /* check against aliases */
938:   N = options->Naliases;
939:   for (i=0; i<N; i++) {
940:     PetscStrcasecmp(options->aliases1[i],name,&match);
941:     if (match) {
942:       name = options->aliases2[i];
943:       break;
944:     }
945:   }

947:   N     = options->N;
948:   n     = N;
949:   names = options->names;
950: 
951:   for (i=0; i<N; i++) {
952:     PetscStrcasecmp(names[i],name,&match);
953:     PetscStrgrt(names[i],name,&gt);
954:     if (match) {
955:       if (options->values[i]) free(options->values[i]);
956:       PetscStrlen(value,&len);
957:       if (len) {
958:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
959:         PetscStrcpy(options->values[i],value);
960:       } else { options->values[i] = 0;}
961:       PetscOptionsMonitor(name,value);
962:       return(0);
963:     } else if (gt) {
964:       n = i;
965:       break;
966:     }
967:   }
968:   if (N >= MAXOPTIONS) {
969:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
970:   }
971:   /* shift remaining values down 1 */
972:   for (i=N; i>n; i--) {
973:     options->names[i]  = options->names[i-1];
974:     options->values[i] = options->values[i-1];
975:     options->used[i]   = options->used[i-1];
976:   }
977:   /* insert new name and value */
978:   PetscStrlen(name,&len);
979:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
980:   PetscStrcpy(options->names[n],name);
981:   PetscStrlen(value,&len);
982:   if (len) {
983:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
984:     PetscStrcpy(options->values[n],value);
985:   } else {options->values[n] = 0;}
986:   options->used[n] = PETSC_FALSE;
987:   options->N++;
988:   PetscOptionsMonitor(name,value);
989:   return(0);
990: }

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

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

1001:    Input Parameter:
1002: .  name - name of option, this SHOULD have the - prepended

1004:    Level: intermediate

1006:    Concepts: options database^removing option
1007: .seealso: PetscOptionsInsert()
1008: @*/
1009: PetscErrorCode  PetscOptionsClearValue(const char iname[])
1010: {
1012:   PetscInt       N,n,i;
1013:   char           **names,*name=(char*)iname;
1014:   PetscBool      gt,match;

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

1020:   name++;

1022:   N     = options->N; n = 0;
1023:   names = options->names;
1024: 
1025:   for (i=0; i<N; i++) {
1026:     PetscStrcasecmp(names[i],name,&match);
1027:     PetscStrgrt(names[i],name,&gt);
1028:     if (match) {
1029:       if (options->names[i])  free(options->names[i]);
1030:       if (options->values[i]) free(options->values[i]);
1031:       PetscOptionsMonitor(name,"");
1032:       break;
1033:     } else if (gt) {
1034:       return(0); /* it was not listed */
1035:     }
1036:     n++;
1037:   }
1038:   if (n == N) return(0); /* it was not listed */

1040:   /* shift remaining values down 1 */
1041:   for (i=n; i<N-1; i++) {
1042:     options->names[i]  = options->names[i+1];
1043:     options->values[i] = options->values[i+1];
1044:     options->used[i]   = options->used[i+1];
1045:   }
1046:   options->N--;
1047:   return(0);
1048: }

1052: /*@C
1053:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1058:    Input Parameters:
1059: +  inewname - the alias
1060: -  ioldname - the name that alias will refer to 

1062:    Level: advanced

1064: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1065:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1066:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1067:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1068:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1069:           PetscOptionsList(), PetscOptionsEList()
1070: @*/
1071: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
1072: {
1074:   PetscInt       n = options->Naliases;
1075:   size_t         len;
1076:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

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

1085:   newname++; oldname++;
1086:   PetscStrlen(newname,&len);
1087:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1088:   PetscStrcpy(options->aliases1[n],newname);
1089:   PetscStrlen(oldname,&len);
1090:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1091:   PetscStrcpy(options->aliases2[n],oldname);
1092:   options->Naliases++;
1093:   return(0);
1094: }

1098: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool  *flg)
1099: {
1101:   PetscInt       i,N;
1102:   size_t         len;
1103:   char           **names,tmp[256];
1104:   PetscBool      match;

1107:   if (!options) {PetscOptionsInsert(0,0,0);}
1108:   N = options->N;
1109:   names = options->names;

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

1113:   /* append prefix to name */
1114:   if (pre) {
1115:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1116:     PetscStrncpy(tmp,pre,256);
1117:     PetscStrlen(tmp,&len);
1118:     PetscStrncat(tmp,name+1,256-len-1);
1119:   } else {
1120:     PetscStrncpy(tmp,name+1,256);
1121:   }

1123:   /* slow search */
1124:   *flg = PETSC_FALSE;
1125:   for (i=0; i<N; i++) {
1126:     PetscStrcasecmp(names[i],tmp,&match);
1127:     if (match) {
1128:        *value           = options->values[i];
1129:        options->used[i] = PETSC_TRUE;
1130:        *flg             = PETSC_TRUE;
1131:        break;
1132:      }
1133:   }
1134:   if (!*flg) {
1135:     PetscInt j,cnt = 0,locs[16],loce[16];
1136:     size_t   n;
1137:     PetscStrlen(tmp,&n);
1138:     /* determine the location and number of all _%d_ in the key */
1139:     for (i=0; i< (PetscInt)n; i++) {
1140:       if (tmp[i] == '_') {
1141:         for (j=i+1; j< (PetscInt)n; j++) {
1142:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1143:           if (tmp[j] == '_' && j > i+1) { /* found a number */
1144:             locs[cnt]   = i+1;
1145:             loce[cnt++] = j+1;
1146:           }
1147:           break;
1148:         }
1149:       }
1150:     }
1151:     if (cnt) {
1152:       char tmp2[256];
1153:       for (i=0; i<cnt; i++) {
1154:         PetscStrcpy(tmp2,"-");
1155:         PetscStrncat(tmp2,tmp,locs[i]);
1156:         PetscStrcat(tmp2,tmp+loce[i]);
1157:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1158:         if (*flg) break;
1159:       }
1160:     }
1161:   }
1162:   return(0);
1163: }

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

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

1173:    Input Parameters:
1174: +  name - the option one is seeking 
1175: -  mess - error message (may be PETSC_NULL)

1177:    Level: advanced

1179:    Concepts: options database^rejecting option

1181: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1182:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1183:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1184:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1185:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1186:           PetscOptionsList(), PetscOptionsEList()
1187: @*/
1188: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
1189: {
1191:   PetscBool      flag = PETSC_FALSE;

1194:   PetscOptionsHasName(PETSC_NULL,name,&flag);
1195:   if (flag) {
1196:     if (mess) {
1197:       SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1198:     } else {
1199:       SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1200:     }
1201:   }
1202:   return(0);
1203: }

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

1211:    Not Collective

1213:    Input Parameters:
1214: +  name - the option one is seeking 
1215: -  pre - string to prepend to the name or PETSC_NULL

1217:    Output Parameters:
1218: .  set - PETSC_TRUE if found else PETSC_FALSE.

1220:    Level: beginner

1222:    Concepts: options database^has option name

1224:    Notes: Name cannot be simply -h

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

1228: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1229:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1230:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1231:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1232:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1233:           PetscOptionsList(), PetscOptionsEList()
1234: @*/
1235: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscBool  *set)
1236: {
1237:   char           *value;
1239:   PetscBool      flag;

1242:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1243:   if (set) *set = flag;
1244:   return(0);
1245: }

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

1252:    Not Collective

1254:    Input Parameters:
1255: +  pre - the string to prepend to the name or PETSC_NULL
1256: -  name - the option one is seeking

1258:    Output Parameter:
1259: +  ivalue - the integer value to return
1260: -  set - PETSC_TRUE if found, else PETSC_FALSE

1262:    Level: beginner

1264:    Concepts: options database^has int

1266: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1267:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1268:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1269:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1270:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1271:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1272:           PetscOptionsList(), PetscOptionsEList()
1273: @*/
1274: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool  *set)
1275: {
1276:   char           *value;
1278:   PetscBool      flag;

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

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

1301:    Not Collective

1303:    Input Parameters:
1304: +  pre - the string to prepend to the name or PETSC_NULL
1305: .  opt - option name
1306: .  list - the possible choices
1307: .  ntext - number of choices

1309:    Output Parameter:
1310: +  value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1311: -  set - PETSC_TRUE if found, else PETSC_FALSE
1312:    
1313:    Level: intermediate

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

1317:    Concepts: options database^list

1319: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1320:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1321:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1322:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1323:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1324:           PetscOptionsList(), PetscOptionsEList()
1325: @*/
1326: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscBool  *set)
1327: {
1329:   size_t         alen,len = 0;
1330:   char           *svalue;
1331:   PetscBool      aset,flg = PETSC_FALSE;
1332:   PetscInt       i;

1335:   for ( i=0; i<ntext; i++) {
1336:     PetscStrlen(list[i],&alen);
1337:     if (alen > len) len = alen;
1338:   }
1339:   len += 5; /* a little extra space for user mistypes */
1340:   PetscMalloc(len*sizeof(char),&svalue);
1341:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1342:   if (aset) {
1343:     if (set) *set = PETSC_TRUE;
1344:     for (i=0; i<ntext; i++) {
1345:       PetscStrcasecmp(svalue,list[i],&flg);
1346:       if (flg || !svalue[0]) {
1347:         flg    = PETSC_TRUE;
1348:         *value = i;
1349:         break;
1350:       }
1351:     }
1352:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1353:   } else if (set) {
1354:     *set = PETSC_FALSE;
1355:   }
1356:   PetscFree(svalue);
1357:   return(0);
1358: }

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

1365:    Not Collective

1367:    Input Parameters:
1368: +  pre - option prefix or PETSC_NULL
1369: .  opt - option name
1370: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1371: -  defaultv - the default (current) value

1373:    Output Parameter:
1374: +  value - the  value to return
1375: -  set - PETSC_TRUE if found, else PETSC_FALSE

1377:    Level: beginner

1379:    Concepts: options database

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

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

1385: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1386:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1387:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1388:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1389:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1390:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1391:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1392: @*/
1393: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscBool  *set)
1394: {
1396:   PetscInt       ntext = 0,tval;
1397:   PetscBool      fset;

1400:   while (list[ntext++]) {
1401:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1402:   }
1403:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1404:   ntext -= 3;
1405:   PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1406:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1407:   if (fset) *value = (PetscEnum)tval;
1408:   if (set) *set = fset;
1409:   return(0);
1410: }

1414: /*@C
1415:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular 
1416:             option in the database.

1418:    Not Collective

1420:    Input Parameters:
1421: +  pre - the string to prepend to the name or PETSC_NULL
1422: -  name - the option one is seeking

1424:    Output Parameter:
1425: +  ivalue - the logical value to return
1426: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1428:    Level: beginner

1430:    Notes:
1431:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1432:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1437:    Concepts: options database^has logical

1439: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1440:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1441:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1442:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1443:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1444:           PetscOptionsList(), PetscOptionsEList()
1445: @*/
1446: PetscErrorCode  PetscOptionsGetBool(const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
1447: {
1448:   char           *value;
1449:   PetscBool      flag;

1455:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1456:   if (flag) {
1457:     if (set) *set = PETSC_TRUE;
1458:     if (!value) {
1459:       *ivalue = PETSC_TRUE;
1460:     } else {
1461:       PetscOptionsStringToBool(value, ivalue);
1462:     }
1463:   } else {
1464:     if (set) *set = PETSC_FALSE;
1465:   }
1466:   return(0);
1467: }

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

1476:    Not Collective

1478:    Input Parameters:
1479: +  pre - string to prepend to each name or PETSC_NULL
1480: .  name - the option one is seeking
1481: -  nmax - maximum number of values to retrieve

1483:    Output Parameter:
1484: +  dvalue - the integer values to return
1485: .  nmax - actual number of values retreived
1486: -  set - PETSC_TRUE if found, else PETSC_FALSE

1488:    Level: beginner

1490:    Concepts: options database^array of ints

1492:    Notes:
1493:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1494:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1496: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1497:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1498:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1499:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1500:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1501:           PetscOptionsList(), PetscOptionsEList()
1502: @*/
1503: PetscErrorCode  PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool  dvalue[],PetscInt *nmax,PetscBool  *set)
1504: {
1505:   char           *value;
1507:   PetscInt       n = 0;
1508:   PetscBool      flag;
1509:   PetscToken     token;

1514:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1515:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1516:   if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}

1518:   if (set) *set = PETSC_TRUE;

1520:   PetscTokenCreate(value,',',&token);
1521:   PetscTokenFind(token,&value);
1522:   while (n < *nmax) {
1523:     if (!value) break;
1524:     PetscOptionsStringToBool(value,dvalue);
1525:     PetscTokenFind(token,&value);
1526:     dvalue++;
1527:     n++;
1528:   }
1529:   PetscTokenDestroy(token);
1530:   *nmax = n;
1531:   return(0);
1532: }

1536: /*@C
1537:    PetscOptionsGetReal - Gets the double precision value for a particular 
1538:    option in the database.

1540:    Not Collective

1542:    Input Parameters:
1543: +  pre - string to prepend to each name or PETSC_NULL
1544: -  name - the option one is seeking

1546:    Output Parameter:
1547: +  dvalue - the double value to return
1548: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

1552:    Level: beginner

1554:    Concepts: options database^has double

1556: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1557:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1558:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1559:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1560:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1561:           PetscOptionsList(), PetscOptionsEList()
1562: @*/
1563: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
1564: {
1565:   char           *value;
1567:   PetscBool      flag;

1572:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1573:   if (flag) {
1574:     if (!value) {if (set) *set = PETSC_FALSE;}
1575:     else        {if (set) *set = PETSC_TRUE; PetscOptionsStringToReal(value,dvalue);}
1576:   } else {
1577:     if (set) *set = PETSC_FALSE;
1578:   }
1579:   return(0);
1580: }

1584: /*@C
1585:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1586:    option in the database.

1588:    Not Collective

1590:    Input Parameters:
1591: +  pre - string to prepend to each name or PETSC_NULL
1592: -  name - the option one is seeking

1594:    Output Parameter:
1595: +  dvalue - the double value to return
1596: -  set - PETSC_TRUE if found, else PETSC_FALSE

1598:    Level: beginner

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

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

1606:    Concepts: options database^has scalar

1608: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1609:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1610:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1611:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1612:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1613:           PetscOptionsList(), PetscOptionsEList()
1614: @*/
1615: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
1616: {
1617:   char           *value;
1618:   PetscBool      flag;

1624:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1625:   if (flag) {
1626:     if (!value) {
1627:       if (set) *set = PETSC_FALSE;
1628:     } else {
1629: #if !defined(PETSC_USE_COMPLEX)
1630:       PetscOptionsStringToReal(value,dvalue);
1631: #else
1632:       PetscReal  re=0.0,im=0.0;
1633:       PetscToken token;
1634:       char       *tvalue = 0;

1636:       PetscTokenCreate(value,',',&token);
1637:       PetscTokenFind(token,&tvalue);
1638:       if (!tvalue) { SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1639:       PetscOptionsStringToReal(tvalue,&re);
1640:       PetscTokenFind(token,&tvalue);
1641:       if (!tvalue) { /* Unknown separator used. using only real value */
1642:         *dvalue = re;
1643:       } else {
1644:         PetscOptionsStringToReal(tvalue,&im);
1645:         *dvalue = re + PETSC_i*im;
1646:       }
1647:       PetscTokenDestroy(token);
1648: #endif
1649:       if (set) *set    = PETSC_TRUE;
1650:     }
1651:   } else { /* flag */
1652:     if (set) *set = PETSC_FALSE;
1653:   }
1654:   return(0);
1655: }

1659: /*@C
1660:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1661:    particular option in the database.  The values must be separated with 
1662:    commas with no intervening spaces.

1664:    Not Collective

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

1671:    Output Parameters:
1672: +  dvalue - the double value to return
1673: .  nmax - actual number of values retreived
1674: -  set - PETSC_TRUE if found, else PETSC_FALSE

1676:    Level: beginner

1678:    Concepts: options database^array of doubles

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

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

1702:   if (set) *set = PETSC_TRUE;

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

1719: /*@C
1720:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1721:    option in the database.  The values must be separated with commas with 
1722:    no intervening spaces. 

1724:    Not Collective

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

1731:    Output Parameter:
1732: +  dvalue - the integer values to return
1733: .  nmax - actual number of values retreived
1734: -  set - PETSC_TRUE if found, else PETSC_FALSE

1736:    Level: beginner

1738:    Concepts: options database^array of ints

1740: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1741:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1742:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1743:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1744:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1745:           PetscOptionsList(), PetscOptionsEList()
1746: @*/
1747: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
1748: {
1749:   char           *value;
1751:   PetscInt       n = 0,i,start,end;
1752:   size_t         len;
1753:   PetscBool      flag,foundrange;
1754:   PetscToken     token;

1759:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1760:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1761:   if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}

1763:   if (set) *set = PETSC_TRUE;

1765:   PetscTokenCreate(value,',',&token);
1766:   PetscTokenFind(token,&value);
1767:   while (n < *nmax) {
1768:     if (!value) break;
1769: 
1770:     /* look for form  d-D where d and D are integers */
1771:     foundrange = PETSC_FALSE;
1772:     PetscStrlen(value,&len);
1773:     if (value[0] == '-') i=2;
1774:     else i=1;
1775:     for (;i<(int)len; i++) {
1776:       if (value[i] == '-') {
1777:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1778:         value[i] = 0;
1779:         PetscOptionsStringToInt(value,&start);
1780:         PetscOptionsStringToInt(value+i+1,&end);
1781:         if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1782:         if (n + end - start - 1 >= *nmax) SETERRQ4(PETSC_COMM_SELF,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);
1783:         for (;start<end; start++) {
1784:           *dvalue = start; dvalue++;n++;
1785:         }
1786:         foundrange = PETSC_TRUE;
1787:         break;
1788:       }
1789:     }
1790:     if (!foundrange) {
1791:       PetscOptionsStringToInt(value,dvalue);
1792:       dvalue++;
1793:       n++;
1794:     }
1795:     PetscTokenFind(token,&value);
1796:   }
1797:   PetscTokenDestroy(token);
1798:   *nmax = n;
1799:   return(0);
1800: }

1804: /*@C
1805:    PetscOptionsGetString - Gets the string value for a particular option in
1806:    the database.

1808:    Not Collective

1810:    Input Parameters:
1811: +  pre - string to prepend to name or PETSC_NULL
1812: .  name - the option one is seeking
1813: -  len - maximum length of the string including null termination

1815:    Output Parameters:
1816: +  string - location to copy string
1817: -  set - PETSC_TRUE if found, else PETSC_FALSE

1819:    Level: beginner

1821:    Fortran Note:
1822:    The Fortran interface is slightly different from the C/C++
1823:    interface (len is not used).  Sample usage in Fortran follows
1824: .vb
1825:       character *20 string
1826:       integer   flg, ierr
1827:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1828: .ve

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

1832:    Concepts: options database^string

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

1837: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1838:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1839:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1840:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1841:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1842:           PetscOptionsList(), PetscOptionsEList()
1843: @*/
1844: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
1845: {
1846:   char           *value;
1848:   PetscBool      flag;

1853:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1854:   if (!flag) {
1855:     if (set) *set = PETSC_FALSE;
1856:   } else {
1857:     if (set) *set = PETSC_TRUE;
1858:     if (value) {
1859:       PetscStrncpy(string,value,len);
1860:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
1861:     } else {
1862:       PetscMemzero(string,len);
1863:     }
1864:   }
1865:   return(0);
1866: }

1870: char* PetscOptionsGetStringMatlab(const char pre[],const char name[])
1871: {
1872:   char           *value;
1874:   PetscBool      flag;

1877:   PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
1878:   if (flag) PetscFunctionReturn(value);
1879:   else return(0);
1880: }


1885: /*@C
1886:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1887:    option in the database. The values must be separated with commas with 
1888:    no intervening spaces. 

1890:    Not Collective

1892:    Input Parameters:
1893: +  pre - string to prepend to name or PETSC_NULL
1894: .  name - the option one is seeking
1895: -  nmax - maximum number of strings

1897:    Output Parameter:
1898: +  strings - location to copy strings
1899: -  set - PETSC_TRUE if found, else PETSC_FALSE

1901:    Level: beginner

1903:    Notes: 
1904:    The user should pass in an array of pointers to char, to hold all the
1905:    strings returned by this function.

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

1910:    Contributed by Matthew Knepley.

1912:    Concepts: options database^array of strings

1914: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1915:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1916:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1917:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1918:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1919:           PetscOptionsList(), PetscOptionsEList()
1920: @*/
1921: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
1922: {
1923:   char           *value;
1925:   PetscInt       n;
1926:   PetscBool      flag;
1927:   PetscToken     token;
1928: 
1932:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1933:   if (!flag)  {*nmax = 0; if (set) *set = PETSC_FALSE; return(0);}
1934:   if (!value) {*nmax = 0; if (set) *set = PETSC_FALSE;return(0);}
1935:   if (!*nmax) {if (set) *set = PETSC_FALSE;return(0);}
1936:   if (set) *set = PETSC_TRUE;

1938:   PetscTokenCreate(value,',',&token);
1939:   PetscTokenFind(token,&value);
1940:   n = 0;
1941:   while (n < *nmax) {
1942:     if (!value) break;
1943:     PetscStrallocpy(value,&strings[n]);
1944:     PetscTokenFind(token,&value);
1945:     n++;
1946:   }
1947:   PetscTokenDestroy(token);
1948:   *nmax = n;
1949:   return(0);
1950: }

1954: /*@C
1955:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1956:    database that have never been selected.

1958:    Not Collective

1960:    Output Parameter:
1961: .   N - count of options not used

1963:    Level: advanced

1965: .seealso: PetscOptionsView()
1966: @*/
1967: PetscErrorCode  PetscOptionsAllUsed(PetscInt *N)
1968: {
1969:   PetscInt i,n = 0;

1972:   for (i=0; i<options->N; i++) {
1973:     if (!options->used[i]) { n++; }
1974:   }
1975:   *N = n;
1976:   return(0);
1977: }

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

1984:   Not collective

1986:    Options Database Key:
1987: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1989:   Level: advanced

1991: .seealso: PetscOptionsAllUsed()
1992: @*/
1993: PetscErrorCode  PetscOptionsLeft(void)
1994: {
1996:   PetscInt       i;

1999:   for (i=0; i<options->N; i++) {
2000:     if (!options->used[i]) {
2001:       if (options->values[i]) {
2002:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2003:       } else {
2004:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
2005:       }
2006:     }
2007:   }
2008:   return(0);
2009: }


2014: /*
2015:     PetscOptionsCreate - Creates the empty options database.

2017: */
2018: PetscErrorCode  PetscOptionsCreate(void)
2019: {

2023:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
2024:   PetscMemzero(options,sizeof(PetscOptionsTable));
2025:   options->namegiven                 = PETSC_FALSE;
2026:   options->N                         = 0;
2027:   options->Naliases                  = 0;
2028:   options->numbermonitors         = 0;

2030:   PetscOptionsObject.prefix = PETSC_NULL;
2031:   PetscOptionsObject.title  = PETSC_NULL;
2032: 
2033:   return(0);
2034: }

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

2041:    Collective on PETSC_COMM_WORLD

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

2050:    Notes:
2051:    To see all options, run your program with the -help option or consult
2052:    the <A href="../../docs/manual.pdf">users manual</A>.. 

2054:    Level: intermediate

2056: .keywords: set, options, database
2057: @*/
2058: PetscErrorCode  PetscOptionsSetFromOptions(void)
2059: {
2060:   PetscBool           flgc,flgm;
2061:   PetscErrorCode      ierr;
2062:   char                monfilename[PETSC_MAX_PATH_LEN];
2063:   PetscViewer         monviewer;

2066:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
2067:     PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2068:     PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",PETSC_FALSE,&flgc,PETSC_NULL);
2069:   PetscOptionsEnd();
2070:   if (flgm) {
2071:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2072:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2073:   }
2074:   if (flgc) { PetscOptionsMonitorCancel(); }
2075:   return(0);
2076: }


2081: /*@C
2082:    PetscOptionsMonitorDefault - Print all options set value events.

2084:    Logically Collective on PETSC_COMM_WORLD

2086:    Input Parameters:
2087: +  name  - option name string
2088: .  value - option value string
2089: -  dummy - unused monitor context 

2091:    Level: intermediate

2093: .keywords: PetscOptions, default, monitor

2095: .seealso: PetscOptionsMonitorSet()
2096: @*/
2097: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2098: {
2100:   PetscViewer    viewer = (PetscViewer) dummy;

2103:   if (!viewer) {
2104:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
2105:   }
2106:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2107:   return(0);
2108: }

2112: /*@C
2113:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2114:    modified the PETSc options database.
2115:       
2116:    Not collective

2118:    Input Parameters:
2119: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
2120: .  mctx    - [optional] context for private data for the
2121:              monitor routine (use PETSC_NULL if no context is desired)
2122: -  monitordestroy - [optional] routine that frees monitor context
2123:           (may be PETSC_NULL)

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

2128: +  name - option name string
2129: .  value - option value string
2130: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

2132:    Options Database Keys:
2133: +    -options_monitor    - sets PetscOptionsMonitorDefault()
2134: -    -options_monitor_cancel - cancels all monitors that have
2135:                           been hardwired into a code by 
2136:                           calls to PetscOptionsMonitorSet(), but
2137:                           does not cancel those set via
2138:                           the options database.

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

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

2149:    Level: beginner

2151: .keywords: PetscOptions, set, monitor

2153: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2154: @*/
2155: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2156: {
2158:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2159:   options->monitor[options->numbermonitors]           = monitor;
2160:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
2161:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
2162:   return(0);
2163: }

2167: /*@
2168:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2170:    Not collective 

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

2177:    Level: intermediate

2179: .keywords: PetscOptions, set, monitor

2181: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2182: @*/
2183: PetscErrorCode  PetscOptionsMonitorCancel(void)
2184: {
2186:   PetscInt       i;

2189:   for (i=0; i<options->numbermonitors; i++) {
2190:     if (options->monitordestroy[i]) {
2191:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
2192:     }
2193:   }
2194:   options->numbermonitors = 0;
2195:   return(0);
2196: }