Actual source code: options.c

petsc-3.7.6 2017-04-24
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>        /*I  "petscsys.h"   I*/
 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:   }

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

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

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

 94:   if (tdefault)    *a = PETSC_DEFAULT;
 95:   else if (decide) *a = PETSC_DECIDE;
 96:   else if (mouse)  *a = -1;
 97:   else {
 98:     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);

100:     for (i=1; i<len; i++) {
101:       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);
102:     }

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

115: #if defined(PETSC_USE_REAL___FLOAT128)
116: #include <quadmath.h>
117: #endif

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

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

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

143:   if (tdefault)    *a = PETSC_DEFAULT;
144:   else if (decide) *a = PETSC_DECIDE;
145:   else {
146:     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);
147: #if defined(PETSC_USE_REAL___FLOAT128)
148:     *a = strtoflt128(name,NULL);
149: #else
150:     *a = atof(name);
151: #endif
152:   }
153:   return(0);
154: }

158: /*
159:    Converts a string to PetscScalar value. Handles
160:       [-][2].0
161:       [-][2].0i
162:       [-][2].0+/-2.0i

164: */
165: PetscErrorCode  PetscOptionsStringToScalar(const char name[],PetscScalar *a)
166: {
168:   size_t         len;

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

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

187:     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);
188:     if (name[0] == '-') {
189:       neg = PETSC_TRUE;
190:       name++;
191:     }
192:     if (name[0] == 'i') {
193: #if defined(PETSC_USE_COMPLEX)
194:       *a = -PETSC_i;
195: #else
196:      SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
197: #endif
198:       return(0);
199:     }

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

247: /*
248:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
249: */
250: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
251: {
252:   PetscBool      istrue, isfalse;
253:   size_t         len;

257:   PetscStrlen(value, &len);
258:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
259:   PetscStrcasecmp(value,"TRUE",&istrue);
260:   if (istrue) {*a = PETSC_TRUE; return(0);}
261:   PetscStrcasecmp(value,"YES",&istrue);
262:   if (istrue) {*a = PETSC_TRUE; return(0);}
263:   PetscStrcasecmp(value,"1",&istrue);
264:   if (istrue) {*a = PETSC_TRUE; return(0);}
265:   PetscStrcasecmp(value,"on",&istrue);
266:   if (istrue) {*a = PETSC_TRUE; return(0);}
267:   PetscStrcasecmp(value,"FALSE",&isfalse);
268:   if (isfalse) {*a = PETSC_FALSE; return(0);}
269:   PetscStrcasecmp(value,"NO",&isfalse);
270:   if (isfalse) {*a = PETSC_FALSE; return(0);}
271:   PetscStrcasecmp(value,"0",&isfalse);
272:   if (isfalse) {*a = PETSC_FALSE; return(0);}
273:   PetscStrcasecmp(value,"off",&isfalse);
274:   if (isfalse) {*a = PETSC_FALSE; return(0);}
275:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
276: }

280: /*@C
281:     PetscGetProgramName - Gets the name of the running program.

283:     Not Collective

285:     Input Parameter:
286: .   len - length of the string name

288:     Output Parameter:
289: .   name - the name of the running program

291:    Level: advanced

293:     Notes:
294:     The name of the program is copied into the user-provided character
295:     array of length len.  On some machines the program name includes
296:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
297: @*/
298: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
299: {

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

309: PetscErrorCode  PetscSetProgramName(const char name[])
310: {

314:   PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);
315:   return(0);
316: }

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

323:    Input Parameter:
324: .    in_str - string to check if valid

326:    Output Parameter:
327: .    key - PETSC_TRUE if a valid key

329:   Level: intermediate

331: @*/
332: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
333: {
334:   PetscBool      inf,INF;

338:   *key = PETSC_FALSE;
339:   if (!in_str) return(0);
340:   if (in_str[0] != '-') return(0);
341:   if (in_str[1] == '-') in_str++;
342:   if (!isalpha((int)(in_str[1]))) return(0);
343:   PetscStrncmp(in_str+1,"inf",3,&inf);
344:   PetscStrncmp(in_str+1,"INF",3,&INF);
345:   if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
346:   *key = PETSC_TRUE;
347:   return(0);
348: }

352: /*@C
353:      PetscOptionsInsertString - Inserts options into the database from a string

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

358:   Input Parameter:
359: .   in_str - string that contains options separated by blanks


362:   Level: intermediate

364:   Contributed by Boyana Norris

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

373: @*/
374: PetscErrorCode  PetscOptionsInsertString(PetscOptions options,const char in_str[])
375: {
376:   char           *first,*second;
378:   PetscToken     token;
379:   PetscBool      key,ispush,ispop;

382:   options = options ? options : defaultoptions;
383:   PetscTokenCreate(in_str,' ',&token);
384:   PetscTokenFind(token,&first);
385:   while (first) {
386:     PetscStrcasecmp(first,"-prefix_push",&ispush);
387:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
388:     PetscOptionsValidKey(first,&key);
389:     if (ispush) {
390:       PetscTokenFind(token,&second);
391:       PetscOptionsPrefixPush(options,second);
392:       PetscTokenFind(token,&first);
393:     } else if (ispop) {
394:       PetscOptionsPrefixPop(options);
395:       PetscTokenFind(token,&first);
396:     } else if (key) {
397:       PetscTokenFind(token,&second);
398:       PetscOptionsValidKey(second,&key);
399:       if (!key) {
400:         PetscOptionsSetValue(options,first,second);
401:         PetscTokenFind(token,&first);
402:       } else {
403:         PetscOptionsSetValue(options,first,NULL);
404:         first = second;
405:       }
406:     } else {
407:       PetscTokenFind(token,&first);
408:     }
409:   }
410:   PetscTokenDestroy(&token);
411:   return(0);
412: }

