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;

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

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

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

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

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

103: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
104: {
106:   size_t         len;
107:   PetscTruth     decide,tdefault;

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

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

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

137: /*@C
138:     PetscGetProgramName - Gets the name of the running program. 

140:     Not Collective

142:     Input Parameter:
143: .   len - length of the string name

145:     Output Parameter:
146: .   name - the name of the running program

148:    Level: advanced

150:     Notes:
151:     The name of the program is copied into the user-provided character
152:     array of length len.  On some machines the program name includes 
153:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
154: @*/
155: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
156: {

160:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
161:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
162:   PetscStrncpy(name,options->programname,len);
163:   return(0);
164: }

168: PetscErrorCode  PetscSetProgramName(const char name[])
169: {

173:   options->namegiven = PETSC_TRUE;
174:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
175:   return(0);
176: }

180: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscTruth *key)
181: {
183:   *key = PETSC_FALSE;
184:   if (!in_str) return(0);
185:   if (in_str[0] != '-') return(0);
186:   if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
187:   *key = PETSC_TRUE;
188:   return(0);
189: }

193: /*@C
194:      PetscOptionsInsertString - Inserts options into the database from a string

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

199:   Input Parameter:
200: .   in_str - string that contains options separated by blanks


203:   Level: intermediate

205:   Contributed by Boyana Norris

207: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
208:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
209:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
210:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
211:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
212:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

214: @*/
215: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
216: {
217:   char           *first,*second;
219:   PetscToken     *token;
220:   PetscTruth     key;

223:   PetscTokenCreate(in_str,' ',&token);
224:   PetscTokenFind(token,&first);
225:   while (first) {
226:     PetscOptionsValidKey(first,&key);
227:     if (key) {
228:       PetscTokenFind(token,&second);
229:       PetscOptionsValidKey(second,&key);
230:       if (!key) {
231:         PetscOptionsSetValue(first,second);
232:         PetscTokenFind(token,&first);
233:       } else {
234:         PetscOptionsSetValue(first,PETSC_NULL);
235:         first = second;
236:       }
237:     } else {
238:       PetscTokenFind(token,&first);
239:     }
240:   }
241:   PetscTokenDestroy(token);
242:   return(0);
243: }

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

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

253:   Input Parameter:
254: .   file - name of file


257:   Level: intermediate

259: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
260:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
261:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
262:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
263:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
264:           PetscOptionsList(), PetscOptionsEList()

266: @*/
267: PetscErrorCode  PetscOptionsInsertFile(const char file[])
268: {
269:   char           string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
271:   size_t         i,len,startIndex;
272:   FILE           *fd;
273:   PetscToken     *token;

276:   PetscFixFilename(file,fname);
277:   fd   = fopen(fname,"r");
278:   if (fd) {
279:     while (fgets(string,128,fd)) {
280:       /* Comments are indicated by #, ! or % in the first column */
281:       if (string[0] == '#') continue;
282:       if (string[0] == '!') continue;
283:       if (string[0] == '%') continue;

285:       PetscStrlen(string,&len);

287:       /* replace tabs, ^M with " " */
288:       for (i=0; i<len; i++) {
289:         if (string[i] == '\t' || string[i] == '\r') {
290:           string[i] = ' ';
291:         }
292:       }
293:       for(startIndex = 0; startIndex < len-1; startIndex++) {
294:         if (string[startIndex] != ' ') break;
295:       }
296:       PetscTokenCreate(&string[startIndex],' ',&token);
297:       PetscTokenFind(token,&first);
298:       PetscTokenFind(token,&second);
299:       if (first && first[0] == '-') {
300:         if (second) {final = second;} else {final = first;}
301:         PetscStrlen(final,&len);
302:         while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
303:           len--; final[len] = 0;
304:         }
305:         PetscOptionsSetValue(first,second);
306:       } else if (first) {
307:         PetscTruth match;

309:         PetscStrcasecmp(first,"alias",&match);
310:         if (match) {
311:           PetscTokenFind(token,&third);
312:           if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
313:           PetscStrlen(third,&len);
314:           if (third[len-1] == '\n') third[len-1] = 0;
315:           PetscOptionsSetAlias(second,third);
316:         }
317:       }
318:       PetscTokenDestroy(token);
319:     }
320:     fclose(fd);
321:   } else {
322:     SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
323:   }
324:   return(0);
325: }

