Actual source code: options.c

petsc-master 2017-01-18
Report Typos and Errors

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

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

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

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

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

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

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

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


 57: static PetscOptions      defaultoptions = NULL;

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

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

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

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

 92:   if (tdefault)    *a = PETSC_DEFAULT;
 93:   else if (decide) *a = PETSC_DECIDE;
 94:   else if (mouse)  *a = -1;
 95:   else {
 96:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);

 98:     for (i=1; i<len; i++) {
 99:       if (name[i] < '0' || name[i] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
100:     }

102: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
103:     *a = atoll(name);
104: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
105:     *a = _atoi64(name);
106: #else
107:     *a = (PetscInt)atoi(name);
108: #endif
109:   }
110:   return(0);
111: }

113: #if defined(PETSC_USE_REAL___FLOAT128)
114: #include <quadmath.h>
115: #endif

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

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

130:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
131:   if (!tdefault) {
132:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
133:   }
134:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
135:   if (!decide) {
136:     PetscStrcasecmp(name,"DECIDE",&decide);
137:   }

139:   if (tdefault)    *a = PETSC_DEFAULT;
140:   else if (decide) *a = PETSC_DECIDE;
141:   else {
142:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
143: #if defined(PETSC_USE_REAL___FLOAT128)
144:     *a = strtoflt128(name,NULL);
145: #else
146:     *a = atof(name);
147: #endif
148:   }
149:   return(0);
150: }