414: /*
415:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
416: */
417: static char *Petscgetline(FILE * f)
418: {
419:   size_t size  = 0;
420:   size_t len   = 0;
421:   size_t last  = 0;
422:   char   *buf  = NULL;

424:   if (feof(f)) return 0;
425:   do {
426:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
427:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
428:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
429:     end of the string, so we make sure we overwrite this */
430:     if (!fgets(buf+len,size,f)) buf[len]=0;
431:     PetscStrlen(buf,&len);
432:     last = len - 1;
433:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
434:   if (len) return buf;
435:   free(buf);
436:   return 0;
437: }


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

445:      Collective on MPI_Comm

447:   Input Parameter:
448: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
449: .   options - options database, use NULL for default global database
450: .   file - name of file
451: -   require - if PETSC_TRUE will generate an error if the file does not exist


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

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

460:   Level: developer

462: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
463:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
464:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
465:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
466:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
467:           PetscOptionsFList(), PetscOptionsEList()

469: @*/
470: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
471: {
472:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
474:   size_t         i,len,bytes;
475:   FILE           *fd;
476:   PetscToken     token;
477:   int            err;
478:   char           cmt[1]={'#'},*cmatch;
479:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];
480:   PetscBool      isdir;

483:   options = options ? options : defaultoptions;
484:   MPI_Comm_rank(comm,&rank);
485:   if (!rank) {
486:     cnt        = 0;
487:     acnt       = 0;

489:     PetscFixFilename(file,fname);
490:     fd   = fopen(fname,"r");
491:     PetscTestDirectory(fname,'r',&isdir);
492:     if (isdir && require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Specified options file %s is a directory",fname);
493:     if (fd && !isdir) {
494:       PetscSegBuffer vseg,aseg;
495:       PetscSegBufferCreate(1,4000,&vseg);
496:       PetscSegBufferCreate(1,2000,&aseg);

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

501:       while ((string = Petscgetline(fd))) {
502:         /* eliminate comments from each line */
503:         for (i=0; i<1; i++) {
504:           PetscStrchr(string,cmt[i],&cmatch);
505:           if (cmatch) *cmatch = 0;
506:         }
507:         PetscStrlen(string,&len);
508:         /* replace tabs, ^M, \n with " " */
509:         for (i=0; i<len; i++) {
510:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
511:             string[i] = ' ';
512:           }
513:         }
514:         PetscTokenCreate(string,' ',&token);
515:         PetscTokenFind(token,&first);
516:         if (!first) {
517:           goto destroy;
518:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
519:           PetscTokenFind(token,&first);
520:         }
521:         PetscTokenFind(token,&second);
522:         if (!first) {
523:           goto destroy;
524:         } else if (first[0] == '-') {
525:           PetscStrlen(first,&len);
526:           PetscSegBufferGet(vseg,len+1,&vstring);
527:           PetscMemcpy(vstring,first,len);
528:           vstring[len] = ' ';
529:           if (second) {
530:             PetscStrlen(second,&len);
531:             PetscSegBufferGet(vseg,len+3,&vstring);
532:             vstring[0] = '"';
533:             PetscMemcpy(vstring+1,second,len);
534:             vstring[len+1] = '"';
535:             vstring[len+2] = ' ';
536:           }
537:         } else {
538:           PetscBool match;

540:           PetscStrcasecmp(first,"alias",&match);
541:           if (match) {
542:             PetscTokenFind(token,&third);
543:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
544:             PetscStrlen(second,&len);
545:             PetscSegBufferGet(aseg,len+1,&astring);
546:             PetscMemcpy(astring,second,len);
547:             astring[len] = ' ';

549:             PetscStrlen(third,&len);
550:             PetscSegBufferGet(aseg,len+1,&astring);
551:             PetscMemcpy(astring,third,len);
552:             astring[len] = ' ';
553:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
554:         }
555: destroy:
556:         free(string);
557:         PetscTokenDestroy(&token);
558:       }
559:       err = fclose(fd);
560:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
561:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
562:       PetscMPIIntCast(bytes,&acnt);
563:       PetscSegBufferGet(aseg,1,&astring);
564:       astring[0] = 0;
565:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
566:       PetscMPIIntCast(bytes,&cnt);
567:       PetscSegBufferGet(vseg,1,&vstring);
568:       vstring[0] = 0;
569:       PetscMalloc1(2+acnt+cnt,&packed);
570:       PetscSegBufferExtractTo(aseg,packed);
571:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
572:       PetscSegBufferDestroy(&aseg);
573:       PetscSegBufferDestroy(&vseg);
574:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
575:   }

577:   counts[0] = acnt;
578:   counts[1] = cnt;
579:   MPI_Bcast(counts,2,MPI_INT,0,comm);
580:   acnt = counts[0];
581:   cnt = counts[1];
582:   if (rank) {
583:     PetscMalloc1(2+acnt+cnt,&packed);
584:   }
585:   if (acnt || cnt) {
586:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
587:     astring = packed;
588:     vstring = packed + acnt + 1;
589:   }

591:   if (acnt) {
592:     PetscToken token;
593:     char       *first,*second;

595:     PetscTokenCreate(astring,' ',&token);
596:     PetscTokenFind(token,&first);
597:     while (first) {
598:       PetscTokenFind(token,&second);
599:       PetscOptionsSetAlias(options,first,second);
600:       PetscTokenFind(token,&first);
601:     }
602:     PetscTokenDestroy(&token);
603:   }

605:   if (cnt) {
606:     PetscOptionsInsertString(options,vstring);
607:   }
608:   PetscFree(packed);
609:   return(0);
610: }

614: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
615: {
617:   int            left    = argc - 1;
618:   char           **eargs = args + 1;

621:   options = options ? options : defaultoptions;
622:   while (left) {
623:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
624:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
625:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
626:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
627:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
628:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
629:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
630:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
631:     isp4 = (PetscBool) (isp4 || tisp4);
632:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
633:     isp4 = (PetscBool) (isp4 || tisp4);
634:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
635:     PetscOptionsValidKey(eargs[0],&key);

637:     if (!key) {
638:       eargs++; left--;
639:     } else if (isoptions_file) {
640:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
641:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
642:       PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
643:       eargs += 2; left -= 2;
644:     } else if (isprefixpush) {
645:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
646:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
647:       PetscOptionsPrefixPush(options,eargs[1]);
648:       eargs += 2; left -= 2;
649:     } else if (isprefixpop) {
650:       PetscOptionsPrefixPop(options);
651:       eargs++; left--;

653:       /*
654:        These are "bad" options that MPICH, etc put on the command line
655:        we strip them out here.
656:        */
657:     } else if (tisp4 || isp4rmrank) {
658:       eargs += 1; left -= 1;
659:     } else if (isp4 || isp4yourname) {
660:       eargs += 2; left -= 2;
661:     } else {
662:       PetscBool nextiskey = PETSC_FALSE;
663:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
664:       if (left < 2 || nextiskey) {
665:         PetscOptionsSetValue(options,eargs[0],NULL);
666:         eargs++; left--;
667:       } else {
668:         PetscOptionsSetValue(options,eargs[0],eargs[1]);
669:         eargs += 2; left -= 2;
670:       }
671:     }
672:   }
673:   return(0);
674: }


679: /*@C
680:    PetscOptionsInsert - Inserts into the options database from the command line,
681:                    the environmental variable and a file.

683:    Input Parameters:
684: +  options - options database or NULL for the default global database
685: .  argc - count of number of command line arguments
686: .  args - the command line arguments
687: -  file - optional filename, defaults to ~username/.petscrc

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

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

698:    Level: advanced

700:    Concepts: options database^adding

702: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
703:           PetscInitialize()
704: @*/
705: PetscErrorCode  PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
706: {
708:   PetscMPIInt    rank;
709:   char           pfile[PETSC_MAX_PATH_LEN];
710:   PetscBool      flag = PETSC_FALSE;

712: 
714:   if (!options) {
715:     if (!defaultoptions) {
716:       PetscOptionsCreateDefault();
717:     }
718:     options = defaultoptions;
719:   }
720:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

722:   options->argc = (argc) ? *argc : 0;
723:   options->args = (args) ? *args : NULL;

725:   if (file && file[0]) {
726:     char fullpath[PETSC_MAX_PATH_LEN];

728:     PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
729:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
730:   }
731:   /*
732:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
733:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
734:   */
735:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
736:   PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
737:   if (!flag) {
738:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
739:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
740:     if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
741:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
742:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
743:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
744:   }

746:   /* insert environmental options */
747:   {
748:     char   *eoptions = 0;
749:     size_t len       = 0;
750:     if (!rank) {
751:       eoptions = (char*)getenv("PETSC_OPTIONS");
752:       PetscStrlen(eoptions,&len);
753:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
754:     } else {
755:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
756:       if (len) {
757:         PetscMalloc1(len+1,&eoptions);
758:       }
759:     }
760:     if (len) {
761:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
762:       if (rank) eoptions[len] = 0;
763:       PetscOptionsInsertString(options,eoptions);
764:       if (rank) {PetscFree(eoptions);}
765:     }
766:   }

768: #if defined(PETSC_HAVE_YAML)
769:   char      yaml_file[PETSC_MAX_PATH_LEN];
770:   PetscBool yaml_flg = PETSC_FALSE;
771:   PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
772:   if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
773: #endif

775:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
776:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
777:   return(0);
778: }

782: /*@C
783:    PetscOptionsView - Prints the options that have been loaded. This is
784:    useful for debugging purposes.

786:    Logically Collective on PetscViewer

788:    Input Parameter:
789: .  viewer - must be an PETSCVIEWERASCII viewer

791:    Options Database Key:
792: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

794:    Level: advanced

796:    Concepts: options database^printing

798: .seealso: PetscOptionsAllUsed()
799: @*/
800: PetscErrorCode  PetscOptionsView(PetscOptions options,PetscViewer viewer)
801: {
803:   PetscInt       i;
804:   PetscBool      isascii;

807:   options = options ? options : defaultoptions;
808:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
809:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
810:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

812:   if (options->N) {
813:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
814:   } else {
815:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
816:   }
817:   for (i=0; i<options->N; i++) {
818:     if (options->values[i]) {
819:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
820:     } else {
821:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
822:     }
823:   }
824:   if (options->N) {
825:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
826:   }
827:   return(0);
828: }

832: /*
833:    Called by error handlers to print options used in run
834: */
835: PetscErrorCode  PetscOptionsViewError(void)
836: {
837:   PetscInt       i;
838:   PetscOptions   options = defaultoptions;

841:   if (options->N) {
842:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
843:   } else {
844:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
845:   }
846:   for (i=0; i<options->N; i++) {
847:     if (options->values[i]) {
848:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
849:     } else {
850:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
851:     }
852:   }
853:   return(0);
854: }

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

861:    Not Collective

863:    Input Paramter:
864: .  options - the options database, use NULL for the default global database

866:    Output Parameter:
867: .  copts - pointer where string pointer is stored

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

871:    Level: advanced

873:    Concepts: options database^listing

875: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
876: @*/
877: PetscErrorCode  PetscOptionsGetAll(PetscOptions options,char *copts[])
878: {
880:   PetscInt       i;
881:   size_t         len       = 1,lent = 0;
882:   char           *coptions = NULL;

885:   options = options ? options : defaultoptions;

887:   /* count the length of the required string */
888:   for (i=0; i<options->N; i++) {
889:     PetscStrlen(options->names[i],&lent);
890:     len += 2 + lent;
891:     if (options->values[i]) {
892:       PetscStrlen(options->values[i],&lent);
893:       len += 1 + lent;
894:     }
895:   }
896:   PetscMalloc1(len,&coptions);
897:   coptions[0] = 0;
898:   for (i=0; i<options->N; i++) {
899:     PetscStrcat(coptions,"-");
900:     PetscStrcat(coptions,options->names[i]);
901:     PetscStrcat(coptions," ");
902:     if (options->values[i]) {
903:       PetscStrcat(coptions,options->values[i]);
904:       PetscStrcat(coptions," ");
905:     }
906:   }
907:   *copts = coptions;
908:   return(0);
909: }

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

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

918:    Input Parameter:
919: +  options - options database, or NULL for the default global database
920: -  prefix - The string to append to the existing prefix

922:    Options Database Keys:
923:  +   -prefix_push <some_prefix_> - push the given prefix
924:  -   -prefix_pop - pop the last prefix

926:    Notes:
927:    It is common to use this in conjunction with -options_file as in

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

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

933: Level: advanced

935: .seealso: PetscOptionsPrefixPop()
936: @*/
937: PetscErrorCode  PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
938: {
940:   size_t         n;
941:   PetscInt       start;
942:   char           buf[2048];
943:   PetscBool      key;

947:   options = options ? options : defaultoptions;
948:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
949:   buf[0] = '-';
950:   PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
951:   buf[sizeof(buf) - 1] = 0;
952:   PetscOptionsValidKey(buf,&key);
953:   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);

955:   if (!options) {
956:     PetscOptionsInsert(NULL,0,0,0);
957:     options = defaultoptions;
958:   }
959:   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);
960:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
961:   PetscStrlen(prefix,&n);
962:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
963:   PetscMemcpy(options->prefix+start,prefix,n+1);
964:   options->prefixstack[options->prefixind++] = start+n;
965:   return(0);
966: }

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

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

