Actual source code: options.c

petsc-master 2020-08-06
Report Typos and Errors
  1: /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
  2: #define PETSC_DESIRE_FEATURE_TEST_MACROS /* for atoll() */

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

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

 12:  #include <petsc/private/petscimpl.h>
 13:  #include <petscviewer.h>
 14: #include <ctype.h>
 15: #if defined(PETSC_HAVE_MALLOC_H)
 16: #include <malloc.h>
 17: #endif
 18: #if defined(PETSC_HAVE_STRINGS_H)
 19: #  include <strings.h>          /* strcasecmp */
 20: #endif
 21: #if defined(PETSC_HAVE_YAML)
 22: #include <yaml.h>
 23: #endif

 25: #if defined(PETSC_HAVE_STRCASECMP)
 26: #define PetscOptNameCmp(a,b) strcasecmp(a,b)
 27: #elif defined(PETSC_HAVE_STRICMP)
 28: #define PetscOptNameCmp(a,b) stricmp(a,b)
 29: #else
 30: #define PetscOptNameCmp(a,b) Error_strcasecmp_not_found
 31: #endif

 33:  #include <petsc/private/hashtable.h>

 35: /* This assumes ASCII encoding and ignores locale settings */
 36: /* Using tolower() is about 2X slower in microbenchmarks   */
 37: PETSC_STATIC_INLINE int PetscToLower(int c)
 38: {
 39:   return ((c >= 'A') & (c <= 'Z')) ? c + 'a' - 'A' : c;
 40: }

 42: /* Bob Jenkins's one at a time hash function (case-insensitive) */
 43: PETSC_STATIC_INLINE unsigned int PetscOptHash(const char key[])
 44: {
 45:   unsigned int hash = 0;
 46:   while (*key) {
 47:     hash += PetscToLower(*key++);
 48:     hash += hash << 10;
 49:     hash ^= hash >>  6;
 50:   }
 51:   hash += hash <<  3;
 52:   hash ^= hash >> 11;
 53:   hash += hash << 15;
 54:   return hash;
 55: }

 57: PETSC_STATIC_INLINE int PetscOptEqual(const char a[],const char b[])
 58: {
 59:   return !PetscOptNameCmp(a,b);
 60: }

 62: KHASH_INIT(HO, kh_cstr_t, int, 1, PetscOptHash, PetscOptEqual)

 64: /*
 65:     This table holds all the options set by the user. For simplicity, we use a static size database
 66: */
 67: #define MAXOPTNAME 512
 68: #define MAXOPTIONS 512
 69: #define MAXALIASES  25
 70: #define MAXPREFIXES 25
 71: #define MAXOPTIONSMONITORS 5

 73: struct  _n_PetscOptions {
 74:   PetscOptions   previous;
 75:   int            N;                    /* number of options */
 76:   char           *names[MAXOPTIONS];   /* option names */
 77:   char           *values[MAXOPTIONS];  /* option values */
 78:   PetscBool      used[MAXOPTIONS];     /* flag option use */
 79:   PetscBool      precedentProcessed;

 81:   /* Hash table */
 82:   khash_t(HO)    *ht;

 84:   /* Prefixes */
 85:   int            prefixind;
 86:   int            prefixstack[MAXPREFIXES];
 87:   char           prefix[MAXOPTNAME];

 89:   /* Aliases */
 90:   int            Naliases;                   /* number or aliases */
 91:   char           *aliases1[MAXALIASES];      /* aliased */
 92:   char           *aliases2[MAXALIASES];      /* aliasee */

 94:   /* Help */
 95:   PetscBool      help;       /* flag whether "-help" is in the database */
 96:   PetscBool      help_intro; /* flag whether "-help intro" is in the database */

 98:   /* Monitors */
 99:   PetscBool      monitorFromOptions, monitorCancel;
100:   PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[],const char[],void*); /* returns control to user after */
101:   PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**);         /* */
102:   void           *monitorcontext[MAXOPTIONSMONITORS];                  /* to pass arbitrary user data into monitor */
103:   PetscInt       numbermonitors;                                       /* to, for instance, detect options being set */
104: };

106: static PetscOptions defaultoptions = NULL;  /* the options database routines query this object for options */

108: /* list of options which preceed others, i.e., are processed in PetscOptionsProcessPrecedentFlags() */
109: static const char *precedentOptions[] = {"-options_monitor","-options_monitor_cancel","-help","-skip_petscrc","-options_file_yaml","-options_string_yaml"};
110: enum PetscPrecedentOption {PO_OPTIONS_MONITOR,PO_OPTIONS_MONITOR_CANCEL,PO_HELP,PO_SKIP_PETSCRC,PO_OPTIONS_FILE_YAML,PO_OPTIONS_STRING_YAML,PO_NUM};

112: static PetscErrorCode PetscOptionsSetValue_Private(PetscOptions,const char[],const char[],int*);

114: /*
115:     Options events monitor
116: */
117: static PetscErrorCode PetscOptionsMonitor(PetscOptions options,const char name[],const char value[])
118: {
119:   PetscInt       i;

122:   if (!PetscErrorHandlingInitialized) return 0;
124:   if (!value) value = "";
125:   if (options->monitorFromOptions) {
126:     PetscOptionsMonitorDefault(name,value,NULL);
127:   }
128:   for (i=0; i<options->numbermonitors; i++) {
129:     (*options->monitor[i])(name,value,options->monitorcontext[i]);
130:   }
131:   return(0);
132: }

134: /*@
135:    PetscOptionsCreate - Creates an empty options database.

137:    Logically collective

139:    Output Parameter:
140: .  options - Options database object

142:    Level: advanced

144:    Developer Note: We may want eventually to pass a MPI_Comm to determine the ownership of the object

146: .seealso: PetscOptionsDestroy(), PetscOptionsPush(), PetscOptionsPop(), PetscOptionsInsert(), PetscOptionsSetValue()
147: @*/
148: PetscErrorCode PetscOptionsCreate(PetscOptions *options)
149: {
150:   if (!options) return PETSC_ERR_ARG_NULL;
151:   *options = (PetscOptions)calloc(1,sizeof(**options));
152:   if (!*options) return PETSC_ERR_MEM;
153:   return 0;
154: }

156: /*@
157:     PetscOptionsDestroy - Destroys an option database.

159:     Logically collective on whatever communicator was associated with the call to PetscOptionsCreate()

161:   Input Parameter:
162: .  options - the PetscOptions object

164:    Level: advanced

166: .seealso: PetscOptionsInsert(), PetscOptionsPush(), PetscOptionsPop(), PetscOptionsInsert(), PetscOptionsSetValue()
167: @*/
168: PetscErrorCode PetscOptionsDestroy(PetscOptions *options)
169: {

172:   if (!*options) return 0;
173:   if ((*options)->previous) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"You are destroying an option that has been used with PetscOptionsPush() but does not have a corresponding PetscOptionsPop()");
174:   PetscOptionsClear(*options);if (ierr) return ierr;
175:   /* XXX what about monitors ? */
176:   free(*options);
177:   *options = NULL;
178:   return(0);
179: }

181: /*
182:     PetscOptionsCreateDefault - Creates the default global options database
183: */
184: PetscErrorCode PetscOptionsCreateDefault(void)
185: {

188:   if (!defaultoptions) {
189:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
190:   }
191:   return 0;
192: }

194: /*@
195:       PetscOptionsPush - Push a new PetscOptions object as the default provider of options
196:                          Allows using different parts of a code to use different options databases

198:   Logically Collective

200:   Input Parameter:
201: .   opt - the options obtained with PetscOptionsCreate()

203:   Notes:
204:   Use PetscOptionsPop() to return to the previous default options database

206:   The collectivity of this routine is complex; only the MPI processes that call this routine will
207:   have the affect of these options. If some processes that create objects call this routine and others do
208:   not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
209:   on different ranks.

211:    Level: advanced

213: .seealso: PetscOptionsPop(), PetscOptionsCreate(), PetscOptionsInsert(), PetscOptionsSetValue(), PetscOptionsLeft()

215: @*/
216: PetscErrorCode PetscOptionsPush(PetscOptions opt)
217: {

221:   PetscOptionsCreateDefault();
222:   opt->previous        = defaultoptions;
223:   defaultoptions       = opt;
224:   return(0);
225: }

227: /*@
228:       PetscOptionsPop - Pop the most recent PetscOptionsPush() to return to the previous default options

230:       Logically collective on whatever communicator was associated with the call to PetscOptionsCreate()

232:   Notes:
233:   Use PetscOptionsPop() to return to the previous default options database
234:   Allows using different parts of a code to use different options databases

236:    Level: advanced

238: .seealso: PetscOptionsPop(), PetscOptionsCreate(), PetscOptionsInsert(), PetscOptionsSetValue(), PetscOptionsLeft()

240: @*/
241: PetscErrorCode PetscOptionsPop(void)
242: {
243:   PetscOptions current = defaultoptions;

246:   if (!defaultoptions) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Missing default options");
247:   if (!defaultoptions->previous) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"PetscOptionsPop() called too many times");
248:   defaultoptions = defaultoptions->previous;
249:   current->previous    = NULL;
250:   return(0);
251: }

253: /*
254:     PetscOptionsDestroyDefault - Destroys the default global options database
255: */
256: PetscErrorCode PetscOptionsDestroyDefault(void)
257: {
259:   PetscOptions   tmp;

261:   /* Destroy any options that the user forgot to pop */
262:   while (defaultoptions->previous) {
263:     tmp = defaultoptions;
264:     PetscOptionsPop();
265:     PetscOptionsDestroy(&tmp);
266:   }
267:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
268:   return 0;
269: }

271: /*@C
272:    PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter.

274:    Not collective

276:    Input Parameter:
277: .  key - string to check if valid

279:    Output Parameter:
280: .  valid - PETSC_TRUE if a valid key

282:    Level: intermediate
283: @*/
284: PetscErrorCode PetscOptionsValidKey(const char key[],PetscBool *valid)
285: {
286:   char           *ptr;

291:   *valid = PETSC_FALSE;
292:   if (!key) return(0);
293:   if (key[0] != '-') return(0);
294:   if (key[1] == '-') key++;
295:   if (!isalpha((int)key[1])) return(0);
296:   (void) strtod(key,&ptr);
297:   if (ptr != key && !(*ptr == '_' || isalnum((int)*ptr))) return(0);
298:   *valid = PETSC_TRUE;
299:   return(0);
300: }

302: /*@C
303:    PetscOptionsInsertString - Inserts options into the database from a string

305:    Logically Collective

307:    Input Parameter:
308: +  options - options object
309: -  in_str - string that contains options separated by blanks

311:    Level: intermediate

313:   The collectivity of this routine is complex; only the MPI processes that call this routine will
314:   have the affect of these options. If some processes that create objects call this routine and others do
315:   not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
316:   on different ranks.

318:    Contributed by Boyana Norris

320: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
321:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
322:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
323:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
324:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
325:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()
326: @*/
327: PetscErrorCode PetscOptionsInsertString(PetscOptions options,const char in_str[])
328: {
329:   char           *first,*second;
331:   PetscToken     token;
332:   PetscBool      key,ispush,ispop,isopts;

335:   PetscTokenCreate(in_str,' ',&token);
336:   PetscTokenFind(token,&first);
337:   while (first) {
338:     PetscStrcasecmp(first,"-prefix_push",&ispush);
339:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
340:     PetscStrcasecmp(first,"-options_file",&isopts);
341:     PetscOptionsValidKey(first,&key);
342:     if (ispush) {
343:       PetscTokenFind(token,&second);
344:       PetscOptionsPrefixPush(options,second);
345:       PetscTokenFind(token,&first);
346:     } else if (ispop) {
347:       PetscOptionsPrefixPop(options);
348:       PetscTokenFind(token,&first);
349:     } else if (isopts) {
350:       PetscTokenFind(token,&second);
351:       PetscOptionsInsertFile(PETSC_COMM_SELF,options,second,PETSC_TRUE);
352:       PetscTokenFind(token,&first);
353:     } else if (key) {
354:       PetscTokenFind(token,&second);
355:       PetscOptionsValidKey(second,&key);
356:       if (!key) {
357:         PetscOptionsSetValue(options,first,second);
358:         PetscTokenFind(token,&first);
359:       } else {
360:         PetscOptionsSetValue(options,first,NULL);
361:         first = second;
362:       }
363:     } else {
364:       PetscTokenFind(token,&first);
365:     }
366:   }
367:   PetscTokenDestroy(&token);
368:   return(0);
369: }