329: /*@C
330:    PetscOptionsInsert - Inserts into the options database from the command line,
331:                    the environmental variable and a file.

333:    Input Parameters:
334: +  argc - count of number of command line arguments
335: .  args - the command line arguments
336: -  file - optional filename, defaults to ~username/.petscrc

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

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

346:    Level: advanced

348:    Concepts: options database^adding

350: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
351:           PetscInitialize()
352: @*/
353: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
354: {
356:   PetscMPIInt    rank;
357:   char           pfile[PETSC_MAX_PATH_LEN];
358:   PetscTruth     flag;

361:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

363:   options->argc     = (argc) ? *argc : 0;
364:   options->args     = (args) ? *args : 0;

366:   if (file) {
367:     PetscOptionsInsertFile(file);
368:   }
369:   PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
370:   if (!flag) {
371:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
372:     if (pfile[0]) {
373:       PetscStrcat(pfile,"/.petscrc");
374:       PetscTestFile(pfile,'r',&flag);
375:       if (flag) {
376:         PetscOptionsInsertFile(pfile);
377:         PetscInfo(0,"Loading ~/.petscrc\n");
378:       }
379:     }
380:     PetscTestFile(".petscrc",'r',&flag);
381:     if (flag) {
382:       PetscOptionsInsertFile(".petscrc");
383:       PetscInfo(0,"Loading local directory file .petscrc\n");
384:     }
385:   }

387:   /* insert environmental options */
388:   {
389:     char   *eoptions = 0;
390:     size_t len = 0;
391:     if (!rank) {
392:       eoptions = (char*)getenv("PETSC_OPTIONS");
393:       PetscStrlen(eoptions,&len);
394:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
395:     } else {
396:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
397:       if (len) {
398:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
399:       }
400:     }
401:     if (len) {
402:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
403:       if (rank) eoptions[len] = 0;
404:       PetscOptionsInsertString(eoptions);
405:       if (rank) {PetscFree(eoptions);}
406:     }
407:   }

409:   /* insert command line options */
410:   if (argc && args && *argc) {
411:     int        left    = *argc - 1;
412:     char       **eargs = *args + 1;
413:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

415:     while (left) {
416:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
417:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
418:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
419:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
420:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
421:       isp4 = (PetscTruth) (isp4 || tisp4);
422:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
423:       isp4 = (PetscTruth) (isp4 || tisp4);
424:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

426:       if (eargs[0][0] != '-') {
427:         eargs++; left--;
428:       } else if (isoptions_file) {
429:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
430:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
431:         PetscOptionsInsertFile(eargs[1]);
432:         eargs += 2; left -= 2;

434:       /*
435:          These are "bad" options that MPICH, etc put on the command line
436:          we strip them out here.
437:       */
438:       } else if (tisp4 || isp4rmrank) {
439:         eargs += 1; left -= 1;
440:       } else if (isp4 || isp4yourname) {
441:         eargs += 2; left -= 2;
442:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
443:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
444:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
445:         eargs++; left--;
446:       } else {
447:         PetscOptionsSetValue(eargs[0],eargs[1]);
448:         eargs += 2; left -= 2;
449:       }
450:     }
451:   }
452:   return(0);
453: }

457: /*@C
458:    PetscOptionsPrint - Prints the options that have been loaded. This is
459:    useful for debugging purposes.

461:    Collective on PETSC_COMM_WORLD

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

466:    Options Database Key:
467: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

469:    Level: advanced

471:    Concepts: options database^printing

473: .seealso: PetscOptionsAllUsed()
474: @*/
475: PetscErrorCode  PetscOptionsPrint(FILE *fd)
476: {
478:   PetscInt       i;

481:   if (!fd) fd = stdout;
482:   if (!options) {PetscOptionsInsert(0,0,0);}
483:   for (i=0; i<options->N; i++) {
484:     if (options->values[i]) {
485:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
486:     } else {
487:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
488:     }
489:   }
490:   return(0);
491: }

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

498:    Not Collective

500:    Output Parameter:
501: .  copts - pointer where string pointer is stored

503:    Level: advanced

505:    Concepts: options database^listing

507: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
508: @*/
509: PetscErrorCode  PetscOptionsGetAll(char *copts[])
510: {
512:   PetscInt       i;
513:   size_t         len = 1,lent;
514:   char           *coptions;

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

519:   /* count the length of the required string */
520:   for (i=0; i<options->N; i++) {
521:     PetscStrlen(options->names[i],&lent);
522:     len += 2 + lent;
523:     if (options->values[i]) {
524:       PetscStrlen(options->values[i],&lent);
525:       len += 1 + lent;
526:     }
527:   }
528:   PetscMalloc(len*sizeof(char),&coptions);
529:   coptions[0] = 0;
530:   for (i=0; i<options->N; i++) {
531:     PetscStrcat(coptions,"-");
532:     PetscStrcat(coptions,options->names[i]);
533:     PetscStrcat(coptions," ");
534:     if (options->values[i]) {
535:       PetscStrcat(coptions,options->values[i]);
536:       PetscStrcat(coptions," ");
537:     }
538:   }
539:   *copts = coptions;
540:   return(0);
541: }