152: /*
153:    Converts a string to PetscScalar value. Handles
154:       [-][2].0
155:       [-][2].0i
156:       [-][2].0+/-2.0i

158: */
159: PetscErrorCode  PetscOptionsStringToScalar(const char name[],PetscScalar *a)
160: {
162:   size_t         len;

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

168:   if (name[0] == '+') name++;
169:   if (name[0] == 'i') {
170: #if defined(PETSC_USE_COMPLEX)
171:     *a = PETSC_i;
172: #else
173:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
174: #endif
175:   } else {
176:     PetscToken token;
177:     char       *tvalue1,*tvalue2;
178:     PetscBool  neg = PETSC_FALSE, negim = PETSC_FALSE;
179:     PetscReal  re = 0.0,im = 0.0;

181:     if (name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
182:     if (name[0] == '-') {
183:       neg = PETSC_TRUE;
184:       name++;
185:     }
186:     if (name[0] == 'i') {
187: #if defined(PETSC_USE_COMPLEX)
188:       *a = -PETSC_i;
189: #else
190:      SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
191: #endif
192:       return(0);
193:     }

195:     PetscTokenCreate(name,'+',&token);
196:     PetscTokenFind(token,&tvalue1);
197:     PetscTokenFind(token,&tvalue2);
198:     if (!tvalue2) {
199:       negim = PETSC_TRUE;
200:       PetscTokenDestroy(&token);
201:       PetscTokenCreate(name,'-',&token);
202:       PetscTokenFind(token,&tvalue1);
203:       PetscTokenFind(token,&tvalue2);
204:     }
205:     if (!tvalue2) {
206:       PetscBool isim;
207:       PetscStrendswith(tvalue1,"i",&isim);
208:       if (isim) {
209:         tvalue2 = tvalue1;
210:         tvalue1 = NULL;
211:         negim   = neg;
212:       }
213:     } else {
214:       PetscBool isim;
215:       PetscStrendswith(tvalue2,"i",&isim);
216:       if (!isim) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
217:     }
218:     if (tvalue1) {
219:       PetscOptionsStringToReal(tvalue1,&re);
220:       if (neg) re = -re;
221:     }
222:     if (tvalue2) {
223:       PetscStrlen(tvalue2,&len);
224:       tvalue2[len-1] = 0;
225:       PetscOptionsStringToReal(tvalue2,&im);
226:       if (negim) im = -im;
227:     }
228:     PetscTokenDestroy(&token);
229: #if defined(PETSC_USE_COMPLEX)
230:     *a = re + im*PETSC_i;
231: #else
232:     if (im != 0.0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is complex but complex not supported ",name);
233:     *a = re;
234: #endif
235:   }
236:   return(0);
237: }

239: /*
240:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
241: */
242: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
243: {
244:   PetscBool      istrue, isfalse;
245:   size_t         len;

249:   PetscStrlen(value, &len);
250:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
251:   PetscStrcasecmp(value,"TRUE",&istrue);
252:   if (istrue) {*a = PETSC_TRUE; return(0);}
253:   PetscStrcasecmp(value,"YES",&istrue);
254:   if (istrue) {*a = PETSC_TRUE; return(0);}
255:   PetscStrcasecmp(value,"1",&istrue);
256:   if (istrue) {*a = PETSC_TRUE; return(0);}
257:   PetscStrcasecmp(value,"on",&istrue);
258:   if (istrue) {*a = PETSC_TRUE; return(0);}
259:   PetscStrcasecmp(value,"FALSE",&isfalse);
260:   if (isfalse) {*a = PETSC_FALSE; return(0);}
261:   PetscStrcasecmp(value,"NO",&isfalse);
262:   if (isfalse) {*a = PETSC_FALSE; return(0);}
263:   PetscStrcasecmp(value,"0",&isfalse);
264:   if (isfalse) {*a = PETSC_FALSE; return(0);}
265:   PetscStrcasecmp(value,"off",&isfalse);
266:   if (isfalse) {*a = PETSC_FALSE; return(0);}
267:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
268: }

270: /*@C
271:     PetscGetProgramName - Gets the name of the running program.

273:     Not Collective

275:     Input Parameter:
276: .   len - length of the string name

278:     Output Parameter:
279: .   name - the name of the running program

281:    Level: advanced

283:     Notes:
284:     The name of the program is copied into the user-provided character
285:     array of length len.  On some machines the program name includes
286:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
287: @*/
288: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
289: {

293:    PetscStrncpy(name,defaultoptions->programname,len);
294:   return(0);
295: }

297: PetscErrorCode  PetscSetProgramName(const char name[])
298: {

302:   PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);
303:   return(0);
304: }

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

309:    Input Parameter:
310: .    in_str - string to check if valid

312:    Output Parameter:
313: .    key - PETSC_TRUE if a valid key

315:   Level: intermediate

317: @*/
318: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
319: {
320:   PetscBool      inf,INF;

324:   *key = PETSC_FALSE;
325:   if (!in_str) return(0);
326:   if (in_str[0] != '-') return(0);
327:   if (in_str[1] == '-') in_str++;
328:   if (!isalpha((int)(in_str[1]))) return(0);
329:   PetscStrncmp(in_str+1,"inf",3,&inf);
330:   PetscStrncmp(in_str+1,"INF",3,&INF);
331:   if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
332:   *key = PETSC_TRUE;
333:   return(0);
334: }

336: /*@C
337:      PetscOptionsInsertString - Inserts options into the database from a string

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

342:   Input Parameter:
343: .   in_str - string that contains options separated by blanks


346:   Level: intermediate

348:   Contributed by Boyana Norris

350: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
351:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
352:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
353:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
354:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
355:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()

357: @*/
358: PetscErrorCode  PetscOptionsInsertString(PetscOptions options,const char in_str[])
359: {
360:   char           *first,*second;
362:   PetscToken     token;
363:   PetscBool      key,ispush,ispop;

366:   options = options ? options : defaultoptions;
367:   PetscTokenCreate(in_str,' ',&token);
368:   PetscTokenFind(token,&first);
369:   while (first) {
370:     PetscStrcasecmp(first,"-prefix_push",&ispush);
371:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
372:     PetscOptionsValidKey(first,&key);
373:     if (ispush) {
374:       PetscTokenFind(token,&second);
375:       PetscOptionsPrefixPush(options,second);
376:       PetscTokenFind(token,&first);
377:     } else if (ispop) {
378:       PetscOptionsPrefixPop(options);
379:       PetscTokenFind(token,&first);
380:     } else if (key) {
381:       PetscTokenFind(token,&second);
382:       PetscOptionsValidKey(second,&key);
383:       if (!key) {
384:         PetscOptionsSetValue(options,first,second);
385:         PetscTokenFind(token,&first);
386:       } else {
387:         PetscOptionsSetValue(options,first,NULL);
388:         first = second;
389:       }
390:     } else {
391:       PetscTokenFind(token,&first);
392:     }
393:   }
394:   PetscTokenDestroy(&token);
395:   return(0);
396: }

398: /*
399:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
400: */
401: static char *Petscgetline(FILE * f)
402: {
403:   size_t size  = 0;
404:   size_t len   = 0;
405:   size_t last  = 0;
406:   char   *buf  = NULL;

408:   if (feof(f)) return 0;
409:   do {
410:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
411:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
412:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
413:     end of the string, so we make sure we overwrite this */
414:     if (!fgets(buf+len,size,f)) buf[len]=0;
415:     PetscStrlen(buf,&len);
416:     last = len - 1;
417:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
418:   if (len) return buf;
419:   free(buf);
420:   return 0;
421: }


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

427:      Collective on MPI_Comm

429:   Input Parameter:
430: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
431: .   options - options database, use NULL for default global database
432: .   file - name of file
433: -   require - if PETSC_TRUE will generate an error if the file does not exist


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

438:    Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
439:    such as -log_summary or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later
440:    calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().

442:   Level: developer

444: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
445:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
446:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
447:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
448:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
449:           PetscOptionsFList(), PetscOptionsEList()

451: @*/
452: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
453: {
454:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
456:   size_t         i,len,bytes;
457:   FILE           *fd;
458:   PetscToken     token;
459:   int            err;
460:   char           cmt[1]={'#'},*cmatch;
461:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];

464:   options = options ? options : defaultoptions;
465:   MPI_Comm_rank(comm,&rank);
466:   if (!rank) {
467:     cnt        = 0;
468:     acnt       = 0;

470:     PetscFixFilename(file,fname);
471:     fd   = fopen(fname,"r");
472:     if (fd) {
473:       PetscSegBuffer vseg,aseg;
474:       PetscSegBufferCreate(1,4000,&vseg);
475:       PetscSegBufferCreate(1,2000,&aseg);

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

480:       while ((string = Petscgetline(fd))) {
481:         /* eliminate comments from each line */
482:         for (i=0; i<1; i++) {
483:           PetscStrchr(string,cmt[i],&cmatch);
484:           if (cmatch) *cmatch = 0;
485:         }
486:         PetscStrlen(string,&len);
487:         /* replace tabs, ^M, \n with " " */
488:         for (i=0; i<len; i++) {
489:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
490:             string[i] = ' ';
491:           }
492:         }
493:         PetscTokenCreate(string,' ',&token);
494:         PetscTokenFind(token,&first);
495:         if (!first) {
496:           goto destroy;
497:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
498:           PetscTokenFind(token,&first);
499:         }
500:         PetscTokenFind(token,&second);
501:         if (!first) {
502:           goto destroy;
503:         } else if (first[0] == '-') {
504:           PetscStrlen(first,&len);
505:           PetscSegBufferGet(vseg,len+1,&vstring);
506:           PetscMemcpy(vstring,first,len);
507:           vstring[len] = ' ';
508:           if (second) {
509:             PetscStrlen(second,&len);
510:             PetscSegBufferGet(vseg,len+3,&vstring);
511:             vstring[0] = '"';
512:             PetscMemcpy(vstring+1,second,len);
513:             vstring[len+1] = '"';
514:             vstring[len+2] = ' ';
515:           }
516:         } else {
517:           PetscBool match;

519:           PetscStrcasecmp(first,"alias",&match);
520:           if (match) {
521:             PetscTokenFind(token,&third);
522:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
523:             PetscStrlen(second,&len);
524:             PetscSegBufferGet(aseg,len+1,&astring);
525:             PetscMemcpy(astring,second,len);
526:             astring[len] = ' ';

528:             PetscStrlen(third,&len);
529:             PetscSegBufferGet(aseg,len+1,&astring);
530:             PetscMemcpy(astring,third,len);
531:             astring[len] = ' ';
532:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
533:         }
534: destroy:
535:         free(string);
536:         PetscTokenDestroy(&token);
537:       }
538:       err = fclose(fd);
539:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
540:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
541:       PetscMPIIntCast(bytes,&acnt);
542:       PetscSegBufferGet(aseg,1,&astring);
543:       astring[0] = 0;
544:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
545:       PetscMPIIntCast(bytes,&cnt);
546:       PetscSegBufferGet(vseg,1,&vstring);
547:       vstring[0] = 0;
548:       PetscMalloc1(2+acnt+cnt,&packed);
549:       PetscSegBufferExtractTo(aseg,packed);
550:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
551:       PetscSegBufferDestroy(&aseg);
552:       PetscSegBufferDestroy(&vseg);
553:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
554:   }

556:   counts[0] = acnt;
557:   counts[1] = cnt;
558:   MPI_Bcast(counts,2,MPI_INT,0,comm);
559:   acnt = counts[0];
560:   cnt = counts[1];
561:   if (rank) {
562:     PetscMalloc1(2+acnt+cnt,&packed);
563:   }
564:   if (acnt || cnt) {
565:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
566:     astring = packed;
567:     vstring = packed + acnt + 1;
568:   }

570:   if (acnt) {
571:     PetscToken token;
572:     char       *first,*second;

574:     PetscTokenCreate(astring,' ',&token);
575:     PetscTokenFind(token,&first);
576:     while (first) {
577:       PetscTokenFind(token,&second);
578:       PetscOptionsSetAlias(options,first,second);
579:       PetscTokenFind(token,&first);
580:     }
581:     PetscTokenDestroy(&token);
582:   }

584:   if (cnt) {
585:     PetscOptionsInsertString(options,vstring);
586:   }
587:   PetscFree(packed);
588:   return(0);
589: }

591: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
592: {
594:   int            left    = argc - 1;
595:   char           **eargs = args + 1;

598:   options = options ? options : defaultoptions;
599:   while (left) {
600:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
601:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
602:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
603:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
604:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
605:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
606:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
607:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
608:     isp4 = (PetscBool) (isp4 || tisp4);
609:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
610:     isp4 = (PetscBool) (isp4 || tisp4);
611:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
612:     PetscOptionsValidKey(eargs[0],&key);

614:     if (!key) {
615:       eargs++; left--;
616:     } else if (isoptions_file) {
617:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
618:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
619:       PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
620:       eargs += 2; left -= 2;
621:     } else if (isprefixpush) {
622:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
623:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
624:       PetscOptionsPrefixPush(options,eargs[1]);
625:       eargs += 2; left -= 2;
626:     } else if (isprefixpop) {
627:       PetscOptionsPrefixPop(options);
628:       eargs++; left--;

630:       /*
631:        These are "bad" options that MPICH, etc put on the command line
632:        we strip them out here.
633:        */
634:     } else if (tisp4 || isp4rmrank) {
635:       eargs += 1; left -= 1;
636:     } else if (isp4 || isp4yourname) {
637:       eargs += 2; left -= 2;
638:     } else {
639:       PetscBool nextiskey = PETSC_FALSE;
640:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
641:       if (left < 2 || nextiskey) {
642:         PetscOptionsSetValue(options,eargs[0],NULL);
643:         eargs++; left--;
644:       } else {
645:         PetscOptionsSetValue(options,eargs[0],eargs[1]);
646:         eargs += 2; left -= 2;
647:       }
648:     }
649:   }
650:   return(0);
651: }


654: /*@C
655:    PetscOptionsInsert - Inserts into the options database from the command line,
656:                    the environmental variable and a file.

658:    Input Parameters:
659: +  options - options database or NULL for the default global database
660: .  argc - count of number of command line arguments
661: .  args - the command line arguments
662: -  file - optional filename, defaults to ~username/.petscrc

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

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

673:    Level: advanced

675:    Concepts: options database^adding

677: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
678:           PetscInitialize()
679: @*/
680: PetscErrorCode  PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
681: {
683:   PetscMPIInt    rank;
684:   char           pfile[PETSC_MAX_PATH_LEN];
685:   PetscBool      flag = PETSC_FALSE;

687: 
689:   if (!options) {
690:     if (!defaultoptions) {
691:       PetscOptionsCreateDefault();
692:     }
693:     options = defaultoptions;
694:   }
695:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

697:   options->argc = (argc) ? *argc : 0;
698:   options->args = (args) ? *args : NULL;

700:   if (file && file[0]) {
701:     char fullpath[PETSC_MAX_PATH_LEN];

703:     PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
704:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
705:   }
706:   /*
707:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
708:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
709:   */
710:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
711:   PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
712:   if (!flag) {
713:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
714:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
715:     if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
716:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
717:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
718:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
719:   }

721:   /* insert environmental options */
722:   {
723:     char   *eoptions = 0;
724:     size_t len       = 0;
725:     if (!rank) {
726:       eoptions = (char*)getenv("PETSC_OPTIONS");
727:       PetscStrlen(eoptions,&len);
728:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
729:     } else {
730:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
731:       if (len) {
732:         PetscMalloc1(len+1,&eoptions);
733:       }
734:     }
735:     if (len) {
736:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
737:       if (rank) eoptions[len] = 0;
738:       PetscOptionsInsertString(options,eoptions);
739:       if (rank) {PetscFree(eoptions);}
740:     }
741:   }

743: #if defined(PETSC_HAVE_YAML)
744:   {
745:     char      yaml_file[PETSC_MAX_PATH_LEN];
746:     PetscBool yaml_flg;
747:     PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
748:     if (yaml_flg) {
749:       PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
750:     }
751:   }
752: #endif

754:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
755:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
756:   return(0);
757: }

759: /*@C
760:    PetscOptionsView - Prints the options that have been loaded. This is
761:    useful for debugging purposes.

763:    Logically Collective on PetscViewer

765:    Input Parameter:
766: .  viewer - must be an PETSCVIEWERASCII viewer

768:    Options Database Key:
769: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

771:    Level: advanced

773:    Concepts: options database^printing

775: .seealso: PetscOptionsAllUsed()
776: @*/
777: PetscErrorCode  PetscOptionsView(PetscOptions options,PetscViewer viewer)
778: {
780:   PetscInt       i;
781:   PetscBool      isascii;

784:   options = options ? options : defaultoptions;
785:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
786:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
787:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

789:   if (options->N) {
790:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
791:   } else {
792:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
793:   }
794:   for (i=0; i<options->N; i++) {
795:     if (options->values[i]) {
796:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
797:     } else {
798:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
799:     }
800:   }
801:   if (options->N) {
802:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
803:   }
804:   return(0);
805: }

807: /*
808:    Called by error handlers to print options used in run
809: */
810: PetscErrorCode  PetscOptionsViewError(void)
811: {
812:   PetscInt       i;
813:   PetscOptions   options = defaultoptions;

816:   if (options->N) {
817:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
818:   } else {
819:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
820:   }
821:   for (i=0; i<options->N; i++) {
822:     if (options->values[i]) {
823:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
824:     } else {
825:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
826:     }
827:   }
828:   return(0);
829: }

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

834:    Not Collective

836:    Input Paramter:
837: .  options - the options database, use NULL for the default global database

839:    Output Parameter:
840: .  copts - pointer where string pointer is stored

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

844:    Level: advanced

846:    Concepts: options database^listing

848: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
849: @*/
850: PetscErrorCode  PetscOptionsGetAll(PetscOptions options,char *copts[])
851: {
853:   PetscInt       i;
854:   size_t         len       = 1,lent = 0;
855:   char           *coptions = NULL;

858:   options = options ? options : defaultoptions;

860:   /* count the length of the required string */
861:   for (i=0; i<options->N; i++) {
862:     PetscStrlen(options->names[i],&lent);
863:     len += 2 + lent;
864:     if (options->values[i]) {
865:       PetscStrlen(options->values[i],&lent);
866:       len += 1 + lent;
867:     }
868:   }
869:   PetscMalloc1(len,&coptions);
870:   coptions[0] = 0;
871:   for (i=0; i<options->N; i++) {
872:     PetscStrcat(coptions,"-");
873:     PetscStrcat(coptions,options->names[i]);
874:     PetscStrcat(coptions," ");
875:     if (options->values[i]) {
876:       PetscStrcat(coptions,options->values[i]);
877:       PetscStrcat(coptions," ");
878:     }
879:   }
880:   *copts = coptions;
881:   return(0);
882: }

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

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

889:    Input Parameter:
890: +  options - options database, or NULL for the default global database
891: -  prefix - The string to append to the existing prefix

893:    Options Database Keys:
894:  +   -prefix_push <some_prefix_> - push the given prefix
895:  -   -prefix_pop - pop the last prefix

897:    Notes:
898:    It is common to use this in conjunction with -options_file as in

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

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

904: Level: advanced

906: .seealso: PetscOptionsPrefixPop()
907: @*/
908: PetscErrorCode  PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
909: {
911:   size_t         n;
912:   PetscInt       start;
913:   char           buf[2048];
914:   PetscBool      key;

918:   options = options ? options : defaultoptions;
919:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
920:   buf[0] = '-';
921:   PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
922:   buf[sizeof(buf) - 1] = 0;
923:   PetscOptionsValidKey(buf,&key);
924:   if (!key) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Given prefix \"%s\" not valid (the first character must be a letter, do not include leading '-')",prefix);

926:   if (!options) {
927:     PetscOptionsInsert(NULL,0,0,0);
928:     options = defaultoptions;
929:   }
930:   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);
931:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
932:   PetscStrlen(prefix,&n);
933:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
934:   PetscMemcpy(options->prefix+start,prefix,n+1);
935:   options->prefixstack[options->prefixind++] = start+n;
936:   return(0);
937: }

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

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