975:   Input Parameters:
976: .  options - options database, or NULL for the default global database

978:    Level: advanced

980: .seealso: PetscOptionsPrefixPush()
981: @*/
982: PetscErrorCode  PetscOptionsPrefixPop(PetscOptions options)
983: {
984:   PetscInt offset;

987:   options = options ? options : defaultoptions;
988:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
989:   options->prefixind--;
990:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
991:   options->prefix[offset] = 0;
992:   return(0);
993: }

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

1000:   Input Parameters:
1001: .  options - options database, use NULL for the default global database

1003:    Level: developer

1005: .seealso: PetscOptionsInsert()
1006: @*/
1007: PetscErrorCode  PetscOptionsClear(PetscOptions options)
1008: {
1009:   PetscInt     i;

1012:   options = options ? options : defaultoptions;
1013:   for (i=0; i<options->N; i++) {
1014:     if (options->names[i])  free(options->names[i]);
1015:     if (options->values[i]) free(options->values[i]);
1016:   }
1017:   for (i=0; i<options->Naliases; i++) {
1018:     free(options->aliases1[i]);
1019:     free(options->aliases2[i]);
1020:   }
1021:   options->prefix[0] = 0;
1022:   options->prefixind = 0;
1023:   options->N         = 0;
1024:   options->Naliases  = 0;
1025:   return(0);
1026: }

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

1033:   Input Parameters:
1034: .  obj  - the PetscObject

1036:    Level: developer

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

1041: .seealso: PetscOptionsInsert()
1042: @*/
1043: PetscErrorCode  PetscObjectSetPrintedOptions(PetscObject obj)
1044: {
1046:   obj->optionsprinted = PETSC_TRUE;
1047:   return(0);
1048: }

1052: /*@
1053:     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.

1055:   Input Parameters:
1056: +  pobj - the parent object
1057: -  obj  - the PetscObject

1059:    Level: developer

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

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

1066: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1067: @*/
1068: PetscErrorCode  PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1069: {
1071:   PetscMPIInt    prank,size;

1074:   MPI_Comm_rank(pobj->comm,&prank);
1075:   MPI_Comm_size(obj->comm,&size);
1076:   if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
1077:   return(0);
1078: }

1082: /*@
1083:     PetscOptionsDestroy - Destroys an option database.

1085:   Input Parameter:
1086: .  options - the PetscOptions object

1088:    Level: developer

1090: .seealso: PetscOptionsInsert()
1091: @*/
1092: PetscErrorCode  PetscOptionsDestroy(PetscOptions *options)
1093: {

1097:   PetscOptionsClear(*options);
1098:   free(*options);
1099:   *options = NULL;
1100:   return(0);
1101: }

1105: PetscErrorCode  PetscOptionsDestroyDefault(void)
1106: {

1109:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1110:   return 0;
1111: }


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

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

1123:    Input Parameters:
1124: +  options - options database, use NULL for the default global database
1125: .  name - name of option, this SHOULD have the - prepended
1126: -  value - the option value (not used for all options)

