Actual source code: options.c

  1: #define PETSC_DLL
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

 10:  #include petsc.h
 11:  #include petscsys.h
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif
 15: #if defined(PETSC_HAVE_MALLOC_H)
 16: #include <malloc.h>
 17: #endif
 18: #if defined(PETSC_HAVE_SYS_PARAM_H)
 19: #include "sys/param.h"
 20: #endif
 21: #include "petscfix.h"

 23: /* 
 24:     For simplicity, we use a static size database
 25: */
 26: #define MAXOPTIONS 512
 27: #define MAXALIASES 25
 28: #define MAXOPTIONSMONITORS 5

 30: typedef struct {
 31:   int        N,argc,Naliases;
 32:   char       **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
 33:   char       *aliases1[MAXALIASES],*aliases2[MAXALIASES];
 34:   PetscTruth used[MAXOPTIONS];
 35:   PetscTruth namegiven;
 36:   char       programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */

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

 44: } PetscOptionsTable;


 47: static PetscOptionsTable *options = 0;


 51: /*
 52:     Options events monitor
 53: */
 54: #define PetscOptionsMonitor(name,value)                                     \
 55:         { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
 56:           for (_i=0; _i<_im; _i++) {\
 57:             _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
 58:           } \
 59:         }

 63: PetscErrorCode  PetscOptionsAtoi(const char name[],PetscInt *a)
 64: {
 66:   size_t         i,len;
 67:   PetscTruth     decide,tdefault,mouse;

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

 73:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 74:   if (!tdefault) {
 75:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 76:   }
 77:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 78:   if (!decide) {
 79:     PetscStrcasecmp(name,"DECIDE",&decide);
 80:   }
 81:   PetscStrcasecmp(name,"mouse",&mouse);

 83:   if (tdefault) {
 84:     *a = PETSC_DEFAULT;
 85:   } else if (decide) {
 86:     *a = PETSC_DECIDE;
 87:   } else if (mouse) {
 88:     *a = -1;
 89:   } else {
 90:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
 91:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 92:     }
 93:     for (i=1; i<len; i++) {
 94:       if (name[i] < '0' || name[i] > '9') {
 95:         SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 96:       }
 97:     }
 98:     *a  = atoi(name);
 99:   }
100:   return(0);
101: }

105: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
106: {
108:   size_t         len;
109:   PetscTruth     decide,tdefault;

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

115:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
116:   if (!tdefault) {
117:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
118:   }
119:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
120:   if (!decide) {
121:     PetscStrcasecmp(name,"DECIDE",&decide);
122:   }

124:   if (tdefault) {
125:     *a = PETSC_DEFAULT;
126:   } else if (decide) {
127:     *a = PETSC_DECIDE;
128:   } else {
129:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
130:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
131:     }
132:     *a  = atof(name);
133:   }
134:   return(0);
135: }

139: PetscErrorCode  PetscOptionsAtol(const char value[], PetscTruth *a)
140: {
141:   PetscTruth     istrue, isfalse;
142:   size_t         len;

146:   PetscStrlen(value, &len);
147:   if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
148:   PetscStrcasecmp(value,"TRUE",&istrue);
149:   if (istrue) {*a = PETSC_TRUE; return(0);}
150:   PetscStrcasecmp(value,"YES",&istrue);
151:   if (istrue) {*a = PETSC_TRUE; return(0);}
152:   PetscStrcasecmp(value,"1",&istrue);
153:   if (istrue) {*a = PETSC_TRUE; return(0);}
154:   PetscStrcasecmp(value,"on",&istrue);
155:   if (istrue) {*a = PETSC_TRUE; return(0);}
156:   PetscStrcasecmp(value,"FALSE",&isfalse);
157:   if (isfalse) {*a = PETSC_FALSE; return(0);}
158:   PetscStrcasecmp(value,"NO",&isfalse);
159:   if (isfalse) {*a = PETSC_FALSE; return(0);}
160:   PetscStrcasecmp(value,"0",&isfalse);
161:   if (isfalse) {*a = PETSC_FALSE; return(0);}
162:   PetscStrcasecmp(value,"off",&isfalse);
163:   if (isfalse) {*a = PETSC_FALSE; return(0);}
164:   SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
165:   return(0);
166: }

170: /*@C
171:     PetscGetProgramName - Gets the name of the running program. 

173:     Not Collective

175:     Input Parameter:
176: .   len - length of the string name

178:     Output Parameter:
179: .   name - the name of the running program

181:    Level: advanced

183:     Notes:
184:     The name of the program is copied into the user-provided character
185:     array of length len.  On some machines the program name includes 
186:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
187: @*/
188: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
189: {

193:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
194:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
195:   PetscStrncpy(name,options->programname,len);
196:   return(0);
197: }

201: PetscErrorCode  PetscSetProgramName(const char name[])
202: {

206:   options->namegiven = PETSC_TRUE;
207:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
208:   return(0);
209: }

213: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscTruth *key)
214: {
216:   *key = PETSC_FALSE;
217:   if (!in_str) return(0);
218:   if (in_str[0] != '-') return(0);
219:   if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
220:   *key = PETSC_TRUE;
221:   return(0);
222: }