545: /*@C
546:     PetscOptionsDestroy - Destroys the option database. 

548:     Note:
549:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
550:     typically does not need to call this routine.

552:    Level: developer

554: .seealso: PetscOptionsInsert()
555: @*/
556: PetscErrorCode  PetscOptionsDestroy(void)
557: {
558:   PetscInt i;

561:   if (!options) return(0);
562:   for (i=0; i<options->N; i++) {
563:     if (options->names[i]) free(options->names[i]);
564:     if (options->values[i]) free(options->values[i]);
565:   }
566:   for (i=0; i<options->Naliases; i++) {
567:     free(options->aliases1[i]);
568:     free(options->aliases2[i]);
569:   }
570:   free(options);
571:   options = 0;
572:   return(0);
573: }

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

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

584:    Input Parameters:
585: +  name - name of option, this SHOULD have the - prepended
586: -  value - the option value (not used for all options)

588:    Level: intermediate

590:    Note:
591:    Only some options have values associated with them, such as
592:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

594:   Concepts: options database^adding option

596: .seealso: PetscOptionsInsert()
597: @*/
598: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
599: {
600:   size_t         len;
602:   PetscInt       N,n,i;
603:   char           **names;
604:   const char     *name = (char*)iname;
605:   PetscTruth     gt,match;

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

610:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
611:   PetscStrcasecmp(name,"-h",&match);
612:   if (match) name = "-help";

614:   name++;
615:   /* first check against aliases */
616:   N = options->Naliases;
617:   for (i=0; i<N; i++) {
618:     PetscStrcasecmp(options->aliases1[i],name,&match);
619:     if (match) {
620:       name = options->aliases2[i];
621:       break;
622:     }
623:   }

625:   N     = options->N;
626:   n     = N;
627:   names = options->names;
628: 
629:   for (i=0; i<N; i++) {
630:     PetscStrcasecmp(names[i],name,&match);
631:     PetscStrgrt(names[i],name,&gt);
632:     if (match) {
633:       if (options->values[i]) free(options->values[i]);
634:       PetscStrlen(value,&len);
635:       if (len) {
636:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
637:         PetscStrcpy(options->values[i],value);
638:       } else { options->values[i] = 0;}
639:       PetscOptionsMonitor(name,value);
640:       return(0);
641:     } else if (gt) {
642:       n = i;
643:       break;
644:     }
645:   }
646:   if (N >= MAXOPTIONS) {
647:     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);
648:   }
649:   /* shift remaining values down 1 */
650:   for (i=N; i>n; i--) {
651:     names[i]           = names[i-1];
652:     options->values[i] = options->values[i-1];
653:     options->used[i]   = options->used[i-1];
654:   }
655:   /* insert new name and value */
656:   PetscStrlen(name,&len);
657:   names[n] = (char*)malloc((len+1)*sizeof(char));
658:   PetscStrcpy(names[n],name);
659:   if (value) {
660:     PetscStrlen(value,&len);
661:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
662:     PetscStrcpy(options->values[n],value);
663:   } else {options->values[n] = 0;}
664:   options->used[n] = PETSC_FALSE;
665:   options->N++;
666:   PetscOptionsMonitor(name,value);
667:   return(0);
668: }

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

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

679:    Input Parameter:
680: .  name - name of option, this SHOULD have the - prepended

682:    Level: intermediate

684:    Concepts: options database^removing option
685: .seealso: PetscOptionsInsert()
686: @*/
687: PetscErrorCode  PetscOptionsClearValue(const char iname[])
688: {
690:   PetscInt       N,n,i;
691:   char           **names,*name=(char*)iname;
692:   PetscTruth     gt,match;

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

698:   name++;

700:   N     = options->N; n = 0;
701:   names = options->names;
702: 
703:   for (i=0; i<N; i++) {
704:     PetscStrcasecmp(names[i],name,&match);
705:     PetscStrgrt(names[i],name,&gt);
706:     if (match) {
707:       if (options->values[i]) free(options->values[i]);
708:       PetscOptionsMonitor(name,"");
709:       break;
710:     } else if (gt) {
711:       return(0); /* it was not listed */
712:     }
713:     n++;
714:   }
715:   if (n == N) return(0); /* it was not listed */

717:   /* shift remaining values down 1 */
718:   for (i=n; i<N-1; i++) {
719:     names[i]           = names[i+1];
720:     options->values[i] = options->values[i+1];
721:     options->used[i]   = options->used[i+1];
722:   }
723:   options->N--;
724:   return(0);
725: }

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

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