944:   Input Parameters:
945: .  options - options database, or NULL for the default global database

947:    Level: advanced

949: .seealso: PetscOptionsPrefixPush()
950: @*/
951: PetscErrorCode  PetscOptionsPrefixPop(PetscOptions options)
952: {
953:   PetscInt offset;

956:   options = options ? options : defaultoptions;
957:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
958:   options->prefixind--;
959:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
960:   options->prefix[offset] = 0;
961:   return(0);
962: }

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

967:   Input Parameters:
968: .  options - options database, use NULL for the default global database

970:    Level: developer

972: .seealso: PetscOptionsInsert()
973: @*/
974: PetscErrorCode  PetscOptionsClear(PetscOptions options)
975: {
976:   PetscInt     i;

979:   options = options ? options : defaultoptions;
980:   for (i=0; i<options->N; i++) {
981:     if (options->names[i])  free(options->names[i]);
982:     if (options->values[i]) free(options->values[i]);
983:   }
984:   for (i=0; i<options->Naliases; i++) {
985:     free(options->aliases1[i]);
986:     free(options->aliases2[i]);
987:   }
988:   options->prefix[0] = 0;
989:   options->prefixind = 0;
990:   options->N         = 0;
991:   options->Naliases  = 0;
992:   return(0);
993: }

995: /*@
996:     PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options

998:   Input Parameters:
999: .  obj  - the PetscObject

1001:    Level: developer

1003:    Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by 
1004:     PCBJACOBI from all printing the same help messages to the screen

1006: .seealso: PetscOptionsInsert()
1007: @*/
1008: PetscErrorCode  PetscObjectSetPrintedOptions(PetscObject obj)
1009: {
1011:   obj->optionsprinted = PETSC_TRUE;
1012:   return(0);
1013: }

1015: /*@
1016:     PetscObjectInheritPrintedOptions - If the child object is not on the rank 0 process of the parent object and the child is sequential then the child gets it set.

1018:   Input Parameters:
1019: +  pobj - the parent object
1020: -  obj  - the PetscObject

1022:    Level: developer

1024:    Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by 
1025:     PCBJACOBI from all printing the same help messages to the screen

1027:     This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap

1029: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1030: @*/
1031: PetscErrorCode  PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1032: {
1034:   PetscMPIInt    prank,size;

1037:   MPI_Comm_rank(pobj->comm,&prank);
1038:   MPI_Comm_size(obj->comm,&size);
1039:   if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
1040:   return(0);
1041: }