226: /*@C
227:      PetscOptionsInsertString - Inserts options into the database from a string

229:      Not collective: but only processes that call this routine will set the options
230:                      included in the file

232:   Input Parameter:
233: .   in_str - string that contains options separated by blanks


236:   Level: intermediate

238:   Contributed by Boyana Norris

240: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
241:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
242:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
243:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
244:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
245:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

247: @*/
248: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
249: {
250:   char           *first,*second;
252:   PetscToken     token;
253:   PetscTruth     key;

256:   PetscTokenCreate(in_str,' ',&token);
257:   PetscTokenFind(token,&first);
258:   while (first) {
259:     PetscOptionsValidKey(first,&key);
260:     if (key) {
261:       PetscTokenFind(token,&second);
262:       PetscOptionsValidKey(second,&key);
263:       if (!key) {
264:         PetscOptionsSetValue(first,second);
265:         PetscTokenFind(token,&first);
266:       } else {
267:         PetscOptionsSetValue(first,PETSC_NULL);
268:         first = second;
269:       }
270:     } else {
271:       PetscTokenFind(token,&first);
272:     }
273:   }
274:   PetscTokenDestroy(token);
275:   return(0);
276: }

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

283:      Not collective: but only processes that call this routine will set the options
284:                      included in the file

286:   Input Parameter:
287: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
288: .   file - name of file
289: -   require - if PETSC_TRUE will generate an error if the file does not exist


292:   Level: intermediate

294: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
295:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
296:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
297:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
298:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
299:           PetscOptionsList(), PetscOptionsEList()

301: @*/
302: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
303: {
304:   char           string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring,*astring;
306:   size_t         i,len;
307:   FILE           *fd;
308:   PetscToken     token;
309:   int            err;
310:   char           cmt[3]={'#','!','%'},*cmatch;
311:   PetscMPIInt    rank,cnt,acnt;

314:   /* Warning: assume a maximum size for all options in a string */
315:   PetscMalloc(64000*sizeof(char),&vstring);
316:   vstring[0] = 0;
317:   PetscMalloc(64000*sizeof(char),&astring);
318:   astring[0] = 0;
319:   cnt     = 0;
320:   acnt    = 0;
321:   MPI_Comm_rank(comm,&rank);
322:   if (!rank) {
323:     PetscFixFilename(file,fname);
324:     fd   = fopen(fname,"r");
325:     if (fd) {
326:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
327:       PetscInfo1(0,"Opened options file %s\n",file);
328:       while (fgets(string,PETSC_MAX_PATH_LEN,fd)) {
329:         /* eliminate comments from each line */
330:         for (i=0; i<3; i++){
331:           PetscStrchr(string,cmt[i],&cmatch);
332:           if (cmatch) *cmatch = 0;
333:         }
334:         PetscStrlen(string,&len);
335:         /* replace tabs, ^M, \n with " " */
336:         for (i=0; i<len; i++) {
337:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
338:             string[i] = ' ';
339:           }
340:         }
341:         PetscTokenCreate(string,' ',&token);
342:         PetscTokenFind(token,&first);
343:         if (!first) {
344:           goto destroy;
345:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
346:           PetscTokenFind(token,&first);
347:         }
348:         PetscTokenFind(token,&second);
349:         if (!first) {
350:           goto destroy;
351:         } else if (first[0] == '-') {
352:           /* warning: should be making sure we do not overfill vstring */
353:           PetscStrcat(vstring,first);
354:           PetscStrcat(vstring," ");
355:           if (second) {
356:             /* protect second with quotes in case it contains strings */
357:             PetscStrcat(vstring,"\"");
358:             PetscStrcat(vstring,second);
359:             PetscStrcat(vstring,"\"");
360:           }
361:           PetscStrcat(vstring," ");
362:           /* PetscOptionsSetValue(first,second); */
363:         } else {
364:           PetscTruth match;

366:           PetscStrcasecmp(first,"alias",&match);
367:           if (match) {
368:             PetscTokenFind(token,&third);
369:             if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
370:             PetscStrcat(astring,second);
371:             PetscStrcat(astring," ");
372:             PetscStrcat(astring,third);
373:             PetscStrcat(astring," ");
374:             /* PetscOptionsSetAlias(second,third);*/
375:           } else {
376:             SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
377:           }
378:         }
379:         destroy:
380:         PetscTokenDestroy(token);
381:       }
382:       err = fclose(fd);
383:       if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
384:       PetscStrlen(astring,&len);
385:       acnt = PetscMPIIntCast(len);
386:       PetscStrlen(vstring,&len);
387:       cnt  = PetscMPIIntCast(len);
388:     } else if (require) {
389:       SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
390:     }
391:   }
392:   MPI_Bcast(&acnt,1,MPIU_INT,0,comm);
393:   if (acnt) {
394:     PetscToken token;
395:     char       *first,*second;

397:     MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
398:     astring[acnt] = 0;
399:     PetscTokenCreate(astring,' ',&token);
400:     PetscTokenFind(token,&first);
401:     while (first) {
402:       PetscTokenFind(token,&second);
403:       PetscOptionsSetAlias(first,second);
404:       PetscTokenFind(token,&first);
405:     }
406:     PetscTokenDestroy(token);
407:   }

409:   MPI_Bcast(&cnt,1,MPIU_INT,0,comm);
410:   if (cnt) {
411:     if (rank && vstring && cnt>64000 ) {
412:       PetscFree(vstring);
413:       PetscMalloc((cnt+1)*sizeof(char),&vstring);
414:     }
415:     MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
416:     vstring[cnt] = 0;
417:     PetscOptionsInsertString(vstring);
418:   }
419:   PetscFree(astring);
420:   PetscFree(vstring);
421:   return(0);
422: }