735:    Input Parameters:
736: +  name - the option one is seeking 
737: -  mess - error message (may be PETSC_NULL)

739:    Level: advanced

741:    Concepts: options database^rejecting option

743: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
744:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
745:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
746:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
747:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
748:           PetscOptionsList(), PetscOptionsEList()
749: @*/
750: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
751: {
753:   PetscInt       n = options->Naliases;
754:   size_t         len;
755:   char           *newname = (char *)inewname,*oldname = (char*)ioldname;

758:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
759:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
760:   if (n >= MAXALIASES) {
761:     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);
762:   }

764:   newname++; oldname++;
765:   PetscStrlen(newname,&len);
766:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
767:   PetscStrcpy(options->aliases1[n],newname);
768:   PetscStrlen(oldname,&len);
769:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
770:   PetscStrcpy(options->aliases2[n],oldname);
771:   options->Naliases++;
772:   return(0);
773: }

777: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
778: {
780:   PetscInt       i,N;
781:   size_t         len;
782:   char           **names,tmp[256];
783:   PetscTruth     match;

786:   if (!options) {PetscOptionsInsert(0,0,0);}
787:   N = options->N;
788:   names = options->names;

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

792:   /* append prefix to name */
793:   if (pre) {
794:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
795:     PetscStrncpy(tmp,pre,256);
796:     PetscStrlen(tmp,&len);
797:     PetscStrncat(tmp,name+1,256-len-1);
798:   } else {
799:     PetscStrncpy(tmp,name+1,256);
800:   }

802:   /* slow search */
803:   *flg = PETSC_FALSE;
804:   for (i=0; i<N; i++) {
805:     PetscStrcasecmp(names[i],tmp,&match);
806:     if (match) {
807:        *value           = options->values[i];
808:        options->used[i] = PETSC_TRUE;
809:        *flg             = PETSC_TRUE;
810:        break;
811:      }
812:   }
813:   if (!*flg) {
814:     PetscInt j,cnt = 0,locs[16],loce[16];
815:     size_t   n;
816:     PetscStrlen(tmp,&n);
817:     /* determine the location and number of all _%d_ in the key */
818:     for (i=0; i< (PetscInt)n; i++) {
819:       if (tmp[i] == '_') {
820:         for (j=i+1; j< (PetscInt)n; j++) {
821:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
822:           if (tmp[j] == '_' && j > i+1) { /* found a number */
823:             locs[cnt]   = i+1;
824:             loce[cnt++] = j+1;
825:           }
826:           break;
827:         }
828:       }
829:     }
830:     if (cnt) {
831:       char tmp2[256];
832:       for (i=0; i<cnt; i++) {
833:         PetscStrcpy(tmp2,"-");
834:         PetscStrncat(tmp2,tmp,locs[i]);
835:         PetscStrcat(tmp2,tmp+loce[i]);
836:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
837:         if (*flg) break;
838:       }
839:     }
840:   }
841:   return(0);
842: }

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

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

852:    Input Parameters:
853: +  name - the option one is seeking 
854: -  mess - error message (may be PETSC_NULL)

856:    Level: advanced

858:    Concepts: options database^rejecting option

860: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
861:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
862:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
863:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
864:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
865:           PetscOptionsList(), PetscOptionsEList()
866: @*/
867: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
868: {
870:   PetscTruth     flag;

873:   PetscOptionsHasName(PETSC_NULL,name,&flag);
874:   if (flag) {
875:     if (mess) {
876:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
877:     } else {
878:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
879:     }
880:   }
881:   return(0);
882: }

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

889:    Not Collective

891:    Input Parameters:
892: +  name - the option one is seeking 
893: -  pre - string to prepend to the name or PETSC_NULL

895:    Output Parameters:
896: .  flg - PETSC_TRUE if found else PETSC_FALSE.

898:    Level: beginner

900:    Concepts: options database^has option name

902:    Notes: Name cannot be simply -h

904: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
905:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
906:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
907:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
908:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
909:           PetscOptionsList(), PetscOptionsEList()
910: @*/
911: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
912: {
913:   char           *value;
915:   PetscTruth     isfalse,flag;

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

920:   /* remove if turned off */
921:   if (flag) {
922:     PetscStrcasecmp(value,"FALSE",&isfalse);
923:     if (isfalse) flag = PETSC_FALSE;
924:     PetscStrcasecmp(value,"NO",&isfalse);
925:     if (isfalse) flag = PETSC_FALSE;
926:     PetscStrcasecmp(value,"0",&isfalse);
927:     if (isfalse) flag = PETSC_FALSE;
928:   }
929:   if (flg) *flg = flag;
930:   return(0);
931: }

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

