Actual source code: options.c

petsc-3.7.0 2016-04-25
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:     PetscOptionsDestroy - Destroys an option database.

1030:   Input Parameter:
1031: .  options - the PetscOptions object

1033:    Level: developer

1035: .seealso: PetscOptionsInsert()
1036: @*/
1037: PetscErrorCode  PetscOptionsDestroy(PetscOptions *options)
1038: {

1042:   PetscOptionsClear(*options);
1043:   free(*options);
1044:   *options = NULL;
1045:   return(0);
1046: }

1050: PetscErrorCode  PetscOptionsDestroyDefault(void)
1051: {

1054:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1055:   return 0;
1056: }


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

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

1068:    Input Parameters:
1069: +  options - options database, use NULL for the default global database
1070: .  name - name of option, this SHOULD have the - prepended
1071: -  value - the option value (not used for all options)

1073:    Level: intermediate

1075:    Note:
1076:    This function can be called BEFORE PetscInitialize()

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

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

1083:   Concepts: options database^adding option

1085: .seealso: PetscOptionsInsert()
1086: @*/
1087: PetscErrorCode  PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1088: {
1089:   size_t         len;
1091:   PetscInt       N,n,i;
1092:   char           **names;
1093:   char           fullname[2048];
1094:   const char     *name = iname;
1095:   int            gt,match;

1097:   if (!options) {
1098:     if (!defaultoptions) {
1099:       PetscOptionsCreateDefault();
1100:       if (ierr) return ierr;
1101:     }
1102:     options = defaultoptions;
1103:   }

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

1109:   name++; /* skip starting hyphen */
1110:   if (options->prefixind > 0) {
1111:     strncpy(fullname,options->prefix,sizeof(fullname));
1112:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1113:     name = fullname;
1114:   }

1116:   /* check against aliases */
1117:   N = options->Naliases;
1118:   for (i=0; i<N; i++) {
1119: #if defined(PETSC_HAVE_STRCASECMP)
1120:     match = strcasecmp(options->aliases1[i],name);
1121: #elif defined(PETSC_HAVE_STRICMP)
1122:     match = stricmp(options->aliases1[i],name);
1123: #else
1124:     Error
1125: #endif
1126:     if (!match) {
1127:       name = options->aliases2[i];
1128:       break;
1129:     }
1130:   }

1132:   N     = options->N;
1133:   n     = N;
1134:   names = options->names;

1136:   for (i=0; i<N; i++) {
1137: #if defined(PETSC_HAVE_STRCASECMP)
1138:     gt = strcasecmp(names[i],name);
1139: #elif defined(PETSC_HAVE_STRICMP)
1140:     gt = stricmp(names[i],name);
1141: #else
1142:     Error
1143: #endif
1144:     if (!gt) {
1145:       if (options->values[i]) free(options->values[i]);
1146:       len = value ? strlen(value) : 0;
1147:       if (len) {
1148:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
1149:         if (!options->values[i]) return PETSC_ERR_MEM;
1150:         strcpy(options->values[i],value);
1151:       } else options->values[i] = 0;
1152:       return 0;
1153:     } else if (gt > 0) {
1154:       n = i;
1155:       break;
1156:     }
1157:   }
1158:   if (N >= MAXOPTIONS) abort();

1160:   /* shift remaining values down 1 */
1161:   for (i=N; i>n; i--) {
1162:     options->names[i]  = options->names[i-1];
1163:     options->values[i] = options->values[i-1];
1164:     options->used[i]   = options->used[i-1];
1165:   }
1166:   /* insert new name and value */
1167:   len = strlen(name);
1168:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
1169:   if (!options->names[n]) return PETSC_ERR_MEM;
1170:   strcpy(options->names[n],name);
1171:   len = value ? strlen(value) : 0;
1172:   if (len) {
1173:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
1174:     if (!options->values[n]) return PETSC_ERR_MEM;
1175:     strcpy(options->values[n],value);
1176:   } else options->values[n] = NULL;
1177:   options->used[n] = PETSC_FALSE;
1178:   options->N++;
1179:   return 0;
1180: }

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

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