371: /*
372:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
373: */
374: static char *Petscgetline(FILE * f)
375: {
376:   size_t size  = 0;
377:   size_t len   = 0;
378:   size_t last  = 0;
379:   char   *buf  = NULL;

381:   if (feof(f)) return NULL;
382:   do {
383:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
384:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
385:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
386:     end of the string, so we make sure we overwrite this */
387:     if (!fgets(buf+len,1024,f)) buf[len]=0;
388:     PetscStrlen(buf,&len);
389:     last = len - 1;
390:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
391:   if (len) return buf;
392:   free(buf);
393:   return NULL;
394: }

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

399:      Collective

401:   Input Parameter:
402: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
403: .   options - options database, use NULL for default global database
404: .   file - name of file
405: -   require - if PETSC_TRUE will generate an error if the file does not exist


408:   Notes:
409:     Use  # for lines that are comments and which should be ignored.
410:     Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
411:    such as -log_view or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later
412:    calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().
413:    The collectivity of this routine is complex; only the MPI processes in comm will
414:    have the affect of these options. If some processes that create objects call this routine and others do
415:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
416:    on different ranks.

418:   Level: developer

420: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
421:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
422:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
423:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
424:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
425:           PetscOptionsFList(), PetscOptionsEList()

427: @*/
428: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
429: {
430:   char           *string,fname[PETSC_MAX_PATH_LEN],*vstring = NULL,*astring = NULL,*packed = NULL;
431:   char           *tokens[4];
433:   size_t         i,len,bytes;
434:   FILE           *fd;
435:   PetscToken     token=NULL;
436:   int            err;
437:   char           *cmatch;
438:   const char     cmt='#';
439:   PetscInt       line=1;
440:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];
441:   PetscBool      isdir,alias=PETSC_FALSE,valid;

444:   MPI_Comm_rank(comm,&rank);
445:   PetscMemzero(tokens,sizeof(tokens));
446:   if (!rank) {
447:     cnt        = 0;
448:     acnt       = 0;

450:     PetscFixFilename(file,fname);
451:     fd   = fopen(fname,"r");
452:     PetscTestDirectory(fname,'r',&isdir);
453:     if (isdir && require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Specified options file %s is a directory",fname);
454:     if (fd && !isdir) {
455:       PetscSegBuffer vseg,aseg;
456:       PetscSegBufferCreate(1,4000,&vseg);
457:       PetscSegBufferCreate(1,2000,&aseg);

459:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
460:       PetscInfo1(NULL,"Opened options file %s\n",file);

462:       while ((string = Petscgetline(fd))) {
463:         /* eliminate comments from each line */
464:         PetscStrchr(string,cmt,&cmatch);
465:         if (cmatch) *cmatch = 0;
466:         PetscStrlen(string,&len);
467:         /* replace tabs, ^M, \n with " " */
468:         for (i=0; i<len; i++) {
469:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
470:             string[i] = ' ';
471:           }
472:         }
473:         PetscTokenCreate(string,' ',&token);
474:         PetscTokenFind(token,&tokens[0]);
475:         if (!tokens[0]) {
476:           goto destroy;
477:         } else if (!tokens[0][0]) { /* if token 0 is empty (string begins with spaces), redo */
478:           PetscTokenFind(token,&tokens[0]);
479:         }
480:         for (i=1; i<4; i++) {
481:           PetscTokenFind(token,&tokens[i]);
482:         }
483:         if (!tokens[0]) {
484:           goto destroy;
485:         } else if (tokens[0][0] == '-') {
486:           PetscOptionsValidKey(tokens[0],&valid);
487:           if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: invalid option %s",fname,line,tokens[0]);
488:           PetscStrlen(tokens[0],&len);
489:           PetscSegBufferGet(vseg,len+1,&vstring);
490:           PetscArraycpy(vstring,tokens[0],len);
491:           vstring[len] = ' ';
492:           if (tokens[1]) {
493:             PetscOptionsValidKey(tokens[1],&valid);
494:             if (valid) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: cannot specify two options per line (%s %s)",fname,line,tokens[0],tokens[1]);
495:             PetscStrlen(tokens[1],&len);
496:             PetscSegBufferGet(vseg,len+3,&vstring);
497:             vstring[0] = '"';
498:             PetscArraycpy(vstring+1,tokens[1],len);
499:             vstring[len+1] = '"';
500:             vstring[len+2] = ' ';
501:           }
502:         } else {
503:           PetscStrcasecmp(tokens[0],"alias",&alias);
504:           if (alias) {
505:             PetscOptionsValidKey(tokens[1],&valid);
506:             if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: invalid aliased option %s",fname,line,tokens[1]);
507:             if (!tokens[2]) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: alias missing for %s",fname,line,tokens[1]);
508:             PetscOptionsValidKey(tokens[2],&valid);
509:             if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: invalid aliasee option %s",fname,line,tokens[2]);
510:             PetscStrlen(tokens[1],&len);
511:             PetscSegBufferGet(aseg,len+1,&astring);
512:             PetscArraycpy(astring,tokens[1],len);
513:             astring[len] = ' ';

515:             PetscStrlen(tokens[2],&len);
516:             PetscSegBufferGet(aseg,len+1,&astring);
517:             PetscArraycpy(astring,tokens[2],len);
518:             astring[len] = ' ';
519:           } else SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown first token in options file %s line %D: %s",fname,line,tokens[0]);
520:         }
521:         {
522:           const char *extraToken = alias ? tokens[3] : tokens[2];
523:           if (extraToken) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file %s line %D: extra token %s",fname,line,extraToken);
524:         }
525: destroy:
526:         free(string);
527:         PetscTokenDestroy(&token);
528:         alias = PETSC_FALSE;
529:         line++;
530:       }
531:       err = fclose(fd);
532:       if (err) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file %s",fname);
533:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
534:       PetscMPIIntCast(bytes,&acnt);
535:       PetscSegBufferGet(aseg,1,&astring);
536:       astring[0] = 0;
537:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
538:       PetscMPIIntCast(bytes,&cnt);
539:       PetscSegBufferGet(vseg,1,&vstring);
540:       vstring[0] = 0;
541:       PetscMalloc1(2+acnt+cnt,&packed);
542:       PetscSegBufferExtractTo(aseg,packed);
543:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
544:       PetscSegBufferDestroy(&aseg);
545:       PetscSegBufferDestroy(&vseg);
546:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open options file %s",fname);
547:   }

549:   counts[0] = acnt;
550:   counts[1] = cnt;
551:   MPI_Bcast(counts,2,MPI_INT,0,comm);
552:   acnt = counts[0];
553:   cnt = counts[1];
554:   if (rank) {
555:     PetscMalloc1(2+acnt+cnt,&packed);
556:   }
557:   if (acnt || cnt) {
558:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
559:     astring = packed;
560:     vstring = packed + acnt + 1;
561:   }

563:   if (acnt) {
564:     PetscTokenCreate(astring,' ',&token);
565:     PetscTokenFind(token,&tokens[0]);
566:     while (tokens[0]) {
567:       PetscTokenFind(token,&tokens[1]);
568:       PetscOptionsSetAlias(options,tokens[0],tokens[1]);
569:       PetscTokenFind(token,&tokens[0]);
570:     }
571:     PetscTokenDestroy(&token);
572:   }

574:   if (cnt) {
575:     PetscOptionsInsertString(options,vstring);
576:   }
577:   PetscFree(packed);
578:   return(0);
579: }

581: static PetscErrorCode PetscOptionsInsertArgs(PetscOptions options,int argc,char *args[])
582: {
584:   int            left    = argc - 1;
585:   char           **eargs = args + 1;

588:   while (left) {
589:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
590:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
591:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
592:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
593:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
594:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
595:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
596:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
597:     isp4 = (PetscBool) (isp4 || tisp4);
598:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
599:     isp4 = (PetscBool) (isp4 || tisp4);
600:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
601:     PetscOptionsValidKey(eargs[0],&key);

603:     if (!key) {
604:       eargs++; left--;
605:     } else if (isoptions_file) {
606:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
607:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
608:       PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
609:       eargs += 2; left -= 2;
610:     } else if (isprefixpush) {
611:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
612:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
613:       PetscOptionsPrefixPush(options,eargs[1]);
614:       eargs += 2; left -= 2;
615:     } else if (isprefixpop) {
616:       PetscOptionsPrefixPop(options);
617:       eargs++; left--;

619:       /*
620:        These are "bad" options that MPICH, etc put on the command line
621:        we strip them out here.
622:        */
623:     } else if (tisp4 || isp4rmrank) {
624:       eargs += 1; left -= 1;
625:     } else if (isp4 || isp4yourname) {
626:       eargs += 2; left -= 2;
627:     } else {
628:       PetscBool nextiskey = PETSC_FALSE;
629:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
630:       if (left < 2 || nextiskey) {
631:         PetscOptionsSetValue(options,eargs[0],NULL);
632:         eargs++; left--;
633:       } else {
634:         PetscOptionsSetValue(options,eargs[0],eargs[1]);
635:         eargs += 2; left -= 2;
636:       }
637:     }
638:   }
639:   return(0);
640: }

642: PETSC_STATIC_INLINE PetscErrorCode PetscOptionsStringToBoolIfSet_Private(enum PetscPrecedentOption opt,const char *val[],PetscBool set[],PetscBool *flg)
643: {

647:   if (set[opt]) {
648:     PetscOptionsStringToBool(val[opt],flg);
649:   } else *flg = PETSC_FALSE;
650:   return(0);
651: }

653: /* Process options with absolute precedence */
654: static PetscErrorCode PetscOptionsProcessPrecedentFlags(PetscOptions options,int argc,char *args[],PetscBool *skip_petscrc,PetscBool *skip_petscrc_set)
655: {
656:   const char* const *opt = precedentOptions;
657:   const size_t      n = PO_NUM;
658:   size_t            o;
659:   int               a;
660:   const char        **val;
661:   PetscBool         *set;
662:   PetscErrorCode    ierr;

665:   PetscCalloc2(n,&val,n,&set);

667:   /* Look for options possibly set using PetscOptionsSetValue beforehand */
668:   for (o=0; o<n; o++) {
669:     PetscOptionsFindPair(options,NULL,opt[o],&val[o],&set[o]);
670:   }

672:   /* Loop through all args to collect last occuring value of each option */
673:   for (a=1; a<argc; a++) {
674:     PetscBool valid, eq;

676:     PetscOptionsValidKey(args[a],&valid);
677:     if (!valid) continue;
678:     for (o=0; o<n; o++) {
679:       PetscStrcasecmp(args[a],opt[o],&eq);
680:       if (eq) {
681:         set[o] = PETSC_TRUE;
682:         if (a == argc-1 || !args[a+1] || !args[a+1][0] || args[a+1][0] == '-') val[o] = NULL;
683:         else val[o] = args[a+1];
684:         break;
685:       }
686:     }
687:   }

689:   /* Process flags */
690:   PetscStrcasecmp(val[PO_HELP], "intro", &options->help_intro);
691:   if (options->help_intro) options->help = PETSC_TRUE;
692:   else {PetscOptionsStringToBoolIfSet_Private(PO_HELP,            val,set,&options->help);}
693:   PetscOptionsStringToBoolIfSet_Private(PO_OPTIONS_MONITOR_CANCEL,val,set,&options->monitorCancel);
694:   PetscOptionsStringToBoolIfSet_Private(PO_OPTIONS_MONITOR,       val,set,&options->monitorFromOptions);
695:   PetscOptionsStringToBoolIfSet_Private(PO_SKIP_PETSCRC,          val,set,skip_petscrc);
696:   *skip_petscrc_set = set[PO_SKIP_PETSCRC];

698:   /* Store precedent options in database and mark them as used */
699:   for (o=0; o<n; o++) {
700:     if (set[o]) {
701:       int pos;

703:       PetscOptionsSetValue_Private(options,opt[o],val[o],&pos);
704:       options->used[pos] = PETSC_TRUE;
705:     }
706:   }

708:   PetscFree2(val,set);
709:   options->precedentProcessed = PETSC_TRUE;
710:   return(0);
711: }

713: PETSC_STATIC_INLINE PetscErrorCode PetscOptionsSkipPrecedent(PetscOptions options,const char name[],PetscBool *flg)
714: {
715:   int i;

718:   *flg = PETSC_FALSE;
719:   if (options->precedentProcessed) {
720:     for (i=0; i<PO_NUM; i++) {
721:       if (!PetscOptNameCmp(precedentOptions[i],name)) {
722:         /* check if precedent option has been set already */
723:         PetscOptionsFindPair(options,NULL,name,NULL,flg);
724:         if (*flg) break;
725:       }
726:     }
727:   }
728:   return(0);
729: }

731: /*@C
732:    PetscOptionsInsert - Inserts into the options database from the command line,
733:                         the environmental variable and a file.

735:    Collective on PETSC_COMM_WORLD

737:    Input Parameters:
738: +  options - options database or NULL for the default global database
739: .  argc - count of number of command line arguments
740: .  args - the command line arguments
741: -  file - [optional] PETSc database file, also checks ~/.petscrc, .petscrc and petscrc.
742:           Use NULL to not check for code specific file.
743:           Use -skip_petscrc in the code specific file (or command line) to skip ~/.petscrc, .petscrc and petscrc files.

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

750:    Options Database Keys:
751: .   -options_file <filename> - read options from a file

753:    See PetscInitialize() for options related to option database monitoring.

755:    Level: advanced

757: .seealso: PetscOptionsDestroy(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
758:           PetscInitialize()
759: @*/
760: PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
761: {
763:   PetscMPIInt    rank;
764:   char           filename[PETSC_MAX_PATH_LEN];
765:   PetscBool      hasArgs = (argc && *argc) ? PETSC_TRUE : PETSC_FALSE;
766:   PetscBool      skipPetscrc = PETSC_FALSE, skipPetscrcSet = PETSC_FALSE;


770:   if (hasArgs && !(args && *args)) SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_ARG_NULL, "*argc > 1 but *args not given");
771:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

773:   if (!options) {
774:     PetscOptionsCreateDefault();
775:     options = defaultoptions;
776:   }
777:   if (hasArgs) {
778:     /* process options with absolute precedence */
779:     PetscOptionsProcessPrecedentFlags(options,*argc,*args,&skipPetscrc,&skipPetscrcSet);
780:   }
781:   if (file && file[0]) {
782:     PetscStrreplace(PETSC_COMM_WORLD,file,filename,PETSC_MAX_PATH_LEN);
783:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,filename,PETSC_TRUE);
784:     /* if -skip_petscrc has not been set from command line, check whether it has been set in the file */
785:     if (!skipPetscrcSet) {PetscOptionsGetBool(options,NULL,"-skip_petscrc",&skipPetscrc,NULL);}
786:   }
787:   if (!skipPetscrc) {
788:     PetscGetHomeDirectory(filename,PETSC_MAX_PATH_LEN-16);
789:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
790:     if (filename[0]) { PetscStrcat(filename,"/.petscrc"); }
791:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,filename,PETSC_FALSE);
792:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
793:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
794:   }

