Actual source code: options.c

petsc-3.11.3 2019-06-26
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_STRING_H)
 19: #include <string.h>             /* strcasecmp */
 20: #endif
 21: #if defined(PETSC_HAVE_STRINGS_H)
 22: #  include <strings.h>          /* strcasecmp */
 23: #endif
 24: #if defined(PETSC_HAVE_YAML)
 25: #include <yaml.h>
 26: #endif

 28: #if defined(PETSC_HAVE_STRCASECMP)
 29: #define PetscOptNameCmp(a,b) strcasecmp(a,b)
 30: #elif defined(PETSC_HAVE_STRICMP)
 31: #define PetscOptNameCmp(a,b) stricmp(a,b)
 32: #else
 33: #define PetscOptNameCmp(a,b) Error_strcasecmp_not_found
 34: #endif

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

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

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

 60: PETSC_STATIC_INLINE int PetscOptEqual(const char a[],const char b[])
 61: {
 62:   return !PetscOptNameCmp(a,b);
 63: }

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

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

 76: struct  _n_PetscOptions {
 77:   int        N;                    /* number of options */
 78:   char       *names[MAXOPTIONS];   /* option names */
 79:   char       *values[MAXOPTIONS];  /* option values */
 80:   PetscBool  used[MAXOPTIONS];     /* flag option use */

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

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

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

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

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

105: static PetscOptions defaultoptions = NULL;


108: /*
109:     Options events monitor
110: */
111: static PetscErrorCode PetscOptionsMonitor(PetscOptions options,const char name[],const char value[])
112: {
113:   PetscInt       i;

116:   if (!PetscInitializeCalled) return 0;
118:   for (i=0; i<options->numbermonitors; i++) {
119:     (*options->monitor[i])(name,value,options->monitorcontext[i]);
120:   }
121:   return(0);
122: }

124: /*@
125:    PetscOptionsCreate - Creates an empty options database.

127:    Output Parameter:
128: .  options - Options database object

130:    Level: advanced

132: .seealso: PetscOptionsDestroy()
133: @*/
134: PetscErrorCode PetscOptionsCreate(PetscOptions *options)
135: {
136:   if (!options) return PETSC_ERR_ARG_NULL;
137:   *options = (PetscOptions)calloc(1,sizeof(**options));
138:   if (!*options) return PETSC_ERR_MEM;
139:   return 0;
140: }

142: /*@
143:     PetscOptionsDestroy - Destroys an option database.

145:   Input Parameter:
146: .  options - the PetscOptions object

148:    Level: developer

150: .seealso: PetscOptionsInsert()
151: @*/
152: PetscErrorCode PetscOptionsDestroy(PetscOptions *options)
153: {

156:   if (!*options) return 0;
157:   PetscOptionsClear(*options);if (ierr) return ierr;
158:   /* XXX what about monitors ? */
159:   free(*options);
160:   *options = NULL;
161:   return(0);
162: }

164: /*
165:     PetscOptionsCreateDefault - Creates the default global options database
166: */
167: PetscErrorCode PetscOptionsCreateDefault(void)
168: {

171:   if (!defaultoptions) {
172:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
173:   }
174:   return 0;
175: }

177: /*
178:     PetscOptionsDestroyDefault - Destroys the default global options database
179: */
180: PetscErrorCode PetscOptionsDestroyDefault(void)
181: {

184:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
185:   return 0;
186: }

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

191:    Input Parameter:
192: .  key - string to check if valid

194:    Output Parameter:
195: .  valid - PETSC_TRUE if a valid key

197:    Level: intermediate
198: @*/
199: PetscErrorCode PetscOptionsValidKey(const char key[],PetscBool *valid)
200: {
201:   char           *ptr;

206:   *valid = PETSC_FALSE;
207:   if (!key) return(0);
208:   if (key[0] != '-') return(0);
209:   if (key[1] == '-') key++;
210:   if (!isalpha((int)(key[1]))) return(0);
211:   (void) strtod(key,&ptr);
212:   if (ptr != key && !(*ptr == '_' || isalnum(*ptr))) return(0);
213:   *valid = PETSC_TRUE;
214:   return(0);
215: }

217: /*@C
218:    PetscOptionsInsertString - Inserts options into the database from a string

220:    Not Collective, but only processes that call this routine will set the options
221:    included in the string

223:    Input Parameter:
224: .  in_str - string that contains options separated by blanks


227:    Level: intermediate

229:    Contributed by Boyana Norris

231: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
232:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
233:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
234:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
235:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
236:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()
237: @*/
238: PetscErrorCode PetscOptionsInsertString(PetscOptions options,const char in_str[])
239: {
240:   char           *first,*second;
242:   PetscToken     token;
243:   PetscBool      key,ispush,ispop,isopts;

246:   PetscTokenCreate(in_str,' ',&token);
247:   PetscTokenFind(token,&first);
248:   while (first) {
249:     PetscStrcasecmp(first,"-prefix_push",&ispush);
250:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
251:     PetscStrcasecmp(first,"-options_file",&isopts);
252:     PetscOptionsValidKey(first,&key);
253:     if (ispush) {
254:       PetscTokenFind(token,&second);
255:       PetscOptionsPrefixPush(options,second);
256:       PetscTokenFind(token,&first);
257:     } else if (ispop) {
258:       PetscOptionsPrefixPop(options);
259:       PetscTokenFind(token,&first);
260:     } else if (isopts) {
261:       PetscTokenFind(token,&second);
262:       PetscOptionsInsertFile(PETSC_COMM_SELF,options,second,PETSC_TRUE);
263:       PetscTokenFind(token,&first);
264:     } else if (key) {
265:       PetscTokenFind(token,&second);
266:       PetscOptionsValidKey(second,&key);
267:       if (!key) {
268:         PetscOptionsSetValue(options,first,second);
269:         PetscTokenFind(token,&first);
270:       } else {
271:         PetscOptionsSetValue(options,first,NULL);
272:         first = second;
273:       }
274:     } else {
275:       PetscTokenFind(token,&first);
276:     }
277:   }
278:   PetscTokenDestroy(&token);
279:   return(0);
280: }

282: /*
283:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
284: */
285: static char *Petscgetline(FILE * f)
286: {
287:   size_t size  = 0;
288:   size_t len   = 0;
289:   size_t last  = 0;
290:   char   *buf  = NULL;

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

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

310:      Collective on MPI_Comm

312:   Input Parameter:
313: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
314: .   options - options database, use NULL for default global database
315: .   file - name of file
316: -   require - if PETSC_TRUE will generate an error if the file does not exist


319:   Notes:
320:     Use  # for lines that are comments and which should be ignored.

322:    Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
323:    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
324:    calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().

326:   Level: developer

328: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
329:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
330:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
331:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
332:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
333:           PetscOptionsFList(), PetscOptionsEList()

335: @*/
336: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
337: {
338:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
340:   size_t         i,len,bytes;
341:   FILE           *fd;
342:   PetscToken     token;
343:   int            err;
344:   char           cmt[1]={'#'},*cmatch;
345:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];
346:   PetscBool      isdir;

349:   MPI_Comm_rank(comm,&rank);
350:   if (!rank) {
351:     cnt        = 0;
352:     acnt       = 0;

354:     PetscFixFilename(file,fname);
355:     fd   = fopen(fname,"r");
356:     PetscTestDirectory(fname,'r',&isdir);
357:     if (isdir && require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Specified options file %s is a directory",fname);
358:     if (fd && !isdir) {
359:       PetscSegBuffer vseg,aseg;
360:       PetscSegBufferCreate(1,4000,&vseg);
361:       PetscSegBufferCreate(1,2000,&aseg);

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

366:       while ((string = Petscgetline(fd))) {
367:         /* eliminate comments from each line */
368:         for (i=0; i<1; i++) {
369:           PetscStrchr(string,cmt[i],&cmatch);
370:           if (cmatch) *cmatch = 0;
371:         }
372:         PetscStrlen(string,&len);
373:         /* replace tabs, ^M, \n with " " */
374:         for (i=0; i<len; i++) {
375:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
376:             string[i] = ' ';
377:           }
378:         }
379:         PetscTokenCreate(string,' ',&token);
380:         PetscTokenFind(token,&first);
381:         if (!first) {
382:           goto destroy;
383:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
384:           PetscTokenFind(token,&first);
385:         }
386:         PetscTokenFind(token,&second);
387:         if (!first) {
388:           goto destroy;
389:         } else if (first[0] == '-') {
390:           PetscStrlen(first,&len);
391:           PetscSegBufferGet(vseg,len+1,&vstring);
392:           PetscMemcpy(vstring,first,len);
393:           vstring[len] = ' ';
394:           if (second) {
395:             PetscStrlen(second,&len);
396:             PetscSegBufferGet(vseg,len+3,&vstring);
397:             vstring[0] = '"';
398:             PetscMemcpy(vstring+1,second,len);
399:             vstring[len+1] = '"';
400:             vstring[len+2] = ' ';
401:           }
402:         } else {
403:           PetscBool match;

405:           PetscStrcasecmp(first,"alias",&match);
406:           if (match) {
407:             PetscTokenFind(token,&third);
408:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
409:             PetscStrlen(second,&len);
410:             PetscSegBufferGet(aseg,len+1,&astring);
411:             PetscMemcpy(astring,second,len);
412:             astring[len] = ' ';

414:             PetscStrlen(third,&len);
415:             PetscSegBufferGet(aseg,len+1,&astring);
416:             PetscMemcpy(astring,third,len);
417:             astring[len] = ' ';
418:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
419:         }
420: destroy:
421:         free(string);
422:         PetscTokenDestroy(&token);
423:       }
424:       err = fclose(fd);
425:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
426:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
427:       PetscMPIIntCast(bytes,&acnt);
428:       PetscSegBufferGet(aseg,1,&astring);
429:       astring[0] = 0;
430:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
431:       PetscMPIIntCast(bytes,&cnt);
432:       PetscSegBufferGet(vseg,1,&vstring);
433:       vstring[0] = 0;
434:       PetscMalloc1(2+acnt+cnt,&packed);
435:       PetscSegBufferExtractTo(aseg,packed);
436:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
437:       PetscSegBufferDestroy(&aseg);
438:       PetscSegBufferDestroy(&vseg);
439:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
440:   }

442:   counts[0] = acnt;
443:   counts[1] = cnt;
444:   MPI_Bcast(counts,2,MPI_INT,0,comm);
445:   acnt = counts[0];
446:   cnt = counts[1];
447:   if (rank) {
448:     PetscMalloc1(2+acnt+cnt,&packed);
449:   }
450:   if (acnt || cnt) {
451:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
452:     astring = packed;
453:     vstring = packed + acnt + 1;
454:   }

456:   if (acnt) {
457:     PetscToken token;
458:     char       *first,*second;

460:     PetscTokenCreate(astring,' ',&token);
461:     PetscTokenFind(token,&first);
462:     while (first) {
463:       PetscTokenFind(token,&second);
464:       PetscOptionsSetAlias(options,first,second);
465:       PetscTokenFind(token,&first);
466:     }
467:     PetscTokenDestroy(&token);
468:   }

470:   if (cnt) {
471:     PetscOptionsInsertString(options,vstring);
472:   }
473:   PetscFree(packed);
474:   return(0);
475: }

477: static PetscErrorCode PetscOptionsInsertArgs(PetscOptions options,int argc,char *args[])
478: {
480:   int            left    = argc - 1;
481:   char           **eargs = args + 1;

484:   while (left) {
485:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
486:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
487:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
488:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
489:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
490:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
491:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
492:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
493:     isp4 = (PetscBool) (isp4 || tisp4);
494:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
495:     isp4 = (PetscBool) (isp4 || tisp4);
496:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
497:     PetscOptionsValidKey(eargs[0],&key);

499:     if (!key) {
500:       eargs++; left--;
501:     } else if (isoptions_file) {
502:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
503:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
504:       PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
505:       eargs += 2; left -= 2;
506:     } else if (isprefixpush) {
507:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
508:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
509:       PetscOptionsPrefixPush(options,eargs[1]);
510:       eargs += 2; left -= 2;
511:     } else if (isprefixpop) {
512:       PetscOptionsPrefixPop(options);
513:       eargs++; left--;

515:       /*
516:        These are "bad" options that MPICH, etc put on the command line
517:        we strip them out here.
518:        */
519:     } else if (tisp4 || isp4rmrank) {
520:       eargs += 1; left -= 1;
521:     } else if (isp4 || isp4yourname) {
522:       eargs += 2; left -= 2;
523:     } else {
524:       PetscBool nextiskey = PETSC_FALSE;
525:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
526:       if (left < 2 || nextiskey) {
527:         PetscOptionsSetValue(options,eargs[0],NULL);
528:         eargs++; left--;
529:       } else {
530:         PetscOptionsSetValue(options,eargs[0],eargs[1]);
531:         eargs += 2; left -= 2;
532:       }
533:     }
534:   }
535:   return(0);
536: }


539: /*@C
540:    PetscOptionsInsert - Inserts into the options database from the command line,
541:                    the environmental variable and a file.

543:    Input Parameters:
544: +  options - options database or NULL for the default global database
545: .  argc - count of number of command line arguments
546: .  args - the command line arguments
547: -  file - optional filename, defaults to ~username/.petscrc

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

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

558:    Level: advanced

560:    Concepts: options database^adding

562: .seealso: PetscOptionsDestroy(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
563:           PetscInitialize()
564: @*/
565: PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
566: {
568:   PetscMPIInt    rank;
569:   char           filename[PETSC_MAX_PATH_LEN];
570:   PetscBool      flag = PETSC_FALSE;


574:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

576:   if (file && file[0]) {
577:     PetscStrreplace(PETSC_COMM_WORLD,file,filename,PETSC_MAX_PATH_LEN);
578:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,filename,PETSC_TRUE);
579:   }
580:   /*
581:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
582:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
583:   */
584:   if (argc && args && *argc) {PetscOptionsInsertArgs(options,*argc,*args);}
585:   PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
586:   if (!flag) {
587:     PetscGetHomeDirectory(filename,PETSC_MAX_PATH_LEN-16);
588:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
589:     if (filename[0]) { PetscStrcat(filename,"/.petscrc"); }
590:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,filename,PETSC_FALSE);
591:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
592:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
593:   }

595:   /* insert environment options */
596:   {
597:     char   *eoptions = NULL;
598:     size_t len       = 0;
599:     if (!rank) {
600:       eoptions = (char*)getenv("PETSC_OPTIONS");
601:       PetscStrlen(eoptions,&len);
602:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
603:     } else {
604:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
605:       if (len) {
606:         PetscMalloc1(len+1,&eoptions);
607:       }
608:     }
609:     if (len) {
610:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
611:       if (rank) eoptions[len] = 0;
612:       PetscOptionsInsertString(options,eoptions);
613:       if (rank) {PetscFree(eoptions);}
614:     }
615:   }

617: #if defined(PETSC_HAVE_YAML)
618:   {
619:     char      yaml_file[PETSC_MAX_PATH_LEN];
620:     PetscBool yaml_flg;
621:     PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
622:     if (yaml_flg) {
623:       PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
624:     }
625:   }
626: #endif

628:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
629:   if (argc && args && *argc) {PetscOptionsInsertArgs(options,*argc,*args);}
630:   return(0);
631: }

633: /*@C
634:    PetscOptionsView - Prints the options that have been loaded. This is
635:    useful for debugging purposes.

637:    Logically Collective on PetscViewer

639:    Input Parameter:
640: -  options - options database, use NULL for default global database
641: +  viewer - must be an PETSCVIEWERASCII viewer

643:    Options Database Key:
644: .  -options_view - Activates PetscOptionsView() within PetscFinalize()

646:    Level: advanced

648:    Concepts: options database^printing

650: .seealso: PetscOptionsAllUsed()
651: @*/
652: PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer)
653: {
655:   PetscInt       i;
656:   PetscBool      isascii;

660:   options = options ? options : defaultoptions;
661:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
662:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
663:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

665:   if (!options->N) {
666:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
667:     return(0);
668:   }

670:   PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
671:   for (i=0; i<options->N; i++) {
672:     if (options->values[i]) {
673:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
674:     } else {
675:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
676:     }
677:   }
678:   PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
679:   return(0);
680: }