1191:    Input Parameter:
1192: +  options - options database, use NULL for the default global database
1193: .  name - name of option, this SHOULD have the - prepended

1195:    Level: intermediate

1197:    Concepts: options database^removing option
1198: .seealso: PetscOptionsInsert()
1199: @*/
1200: PetscErrorCode  PetscOptionsClearValue(PetscOptions options,const char iname[])
1201: {
1203:   PetscInt       N,n,i;
1204:   char           **names,*name=(char*)iname;
1205:   PetscBool      gt,match;

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

1212:   N     = options->N; n = 0;
1213:   names = options->names;

1215:   for (i=0; i<N; i++) {
1216:     PetscStrcasecmp(names[i],name,&match);
1217:     PetscStrgrt(names[i],name,&gt);
1218:     if (match) {
1219:       if (options->names[i])  free(options->names[i]);
1220:       if (options->values[i]) free(options->values[i]);
1221:       PetscOptionsMonitor(name,"");
1222:       break;
1223:     } else if (gt) return(0); /* it was not listed */

1225:     n++;
1226:   }
1227:   if (n == N) return(0); /* it was not listed */

1229:   /* shift remaining values down 1 */
1230:   for (i=n; i<N-1; i++) {
1231:     options->names[i]  = options->names[i+1];
1232:     options->values[i] = options->values[i+1];
1233:     options->used[i]   = options->used[i+1];
1234:   }
1235:   options->N--;
1236:   return(0);
1237: }

1241: /*@C
1242:    PetscOptionsSetAlias - Makes a key and alias for another key

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

1247:    Input Parameters:
1248: +  options - options database or NULL for default global database
1249: .  inewname - the alias
1250: -  ioldname - the name that alias will refer to

1252:    Level: advanced

1254: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1255:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1256:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1257:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1258:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1259:           PetscOptionsFList(), PetscOptionsEList()
1260: @*/
1261: PetscErrorCode  PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1262: {
1264:   PetscInt       n = options->Naliases;
1265:   size_t         len;
1266:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

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

1274:   newname++; oldname++;
1275:   PetscStrlen(newname,&len);
1276:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1277:   PetscStrcpy(options->aliases1[n],newname);
1278:   PetscStrlen(oldname,&len);
1279:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1280:   PetscStrcpy(options->aliases2[n],oldname);
1281:   options->Naliases++;
1282:   return(0);
1283: }

1287: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool  *flg)
1288: {
1290:   PetscInt       i,N;
1291:   size_t         len;
1292:   char           **names,tmp[256];
1293:   PetscBool      match;

1296:   options = options ? options : defaultoptions;
1297:   N     = options->N;
1298:   names = options->names;

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

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

1324:     PetscMemcpy(key+1,tmp,sizeof(tmp));
1325:     PetscOptionsValidKey(key,&valid);
1326:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1327:   }
1328: #endif

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

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

1383:   options = options ? options : defaultoptions;
1384:   N     = options->N;
1385:   names = options->names;

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

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

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

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

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

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

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

1445:    Level: advanced

1447:    Concepts: options database^rejecting option

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

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

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

1477:    Not Collective

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

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

1487:    Level: beginner

1489:    Concepts: options database^has option name

1491:    Notes: Name cannot be simply -h

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

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

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

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

1520:    Not Collective

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

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

1531:    Level: beginner

1533:    Concepts: options database^has int

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

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

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

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: .  opt - option name
1578: .  list - the possible choices (one of these must be selected, anything else is invalid)
1579: .  ntext - number of choices

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

1585:    Level: intermediate

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

1589:    Concepts: options database^list

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

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

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

1629:    Not Collective

1631:    Input Parameters:
1632: +  options - options database use NULL for default global database
1633: .  pre - option prefix or NULL
1634: .  opt - option name
1635: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1636: -  defaultv - the default (current) value