796:   /* insert environment options */
797:   {
798:     char   *eoptions = NULL;
799:     size_t len       = 0;
800:     if (!rank) {
801:       eoptions = (char*)getenv("PETSC_OPTIONS");
802:       PetscStrlen(eoptions,&len);
803:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
804:     } else {
805:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
806:       if (len) {
807:         PetscMalloc1(len+1,&eoptions);
808:       }
809:     }
810:     if (len) {
811:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
812:       if (rank) eoptions[len] = 0;
813:       PetscOptionsInsertString(options,eoptions);
814:       if (rank) {PetscFree(eoptions);}
815:     }
816:   }

818: #if defined(PETSC_HAVE_YAML)
819:   {
820:     char   *eoptions = NULL;
821:     size_t len       = 0;
822:     if (!rank) {
823:       eoptions = (char*)getenv("PETSC_OPTIONS_YAML");
824:       PetscStrlen(eoptions,&len);
825:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
826:     } else {
827:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
828:       if (len) {
829:         PetscMalloc1(len+1,&eoptions);
830:       }
831:     }
832:     if (len) {
833:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
834:       if (rank) eoptions[len] = 0;
835:       PetscOptionsInsertStringYAML(options,eoptions);
836:       if (rank) {PetscFree(eoptions);}
837:     }
838:   }
839:   {
840:     char      yaml_file[PETSC_MAX_PATH_LEN];
841:     char      yaml_string[BUFSIZ];
842:     PetscBool yaml_flg;
843:     PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,sizeof(yaml_file),&yaml_flg);
844:     if (yaml_flg) {
845:       PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
846:     }
847:     PetscOptionsGetString(NULL,NULL,"-options_string_yaml",yaml_string,sizeof(yaml_string),&yaml_flg);
848:     if (yaml_flg) {
849:       PetscOptionsInsertStringYAML(NULL,yaml_string);
850:     }
851:   }
852: #endif

854:   /* insert command line options here because they take precedence over arguments in petscrc/environment */
855:   if (hasArgs) {PetscOptionsInsertArgs(options,*argc,*args);}
856:   return(0);
857: }

859: /*@C
860:    PetscOptionsView - Prints the options that have been loaded. This is
861:    useful for debugging purposes.

863:    Logically Collective on PetscViewer

865:    Input Parameter:
866: +  options - options database, use NULL for default global database
867: -  viewer - must be an PETSCVIEWERASCII viewer

869:    Options Database Key:
870: .  -options_view - Activates PetscOptionsView() within PetscFinalize()

872:    Notes:
873:    Only the rank zero process of MPI_Comm used to create view prints the option values. Other processes
874:    may have different values but they are not printed.

876:    Level: advanced

878: .seealso: PetscOptionsAllUsed()
879: @*/
880: PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer)
881: {
883:   PetscInt       i;
884:   PetscBool      isascii;

888:   options = options ? options : defaultoptions;
889:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
890:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
891:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

893:   if (!options->N) {
894:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
895:     return(0);
896:   }

898:   PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
899:   for (i=0; i<options->N; i++) {
900:     if (options->values[i]) {
901:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
902:     } else {
903:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
904:     }
905:   }
906:   PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
907:   return(0);
908: }

910: /*
911:    Called by error handlers to print options used in run
912: */
913: PETSC_EXTERN PetscErrorCode PetscOptionsViewError(void)
914: {
915:   PetscInt     i;
916:   PetscOptions options = defaultoptions;

919:   if (options->N) {
920:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
921:   } else {
922:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
923:   }
924:   for (i=0; i<options->N; i++) {
925:     if (options->values[i]) {
926:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
927:     } else {
928:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
929:     }
930:   }
931:   return(0);
932: }

934: /*@C
935:    PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.

937:    Logically Collective

939:    Input Parameter:
940: +  options - options database, or NULL for the default global database
941: -  prefix - The string to append to the existing prefix

943:    Options Database Keys:
944: +   -prefix_push <some_prefix_> - push the given prefix
945: -   -prefix_pop - pop the last prefix

947:    Notes:
948:    It is common to use this in conjunction with -options_file as in

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

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

954:    The collectivity of this routine is complex; only the MPI processes that call this routine will
955:    have the affect of these options. If some processes that create objects call this routine and others do
956:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
957:    on different ranks.

959: Level: advanced

961: .seealso: PetscOptionsPrefixPop(), PetscOptionsPush(), PetscOptionsPop(), PetscOptionsCreate(), PetscOptionsSetValue()
962: @*/
963: PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
964: {
966:   size_t         n;
967:   PetscInt       start;
968:   char           key[MAXOPTNAME+1];
969:   PetscBool      valid;

973:   options = options ? options : defaultoptions;
974:   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);
975:   key[0] = '-'; /* keys must start with '-' */
976:   PetscStrncpy(key+1,prefix,sizeof(key)-1);
977:   PetscOptionsValidKey(key,&valid);
978:   if (!valid) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Given prefix \"%s\" not valid (the first character must be a letter, do not include leading '-')",prefix);
979:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
980:   PetscStrlen(prefix,&n);
981:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
982:   PetscArraycpy(options->prefix+start,prefix,n+1);
983:   options->prefixstack[options->prefixind++] = start+n;
984:   return(0);
985: }

987: /*@C
988:    PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details

990:    Logically Collective on the MPI_Comm that called PetscOptionsPrefixPush()

992:   Input Parameters:
993: .  options - options database, or NULL for the default global database

995:    Level: advanced

997: .seealso: PetscOptionsPrefixPush(), PetscOptionsPush(), PetscOptionsPop(), PetscOptionsCreate(), PetscOptionsSetValue()
998: @*/
999: PetscErrorCode PetscOptionsPrefixPop(PetscOptions options)
1000: {
1001:   PetscInt offset;

1004:   options = options ? options : defaultoptions;
1005:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
1006:   options->prefixind--;
1007:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
1008:   options->prefix[offset] = 0;
1009:   return(0);
1010: }

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

1015:     Logically Collective

1017:   Input Parameters:
1018: .  options - options database, use NULL for the default global database

1020:    The collectivity of this routine is complex; only the MPI processes that call this routine will
1021:    have the affect of these options. If some processes that create objects call this routine and others do
1022:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
1023:    on different ranks.

1025:    Level: developer

1027: .seealso: PetscOptionsInsert()
1028: @*/
1029: PetscErrorCode PetscOptionsClear(PetscOptions options)
1030: {
1031:   PetscInt i;

1033:   options = options ? options : defaultoptions;
1034:   if (!options) return 0;

1036:   for (i=0; i<options->N; i++) {
1037:     if (options->names[i])  free(options->names[i]);
1038:     if (options->values[i]) free(options->values[i]);
1039:   }
1040:   options->N = 0;

1042:   for (i=0; i<options->Naliases; i++) {
1043:     free(options->aliases1[i]);
1044:     free(options->aliases2[i]);
1045:   }
1046:   options->Naliases = 0;

1048:   /* destroy hash table */
1049:   kh_destroy(HO,options->ht);
1050:   options->ht = NULL;

1052:   options->prefixind = 0;
1053:   options->prefix[0] = 0;
1054:   options->help      = PETSC_FALSE;
1055:   return 0;
1056: }