682: /*
683:    Called by error handlers to print options used in run
684: */
685: PETSC_EXTERN PetscErrorCode PetscOptionsViewError(void)
686: {
687:   PetscInt     i;
688:   PetscOptions options = defaultoptions;

691:   if (options->N) {
692:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
693:   } else {
694:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
695:   }
696:   for (i=0; i<options->N; i++) {
697:     if (options->values[i]) {
698:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
699:     } else {
700:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
701:     }
702:   }
703:   return(0);
704: }

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

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

711:    Input Parameter:
712: +  options - options database, or NULL for the default global database
713: -  prefix - The string to append to the existing prefix

715:    Options Database Keys:
716: +   -prefix_push <some_prefix_> - push the given prefix
717: -   -prefix_pop - pop the last prefix

719:    Notes:
720:    It is common to use this in conjunction with -options_file as in

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

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

726: Level: advanced

728: .seealso: PetscOptionsPrefixPop()
729: @*/
730: PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
731: {
733:   size_t         n;
734:   PetscInt       start;
735:   char           key[MAXOPTNAME+1];
736:   PetscBool      valid;

740:   options = options ? options : defaultoptions;
741:   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);
742:   key[0] = '-'; /* keys must start with '-' */
743:   PetscStrncpy(key+1,prefix,sizeof(key)-1);
744:   PetscOptionsValidKey(key,&valid);
745:   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);
746:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
747:   PetscStrlen(prefix,&n);
748:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
749:   PetscMemcpy(options->prefix+start,prefix,n+1);
750:   options->prefixstack[options->prefixind++] = start+n;
751:   return(0);
752: }

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

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

759:   Input Parameters:
760: .  options - options database, or NULL for the default global database