1638:    Output Parameter:
1639: +  value - the  value to return
1640: -  set - PETSC_TRUE if found, else PETSC_FALSE

1642:    Level: beginner

1644:    Concepts: options database

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

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

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

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

1680: /*@C
1681:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1682:             option in the database.

1684:    Not Collective

1686:    Input Parameters:
1687: +  options - options database use NULL for default global database
1688: .  pre - the string to prepend to the name or NULL
1689: -  name - the option one is seeking

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

1695:    Level: beginner

1697:    Notes:
1698:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1699:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1704:    Concepts: options database^has logical

1706: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1707:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1708:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1709:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1710:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1711:           PetscOptionsFList(), PetscOptionsEList()
1712: @*/
1713: PetscErrorCode  PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
1714: {
1715:   char           *value;
1716:   PetscBool      flag;

1722:   options = options ? options : defaultoptions;
1723:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1724:   if (flag) {
1725:     if (set) *set = PETSC_TRUE;
1726:     if (!value) {
1727:       if (ivalue) *ivalue = PETSC_TRUE;
1728:     } else {
1729:       PetscOptionsStringToBool(value, ivalue);
1730:     }
1731:   } else {
1732:     if (set) *set = PETSC_FALSE;
1733:   }
1734:   return(0);
1735: }

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

1744:    Not Collective

1746:    Input Parameters:
1747: +  options - options database use NULL for default global database
1748: .  pre - string to prepend to each name or NULL
1749: .  name - the option one is seeking
1750: -  nmax - maximum number of values to retrieve

1752:    Output Parameter:
1753: +  dvalue - the integer values to return
1754: .  nmax - actual number of values retreived
1755: -  set - PETSC_TRUE if found, else PETSC_FALSE

1757:    Level: beginner

1759:    Concepts: options database^array of ints

1761:    Notes:
1762:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1763:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1765: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1766:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1767:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1768:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1769:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1770:           PetscOptionsFList(), PetscOptionsEList()
1771: @*/
1772: PetscErrorCode  PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
1773: {
1774:   char           *value;
1776:   PetscInt       n = 0;
1777:   PetscBool      flag;
1778:   PetscToken     token;

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

1787:   if (set) *set = PETSC_TRUE;

1789:   PetscTokenCreate(value,',',&token);
1790:   PetscTokenFind(token,&value);
1791:   while (n < *nmax) {
1792:     if (!value) break;
1793:     PetscOptionsStringToBool(value,dvalue);
1794:     PetscTokenFind(token,&value);
1795:     dvalue++;
1796:     n++;
1797:   }
1798:   PetscTokenDestroy(&token);
1799:   *nmax = n;
1800:   return(0);
1801: }

1805: /*@C
1806:    PetscOptionsGetReal - Gets the double precision value for a particular
1807:    option in the database.

1809:    Not Collective

1811:    Input Parameters:
1812: +  options - options database use NULL for default global database
1813: .  pre - string to prepend to each name or NULL
1814: -  name - the option one is seeking

1816:    Output Parameter:
1817: +  dvalue - the double value to return
1818: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

1822:    Level: beginner

1824:    Concepts: options database^has double

1826: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1827:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1828:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1829:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1830:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1831:           PetscOptionsFList(), PetscOptionsEList()
1832: @*/
1833: PetscErrorCode  PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
1834: {
1835:   char           *value;
1837:   PetscBool      flag;

1842:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1843:   if (flag) {
1844:     if (!value) {
1845:       if (set) *set = PETSC_FALSE;
1846:     } else {
1847:       if (set) *set = PETSC_TRUE;
1848:       PetscOptionsStringToReal(value,dvalue);
1849:     }
1850:   } else {
1851:     if (set) *set = PETSC_FALSE;
1852:   }
1853:   return(0);
1854: }