1058: /*@C
1059:    PetscOptionsSetAlias - Makes a key and alias for another key

1061:    Logically Collective

1063:    Input Parameters:
1064: +  options - options database, or NULL for default global database
1065: .  newname - the alias
1066: -  oldname - the name that alias will refer to

1068:    Level: advanced

1070:    The collectivity of this routine is complex; only the MPI processes that call this routine will
1071:    have the affect of these options. If some processes that create objects call this routine and others do
1072:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
1073:    on different ranks.

1075: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1076:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1077:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1078:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1079:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1080:           PetscOptionsFList(), PetscOptionsEList()
1081: @*/
1082: PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char newname[],const char oldname[])
1083: {
1084:   PetscInt       n;
1085:   size_t         len;
1086:   PetscBool      valid;

1092:   options = options ? options : defaultoptions;
1093:   PetscOptionsValidKey(newname,&valid);
1094:   if (!valid) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid aliased option %s",newname);
1095:   PetscOptionsValidKey(oldname,&valid);
1096:   if (!valid) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid aliasee option %s",oldname);

1098:   n = options->Naliases;
1099:   if (n >= MAXALIASES) 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);

1101:   newname++; oldname++;
1102:   PetscStrlen(newname,&len);
1103:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1104:   PetscStrcpy(options->aliases1[n],newname);
1105:   PetscStrlen(oldname,&len);
1106:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1107:   PetscStrcpy(options->aliases2[n],oldname);
1108:   options->Naliases++;
1109:   return(0);
1110: }

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

1116:    Logically Collective

1118:    Input Parameters:
1119: +  options - options database, use NULL for the default global database
1120: .  name - name of option, this SHOULD have the - prepended
1121: -  value - the option value (not used for all options, so can be NULL)

1123:    Level: intermediate

1125:    Note:
1126:    This function can be called BEFORE PetscInitialize()

1128:    The collectivity of this routine is complex; only the MPI processes that call this routine will
1129:    have the affect of these options. If some processes that create objects call this routine and others do
1130:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
1131:    on different ranks.

1133:    Developers Note: Uses malloc() directly because PETSc may not be initialized yet.

1135: .seealso: PetscOptionsInsert(), PetscOptionsClearValue()
1136: @*/
1137: PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char name[],const char value[])
1138: {
1139:   return PetscOptionsSetValue_Private(options,name,value,NULL);
1140: }

1142: static PetscErrorCode PetscOptionsSetValue_Private(PetscOptions options,const char name[],const char value[],int *pos)
1143: {
1144:   size_t         len;
1145:   int            N,n,i;
1146:   char           **names;
1147:   char           fullname[MAXOPTNAME] = "";
1148:   PetscBool      flg;

1151:   if (!options) {
1152:     PetscOptionsCreateDefault();if (ierr) return ierr;
1153:     options = defaultoptions;
1154:   }

1156:   if (name[0] != '-') return PETSC_ERR_ARG_OUTOFRANGE;

1158:   PetscOptionsSkipPrecedent(options,name,&flg);
1159:   if (flg) return 0;

1161:   name++; /* skip starting dash */

1163:   if (options->prefixind > 0) {
1164:     strncpy(fullname,options->prefix,sizeof(fullname));
1165:     fullname[sizeof(fullname)-1] = 0;
1166:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1167:     fullname[sizeof(fullname)-1] = 0;
1168:     name = fullname;
1169:   }

1171:   /* check against aliases */
1172:   N = options->Naliases;
1173:   for (i=0; i<N; i++) {
1174:     int result = PetscOptNameCmp(options->aliases1[i],name);
1175:     if (!result) { name = options->aliases2[i]; break; }
1176:   }

1178:   /* slow search */
1179:   N = n = options->N;
1180:   names = options->names;
1181:   for (i=0; i<N; i++) {
1182:     int result = PetscOptNameCmp(names[i],name);
1183:     if (!result) {
1184:       n = i; goto setvalue;
1185:     } else if (result > 0) {
1186:       n = i; break;
1187:     }
1188:   }
1189:   if (N >= MAXOPTIONS) return PETSC_ERR_MEM;
1190:   /* shift remaining values up 1 */
1191:   for (i=N; i>n; i--) {
1192:     options->names[i]  = options->names[i-1];
1193:     options->values[i] = options->values[i-1];
1194:     options->used[i]   = options->used[i-1];
1195:   }
1196:   options->names[n]  = NULL;
1197:   options->values[n] = NULL;
1198:   options->used[n]   = PETSC_FALSE;
1199:   options->N++;

1201:   /* destroy hash table */
1202:   kh_destroy(HO,options->ht);
1203:   options->ht = NULL;

1205:   /* set new name */
1206:   len = strlen(name);
1207:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
1208:   if (!options->names[n]) return PETSC_ERR_MEM;
1209:   strcpy(options->names[n],name);

1211: setvalue:
1212:   /* set new value */
1213:   if (options->values[n]) free(options->values[n]);
1214:   len = value ? strlen(value) : 0;
1215:   if (len) {
1216:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
1217:     if (!options->values[n]) return PETSC_ERR_MEM;
1218:     strcpy(options->values[n],value);
1219:   } else {
1220:     options->values[n] = NULL;
1221:   }

1223:   if (PetscErrorHandlingInitialized) {
1224:     PetscOptionsMonitor(options,name,value);
1225:   }
1226:   if (pos) *pos = n;
1227:   return 0;
1228: }

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

1234:    Logically Collective

1236:    Input Parameter:
1237: +  options - options database, use NULL for the default global database
1238: -  name - name of option, this SHOULD have the - prepended

1240:    Level: intermediate

1242:    The collectivity of this routine is complex; only the MPI processes that call this routine will
1243:    have the affect of these options. If some processes that create objects call this routine and others do
1244:    not the code may fail in complicated ways because the same parallel solvers may incorrectly use different options
1245:    on different ranks.

1247: .seealso: PetscOptionsInsert()
1248: @*/
1249: PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char name[])
1250: {
1251:   int            N,n,i;
1252:   char           **names;

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

1259:   if (!PetscOptNameCmp(name,"-help")) options->help = PETSC_FALSE;

1261:   name++; /* skip starting dash */

1263:   /* slow search */
1264:   N = n = options->N;
1265:   names = options->names;
1266:   for (i=0; i<N; i++) {
1267:     int result = PetscOptNameCmp(names[i],name);
1268:     if (!result) {
1269:       n = i; break;
1270:     } else if (result > 0) {
1271:       n = N; break;
1272:     }
1273:   }
1274:   if (n == N) return(0); /* it was not present */

1276:   /* remove name and value */
1277:   if (options->names[n])  free(options->names[n]);
1278:   if (options->values[n]) free(options->values[n]);
1279:   /* shift remaining values down 1 */
1280:   for (i=n; i<N-1; i++) {
1281:     options->names[i]  = options->names[i+1];
1282:     options->values[i] = options->values[i+1];
1283:     options->used[i]   = options->used[i+1];
1284:   }
1285:   options->N--;

1287:   /* destroy hash table */
1288:   kh_destroy(HO,options->ht);
1289:   options->ht = NULL;

1291:   PetscOptionsMonitor(options,name,NULL);
1292:   return(0);
1293: }

