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;
 57: extern PetscOptionsObjectType PetscOptionsObject;

 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: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
113:     *a = _atoi64(name);
114: #else
115:     *a = (PetscInt)atoi(name);
116: #endif
117:   }
118:   return(0);
119: }

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

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

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

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

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

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

194: /*@C
195:     PetscGetProgramName - Gets the name of the running program. 

197:     Not Collective

199:     Input Parameter:
200: .   len - length of the string name

202:     Output Parameter:
203: .   name - the name of the running program

205:    Level: advanced

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

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

225: PetscErrorCode  PetscSetProgramName(const char name[])
226: {

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

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

240:    Input Parameter:
241: .    in_str - string to check if valid

243:    Output Parameter:
244: .    key - PETSC_TRUE if a valid key

246:   Level: intermediate

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

263: /*@C
264:      PetscOptionsInsertString - Inserts options into the database from a string

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

269:   Input Parameter:
270: .   in_str - string that contains options separated by blanks


273:   Level: intermediate

275:   Contributed by Boyana Norris

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

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

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

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

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


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

355:      Collective on MPI_Comm

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


363:   Level: developer

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

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

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

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

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

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

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

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

500: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
501: {
503:   int            left    = argc - 1;
504:   char           **eargs = args + 1;

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

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

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


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

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

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

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

581:    Level: advanced

583:    Concepts: options database^adding

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

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

602:   options->argc     = (argc) ? *argc : 0;
603:   options->args     = (args) ? *args : PETSC_NULL;

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

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

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

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

657:   return(0);
658: }

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

666:    Logically Collective on PetscViewer

668:    Input Parameter:
669: .  viewer - must be an PETSCVIEWERASCII viewer

671:    Options Database Key:
672: .  -optionstable - Activates PetscOptionsView() within PetscFinalize()

674:    Level: advanced

676:    Concepts: options database^printing

678: .seealso: PetscOptionsAllUsed()
679: @*/
680: PetscErrorCode  PetscOptionsView(PetscViewer viewer)
681: {
683:   PetscInt       i;
684:   PetscBool      isascii;

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

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

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

715:    Not Collective

717:    Output Parameter:
718: .  copts - pointer where string pointer is stored

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

722:    Level: advanced

724:    Concepts: options database^listing

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

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

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

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

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

769:    Input Parameter:
770: .  prefix - The string to append to the existing prefix

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

776:    Notes:
777:    It is common to use this in conjunction with -options_file as in

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

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

783: Level: advanced

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

797:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
798:   buf[0] = '-';
799:   PetscStrncpy(buf+1,prefix,sizeof buf - 1);
800:   buf[sizeof buf - 1] = 0;
801:   PetscOptionsValidKey(buf,&key);
802:   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);

804:   if (!options) {PetscOptionsInsert(0,0,0);}
805:   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);
806:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
807:   PetscStrlen(prefix,&n);
808:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
809:   PetscMemcpy(options->prefix+start,prefix,n+1);
810:   options->prefixstack[options->prefixind++] = start+n;
811:   return(0);
812: }

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

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

821:    Level: advanced

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

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

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

842:    Level: developer

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

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

869: /*@C
870:     PetscOptionsDestroy - Destroys the option database. 

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

876:    Level: developer

878: .seealso: PetscOptionsInsert()
879: @*/
880: PetscErrorCode  PetscOptionsDestroy(void)
881: {

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

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

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

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

905:    Level: intermediate

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

911:   Concepts: options database^adding option

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

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

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

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

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

949:   N     = options->N;
950:   n     = N;
951:   names = options->names;
952: 
953:   for (i=0; i<N; i++) {
954:     PetscStrcasecmp(names[i],name,&match);
955:     PetscStrgrt(names[i],name,&gt);
956:     if (match) {
957:       if (options->values[i]) free(options->values[i]);
958:       PetscStrlen(value,&len);
959:       if (len) {
960:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
961:         PetscStrcpy(options->values[i],value);
962:       } else { options->values[i] = 0;}
963:       PetscOptionsMonitor(name,value);
964:       return(0);
965:     } else if (gt) {
966:       n = i;
967:       break;
968:     }
969:   }
970:   if (N >= MAXOPTIONS) {
971:     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);
972:   }
973:   /* shift remaining values down 1 */
974:   for (i=N; i>n; i--) {
975:     options->names[i]  = options->names[i-1];
976:     options->values[i] = options->values[i-1];
977:     options->used[i]   = options->used[i-1];
978:   }
979:   /* insert new name and value */
980:   PetscStrlen(name,&len);
981:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
982:   PetscStrcpy(options->names[n],name);
983:   PetscStrlen(value,&len);
984:   if (len) {
985:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
986:     PetscStrcpy(options->values[n],value);
987:   } else {options->values[n] = 0;}
988:   options->used[n] = PETSC_FALSE;
989:   options->N++;
990:   PetscOptionsMonitor(name,value);
991:   return(0);
992: }

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

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