938:    Not Collective

940:    Input Parameters:
941: +  pre - the string to prepend to the name or PETSC_NULL
942: -  name - the option one is seeking

944:    Output Parameter:
945: +  ivalue - the integer value to return
946: -  flg - PETSC_TRUE if found, else PETSC_FALSE

948:    Level: beginner

950:    Concepts: options database^has int

952: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
953:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
954:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
955:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
956:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
957:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
958:           PetscOptionsList(), PetscOptionsEList()
959: @*/
960: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
961: {
962:   char           *value;
964:   PetscTruth     flag;

969:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
970:   if (flag) {
971:     if (!value) {if (flg) *flg = PETSC_FALSE;}
972:     else {
973:       if (flg) *flg = PETSC_TRUE;
974:       PetscOptionsAtoi(value,ivalue);
975:     }
976:   } else {
977:     if (flg) *flg = PETSC_FALSE;
978:   }
979:   return(0);
980: }

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

987:    Not Collective

989:    Input Parameters:
990: +  pre - the string to prepend to the name or PETSC_NULL
991: .  opt - option name
992: .  list - the possible choices
993: .  ntext - number of choices

995:    Output Parameter:
996: +  value - the index of the value to return
997: -  set - PETSC_TRUE if found, else PETSC_FALSE
998:    
999:    Level: intermediate

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

1003:    Concepts: options database^list

1005: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1006:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1007:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1008:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1009:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1010:           PetscOptionsList(), PetscOptionsEList()
1011: @*/
1012: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1013: {
1015:   size_t         alen,len = 0;
1016:   char           *svalue;
1017:   PetscTruth     aset,flg = PETSC_FALSE;
1018:   PetscInt       i;

1021:   for ( i=0; i<ntext; i++) {
1022:     PetscStrlen(list[i],&alen);
1023:     if (alen > len) len = alen;
1024:   }
1025:   len += 5; /* a little extra space for user mistypes */
1026:   PetscMalloc(len*sizeof(char),&svalue);
1027:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1028:   if (aset) {
1029:     if (set) *set = PETSC_TRUE;
1030:     for (i=0; i<ntext; i++) {
1031:       PetscStrcasecmp(svalue,list[i],&flg);
1032:       if (flg) {
1033:         *value = i;
1034:         break;
1035:       }
1036:     }
1037:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1038:   } else if (set) {
1039:     *set = PETSC_FALSE;
1040:   }
1041:   PetscFree(svalue);
1042:   return(0);
1043: }

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

1050:    Not Collective

1052:    Input Parameters:
1053: +  pre - option prefix or PETSC_NULL
1054: .  opt - option name
1055: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1056: -  defaultv - the default (current) value

1058:    Output Parameter:
1059: +  value - the  value to return
1060: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1062:    Level: beginner

1064:    Concepts: options database

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

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

1070: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1071:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1072:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1073:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1074:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1075:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1076:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1077: @*/
1078: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1079: {
1081:   PetscInt       ntext = 0;

1084:   while (list[ntext++]) {
1085:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1086:   }
1087:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1088:   ntext -= 3;
1089:   PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1090:   return(0);
1091: }

1095: /*@C
1096:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1097:             option in the database.

1099:    Not Collective

1101:    Input Parameters:
1102: +  pre - the string to prepend to the name or PETSC_NULL
1103: -  name - the option one is seeking

1105:    Output Parameter:
1106: +  ivalue - the logical value to return
1107: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1109:    Level: beginner

1111:    Notes:
1112:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1113:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1115:    Concepts: options database^has logical

1117: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1118:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1119:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1120:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1121:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1122:           PetscOptionsList(), PetscOptionsEList()
1123: @*/
1124: PetscErrorCode  PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1125: {
1126:   char           *value;
1127:   PetscTruth     flag,istrue,isfalse;

1133:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1134:   if (flag) {
1135:     if (flg) *flg = PETSC_TRUE;
1136:     if (!value) {
1137:       *ivalue = PETSC_TRUE;
1138:     } else {
1139:       *ivalue = PETSC_TRUE;
1140:       PetscStrcasecmp(value,"TRUE",&istrue);
1141:       if (istrue) return(0);
1142:       PetscStrcasecmp(value,"YES",&istrue);
1143:       if (istrue) return(0);
1144:       PetscStrcasecmp(value,"1",&istrue);
1145:       if (istrue) return(0);
1146:       PetscStrcasecmp(value,"on",&istrue);
1147:       if (istrue) return(0);

1149:       *ivalue = PETSC_FALSE;
1150:       PetscStrcasecmp(value,"FALSE",&isfalse);
1151:       if (isfalse) return(0);
1152:       PetscStrcasecmp(value,"NO",&isfalse);
1153:       if (isfalse) return(0);
1154:       PetscStrcasecmp(value,"0",&isfalse);
1155:       if (isfalse) return(0);
1156:       PetscStrcasecmp(value,"off",&isfalse);
1157:       if (isfalse) return(0);

1159:       SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1160:     }
1161:   } else {
1162:     if (flg) *flg = PETSC_FALSE;
1163:   }
1164:   return(0);
1165: }