1128:    Level: intermediate

1130:    Note:
1131:    This function can be called BEFORE PetscInitialize()

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

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

1138:   Concepts: options database^adding option

1140: .seealso: PetscOptionsInsert()
1141: @*/
1142: PetscErrorCode  PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1143: {
1144:   size_t         len;
1146:   PetscInt       N,n,i;
1147:   char           **names;
1148:   char           fullname[2048];
1149:   const char     *name = iname;
1150:   int            match;

1152:   if (!options) {
1153:     if (!defaultoptions) {
1154:       PetscOptionsCreateDefault();
1155:       if (ierr) return ierr;
1156:     }
1157:     options = defaultoptions;
1158:   }

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

1164:   name++; /* skip starting hyphen */
1165:   if (options->prefixind > 0) {
1166:     strncpy(fullname,options->prefix,sizeof(fullname));
1167:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1168:     name = fullname;
1169:   }

1171:   /* check against aliases */
1172:   N = options->Naliases;
1173:   for (i=0; i<N; i++) {
1174: #if defined(PETSC_HAVE_STRCASECMP)
1175:     match = strcasecmp(options->aliases1[i],name);
1176: #elif defined(PETSC_HAVE_STRICMP)
1177:     match = stricmp(options->aliases1[i],name);
1178: #else
1179:     Error
1180: #endif
1181:     if (!match) {
1182:       name = options->aliases2[i];
1183:       break;
1184:     }
1185:   }

1187:   N     = options->N;
1188:   n     = N;
1189:   names = options->names;

1191:   for (i=0; i<N; i++) {
1192: #if defined(PETSC_HAVE_STRCASECMP)
1193:     match = strcasecmp(names[i],name);
1194: #elif defined(PETSC_HAVE_STRICMP)
1195:     match = stricmp(names[i],name);
1196: #else
1197:     Error
1198: #endif
1199:     if (!match) {
1200:       if (options->values[i]) free(options->values[i]);
1201:       len = value ? strlen(value) : 0;
1202:       if (len) {
1203:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
1204:         if (!options->values[i]) return PETSC_ERR_MEM;
1205:         strcpy(options->values[i],value);
1206:       } else options->values[i] = 0;
1207:       return 0;
1208:     } else if (strcmp(names[i],name) > 0) {
1209:       n = i;
1210:       break;
1211:     }
1212:   }
1213:   if (N >= MAXOPTIONS) abort();

1215:   /* shift remaining values down 1 */
1216:   for (i=N; i>n; i--) {
1217:     options->names[i]  = options->names[i-1];
1218:     options->values[i] = options->values[i-1];
1219:     options->used[i]   = options->used[i-1];
1220:   }
1221:   /* insert new name and value */
1222:   len = strlen(name);
1223:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
1224:   if (!options->names[n]) return PETSC_ERR_MEM;
1225:   strcpy(options->names[n],name);
1226:   len = value ? strlen(value) : 0;
1227:   if (len) {
1228:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
1229:     if (!options->values[n]) return PETSC_ERR_MEM;
1230:     strcpy(options->values[n],value);
1231:   } else options->values[n] = NULL;
1232:   options->used[n] = PETSC_FALSE;
1233:   options->N++;
1234:   return 0;
1235: }

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

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

1246:    Input Parameter:
1247: +  options - options database, use NULL for the default global database
1248: .  name - name of option, this SHOULD have the - prepended

1250:    Level: intermediate

1252:    Concepts: options database^removing option
1253: .seealso: PetscOptionsInsert()
1254: @*/
1255: PetscErrorCode  PetscOptionsClearValue(PetscOptions options,const char iname[])
1256: {
1258:   PetscInt       N,n,i;
1259:   char           **names,*name=(char*)iname;
1260:   PetscBool      gt,match;

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

1267:   N     = options->N; n = 0;
1268:   names = options->names;

1270:   for (i=0; i<N; i++) {
1271:     PetscStrcasecmp(names[i],name,&match);
1272:     PetscStrgrt(names[i],name,&gt);
1273:     if (match) {
1274:       if (options->names[i])  free(options->names[i]);
1275:       if (options->values[i]) free(options->values[i]);
1276:       PetscOptionsMonitor(name,"");
1277:       break;
1278:     } else if (gt) return(0); /* it was not listed */

1280:     n++;
1281:   }
1282:   if (n == N) return(0); /* it was not listed */

1284:   /* shift remaining values down 1 */
1285:   for (i=n; i<N-1; i++) {
1286:     options->names[i]  = options->names[i+1];
1287:     options->values[i] = options->values[i+1];
1288:     options->used[i]   = options->used[i+1];
1289:   }
1290:   options->N--;
1291:   return(0);
1292: }

1296: /*@C
1297:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1302:    Input Parameters:
1303: +  options - options database or NULL for default global database
1304: .  inewname - the alias
1305: -  ioldname - the name that alias will refer to

1307:    Level: advanced

1309: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1310:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1311:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1312:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1313:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1314:           PetscOptionsFList(), PetscOptionsEList()
1315: @*/
1316: PetscErrorCode  PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1317: {
1319:   PetscInt       n = options->Naliases;
1320:   size_t         len;
1321:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

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

1329:   newname++; oldname++;
1330:   PetscStrlen(newname,&len);
1331:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1332:   PetscStrcpy(options->aliases1[n],newname);
1333:   PetscStrlen(oldname,&len);
1334:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1335:   PetscStrcpy(options->aliases2[n],oldname);
1336:   options->Naliases++;
1337:   return(0);
1338: }

1342: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool  *flg)
1343: {
1345:   PetscInt       i,N;
1346:   size_t         len;
1347:   char           **names,tmp[256];
1348:   PetscBool      match;

1351:   options = options ? options : defaultoptions;
1352:   N     = options->N;
1353:   names = options->names;

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

1357:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1358:   if (pre) {
1359:     char       *ptr   = tmp;
1360:     const char *namep = name;
1361:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1362:     if (name[1] == '-') {
1363:       *ptr++ = '-';
1364:       namep++;
1365:     }
1366:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1367:     tmp[sizeof(tmp)-1] = 0;
1368:     PetscStrlen(tmp,&len);
1369:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1370:   } else {
1371:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1372:     tmp[sizeof(tmp)-1] = 0;
1373:   }
1374: #if defined(PETSC_USE_DEBUG)
1375:   {
1376:     PetscBool valid;
1377:     char      key[sizeof(tmp)+1] = "-";

1379:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1380:     PetscOptionsValidKey(key,&valid);
1381:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1382:   }
1383: #endif

1385:   /* slow search */
1386:   *flg = PETSC_FALSE;
1387:   for (i=0; i<N; i++) {
1388:     PetscStrcasecmp(names[i],tmp,&match);
1389:     if (match) {
1390:       *value           = options->values[i];
1391:       options->used[i] = PETSC_TRUE;
1392:       *flg             = PETSC_TRUE;
1393:       break;
1394:     }
1395:   }
1396:   if (!*flg) {
1397:     PetscInt j,cnt = 0,locs[16],loce[16];
1398:     size_t   n;
1399:     PetscStrlen(tmp,&n);
1400:     /* determine the location and number of all _%d_ in the key */
1401:     for (i=0; i< (PetscInt)n; i++) {
1402:       if (tmp[i] == '_') {
1403:         for (j=i+1; j< (PetscInt)n; j++) {
1404:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1405:           if (tmp[j] == '_' && j > i+1) { /* found a number */
1406:             locs[cnt]   = i+1;
1407:             loce[cnt++] = j+1;
1408:           }
1409:           break;
1410:         }
1411:       }
1412:     }
1413:     if (cnt) {
1414:       char tmp2[256];
1415:       for (i=0; i<cnt; i++) {
1416:         PetscStrcpy(tmp2,"-");
1417:         PetscStrncat(tmp2,tmp,locs[i]);
1418:         PetscStrcat(tmp2,tmp+loce[i]);
1419:         PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
1420:         if (*flg) break;
1421:       }
1422:     }
1423:   }
1424:   return(0);
1425: }