1858: /*@C
1859:    PetscOptionsGetScalar - Gets the scalar value for a particular
1860:    option in the database.

1862:    Not Collective

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

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

1873:    Level: beginner

1875:    Usage:
1876:    A complex number 2+3i must be specified with NO spaces

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

1880:    Concepts: options database^has scalar

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

1898:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1899:   if (flag) {
1900:     if (!value) {
1901:       if (set) *set = PETSC_FALSE;
1902:     } else {
1903: #if !defined(PETSC_USE_COMPLEX)
1904:       PetscOptionsStringToReal(value,dvalue);
1905: #else
1906:       PetscOptionsStringToScalar(value,dvalue);
1907: #endif
1908:       if (set) *set = PETSC_TRUE;
1909:     }
1910:   } else { /* flag */
1911:     if (set) *set = PETSC_FALSE;
1912:   }
1913:   return(0);
1914: }

1918: /*@C
1919:    PetscOptionsGetRealArray - Gets an array of double precision values for a
1920:    particular option in the database.  The values must be separated with
1921:    commas with no intervening spaces.

1923:    Not Collective

1925:    Input Parameters:
1926: +  options - options database use NULL for default global database
1927: .  pre - string to prepend to each name or NULL
1928: .  name - the option one is seeking
1929: -  nmax - maximum number of values to retrieve

1931:    Output Parameters:
1932: +  dvalue - the double values to return
1933: .  nmax - actual number of values retreived
1934: -  set - PETSC_TRUE if found, else PETSC_FALSE

1936:    Level: beginner

1938:    Concepts: options database^array of doubles

1940: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1941:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1942:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1943:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1944:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1945:           PetscOptionsFList(), PetscOptionsEList()
1946: @*/
1947: PetscErrorCode  PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool  *set)
1948: {
1949:   char           *value;
1951:   PetscInt       n = 0;
1952:   PetscBool      flag;
1953:   PetscToken     token;

1958:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1959:   if (!flag) {
1960:     if (set) *set = PETSC_FALSE;
1961:     *nmax = 0;
1962:     return(0);
1963:   }
1964:   if (!value) {
1965:     if (set) *set = PETSC_TRUE;
1966:     *nmax = 0;
1967:     return(0);
1968:   }

1970:   if (set) *set = PETSC_TRUE;

1972:   PetscTokenCreate(value,',',&token);
1973:   PetscTokenFind(token,&value);
1974:   while (n < *nmax) {
1975:     if (!value) break;
1976:     PetscOptionsStringToReal(value,dvalue++);
1977:     PetscTokenFind(token,&value);
1978:     n++;
1979:   }
1980:   PetscTokenDestroy(&token);
1981:   *nmax = n;
1982:   return(0);
1983: }

1987: /*@C
1988:    PetscOptionsGetScalarArray - Gets an array of scalars for a
1989:    particular option in the database.  The values must be separated with
1990:    commas with no intervening spaces.

1992:    Not Collective

1994:    Input Parameters:
1995: +  options - options database use NULL for default global database
1996: .  pre - string to prepend to each name or NULL
1997: .  name - the option one is seeking
1998: -  nmax - maximum number of values to retrieve

2000:    Output Parameters:
2001: +  dvalue - the scalar values to return
2002: .  nmax - actual number of values retreived
2003: -  set - PETSC_TRUE if found, else PETSC_FALSE

2005:    Level: beginner

2007:    Concepts: options database^array of doubles

2009: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2010:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2011:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2012:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2013:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2014:           PetscOptionsFList(), PetscOptionsEList()
2015: @*/
2016: PetscErrorCode  PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
2017: {
2018:   char           *value;
2020:   PetscInt       n = 0;
2021:   PetscBool      flag;
2022:   PetscToken     token;

2027:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2028:   if (!flag) {
2029:     if (set) *set = PETSC_FALSE;
2030:     *nmax = 0;
2031:     return(0);
2032:   }
2033:   if (!value) {
2034:     if (set) *set = PETSC_TRUE;
2035:     *nmax = 0;
2036:     return(0);
2037:   }

2039:   if (set) *set = PETSC_TRUE;

2041:   PetscTokenCreate(value,',',&token);
2042:   PetscTokenFind(token,&value);
2043:   while (n < *nmax) {
2044:     if (!value) break;
2045:     PetscOptionsStringToScalar(value,dvalue++);
2046:     PetscTokenFind(token,&value);
2047:     n++;
2048:   }
2049:   PetscTokenDestroy(&token);
2050:   *nmax = n;
2051:   return(0);
2052: }