1169: /*@C
1170:    PetscOptionsGetReal - Gets the double precision value for a particular 
1171:    option in the database.

1173:    Not Collective

1175:    Input Parameters:
1176: +  pre - string to prepend to each name or PETSC_NULL
1177: -  name - the option one is seeking

1179:    Output Parameter:
1180: +  dvalue - the double value to return
1181: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1183:    Level: beginner

1185:    Concepts: options database^has double

1187: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1188:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1189:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1190:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1191:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1192:           PetscOptionsList(), PetscOptionsEList()
1193: @*/
1194: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1195: {
1196:   char           *value;
1198:   PetscTruth     flag;

1203:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1204:   if (flag) {
1205:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1206:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1207:   } else {
1208:     if (flg) *flg = PETSC_FALSE;
1209:   }
1210:   return(0);
1211: }

1215: /*@C
1216:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1217:    option in the database.

1219:    Not Collective

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

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

1229:    Level: beginner

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

1235:    Concepts: options database^has scalar

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

1253:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1254:   if (flag) {
1255:     if (!value) {
1256:       if (flg) *flg = PETSC_FALSE;
1257:     } else {
1258: #if !defined(PETSC_USE_COMPLEX)
1259:       PetscOptionsAtod(value,dvalue);
1260: #else
1261:       PetscReal  re=0.0,im=0.0;
1262:       PetscToken *token;
1263:       char       *tvalue = 0;

1265:       PetscTokenCreate(value,',',&token);
1266:       PetscTokenFind(token,&tvalue);
1267:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1268:       PetscOptionsAtod(tvalue,&re);
1269:       PetscTokenFind(token,&tvalue);
1270:       if (!tvalue) { /* Unknown separator used. using only real value */
1271:         *dvalue = re;
1272:       } else {
1273:         PetscOptionsAtod(tvalue,&im);
1274:         *dvalue = re + PETSC_i*im;
1275:       }
1276:       PetscTokenDestroy(token);
1277: #endif
1278:       if (flg) *flg    = PETSC_TRUE;
1279:     }
1280:   } else { /* flag */
1281:     if (flg) *flg = PETSC_FALSE;
1282:   }
1283:   return(0);
1284: }

1288: /*@C
1289:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1290:    particular option in the database.  The values must be separated with 
1291:    commas with no intervening spaces.

1293:    Not Collective

1295:    Input Parameters:
1296: +  pre - string to prepend to each name or PETSC_NULL
1297: .  name - the option one is seeking
1298: -  nmax - maximum number of values to retrieve

1300:    Output Parameters:
1301: +  dvalue - the double value to return
1302: .  nmax - actual number of values retreived
1303: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1305:    Level: beginner

1307:    Concepts: options database^array of doubles

1309: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1310:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1311:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1312:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1313:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1314:           PetscOptionsList(), PetscOptionsEList()
1315: @*/
1316: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1317: {
1318:   char           *value;
1320:   PetscInt       n = 0;
1321:   PetscTruth     flag;
1322:   PetscToken     *token;

1327:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1328:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1329:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1331:   if (flg) *flg = PETSC_TRUE;

1333:   PetscTokenCreate(value,',',&token);
1334:   PetscTokenFind(token,&value);
1335:   while (n < *nmax) {
1336:     if (!value) break;
1337:     PetscOptionsAtod(value,dvalue++);
1338:     PetscTokenFind(token,&value);
1339:     n++;
1340:   }
1341:   PetscTokenDestroy(token);
1342:   *nmax = n;
1343:   return(0);
1344: }