1043: /*@
1044:     PetscOptionsDestroy - Destroys an option database.

1046:   Input Parameter:
1047: .  options - the PetscOptions object

1049:    Level: developer

1051: .seealso: PetscOptionsInsert()
1052: @*/
1053: PetscErrorCode  PetscOptionsDestroy(PetscOptions *options)
1054: {

1058:   PetscOptionsClear(*options);
1059:   free(*options);
1060:   *options = NULL;
1061:   return(0);
1062: }

1064: PetscErrorCode  PetscOptionsDestroyDefault(void)
1065: {

1068:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1069:   return 0;
1070: }


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

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

1080:    Input Parameters:
1081: +  options - options database, use NULL for the default global database
1082: .  name - name of option, this SHOULD have the - prepended
1083: -  value - the option value (not used for all options)

1085:    Level: intermediate

1087:    Note:
1088:    This function can be called BEFORE PetscInitialize()

1090:    Only some options have values associated with them, such as
1091:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

1093:   Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized

1095:   Concepts: options database^adding option

1097: .seealso: PetscOptionsInsert()
1098: @*/
1099: PetscErrorCode  PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1100: {
1101:   size_t         len;
1103:   PetscInt       N,n,i;
1104:   char           **names;
1105:   char           fullname[2048];
1106:   const char     *name = iname;
1107:   int            match;

1109:   if (!options) {
1110:     if (!defaultoptions) {
1111:       PetscOptionsCreateDefault();
1112:       if (ierr) return ierr;
1113:     }
1114:     options = defaultoptions;
1115:   }

1117:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
1118:   match = strcmp(name,"-h");
1119:   if (!match) name = "-help";

1121:   name++; /* skip starting hyphen */
1122:   if (options->prefixind > 0) {
1123:     strncpy(fullname,options->prefix,sizeof(fullname));
1124:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1125:     name = fullname;
1126:   }

1128:   /* check against aliases */
1129:   N = options->Naliases;
1130:   for (i=0; i<N; i++) {
1131: #if defined(PETSC_HAVE_STRCASECMP)
1132:     match = strcasecmp(options->aliases1[i],name);
1133: #elif defined(PETSC_HAVE_STRICMP)
1134:     match = stricmp(options->aliases1[i],name);
1135: #else
1136:     Error
1137: #endif
1138:     if (!match) {
1139:       name = options->aliases2[i];
1140:       break;
1141:     }
1142:   }

1144:   N     = options->N;
1145:   n     = N;
1146:   names = options->names;

1148:   for (i=0; i<N; i++) {
1149: #if defined(PETSC_HAVE_STRCASECMP)
1150:     match = strcasecmp(names[i],name);
1151: #elif defined(PETSC_HAVE_STRICMP)
1152:     match = stricmp(names[i],name);
1153: #else
1154:     Error
1155: #endif
1156:     if (!match) {
1157:       if (options->values[i]) free(options->values[i]);
1158:       len = value ? strlen(value) : 0;
1159:       if (len) {
1160:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
1161:         if (!options->values[i]) return PETSC_ERR_MEM;
1162:         strcpy(options->values[i],value);
1163:       } else options->values[i] = 0;
1164:       return 0;
1165:     } else if (strcmp(names[i],name) > 0) {
1166:       n = i;
1167:       break;
1168:     }
1169:   }
1170:   if (N >= MAXOPTIONS) abort();

1172:   /* shift remaining values down 1 */
1173:   for (i=N; i>n; i--) {
1174:     options->names[i]  = options->names[i-1];
1175:     options->values[i] = options->values[i-1];
1176:     options->used[i]   = options->used[i-1];
1177:   }
1178:   /* insert new name and value */
1179:   len = strlen(name);
1180:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
1181:   if (!options->names[n]) return PETSC_ERR_MEM;
1182:   strcpy(options->names[n],name);
1183:   len = value ? strlen(value) : 0;
1184:   if (len) {
1185:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
1186:     if (!options->values[n]) return PETSC_ERR_MEM;
1187:     strcpy(options->values[n],value);
1188:   } else options->values[n] = NULL;
1189:   options->used[n] = PETSC_FALSE;
1190:   options->N++;
1191:   return 0;
1192: }

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

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

1201:    Input Parameter:
1202: +  options - options database, use NULL for the default global database
1203: .  name - name of option, this SHOULD have the - prepended

1205:    Level: intermediate

1207:    Concepts: options database^removing option
1208: .seealso: PetscOptionsInsert()
1209: @*/
1210: PetscErrorCode  PetscOptionsClearValue(PetscOptions options,const char iname[])
1211: {
1213:   PetscInt       N,n,i;
1214:   char           **names,*name=(char*)iname;
1215:   PetscBool      gt,match;

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

1222:   N     = options->N; n = 0;
1223:   names = options->names;

1225:   for (i=0; i<N; i++) {
1226:     PetscStrcasecmp(names[i],name,&match);
1227:     PetscStrgrt(names[i],name,&gt);
1228:     if (match) {
1229:       if (options->names[i])  free(options->names[i]);
1230:       if (options->values[i]) free(options->values[i]);
1231:       PetscOptionsMonitor(name,"");
1232:       break;
1233:     } else if (gt) return(0); /* it was not listed */

1235:     n++;
1236:   }
1237:   if (n == N) return(0); /* it was not listed */

1239:   /* shift remaining values down 1 */
1240:   for (i=n; i<N-1; i++) {
1241:     options->names[i]  = options->names[i+1];
1242:     options->values[i] = options->values[i+1];
1243:     options->used[i]   = options->used[i+1];
1244:   }
1245:   options->N--;
1246:   return(0);
1247: }

1249: /*@C
1250:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1255:    Input Parameters:
1256: +  options - options database or NULL for default global database
1257: .  inewname - the alias
1258: -  ioldname - the name that alias will refer to

1260:    Level: advanced

1262: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1263:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1264:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1265:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1266:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1267:           PetscOptionsFList(), PetscOptionsEList()
1268: @*/
1269: PetscErrorCode  PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1270: {
1272:   PetscInt       n = options->Naliases;
1273:   size_t         len;
1274:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

1277:   options = options ? options : defaultoptions;
1278:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1279:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1280:   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);

1282:   newname++; oldname++;
1283:   PetscStrlen(newname,&len);
1284:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1285:   PetscStrcpy(options->aliases1[n],newname);
1286:   PetscStrlen(oldname,&len);
1287:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1288:   PetscStrcpy(options->aliases2[n],oldname);
1289:   options->Naliases++;
1290:   return(0);
1291: }