762:    Level: advanced

764: .seealso: PetscOptionsPrefixPush()
765: @*/
766: PetscErrorCode PetscOptionsPrefixPop(PetscOptions options)
767: {
768:   PetscInt offset;

771:   options = options ? options : defaultoptions;
772:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
773:   options->prefixind--;
774:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
775:   options->prefix[offset] = 0;
776:   return(0);
777: }

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

782:   Input Parameters:
783: .  options - options database, use NULL for the default global database

785:    Level: developer

787: .seealso: PetscOptionsInsert()
788: @*/
789: PetscErrorCode PetscOptionsClear(PetscOptions options)
790: {
791:   PetscInt i;

793:   options = options ? options : defaultoptions;
794:   if (!options) return 0;

796:   for (i=0; i<options->N; i++) {
797:     if (options->names[i])  free(options->names[i]);
798:     if (options->values[i]) free(options->values[i]);
799:   }
800:   options->N = 0;

802:   for (i=0; i<options->Naliases; i++) {
803:     free(options->aliases1[i]);
804:     free(options->aliases2[i]);
805:   }
806:   options->Naliases = 0;

808:   /* destroy hash table */
809:   kh_destroy(HO,options->ht);
810:   options->ht = NULL;

812:   options->prefixind = 0;
813:   options->prefix[0] = 0;
814:   options->help      = PETSC_FALSE;
815:   return 0;
816: }

818: /*@C
819:    PetscOptionsSetAlias - Makes a key and alias for another key

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

824:    Input Parameters:
825: +  options - options database, or NULL for default global database
826: .  newname - the alias
827: -  oldname - the name that alias will refer to

829:    Level: advanced

831: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
832:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
833:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
834:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
835:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
836:           PetscOptionsFList(), PetscOptionsEList()
837: @*/
838: PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char newname[],const char oldname[])
839: {
840:   PetscInt       n;
841:   size_t         len;

847:   options = options ? options : defaultoptions;
848:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must start with '-': Instead %s",newname);
849:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must start with '-': Instead %s",oldname);

851:   n = options->Naliases;
852:   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);

854:   newname++; oldname++;
855:   PetscStrlen(newname,&len);
856:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
857:   PetscStrcpy(options->aliases1[n],newname);
858:   PetscStrlen(oldname,&len);
859:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
860:   PetscStrcpy(options->aliases2[n],oldname);
861:   options->Naliases++;
862:   return(0);
863: }

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

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

872:    Input Parameters:
873: +  options - options database, use NULL for the default global database
874: .  name - name of option, this SHOULD have the - prepended
875: -  value - the option value (not used for all options, so can be NULL)

877:    Level: intermediate

879:    Note:
880:    This function can be called BEFORE PetscInitialize()

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

884:    Concepts: options database^adding option

886: .seealso: PetscOptionsInsert(), PetscOptionsClearValue()
887: @*/
888: PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char name[],const char value[])
889: {
890:   size_t         len;
891:   int            N,n,i;
892:   char           **names;
893:   char           fullname[MAXOPTNAME] = "";

896:   if (!options && !defaultoptions) {
897:     PetscOptionsCreateDefault();if (ierr) return ierr;
898:   }
899:   options = options ? options : defaultoptions;

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

903:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
904:   if (!strcmp(name,"-h")) name = "-help";
905:   if (!PetscOptNameCmp(name,"-help")) options->help = PETSC_TRUE;

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

909:   if (options->prefixind > 0) {
910:     strncpy(fullname,options->prefix,sizeof(fullname));
911:     fullname[sizeof(fullname)-1] = 0;
912:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
913:     fullname[sizeof(fullname)-1] = 0;
914:     name = fullname;
915:   }

917:   /* check against aliases */
918:   N = options->Naliases;
919:   for (i=0; i<N; i++) {
920:     int result = PetscOptNameCmp(options->aliases1[i],name);
921:     if (!result) { name = options->aliases2[i]; break; }
922:   }

924:   /* slow search */
925:   N = n = options->N;
926:   names = options->names;
927:   for (i=0; i<N; i++) {
928:     int result = PetscOptNameCmp(names[i],name);
929:     if (!result) {
930:       n = i; goto setvalue;
931:     } else if (result > 0) {
932:       n = i; break;
933:     }
934:   }
935:   if (N >= MAXOPTIONS) return PETSC_ERR_MEM;
936:   /* shift remaining values up 1 */
937:   for (i=N; i>n; i--) {
938:     options->names[i]  = options->names[i-1];
939:     options->values[i] = options->values[i-1];
940:     options->used[i]   = options->used[i-1];
941:   }
942:   options->names[n]  = NULL;
943:   options->values[n] = NULL;
944:   options->used[n]   = PETSC_FALSE;
945:   options->N++;

947:   /* destroy hash table */
948:   kh_destroy(HO,options->ht);
949:   options->ht = NULL;

951:   /* set new name */
952:   len = strlen(name);
953:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
954:   if (!options->names[n]) return PETSC_ERR_MEM;
955:   strcpy(options->names[n],name);

957: setvalue:
958:   /* set new value */
959:   if (options->values[n]) free(options->values[n]);
960:   len = value ? strlen(value) : 0;
961:   if (len) {
962:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
963:     if (!options->values[n]) return PETSC_ERR_MEM;
964:     strcpy(options->values[n],value);
965:   } else {
966:     options->values[n] = NULL;
967:   }

969:   PetscOptionsMonitor(options,name,value?value:"");if (ierr) return ierr;
970:   return 0;
971: }

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

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

980:    Input Parameter:
981: +  options - options database, use NULL for the default global database
982: .  name - name of option, this SHOULD have the - prepended

984:    Level: intermediate

986:    Concepts: options database^removing option
987: .seealso: PetscOptionsInsert()
988: @*/
989: PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char name[])
990: {
991:   int            N,n,i;
992:   char           **names;

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

999:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
1000:   if (!strcmp(name,"-h")) name = "-help";
1001:   if (!PetscOptNameCmp(name,"-help")) options->help = PETSC_FALSE;

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

1005:   /* slow search */
1006:   N = n = options->N;
1007:   names = options->names;
1008:   for (i=0; i<N; i++) {
1009:     int result = PetscOptNameCmp(names[i],name);
1010:     if (!result) {
1011:       n = i; break;
1012:     } else if (result > 0) {
1013:       n = N; break;
1014:     }
1015:   }
1016:   if (n == N) return(0); /* it was not present */

1018:   /* remove name and value */
1019:   if (options->names[n])  free(options->names[n]);
1020:   if (options->values[n]) free(options->values[n]);
1021:   /* shift remaining values down 1 */
1022:   for (i=n; i<N-1; i++) {
1023:     options->names[i]  = options->names[i+1];
1024:     options->values[i] = options->values[i+1];
1025:     options->used[i]   = options->used[i+1];
1026:   }
1027:   options->N--;

1029:   /* destroy hash table */
1030:   kh_destroy(HO,options->ht);
1031:   options->ht = NULL;

1033:   PetscOptionsMonitor(options,name,NULL);
1034:   return(0);
1035: }

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

1040:    Not Collective

1042:    Input Parameters:
1043: +  options - options database, use NULL for the default global database
1044: .  pre - the string to prepend to the name or NULL, this SHOULD NOT have the "-" prepended
1045: -  name - name of option, this SHOULD have the "-" prepended

1047:    Output Parameters:
1048: +  value - the option value (optional, not used for all options)
1049: -  set - whether the option is set (optional)

1051:    Level: developer

1053:   Concepts: options database^getting option