1429: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
1430: {
1432:   PetscInt       i,N;
1433:   size_t         len;
1434:   char           **names,tmp[256];
1435:   PetscBool      match;

1438:   options = options ? options : defaultoptions;
1439:   N     = options->N;
1440:   names = options->names;

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

1444:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1445:   if (pre) {
1446:     char       *ptr   = tmp;
1447:     const char *namep = name;
1448:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1449:     if (name[1] == '-') {
1450:       *ptr++ = '-';
1451:       namep++;
1452:     }
1453:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1454:     tmp[sizeof(tmp)-1] = 0;
1455:     PetscStrlen(tmp,&len);
1456:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1457:   } else {
1458:     PetscStrncpy(tmp,name+1,sizeof(tmp));
1459:     tmp[sizeof(tmp)-1] = 0;
1460:   }
1461: #if defined(PETSC_USE_DEBUG)
1462:   {
1463:     PetscBool valid;
1464:     char      key[sizeof(tmp)+1] = "-";

1466:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1467:     PetscOptionsValidKey(key,&valid);
1468:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1469:   }
1470: #endif

1472:   /* slow search */
1473:   *flg = PETSC_FALSE;
1474:   PetscStrlen(tmp,&len);
1475:   for (i = 0; i < N; ++i) {
1476:     PetscStrncmp(names[i], tmp, len, &match);
1477:     if (match) {
1478:       if (value) *value = options->values[i];
1479:       options->used[i]  = PETSC_TRUE;
1480:       if (flg)   *flg   = PETSC_TRUE;
1481:       break;
1482:     }
1483:   }
1484:   return(0);
1485: }

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

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

1495:    Input Parameters:
1496: +  options - options database use NULL for default global database
1497: .  name - the option one is seeking
1498: -  mess - error message (may be NULL)

1500:    Level: advanced

1502:    Concepts: options database^rejecting option

1504: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1505:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1506:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1507:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1508:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1509:           PetscOptionsFList(), PetscOptionsEList()
1510: @*/
1511: PetscErrorCode  PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
1512: {
1514:   PetscBool      flag = PETSC_FALSE;

1517:   options = options ? options : defaultoptions;
1518:   PetscOptionsHasName(options,NULL,name,&flag);
1519:   if (flag) {
1520:     if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1521:     else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1522:   }
1523:   return(0);
1524: }

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

1532:    Not Collective

1534:    Input Parameters:
1535: +  options - options database use NULL for default global database
1536: .  name - the option one is seeking
1537: -  pre - string to prepend to the name or NULL

1539:    Output Parameters:
1540: .  set - PETSC_TRUE if found else PETSC_FALSE.

1542:    Level: beginner

1544:    Concepts: options database^has option name

1546:    Notes: Name cannot be simply -h

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

1550: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1551:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1552:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1553:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1554:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1555:           PetscOptionsFList(), PetscOptionsEList()
1556: @*/
1557: PetscErrorCode  PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool  *set)
1558: {
1559:   char           *value;
1561:   PetscBool      flag;

1564:   options = options ? options : defaultoptions;
1565:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1566:   if (set) *set = flag;
1567:   return(0);
1568: }

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

1575:    Not Collective

1577:    Input Parameters:
1578: +  options - options database use NULL for default global database
1579: .  pre - the string to prepend to the name or NULL
1580: -  name - the option one is seeking

1582:    Output Parameter:
1583: +  ivalue - the integer value to return
1584: -  set - PETSC_TRUE if found, else PETSC_FALSE

1586:    Level: beginner

1588:    Concepts: options database^has int

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

1607:   options = options ? options : defaultoptions;
1608:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1609:   if (flag) {
1610:     if (!value) {
1611:       if (set) *set = PETSC_FALSE;
1612:     } else {
1613:       if (set) *set = PETSC_TRUE;
1614:       PetscOptionsStringToInt(value,ivalue);
1615:     }
1616:   } else {
1617:     if (set) *set = PETSC_FALSE;
1618:   }
1619:   return(0);
1620: }

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

1627:    Not Collective

1629:    Input Parameters:
1630: +  options - options database use NULL for default global database
1631: .  pre - the string to prepend to the name or NULL
1632: .  opt - option name
1633: .  list - the possible choices (one of these must be selected, anything else is invalid)
1634: .  ntext - number of choices

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

1640:    Level: intermediate

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

1644:    Concepts: options database^list

1646: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1647:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1648:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1649:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1650:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1651:           PetscOptionsFList(), PetscOptionsEList()
1652: @*/
1653: PetscErrorCode  PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool  *set)
1654: {
1656:   size_t         alen,len = 0;
1657:   char           *svalue;
1658:   PetscBool      aset,flg = PETSC_FALSE;
1659:   PetscInt       i;

1662:   options = options ? options : defaultoptions;
1663:   for (i=0; i<ntext; i++) {
1664:     PetscStrlen(list[i],&alen);
1665:     if (alen > len) len = alen;
1666:   }
1667:   len += 5; /* a little extra space for user mistypes */
1668:   PetscMalloc1(len,&svalue);
1669:   PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
1670:   if (aset) {
1671:     PetscEListFind(ntext,list,svalue,value,&flg);
1672:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1673:     if (set) *set = PETSC_TRUE;
1674:   } else if (set) *set = PETSC_FALSE;
1675:   PetscFree(svalue);
1676:   return(0);
1677: }

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

1684:    Not Collective

1686:    Input Parameters:
1687: +  options - options database use NULL for default global database
1688: .  pre - option prefix or NULL
1689: .  opt - option name
1690: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1691: -  defaultv - the default (current) value

1693:    Output Parameter:
1694: +  value - the  value to return
1695: -  set - PETSC_TRUE if found, else PETSC_FALSE

1697:    Level: beginner

1699:    Concepts: options database

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

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

1705: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1706:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1707:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1708:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1709:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1710:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1711:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1712: @*/
1713: PetscErrorCode  PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool  *set)
1714: {
1716:   PetscInt       ntext = 0,tval;
1717:   PetscBool      fset;

1720:   options = options ? options : defaultoptions;
1721:   while (list[ntext++]) {
1722:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1723:   }
1724:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1725:   ntext -= 3;
1726:   PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
1727:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1728:   if (fset) *value = (PetscEnum)tval;
1729:   if (set) *set = fset;
1730:   return(0);
1731: }

