Actual source code: options.c

petsc-3.7.3 2016-08-01
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];

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

488:     PetscFixFilename(file,fname);
489:     fd   = fopen(fname,"r");
490:     if (fd) {
491:       PetscSegBuffer vseg,aseg;
492:       PetscSegBufferCreate(1,4000,&vseg);
493:       PetscSegBufferCreate(1,2000,&aseg);

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

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

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

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

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

588:   if (acnt) {
589:     PetscToken token;
590:     char       *first,*second;

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

602:   if (cnt) {
603:     PetscOptionsInsertString(options,vstring);
604:   }
605:   PetscFree(packed);
606:   return(0);
607: }

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

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

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

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


676: /*@C
677:    PetscOptionsInsert - Inserts into the options database from the command line,
678:                    the environmental variable and a file.

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

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

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

695:    Level: advanced

697:    Concepts: options database^adding

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

709: 
711:   if (!options) {
712:     if (!defaultoptions) {
713:       PetscOptionsCreateDefault();
714:     }
715:     options = defaultoptions;
716:   }
717:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

719:   options->argc = (argc) ? *argc : 0;
720:   options->args = (args) ? *args : NULL;

722:   if (file && file[0]) {
723:     char fullpath[PETSC_MAX_PATH_LEN];

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

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

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

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

779: /*@C
780:    PetscOptionsView - Prints the options that have been loaded. This is
781:    useful for debugging purposes.

783:    Logically Collective on PetscViewer

785:    Input Parameter:
786: .  viewer - must be an PETSCVIEWERASCII viewer

788:    Options Database Key:
789: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

791:    Level: advanced

793:    Concepts: options database^printing

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

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

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

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

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

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

858:    Not Collective

860:    Input Paramter:
861: .  options - the options database, use NULL for the default global database

863:    Output Parameter:
864: .  copts - pointer where string pointer is stored

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

868:    Level: advanced

870:    Concepts: options database^listing

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

882:   options = options ? options : defaultoptions;

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

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

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

915:    Input Parameter:
916: +  options - options database, or NULL for the default global database
917: -  prefix - The string to append to the existing prefix

919:    Options Database Keys:
920:  +   -prefix_push <some_prefix_> - push the given prefix
921:  -   -prefix_pop - pop the last prefix

923:    Notes:
924:    It is common to use this in conjunction with -options_file as in

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

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

930: Level: advanced

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

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

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

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

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

972:   Input Parameters:
973: .  options - options database, or NULL for the default global database

975:    Level: advanced

977: .seealso: PetscOptionsPrefixPush()
978: @*/
979: PetscErrorCode  PetscOptionsPrefixPop(PetscOptions options)
980: {
981:   PetscInt offset;

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

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

997:   Input Parameters:
998: .  options - options database, use NULL for the default global database

1000:    Level: developer

1002: .seealso: PetscOptionsInsert()
1003: @*/
1004: PetscErrorCode  PetscOptionsClear(PetscOptions options)
1005: {
1006:   PetscInt     i;

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

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

1030:   Input Parameters:
1031: .  obj  - the PetscObject

1033:    Level: developer

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

1038: .seealso: PetscOptionsInsert()
1039: @*/
1040: PetscErrorCode  PetscObjectSetPrintedOptions(PetscObject obj)
1041: {
1043:   obj->optionsprinted = PETSC_TRUE;
1044:   return(0);
1045: }

1049: /*@
1050:     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.

1052:   Input Parameters:
1053: +  pobj - the parent object
1054: -  obj  - the PetscObject

1056:    Level: developer

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

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

1063: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1064: @*/
1065: PetscErrorCode  PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1066: {
1068:   PetscMPIInt    prank,size;

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

1079: /*@
1080:     PetscOptionsDestroy - Destroys an option database.

1082:   Input Parameter:
1083: .  options - the PetscOptions object

1085:    Level: developer

1087: .seealso: PetscOptionsInsert()
1088: @*/
1089: PetscErrorCode  PetscOptionsDestroy(PetscOptions *options)
1090: {

1094:   PetscOptionsClear(*options);
1095:   free(*options);
1096:   *options = NULL;
1097:   return(0);
1098: }

1102: PetscErrorCode  PetscOptionsDestroyDefault(void)
1103: {

1106:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1107:   return 0;
1108: }


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

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

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

1125:    Level: intermediate

1127:    Note:
1128:    This function can be called BEFORE PetscInitialize()

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

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

1135:   Concepts: options database^adding option

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

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

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

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

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

1184:   N     = options->N;
1185:   n     = N;
1186:   names = options->names;

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

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

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

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

1243:    Input Parameter:
1244: +  options - options database, use NULL for the default global database
1245: .  name - name of option, this SHOULD have the - prepended

1247:    Level: intermediate

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

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

1264:   N     = options->N; n = 0;
1265:   names = options->names;

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

1277:     n++;
1278:   }
1279:   if (n == N) return(0); /* it was not listed */

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

1293: /*@C
1294:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1299:    Input Parameters:
1300: +  options - options database or NULL for default global database
1301: .  inewname - the alias
1302: -  ioldname - the name that alias will refer to

1304:    Level: advanced

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

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

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

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

1348:   options = options ? options : defaultoptions;
1349:   N     = options->N;
1350:   names = options->names;

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

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

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

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

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

1435:   options = options ? options : defaultoptions;
1436:   N     = options->N;
1437:   names = options->names;

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

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

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

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

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

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

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

1497:    Level: advanced

1499:    Concepts: options database^rejecting option

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

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

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

1529:    Not Collective

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

1536:    Output Parameters:
1537: .  set - PETSC_TRUE if found else PETSC_FALSE.

1539:    Level: beginner

1541:    Concepts: options database^has option name

1543:    Notes: Name cannot be simply -h

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

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

1561:   options = options ? options : defaultoptions;
1562:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1563:   if (set) *set = flag;
1564:   return(0);
1565: }

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

1572:    Not Collective

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

1579:    Output Parameter:
1580: +  ivalue - the integer value to return
1581: -  set - PETSC_TRUE if found, else PETSC_FALSE

1583:    Level: beginner

1585:    Concepts: options database^has int

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

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

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

1624:    Not Collective

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

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

1637:    Level: intermediate

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

1641:    Concepts: options database^list

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

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

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

1681:    Not Collective

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

1690:    Output Parameter:
1691: +  value - the  value to return
1692: -  set - PETSC_TRUE if found, else PETSC_FALSE

1694:    Level: beginner

1696:    Concepts: options database

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

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

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

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

1732: /*@C
1733:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1734:             option in the database.

1736:    Not Collective

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

1743:    Output Parameter:
1744: +  ivalue - the logical value to return
1745: -  set - PETSC_TRUE  if found, else PETSC_FALSE

1747:    Level: beginner

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

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

1756:    Concepts: options database^has logical

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

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

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

1796:    Not Collective

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

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

1809:    Level: beginner

1811:    Concepts: options database^array of ints

1813:    Notes:
1814:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1815:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

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

1839:   if (set) *set = PETSC_TRUE;

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

1857: /*@C
1858:    PetscOptionsGetReal - Gets the double precision value for a particular
1859:    option in the database.

1861:    Not Collective

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

1868:    Output Parameter:
1869: +  dvalue - the double value to return
1870: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

1874:    Level: beginner

1876:    Concepts: options database^has double

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

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

1910: /*@C
1911:    PetscOptionsGetScalar - Gets the scalar value for a particular
1912:    option in the database.

1914:    Not Collective

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

1921:    Output Parameter:
1922: +  dvalue - the double value to return
1923: -  set - PETSC_TRUE if found, else PETSC_FALSE

1925:    Level: beginner

1927:    Usage:
1928:    A complex number 2+3i must be specified with NO spaces

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

1932:    Concepts: options database^has scalar

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

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

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

1975:    Not Collective

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

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

1988:    Level: beginner

1990:    Concepts: options database^array of doubles

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

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

2022:   if (set) *set = PETSC_TRUE;

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

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

2044:    Not Collective

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

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

2057:    Level: beginner

2059:    Concepts: options database^array of doubles

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

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

2091:   if (set) *set = PETSC_TRUE;

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

2108: /*@C
2109:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2110:    option in the database.

2112:    Not Collective

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

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

2125:    Level: beginner

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

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

2136:    Concepts: options database^array of ints

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

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

2169:   if (set) *set = PETSC_TRUE;

2171:   PetscTokenCreate(value,',',&token);
2172:   PetscTokenFind(token,&value);
2173:   while (n < *nmax) {
2174:     if (!value) break;

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

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

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

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

2226:    Not Collective

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

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

2240:    Level: beginner

2242:    Concepts: options database

2244:    Notes:
2245:    The array must be passed as a comma separated list.

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

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

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


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

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

2301: /*@C
2302:    PetscOptionsGetString - Gets the string value for a particular option in
2303:    the database.

2305:    Not Collective

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

2313:    Output Parameters:
2314: +  string - location to copy string
2315: -  set - PETSC_TRUE if found, else PETSC_FALSE

2317:    Level: beginner

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

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

2330:    Concepts: options database^string

2332:     Note:
2333:       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).

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

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

2368: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2369: {
2370:   char           *value;
2372:   PetscBool      flag;

2375:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2376:   if (flag) PetscFunctionReturn(value);
2377:   else return(0);
2378: }


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

2388:    Not Collective

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

2396:    Output Parameter:
2397: +  strings - location to copy strings
2398: -  set - PETSC_TRUE if found, else PETSC_FALSE

2400:    Level: beginner

2402:    Notes:
2403:    The user should pass in an array of pointers to char, to hold all the
2404:    strings returned by this function.

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

2409:    Contributed by Matthew Knepley.

2411:    Concepts: options database^array of strings

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

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

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

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

2467:    Not Collective

2469:    Input Parameter:
2470: +   options - options database use NULL for default global database
2471: -   option - string name of option

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

2476:    Level: advanced

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

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

2500: /*@C
2501:    PetscOptionsAllUsed - Returns a count of the number of options in the
2502:    database that have never been selected.

2504:    Not Collective

2506:    Input Parameter:
2507: .  options - options database use NULL for default global database

2509:    Output Parameter:
2510: .   N - count of options not used

2512:    Level: advanced

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

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

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

2534:   Not collective

2536:    Input Parameter:
2537: .  options - options database use NULL for default global database

2539:    Options Database Key:
2540: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

2542:   Level: advanced

2544: .seealso: PetscOptionsAllUsed()
2545: @*/
2546: PetscErrorCode  PetscOptionsLeft(PetscOptions options)
2547: {
2549:   PetscInt       i;

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

2567: /*@
2568:     PetscOptionsCreate - Creates the empty options database.

2570:   Output Parameter:
2571: .   options - Options database object

2573:   Level: advanced

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

2589: /*
2590:     PetscOptionsCreateDefault - Creates the default global options database

2592: */
2593: PetscErrorCode  PetscOptionsCreateDefault(void)
2594: {

2597:   if (!defaultoptions) {
2598:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2599:   }
2600:   return 0;
2601: }

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

2608:    Collective on PETSC_COMM_WORLD

2610:    Input Parameter:
2611: .  options - options database use NULL for default global database

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

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

2623:    Level: intermediate

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

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

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


2655: /*@C
2656:    PetscOptionsMonitorDefault - Print all options set value events.

2658:    Logically Collective on PETSC_COMM_WORLD

2660:    Input Parameters:
2661: +  name  - option name string
2662: .  value - option value string
2663: -  dummy - an ASCII viewer

2665:    Level: intermediate

2667: .keywords: PetscOptions, default, monitor

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

2677:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2678:   return(0);
2679: }

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

2687:    Not collective

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

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

2699: +  name - option name string
2700: .  value - option value string
2701: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

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

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

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

2720:    Level: beginner

2722: .keywords: PetscOptions, set, monitor

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

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

2740: /*@
2741:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2743:    Not collective

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

2750:    Level: intermediate

2752: .keywords: PetscOptions, set, monitor

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

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

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

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

2779:   Collective on PetscObject

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

2786:   Level: intermediate

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

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