1055: .seealso: PetscOptionsSetValue(), PetscOptionsClearValue()
1056: @*/
1057: PetscErrorCode PetscOptionsFindPair(PetscOptions options,const char pre[],const char name[],const char *value[],PetscBool *set)
1058: {
1059:   char           buf[MAXOPTNAME];
1060:   PetscBool      usehashtable = PETSC_TRUE;
1061:   PetscBool      matchnumbers = PETSC_TRUE;

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

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

1071:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1072:   if (pre && pre[0]) {
1073:     char *ptr = buf;
1074:     if (name[0] == '-') { *ptr++ = '-';  name++; }
1075:     PetscStrncpy(ptr,pre,buf+sizeof(buf)-ptr);
1076:     PetscStrlcat(buf,name,sizeof(buf));
1077:     name = buf;
1078:   }

1080: #if defined(PETSC_USE_DEBUG)
1081:   {
1082:     PetscBool valid;
1083:     char      key[MAXOPTNAME+1] = "-";
1084:     PetscStrncpy(key+1,name,sizeof(key)-1);
1085:     PetscOptionsValidKey(key,&valid);
1086:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1087:   }
1088: #endif

1090:   if (!options->ht && usehashtable) {
1091:     int i,ret;
1092:     khiter_t it;
1093:     khash_t(HO) *ht;
1094:     ht = kh_init(HO);
1095:     if (PetscUnlikely(!ht)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1096:     ret = kh_resize(HO,ht,options->N*2); /* twice the required size to reduce risk of collisions */
1097:     if (PetscUnlikely(ret)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1098:     for (i=0; i<options->N; i++) {
1099:       it = kh_put(HO,ht,options->names[i],&ret);
1100:       if (PetscUnlikely(ret != 1)) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"Hash table allocation failed");
1101:       kh_val(ht,it) = i;
1102:     }
1103:     options->ht = ht;
1104:   }

1106:   if (usehashtable)
1107:   { /* fast search */
1108:     khash_t(HO) *ht = options->ht;
1109:     khiter_t it = kh_get(HO,ht,name);
1110:     if (it != kh_end(ht)) {
1111:       int i = kh_val(ht,it);
1112:       options->used[i]  = PETSC_TRUE;
1113:       if (value) *value = options->values[i];
1114:       if (set)   *set   = PETSC_TRUE;
1115:       return(0);
1116:     }
1117:   } else
1118:   { /* slow search */
1119:     int i, N = options->N;
1120:     for (i=0; i<N; i++) {
1121:       int result = PetscOptNameCmp(options->names[i],name);
1122:       if (!result) {
1123:         options->used[i]  = PETSC_TRUE;
1124:         if (value) *value = options->values[i];
1125:         if (set)   *set   = PETSC_TRUE;
1126:         return(0);
1127:       } else if (result > 0) {
1128:         break;
1129:       }
1130:     }
1131:   }

1133:   /*
1134:    The following block slows down all lookups in the most frequent path (most lookups are unsuccessful).
1135:    Maybe this special lookup mode should be enabled on request with a push/pop API.
1136:    The feature of matching _%d_ used sparingly in the codebase.
1137:    */
1138:   if (matchnumbers) {
1139:     int i,j,cnt = 0,locs[16],loce[16];
1140:     /* determine the location and number of all _%d_ in the key */
1141:     for (i=0; name[i]; i++) {
1142:       if (name[i] == '_') {
1143:         for (j=i+1; name[j]; j++) {
1144:           if (name[j] >= '0' && name[j] <= '9') continue;
1145:           if (name[j] == '_' && j > i+1) { /* found a number */
1146:             locs[cnt]   = i+1;
1147:             loce[cnt++] = j+1;
1148:           }
1149:           i = j-1;
1150:           break;
1151:         }
1152:       }
1153:     }
1154:     for (i=0; i<cnt; i++) {
1155:       PetscBool found;
1156:       char      opt[MAXOPTNAME+1] = "-", tmp[MAXOPTNAME];
1157:       PetscStrncpy(tmp,name,PetscMin((size_t)(locs[i]+1),sizeof(tmp)));
1158:       PetscStrlcat(opt,tmp,sizeof(opt));
1159:       PetscStrlcat(opt,name+loce[i],sizeof(opt));
1160:       PetscOptionsFindPair(options,NULL,opt,value,&found);
1161:       if (found) {if (set) *set = PETSC_TRUE; return(0);}
1162:     }
1163:   }

1165:   if (set) *set = PETSC_FALSE;
1166:   return(0);
1167: }

1169: /* Check whether any option begins with pre+name */
1170: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[],const char *value[],PetscBool *set)
1171: {
1172:   char           buf[MAXOPTNAME];
1173:   int            numCnt = 0, locs[16],loce[16];

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

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

1183:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1184:   if (pre && pre[0]) {
1185:     char *ptr = buf;
1186:     if (name[0] == '-') { *ptr++ = '-';  name++; }
1187:     PetscStrncpy(ptr,pre,sizeof(buf)+(size_t)(ptr-buf));
1188:     PetscStrlcat(buf,name,sizeof(buf));
1189:     name = buf;
1190:   }

1192: #if defined(PETSC_USE_DEBUG)
1193:   {
1194:     PetscBool valid;
1195:     char      key[MAXOPTNAME+1] = "-";
1196:     PetscStrncpy(key+1,name,sizeof(key)-1);
1197:     PetscOptionsValidKey(key,&valid);
1198:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1199:   }
1200: #endif

1202:   /* determine the location and number of all _%d_ in the key */
1203:   {
1204:     int i,j;
1205:     for (i=0; name[i]; i++) {
1206:       if (name[i] == '_') {
1207:         for (j=i+1; name[j]; j++) {
1208:           if (name[j] >= '0' && name[j] <= '9') continue;
1209:           if (name[j] == '_' && j > i+1) { /* found a number */
1210:             locs[numCnt]   = i+1;
1211:             loce[numCnt++] = j+1;
1212:           }
1213:           i = j-1;
1214:           break;
1215:         }
1216:       }
1217:     }
1218:   }

1220:   { /* slow search */
1221:     int       c, i;
1222:     size_t    len;
1223:     PetscBool match;

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

1228:       if (c < 0) {
1229:         PetscStrcpy(opt,name);
1230:       } else {
1231:         PetscStrncpy(tmp,name,PetscMin((size_t)(locs[c]+1),sizeof(tmp)));
1232:         PetscStrlcat(opt,tmp,sizeof(opt));
1233:         PetscStrlcat(opt,name+loce[c],sizeof(opt));
1234:       }
1235:       PetscStrlen(opt,&len);
1236:       for (i=0; i<options->N; i++) {
1237:         PetscStrncmp(options->names[i],opt,len,&match);
1238:         if (match) {
1239:           options->used[i]  = PETSC_TRUE;
1240:           if (value) *value = options->values[i];
1241:           if (set)   *set   = PETSC_TRUE;
1242:           return(0);
1243:         }
1244:       }
1245:     }
1246:   }

1248:   if (set) *set = PETSC_FALSE;
1249:   return(0);
1250: }

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

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

1258:    Input Parameters:
1259: +  options - options database, use NULL for default global database
1260: .  pre - the option prefix (may be NULL)
1261: .  name - the option name one is seeking
1262: -  mess - error message (may be NULL)

1264:    Level: advanced

1266:    Concepts: options database^rejecting option

1268: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1269:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1270:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1271:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1272:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1273:           PetscOptionsFList(), PetscOptionsEList()
1274: @*/
1275: PetscErrorCode PetscOptionsReject(PetscOptions options,const char pre[],const char name[],const char mess[])
1276: {
1278:   PetscBool      flag = PETSC_FALSE;

1281:   PetscOptionsHasName(options,pre,name,&flag);
1282:   if (flag) {
1283:     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);
1284:     else SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: -%s%s",pre?pre:"",name+1);
1285:   }
1286:   return(0);
1287: }

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

1292:    Not Collective

1294:    Input Parameters:
1295: .  options - options database, use NULL for default global database

1297:    Output Parameters:
1298: .  set - PETSC_TRUE if found else PETSC_FALSE.

1300:    Level: advanced

1302:    Concepts: options database^help

1304: .seealso: PetscOptionsHasName()
1305: @*/
1306: PetscErrorCode PetscOptionsHasHelp(PetscOptions options,PetscBool *set)
1307: {
1310:   options = options ? options : defaultoptions;
1311:   *set = options->help;
1312:   return(0);
1313: }

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

1319:    Not Collective

1321:    Input Parameters:
1322: +  options - options database, use NULL for default global database
1323: .  pre - string to prepend to the name or NULL
1324: -  name - the option one is seeking

1326:    Output Parameters:
1327: .  set - PETSC_TRUE if found else PETSC_FALSE.

1329:    Level: beginner

1331:    Concepts: options database^has option name

1333:    Notes:
1334:    Name cannot be simply "-h".

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

1338: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1339:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1340:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1341:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1342:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1343:           PetscOptionsFList(), PetscOptionsEList()
1344: @*/
1345: PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set)
1346: {
1347:   const char     *value;
1349:   PetscBool      flag;

1352:   PetscOptionsFindPair(options,pre,name,&value,&flag);
1353:   if (set) *set = flag;
1354:   return(0);
1355: }

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

1360:    Not Collective

1362:    Input Paramter:
1363: .  options - the options database, use NULL for the default global database

1365:    Output Parameter:
1366: .  copts - pointer where string pointer is stored

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

1371:    Level: advanced

1373:    Concepts: options database^listing

1375: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
1376: @*/
1377: PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[])
1378: {
1380:   PetscInt       i;
1381:   size_t         len = 1,lent = 0;
1382:   char           *coptions = NULL;

1386:   options = options ? options : defaultoptions;
1387:   /* count the length of the required string */
1388:   for (i=0; i<options->N; i++) {
1389:     PetscStrlen(options->names[i],&lent);
1390:     len += 2 + lent;
1391:     if (options->values[i]) {
1392:       PetscStrlen(options->values[i],&lent);
1393:       len += 1 + lent;
1394:     }
1395:   }
1396:   PetscMalloc1(len,&coptions);
1397:   coptions[0] = 0;
1398:   for (i=0; i<options->N; i++) {
1399:     PetscStrcat(coptions,"-");
1400:     PetscStrcat(coptions,options->names[i]);
1401:     PetscStrcat(coptions," ");
1402:     if (options->values[i]) {
1403:       PetscStrcat(coptions,options->values[i]);
1404:       PetscStrcat(coptions," ");
1405:     }
1406:   }
1407:   *copts = coptions;
1408:   return(0);
1409: }

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