1735: /*@C
1736:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1737:             option in the database.

1739:    Not Collective

1741:    Input Parameters:
1742: +  options - options database use NULL for default global database
1743: .  pre - the string to prepend to the name or NULL
1744: -  name - the option one is seeking

1746:    Output Parameter:
1747: +  ivalue - the logical value to return
1748: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1750:    Level: beginner

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

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

1759:    Concepts: options database^has logical

1761: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1762:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1763:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1764:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1765:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1766:           PetscOptionsFList(), PetscOptionsEList()
1767: @*/
1768: PetscErrorCode  PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
1769: {
1770:   char           *value;
1771:   PetscBool      flag;

1777:   options = options ? options : defaultoptions;
1778:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1779:   if (flag) {
1780:     if (set) *set = PETSC_TRUE;
1781:     if (!value) {
1782:       if (ivalue) *ivalue = PETSC_TRUE;
1783:     } else {
1784:       PetscOptionsStringToBool(value, ivalue);
1785:     }
1786:   } else {
1787:     if (set) *set = PETSC_FALSE;
1788:   }
1789:   return(0);
1790: }

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

1799:    Not Collective

1801:    Input Parameters:
1802: +  options - options database use NULL for default global database
1803: .  pre - string to prepend to each name or NULL
1804: .  name - the option one is seeking
1805: -  nmax - maximum number of values to retrieve

1807:    Output Parameter:
1808: +  dvalue - the integer values to return
1809: .  nmax - actual number of values retreived
1810: -  set - PETSC_TRUE if found, else PETSC_FALSE

1812:    Level: beginner

1814:    Concepts: options database^array of ints

1816:    Notes:
1817:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1818:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1820: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1821:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1822:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1823:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1824:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1825:           PetscOptionsFList(), PetscOptionsEList()
1826: @*/
1827: PetscErrorCode  PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
1828: {
1829:   char           *value;
1831:   PetscInt       n = 0;
1832:   PetscBool      flag;
1833:   PetscToken     token;

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

1842:   if (set) *set = PETSC_TRUE;

1844:   PetscTokenCreate(value,',',&token);
1845:   PetscTokenFind(token,&value);
1846:   while (n < *nmax) {
1847:     if (!value) break;
1848:     PetscOptionsStringToBool(value,dvalue);
1849:     PetscTokenFind(token,&value);
1850:     dvalue++;
1851:     n++;
1852:   }
1853:   PetscTokenDestroy(&token);
1854:   *nmax = n;
1855:   return(0);
1856: }

1860: /*@C
1861:    PetscOptionsGetReal - Gets the double precision value for a particular
1862:    option in the database.

1864:    Not Collective

1866:    Input Parameters:
1867: +  options - options database use NULL for default global database
1868: .  pre - string to prepend to each name or NULL
1869: -  name - the option one is seeking

1871:    Output Parameter:
1872: +  dvalue - the double value to return
1873: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

1877:    Level: beginner

1879:    Concepts: options database^has double

1881: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1882:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1883:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1884:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1885:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1886:           PetscOptionsFList(), PetscOptionsEList()
1887: @*/
1888: PetscErrorCode  PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
1889: {
1890:   char           *value;
1892:   PetscBool      flag;

1897:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1898:   if (flag) {
1899:     if (!value) {
1900:       if (set) *set = PETSC_FALSE;
1901:     } else {
1902:       if (set) *set = PETSC_TRUE;
1903:       PetscOptionsStringToReal(value,dvalue);
1904:     }
1905:   } else {
1906:     if (set) *set = PETSC_FALSE;
1907:   }
1908:   return(0);
1909: }

1913: /*@C
1914:    PetscOptionsGetScalar - Gets the scalar value for a particular
1915:    option in the database.

1917:    Not Collective

1919:    Input Parameters:
1920: +  options - options database use NULL for default global database
1921: .  pre - string to prepend to each name or NULL
1922: -  name - the option one is seeking

1924:    Output Parameter:
1925: +  dvalue - the double value to return
1926: -  set - PETSC_TRUE if found, else PETSC_FALSE

1928:    Level: beginner

1930:    Usage:
1931:    A complex number 2+3i must be specified with NO spaces

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

1935:    Concepts: options database^has scalar

1937: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1938:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1939:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1940:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1941:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1942:           PetscOptionsFList(), PetscOptionsEList()
1943: @*/
1944: PetscErrorCode  PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
1945: {
1946:   char           *value;
1947:   PetscBool      flag;

1953:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1954:   if (flag) {
1955:     if (!value) {
1956:       if (set) *set = PETSC_FALSE;
1957:     } else {
1958: #if !defined(PETSC_USE_COMPLEX)
1959:       PetscOptionsStringToReal(value,dvalue);
1960: #else
1961:       PetscOptionsStringToScalar(value,dvalue);
1962: #endif
1963:       if (set) *set = PETSC_TRUE;
1964:     }
1965:   } else { /* flag */
1966:     if (set) *set = PETSC_FALSE;
1967:   }
1968:   return(0);
1969: }

1973: /*@C
1974:    PetscOptionsGetRealArray - Gets an array of double precision values for a
1975:    particular option in the database.  The values must be separated with
1976:    commas with no intervening spaces.

1978:    Not Collective

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

1986:    Output Parameters:
1987: +  dvalue - the double values to return
1988: .  nmax - actual number of values retreived
1989: -  set - PETSC_TRUE if found, else PETSC_FALSE

1991:    Level: beginner

1993:    Concepts: options database^array of doubles

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

2013:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2014:   if (!flag) {
2015:     if (set) *set = PETSC_FALSE;
2016:     *nmax = 0;
2017:     return(0);
2018:   }
2019:   if (!value) {
2020:     if (set) *set = PETSC_TRUE;
2021:     *nmax = 0;
2022:     return(0);
2023:   }

2025:   if (set) *set = PETSC_TRUE;

2027:   PetscTokenCreate(value,',',&token);
2028:   PetscTokenFind(token,&value);
2029:   while (n < *nmax) {
2030:     if (!value) break;
2031:     PetscOptionsStringToReal(value,dvalue++);
2032:     PetscTokenFind(token,&value);
2033:     n++;
2034:   }
2035:   PetscTokenDestroy(&token);
2036:   *nmax = n;
2037:   return(0);
2038: }

2042: /*@C
2043:    PetscOptionsGetScalarArray - Gets an array of scalars for a
2044:    particular option in the database.  The values must be separated with
2045:    commas with no intervening spaces.

2047:    Not Collective

2049:    Input Parameters:
2050: +  options - options database use NULL for default global database
2051: .  pre - string to prepend to each name or NULL
2052: .  name - the option one is seeking
2053: -  nmax - maximum number of values to retrieve

2055:    Output Parameters:
2056: +  dvalue - the scalar values to return
2057: .  nmax - actual number of values retreived
2058: -  set - PETSC_TRUE if found, else PETSC_FALSE

2060:    Level: beginner

2062:    Concepts: options database^array of doubles

2064: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2065:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2066:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2067:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2068:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2069:           PetscOptionsFList(), PetscOptionsEList()
2070: @*/
2071: PetscErrorCode  PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
2072: {
2073:   char           *value;
2075:   PetscInt       n = 0;
2076:   PetscBool      flag;
2077:   PetscToken     token;

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

2094:   if (set) *set = PETSC_TRUE;

2096:   PetscTokenCreate(value,',',&token);
2097:   PetscTokenFind(token,&value);
2098:   while (n < *nmax) {
2099:     if (!value) break;
2100:     PetscOptionsStringToScalar(value,dvalue++);
2101:     PetscTokenFind(token,&value);
2102:     n++;
2103:   }
2104:   PetscTokenDestroy(&token);
2105:   *nmax = n;
2106:   return(0);
2107: }