1348: /*@C
1349:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1350:    option in the database.  The values must be separated with commas with 
1351:    no intervening spaces. 

1353:    Not Collective

1355:    Input Parameters:
1356: +  pre - string to prepend to each name or PETSC_NULL
1357: .  name - the option one is seeking
1358: -  nmax - maximum number of values to retrieve

1360:    Output Parameter:
1361: +  dvalue - the integer values to return
1362: .  nmax - actual number of values retreived
1363: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1365:    Level: beginner

1367:    Concepts: options database^array of ints

1369: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1370:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1371:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1372:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1373:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1374:           PetscOptionsList(), PetscOptionsEList()
1375: @*/
1376: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1377: {
1378:   char           *value;
1380:   PetscInt       n = 0,i,start,end;
1381:   size_t         len;
1382:   PetscTruth     flag,foundrange;
1383:   PetscToken     *token;

1388:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1389:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1390:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1392:   if (flg) *flg = PETSC_TRUE;

1394:   PetscTokenCreate(value,',',&token);
1395:   PetscTokenFind(token,&value);
1396:   while (n < *nmax) {
1397:     if (!value) break;
1398: 
1399:     /* look for form  d-D where d and D are integers */
1400:     foundrange = PETSC_FALSE;
1401:     PetscStrlen(value,&len);
1402:     if (value[0] == '-') i=2;
1403:     else i=1;
1404:     for (;i<(int)len; i++) {
1405:       if (value[i] == '-') {
1406:         if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1407:         value[i] = 0;
1408:         PetscOptionsAtoi(value,&start);
1409:         PetscOptionsAtoi(value+i+1,&end);
1410:         if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1411:         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);
1412:         for (;start<end; start++) {
1413:           *dvalue = start; dvalue++;n++;
1414:         }
1415:         foundrange = PETSC_TRUE;
1416:         break;
1417:       }
1418:     }
1419:     if (!foundrange) {
1420:       PetscOptionsAtoi(value,dvalue);
1421:       dvalue++;
1422:       n++;
1423:     }
1424:     PetscTokenFind(token,&value);
1425:   }
1426:   PetscTokenDestroy(token);
1427:   *nmax = n;
1428:   return(0);
1429: }

1433: /*@C
1434:    PetscOptionsGetString - Gets the string value for a particular option in
1435:    the database.

1437:    Not Collective

1439:    Input Parameters:
1440: +  pre - string to prepend to name or PETSC_NULL
1441: .  name - the option one is seeking
1442: -  len - maximum string length

1444:    Output Parameters:
1445: +  string - location to copy string
1446: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1448:    Level: beginner

1450:    Fortran Note:
1451:    The Fortran interface is slightly different from the C/C++
1452:    interface (len is not used).  Sample usage in Fortran follows
1453: .vb
1454:       character *20 string
1455:       integer   flg, ierr
1456:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1457: .ve

1459:    Concepts: options database^string

1461: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1462:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1463:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1464:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1465:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1466:           PetscOptionsList(), PetscOptionsEList()
1467: @*/
1468: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1469: {
1470:   char           *value;
1472:   PetscTruth     flag;

1477:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1478:   if (!flag) {
1479:     if (flg) *flg = PETSC_FALSE;
1480:   } else {
1481:     if (flg) *flg = PETSC_TRUE;
1482:     if (value) {
1483:       PetscStrncpy(string,value,len);
1484:     } else {
1485:       PetscMemzero(string,len);
1486:     }
1487:   }
1488:   return(0);
1489: }

1493: /*@C
1494:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1495:    option in the database. The values must be separated with commas with 
1496:    no intervening spaces. 

1498:    Not Collective

1500:    Input Parameters:
1501: +  pre - string to prepend to name or PETSC_NULL
1502: .  name - the option one is seeking
1503: -  nmax - maximum number of strings

1505:    Output Parameter:
1506: +  strings - location to copy strings
1507: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1509:    Level: beginner

1511:    Notes: 
1512:    The user should pass in an array of pointers to char, to hold all the
1513:    strings returned by this function.

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

1518:    Contributed by Matthew Knepley.

1520:    Concepts: options database^array of strings

1522: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1523:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1524:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1525:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1526:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1527:           PetscOptionsList(), PetscOptionsEList()
1528: @*/
1529: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1530: {
1531:   char           *value;
1533:   PetscInt       n;
1534:   PetscTruth     flag;
1535:   PetscToken     *token;
1536: 
1540:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1541:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1542:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1543:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1544:   if (flg) *flg = PETSC_TRUE;

1546:   PetscTokenCreate(value,',',&token);
1547:   PetscTokenFind(token,&value);
1548:   n = 0;
1549:   while (n < *nmax) {
1550:     if (!value) break;
1551:     PetscStrallocpy(value,&strings[n]);
1552:     PetscTokenFind(token,&value);
1553:     n++;
1554:   }
1555:   PetscTokenDestroy(token);
1556:   *nmax = n;
1557:   return(0);
1558: }

1562: /*@C
1563:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1564:    database that have never been selected.

1566:    Not Collective

1568:    Output Parameter:
1569: .   N - count of options not used

1571:    Level: advanced

1573: .seealso: PetscOptionsPrint()
1574: @*/
1575: PetscErrorCode  PetscOptionsAllUsed(int *N)
1576: {
1577:   PetscInt i,n = 0;

1580:   for (i=0; i<options->N; i++) {
1581:     if (!options->used[i]) { n++; }
1582:   }
1583:   *N = n;
1584:   return(0);
1585: }

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