1414:    Not Collective

1416:    Input Parameter:
1417: +  options - options database, use NULL for default global database
1418: -  name - string name of option

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

1423:    Level: advanced

1425: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
1426: @*/
1427: PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *name,PetscBool *used)
1428: {
1429:   PetscInt       i;

1435:   options = options ? options : defaultoptions;
1436:   *used = PETSC_FALSE;
1437:   for (i=0; i<options->N; i++) {
1438:     PetscStrcmp(options->names[i],name,used);
1439:     if (*used) {
1440:       *used = options->used[i];
1441:       break;
1442:     }
1443:   }
1444:   return(0);
1445: }

1447: /*@
1448:    PetscOptionsAllUsed - Returns a count of the number of options in the
1449:    database that have never been selected.

1451:    Not Collective

1453:    Input Parameter:
1454: .  options - options database, use NULL for default global database

1456:    Output Parameter:
1457: .  N - count of options not used

1459:    Level: advanced

1461: .seealso: PetscOptionsView()
1462: @*/
1463: PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
1464: {
1465:   PetscInt     i,n = 0;

1469:   options = options ? options : defaultoptions;
1470:   for (i=0; i<options->N; i++) {
1471:     if (!options->used[i]) n++;
1472:   }
1473:   *N = n;
1474:   return(0);
1475: }

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

1480:    Not Collective

1482:    Input Parameter:
1483: .  options - options database; use NULL for default global database

1485:    Options Database Key:
1486: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1488:    Level: advanced

1490: .seealso: PetscOptionsAllUsed()
1491: @*/
1492: PetscErrorCode PetscOptionsLeft(PetscOptions options)
1493: {
1495:   PetscInt       i;

1498:   options = options ? options : defaultoptions;
1499:   for (i=0; i<options->N; i++) {
1500:     if (!options->used[i]) {
1501:       if (options->values[i]) {
1502:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1503:       } else {
1504:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
1505:       }
1506:     }
1507:   }
1508:   return(0);
1509: }

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

1514:    Not Collective

1516:    Input Parameter:
1517: .  options - options database, use NULL for default global database

1519:    Output Parameter:
1520: .  N - count of options not used
1521: .  names - names of options not used
1522: .  values - values of options not used

1524:    Level: advanced

1526:    Notes:
1527:    Users should call PetscOptionsLeftRestore() to free the memory allocated in this routine

1529: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft()
1530: @*/
1531: PetscErrorCode PetscOptionsLeftGet(PetscOptions options,PetscInt *N,char **names[],char **values[])
1532: {
1534:   PetscInt       i,n;

1540:   options = options ? options : defaultoptions;

1542:   /* The number of unused PETSc options */
1543:   n = 0;
1544:   for (i=0; i<options->N; i++) {
1545:     if (!options->used[i]) n++;
1546:   }
1547:   if (N) { *N = n; }
1548:   if (names)  { PetscMalloc1(n,names); }
1549:   if (values) { PetscMalloc1(n,values); }

1551:   n = 0;
1552:   if (names || values) {
1553:     for (i=0; i<options->N; i++) {
1554:       if (!options->used[i]) {
1555:         if (names)  (*names)[n]  = options->names[i];
1556:         if (values) (*values)[n] = options->values[i];
1557:         n++;
1558:       }
1559:     }
1560:   }
1561:   return(0);
1562: }

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

1567:    Not Collective

1569:    Input Parameter:
1570: .  options - options database, use NULL for default global database
1571: .  names - names of options not used
1572: .  values - values of options not used

1574:    Level: advanced

1576: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft(), PetscOptionsLeftGet()
1577: @*/
1578: PetscErrorCode PetscOptionsLeftRestore(PetscOptions options,PetscInt *N,char **names[],char **values[])
1579: {

1586:   if (N) { *N = 0; }
1587:   if (names)  { PetscFree(*names); }
1588:   if (values) { PetscFree(*values); }
1589:   return(0);
1590: }

1592: /*@C
1593:    PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc

1595:    Collective on PETSC_COMM_WORLD

1597:    Input Parameter:
1598: .  options - options database, use NULL for default global database

1600:    Options Database Keys:
1601: +  -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
1602:                 available for options set through a file, environment variable, or on
1603:                 the command line. Only options set after PetscInitialize() completes will
1604:                 be monitored.
1605: .  -options_monitor_cancel - cancel all options database monitors

1607:    Notes:
1608:    To see all options, run your program with the -help option or consult Users-Manual: Introduction

1610:    Level: intermediate

1612: .keywords: set, options, database
1613: @*/
1614: PetscErrorCode PetscOptionsSetFromOptions(PetscOptions options)
1615: {
1616:   PetscBool      flgc = PETSC_FALSE,flgm;
1618:   char           monfilename[PETSC_MAX_PATH_LEN];
1619:   PetscViewer    monviewer;

1622:   /*
1623:      The options argument is currently ignored since we currently maintain only a single options database

1625:      options = options ? options : defaultoptions;
1626:   */
1627:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
1628:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
1629:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
1630:   PetscOptionsEnd();
1631:   if (flgm) {
1632:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1633:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
1634:   }
1635:   if (flgc) { PetscOptionsMonitorCancel(); }
1636:   return(0);
1637: }

1639: /*@C
1640:    PetscOptionsMonitorDefault - Print all options set value events.

1642:    Logically Collective on PETSC_COMM_WORLD

1644:    Input Parameters:
1645: +  name  - option name string
1646: .  value - option value string
1647: -  ctx - an ASCII viewer

1649:    Level: intermediate

1651: .keywords: PetscOptions, default, monitor

1653: .seealso: PetscOptionsMonitorSet()
1654: @*/
1655: PetscErrorCode PetscOptionsMonitorDefault(const char name[],const char value[],void *ctx)
1656: {
1658:   PetscViewer    viewer = (PetscViewer)ctx;

1661:   if (!value) {
1662:     PetscViewerASCIIPrintf(viewer,"Removing option: %s\n",name,value);
1663:   } else if (!value[0]) {
1664:     PetscViewerASCIIPrintf(viewer,"Setting option: %s (no value)\n",name);
1665:   } else {
1666:     PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1667:   }
1668:   return(0);
1669: }

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

1675:    Not Collective

1677:    Input Parameters:
1678: +  monitor - pointer to function (if this is NULL, it turns off monitoring
1679: .  mctx    - [optional] context for private data for the
1680:              monitor routine (use NULL if no context is desired)
1681: -  monitordestroy - [optional] routine that frees monitor context
1682:           (may be NULL)

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

1687: +  name - option name string
1688: .  value - option value string
1689: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1691:    Options Database Keys:
1692: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1693: -    -options_monitor_cancel - cancels all monitors that have
1694:                           been hardwired into a code by
1695:                           calls to PetscOptionsMonitorSet(), but
1696:                           does not cancel those set via
1697:                           the options database.

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

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

1708:    Level: beginner

1710: .keywords: PetscOptions, set, monitor

1712: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1713: @*/
1714: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
1715: {
1716:   PetscOptions options = defaultoptions;

1719:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1720:   options->monitor[options->numbermonitors]          = monitor;
1721:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
1722:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1723:   return(0);
1724: }

1726: /*@
1727:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1729:    Not Collective

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

1736:    Level: intermediate

1738: .keywords: PetscOptions, set, monitor

1740: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1741: @*/
1742: PetscErrorCode PetscOptionsMonitorCancel(void)
1743: {
1745:   PetscInt       i;
1746:   PetscOptions   options = defaultoptions;

1749:   for (i=0; i<options->numbermonitors; i++) {
1750:     if (options->monitordestroy[i]) {
1751:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
1752:     }
1753:   }
1754:   options->numbermonitors = 0;
1755:   return(0);
1756: }

1758: /*
1759:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1", "off", "on".
1760: */
1761: PetscErrorCode PetscOptionsStringToBool(const char value[],PetscBool *a)
1762: {
1763:   PetscBool      istrue,isfalse;
1764:   size_t         len;

1768:   PetscStrlen(value,&len);
1769:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Character string of length zero has no logical value");
1770:   PetscStrcasecmp(value,"TRUE",&istrue);
1771:   if (istrue) {*a = PETSC_TRUE; return(0);}
1772:   PetscStrcasecmp(value,"YES",&istrue);
1773:   if (istrue) {*a = PETSC_TRUE; return(0);}
1774:   PetscStrcasecmp(value,"1",&istrue);
1775:   if (istrue) {*a = PETSC_TRUE; return(0);}
1776:   PetscStrcasecmp(value,"on",&istrue);
1777:   if (istrue) {*a = PETSC_TRUE; return(0);}
1778:   PetscStrcasecmp(value,"FALSE",&isfalse);
1779:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1780:   PetscStrcasecmp(value,"NO",&isfalse);
1781:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1782:   PetscStrcasecmp(value,"0",&isfalse);
1783:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1784:   PetscStrcasecmp(value,"off",&isfalse);
1785:   if (isfalse) {*a = PETSC_FALSE; return(0);}
1786:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1787: }

1789: /*
1790:    PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
1791: */
1792: PetscErrorCode PetscOptionsStringToInt(const char name[],PetscInt *a)
1793: {
1795:   size_t         len;
1796:   PetscBool      decide,tdefault,mouse;

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

1802:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
1803:   if (!tdefault) {
1804:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
1805:   }
1806:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
1807:   if (!decide) {
1808:     PetscStrcasecmp(name,"DECIDE",&decide);
1809:   }
1810:   PetscStrcasecmp(name,"mouse",&mouse);

1812:   if (tdefault)    *a = PETSC_DEFAULT;
1813:   else if (decide) *a = PETSC_DECIDE;
1814:   else if (mouse)  *a = -1;
1815:   else {
1816:     char *endptr;
1817:     long strtolval;

1819:     strtolval = strtol(name,&endptr,10);
1820:     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);

1822: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
1823:     (void) strtolval;
1824:     *a = atoll(name);
1825: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
1826:     (void) strtolval;
1827:     *a = _atoi64(name);
1828: #else
1829:     *a = (PetscInt)strtolval;
1830: #endif
1831:   }
1832:   return(0);
1833: }