1295: /*@C
1296:    PetscOptionsFindPair - Gets an option name-value pair from the options database.

1298:    Not Collective

1300:    Input Parameters:
1301: +  options - options database, use NULL for the default global database
1302: .  pre - the string to prepend to the name or NULL, this SHOULD NOT have the "-" prepended
1303: -  name - name of option, this SHOULD have the "-" prepended

1305:    Output Parameters:
1306: +  value - the option value (optional, not used for all options)
1307: -  set - whether the option is set (optional)

1309:    Notes:
1310:    Each process may find different values or no value depending on how options were inserted into the database

1312:    Level: developer

1314: .seealso: PetscOptionsSetValue(), PetscOptionsClearValue()
1315: @*/
1316: PetscErrorCode PetscOptionsFindPair(PetscOptions options,const char pre[],const char name[],const char *value[],PetscBool *set)
1317: {
1318:   char           buf[MAXOPTNAME];
1319:   PetscBool      usehashtable = PETSC_TRUE;
1320:   PetscBool      matchnumbers = PETSC_TRUE;

1324:   options = options ? options : defaultoptions;
1325:   if (pre && PetscUnlikely(pre[0] == '-')) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix cannot begin with '-': Instead %s",pre);
1326:   if (PetscUnlikely(name[0] != '-')) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with '-': Instead %s",name);

1328:   name++; /* skip starting dash */

1330:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1331:   if (pre && pre[0]) {
1332:     char *ptr = buf;
1333:     if (name[0] == '-') { *ptr++ = '-';  name++; }
1334:     PetscStrncpy(ptr,pre,buf+sizeof(buf)-ptr);
1335:     PetscStrlcat(buf,name,sizeof(buf));
1336:     name = buf;
1337:   }

1339:   if (PetscDefined(USE_DEBUG)) {
1340:     PetscBool valid;
1341:     char      key[MAXOPTNAME+1] = "-";
1342:     PetscStrncpy(key+1,name,sizeof(key)-1);
1343:     PetscOptionsValidKey(key,&valid);
1344:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1345:   }

1347:   if (!options->ht && usehashtable) {
1348:     int i,ret;
1349:     khiter_t it;
1350:     khash_t(HO) *ht;
1351:     ht = kh_init(HO);
1352:     if (PetscUnlikely(!ht)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1353:     ret = kh_resize(HO,ht,options->N*2); /* twice the required size to reduce risk of collisions */
1354:     if (PetscUnlikely(ret)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1355:     for (i=0; i<options->N; i++) {
1356:       it = kh_put(HO,ht,options->names[i],&ret);
1357:       if (PetscUnlikely(ret != 1)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1358:       kh_val(ht,it) = i;
1359:     }
1360:     options->ht = ht;
1361:   }

1363:   if (usehashtable)
1364:   { /* fast search */
1365:     khash_t(HO) *ht = options->ht;
1366:     khiter_t it = kh_get(HO,ht,name);
1367:     if (it != kh_end(ht)) {
1368:       int i = kh_val(ht,it);
1369:       options->used[i]  = PETSC_TRUE;
1370:       if (value) *value = options->values[i];
1371:       if (set)   *set   = PETSC_TRUE;
1372:       return(0);
1373:     }
1374:   } else
1375:   { /* slow search */
1376:     int i, N = options->N;
1377:     for (i=0; i<N; i++) {
1378:       int result = PetscOptNameCmp(options->names[i],name);
1379:       if (!result) {
1380:         options->used[i]  = PETSC_TRUE;
1381:         if (value) *value = options->values[i];
1382:         if (set)   *set   = PETSC_TRUE;
1383:         return(0);
1384:       } else if (result > 0) {
1385:         break;
1386:       }
1387:     }
1388:   }

1390:   /*
1391:    The following block slows down all lookups in the most frequent path (most lookups are unsuccessful).
1392:    Maybe this special lookup mode should be enabled on request with a push/pop API.
1393:    The feature of matching _%d_ used sparingly in the codebase.
1394:    */
1395:   if (matchnumbers) {
1396:     int i,j,cnt = 0,locs[16],loce[16];
1397:     /* determine the location and number of all _%d_ in the key */
1398:     for (i=0; name[i]; i++) {
1399:       if (name[i] == '_') {
1400:         for (j=i+1; name[j]; j++) {
1401:           if (name[j] >= '0' && name[j] <= '9') continue;
1402:           if (name[j] == '_' && j > i+1) { /* found a number */
1403:             locs[cnt]   = i+1;
1404:             loce[cnt++] = j+1;
1405:           }
1406:           i = j-1;
1407:           break;
1408:         }
1409:       }
1410:     }
1411:     for (i=0; i<cnt; i++) {
1412:       PetscBool found;
1413:       char      opt[MAXOPTNAME+1] = "-", tmp[MAXOPTNAME];
1414:       PetscStrncpy(tmp,name,PetscMin((size_t)(locs[i]+1),sizeof(tmp)));
1415:       PetscStrlcat(opt,tmp,sizeof(opt));
1416:       PetscStrlcat(opt,name+loce[i],sizeof(opt));
1417:       PetscOptionsFindPair(options,NULL,opt,value,&found);
1418:       if (found) {if (set) *set = PETSC_TRUE; return(0);}
1419:     }
1420:   }

1422:   if (set) *set = PETSC_FALSE;
1423:   return(0);
1424: }

1426: /* Check whether any option begins with pre+name */
1427: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[],const char *value[],PetscBool *set)
1428: {
1429:   char           buf[MAXOPTNAME];
1430:   int            numCnt = 0, locs[16],loce[16];

1434:   options = options ? options : defaultoptions;
1435:   if (pre && pre[0] == '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix cannot begin with '-': Instead %s",pre);
1436:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with '-': Instead %s",name);

1438:   name++; /* skip starting dash */

1440:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1441:   if (pre && pre[0]) {
1442:     char *ptr = buf;
1443:     if (name[0] == '-') { *ptr++ = '-';  name++; }
1444:     PetscStrncpy(ptr,pre,sizeof(buf)+(size_t)(ptr-buf));
1445:     PetscStrlcat(buf,name,sizeof(buf));
1446:     name = buf;
1447:   }

1449:   if (PetscDefined(USE_DEBUG)) {
1450:     PetscBool valid;
1451:     char      key[MAXOPTNAME+1] = "-";
1452:     PetscStrncpy(key+1,name,sizeof(key)-1);
1453:     PetscOptionsValidKey(key,&valid);
1454:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1455:   }

1457:   /* determine the location and number of all _%d_ in the key */
1458:   {
1459:     int i,j;
1460:     for (i=0; name[i]; i++) {
1461:       if (name[i] == '_') {
1462:         for (j=i+1; name[j]; j++) {
1463:           if (name[j] >= '0' && name[j] <= '9') continue;
1464:           if (name[j] == '_' && j > i+1) { /* found a number */
1465:             locs[numCnt]   = i+1;
1466:             loce[numCnt++] = j+1;
1467:           }
1468:           i = j-1;
1469:           break;
1470:         }
1471:       }
1472:     }
1473:   }

1475:   { /* slow search */
1476:     int       c, i;
1477:     size_t    len;
1478:     PetscBool match;

1480:     for (c = -1; c < numCnt; ++c) {
1481:       char opt[MAXOPTNAME+1] = "", tmp[MAXOPTNAME];

1483:       if (c < 0) {
1484:         PetscStrcpy(opt,name);
1485:       } else {
1486:         PetscStrncpy(tmp,name,PetscMin((size_t)(locs[c]+1),sizeof(tmp)));
1487:         PetscStrlcat(opt,tmp,sizeof(opt));
1488:         PetscStrlcat(opt,name+loce[c],sizeof(opt));
1489:       }
1490:       PetscStrlen(opt,&len);
1491:       for (i=0; i<options->N; i++) {
1492:         PetscStrncmp(options->names[i],opt,len,&match);
1493:         if (match) {
1494:           options->used[i]  = PETSC_TRUE;
1495:           if (value) *value = options->values[i];
1496:           if (set)   *set   = PETSC_TRUE;
1497:           return(0);
1498:         }
1499:       }
1500:     }
1501:   }

1503:   if (set) *set = PETSC_FALSE;
1504:   return(0);
1505: }

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

1510:    Not Collective

1512:    Input Parameters:
1513: +  options - options database, use NULL for default global database
1514: .  pre - the option prefix (may be NULL)
1515: .  name - the option name one is seeking
1516: -  mess - error message (may be NULL)

1518:    Level: advanced

1520: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1521:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1522:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1523:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1524:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1525:           PetscOptionsFList(), PetscOptionsEList()
1526: @*/
1527: PetscErrorCode PetscOptionsReject(PetscOptions options,const char pre[],const char name[],const char mess[])
1528: {
1530:   PetscBool      flag = PETSC_FALSE;

1533:   PetscOptionsHasName(options,pre,name,&flag);
1534:   if (flag) {
1535:     if (mess && mess[0]) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: -%s%s with %s",pre?pre:"",name+1,mess);
1536:     else SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: -%s%s",pre?pre:"",name+1);
1537:   }
1538:   return(0);
1539: }

1541: /*@C
1542:    PetscOptionsHasHelp - Determines whether the "-help" option is in the database.

1544:    Not Collective

1546:    Input Parameters:
1547: .  options - options database, use NULL for default global database

1549:    Output Parameters:
1550: .  set - PETSC_TRUE if found else PETSC_FALSE.

1552:    Level: advanced

1554: .seealso: PetscOptionsHasName()
1555: @*/
1556: PetscErrorCode PetscOptionsHasHelp(PetscOptions options,PetscBool *set)
1557: {
1560:   options = options ? options : defaultoptions;
1561:   *set = options->help;
1562:   return(0);
1563: }

1565: PetscErrorCode PetscOptionsHasHelpIntro_Internal(PetscOptions options,PetscBool *set)
1566: {
1569:   options = options ? options : defaultoptions;
1570:   *set = options->help_intro;
1571:   return(0);
1572: }

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

1578:    Not Collective

1580:    Input Parameters:
1581: +  options - options database, use NULL for default global database
1582: .  pre - string to prepend to the name or NULL
1583: -  name - the option one is seeking

1585:    Output Parameters:
1586: .  set - PETSC_TRUE if found else PETSC_FALSE.

1588:    Level: beginner

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

1593: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1594:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1595:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1596:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1597:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1598:           PetscOptionsFList(), PetscOptionsEList()
1599: @*/
1600: PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set)
1601: {
1602:   const char     *value;
1604:   PetscBool      flag;

1607:   PetscOptionsFindPair(options,pre,name,&value,&flag);
1608:   if (set) *set = flag;
1609:   return(0);
1610: }

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

1615:    Not Collective

1617:    Input Parameter:
1618: .  options - the options database, use NULL for the default global database

1620:    Output Parameter:
1621: .  copts - pointer where string pointer is stored

1623:    Notes:
1624:     The array and each entry in the array should be freed with PetscFree()
1625:     Each process may have different values depending on how the options were inserted into the database

1627:    Level: advanced

1629: .seealso: PetscOptionsAllUsed(), PetscOptionsView(), PetscOptionsPush(), PetscOptionsPop()
1630: @*/
1631: PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[])
1632: {
1634:   PetscInt       i;
1635:   size_t         len = 1,lent = 0;
1636:   char           *coptions = NULL;

1640:   options = options ? options : defaultoptions;
1641:   /* count the length of the required string */
1642:   for (i=0; i<options->N; i++) {
1643:     PetscStrlen(options->names[i],&lent);
1644:     len += 2 + lent;
1645:     if (options->values[i]) {
1646:       PetscStrlen(options->values[i],&lent);
1647:       len += 1 + lent;
1648:     }
1649:   }
1650:   PetscMalloc1(len,&coptions);
1651:   coptions[0] = 0;
1652:   for (i=0; i<options->N; i++) {
1653:     PetscStrcat(coptions,"-");
1654:     PetscStrcat(coptions,options->names[i]);
1655:     PetscStrcat(coptions," ");
1656:     if (options->values[i]) {
1657:       PetscStrcat(coptions,options->values[i]);
1658:       PetscStrcat(coptions," ");
1659:     }
1660:   }
1661:   *copts = coptions;
1662:   return(0);
1663: }

1665: /*@C
1666:    PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database

1668:    Not Collective

1670:    Input Parameter:
1671: +  options - options database, use NULL for default global database
1672: -  name - string name of option

1674:    Output Parameter:
1675: .  used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database

1677:    Level: advanced

1679:    Notes:
1680:    The value returned may be different on each process and depends on which options have been processed
1681:    on the given process

1683: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
1684: @*/
1685: PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *name,PetscBool *used)
1686: {
1687:   PetscInt       i;

1693:   options = options ? options : defaultoptions;
1694:   *used = PETSC_FALSE;
1695:   for (i=0; i<options->N; i++) {
1696:     PetscStrcmp(options->names[i],name,used);
1697:     if (*used) {
1698:       *used = options->used[i];
1699:       break;
1700:     }
1701:   }
1702:   return(0);
1703: }

1705: /*@
1706:    PetscOptionsAllUsed - Returns a count of the number of options in the
1707:    database that have never been selected.

1709:    Not Collective

1711:    Input Parameter:
1712: .  options - options database, use NULL for default global database

1714:    Output Parameter:
1715: .  N - count of options not used

1717:    Level: advanced

1719:    Notes:
1720:    The value returned may be different on each process and depends on which options have been processed
1721:    on the given process

1723: .seealso: PetscOptionsView()
1724: @*/
1725: PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
1726: {
1727:   PetscInt     i,n = 0;

1731:   options = options ? options : defaultoptions;
1732:   for (i=0; i<options->N; i++) {
1733:     if (!options->used[i]) n++;
1734:   }
1735:   *N = n;
1736:   return(0);
1737: }

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

1742:    Not Collective

1744:    Input Parameter:
1745: .  options - options database; use NULL for default global database

1747:    Options Database Key:
1748: .  -options_left - activates PetscOptionsAllUsed() within PetscFinalize()

1750:    Notes:
1751:       This is rarely used directly, it is called by PetscFinalize() in debug more or if -options_left
1752:       is passed otherwise to help users determine possible mistakes in their usage of options. This
1753:       only prints values on process zero of PETSC_COMM_WORLD. Other processes depending the objects
1754:       used may have different options that are left unused.

1756:    Level: advanced

1758: .seealso: PetscOptionsAllUsed()
1759: @*/
1760: PetscErrorCode PetscOptionsLeft(PetscOptions options)
1761: {
1763:   PetscInt       i;
1764:   PetscInt       cnt = 0;
1765:   PetscOptions   toptions;

1768:   toptions = options ? options : defaultoptions;
1769:   for (i=0; i<toptions->N; i++) {
1770:     if (!toptions->used[i]) {
1771:       if (toptions->values[i]) {
1772:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",toptions->names[i],toptions->values[i]);
1773:       } else {
1774:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",toptions->names[i]);
1775:       }
1776:     }
1777:   }
1778:   if (!options) {
1779:     toptions = defaultoptions;
1780:     while (toptions->previous) {
1781:       cnt++;
1782:       toptions = toptions->previous;
1783:     }
1784:     if (cnt) {
1785:       PetscPrintf(PETSC_COMM_WORLD,"Option left: You may have forgotten some calls to PetscOptionsPop(),\n             PetscOptionsPop() has been called %D less times than PetscOptionsPush()\n",cnt);
1786:     }
1787:   }
1788:   return(0);
1789: }