426: /*@C
427:    PetscOptionsInsert - Inserts into the options database from the command line,
428:                    the environmental variable and a file.

430:    Input Parameters:
431: +  argc - count of number of command line arguments
432: .  args - the command line arguments
433: -  file - optional filename, defaults to ~username/.petscrc

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

440:    Options Database Keys:
441: +   -options_monitor <optional filename> - print options names and values as they are set

443:    Level: advanced

445:    Concepts: options database^adding

447: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
448:           PetscInitialize()
449: @*/
450: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
451: {
453:   PetscMPIInt    rank;
454:   char           pfile[PETSC_MAX_PATH_LEN];
455:   PetscTruth     flag;

458:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

460:   options->argc     = (argc) ? *argc : 0;
461:   options->args     = (args) ? *args : PETSC_NULL;

463:   if (file) {
464:     PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
465:   }
466:   PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
467:   if (!flag) {
468:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
469:     /* warning: assumes all processes have a home directory or none, but nothing in between */
470:     if (pfile[0]) {
471:       PetscStrcat(pfile,"/.petscrc");
472:       PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
473:     }
474:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
475:   }

477:   /* insert environmental options */
478:   {
479:     char   *eoptions = 0;
480:     size_t len = 0;
481:     if (!rank) {
482:       eoptions = (char*)getenv("PETSC_OPTIONS");
483:       PetscStrlen(eoptions,&len);
484:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
485:     } else {
486:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
487:       if (len) {
488:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
489:       }
490:     }
491:     if (len) {
492:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
493:       if (rank) eoptions[len] = 0;
494:       PetscOptionsInsertString(eoptions);
495:       if (rank) {PetscFree(eoptions);}
496:     }
497:   }

499:   /* insert command line options */
500:   if (argc && args && *argc) {
501:     int        left    = *argc - 1;
502:     char       **eargs = *args + 1;
503:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

505:     while (left) {
506:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
507:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
508:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
509:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
510:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
511:       isp4 = (PetscTruth) (isp4 || tisp4);
512:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
513:       isp4 = (PetscTruth) (isp4 || tisp4);
514:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

516:       if (eargs[0][0] != '-') {
517:         eargs++; left--;
518:       } else if (isoptions_file) {
519:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
520:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
521:         PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
522:         eargs += 2; left -= 2;

524:       /*
525:          These are "bad" options that MPICH, etc put on the command line
526:          we strip them out here.
527:       */
528:       } else if (tisp4 || isp4rmrank) {
529:         eargs += 1; left -= 1;
530:       } else if (isp4 || isp4yourname) {
531:         eargs += 2; left -= 2;
532:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
533:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
534:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
535:         eargs++; left--;
536:       } else {
537:         PetscOptionsSetValue(eargs[0],eargs[1]);
538:         eargs += 2; left -= 2;
539:       }
540:     }
541:   }
542:   return(0);
543: }

547: /*@C
548:    PetscOptionsPrint - Prints the options that have been loaded. This is
549:    useful for debugging purposes.

551:    Collective on PETSC_COMM_WORLD

553:    Input Parameter:
554: .  FILE fd - location to print options (usually stdout or stderr)

556:    Options Database Key:
557: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

559:    Level: advanced

561:    Concepts: options database^printing

563: .seealso: PetscOptionsAllUsed()
564: @*/
565: PetscErrorCode  PetscOptionsPrint(FILE *fd)
566: {
568:   PetscInt       i;

571:   if (!fd) fd = PETSC_STDOUT;
572:   if (!options) {PetscOptionsInsert(0,0,0);}
573:   if (options->N) {
574:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
575:   } else {
576:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
577:   }
578:   for (i=0; i<options->N; i++) {
579:     if (options->values[i]) {
580:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
581:     } else {
582:       PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
583:     }
584:   }
585:   if (options->N) {
586:     PetscFPrintf(PETSC_COMM_WORLD,fd,"#End o PETSc Option Table entries\n");
587:   }
588:   return(0);
589: }

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

596:    Not Collective

598:    Output Parameter:
599: .  copts - pointer where string pointer is stored

601:    Level: advanced

603:    Concepts: options database^listing

605: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
606: @*/
607: PetscErrorCode  PetscOptionsGetAll(char *copts[])
608: {
610:   PetscInt       i;
611:   size_t         len = 1,lent;
612:   char           *coptions;

615:   if (!options) {PetscOptionsInsert(0,0,0);}

617:   /* count the length of the required string */
618:   for (i=0; i<options->N; i++) {
619:     PetscStrlen(options->names[i],&lent);
620:     len += 2 + lent;
621:     if (options->values[i]) {
622:       PetscStrlen(options->values[i],&lent);
623:       len += 1 + lent;
624:     }
625:   }
626:   PetscMalloc(len*sizeof(char),&coptions);
627:   coptions[0] = 0;
628:   for (i=0; i<options->N; i++) {
629:     PetscStrcat(coptions,"-");
630:     PetscStrcat(coptions,options->names[i]);
631:     PetscStrcat(coptions," ");
632:     if (options->values[i]) {
633:       PetscStrcat(coptions,options->values[i]);
634:       PetscStrcat(coptions," ");
635:     }
636:   }
637:   *copts = coptions;
638:   return(0);
639: }

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

646:    Level: developer

648: .seealso: PetscOptionsInsert()
649: @*/
650: PetscErrorCode  PetscOptionsClear(void)
651: {
652:   PetscInt i;

655:   if (!options) return(0);
656:   for (i=0; i<options->N; i++) {
657:     if (options->names[i])  free(options->names[i]);
658:     if (options->values[i]) free(options->values[i]);
659:   }
660:   for (i=0; i<options->Naliases; i++) {
661:     free(options->aliases1[i]);
662:     free(options->aliases2[i]);
663:   }
664:   options->N        = 0;
665:   options->Naliases = 0;
666:   return(0);
667: }

671: /*@C
672:     PetscOptionsDestroy - Destroys the option database. 

674:     Note:
675:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
676:     typically does not need to call this routine.

678:    Level: developer

680: .seealso: PetscOptionsInsert()
681: @*/
682: PetscErrorCode  PetscOptionsDestroy(void)
683: {

687:   if (!options) return(0);
688:   PetscOptionsClear();
689:   free(options);
690:   options = 0;
691:   return(0);
692: }

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

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