1293: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool  *flg)
1294: {
1296:   PetscInt       i,N;
1297:   size_t         len;
1298:   char           **names,tmp[256];
1299:   PetscBool      match;

1302:   options = options ? options : defaultoptions;
1303:   N     = options->N;
1304:   names = options->names;

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

1308:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1309:   if (pre) {
1310:     char       *ptr   = tmp;
1311:     const char *namep = name;
1312:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1313:     if (name[1] == '-') {
1314:       *ptr++ = '-';
1315:       namep++;
1316:     }
1317:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1318:     tmp[sizeof(tmp)-1] = 0;
1319:     PetscStrlen(tmp,&len);
1320:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1321:   } else {
1322:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1323:     tmp[sizeof(tmp)-1] = 0;
1324:   }
1325: #if defined(PETSC_USE_DEBUG)
1326:   {
1327:     PetscBool valid;
1328:     char      key[sizeof(tmp)+1] = "-";

1330:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1331:     PetscOptionsValidKey(key,&valid);
1332:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1333:   }
1334: #endif

1336:   /* slow search */
1337:   *flg = PETSC_FALSE;
1338:   for (i=0; i<N; i++) {
1339:     PetscStrcasecmp(names[i],tmp,&match);
1340:     if (match) {
1341:       *value           = options->values[i];
1342:       options->used[i] = PETSC_TRUE;
1343:       *flg             = PETSC_TRUE;
1344:       break;
1345:     }
1346:   }
1347:   if (!*flg) {
1348:     PetscInt j,cnt = 0,locs[16],loce[16];
1349:     size_t   n;
1350:     PetscStrlen(tmp,&n);
1351:     /* determine the location and number of all _%d_ in the key */
1352:     for (i=0; i< (PetscInt)n; i++) {
1353:       if (tmp[i] == '_') {
1354:         for (j=i+1; j< (PetscInt)n; j++) {
1355:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1356:           if (tmp[j] == '_' && j > i+1) { /* found a number */
1357:             locs[cnt]   = i+1;
1358:             loce[cnt++] = j+1;
1359:           }
1360:           break;
1361:         }
1362:       }
1363:     }
1364:     if (cnt) {
1365:       char tmp2[256];
1366:       for (i=0; i<cnt; i++) {
1367:         PetscStrcpy(tmp2,"-");
1368:         PetscStrncat(tmp2,tmp,locs[i]);
1369:         PetscStrcat(tmp2,tmp+loce[i]);
1370:         PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
1371:         if (*flg) break;
1372:       }
1373:     }
1374:   }
1375:   return(0);
1376: }

1378: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
1379: {
1381:   PetscInt       i,N;
1382:   size_t         len;
1383:   char           **names,tmp[256];
1384:   PetscBool      match;

1387:   options = options ? options : defaultoptions;
1388:   N     = options->N;
1389:   names = options->names;

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

1393:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1394:   if (pre) {
1395:     char       *ptr   = tmp;
1396:     const char *namep = name;
1397:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1398:     if (name[1] == '-') {
1399:       *ptr++ = '-';
1400:       namep++;
1401:     }
1402:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1403:     tmp[sizeof(tmp)-1] = 0;
1404:     PetscStrlen(tmp,&len);
1405:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1406:   } else {
1407:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1408:     tmp[sizeof(tmp)-1] = 0;
1409:   }
1410: #if defined(PETSC_USE_DEBUG)
1411:   {
1412:     PetscBool valid;
1413:     char      key[sizeof(tmp)+1] = "-";

1415:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1416:     PetscOptionsValidKey(key,&valid);
1417:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1418:   }
1419: #endif

1421:   /* slow search */
1422:   *flg = PETSC_FALSE;
1423:   PetscStrlen(tmp,&len);
1424:   for (i = 0; i < N; ++i) {
1425:     PetscStrncmp(names[i], tmp, len, &match);
1426:     if (match) {
1427:       if (value) *value = options->values[i];
1428:       options->used[i]  = PETSC_TRUE;
1429:       if (flg)   *flg   = PETSC_TRUE;
1430:       break;
1431:     }
1432:   }
1433:   return(0);
1434: }

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

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

1442:    Input Parameters:
1443: +  options - options database use NULL for default global database
1444: .  name - the option one is seeking
1445: -  mess - error message (may be NULL)

1447:    Level: advanced

1449:    Concepts: options database^rejecting option

1451: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1452:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1453:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1454:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1455:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1456:           PetscOptionsFList(), PetscOptionsEList()
1457: @*/
1458: PetscErrorCode  PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
1459: {
1461:   PetscBool      flag = PETSC_FALSE;

1464:   options = options ? options : defaultoptions;
1465:   PetscOptionsHasName(options,NULL,name,&flag);
1466:   if (flag) {
1467:     if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1468:     else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1469:   }
1470:   return(0);
1471: }

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

1477:    Not Collective

1479:    Input Parameters:
1480: +  options - options database use NULL for default global database
1481: .  name - the option one is seeking
1482: -  pre - string to prepend to the name or NULL

1484:    Output Parameters:
1485: .  set - PETSC_TRUE if found else PETSC_FALSE.

1487:    Level: beginner

1489:    Concepts: options database^has option name

1491:    Notes: Name cannot be simply -h

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

1495: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1496:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1497:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1498:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1499:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1500:           PetscOptionsFList(), PetscOptionsEList()
1501: @*/
1502: PetscErrorCode  PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool  *set)
1503: {
1504:   char           *value;
1506:   PetscBool      flag;

1509:   options = options ? options : defaultoptions;
1510:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1511:   if (set) *set = flag;
1512:   return(0);
1513: }

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

1518:    Not Collective

1520:    Input Parameters:
1521: +  options - options database use NULL for default global database
1522: .  pre - the string to prepend to the name or NULL
1523: -  name - the option one is seeking

1525:    Output Parameter:
1526: +  ivalue - the integer value to return
1527: -  set - PETSC_TRUE if found, else PETSC_FALSE

1529:    Level: beginner

1531:    Concepts: options database^has int

1533: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1534:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1535:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1536:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1537:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1538:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1539:           PetscOptionsFList(), PetscOptionsEList()
1540: @*/
1541: PetscErrorCode  PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool  *set)
1542: {
1543:   char           *value;
1545:   PetscBool      flag;

1550:   options = options ? options : defaultoptions;
1551:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1552:   if (flag) {
1553:     if (!value) {
1554:       if (set) *set = PETSC_FALSE;
1555:     } else {
1556:       if (set) *set = PETSC_TRUE;
1557:       PetscOptionsStringToInt(value,ivalue);
1558:     }
1559:   } else {
1560:     if (set) *set = PETSC_FALSE;
1561:   }
1562:   return(0);
1563: }

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

1568:    Not Collective

1570:    Input Parameters:
1571: +  options - options database use NULL for default global database
1572: .  pre - the string to prepend to the name or NULL
1573: .  opt - option name
1574: .  list - the possible choices (one of these must be selected, anything else is invalid)
1575: .  ntext - number of choices

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

1581:    Level: intermediate

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

1585:    Concepts: options database^list

1587: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1588:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1589:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1590:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1591:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1592:           PetscOptionsFList(), PetscOptionsEList()
1593: @*/
1594: PetscErrorCode  PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool  *set)
1595: {
1597:   size_t         alen,len = 0;
1598:   char           *svalue;
1599:   PetscBool      aset,flg = PETSC_FALSE;
1600:   PetscInt       i;

1603:   options = options ? options : defaultoptions;
1604:   for (i=0; i<ntext; i++) {
1605:     PetscStrlen(list[i],&alen);
1606:     if (alen > len) len = alen;
1607:   }
1608:   len += 5; /* a little extra space for user mistypes */
1609:   PetscMalloc1(len,&svalue);
1610:   PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
1611:   if (aset) {
1612:     PetscEListFind(ntext,list,svalue,value,&flg);
1613:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1614:     if (set) *set = PETSC_TRUE;
1615:   } else if (set) *set = PETSC_FALSE;
1616:   PetscFree(svalue);
1617:   return(0);
1618: }

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

1623:    Not Collective

1625:    Input Parameters:
1626: +  options - options database use NULL for default global database
1627: .  pre - option prefix or NULL
1628: .  opt - option name
1629: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1630: -  defaultv - the default (current) value

1632:    Output Parameter:
1633: +  value - the  value to return
1634: -  set - PETSC_TRUE if found, else PETSC_FALSE

1636:    Level: beginner

1638:    Concepts: options database

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

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

1644: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1645:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1646:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1647:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1648:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1649:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1650:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1651: @*/
1652: PetscErrorCode  PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool  *set)
1653: {
1655:   PetscInt       ntext = 0,tval;
1656:   PetscBool      fset;

1659:   options = options ? options : defaultoptions;
1660:   while (list[ntext++]) {
1661:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1662:   }
1663:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1664:   ntext -= 3;
1665:   PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
1666:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1667:   if (fset) *value = (PetscEnum)tval;
1668:   if (set) *set = fset;
1669:   return(0);
1670: }