2056: /*@C
2057:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
2058:    option in the database.

2060:    Not Collective

2062:    Input Parameters:
2063: +  options - options database use NULL for default global database
2064: .  pre - string to prepend to each name or NULL
2065: .  name - the option one is seeking
2066: -  nmax - maximum number of values to retrieve

2068:    Output Parameter:
2069: +  dvalue - the integer values to return
2070: .  nmax - actual number of values retreived
2071: -  set - PETSC_TRUE if found, else PETSC_FALSE

2073:    Level: beginner

2075:    Notes:
2076:    The array can be passed as
2077:    a comma separated list:                                 0,1,2,3,4,5,6,7
2078:    a range (start-end+1):                                  0-8
2079:    a range with given increment (start-end+1:inc):         0-7:2
2080:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

2084:    Concepts: options database^array of ints

2086: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2087:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2088:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2089:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2090:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2091:           PetscOptionsFList(), PetscOptionsEList()
2092: @*/
2093: PetscErrorCode  PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
2094: {
2095:   char           *value;
2097:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
2098:   size_t         len;
2099:   PetscBool      flag,foundrange;
2100:   PetscToken     token;

2105:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2106:   if (!flag) {
2107:     if (set) *set = PETSC_FALSE;
2108:     *nmax = 0;
2109:     return(0);
2110:   }
2111:   if (!value) {
2112:     if (set) *set = PETSC_TRUE;
2113:     *nmax = 0;
2114:     return(0);
2115:   }

2117:   if (set) *set = PETSC_TRUE;

2119:   PetscTokenCreate(value,',',&token);
2120:   PetscTokenFind(token,&value);
2121:   while (n < *nmax) {
2122:     if (!value) break;

2124:     /* look for form  d-D where d and D are integers */
2125:     foundrange = PETSC_FALSE;
2126:     PetscStrlen(value,&len);
2127:     if (value[0] == '-') i=2;
2128:     else i=1;
2129:     for (;i<(int)len; i++) {
2130:       if (value[i] == '-') {
2131:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2132:         value[i] = 0;

2134:         PetscOptionsStringToInt(value,&start);
2135:         inc  = 1;
2136:         j    = i+1;
2137:         for (;j<(int)len; j++) {
2138:           if (value[j] == ':') {
2139:             value[j] = 0;

2141:             PetscOptionsStringToInt(value+j+1,&inc);
2142:             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);
2143:             break;
2144:           }
2145:         }
2146:         PetscOptionsStringToInt(value+i+1,&end);
2147:         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);
2148:         nvalues = (end-start)/inc + (end-start)%inc;
2149:         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);
2150:         for (;start<end; start+=inc) {
2151:           *dvalue = start; dvalue++;n++;
2152:         }
2153:         foundrange = PETSC_TRUE;
2154:         break;
2155:       }
2156:     }
2157:     if (!foundrange) {
2158:       PetscOptionsStringToInt(value,dvalue);
2159:       dvalue++;
2160:       n++;
2161:     }
2162:     PetscTokenFind(token,&value);
2163:   }
2164:   PetscTokenDestroy(&token);
2165:   *nmax = n;
2166:   return(0);
2167: }

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

2174:    Not Collective

2176:    Input Parameters:
2177: +  options - options database use NULL for default global database
2178: .  pre - option prefix or NULL
2179: .  name - option name
2180: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2181: -  nmax - maximum number of values to retrieve

2183:    Output Parameters:
2184: +  dvalue - the  enum values to return
2185: .  nmax - actual number of values retreived
2186: -  set - PETSC_TRUE if found, else PETSC_FALSE