703:    Input Parameters:
704: +  name - name of option, this SHOULD have the - prepended
705: -  value - the option value (not used for all options)

707:    Level: intermediate

709:    Note:
710:    Only some options have values associated with them, such as
711:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

713:   Concepts: options database^adding option

715: .seealso: PetscOptionsInsert()
716: @*/
717: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
718: {
719:   size_t         len;
721:   PetscInt       N,n,i;
722:   char           **names;
723:   const char     *name = (char*)iname;
724:   PetscTruth     gt,match;

727:   if (!options) {PetscOptionsInsert(0,0,0);}

729:   /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
730:   PetscStrcasecmp(name,"-h",&match);
731:   if (match) name = "-help";

733:   name++;
734:   /* first check against aliases */
735:   N = options->Naliases;
736:   for (i=0; i<N; i++) {
737:     PetscStrcasecmp(options->aliases1[i],name,&match);
738:     if (match) {
739:       name = options->aliases2[i];
740:       break;
741:     }
742:   }

744:   N     = options->N;
745:   n     = N;
746:   names = options->names;
747: 
748:   for (i=0; i<N; i++) {
749:     PetscStrcasecmp(names[i],name,&match);
750:     PetscStrgrt(names[i],name,&gt);
751:     if (match) {
752:       if (options->values[i]) free(options->values[i]);
753:       PetscStrlen(value,&len);
754:       if (len) {
755:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
756:         PetscStrcpy(options->values[i],value);
757:       } else { options->values[i] = 0;}
758:       PetscOptionsMonitor(name,value);
759:       return(0);
760:     } else if (gt) {
761:       n = i;
762:       break;
763:     }
764:   }
765:   if (N >= MAXOPTIONS) {
766:     SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
767:   }
768:   /* shift remaining values down 1 */
769:   for (i=N; i>n; i--) {
770:     options->names[i]  = options->names[i-1];
771:     options->values[i] = options->values[i-1];
772:     options->used[i]   = options->used[i-1];
773:   }
774:   /* insert new name and value */
775:   PetscStrlen(name,&len);
776:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
777:   PetscStrcpy(options->names[n],name);
778:   PetscStrlen(value,&len);
779:   if (len) {
780:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
781:     PetscStrcpy(options->values[n],value);
782:   } else {options->values[n] = 0;}
783:   options->used[n] = PETSC_FALSE;
784:   options->N++;
785:   PetscOptionsMonitor(name,value);
786:   return(0);
787: }

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

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

798:    Input Parameter:
799: .  name - name of option, this SHOULD have the - prepended

801:    Level: intermediate

803:    Concepts: options database^removing option
804: .seealso: PetscOptionsInsert()
805: @*/
806: PetscErrorCode  PetscOptionsClearValue(const char iname[])
807: {
809:   PetscInt       N,n,i;
810:   char           **names,*name=(char*)iname;
811:   PetscTruth     gt,match;

814:   if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
815:   if (!options) {PetscOptionsInsert(0,0,0);}

817:   name++;

819:   N     = options->N; n = 0;
820:   names = options->names;
821: 
822:   for (i=0; i<N; i++) {
823:     PetscStrcasecmp(names[i],name,&match);
824:     PetscStrgrt(names[i],name,&gt);
825:     if (match) {
826:       if (options->names[i])  free(options->names[i]);
827:       if (options->values[i]) free(options->values[i]);
828:       PetscOptionsMonitor(name,"");
829:       break;
830:     } else if (gt) {
831:       return(0); /* it was not listed */
832:     }
833:     n++;
834:   }
835:   if (n == N) return(0); /* it was not listed */

837:   /* shift remaining values down 1 */
838:   for (i=n; i<N-1; i++) {
839:     options->names[i]  = options->names[i+1];
840:     options->values[i] = options->values[i+1];
841:     options->used[i]   = options->used[i+1];
842:   }
843:   options->N--;
844:   return(0);
845: }

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

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

855:    Input Parameters:
856: +  name - the option one is seeking 
857: -  mess - error message (may be PETSC_NULL)

859:    Level: advanced

861:    Concepts: options database^rejecting option

863: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
864:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
865:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
866:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
867:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
868:           PetscOptionsList(), PetscOptionsEList()
869: @*/
870: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
871: {
873:   PetscInt       n = options->Naliases;
874:   size_t         len;
875:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

878:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
879:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
880:   if (n >= MAXALIASES) {
881:     SETERRQ1(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);
882:   }

884:   newname++; oldname++;
885:   PetscStrlen(newname,&len);
886:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
887:   PetscStrcpy(options->aliases1[n],newname);
888:   PetscStrlen(oldname,&len);
889:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
890:   PetscStrcpy(options->aliases2[n],oldname);
891:   options->Naliases++;
892:   return(0);
893: }