1672: /*@C
1673:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1674:             option in the database.

1676:    Not Collective

1678:    Input Parameters:
1679: +  options - options database use NULL for default global database
1680: .  pre - the string to prepend to the name or NULL
1681: -  name - the option one is seeking

1683:    Output Parameter:
1684: +  ivalue - the logical value to return
1685: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1687:    Level: beginner

1689:    Notes:
1690:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1691:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1696:    Concepts: options database^has logical

1698: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1699:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1700:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1701:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1702:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1703:           PetscOptionsFList(), PetscOptionsEList()
1704: @*/
1705: PetscErrorCode  PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
1706: {
1707:   char           *value;
1708:   PetscBool      flag;

1714:   options = options ? options : defaultoptions;
1715:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1716:   if (flag) {
1717:     if (set) *set = PETSC_TRUE;
1718:     if (!value) {
1719:       if (ivalue) *ivalue = PETSC_TRUE;
1720:     } else {
1721:       PetscOptionsStringToBool(value, ivalue);
1722:     }
1723:   } else {
1724:     if (set) *set = PETSC_FALSE;
1725:   }
1726:   return(0);
1727: }

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

1734:    Not Collective

1736:    Input Parameters:
1737: +  options - options database use NULL for default global database
1738: .  pre - string to prepend to each name or NULL
1739: .  name - the option one is seeking
1740: -  nmax - maximum number of values to retrieve

1742:    Output Parameter:
1743: +  dvalue - the integer values to return
1744: .  nmax - actual number of values retreived
1745: -  set - PETSC_TRUE if found, else PETSC_FALSE

1747:    Level: beginner

1749:    Concepts: options database^array of ints

1751:    Notes:
1752:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1753:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1755: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1756:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1757:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1758:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1759:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1760:           PetscOptionsFList(), PetscOptionsEList()
1761: @*/
1762: PetscErrorCode  PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
1763: {
1764:   char           *value;
1766:   PetscInt       n = 0;
1767:   PetscBool      flag;
1768:   PetscToken     token;

1773:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1774:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1775:   if (!value) {if (set) *set = PETSC_TRUE;  *nmax = 0; return(0);}

1777:   if (set) *set = PETSC_TRUE;

1779:   PetscTokenCreate(value,',',&token);
1780:   PetscTokenFind(token,&value);
1781:   while (n < *nmax) {
1782:     if (!value) break;
1783:     PetscOptionsStringToBool(value,dvalue);
1784:     PetscTokenFind(token,&value);
1785:     dvalue++;
1786:     n++;
1787:   }
1788:   PetscTokenDestroy(&token);
1789:   *nmax = n;
1790:   return(0);
1791: }

1793: /*@C
1794:    PetscOptionsGetReal - Gets the double precision value for a particular
1795:    option in the database.

1797:    Not Collective

1799:    Input Parameters:
1800: +  options - options database use NULL for default global database
1801: .  pre - string to prepend to each name or NULL
1802: -  name - the option one is seeking

1804:    Output Parameter:
1805: +  dvalue - the double value to return
1806: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

1810:    Level: beginner

1812:    Concepts: options database^has double

1814: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1815:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1816:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1817:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1818:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1819:           PetscOptionsFList(), PetscOptionsEList()
1820: @*/
1821: PetscErrorCode  PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
1822: {
1823:   char           *value;
1825:   PetscBool      flag;

1830:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1831:   if (flag) {
1832:     if (!value) {
1833:       if (set) *set = PETSC_FALSE;
1834:     } else {
1835:       if (set) *set = PETSC_TRUE;
1836:       PetscOptionsStringToReal(value,dvalue);
1837:     }
1838:   } else {
1839:     if (set) *set = PETSC_FALSE;
1840:   }
1841:   return(0);
1842: }

1844: /*@C
1845:    PetscOptionsGetScalar - Gets the scalar value for a particular
1846:    option in the database.

1848:    Not Collective

1850:    Input Parameters:
1851: +  options - options database use NULL for default global database
1852: .  pre - string to prepend to each name or NULL
1853: -  name - the option one is seeking

1855:    Output Parameter:
1856: +  dvalue - the double value to return
1857: -  set - PETSC_TRUE if found, else PETSC_FALSE

1859:    Level: beginner

1861:    Usage:
1862:    A complex number 2+3i must be specified with NO spaces

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

1866:    Concepts: options database^has scalar

1868: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1869:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1870:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1871:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1872:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1873:           PetscOptionsFList(), PetscOptionsEList()
1874: @*/
1875: PetscErrorCode  PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
1876: {
1877:   char           *value;
1878:   PetscBool      flag;

1884:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1885:   if (flag) {
1886:     if (!value) {
1887:       if (set) *set = PETSC_FALSE;
1888:     } else {
1889: #if !defined(PETSC_USE_COMPLEX)
1890:       PetscOptionsStringToReal(value,dvalue);
1891: #else
1892:       PetscOptionsStringToScalar(value,dvalue);
1893: #endif
1894:       if (set) *set = PETSC_TRUE;
1895:     }
1896:   } else { /* flag */
1897:     if (set) *set = PETSC_FALSE;
1898:   }
1899:   return(0);
1900: }

1902: /*@C
1903:    PetscOptionsGetRealArray - Gets an array of double precision values for a
1904:    particular option in the database.  The values must be separated with
1905:    commas with no intervening spaces.

1907:    Not Collective

1909:    Input Parameters:
1910: +  options - options database use NULL for default global database
1911: .  pre - string to prepend to each name or NULL
1912: .  name - the option one is seeking
1913: -  nmax - maximum number of values to retrieve

1915:    Output Parameters:
1916: +  dvalue - the double values to return
1917: .  nmax - actual number of values retreived
1918: -  set - PETSC_TRUE if found, else PETSC_FALSE

1920:    Level: beginner

1922:    Concepts: options database^array of doubles

1924: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1925:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1926:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1927:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1928:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1929:           PetscOptionsFList(), PetscOptionsEList()
1930: @*/
1931: PetscErrorCode  PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool  *set)
1932: {
1933:   char           *value;
1935:   PetscInt       n = 0;
1936:   PetscBool      flag;
1937:   PetscToken     token;

1942:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1943:   if (!flag) {
1944:     if (set) *set = PETSC_FALSE;
1945:     *nmax = 0;
1946:     return(0);
1947:   }
1948:   if (!value) {
1949:     if (set) *set = PETSC_TRUE;
1950:     *nmax = 0;
1951:     return(0);
1952:   }

1954:   if (set) *set = PETSC_TRUE;

1956:   PetscTokenCreate(value,',',&token);
1957:   PetscTokenFind(token,&value);
1958:   while (n < *nmax) {
1959:     if (!value) break;
1960:     PetscOptionsStringToReal(value,dvalue++);
1961:     PetscTokenFind(token,&value);
1962:     n++;
1963:   }
1964:   PetscTokenDestroy(&token);
1965:   *nmax = n;
1966:   return(0);
1967: }

1969: /*@C
1970:    PetscOptionsGetScalarArray - Gets an array of scalars for a
1971:    particular option in the database.  The values must be separated with
1972:    commas with no intervening spaces.

1974:    Not Collective

1976:    Input Parameters:
1977: +  options - options database use NULL for default global database
1978: .  pre - string to prepend to each name or NULL
1979: .  name - the option one is seeking
1980: -  nmax - maximum number of values to retrieve

1982:    Output Parameters:
1983: +  dvalue - the scalar values to return
1984: .  nmax - actual number of values retreived
1985: -  set - PETSC_TRUE if found, else PETSC_FALSE

1987:    Level: beginner

1989:    Concepts: options database^array of doubles

1991: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1992:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1993:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1994:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1995:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1996:           PetscOptionsFList(), PetscOptionsEList()
1997: @*/
1998: PetscErrorCode  PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
1999: {
2000:   char           *value;
2002:   PetscInt       n = 0;
2003:   PetscBool      flag;
2004:   PetscToken     token;

2009:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2010:   if (!flag) {
2011:     if (set) *set = PETSC_FALSE;
2012:     *nmax = 0;
2013:     return(0);
2014:   }
2015:   if (!value) {
2016:     if (set) *set = PETSC_TRUE;
2017:     *nmax = 0;
2018:     return(0);
2019:   }

2021:   if (set) *set = PETSC_TRUE;

2023:   PetscTokenCreate(value,',',&token);
2024:   PetscTokenFind(token,&value);
2025:   while (n < *nmax) {
2026:     if (!value) break;
2027:     PetscOptionsStringToScalar(value,dvalue++);
2028:     PetscTokenFind(token,&value);
2029:     n++;
2030:   }
2031:   PetscTokenDestroy(&token);
2032:   *nmax = n;
2033:   return(0);
2034: }