2111: /*@C
2112:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2113:    option in the database.

2115:    Not Collective

2117:    Input Parameters:
2118: +  options - options database use NULL for default global database
2119: .  pre - string to prepend to each name or NULL
2120: .  name - the option one is seeking
2121: -  nmax - maximum number of values to retrieve

2123:    Output Parameter:
2124: +  dvalue - the integer values to return
2125: .  nmax - actual number of values retreived
2126: -  set - PETSC_TRUE if found, else PETSC_FALSE

2128:    Level: beginner

2130:    Notes:
2131:    The array can be passed as
2132:    a comma separated list:                                 0,1,2,3,4,5,6,7
2133:    a range (start-end+1):                                  0-8
2134:    a range with given increment (start-end+1:inc):         0-7:2
2135:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

2139:    Concepts: options database^array of ints

2141: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2142:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2143:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2144:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2145:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2146:           PetscOptionsFList(), PetscOptionsEList()
2147: @*/
2148: PetscErrorCode  PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
2149: {
2150:   char           *value;
2152:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2153:   size_t         len;
2154:   PetscBool      flag,foundrange;
2155:   PetscToken     token;

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

2172:   if (set) *set = PETSC_TRUE;

2174:   PetscTokenCreate(value,',',&token);
2175:   PetscTokenFind(token,&value);
2176:   while (n < *nmax) {
2177:     if (!value) break;

2179:     /* look for form  d-D where d and D are integers */
2180:     foundrange = PETSC_FALSE;
2181:     PetscStrlen(value,&len);
2182:     if (value[0] == '-') i=2;
2183:     else i=1;
2184:     for (;i<(int)len; i++) {
2185:       if (value[i] == '-') {
2186:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2187:         value[i] = 0;

2189:         PetscOptionsStringToInt(value,&start);
2190:         inc  = 1;
2191:         j    = i+1;
2192:         for (;j<(int)len; j++) {
2193:           if (value[j] == ':') {
2194:             value[j] = 0;

2196:             PetscOptionsStringToInt(value+j+1,&inc);
2197:             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);
2198:             break;
2199:           }
2200:         }
2201:         PetscOptionsStringToInt(value+i+1,&end);
2202:         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);
2203:         nvalues = (end-start)/inc + (end-start)%inc;
2204:         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);
2205:         for (;start<end; start+=inc) {
2206:           *dvalue = start; dvalue++;n++;
2207:         }
2208:         foundrange = PETSC_TRUE;
2209:         break;
2210:       }
2211:     }
2212:     if (!foundrange) {
2213:       PetscOptionsStringToInt(value,dvalue);
2214:       dvalue++;
2215:       n++;
2216:     }
2217:     PetscTokenFind(token,&value);
2218:   }
2219:   PetscTokenDestroy(&token);
2220:   *nmax = n;
2221:   return(0);
2222: }

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

2229:    Not Collective

2231:    Input Parameters:
2232: +  options - options database use NULL for default global database
2233: .  pre - option prefix or NULL
2234: .  name - option name
2235: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2236: -  nmax - maximum number of values to retrieve

2238:    Output Parameters:
2239: +  dvalue - the  enum values to return
2240: .  nmax - actual number of values retreived
2241: -  set - PETSC_TRUE if found, else PETSC_FALSE

2243:    Level: beginner

2245:    Concepts: options database

2247:    Notes:
2248:    The array must be passed as a comma separated list.

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

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

2254: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2255:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2256:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2257:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2258:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2259:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2260: @*/
2261: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2262: {
2263:   char           *svalue;
2264:   PetscInt       n = 0;
2265:   PetscEnum      evalue;
2266:   PetscBool      flag;
2267:   PetscToken     token;


2276:   PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2277:   if (!flag) {
2278:     if (set) *set = PETSC_FALSE;
2279:     *nmax = 0;
2280:     return(0);
2281:   }
2282:   if (!svalue) {
2283:     if (set) *set = PETSC_TRUE;
2284:     *nmax = 0;
2285:     return(0);
2286:   }
2287:   if (set) *set = PETSC_TRUE;

2289:   PetscTokenCreate(svalue,',',&token);
2290:   PetscTokenFind(token,&svalue);
2291:   while (svalue && n < *nmax) {
2292:     PetscEnumFind(list,svalue,&evalue,&flag);
2293:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2294:     dvalue[n++] = evalue;
2295:     PetscTokenFind(token,&svalue);
2296:   }
2297:   *nmax = n;
2298:   PetscTokenDestroy(&token);
2299:   return(0);
2300: }

2304: /*@C
2305:    PetscOptionsGetString - Gets the string value for a particular option in
2306:    the database.

2308:    Not Collective

2310:    Input Parameters:
2311: +  options - options database use NULL for default global database
2312: .  pre - string to prepend to name or NULL
2313: .  name - the option one is seeking
2314: -  len - maximum length of the string including null termination

2316:    Output Parameters:
2317: +  string - location to copy string
2318: -  set - PETSC_TRUE if found, else PETSC_FALSE

2320:    Level: beginner

2322:    Fortran Note:
2323:    The Fortran interface is slightly different from the C/C++
2324:    interface (len is not used).  Sample usage in Fortran follows
2325: .vb
2326:       character *20 string
2327:       integer   flg, ierr
2328:       call PetscOptionsGetString(PETSC_NULL_OBJECT,PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
2329: .ve

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

2333:    Concepts: options database^string

2335:     Note:
2336:       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).

2338: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2339:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2340:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2341:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2342:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2343:           PetscOptionsFList(), PetscOptionsEList()
2344: @*/
2345: PetscErrorCode  PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
2346: {
2347:   char           *value;
2349:   PetscBool      flag;

2354:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2355:   if (!flag) {
2356:     if (set) *set = PETSC_FALSE;
2357:   } else {
2358:     if (set) *set = PETSC_TRUE;
2359:     if (value) {
2360:       PetscStrncpy(string,value,len);
2361:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
2362:     } else {
2363:       PetscMemzero(string,len);
2364:     }
2365:   }
2366:   return(0);
2367: }

2371: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2372: {
2373:   char           *value;
2375:   PetscBool      flag;

2378:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2379:   if (flag) PetscFunctionReturn(value);
2380:   else return(0);
2381: }


2386: /*@C
2387:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2388:    option in the database. The values must be separated with commas with
2389:    no intervening spaces.

2391:    Not Collective

2393:    Input Parameters:
2394: +  options - options database use NULL for default global database
2395: .  pre - string to prepend to name or NULL
2396: .  name - the option one is seeking
2397: -  nmax - maximum number of strings

2399:    Output Parameter:
2400: +  strings - location to copy strings
2401: -  set - PETSC_TRUE if found, else PETSC_FALSE

2403:    Level: beginner

2405:    Notes:
2406:    The user should pass in an array of pointers to char, to hold all the
2407:    strings returned by this function.

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

2412:    Contributed by Matthew Knepley.

2414:    Concepts: options database^array of strings

2416: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2417:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2418:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2419:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2420:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2421:           PetscOptionsFList(), PetscOptionsEList()
2422: @*/
2423: PetscErrorCode  PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
2424: {
2425:   char           *value;
2427:   PetscInt       n;
2428:   PetscBool      flag;
2429:   PetscToken     token;

2434:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2435:   if (!flag) {
2436:     *nmax = 0;
2437:     if (set) *set = PETSC_FALSE;
2438:     return(0);
2439:   }
2440:   if (!value) {
2441:     *nmax = 0;
2442:     if (set) *set = PETSC_FALSE;
2443:     return(0);
2444:   }
2445:   if (!*nmax) {
2446:     if (set) *set = PETSC_FALSE;
2447:     return(0);
2448:   }
2449:   if (set) *set = PETSC_TRUE;

2451:   PetscTokenCreate(value,',',&token);
2452:   PetscTokenFind(token,&value);
2453:   n    = 0;
2454:   while (n < *nmax) {
2455:     if (!value) break;
2456:     PetscStrallocpy(value,&strings[n]);
2457:     PetscTokenFind(token,&value);
2458:     n++;
2459:   }
2460:   PetscTokenDestroy(&token);
2461:   *nmax = n;
2462:   return(0);
2463: }

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