1835: #if defined(PETSC_USE_REAL___FLOAT128)
1836: #include <quadmath.h>
1837: #endif

1839: static PetscErrorCode PetscStrtod(const char name[],PetscReal *a,char **endptr)
1840: {
1842: #if defined(PETSC_USE_REAL___FLOAT128)
1843:   *a = strtoflt128(name,endptr);
1844: #else
1845:   *a = (PetscReal)strtod(name,endptr);
1846: #endif
1847:   return(0);
1848: }

1850: static PetscErrorCode PetscStrtoz(const char name[],PetscScalar *a,char **endptr,PetscBool *isImaginary)
1851: {
1852:   PetscBool      hasi = PETSC_FALSE;
1853:   char           *ptr;
1854:   PetscReal      strtoval;

1858:   PetscStrtod(name,&strtoval,&ptr);
1859:   if (ptr == name) {
1860:     strtoval = 1.;
1861:     hasi = PETSC_TRUE;
1862:     if (name[0] == 'i') {
1863:       ptr++;
1864:     } else if (name[0] == '+' && name[1] == 'i') {
1865:       ptr += 2;
1866:     } else if (name[0] == '-' && name[1] == 'i') {
1867:       strtoval = -1.;
1868:       ptr += 2;
1869:     }
1870:   } else if (*ptr == 'i') {
1871:     hasi = PETSC_TRUE;
1872:     ptr++;
1873:   }
1874:   *endptr = ptr;
1875:   *isImaginary = hasi;
1876:   if (hasi) {
1877: #if !defined(PETSC_USE_COMPLEX)
1878:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s contains imaginary but complex not supported ",name);
1879: #else
1880:     *a = PetscCMPLX(0.,strtoval);
1881: #endif
1882:   } else {
1883:     *a = strtoval;
1884:   }
1885:   return(0);
1886: }

1888: /*
1889:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
1890: */
1891: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
1892: {
1893:   size_t         len;
1894:   PetscBool      match;
1895:   char           *endptr;

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

1902:   PetscStrcasecmp(name,"PETSC_DEFAULT",&match);
1903:   if (!match) {
1904:     PetscStrcasecmp(name,"DEFAULT",&match);
1905:   }
1906:   if (match) {*a = PETSC_DEFAULT; return(0);}

1908:   PetscStrcasecmp(name,"PETSC_DECIDE",&match);
1909:   if (!match) {
1910:     PetscStrcasecmp(name,"DECIDE",&match);
1911:   }
1912:   if (match) {*a = PETSC_DECIDE; return(0);}

1914:   PetscStrtod(name,a,&endptr);
1915:   if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value",name);
1916:   return(0);
1917: }

1919: PetscErrorCode PetscOptionsStringToScalar(const char name[],PetscScalar *a)
1920: {
1921:   PetscBool      imag1;
1922:   size_t         len;
1923:   PetscScalar    val = 0.;
1924:   char           *ptr = NULL;

1928:   PetscStrlen(name,&len);
1929:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
1930:   PetscStrtoz(name,&val,&ptr,&imag1);
1931: #if defined(PETSC_USE_COMPLEX)
1932:   if ((size_t) (ptr - name) < len) {
1933:     PetscBool   imag2;
1934:     PetscScalar val2;

1936:     PetscStrtoz(ptr,&val2,&ptr,&imag2);
1937:     if (imag1 || !imag2) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s: must specify imaginary component second",name);
1938:     val = PetscCMPLX(PetscRealPart(val),PetscImaginaryPart(val2));
1939:   }
1940: #endif
1941:   if ((size_t) (ptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
1942:   *a = val;
1943:   return(0);
1944: }

1946: /*@C
1947:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1948:             option in the database.

1950:    Not Collective

1952:    Input Parameters:
1953: +  options - options database, use NULL for default global database
1954: .  pre - the string to prepend to the name or NULL
1955: -  name - the option one is seeking

1957:    Output Parameter:
1958: +  ivalue - the logical value to return
1959: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1961:    Level: beginner

1963:    Notes:
1964:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1965:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1967:       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
1968:      is equivalent to -requested_bool true

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

1973:    Concepts: options database^has logical

1975: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1976:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1977:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1978:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1979:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1980:           PetscOptionsFList(), PetscOptionsEList()
1981: @*/
1982: PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1983: {
1984:   const char     *value;
1985:   PetscBool      flag;

1991:   PetscOptionsFindPair(options,pre,name,&value,&flag);
1992:   if (flag) {
1993:     if (set) *set = PETSC_TRUE;
1994:     if (!value) {
1995:       if (ivalue) *ivalue = PETSC_TRUE;
1996:     } else {
1997:       PetscOptionsStringToBool(value, &flag);
1998:       if (ivalue) *ivalue = flag;
1999:     }
2000:   } else {
2001:     if (set) *set = PETSC_FALSE;
2002:   }
2003:   return(0);
2004: }

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

2009:    Not Collective

2011:    Input Parameters:
2012: +  options - options database, use NULL for default global database
2013: .  pre - the string to prepend to the name or NULL
2014: .  opt - option name
2015: .  list - the possible choices (one of these must be selected, anything else is invalid)
2016: .  ntext - number of choices

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

2022:    Level: intermediate

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

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

2030:    Concepts: options database^list

2032: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2033:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2034:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2035:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2036:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2037:           PetscOptionsFList(), PetscOptionsEList()
2038: @*/
2039: PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set)
2040: {
2042:   size_t         alen,len = 0;
2043:   char           *svalue;
2044:   PetscBool      aset,flg = PETSC_FALSE;
2045:   PetscInt       i;

2049:   for (i=0; i<ntext; i++) {
2050:     PetscStrlen(list[i],&alen);
2051:     if (alen > len) len = alen;
2052:   }
2053:   len += 5; /* a little extra space for user mistypes */
2054:   PetscMalloc1(len,&svalue);
2055:   PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
2056:   if (aset) {
2057:     PetscEListFind(ntext,list,svalue,value,&flg);
2058:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
2059:     if (set) *set = PETSC_TRUE;
2060:   } else if (set) *set = PETSC_FALSE;
2061:   PetscFree(svalue);
2062:   return(0);
2063: }

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

2068:    Not Collective

2070:    Input Parameters:
2071: +  options - options database, use NULL for default global database
2072: .  pre - option prefix or NULL
2073: .  opt - option name
2074: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2075: -  defaultv - the default (current) value

2077:    Output Parameter:
2078: +  value - the  value to return
2079: -  set - PETSC_TRUE if found, else PETSC_FALSE

2081:    Level: beginner

2083:    Concepts: options database

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

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

2091: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2092:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2093:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
2094:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2095:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2096:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2097:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2098: @*/
2099: PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set)
2100: {
2102:   PetscInt       ntext = 0,tval;
2103:   PetscBool      fset;

2107:   while (list[ntext++]) {
2108:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
2109:   }
2110:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
2111:   ntext -= 3;
2112:   PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
2113:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
2114:   if (fset) *value = (PetscEnum)tval;
2115:   if (set) *set = fset;
2116:   return(0);
2117: }

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

2122:    Not Collective

2124:    Input Parameters:
2125: +  options - options database, use NULL for default global database
2126: .  pre - the string to prepend to the name or NULL
2127: -  name - the option one is seeking

2129:    Output Parameter:
2130: +  ivalue - the integer value to return
2131: -  set - PETSC_TRUE if found, else PETSC_FALSE

2133:    Level: beginner

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

2139:    Concepts: options database^has int

2141: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
2142:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2143:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
2144:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2145:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2146:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2147:           PetscOptionsFList(), PetscOptionsEList()
2148: @*/
2149: PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
2150: {
2151:   const char     *value;
2153:   PetscBool      flag;

2158:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2159:   if (flag) {
2160:     if (!value) {
2161:       if (set) *set = PETSC_FALSE;
2162:     } else {
2163:       if (set) *set = PETSC_TRUE;
2164:       PetscOptionsStringToInt(value,ivalue);
2165:     }
2166:   } else {
2167:     if (set) *set = PETSC_FALSE;
2168:   }
2169:   return(0);
2170: }