2188:    Level: beginner

2190:    Concepts: options database

2192:    Notes:
2193:    The array must be passed as a comma separated list.

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

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

2199: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2200:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2201:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2202:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2203:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2204:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2205: @*/
2206: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2207: {
2208:   char           *svalue;
2209:   PetscInt       n = 0;
2210:   PetscEnum      evalue;
2211:   PetscBool      flag;
2212:   PetscToken     token;


2221:   PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2222:   if (!flag) {
2223:     if (set) *set = PETSC_FALSE;
2224:     *nmax = 0;
2225:     return(0);
2226:   }
2227:   if (!svalue) {
2228:     if (set) *set = PETSC_TRUE;
2229:     *nmax = 0;
2230:     return(0);
2231:   }
2232:   if (set) *set = PETSC_TRUE;

2234:   PetscTokenCreate(svalue,',',&token);
2235:   PetscTokenFind(token,&svalue);
2236:   while (svalue && n < *nmax) {
2237:     PetscEnumFind(list,svalue,&evalue,&flag);
2238:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2239:     dvalue[n++] = evalue;
2240:     PetscTokenFind(token,&svalue);
2241:   }
2242:   *nmax = n;
2243:   PetscTokenDestroy(&token);
2244:   return(0);
2245: }

2249: /*@C
2250:    PetscOptionsGetString - Gets the string value for a particular option in
2251:    the database.

2253:    Not Collective

2255:    Input Parameters:
2256: +  options - options database use NULL for default global database
2257: .  pre - string to prepend to name or NULL
2258: .  name - the option one is seeking
2259: -  len - maximum length of the string including null termination

2261:    Output Parameters:
2262: +  string - location to copy string
2263: -  set - PETSC_TRUE if found, else PETSC_FALSE

2265:    Level: beginner

2267:    Fortran Note:
2268:    The Fortran interface is slightly different from the C/C++
2269:    interface (len is not used).  Sample usage in Fortran follows
2270: .vb
2271:       character *20 string
2272:       integer   flg, ierr
2273:       call PetscOptionsGetString(PETSC_NULL_OBJECT,PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
2274: .ve

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

2278:    Concepts: options database^string

2280:     Note:
2281:       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).

2283: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2284:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2285:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2286:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2287:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2288:           PetscOptionsFList(), PetscOptionsEList()
2289: @*/
2290: PetscErrorCode  PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
2291: {
2292:   char           *value;
2294:   PetscBool      flag;

2299:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2300:   if (!flag) {
2301:     if (set) *set = PETSC_FALSE;
2302:   } else {
2303:     if (set) *set = PETSC_TRUE;
2304:     if (value) {
2305:       PetscStrncpy(string,value,len);
2306:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
2307:     } else {
2308:       PetscMemzero(string,len);
2309:     }
2310:   }
2311:   return(0);
2312: }

2316: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2317: {
2318:   char           *value;
2320:   PetscBool      flag;

2323:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2324:   if (flag) PetscFunctionReturn(value);
2325:   else return(0);
2326: }