897: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
898: {
900:   PetscInt       i,N;
901:   size_t         len;
902:   char           **names,tmp[256];
903:   PetscTruth     match;

906:   if (!options) {PetscOptionsInsert(0,0,0);}
907:   N = options->N;
908:   names = options->names;

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

912:   /* append prefix to name */
913:   if (pre) {
914:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
915:     PetscStrncpy(tmp,pre,256);
916:     PetscStrlen(tmp,&len);
917:     PetscStrncat(tmp,name+1,256-len-1);
918:   } else {
919:     PetscStrncpy(tmp,name+1,256);
920:   }

922:   /* slow search */
923:   *flg = PETSC_FALSE;
924:   for (i=0; i<N; i++) {
925:     PetscStrcasecmp(names[i],tmp,&match);
926:     if (match) {
927:        *value           = options->values[i];
928:        options->used[i] = PETSC_TRUE;
929:        *flg             = PETSC_TRUE;
930:        break;
931:      }
932:   }
933:   if (!*flg) {
934:     PetscInt j,cnt = 0,locs[16],loce[16];
935:     size_t   n;
936:     PetscStrlen(tmp,&n);
937:     /* determine the location and number of all _%d_ in the key */
938:     for (i=0; i< (PetscInt)n; i++) {
939:       if (tmp[i] == '_') {
940:         for (j=i+1; j< (PetscInt)n; j++) {
941:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
942:           if (tmp[j] == '_' && j > i+1) { /* found a number */
943:             locs[cnt]   = i+1;
944:             loce[cnt++] = j+1;
945:           }
946:           break;
947:         }
948:       }
949:     }
950:     if (cnt) {
951:       char tmp2[256];
952:       for (i=0; i<cnt; i++) {
953:         PetscStrcpy(tmp2,"-");
954:         PetscStrncat(tmp2,tmp,locs[i]);
955:         PetscStrcat(tmp2,tmp+loce[i]);
956:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
957:         if (*flg) break;
958:       }
959:     }
960:   }
961:   return(0);
962: }

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

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

972:    Input Parameters:
973: +  name - the option one is seeking 
974: -  mess - error message (may be PETSC_NULL)

976:    Level: advanced

978:    Concepts: options database^rejecting option

980: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
981:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
982:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
983:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
984:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
985:           PetscOptionsList(), PetscOptionsEList()
986: @*/
987: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
988: {
990:   PetscTruth     flag;

993:   PetscOptionsHasName(PETSC_NULL,name,&flag);
994:   if (flag) {
995:     if (mess) {
996:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
997:     } else {
998:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
999:     }
1000:   }
1001:   return(0);
1002: }

1006: /*@C
1007:    PetscOptionsHasName - Determines whether a certain option is given in the database.

1009:    Not Collective

1011:    Input Parameters:
1012: +  name - the option one is seeking 
1013: -  pre - string to prepend to the name or PETSC_NULL

1015:    Output Parameters:
1016: .  flg - PETSC_TRUE if found else PETSC_FALSE.

1018:    Level: beginner

1020:    Concepts: options database^has option name

1022:    Notes: Name cannot be simply -h

1024: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1025:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1026:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1027:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1028:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1029:           PetscOptionsList(), PetscOptionsEList()
1030: @*/
1031: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1032: {
1033:   char           *value;
1035:   PetscTruth     isfalse,flag;

1038:   PetscOptionsFindPair_Private(pre,name,&value,&flag);

1040:   /* remove if turned off */
1041:   if (flag) {
1042:     PetscStrcasecmp(value,"FALSE",&isfalse);
1043:     if (isfalse) flag = PETSC_FALSE;
1044:     PetscStrcasecmp(value,"NO",&isfalse);
1045:     if (isfalse) flag = PETSC_FALSE;
1046:     PetscStrcasecmp(value,"0",&isfalse);
1047:     if (isfalse) flag = PETSC_FALSE;
1048:   }
1049:   if (flg) *flg = flag;
1050:   return(0);
1051: }

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

1058:    Not Collective

1060:    Input Parameters:
1061: +  pre - the string to prepend to the name or PETSC_NULL
1062: -  name - the option one is seeking

1064:    Output Parameter:
1065: +  ivalue - the integer value to return
1066: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1068:    Level: beginner

1070:    Concepts: options database^has int

1072: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1073:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1074:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1075:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1076:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1077:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1078:           PetscOptionsList(), PetscOptionsEList()
1079: @*/
1080: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1081: {
1082:   char           *value;
1084:   PetscTruth     flag;

1089:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1090:   if (flag) {
1091:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1092:     else {
1093:       if (flg) *flg = PETSC_TRUE;
1094:       PetscOptionsAtoi(value,ivalue);
1095:     }
1096:   } else {
1097:     if (flg) *flg = PETSC_FALSE;
1098:   }
1099:   return(0);
1100: }

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

1107:    Not Collective

1109:    Input Parameters:
1110: +  pre - the string to prepend to the name or PETSC_NULL
1111: .  opt - option name
1112: .  list - the possible choices
1113: .  ntext - number of choices

1115:    Output Parameter:
1116: +  value - the index of the value to return
1117: -  set - PETSC_TRUE if found, else PETSC_FALSE
1118:    
1119:    Level: intermediate

1121:    See PetscOptionsList() for when the choices are given in a PetscFList()

1123:    Concepts: options database^list

1125: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1126:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1127:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1128:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1129:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1130:           PetscOptionsList(), PetscOptionsEList()
1131: @*/
1132: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1133: {
1135:   size_t         alen,len = 0;
1136:   char           *svalue;
1137:   PetscTruth     aset,flg = PETSC_FALSE;
1138:   PetscInt       i;

1141:   for ( i=0; i<ntext; i++) {
1142:     PetscStrlen(list[i],&alen);
1143:     if (alen > len) len = alen;
1144:   }
1145:   len += 5; /* a little extra space for user mistypes */
1146:   PetscMalloc(len*sizeof(char),&svalue);
1147:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1148:   if (aset) {
1149:     if (set) *set = PETSC_TRUE;
1150:     for (i=0; i<ntext; i++) {
1151:       PetscStrcasecmp(svalue,list[i],&flg);
1152:       if (flg) {
1153:         *value = i;
1154:         break;
1155:       }
1156:     }
1157:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1158:   } else if (set) {
1159:     *set = PETSC_FALSE;
1160:   }
1161:   PetscFree(svalue);
1162:   return(0);
1163: }

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

1170:    Not Collective

1172:    Input Parameters:
1173: +  pre - option prefix or PETSC_NULL
1174: .  opt - option name
1175: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1176: -  defaultv - the default (current) value