2172: /*@C
2173:    PetscOptionsGetReal - Gets the double precision value for a particular
2174:    option in the database.

2176:    Not Collective

2178:    Input Parameters:
2179: +  options - options database, use NULL for default global database
2180: .  pre - string to prepend to each name or NULL
2181: -  name - the option one is seeking

2183:    Output Parameter:
2184: +  dvalue - the double value to return
2185: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

2191:    Level: beginner

2193:    Concepts: options database^has double

2195: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2196:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
2197:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2198:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2199:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2200:           PetscOptionsFList(), PetscOptionsEList()
2201: @*/
2202: PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
2203: {
2204:   const char     *value;
2205:   PetscBool      flag;

2211:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2212:   if (flag) {
2213:     if (!value) {
2214:       if (set) *set = PETSC_FALSE;
2215:     } else {
2216:       if (set) *set = PETSC_TRUE;
2217:       PetscOptionsStringToReal(value,dvalue);
2218:     }
2219:   } else {
2220:     if (set) *set = PETSC_FALSE;
2221:   }
2222:   return(0);
2223: }

2225: /*@C
2226:    PetscOptionsGetScalar - Gets the scalar value for a particular
2227:    option in the database.

2229:    Not Collective

2231:    Input Parameters:
2232: +  options - options database, use NULL for default global database
2233: .  pre - string to prepend to each name or NULL
2234: -  name - the option one is seeking

2236:    Output Parameter:
2237: +  dvalue - the double value to return
2238: -  set - PETSC_TRUE if found, else PETSC_FALSE

2240:    Level: beginner

2242:    Usage:
2243:    A complex number 2+3i must be specified with NO spaces

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

2249:    Concepts: options database^has scalar

2251: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2252:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2253:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2254:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2255:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2256:           PetscOptionsFList(), PetscOptionsEList()
2257: @*/
2258: PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
2259: {
2260:   const char     *value;
2261:   PetscBool      flag;

2267:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2268:   if (flag) {
2269:     if (!value) {
2270:       if (set) *set = PETSC_FALSE;
2271:     } else {
2272: #if !defined(PETSC_USE_COMPLEX)
2273:       PetscOptionsStringToReal(value,dvalue);
2274: #else
2275:       PetscOptionsStringToScalar(value,dvalue);
2276: #endif
2277:       if (set) *set = PETSC_TRUE;
2278:     }
2279:   } else { /* flag */
2280:     if (set) *set = PETSC_FALSE;
2281:   }
2282:   return(0);
2283: }

2285: /*@C
2286:    PetscOptionsGetString - Gets the string value for a particular option in
2287:    the database.

2289:    Not Collective

2291:    Input Parameters:
2292: +  options - options database, use NULL for default global database
2293: .  pre - string to prepend to name or NULL
2294: .  name - the option one is seeking
2295: -  len - maximum length of the string including null termination

2297:    Output Parameters:
2298: +  string - location to copy string
2299: -  set - PETSC_TRUE if found, else PETSC_FALSE

2301:    Level: beginner

2303:    Fortran Note:
2304:    The Fortran interface is slightly different from the C/C++
2305:    interface (len is not used).  Sample usage in Fortran follows
2306: .vb
2307:       character *20    string
2308:       PetscErrorCode   ierr
2309:       PetscBool        set
2310:       call PetscOptionsGetString(PETSC_NULL_OPTIONS,PETSC_NULL_CHARACTER,'-s',string,set,ierr)
2311: .ve

2313:    Notes:
2314:     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

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

2319:    Concepts: options database^string

2321:     Note:
2322:       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).

2324: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2325:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2326:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2327:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2328:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2329:           PetscOptionsFList(), PetscOptionsEList()
2330: @*/
2331: PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set)
2332: {
2333:   const char     *value;
2334:   PetscBool      flag;

2340:   PetscOptionsFindPair(options,pre,name,&value,&flag);
2341:   if (!flag) {
2342:     if (set) *set = PETSC_FALSE;
2343:   } else {
2344:     if (set) *set = PETSC_TRUE;
2345:     if (value) {
2346:       PetscStrncpy(string,value,len);
2347:     } else {
2348:       PetscMemzero(string,len);
2349:     }
2350:   }
2351:   return(0);
2352: }

2354: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2355: {
2356:   const char     *value;
2357:   PetscBool      flag;

2361:   PetscOptionsFindPair(options,pre,name,&value,&flag);if (ierr) return(0);
2362:   if (flag) PetscFunctionReturn((char*)value);
2363:   else return(0);
2364: }

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

2371:    Not Collective

2373:    Input Parameters:
2374: +  options - options database, use NULL for default global database
2375: .  pre - string to prepend to each name or NULL
2376: .  name - the option one is seeking
2377: -  nmax - maximum number of values to retrieve

2379:    Output Parameter:
2380: +  dvalue - the integer values to return
2381: .  nmax - actual number of values retreived
2382: -  set - PETSC_TRUE if found, else PETSC_FALSE

2384:    Level: beginner

2386:    Concepts: options database^array of ints

2388:    Notes:
2389:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
2390:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

2392: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2393:           PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2394:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2395:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2396:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2397:           PetscOptionsFList(), PetscOptionsEList()
2398: @*/
2399: PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
2400: {
2401:   const char     *svalue;
2402:   char           *value;
2404:   PetscInt       n = 0;
2405:   PetscBool      flag;
2406:   PetscToken     token;


2413:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2414:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2415:   if (set) *set = PETSC_TRUE;
2416:   PetscTokenCreate(svalue,',',&token);
2417:   PetscTokenFind(token,&value);
2418:   while (value && n < *nmax) {
2419:     PetscOptionsStringToBool(value,dvalue);
2420:     PetscTokenFind(token,&value);
2421:     dvalue++;
2422:     n++;
2423:   }
2424:   PetscTokenDestroy(&token);
2425:   *nmax = n;
2426:   return(0);
2427: }

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

2432:    Not Collective

2434:    Input Parameters:
2435: +  options - options database, use NULL for default global database
2436: .  pre - option prefix or NULL
2437: .  name - option name
2438: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2439: -  nmax - maximum number of values to retrieve

2441:    Output Parameters:
2442: +  ivalue - the  enum values to return
2443: .  nmax - actual number of values retreived
2444: -  set - PETSC_TRUE if found, else PETSC_FALSE

2446:    Level: beginner

2448:    Concepts: options database

2450:    Notes:
2451:    The array must be passed as a comma separated list.

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

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

2457: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2458:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2459:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2460:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2461:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2462:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2463: @*/
2464: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum ivalue[],PetscInt *nmax,PetscBool *set)
2465: {
2466:   const char     *svalue;
2467:   char           *value;
2468:   PetscInt       n = 0;
2469:   PetscEnum      evalue;
2470:   PetscBool      flag;
2471:   PetscToken     token;


2480:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2481:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2482:   if (set) *set = PETSC_TRUE;
2483:   PetscTokenCreate(svalue,',',&token);
2484:   PetscTokenFind(token,&value);
2485:   while (value && n < *nmax) {
2486:     PetscEnumFind(list,value,&evalue,&flag);
2487:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2488:     ivalue[n++] = evalue;
2489:     PetscTokenFind(token,&value);
2490:   }
2491:   PetscTokenDestroy(&token);
2492:   *nmax = n;
2493:   return(0);
2494: }

2496: /*@C
2497:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2498:    option in the database.

2500:    Not Collective

2502:    Input Parameters:
2503: +  options - options database, use NULL for default global database
2504: .  pre - string to prepend to each name or NULL
2505: .  name - the option one is seeking
2506: -  nmax - maximum number of values to retrieve

2508:    Output Parameter:
2509: +  ivalue - the integer values to return
2510: .  nmax - actual number of values retreived
2511: -  set - PETSC_TRUE if found, else PETSC_FALSE

2513:    Level: beginner

2515:    Notes:
2516:    The array can be passed as
2517:    a comma separated list:                                 0,1,2,3,4,5,6,7
2518:    a range (start-end+1):                                  0-8
2519:    a range with given increment (start-end+1:inc):         0-7:2
2520:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

2524:    Concepts: options database^array of ints

2526: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2527:           PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2528:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2529:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2530:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2531:           PetscOptionsFList(), PetscOptionsEList()
2532: @*/
2533: PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt ivalue[],PetscInt *nmax,PetscBool *set)
2534: {
2535:   const char     *svalue;
2536:   char           *value;
2538:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2539:   size_t         len;
2540:   PetscBool      flag,foundrange;
2541:   PetscToken     token;


2548:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2549:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2550:   if (set) *set = PETSC_TRUE;
2551:   PetscTokenCreate(svalue,',',&token);
2552:   PetscTokenFind(token,&value);
2553:   while (value && n < *nmax) {
2554:     /* look for form  d-D where d and D are integers */
2555:     foundrange = PETSC_FALSE;
2556:     PetscStrlen(value,&len);
2557:     if (value[0] == '-') i=2;
2558:     else i=1;
2559:     for (;i<(int)len; i++) {
2560:       if (value[i] == '-') {
2561:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2562:         value[i] = 0;

2564:         PetscOptionsStringToInt(value,&start);
2565:         inc  = 1;
2566:         j    = i+1;
2567:         for (;j<(int)len; j++) {
2568:           if (value[j] == ':') {
2569:             value[j] = 0;

2571:             PetscOptionsStringToInt(value+j+1,&inc);
2572:             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);
2573:             break;
2574:           }
2575:         }
2576:         PetscOptionsStringToInt(value+i+1,&end);
2577:         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);
2578:         nvalues = (end-start)/inc + (end-start)%inc;
2579:         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);
2580:         for (;start<end; start+=inc) {
2581:           *ivalue = start; ivalue++;n++;
2582:         }
2583:         foundrange = PETSC_TRUE;
2584:         break;
2585:       }
2586:     }
2587:     if (!foundrange) {
2588:       PetscOptionsStringToInt(value,ivalue);
2589:       ivalue++;
2590:       n++;
2591:     }
2592:     PetscTokenFind(token,&value);
2593:   }
2594:   PetscTokenDestroy(&token);
2595:   *nmax = n;
2596:   return(0);
2597: }