2036: /*@C
2037:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2038:    option in the database.

2040:    Not Collective

2042:    Input Parameters:
2043: +  options - options database use NULL for default global database
2044: .  pre - string to prepend to each name or NULL
2045: .  name - the option one is seeking
2046: -  nmax - maximum number of values to retrieve

2048:    Output Parameter:
2049: +  dvalue - the integer values to return
2050: .  nmax - actual number of values retreived
2051: -  set - PETSC_TRUE if found, else PETSC_FALSE

2053:    Level: beginner

2055:    Notes:
2056:    The array can be passed as
2057:    a comma separated list:                                 0,1,2,3,4,5,6,7
2058:    a range (start-end+1):                                  0-8
2059:    a range with given increment (start-end+1:inc):         0-7:2
2060:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

2064:    Concepts: options database^array of ints

2066: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2067:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2068:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2069:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2070:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2071:           PetscOptionsFList(), PetscOptionsEList()
2072: @*/
2073: PetscErrorCode  PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
2074: {
2075:   char           *value;
2077:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2078:   size_t         len;
2079:   PetscBool      flag,foundrange;
2080:   PetscToken     token;

2085:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2086:   if (!flag) {
2087:     if (set) *set = PETSC_FALSE;
2088:     *nmax = 0;
2089:     return(0);
2090:   }
2091:   if (!value) {
2092:     if (set) *set = PETSC_TRUE;
2093:     *nmax = 0;
2094:     return(0);
2095:   }

2097:   if (set) *set = PETSC_TRUE;

2099:   PetscTokenCreate(value,',',&token);
2100:   PetscTokenFind(token,&value);
2101:   while (n < *nmax) {
2102:     if (!value) break;

2104:     /* look for form  d-D where d and D are integers */
2105:     foundrange = PETSC_FALSE;
2106:     PetscStrlen(value,&len);
2107:     if (value[0] == '-') i=2;
2108:     else i=1;
2109:     for (;i<(int)len; i++) {
2110:       if (value[i] == '-') {
2111:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2112:         value[i] = 0;

2114:         PetscOptionsStringToInt(value,&start);
2115:         inc  = 1;
2116:         j    = i+1;
2117:         for (;j<(int)len; j++) {
2118:           if (value[j] == ':') {
2119:             value[j] = 0;

2121:             PetscOptionsStringToInt(value+j+1,&inc);
2122:             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);
2123:             break;
2124:           }
2125:         }
2126:         PetscOptionsStringToInt(value+i+1,&end);
2127:         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);
2128:         nvalues = (end-start)/inc + (end-start)%inc;
2129:         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);
2130:         for (;start<end; start+=inc) {
2131:           *dvalue = start; dvalue++;n++;
2132:         }
2133:         foundrange = PETSC_TRUE;
2134:         break;
2135:       }
2136:     }
2137:     if (!foundrange) {
2138:       PetscOptionsStringToInt(value,dvalue);
2139:       dvalue++;
2140:       n++;
2141:     }
2142:     PetscTokenFind(token,&value);
2143:   }
2144:   PetscTokenDestroy(&token);
2145:   *nmax = n;
2146:   return(0);
2147: }

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

2152:    Not Collective

2154:    Input Parameters:
2155: +  options - options database use NULL for default global database
2156: .  pre - option prefix or NULL
2157: .  name - option name
2158: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2159: -  nmax - maximum number of values to retrieve

2161:    Output Parameters:
2162: +  dvalue - the  enum values to return
2163: .  nmax - actual number of values retreived
2164: -  set - PETSC_TRUE if found, else PETSC_FALSE

2166:    Level: beginner

2168:    Concepts: options database

2170:    Notes:
2171:    The array must be passed as a comma separated list.

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

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

2177: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2178:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2179:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2180:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2181:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2182:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2183: @*/
2184: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2185: {
2186:   char           *svalue;
2187:   PetscInt       n = 0;
2188:   PetscEnum      evalue;
2189:   PetscBool      flag;
2190:   PetscToken     token;


2199:   PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2200:   if (!flag) {
2201:     if (set) *set = PETSC_FALSE;
2202:     *nmax = 0;
2203:     return(0);
2204:   }
2205:   if (!svalue) {
2206:     if (set) *set = PETSC_TRUE;
2207:     *nmax = 0;
2208:     return(0);
2209:   }
2210:   if (set) *set = PETSC_TRUE;

2212:   PetscTokenCreate(svalue,',',&token);
2213:   PetscTokenFind(token,&svalue);
2214:   while (svalue && n < *nmax) {
2215:     PetscEnumFind(list,svalue,&evalue,&flag);
2216:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2217:     dvalue[n++] = evalue;
2218:     PetscTokenFind(token,&svalue);
2219:   }
2220:   *nmax = n;
2221:   PetscTokenDestroy(&token);
2222:   return(0);
2223: }

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

2229:    Not Collective

2231:    Input Parameters:
2232: +  options - options database use NULL for default global database
2233: .  pre - string to prepend to name or NULL
2234: .  name - the option one is seeking
2235: -  len - maximum length of the string including null termination

2237:    Output Parameters:
2238: +  string - location to copy string
2239: -  set - PETSC_TRUE if found, else PETSC_FALSE

2241:    Level: beginner

2243:    Fortran Note:
2244:    The Fortran interface is slightly different from the C/C++
2245:    interface (len is not used).  Sample usage in Fortran follows
2246: .vb
2247:       character *20    string
2248:       PetscErrorCode   ierr
2249:       PetscBool        set
2250:       call PetscOptionsGetString(PETSC_NULL_OPTIONS,PETSC_NULL_CHARACTER,'-s',string,set,ierr)
2251: .ve

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

2255:    Concepts: options database^string

2257:     Note:
2258:       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).

2260: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2261:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2262:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2263:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2264:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2265:           PetscOptionsFList(), PetscOptionsEList()
2266: @*/
2267: PetscErrorCode  PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
2268: {
2269:   char           *value;
2271:   PetscBool      flag;

2276:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2277:   if (!flag) {
2278:     if (set) *set = PETSC_FALSE;
2279:   } else {
2280:     if (set) *set = PETSC_TRUE;
2281:     if (value) {
2282:       PetscStrncpy(string,value,len);
2283:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
2284:     } else {
2285:       PetscMemzero(string,len);
2286:     }
2287:   }
2288:   return(0);
2289: }

2291: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2292: {
2293:   char           *value;
2295:   PetscBool      flag;

2298:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2299:   if (flag) PetscFunctionReturn(value);
2300:   else return(0);
2301: }