1178:    Output Parameter:
1179: +  value - the  value to return
1180: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1182:    Level: beginner

1184:    Concepts: options database

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

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

1190: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1191:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1192:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1193:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1194:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1195:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1196:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1197: @*/
1198: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1199: {
1201:   PetscInt       ntext = 0;

1204:   while (list[ntext++]) {
1205:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1206:   }
1207:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1208:   ntext -= 3;
1209:   PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1210:   return(0);
1211: }

1215: /*@C
1216:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1217:             option in the database.

1219:    Not Collective

1221:    Input Parameters:
1222: +  pre - the string to prepend to the name or PETSC_NULL
1223: -  name - the option one is seeking

1225:    Output Parameter:
1226: +  ivalue - the logical value to return
1227: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1229:    Level: beginner

1231:    Notes:
1232:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1233:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

1238:    Concepts: options database^has logical

1240: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1241:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1242:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1243:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1244:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1245:           PetscOptionsList(), PetscOptionsEList()
1246: @*/
1247: PetscErrorCode  PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1248: {
1249:   char           *value;
1250:   PetscTruth     flag;

1256:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1257:   if (flag) {
1258:     if (flg) *flg = PETSC_TRUE;
1259:     if (!value) {
1260:       *ivalue = PETSC_TRUE;
1261:     } else {
1262:       PetscOptionsAtol(value, ivalue);
1263:     }
1264:   } else {
1265:     if (flg) *flg = PETSC_FALSE;
1266:   }
1267:   return(0);
1268: }

1272: /*@C
1273:    PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular 
1274:    option in the database.  The values must be separated with commas with 
1275:    no intervening spaces. 

1277:    Not Collective

1279:    Input Parameters:
1280: +  pre - string to prepend to each name or PETSC_NULL
1281: .  name - the option one is seeking
1282: -  nmax - maximum number of values to retrieve

1284:    Output Parameter:
1285: +  dvalue - the integer values to return
1286: .  nmax - actual number of values retreived
1287: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1289:    Level: beginner

1291:    Concepts: options database^array of ints

1293:    Notes:
1294:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1295:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1297: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1298:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1299:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1300:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1301:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1302:           PetscOptionsList(), PetscOptionsEList()
1303: @*/
1304: PetscErrorCode  PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1305: {
1306:   char           *value;
1308:   PetscInt       n = 0;
1309:   PetscTruth     flag;
1310:   PetscToken     token;

1315:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1316:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1317:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1319:   if (flg) *flg = PETSC_TRUE;

1321:   PetscTokenCreate(value,',',&token);
1322:   PetscTokenFind(token,&value);
1323:   while (n < *nmax) {
1324:     if (!value) break;
1325:     PetscOptionsAtol(value,dvalue);
1326:     PetscTokenFind(token,&value);
1327:     dvalue++;
1328:     n++;
1329:   }
1330:   PetscTokenDestroy(token);
1331:   *nmax = n;
1332:   return(0);
1333: }

1337: /*@C
1338:    PetscOptionsGetReal - Gets the double precision value for a particular 
1339:    option in the database.

1341:    Not Collective

1343:    Input Parameters:
1344: +  pre - string to prepend to each name or PETSC_NULL
1345: -  name - the option one is seeking

1347:    Output Parameter:
1348: +  dvalue - the double value to return
1349: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1351:    Level: beginner

1353:    Concepts: options database^has double

1355: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1356:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1357:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1358:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1359:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1360:           PetscOptionsList(), PetscOptionsEList()
1361: @*/
1362: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1363: {
1364:   char           *value;
1366:   PetscTruth     flag;

1371:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1372:   if (flag) {
1373:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1374:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1375:   } else {
1376:     if (flg) *flg = PETSC_FALSE;
1377:   }
1378:   return(0);
1379: }

1383: /*@C
1384:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1385:    option in the database.

1387:    Not Collective

1389:    Input Parameters:
1390: +  pre - string to prepend to each name or PETSC_NULL
1391: -  name - the option one is seeking

1393:    Output Parameter:
1394: +  dvalue - the double value to return
1395: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1397:    Level: beginner

1399:    Usage:
1400:    A complex number 2+3i can be specified as 2,3 at the command line.
1401:    or a number 2.0e-10 - 3.3e-20 i  can be specified as 2.0e-10,3.3e-20

1403:    Concepts: options database^has scalar

1405: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1406:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1407:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1408:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1409:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1410:           PetscOptionsList(), PetscOptionsEList()
1411: @*/
1412: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1413: {
1414:   char           *value;
1415:   PetscTruth     flag;

1421:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1422:   if (flag) {
1423:     if (!value) {
1424:       if (flg) *flg = PETSC_FALSE;
1425:     } else {
1426: #if !defined(PETSC_USE_COMPLEX)
1427:       PetscOptionsAtod(value,dvalue);
1428: #else
1429:       PetscReal  re=0.0,im=0.0;
1430:       PetscToken token;
1431:       char       *tvalue = 0;

1433:       PetscTokenCreate(value,',',&token);
1434:       PetscTokenFind(token,&tvalue);
1435:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1436:       PetscOptionsAtod(tvalue,&re);
1437:       PetscTokenFind(token,&tvalue);
1438:       if (!tvalue) { /* Unknown separator used. using only real value */
1439:         *dvalue = re;
1440:       } else {
1441:         PetscOptionsAtod(tvalue,&im);
1442:         *dvalue = re + PETSC_i*im;
1443:       }
1444:       PetscTokenDestroy(token);
1445: #endif
1446:       if (flg) *flg    = PETSC_TRUE;
1447:     }
1448:   } else { /* flag */
1449:     if (flg) *flg = PETSC_FALSE;
1450:   }
1451:   return(0);
1452: }