2331: /*@C
2332:    PetscOptionsGetStringArray - Gets an array of string values for a particular
2333:    option in the database. The values must be separated with commas with
2334:    no intervening spaces.

2336:    Not Collective

2338:    Input Parameters:
2339: +  options - options database use NULL for default global database
2340: .  pre - string to prepend to name or NULL
2341: .  name - the option one is seeking
2342: -  nmax - maximum number of strings

2344:    Output Parameter:
2345: +  strings - location to copy strings
2346: -  set - PETSC_TRUE if found, else PETSC_FALSE

2348:    Level: beginner

2350:    Notes:
2351:    The user should pass in an array of pointers to char, to hold all the
2352:    strings returned by this function.

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

2357:    Contributed by Matthew Knepley.

2359:    Concepts: options database^array of strings

2361: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2362:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2363:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2364:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2365:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2366:           PetscOptionsFList(), PetscOptionsEList()
2367: @*/
2368: PetscErrorCode  PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
2369: {
2370:   char           *value;
2372:   PetscInt       n;
2373:   PetscBool      flag;
2374:   PetscToken     token;

2379:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2380:   if (!flag) {
2381:     *nmax = 0;
2382:     if (set) *set = PETSC_FALSE;
2383:     return(0);
2384:   }
2385:   if (!value) {
2386:     *nmax = 0;
2387:     if (set) *set = PETSC_FALSE;
2388:     return(0);
2389:   }
2390:   if (!*nmax) {
2391:     if (set) *set = PETSC_FALSE;
2392:     return(0);
2393:   }
2394:   if (set) *set = PETSC_TRUE;

2396:   PetscTokenCreate(value,',',&token);
2397:   PetscTokenFind(token,&value);
2398:   n    = 0;
2399:   while (n < *nmax) {
2400:     if (!value) break;
2401:     PetscStrallocpy(value,&strings[n]);
2402:     PetscTokenFind(token,&value);
2403:     n++;
2404:   }
2405:   PetscTokenDestroy(&token);
2406:   *nmax = n;
2407:   return(0);
2408: }

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

2415:    Not Collective

2417:    Input Parameter:
2418: +   options - options database use NULL for default global database
2419: -   option - string name of option

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

2424:    Level: advanced

2426: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2427: @*/
2428: PetscErrorCode  PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2429: {
2430:   PetscInt       i;

2434:   options = options ? options : defaultoptions;
2435:   *used = PETSC_FALSE;
2436:   for (i=0; i<options->N; i++) {
2437:     PetscStrcmp(options->names[i],option,used);
2438:     if (*used) {
2439:       *used = options->used[i];
2440:       break;
2441:     }
2442:   }
2443:   return(0);
2444: }

2448: /*@C
2449:    PetscOptionsAllUsed - Returns a count of the number of options in the
2450:    database that have never been selected.

2452:    Not Collective

2454:    Input Parameter:
2455: .  options - options database use NULL for default global database

2457:    Output Parameter:
2458: .   N - count of options not used

2460:    Level: advanced

2462: .seealso: PetscOptionsView()
2463: @*/
2464: PetscErrorCode  PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2465: {
2466:   PetscInt     i,n = 0;

2469:   options = options ? options : defaultoptions;
2470:   for (i=0; i<options->N; i++) {
2471:     if (!options->used[i]) n++;
2472:   }
2473:   *N = n;
2474:   return(0);
2475: }

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

2482:   Not collective

2484:    Input Parameter:
2485: .  options - options database use NULL for default global database

2487:    Options Database Key:
2488: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

2490:   Level: advanced

2492: .seealso: PetscOptionsAllUsed()
2493: @*/
2494: PetscErrorCode  PetscOptionsLeft(PetscOptions options)
2495: {
2497:   PetscInt       i;

2500:   options = options ? options : defaultoptions;
2501:   for (i=0; i<options->N; i++) {
2502:     if (!options->used[i]) {
2503:       if (options->values[i]) {
2504:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2505:       } else {
2506:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2507:       }
2508:     }
2509:   }
2510:   return(0);
2511: }

2515: /*@
2516:     PetscOptionsCreate - Creates the empty options database.

2518:   Output Parameter:
2519: .   options - Options database object

2521:   Level: advanced

2523: @*/
2524: PetscErrorCode  PetscOptionsCreate(PetscOptions *options)
2525: {
2526:   *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2527:   if (!options) return PETSC_ERR_MEM;
2528:   (*options)->namegiven      = PETSC_FALSE;
2529:   (*options)->N              = 0;
2530:   (*options)->Naliases       = 0;
2531:   (*options)->numbermonitors = 0;
2532:   return 0;
2533: }

2537: /*
2538:     PetscOptionsCreateDefault - Creates the default global options database

2540: */
2541: PetscErrorCode  PetscOptionsCreateDefault(void)
2542: {

2545:   if (!defaultoptions) {
2546:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2547:   }
2548:   return 0;
2549: }

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