1791: /*@C
1792:    PetscOptionsLeftGet - Returns all options that were set and never used.

1794:    Not Collective

1796:    Input Parameter:
1797: .  options - options database, use NULL for default global database

1799:    Output Parameter:
1800: +  N - count of options not used
1801: .  names - names of options not used
1802: -  values - values of options not used

1804:    Level: advanced

1806:    Notes:
1807:    Users should call PetscOptionsLeftRestore() to free the memory allocated in this routine
1808:    Notes: The value returned may be different on each process and depends on which options have been processed
1809:    on the given process

1811: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft()
1812: @*/
1813: PetscErrorCode PetscOptionsLeftGet(PetscOptions options,PetscInt *N,char **names[],char **values[])
1814: {
1816:   PetscInt       i,n;

1822:   options = options ? options : defaultoptions;

1824:   /* The number of unused PETSc options */
1825:   n = 0;
1826:   for (i=0; i<options->N; i++) {
1827:     if (!options->used[i]) n++;
1828:   }
1829:   if (N) { *N = n; }
1830:   if (names)  { PetscMalloc1(n,names); }
1831:   if (values) { PetscMalloc1(n,values); }

1833:   n = 0;
1834:   if (names || values) {
1835:     for (i=0; i<options->N; i++) {
1836:       if (!options->used[i]) {
1837:         if (names)  (*names)[n]  = options->names[i];
1838:         if (values) (*values)[n] = options->values[i];
1839:         n++;
1840:       }
1841:     }
1842:   }
1843:   return(0);
1844: }

1846: /*@C
1847:    PetscOptionsLeftRestore - Free memory for the unused PETSc options obtained using PetscOptionsLeftGet.

1849:    Not Collective

1851:    Input Parameter:
1852: +  options - options database, use NULL for default global database
1853: .  names - names of options not used
1854: -  values - values of options not used

1856:    Level: advanced

1858: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft(), PetscOptionsLeftGet()
1859: @*/
1860: PetscErrorCode PetscOptionsLeftRestore(PetscOptions options,PetscInt *N,char **names[],char **values[])
1861: {

1868:   if (N) { *N = 0; }
1869:   if (names)  { PetscFree(*names); }
1870:   if (values) { PetscFree(*values); }
1871:   return(0);
1872: }

1874: /*@C
1875:    PetscOptionsMonitorDefault - Print all options set value events using the supplied PetscViewer.

1877:    Logically Collective on ctx

1879:    Input Parameters:
1880: +  name  - option name string
1881: .  value - option value string
1882: -  ctx - an ASCII viewer or NULL

1884:    Level: intermediate

1886:    Notes:
1887:      If ctx=NULL, PetscPrintf() is used.
1888:      The first MPI rank in the PetscViewer viewer actually prints the values, other
1889:      processes may have different values set

1891: .seealso: PetscOptionsMonitorSet()
1892: @*/
1893: PetscErrorCode PetscOptionsMonitorDefault(const char name[],const char value[],void *ctx)
1894: {

1898:   if (ctx) {
1899:     PetscViewer viewer = (PetscViewer)ctx;
1900:     if (!value) {
1901:       PetscViewerASCIIPrintf(viewer,"Removing option: %s\n",name,value);
1902:     } else if (!value[0]) {
1903:       PetscViewerASCIIPrintf(viewer,"Setting option: %s (no value)\n",name);
1904:     } else {
1905:       PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1906:     }
1907:   } else {
1908:     MPI_Comm comm = PETSC_COMM_WORLD;
1909:     if (!value) {
1910:       PetscPrintf(comm,"Removing option: %s\n",name,value);
1911:     } else if (!value[0]) {
1912:       PetscPrintf(comm,"Setting option: %s (no value)\n",name);
1913:     } else {
1914:       PetscPrintf(comm,"Setting option: %s = %s\n",name,value);
1915:     }
1916:   }
1917:   return(0);
1918: }

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

1924:    Not Collective

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

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

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

1940:    Options Database Keys:
1941:    See PetscInitialize() for options related to option database monitoring.

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

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

1952:    Level: intermediate

1954: .seealso: PetscOptionsMonitorDefault(), PetscInitialize()
1955: @*/
1956: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
1957: {
1958:   PetscOptions options = defaultoptions;

1961:   if (options->monitorCancel) return(0);
1962:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1963:   options->monitor[options->numbermonitors]          = monitor;
1964:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
1965:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1966:   return(0);
1967: }

1969: /*
1970:    PetscOptionsStringToBool - Converts string to PetscBool, handles cases like "yes", "no", "true", "false", "0", "1", "off", "on".
1971:      Empty string is considered as true.
1972: */
1973: PetscErrorCode PetscOptionsStringToBool(const char value[],PetscBool *a)
1974: {
1975:   PetscBool      istrue,isfalse;
1976:   size_t         len;

1980:   /* PetscStrlen() returns 0 for NULL or "" */
1981:   PetscStrlen(value,&len);
1982:   if (!len)  {*a = PETSC_TRUE; return(0);}
1983:   PetscStrcasecmp(value,"TRUE",&istrue);
1984:   if (istrue) {*a = PETSC_TRUE; return(0);}
1985:   PetscStrcasecmp(value,"YES",&istrue);
1986:   if (istrue) {*a = PETSC_TRUE; return(0);}
1987:   PetscStrcasecmp(value,"1",&istrue);
1988:   if (istrue) {*a = PETSC_TRUE; return(0);}
1989:   PetscStrcasecmp(value,"on",&istrue);
1990:   if (istrue) {*a = PETSC_TRUE; return(0);}
1991:   PetscStrcasecmp(value,"FALSE",&isfalse);
1992:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1993:   PetscStrcasecmp(value,"NO",&isfalse);
1994:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1995:   PetscStrcasecmp(value,"0",&isfalse);
1996:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1997:   PetscStrcasecmp(value,"off",&isfalse);
1998:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1999:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
2000: }

2002: /*
2003:    PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
2004: */
2005: PetscErrorCode PetscOptionsStringToInt(const char name[],PetscInt *a)
2006: {
2008:   size_t         len;
2009:   PetscBool      decide,tdefault,mouse;

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

2015:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
2016:   if (!tdefault) {
2017:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
2018:   }
2019:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
2020:   if (!decide) {
2021:     PetscStrcasecmp(name,"DECIDE",&decide);
2022:   }
2023:   PetscStrcasecmp(name,"mouse",&mouse);

2025:   if (tdefault)    *a = PETSC_DEFAULT;
2026:   else if (decide) *a = PETSC_DECIDE;
2027:   else if (mouse)  *a = -1;
2028:   else {
2029:     char *endptr;
2030:     long strtolval;

2032:     strtolval = strtol(name,&endptr,10);
2033:     if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);

2035: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
2036:     (void) strtolval;
2037:     *a = atoll(name);
2038: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
2039:     (void) strtolval;
2040:     *a = _atoi64(name);
2041: #else
2042:     *a = (PetscInt)strtolval;
2043: #endif
2044:   }
2045:   return(0);
2046: }

2048: #if defined(PETSC_USE_REAL___FLOAT128)
2049: #include <quadmath.h>
2050: #endif

2052: static PetscErrorCode PetscStrtod(const char name[],PetscReal *a,char **endptr)
2053: {
2055: #if defined(PETSC_USE_REAL___FLOAT128)
2056:   *a = strtoflt128(name,endptr);
2057: #else
2058:   *a = (PetscReal)strtod(name,endptr);
2059: #endif
2060:   return(0);
2061: }

2063: static PetscErrorCode PetscStrtoz(const char name[],PetscScalar *a,char **endptr,PetscBool *isImaginary)
2064: {
2065:   PetscBool      hasi = PETSC_FALSE;
2066:   char           *ptr;
2067:   PetscReal      strtoval;

2071:   PetscStrtod(name,&strtoval,&ptr);
2072:   if (ptr == name) {
2073:     strtoval = 1.;
2074:     hasi = PETSC_TRUE;
2075:     if (name[0] == 'i') {
2076:       ptr++;
2077:     } else if (name[0] == '+' && name[1] == 'i') {
2078:       ptr += 2;
2079:     } else if (name[0] == '-' && name[1] == 'i') {
2080:       strtoval = -1.;
2081:       ptr += 2;
2082:     }
2083:   } else if (*ptr == 'i') {
2084:     hasi = PETSC_TRUE;
2085:     ptr++;
2086:   }
2087:   *endptr = ptr;
2088:   *isImaginary = hasi;
2089:   if (hasi) {
2090: #if !defined(PETSC_USE_COMPLEX)
2091:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s contains imaginary but complex not supported ",name);
2092: #else
2093:     *a = PetscCMPLX(0.,strtoval);
2094: #endif
2095:   } else {
2096:     *a = strtoval;
2097:   }
2098:   return(0);
2099: }

2101: /*
2102:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
2103: */
2104: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
2105: {
2106:   size_t         len;
2107:   PetscBool      match;
2108:   char           *endptr;

2112:   PetscStrlen(name,&len);
2113:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"String of length zero has no numerical value");

2115:   PetscStrcasecmp(name,"PETSC_DEFAULT",&match);
2116:   if (!match) {
2117:     PetscStrcasecmp(name,"DEFAULT",&match);
2118:   }
2119:   if (match) {*a = PETSC_DEFAULT; return(0);}

2121:   PetscStrcasecmp(name,"PETSC_DECIDE",&match);
2122:   if (!match) {
2123:     PetscStrcasecmp(name,"DECIDE",&match);
2124:   }
2125:   if (match) {*a = PETSC_DECIDE; return(0);}

2127:   PetscStrtod(name,a,&endptr);
2128:   if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value",name);
2129:   return(0);
2130: }