1456: /*@C
1457:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1458:    particular option in the database.  The values must be separated with 
1459:    commas with no intervening spaces.

1461:    Not Collective

1463:    Input Parameters:
1464: +  pre - string to prepend to each name or PETSC_NULL
1465: .  name - the option one is seeking
1466: -  nmax - maximum number of values to retrieve

1468:    Output Parameters:
1469: +  dvalue - the double value to return
1470: .  nmax - actual number of values retreived
1471: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1473:    Level: beginner

1475:    Concepts: options database^array of doubles

1477: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1478:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1479:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1480:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1481:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1482:           PetscOptionsList(), PetscOptionsEList()
1483: @*/
1484: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1485: {
1486:   char           *value;
1488:   PetscInt       n = 0;
1489:   PetscTruth     flag;
1490:   PetscToken     token;

1495:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1496:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1497:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1499:   if (flg) *flg = PETSC_TRUE;

1501:   PetscTokenCreate(value,',',&token);
1502:   PetscTokenFind(token,&value);
1503:   while (n < *nmax) {
1504:     if (!value) break;
1505:     PetscOptionsAtod(value,dvalue++);
1506:     PetscTokenFind(token,&value);
1507:     n++;
1508:   }
1509:   PetscTokenDestroy(token);
1510:   *nmax = n;
1511:   return(0);
1512: }