2599: /*@C
2600:    PetscOptionsGetRealArray - Gets an array of double precision values for a
2601:    particular option in the database.  The values must be separated with
2602:    commas with no intervening spaces.

2604:    Not Collective

2606:    Input Parameters:
2607: +  options - options database, use NULL for default global database
2608: .  pre - string to prepend to each name or NULL
2609: .  name - the option one is seeking
2610: -  nmax - maximum number of values to retrieve

2612:    Output Parameters:
2613: +  dvalue - the double values to return
2614: .  nmax - actual number of values retreived
2615: -  set - PETSC_TRUE if found, else PETSC_FALSE

2617:    Level: beginner

2619:    Concepts: options database^array of doubles

2621: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2622:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2623:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2624:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2625:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2626:           PetscOptionsFList(), PetscOptionsEList()
2627: @*/
2628: PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
2629: {
2630:   const char     *svalue;
2631:   char           *value;
2633:   PetscInt       n = 0;
2634:   PetscBool      flag;
2635:   PetscToken     token;


2642:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2643:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2644:   if (set) *set = PETSC_TRUE;
2645:   PetscTokenCreate(svalue,',',&token);
2646:   PetscTokenFind(token,&value);
2647:   while (value && n < *nmax) {
2648:     PetscOptionsStringToReal(value,dvalue++);
2649:     PetscTokenFind(token,&value);
2650:     n++;
2651:   }
2652:   PetscTokenDestroy(&token);
2653:   *nmax = n;
2654:   return(0);
2655: }

2657: /*@C
2658:    PetscOptionsGetScalarArray - Gets an array of scalars for a
2659:    particular option in the database.  The values must be separated with
2660:    commas with no intervening spaces.

2662:    Not Collective

2664:    Input Parameters:
2665: +  options - options database, use NULL for default global database
2666: .  pre - string to prepend to each name or NULL
2667: .  name - the option one is seeking
2668: -  nmax - maximum number of values to retrieve

2670:    Output Parameters:
2671: +  dvalue - the scalar values to return
2672: .  nmax - actual number of values retreived
2673: -  set - PETSC_TRUE if found, else PETSC_FALSE

2675:    Level: beginner

2677:    Concepts: options database^array of doubles

2679: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2680:           PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2681:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2682:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2683:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2684:           PetscOptionsFList(), PetscOptionsEList()
2685: @*/
2686: PetscErrorCode PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool *set)
2687: {
2688:   const char     *svalue;
2689:   char           *value;
2691:   PetscInt       n = 0;
2692:   PetscBool      flag;
2693:   PetscToken     token;


2700:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2701:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2702:   if (set) *set = PETSC_TRUE;
2703:   PetscTokenCreate(svalue,',',&token);
2704:   PetscTokenFind(token,&value);
2705:   while (value && n < *nmax) {
2706:     PetscOptionsStringToScalar(value,dvalue++);
2707:     PetscTokenFind(token,&value);
2708:     n++;
2709:   }
2710:   PetscTokenDestroy(&token);
2711:   *nmax = n;
2712:   return(0);
2713: }

2715: /*@C
2716:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2717:    option in the database. The values must be separated with commas with
2718:    no intervening spaces.

2720:    Not Collective

2722:    Input Parameters:
2723: +  options - options database, use NULL for default global database
2724: .  pre - string to prepend to name or NULL
2725: .  name - the option one is seeking
2726: -  nmax - maximum number of strings

2728:    Output Parameter:
2729: +  strings - location to copy strings
2730: -  set - PETSC_TRUE if found, else PETSC_FALSE

2732:    Level: beginner

2734:    Notes:
2735:    The user should pass in an array of pointers to char, to hold all the
2736:    strings returned by this function.

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

2741:    Contributed by Matthew Knepley.

2743:    Concepts: options database^array of strings

2745: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2746:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2747:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2748:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2749:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2750:           PetscOptionsFList(), PetscOptionsEList()
2751: @*/
2752: PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
2753: {
2754:   const char     *svalue;
2755:   char           *value;
2757:   PetscInt       n = 0;
2758:   PetscBool      flag;
2759:   PetscToken     token;


2766:   PetscOptionsFindPair(options,pre,name,&svalue,&flag);
2767:   if (!flag || !svalue)  { if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
2768:   if (set) *set = PETSC_TRUE;
2769:   PetscTokenCreate(svalue,',',&token);
2770:   PetscTokenFind(token,&value);
2771:   while (value && n < *nmax) {
2772:     PetscStrallocpy(value,&strings[n]);
2773:     PetscTokenFind(token,&value);
2774:     n++;
2775:   }
2776:   PetscTokenDestroy(&token);
2777:   *nmax = n;
2778:   return(0);
2779: }

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

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

2786:    Not Collective

2788:    Input Parameters:
2789: +  pre - string to prepend to name or NULL
2790: .  oldname - the old, deprecated option
2791: .  newname - the new option, or NULL if option is purely removed
2792: .  version - a string describing the version of first deprecation, e.g. "3.9"
2793: -  info - additional information string, or NULL.

2795:    Options Database Keys:
2796: . -options_suppress_deprecated_warnings - do not print deprecation warnings

2798:    Notes:
2799:    Must be called between PetscOptionsBegin() and PetscOptionsEnd().
2800:    If newname is provided, the old option is replaced. Otherwise, it remains
2801:    in the options database.
2802:    If an option is not replaced, the info argument should be used to advise the user
2803:    on how to proceed.
2804:    There is a limit on the length of the warning printed, so very long strings
2805:    provided as info may be truncated.

2807:    Level: developer

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

2811: @*/
2812: PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *PetscOptionsObject,const char oldname[],const char newname[],const char version[],const char info[])
2813: {
2814:   PetscErrorCode     ierr;
2815:   PetscBool          found,quiet;
2816:   const char         *value;
2817:   const char * const quietopt="-options_suppress_deprecated_warnings";
2818:   char               msg[4096];


2824:   PetscOptionsFindPair(PetscOptionsObject->options,PetscOptionsObject->prefix,oldname,&value,&found);
2825:   if (found) {
2826:     if (newname) {
2827:       if (PetscOptionsObject->prefix) {
2828:         PetscOptionsPrefixPush(PetscOptionsObject->options,PetscOptionsObject->prefix);
2829:       }
2830:       PetscOptionsSetValue(PetscOptionsObject->options,newname,value);
2831:       if (PetscOptionsObject->prefix) {
2832:         PetscOptionsPrefixPop(PetscOptionsObject->options);
2833:       }
2834:       PetscOptionsClearValue(PetscOptionsObject->options,oldname);
2835:     }
2836:     quiet = PETSC_FALSE;
2837:     PetscOptionsGetBool(PetscOptionsObject->options,NULL,quietopt,&quiet,NULL);
2838:     if (!quiet) {
2839:       PetscStrcpy(msg,"** PETSc DEPRECATION WARNING ** : the option ");
2840:       PetscStrcat(msg,oldname);
2841:       PetscStrcat(msg," is deprecated as of version ");
2842:       PetscStrcat(msg,version);
2843:       PetscStrcat(msg," and will be removed in a future release.");
2844:       if (newname) {
2845:         PetscStrcat(msg," Please use the option ");
2846:         PetscStrcat(msg,newname);
2847:         PetscStrcat(msg," instead.");
2848:       }
2849:       if (info) {
2850:         PetscStrcat(msg," ");
2851:         PetscStrcat(msg,info);
2852:       }
2853:       PetscStrcat(msg," (Silence this warning with ");
2854:       PetscStrcat(msg,quietopt);
2855:       PetscStrcat(msg,")\n");
2856:       PetscPrintf(PetscOptionsObject->comm,msg);
2857:     }
2858:   }
2859:   return(0);
2860: }