2132: PetscErrorCode PetscOptionsStringToScalar(const char name[],PetscScalar *a)
2133: {
2134:   PetscBool      imag1;
2135:   size_t         len;
2136:   PetscScalar    val = 0.;
2137:   char           *ptr = NULL;

2141:   PetscStrlen(name,&len);
2142:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
2143:   PetscStrtoz(name,&val,&ptr,&imag1);
2144: #if defined(PETSC_USE_COMPLEX)
2145:   if ((size_t) (ptr - name) < len) {
2146:     PetscBool   imag2;
2147:     PetscScalar val2;

2149:     PetscStrtoz(ptr,&val2,&ptr,&imag2);
2150:     if (imag1 || !imag2) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s: must specify imaginary component second",name);
2151:     val = PetscCMPLX(PetscRealPart(val),PetscImaginaryPart(val2));
2152:   }
2153: #endif
2154:   if ((size_t) (ptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
2155:   *a = val;
2156:   return(0);
2157: }

2159: /*@C
2160:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
2161:             option in the database.

2163:    Not Collective

2165:    Input Parameters:
2166: +  options - options database, use NULL for default global database
2167: .  pre - the string to prepend to the name or NULL
2168: -  name - the option one is seeking

2170:    Output Parameter:
2171: +  ivalue - the logical value to return
2172: -  set - PETSC_TRUE  if found, else PETSC_FALSE

2174:    Level: beginner

2176:    Notes:
2177:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
2178:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

2180:       If the option is given, but no value is provided, then ivalue and set are both given the value PETSC_TRUE. That is -requested_bool
2181:      is equivalent to -requested_bool true

2183:        If the user does not supply the option at all ivalue is NOT changed. Thus
2184:      you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

2186: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
2187:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
2188:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2189:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2190:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2191:           PetscOptionsFList(), PetscOptionsEList()
2192: @*/
2193: PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
2194: {
2195:   const char     *value;
2196:   PetscBool      flag;

2202:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2203:   if (flag) {
2204:     if (set) *set = PETSC_TRUE;
2205:     PetscOptionsStringToBool(value, &flag);
2206:     if (ivalue) *ivalue = flag;
2207:   } else {
2208:     if (set) *set = PETSC_FALSE;
2209:   }
2210:   return(0);
2211: }

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

2216:    Not Collective

2218:    Input Parameters:
2219: +  options - options database, use NULL for default global database
2220: .  pre - the string to prepend to the name or NULL
2221: .  opt - option name
2222: .  list - the possible choices (one of these must be selected, anything else is invalid)
2223: -  ntext - number of choices

2225:    Output Parameter:
2226: +  value - the index of the value to return (defaults to zero if the option name is given but no choice is listed)
2227: -  set - PETSC_TRUE if found, else PETSC_FALSE

2229:    Level: intermediate

2231:    Notes:
2232:     If the user does not supply the option value is NOT changed. Thus
2233:      you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

2235:    See PetscOptionsFList() for when the choices are given in a PetscFunctionList()

2237: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2238:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2239:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2240:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2241:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2242:           PetscOptionsFList(), PetscOptionsEList()
2243: @*/
2244: PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set)
2245: {
2247:   size_t         alen,len = 0, tlen = 0;
2248:   char           *svalue;
2249:   PetscBool      aset,flg = PETSC_FALSE;
2250:   PetscInt       i;

2254:   for (i=0; i<ntext; i++) {
2255:     PetscStrlen(list[i],&alen);
2256:     if (alen > len) len = alen;
2257:     tlen += len + 1;
2258:   }
2259:   len += 5; /* a little extra space for user mistypes */
2260:   PetscMalloc1(len,&svalue);
2261:   PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
2262:   if (aset) {
2263:     PetscEListFind(ntext,list,svalue,value,&flg);
2264:     if (!flg) {
2265:       char *avail,*pavl;

2267:       PetscMalloc1(tlen,&avail);
2268:       pavl = avail;
2269:       for (i=0; i<ntext; i++) {
2270:         PetscStrlen(list[i],&alen);
2271:         PetscStrcpy(pavl,list[i]);
2272:         pavl += alen;
2273:         PetscStrcpy(pavl," ");
2274:         pavl += 1;
2275:       }
2276:       PetscStrtolower(avail);
2277:       SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s. Available options: %s",svalue,pre ? pre : "",opt+1,avail);
2278:     }
2279:     if (set) *set = PETSC_TRUE;
2280:   } else if (set) *set = PETSC_FALSE;
2281:   PetscFree(svalue);
2282:   return(0);
2283: }

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

2288:    Not Collective

2290:    Input Parameters:
2291: +  options - options database, use NULL for default global database
2292: .  pre - option prefix or NULL
2293: .  opt - option name
2294: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2295: -  defaultv - the default (current) value

2297:    Output Parameter:
2298: +  value - the  value to return
2299: -  set - PETSC_TRUE if found, else PETSC_FALSE

2301:    Level: beginner

2303:    Notes:
2304:     If the user does not supply the option value is NOT changed. Thus
2305:      you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

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

2309: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2310:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2311:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
2312:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2313:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2314:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2315:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2316: @*/
2317: PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set)
2318: {
2320:   PetscInt       ntext = 0,tval;
2321:   PetscBool      fset;

2325:   while (list[ntext++]) {
2326:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
2327:   }
2328:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
2329:   ntext -= 3;
2330:   PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
2331:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
2332:   if (fset) *value = (PetscEnum)tval;
2333:   if (set) *set = fset;
2334:   return(0);
2335: }

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

2340:    Not Collective

2342:    Input Parameters:
2343: +  options - options database, use NULL for default global database
2344: .  pre - the string to prepend to the name or NULL
2345: -  name - the option one is seeking

2347:    Output Parameter:
2348: +  ivalue - the integer value to return
2349: -  set - PETSC_TRUE if found, else PETSC_FALSE

2351:    Level: beginner

2353:    Notes:
2354:    If the user does not supply the option ivalue is NOT changed. Thus
2355:    you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

2357: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
2358:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2359:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
2360:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2361:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2362:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2363:           PetscOptionsFList(), PetscOptionsEList()
2364: @*/
2365: PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
2366: {
2367:   const char     *value;
2369:   PetscBool      flag;

2374:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2375:   if (flag) {
2376:     if (!value) {
2377:       if (set) *set = PETSC_FALSE;
2378:     } else {
2379:       if (set) *set = PETSC_TRUE;
2380:       PetscOptionsStringToInt(value,ivalue);
2381:     }
2382:   } else {
2383:     if (set) *set = PETSC_FALSE;
2384:   }
2385:   return(0);
2386: }

2388: /*@C
2389:    PetscOptionsGetReal - Gets the double precision value for a particular
2390:    option in the database.

2392:    Not Collective

2394:    Input Parameters:
2395: +  options - options database, use NULL for default global database
2396: .  pre - string to prepend to each name or NULL
2397: -  name - the option one is seeking

2399:    Output Parameter:
2400: +  dvalue - the double value to return
2401: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

2403:    Notes:
2404:     If the user does not supply the option dvalue is NOT changed. Thus
2405:      you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

2407:    Level: beginner

2409: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2410:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
2411:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2412:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2413:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2414:           PetscOptionsFList(), PetscOptionsEList()
2415: @*/
2416: PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
2417: {
2418:   const char     *value;
2419:   PetscBool      flag;

2425:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2426:   if (flag) {
2427:     if (!value) {
2428:       if (set) *set = PETSC_FALSE;
2429:     } else {
2430:       if (set) *set = PETSC_TRUE;
2431:       PetscOptionsStringToReal(value,dvalue);
2432:     }
2433:   } else {
2434:     if (set) *set = PETSC_FALSE;
2435:   }
2436:   return(0);
2437: }

2439: /*@C
2440:    PetscOptionsGetScalar - Gets the scalar value for a particular
2441:    option in the database.

2443:    Not Collective

2445:    Input Parameters:
2446: +  options - options database, use NULL for default global database
2447: .  pre - string to prepend to each name or NULL
2448: -  name - the option one is seeking

2450:    Output Parameter:
2451: +  dvalue - the double value to return
2452: -  set - PETSC_TRUE if found, else PETSC_FALSE

2454:    Level: beginner

2456:    Usage:
2457:    A complex number 2+3i must be specified with NO spaces

2459:    Notes:
2460:     If the user does not supply the option dvalue is NOT changed. Thus
2461:      you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.

2463: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2464:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2465:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2466:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2467:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2468:           PetscOptionsFList(), PetscOptionsEList()
2469: @*/
2470: PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
2471: {
2472:   const char     *value;
2473:   PetscBool      flag;

2479:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2480:   if (flag) {
2481:     if (!value) {
2482:       if (set) *set = PETSC_FALSE;
2483:     } else {
2484: #if !defined(PETSC_USE_COMPLEX)
2485:       PetscOptionsStringToReal(value,dvalue);
2486: #else
2487:       PetscOptionsStringToScalar(value,dvalue);
2488: #endif
2489:       if (set) *set = PETSC_TRUE;
2490:     }
2491:   } else { /* flag */
2492:     if (set) *set = PETSC_FALSE;
2493:   }
2494:   return(0);
2495: }

2497: /*@C
2498:    PetscOptionsGetString - Gets the string value for a particular option in
2499:    the database.

2501:    Not Collective

2503:    Input Parameters:
2504: +  options - options database, use NULL for default global database
2505: .  pre - string to prepend to name or NULL
2506: .  name - the option one is seeking
2507: -  len - maximum length of the string including null termination

2509:    Output Parameters:
2510: +  string - location to copy string
2511: -  set - PETSC_TRUE if found, else PETSC_FALSE

2513:    Level: beginner

2515:    Fortran Note:
2516:    The Fortran interface is slightly different from the C/C++
2517:    interface (len is not used).  Sample usage in Fortran follows
2518: .vb
2519:       character *20    string
2520:       PetscErrorCode   ierr
2521:       PetscBool        set
2522:       call PetscOptionsGetString(PETSC_NULL_OPTIONS,PETSC_NULL_CHARACTER,'-s',string,set,ierr)
2523: .ve

2525:    Notes:
2526:     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

2528:            If the user does not use the option then the string is not changed. Thus
2529:            you should ALWAYS initialize the string if you access it without first checking if the set flag is true.

2531:     Note:
2532:       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).

2534: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2535:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2536:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2537:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2538:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2539:           PetscOptionsFList(), PetscOptionsEList()
2540: @*/
2541: PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set)
2542: {
2543:   const char     *value;
2544:   PetscBool      flag;

2550:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2551:   if (!flag) {
2552:     if (set) *set = PETSC_FALSE;
2553:   } else {
2554:     if (set) *set = PETSC_TRUE;
2555:     if (value) {
2556:       PetscStrncpy(string,value,len);
2557:     } else {
2558:       PetscArrayzero(string,len);
2559:     }
2560:   }
2561:   return(0);
2562: }

2564: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2565: {
2566:   const char     *value;
2567:   PetscBool      flag;

2571:   PetscOptionsFindPair(options,pre,name,&value,&flag);if (ierr) PetscFunctionReturn(NULL);
2572:   if (flag) PetscFunctionReturn((char*)value);
2573:   else PetscFunctionReturn(NULL);
2574: }

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

2581:    Not Collective

2583:    Input Parameters:
2584: +  options - options database, use NULL for default global database
2585: .  pre - string to prepend to each name or NULL
2586: .  name - the option one is seeking
2587: -  nmax - maximum number of values to retrieve

2589:    Output Parameter:
2590: +  dvalue - the integer values to return
2591: .  nmax - actual number of values retreived
2592: -  set - PETSC_TRUE if found, else PETSC_FALSE

2594:    Level: beginner

2596:    Notes:
2597:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
2598:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

2600: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2601:           PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2602:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2603:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2604:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2605:           PetscOptionsFList(), PetscOptionsEList()
2606: @*/
2607: PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
2608: {
2609:   const char     *svalue;
2610:   char           *value;
2612:   PetscInt       n = 0;
2613:   PetscBool      flag;
2614:   PetscToken     token;


2621:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2622:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2623:   if (set) *set = PETSC_TRUE;
2624:   PetscTokenCreate(svalue,',',&token);
2625:   PetscTokenFind(token,&value);
2626:   while (value && n < *nmax) {
2627:     PetscOptionsStringToBool(value,dvalue);
2628:     PetscTokenFind(token,&value);
2629:     dvalue++;
2630:     n++;
2631:   }
2632:   PetscTokenDestroy(&token);
2633:   *nmax = n;
2634:   return(0);
2635: }

2637: /*@C
2638:    PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.

2640:    Not Collective

2642:    Input Parameters:
2643: +  options - options database, use NULL for default global database
2644: .  pre - option prefix or NULL
2645: .  name - option name
2646: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2647: -  nmax - maximum number of values to retrieve

2649:    Output Parameters:
2650: +  ivalue - the  enum values to return
2651: .  nmax - actual number of values retreived
2652: -  set - PETSC_TRUE if found, else PETSC_FALSE

2654:    Level: beginner

2656:    Notes:
2657:    The array must be passed as a comma separated list.

2659:    There must be no intervening spaces between the values.

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

2663: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2664:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2665:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2666:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2667:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2668:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2669: @*/
2670: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum ivalue[],PetscInt *nmax,PetscBool *set)
2671: {
2672:   const char     *svalue;
2673:   char           *value;
2674:   PetscInt       n = 0;
2675:   PetscEnum      evalue;
2676:   PetscBool      flag;
2677:   PetscToken     token;


2686:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2687:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2688:   if (set) *set = PETSC_TRUE;
2689:   PetscTokenCreate(svalue,',',&token);
2690:   PetscTokenFind(token,&value);
2691:   while (value && n < *nmax) {
2692:     PetscEnumFind(list,value,&evalue,&flag);
2693:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2694:     ivalue[n++] = evalue;
2695:     PetscTokenFind(token,&value);
2696:   }
2697:   PetscTokenDestroy(&token);
2698:   *nmax = n;
2699:   return(0);
2700: }