1516: /*@C
1517:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1518:    option in the database.  The values must be separated with commas with 
1519:    no intervening spaces. 

1521:    Not Collective

1523:    Input Parameters:
1524: +  pre - string to prepend to each name or PETSC_NULL
1525: .  name - the option one is seeking
1526: -  nmax - maximum number of values to retrieve

1528:    Output Parameter:
1529: +  dvalue - the integer values to return
1530: .  nmax - actual number of values retreived
1531: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1533:    Level: beginner

1535:    Concepts: options database^array of ints

1537: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1538:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1539:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1540:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1541:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1542:           PetscOptionsList(), PetscOptionsEList()
1543: @*/
1544: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1545: {
1546:   char           *value;
1548:   PetscInt       n = 0,i,start,end;
1549:   size_t         len;
1550:   PetscTruth     flag,foundrange;
1551:   PetscToken     token;

1556:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1557:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1558:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1560:   if (flg) *flg = PETSC_TRUE;

1562:   PetscTokenCreate(value,',',&token);
1563:   PetscTokenFind(token,&value);
1564:   while (n < *nmax) {
1565:     if (!value) break;
1566: 
1567:     /* look for form  d-D where d and D are integers */
1568:     foundrange = PETSC_FALSE;
1569:     PetscStrlen(value,&len);
1570:     if (value[0] == '-') i=2;
1571:     else i=1;
1572:     for (;i<(int)len; i++) {
1573:       if (value[i] == '-') {
1574:         if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1575:         value[i] = 0;
1576:         PetscOptionsAtoi(value,&start);
1577:         PetscOptionsAtoi(value+i+1,&end);
1578:         if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1579:         if (n + end - start - 1 >= *nmax) SETERRQ4(PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
1580:         for (;start<end; start++) {
1581:           *dvalue = start; dvalue++;n++;
1582:         }
1583:         foundrange = PETSC_TRUE;
1584:         break;
1585:       }
1586:     }
1587:     if (!foundrange) {
1588:       PetscOptionsAtoi(value,dvalue);
1589:       dvalue++;
1590:       n++;
1591:     }
1592:     PetscTokenFind(token,&value);
1593:   }
1594:   PetscTokenDestroy(token);
1595:   *nmax = n;
1596:   return(0);
1597: }

1601: /*@C
1602:    PetscOptionsGetString - Gets the string value for a particular option in
1603:    the database.

1605:    Not Collective

1607:    Input Parameters:
1608: +  pre - string to prepend to name or PETSC_NULL
1609: .  name - the option one is seeking
1610: -  len - maximum string length

1612:    Output Parameters:
1613: +  string - location to copy string
1614: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1616:    Level: beginner

1618:    Fortran Note:
1619:    The Fortran interface is slightly different from the C/C++
1620:    interface (len is not used).  Sample usage in Fortran follows
1621: .vb
1622:       character *20 string
1623:       integer   flg, ierr
1624:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1625: .ve

1627:    Concepts: options database^string

1629: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1630:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1631:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1632:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1633:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1634:           PetscOptionsList(), PetscOptionsEList()
1635: @*/
1636: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1637: {
1638:   char           *value;
1640:   PetscTruth     flag;

1645:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1646:   if (!flag) {
1647:     if (flg) *flg = PETSC_FALSE;
1648:   } else {
1649:     if (flg) *flg = PETSC_TRUE;
1650:     if (value) {
1651:       PetscStrncpy(string,value,len);
1652:     } else {
1653:       PetscMemzero(string,len);
1654:     }
1655:   }
1656:   return(0);
1657: }

1661: /*@C
1662:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1663:    option in the database. The values must be separated with commas with 
1664:    no intervening spaces. 

1666:    Not Collective

1668:    Input Parameters:
1669: +  pre - string to prepend to name or PETSC_NULL
1670: .  name - the option one is seeking
1671: -  nmax - maximum number of strings

1673:    Output Parameter:
1674: +  strings - location to copy strings
1675: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1677:    Level: beginner

1679:    Notes: 
1680:    The user should pass in an array of pointers to char, to hold all the
1681:    strings returned by this function.

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

1686:    Contributed by Matthew Knepley.

1688:    Concepts: options database^array of strings

1690: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1691:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1692:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1693:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1694:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1695:           PetscOptionsList(), PetscOptionsEList()
1696: @*/
1697: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1698: {
1699:   char           *value;
1701:   PetscInt       n;
1702:   PetscTruth     flag;
1703:   PetscToken     token;
1704: 
1708:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1709:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1710:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1711:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1712:   if (flg) *flg = PETSC_TRUE;

1714:   PetscTokenCreate(value,',',&token);
1715:   PetscTokenFind(token,&value);
1716:   n = 0;
1717:   while (n < *nmax) {
1718:     if (!value) break;
1719:     PetscStrallocpy(value,&strings[n]);
1720:     PetscTokenFind(token,&value);
1721:     n++;
1722:   }
1723:   PetscTokenDestroy(token);
1724:   *nmax = n;
1725:   return(0);
1726: }

1730: /*@C
1731:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1732:    database that have never been selected.

1734:    Not Collective

1736:    Output Parameter:
1737: .   N - count of options not used

1739:    Level: advanced

1741: .seealso: PetscOptionsPrint()
1742: @*/
1743: PetscErrorCode  PetscOptionsAllUsed(int *N)
1744: {
1745:   PetscInt i,n = 0;

1748:   for (i=0; i<options->N; i++) {
1749:     if (!options->used[i]) { n++; }
1750:   }
1751:   *N = n;
1752:   return(0);
1753: }

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

1760:   Not collective

1762:    Options Database Key:
1763: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1765:   Level: advanced

1767: .seealso: PetscOptionsAllUsed()
1768: @*/
1769: PetscErrorCode  PetscOptionsLeft(void)
1770: {
1772:   PetscInt       i;

1775:   for (i=0; i<options->N; i++) {
1776:     if (!options->used[i]) {
1777:       if (options->values[i]) {
1778:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1779:       } else {
1780:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1781:       }
1782:     }
1783:   }
1784:   return(0);
1785: }


1788: /*
1789:     PetscOptionsCreate - Creates the empty options database.

1791: */
1794: PetscErrorCode  PetscOptionsCreate(void)
1795: {

1799:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1800:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1801:   options->namegiven                 = PETSC_FALSE;
1802:   options->N                         = 0;
1803:   options->Naliases                  = 0;
1804:   options->numbermonitors         = 0;

1806:   PetscOptionsObject.prefix = PETSC_NULL;
1807:   PetscOptionsObject.title  = PETSC_NULL;
1808: 
1809:   return(0);
1810: }

1814: /*@
1815:    PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.

1817:    Collective on PETSC_COMM_WORLD

1819:    Options Database Keys:
1820: +  -options_monitor <optional filename> - prints the names and values of all 
1821:                                  runtime options as they are set. The monitor functionality is not 
1822:                 available for options set through a file, environment variable, or on 
1823:                 the command line. Only options set after PetscInitialize completes will 
1824:                 be monitored.
1825: .  -options_monitor_cancel - cancel all options database monitors    

1827:    Notes:
1828:    To see all options, run your program with the -help option or consult
1829:    the users manual. 

1831:    Level: intermediate

1833: .keywords: set, options, database
1834: @*/
1835: PetscErrorCode  PetscOptionsSetFromOptions(void)
1836: {
1837:   PetscTruth          flg;
1838:   PetscErrorCode      ierr;
1839:   char                monfilename[PETSC_MAX_PATH_LEN];
1840:   PetscViewer         monviewer;


1844:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1845:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1846:   if (flg && (!options->numbermonitors)) {
1847:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1848:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1849:   }
1850: 
1851:   PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1852:   if (flg) { PetscOptionsMonitorCancel(); }
1853: 
1854:   PetscOptionsEnd();

1856:   return(0);
1857: }


1862: /*@C
1863:    PetscOptionsMonitorDefault - Print all options set value events.

1865:    Collective on PETSC_COMM_WORLD

1867:    Input Parameters:
1868: +  name  - option name string
1869: .  value - option value string
1870: -  dummy - unused monitor context 

1872:    Level: intermediate

1874: .keywords: PetscOptions, default, monitor

1876: .seealso: PetscOptionsMonitorSet()
1877: @*/
1878: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1879: {
1881:   PetscViewer    viewer = (PetscViewer) dummy;

1884:   if (!viewer) {
1885:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1886:   }
1887:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1888:   return(0);
1889: }

1893: /*@C
1894:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1895:    modified the PETSc options database.
1896:       
1897:    Not collective

1899:    Input Parameters:
1900: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1901: .  mctx    - [optional] context for private data for the
1902:              monitor routine (use PETSC_NULL if no context is desired)
1903: -  monitordestroy - [optional] routine that frees monitor context
1904:           (may be PETSC_NULL)

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

1909: +  name - option name string
1910: .  value - option value string
1911: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1913:    Options Database Keys:
1914: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1915: -    -options_monitor_cancel - cancels all monitors that have
1916:                           been hardwired into a code by 
1917:                           calls to PetscOptionsMonitorSet(), but
1918:                           does not cancel those set via
1919:                           the options database.

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

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

1930:    Level: beginner

1932: .keywords: PetscOptions, set, monitor

1934: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1935: @*/
1936: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1937: {
1939:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1940:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1941:   }
1942:   options->monitor[options->numbermonitors]           = monitor;
1943:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1944:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1945:   return(0);
1946: }

1950: /*@
1951:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1953:    Not collective 

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

1960:    Level: intermediate

1962: .keywords: PetscOptions, set, monitor

1964: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1965: @*/
1966: PetscErrorCode  PetscOptionsMonitorCancel(void)
1967: {
1969:   PetscInt       i;

1972:   for (i=0; i<options->numbermonitors; i++) {
1973:     if (options->monitordestroy[i]) {
1974:       (*options->monitordestroy[i])(options->monitorcontext[i]);
1975:     }
1976:   }
1977:   options->numbermonitors = 0;
1978:   return(0);
1979: }