2304: /*@C
2305:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2306:    option in the database. The values must be separated with commas with
2307:    no intervening spaces.

2309:    Not Collective

2311:    Input Parameters:
2312: +  options - options database use NULL for default global database
2313: .  pre - string to prepend to name or NULL
2314: .  name - the option one is seeking
2315: -  nmax - maximum number of strings

2317:    Output Parameter:
2318: +  strings - location to copy strings
2319: -  set - PETSC_TRUE if found, else PETSC_FALSE

2321:    Level: beginner

2323:    Notes:
2324:    The user should pass in an array of pointers to char, to hold all the
2325:    strings returned by this function.

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

2330:    Contributed by Matthew Knepley.

2332:    Concepts: options database^array of strings

2334: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2335:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2336:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2337:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2338:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2339:           PetscOptionsFList(), PetscOptionsEList()
2340: @*/
2341: PetscErrorCode  PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
2342: {
2343:   char           *value;
2345:   PetscInt       n;
2346:   PetscBool      flag;
2347:   PetscToken     token;

2352:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2353:   if (!flag) {
2354:     *nmax = 0;
2355:     if (set) *set = PETSC_FALSE;
2356:     return(0);
2357:   }
2358:   if (!value) {
2359:     *nmax = 0;
2360:     if (set) *set = PETSC_FALSE;
2361:     return(0);
2362:   }
2363:   if (!*nmax) {
2364:     if (set) *set = PETSC_FALSE;
2365:     return(0);
2366:   }
2367:   if (set) *set = PETSC_TRUE;

2369:   PetscTokenCreate(value,',',&token);
2370:   PetscTokenFind(token,&value);
2371:   n    = 0;
2372:   while (n < *nmax) {
2373:     if (!value) break;
2374:     PetscStrallocpy(value,&strings[n]);
2375:     PetscTokenFind(token,&value);
2376:     n++;
2377:   }
2378:   PetscTokenDestroy(&token);
2379:   *nmax = n;
2380:   return(0);
2381: }

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

2386:    Not Collective

2388:    Input Parameter:
2389: +   options - options database use NULL for default global database
2390: -   option - string name of option

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

2395:    Level: advanced

2397: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2398: @*/
2399: PetscErrorCode  PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2400: {
2401:   PetscInt       i;

2405:   options = options ? options : defaultoptions;
2406:   *used = PETSC_FALSE;
2407:   for (i=0; i<options->N; i++) {
2408:     PetscStrcmp(options->names[i],option,used);
2409:     if (*used) {
2410:       *used = options->used[i];
2411:       break;
2412:     }
2413:   }
2414:   return(0);
2415: }

2417: /*@C
2418:    PetscOptionsAllUsed - Returns a count of the number of options in the
2419:    database that have never been selected.

2421:    Not Collective

2423:    Input Parameter:
2424: .  options - options database use NULL for default global database

2426:    Output Parameter:
2427: .   N - count of options not used

2429:    Level: advanced

2431: .seealso: PetscOptionsView()
2432: @*/
2433: PetscErrorCode  PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2434: {
2435:   PetscInt     i,n = 0;

2438:   options = options ? options : defaultoptions;
2439:   for (i=0; i<options->N; i++) {
2440:     if (!options->used[i]) n++;
2441:   }
2442:   *N = n;
2443:   return(0);
2444: }

2446: /*@C
2447:     PetscOptionsLeft - Prints to screen any options that were set and never used.

2449:   Not collective

2451:    Input Parameter:
2452: .  options - options database use NULL for default global database

2454:    Options Database Key:
2455: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

2457:   Level: advanced

2459: .seealso: PetscOptionsAllUsed()
2460: @*/
2461: PetscErrorCode  PetscOptionsLeft(PetscOptions options)
2462: {
2464:   PetscInt       i;

2467:   options = options ? options : defaultoptions;
2468:   for (i=0; i<options->N; i++) {
2469:     if (!options->used[i]) {
2470:       if (options->values[i]) {
2471:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2472:       } else {
2473:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2474:       }
2475:     }
2476:   }
2477:   return(0);
2478: }

2480: /*@
2481:     PetscOptionsCreate - Creates the empty options database.

2483:   Output Parameter:
2484: .   options - Options database object

2486:   Level: advanced

2488: @*/
2489: PetscErrorCode  PetscOptionsCreate(PetscOptions *options)
2490: {
2491:   *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2492:   if (!options) return PETSC_ERR_MEM;
2493:   (*options)->namegiven      = PETSC_FALSE;
2494:   (*options)->N              = 0;
2495:   (*options)->Naliases       = 0;
2496:   (*options)->numbermonitors = 0;
2497:   return 0;
2498: }

2500: /*
2501:     PetscOptionsCreateDefault - Creates the default global options database

2503: */
2504: PetscErrorCode  PetscOptionsCreateDefault(void)
2505: {

2508:   if (!defaultoptions) {
2509:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2510:   }
2511:   return 0;
2512: }

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

2517:    Collective on PETSC_COMM_WORLD

2519:    Input Parameter:
2520: .  options - options database use NULL for default global database

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

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

2532:    Level: intermediate

2534: .keywords: set, options, database
2535: @*/
2536: PetscErrorCode  PetscOptionsSetFromOptions(PetscOptions options)
2537: {
2538:   PetscBool      flgc = PETSC_FALSE,flgm;
2540:   char           monfilename[PETSC_MAX_PATH_LEN];
2541:   PetscViewer    monviewer;

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

2547:      options = options ? options : defaultoptions;
2548:   */
2549:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2550:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2551:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2552:   PetscOptionsEnd();
2553:   if (flgm) {
2554:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2555:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2556:   }
2557:   if (flgc) { PetscOptionsMonitorCancel(); }
2558:   return(0);
2559: }


2562: /*@C
2563:    PetscOptionsMonitorDefault - Print all options set value events.

2565:    Logically Collective on PETSC_COMM_WORLD

2567:    Input Parameters:
2568: +  name  - option name string
2569: .  value - option value string
2570: -  dummy - an ASCII viewer

2572:    Level: intermediate

2574: .keywords: PetscOptions, default, monitor

2576: .seealso: PetscOptionsMonitorSet()
2577: @*/
2578: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2579: {
2581:   PetscViewer    viewer = (PetscViewer) dummy;

2584:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2585:   return(0);
2586: }

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

2592:    Not collective

2594:    Input Parameters:
2595: +  monitor - pointer to function (if this is NULL, it turns off monitoring
2596: .  mctx    - [optional] context for private data for the
2597:              monitor routine (use NULL if no context is desired)
2598: -  monitordestroy - [optional] routine that frees monitor context
2599:           (may be NULL)

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

2604: +  name - option name string
2605: .  value - option value string
2606: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

2608:    Options Database Keys:
2609: +    -options_monitor    - sets PetscOptionsMonitorDefault()
2610: -    -options_monitor_cancel - cancels all monitors that have
2611:                           been hardwired into a code by
2612:                           calls to PetscOptionsMonitorSet(), but
2613:                           does not cancel those set via
2614:                           the options database.

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

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

2625:    Level: beginner

2627: .keywords: PetscOptions, set, monitor

2629: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2630: @*/
2631: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2632: {
2633:   PetscOptions options = defaultoptions;

2636:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2637:   options->monitor[options->numbermonitors]          = monitor;
2638:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
2639:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2640:   return(0);
2641: }

2643: /*@
2644:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2646:    Not collective

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

2653:    Level: intermediate

2655: .keywords: PetscOptions, set, monitor

2657: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2658: @*/
2659: PetscErrorCode  PetscOptionsMonitorCancel(void)
2660: {
2662:   PetscInt       i;
2663:   PetscOptions   options = defaultoptions;

2666:   for (i=0; i<options->numbermonitors; i++) {
2667:     if (options->monitordestroy[i]) {
2668:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
2669:     }
2670:   }
2671:   options->numbermonitors = 0;
2672:   return(0);
2673: }

2675: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }

2677: /*@C
2678:   PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed.

2680:   Collective on PetscObject

2682:   Input Parameters:
2683: + obj   - the object
2684: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
2685: - optionname - option to activate viewing

2687:   Level: intermediate

2689: @*/
2690: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2691: {
2692:   PetscErrorCode    ierr;
2693:   PetscViewer       viewer;
2694:   PetscBool         flg;
2695:   static PetscBool  incall = PETSC_FALSE;
2696:   PetscViewerFormat format;
2697:   char              *prefix;

2700:   if (incall) return(0);
2701:   incall = PETSC_TRUE;
2702:   prefix = bobj ? bobj->prefix : obj->prefix;
2703:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2704:   if (flg) {
2705:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2706:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2707:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2708:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2709:   }
2710:   incall = PETSC_FALSE;
2711:   return(0);
2712: }