2702: /*@C
2703:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2704:    option in the database.

2706:    Not Collective

2708:    Input Parameters:
2709: +  options - options database, use NULL for default global database
2710: .  pre - string to prepend to each name or NULL
2711: .  name - the option one is seeking
2712: -  nmax - maximum number of values to retrieve

2714:    Output Parameter:
2715: +  ivalue - the integer values to return
2716: .  nmax - actual number of values retreived
2717: -  set - PETSC_TRUE if found, else PETSC_FALSE

2719:    Level: beginner

2721:    Notes:
2722:    The array can be passed as
2723:    a comma separated list:                                 0,1,2,3,4,5,6,7
2724:    a range (start-end+1):                                  0-8
2725:    a range with given increment (start-end+1:inc):         0-7:2
2726:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

2728:    There must be no intervening spaces between the values.

2730: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2731:           PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2732:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2733:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2734:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2735:           PetscOptionsFList(), PetscOptionsEList()
2736: @*/
2737: PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt ivalue[],PetscInt *nmax,PetscBool *set)
2738: {
2739:   const char     *svalue;
2740:   char           *value;
2742:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2743:   size_t         len;
2744:   PetscBool      flag,foundrange;
2745:   PetscToken     token;


2752:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2753:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2754:   if (set) *set = PETSC_TRUE;
2755:   PetscTokenCreate(svalue,',',&token);
2756:   PetscTokenFind(token,&value);
2757:   while (value && n < *nmax) {
2758:     /* look for form  d-D where d and D are integers */
2759:     foundrange = PETSC_FALSE;
2760:     PetscStrlen(value,&len);
2761:     if (value[0] == '-') i=2;
2762:     else i=1;
2763:     for (;i<(int)len; i++) {
2764:       if (value[i] == '-') {
2765:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2766:         value[i] = 0;

2768:         PetscOptionsStringToInt(value,&start);
2769:         inc  = 1;
2770:         j    = i+1;
2771:         for (;j<(int)len; j++) {
2772:           if (value[j] == ':') {
2773:             value[j] = 0;

2775:             PetscOptionsStringToInt(value+j+1,&inc);
2776:             if (inc <= 0) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry,%s cannot have negative increment",n,value+j+1);
2777:             break;
2778:           }
2779:         }
2780:         PetscOptionsStringToInt(value+i+1,&end);
2781:         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);
2782:         nvalues = (end-start)/inc + (end-start)%inc;
2783:         if (n + nvalues  > *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
2784:         for (;start<end; start+=inc) {
2785:           *ivalue = start; ivalue++;n++;
2786:         }
2787:         foundrange = PETSC_TRUE;
2788:         break;
2789:       }
2790:     }
2791:     if (!foundrange) {
2792:       PetscOptionsStringToInt(value,ivalue);
2793:       ivalue++;
2794:       n++;
2795:     }
2796:     PetscTokenFind(token,&value);
2797:   }
2798:   PetscTokenDestroy(&token);
2799:   *nmax = n;
2800:   return(0);
2801: }

2803: /*@C
2804:    PetscOptionsGetRealArray - Gets an array of double precision values for a
2805:    particular option in the database.  The values must be separated with
2806:    commas with no intervening spaces.

2808:    Not Collective

2810:    Input Parameters:
2811: +  options - options database, use NULL for default global database
2812: .  pre - string to prepend to each name or NULL
2813: .  name - the option one is seeking
2814: -  nmax - maximum number of values to retrieve

2816:    Output Parameters:
2817: +  dvalue - the double values to return
2818: .  nmax - actual number of values retreived
2819: -  set - PETSC_TRUE if found, else PETSC_FALSE

2821:    Level: beginner

2823: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2824:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2825:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2826:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2827:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2828:           PetscOptionsFList(), PetscOptionsEList()
2829: @*/
2830: PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
2831: {
2832:   const char     *svalue;
2833:   char           *value;
2835:   PetscInt       n = 0;
2836:   PetscBool      flag;
2837:   PetscToken     token;


2844:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2845:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2846:   if (set) *set = PETSC_TRUE;
2847:   PetscTokenCreate(svalue,',',&token);
2848:   PetscTokenFind(token,&value);
2849:   while (value && n < *nmax) {
2850:     PetscOptionsStringToReal(value,dvalue++);
2851:     PetscTokenFind(token,&value);
2852:     n++;
2853:   }
2854:   PetscTokenDestroy(&token);
2855:   *nmax = n;
2856:   return(0);
2857: }

2859: /*@C
2860:    PetscOptionsGetScalarArray - Gets an array of scalars for a
2861:    particular option in the database.  The values must be separated with
2862:    commas with no intervening spaces.

2864:    Not Collective

2866:    Input Parameters:
2867: +  options - options database, use NULL for default global database
2868: .  pre - string to prepend to each name or NULL
2869: .  name - the option one is seeking
2870: -  nmax - maximum number of values to retrieve

2872:    Output Parameters:
2873: +  dvalue - the scalar values to return
2874: .  nmax - actual number of values retreived
2875: -  set - PETSC_TRUE if found, else PETSC_FALSE

2877:    Level: beginner

2879: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2880:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2881:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2882:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2883:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2884:           PetscOptionsFList(), PetscOptionsEList()
2885: @*/
2886: PetscErrorCode PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool *set)
2887: {
2888:   const char     *svalue;
2889:   char           *value;
2891:   PetscInt       n = 0;
2892:   PetscBool      flag;
2893:   PetscToken     token;


2900:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2901:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2902:   if (set) *set = PETSC_TRUE;
2903:   PetscTokenCreate(svalue,',',&token);
2904:   PetscTokenFind(token,&value);
2905:   while (value && n < *nmax) {
2906:     PetscOptionsStringToScalar(value,dvalue++);
2907:     PetscTokenFind(token,&value);
2908:     n++;
2909:   }
2910:   PetscTokenDestroy(&token);
2911:   *nmax = n;
2912:   return(0);
2913: }

2915: /*@C
2916:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2917:    option in the database. The values must be separated with commas with
2918:    no intervening spaces.

2920:    Not Collective

2922:    Input Parameters:
2923: +  options - options database, use NULL for default global database
2924: .  pre - string to prepend to name or NULL
2925: .  name - the option one is seeking
2926: -  nmax - maximum number of strings

2928:    Output Parameter:
2929: +  strings - location to copy strings
2930: -  set - PETSC_TRUE if found, else PETSC_FALSE

2932:    Level: beginner

2934:    Notes:
2935:    The user should pass in an array of pointers to char, to hold all the
2936:    strings returned by this function.

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

2941: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2942:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2943:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2944:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2945:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2946:           PetscOptionsFList(), PetscOptionsEList()
2947: @*/
2948: PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
2949: {
2950:   const char     *svalue;
2951:   char           *value;
2953:   PetscInt       n = 0;
2954:   PetscBool      flag;
2955:   PetscToken     token;


2962:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2963:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2964:   if (set) *set = PETSC_TRUE;
2965:   PetscTokenCreate(svalue,',',&token);
2966:   PetscTokenFind(token,&value);
2967:   while (value && n < *nmax) {
2968:     PetscStrallocpy(value,&strings[n]);
2969:     PetscTokenFind(token,&value);
2970:     n++;
2971:   }
2972:   PetscTokenDestroy(&token);
2973:   *nmax = n;
2974:   return(0);
2975: }

2977: /*@C
2978:    PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with a new one

2980:    Prints a deprecation warning, unless an option is supplied to suppress.

2982:    Logically Collective

2984:    Input Parameters:
2985: +  pre - string to prepend to name or NULL
2986: .  oldname - the old, deprecated option
2987: .  newname - the new option, or NULL if option is purely removed
2988: .  version - a string describing the version of first deprecation, e.g. "3.9"
2989: -  info - additional information string, or NULL.

2991:    Options Database Keys:
2992: . -options_suppress_deprecated_warnings - do not print deprecation warnings

2994:    Notes:
2995:    Must be called between PetscOptionsBegin() (or PetscObjectOptionsBegin()) and PetscOptionsEnd().
2996:    Only the proces of rank zero that owns the PetscOptionsItems are argument (managed by PetscOptionsBegin() or
2997:    PetscObjectOptionsBegin() prints the information
2998:    If newname is provided, the old option is replaced. Otherwise, it remains
2999:    in the options database.
3000:    If an option is not replaced, the info argument should be used to advise the user
3001:    on how to proceed.
3002:    There is a limit on the length of the warning printed, so very long strings
3003:    provided as info may be truncated.

3005:    Level: developer

3007: .seealso: PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsScalar(), PetscOptionsBool(), PetscOptionsString(), PetscOptionsSetValue()

3009: @*/
3010: PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *PetscOptionsObject,const char oldname[],const char newname[],const char version[],const char info[])
3011: {
3012:   PetscErrorCode     ierr;
3013:   PetscBool          found,quiet;
3014:   const char         *value;
3015:   const char * const quietopt="-options_suppress_deprecated_warnings";
3016:   char               msg[4096];
3017:   char               *prefix = NULL;
3018:   PetscOptions       options = NULL;
3019:   MPI_Comm           comm = PETSC_COMM_SELF;

3024:   if (PetscOptionsObject) {
3025:     prefix  = PetscOptionsObject->prefix;
3026:     options = PetscOptionsObject->options;
3027:     comm    = PetscOptionsObject->comm;
3028:   }
3029:   PetscOptionsFindPair(options,prefix,oldname,&value,&found);
3030:   if (found) {
3031:     if (newname) {
3032:       if (prefix) {
3033:         PetscOptionsPrefixPush(options,prefix);
3034:       }
3035:       PetscOptionsSetValue(options,newname,value);
3036:       if (prefix) {
3037:         PetscOptionsPrefixPop(options);
3038:       }
3039:       PetscOptionsClearValue(options,oldname);
3040:     }
3041:     quiet = PETSC_FALSE;
3042:     PetscOptionsGetBool(options,NULL,quietopt,&quiet,NULL);
3043:     if (!quiet) {
3044:       PetscStrcpy(msg,"** PETSc DEPRECATION WARNING ** : the option ");
3045:       PetscStrcat(msg,oldname);
3046:       PetscStrcat(msg," is deprecated as of version ");
3047:       PetscStrcat(msg,version);
3048:       PetscStrcat(msg," and will be removed in a future release.");
3049:       if (newname) {
3050:         PetscStrcat(msg," Please use the option ");
3051:         PetscStrcat(msg,newname);
3052:         PetscStrcat(msg," instead.");
3053:       }
3054:       if (info) {
3055:         PetscStrcat(msg," ");
3056:         PetscStrcat(msg,info);
3057:       }
3058:       PetscStrcat(msg," (Silence this warning with ");
3059:       PetscStrcat(msg,quietopt);
3060:       PetscStrcat(msg,")\n");
3061:       PetscPrintf(comm,msg);
3062:     }
3063:   }
3064:   return(0);
3065: }