1003:    Input Parameter:
1004: .  name - name of option, this SHOULD have the - prepended

1006:    Level: intermediate

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

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

1022:   name++;

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

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

1054: /*@C
1055:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1060:    Input Parameters:
1061: +  inewname - the alias
1062: -  ioldname - the name that alias will refer to 

1064:    Level: advanced

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

1081:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1082:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1083:   if (n >= MAXALIASES) {
1084:     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);
1085:   }

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

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

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

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

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

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

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

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

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

1179:    Level: advanced

1181:    Concepts: options database^rejecting option

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

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

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

1213:    Not Collective

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

1219:    Output Parameters:
1220: .  set - PETSC_TRUE if found else PETSC_FALSE.

1222:    Level: beginner

1224:    Concepts: options database^has option name

1226:    Notes: Name cannot be simply -h

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

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

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

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

1254:    Not Collective

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

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

1264:    Level: beginner

1266:    Concepts: options database^has int

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

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

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

1303:    Not Collective

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

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

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

1319:    Concepts: options database^list

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

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

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

1367:    Not Collective

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

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

1379:    Level: beginner

1381:    Concepts: options database

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

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

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

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

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

1420:    Not Collective

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

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

1430:    Level: beginner

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

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

1439:    Concepts: options database^has logical

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

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

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

1478:    Not Collective

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

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

1490:    Level: beginner

1492:    Concepts: options database^array of ints

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

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

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

1520:   if (set) *set = PETSC_TRUE;

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

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

1542:    Not Collective

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

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

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

1554:    Level: beginner

1556:    Concepts: options database^has double

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

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

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

1590:    Not Collective

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

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

1600:    Level: beginner

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

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

1608:    Concepts: options database^has scalar

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

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

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

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

1666:    Not Collective

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

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

1678:    Level: beginner

1680:    Concepts: options database^array of doubles

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

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

1704:   if (set) *set = PETSC_TRUE;

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

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

1726:    Not Collective

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

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

1738:    Level: beginner

1740:    Concepts: options database^array of ints

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

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

1765:   if (set) *set = PETSC_TRUE;

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

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

1810:    Not Collective

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

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

1821:    Level: beginner

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

1832:    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

1834:    Concepts: options database^string

1836:     Note:
1837:       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).

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

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

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

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


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

1892:    Not Collective

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

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

1903:    Level: beginner

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

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

1912:    Contributed by Matthew Knepley.

1914:    Concepts: options database^array of strings

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

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

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

1960:    Not Collective

1962:    Output Parameter:
1963: .   N - count of options not used

1965:    Level: advanced

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

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

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

1986:   Not collective

1988:    Options Database Key:
1989: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1991:   Level: advanced

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

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


2016: /*
2017:     PetscOptionsCreate - Creates the empty options database.

2019: */
2020: PetscErrorCode  PetscOptionsCreate(void)
2021: {

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

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

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

2043:    Collective on PETSC_COMM_WORLD

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

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

2056:    Level: intermediate

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

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


2083: /*@C
2084:    PetscOptionsMonitorDefault - Print all options set value events.

2086:    Logically Collective on PETSC_COMM_WORLD

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

2093:    Level: intermediate

2095: .keywords: PetscOptions, default, monitor

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

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

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

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

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

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

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

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

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

2151:    Level: beginner

2153: .keywords: PetscOptions, set, monitor

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

2169: /*@
2170:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2172:    Not collective 

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

2179:    Level: intermediate

2181: .keywords: PetscOptions, set, monitor

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

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