2470:    Not Collective

2472:    Input Parameter:
2473: +   options - options database use NULL for default global database
2474: -   option - string name of option

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

2479:    Level: advanced

2481: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2482: @*/
2483: PetscErrorCode  PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2484: {
2485:   PetscInt       i;

2489:   options = options ? options : defaultoptions;
2490:   *used = PETSC_FALSE;
2491:   for (i=0; i<options->N; i++) {
2492:     PetscStrcmp(options->names[i],option,used);
2493:     if (*used) {
2494:       *used = options->used[i];
2495:       break;
2496:     }
2497:   }
2498:   return(0);
2499: }

2503: /*@C
2504:    PetscOptionsAllUsed - Returns a count of the number of options in the
2505:    database that have never been selected.

2507:    Not Collective

2509:    Input Parameter:
2510: .  options - options database use NULL for default global database

2512:    Output Parameter:
2513: .   N - count of options not used

2515:    Level: advanced

2517: .seealso: PetscOptionsView()
2518: @*/
2519: PetscErrorCode  PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2520: {
2521:   PetscInt     i,n = 0;

2524:   options = options ? options : defaultoptions;
2525:   for (i=0; i<options->N; i++) {
2526:     if (!options->used[i]) n++;
2527:   }
2528:   *N = n;
2529:   return(0);
2530: }

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

2537:   Not collective

2539:    Input Parameter:
2540: .  options - options database use NULL for default global database

2542:    Options Database Key:
2543: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

2545:   Level: advanced

2547: .seealso: PetscOptionsAllUsed()
2548: @*/
2549: PetscErrorCode  PetscOptionsLeft(PetscOptions options)
2550: {
2552:   PetscInt       i;

2555:   options = options ? options : defaultoptions;
2556:   for (i=0; i<options->N; i++) {
2557:     if (!options->used[i]) {
2558:       if (options->values[i]) {
2559:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2560:       } else {
2561:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2562:       }
2563:     }
2564:   }
2565:   return(0);
2566: }

2570: /*@
2571:     PetscOptionsCreate - Creates the empty options database.

2573:   Output Parameter:
2574: .   options - Options database object

2576:   Level: advanced

2578: @*/
2579: PetscErrorCode  PetscOptionsCreate(PetscOptions *options)
2580: {
2581:   *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2582:   if (!options) return PETSC_ERR_MEM;
2583:   (*options)->namegiven      = PETSC_FALSE;
2584:   (*options)->N              = 0;
2585:   (*options)->Naliases       = 0;
2586:   (*options)->numbermonitors = 0;
2587:   return 0;
2588: }

2592: /*
2593:     PetscOptionsCreateDefault - Creates the default global options database

2595: */
2596: PetscErrorCode  PetscOptionsCreateDefault(void)
2597: {

2600:   if (!defaultoptions) {
2601:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2602:   }
2603:   return 0;
2604: }

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

2611:    Collective on PETSC_COMM_WORLD

2613:    Input Parameter:
2614: .  options - options database use NULL for default global database

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

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

2626:    Level: intermediate

2628: .keywords: set, options, database
2629: @*/
2630: PetscErrorCode  PetscOptionsSetFromOptions(PetscOptions options)
2631: {
2632:   PetscBool      flgc = PETSC_FALSE,flgm;
2634:   char           monfilename[PETSC_MAX_PATH_LEN];
2635:   PetscViewer    monviewer;

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

2641:      options = options ? options : defaultoptions;
2642:   */
2643:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2644:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2645:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2646:   PetscOptionsEnd();
2647:   if (flgm) {
2648:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2649:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2650:   }
2651:   if (flgc) { PetscOptionsMonitorCancel(); }
2652:   return(0);
2653: }


2658: /*@C
2659:    PetscOptionsMonitorDefault - Print all options set value events.

2661:    Logically Collective on PETSC_COMM_WORLD

2663:    Input Parameters:
2664: +  name  - option name string
2665: .  value - option value string
2666: -  dummy - an ASCII viewer

2668:    Level: intermediate

2670: .keywords: PetscOptions, default, monitor

2672: .seealso: PetscOptionsMonitorSet()
2673: @*/
2674: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2675: {
2677:   PetscViewer    viewer = (PetscViewer) dummy;

2680:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2681:   return(0);
2682: }

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

2690:    Not collective

2692:    Input Parameters:
2693: +  monitor - pointer to function (if this is NULL, it turns off monitoring
2694: .  mctx    - [optional] context for private data for the
2695:              monitor routine (use NULL if no context is desired)
2696: -  monitordestroy - [optional] routine that frees monitor context
2697:           (may be NULL)

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

2702: +  name - option name string
2703: .  value - option value string
2704: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

2706:    Options Database Keys:
2707: +    -options_monitor    - sets PetscOptionsMonitorDefault()
2708: -    -options_monitor_cancel - cancels all monitors that have
2709:                           been hardwired into a code by
2710:                           calls to PetscOptionsMonitorSet(), but
2711:                           does not cancel those set via
2712:                           the options database.

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

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

2723:    Level: beginner

2725: .keywords: PetscOptions, set, monitor

2727: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2728: @*/
2729: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2730: {
2731:   PetscOptions options = defaultoptions;

2734:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2735:   options->monitor[options->numbermonitors]          = monitor;
2736:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
2737:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2738:   return(0);
2739: }

2743: /*@
2744:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2746:    Not collective

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

2753:    Level: intermediate

2755: .keywords: PetscOptions, set, monitor

2757: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2758: @*/
2759: PetscErrorCode  PetscOptionsMonitorCancel(void)
2760: {
2762:   PetscInt       i;
2763:   PetscOptions   options = defaultoptions;

2766:   for (i=0; i<options->numbermonitors; i++) {
2767:     if (options->monitordestroy[i]) {
2768:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
2769:     }
2770:   }
2771:   options->numbermonitors = 0;
2772:   return(0);
2773: }

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

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

2782:   Collective on PetscObject

2784:   Input Parameters:
2785: + obj   - the object
2786: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
2787: - optionname - option to activate viewing

2789:   Level: intermediate

2791: @*/
2792: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2793: {
2794:   PetscErrorCode    ierr;
2795:   PetscViewer       viewer;
2796:   PetscBool         flg;
2797:   static PetscBool  incall = PETSC_FALSE;
2798:   PetscViewerFormat format;
2799:   char              *prefix;

2802:   if (incall) return(0);
2803:   incall = PETSC_TRUE;
2804:   prefix = bobj ? bobj->prefix : obj->prefix;
2805:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2806:   if (flg) {
2807:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2808:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2809:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2810:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2811:   }
2812:   incall = PETSC_FALSE;
2813:   return(0);
2814: }