1592:   Not collective

1594:    Options Database Key:
1595: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1597:   Level: advanced

1599: .seealso: PetscOptionsAllUsed()
1600: @*/
1601: PetscErrorCode  PetscOptionsLeft(void)
1602: {
1604:   PetscInt       i;

1607:   for (i=0; i<options->N; i++) {
1608:     if (!options->used[i]) {
1609:       if (options->values[i]) {
1610:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1611:       } else {
1612:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1613:       }
1614:     }
1615:   }
1616:   return(0);
1617: }


1620: /*
1621:     PetscOptionsCreate - Creates the empty options database.

1623: */
1626: PetscErrorCode  PetscOptionsCreate(void)
1627: {

1631:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1632:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1633:   options->namegiven                 = PETSC_FALSE;
1634:   options->N                         = 0;
1635:   options->Naliases                  = 0;
1636:   options->numbermonitors         = 0;
1637: 
1638:   return(0);
1639: }

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

1646:    Collective on PETSC_COMM_WORLD

1648:    Options Database Keys:
1649: +  -options_monitor <optional filename> - prints the names and values of all 
1650:                                  runtime options as they are set. The monitor functionality is not 
1651:                 available for options set through a file, environment variable, or on 
1652:                 the command line. Only options set after PetscInitialize completes will 
1653:                 be monitored.
1654: .  -options_monitor_cancel - cancel all options database monitors    

1656:    Notes:
1657:    To see all options, run your program with the -help option or consult
1658:    the users manual. 

1660:    Level: intermediate

1662: .keywords: set, options, database
1663: @*/
1664: PetscErrorCode  PetscOptionsSetFromOptions()
1665: {
1666:   PetscTruth          flg;
1667:   PetscErrorCode      ierr;
1668:   char                monfilename[PETSC_MAX_PATH_LEN];
1669:   PetscViewer         monviewer;


1673:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1674:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1675:   if (flg && (!options->numbermonitors)) {
1676:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1677:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1678:   }
1679: 
1680:   PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1681:   if (flg) { PetscOptionsMonitorCancel(); }
1682: 
1683:   PetscOptionsEnd();

1685:   return(0);
1686: }


1691: /*@C
1692:    PetscOptionsMonitorDefault - Print all options set value events.

1694:    Collective on PETSC_COMM_WORLD

1696:    Input Parameters:
1697: +  name  - option name string
1698: .  value - option value string
1699: -  dummy - unused monitor context 

1701:    Level: intermediate

1703: .keywords: PetscOptions, default, monitor

1705: .seealso: PetscOptionsMonitorSet()
1706: @*/
1707: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1708: {
1710:   PetscViewer    viewer = (PetscViewer) dummy;

1713:   if (!viewer) {
1714:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1715:   }
1716:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1717:   return(0);
1718: }

1722: /*@C
1723:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1724:    modified the PETSc options database.
1725:       
1726:    Not collective

1728:    Input Parameters:
1729: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1730: .  mctx    - [optional] context for private data for the
1731:              monitor routine (use PETSC_NULL if no context is desired)
1732: -  monitordestroy - [optional] routine that frees monitor context
1733:           (may be PETSC_NULL)

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

1738: +  name - option name string
1739: .  value - option value string
1740: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

1742:    Options Database Keys:
1743: +    -options_monitor    - sets PetscOptionsMonitorDefault()
1744: -    -options_monitor_cancel - cancels all monitors that have
1745:                           been hardwired into a code by 
1746:                           calls to PetscOptionsMonitorSet(), but
1747:                           does not cancel those set via
1748:                           the options database.

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

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

1759:    Level: beginner

1761: .keywords: PetscOptions, set, monitor

1763: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1764: @*/
1765: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1766: {
1768:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1769:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1770:   }
1771:   options->monitor[options->numbermonitors]           = monitor;
1772:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1773:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1774:   return(0);
1775: }

1779: /*@
1780:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1782:    Not collective 

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

1789:    Level: intermediate

1791: .keywords: PetscOptions, set, monitor

1793: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1794: @*/
1795: PetscErrorCode  PetscOptionsMonitorCancel(void)
1796: {
1798:   PetscInt       i;

1801:   for (i=0; i<options->numbermonitors; i++) {
1802:     if (options->monitordestroy[i]) {
1803:       (*options->monitordestroy[i])(options->monitorcontext[i]);
1804:     }
1805:   }
1806:   options->numbermonitors = 0;
1807:   return(0);
1808: }