2556:    Collective on PETSC_COMM_WORLD

2558:    Input Parameter:
2559: .  options - options database use NULL for default global database

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

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

2571:    Level: intermediate

2573: .keywords: set, options, database
2574: @*/
2575: PetscErrorCode  PetscOptionsSetFromOptions(PetscOptions options)
2576: {
2577:   PetscBool      flgc = PETSC_FALSE,flgm;
2579:   char           monfilename[PETSC_MAX_PATH_LEN];
2580:   PetscViewer    monviewer;

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

2586:      options = options ? options : defaultoptions;
2587:   */
2588:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2589:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2590:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2591:   PetscOptionsEnd();
2592:   if (flgm) {
2593:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2594:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2595:   }
2596:   if (flgc) { PetscOptionsMonitorCancel(); }
2597:   return(0);
2598: }


2603: /*@C
2604:    PetscOptionsMonitorDefault - Print all options set value events.

2606:    Logically Collective on PETSC_COMM_WORLD

2608:    Input Parameters:
2609: +  name  - option name string
2610: .  value - option value string
2611: -  dummy - an ASCII viewer

2613:    Level: intermediate

2615: .keywords: PetscOptions, default, monitor

2617: .seealso: PetscOptionsMonitorSet()
2618: @*/
2619: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2620: {
2622:   PetscViewer    viewer = (PetscViewer) dummy;

2625:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2626:   return(0);
2627: }

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

2635:    Not collective

2637:    Input Parameters:
2638: +  monitor - pointer to function (if this is NULL, it turns off monitoring
2639: .  mctx    - [optional] context for private data for the
2640:              monitor routine (use NULL if no context is desired)
2641: -  monitordestroy - [optional] routine that frees monitor context
2642:           (may be NULL)

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

2647: +  name - option name string
2648: .  value - option value string
2649: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

2651:    Options Database Keys:
2652: +    -options_monitor    - sets PetscOptionsMonitorDefault()
2653: -    -options_monitor_cancel - cancels all monitors that have
2654:                           been hardwired into a code by
2655:                           calls to PetscOptionsMonitorSet(), but
2656:                           does not cancel those set via
2657:                           the options database.

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

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

2668:    Level: beginner

2670: .keywords: PetscOptions, set, monitor

2672: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2673: @*/
2674: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2675: {
2676:   PetscOptions options = defaultoptions;

2679:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2680:   options->monitor[options->numbermonitors]          = monitor;
2681:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
2682:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2683:   return(0);
2684: }

2688: /*@
2689:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

2691:    Not collective

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

2698:    Level: intermediate

2700: .keywords: PetscOptions, set, monitor

2702: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2703: @*/
2704: PetscErrorCode  PetscOptionsMonitorCancel(void)
2705: {
2707:   PetscInt       i;
2708:   PetscOptions   options = defaultoptions;

2711:   for (i=0; i<options->numbermonitors; i++) {
2712:     if (options->monitordestroy[i]) {
2713:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
2714:     }
2715:   }
2716:   options->numbermonitors = 0;
2717:   return(0);
2718: }

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

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

2727:   Collective on PetscObject

2729:   Input Parameters:
2730: + obj   - the object
2731: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
2732: - optionname - option to activate viewing

2734:   Level: intermediate

2736: @*/
2737: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2738: {
2739:   PetscErrorCode    ierr;
2740:   PetscViewer       viewer;
2741:   PetscBool         flg;
2742:   static PetscBool  incall = PETSC_FALSE;
2743:   PetscViewerFormat format;
2744:   char              *prefix;

2747:   if (incall) return(0);
2748:   incall = PETSC_TRUE;
2749:   prefix = bobj ? bobj->prefix : obj->prefix;
2750:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2751:   if (flg) {
2752:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2753:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2754:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2755:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2756:   }
2757:   incall = PETSC_FALSE;
2758:   return(0);
2759: }