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: /*@C
181:      PetscOptionsInsertString - Inserts options into the database from a string

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

186:   Input Parameter:
187: .   in_str - string that contains options separated by blanks


190:   Level: intermediate

192:   Contributed by Boyana Norris

194: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
195:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
196:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
197:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
198:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
199:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

201: @*/
202: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
203: {
204:   char           *str,*first,*second,*third,*final;
205:   size_t         len;
207:   PetscToken     *token;

210:   PetscStrallocpy(in_str, &str);
211:   PetscTokenCreate(str,' ',&token);
212:   PetscTokenFind(token,&first);
213:   PetscTokenFind(token,&second);
214:   if (first && first[0] == '-') {
215:     if (second) {final = second;} else {final = first;}
216:     PetscStrlen(final,&len);
217:     while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
218:       len--; final[len] = 0;
219:     }
220:     PetscOptionsSetValue(first,second);
221:   } else if (first) {
222:     PetscTruth match;
223: 
224:     PetscStrcasecmp(first,"alias",&match);
225:     if (match) {
226:       PetscTokenFind(token,&third);
227:       if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
228:       PetscStrlen(third,&len);
229:       if (third[len-1] == 'n') third[len-1] = 0;
230:       PetscOptionsSetAlias(second,third);
231:     }
232:   }
233:   PetscTokenDestroy(token);
234:   PetscFree(str);
235: 
236:   return(0);
237: }

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

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

247:   Input Parameter:
248: .   file - name of file


251:   Level: intermediate

253: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
254:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
255:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
256:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
257:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
258:           PetscOptionsList(), PetscOptionsEList()

260: @*/
261: PetscErrorCode  PetscOptionsInsertFile(const char file[])
262: {
263:   char           string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
265:   size_t         i,len,startIndex;
266:   FILE           *fd;
267:   PetscToken     *token;

270:   PetscFixFilename(file,fname);
271:   fd   = fopen(fname,"r");
272:   if (fd) {
273:     while (fgets(string,128,fd)) {
274:       /* Comments are indicated by #, ! or % in the first column */
275:       if (string[0] == '#') continue;
276:       if (string[0] == '!') continue;
277:       if (string[0] == '%') continue;

279:       PetscStrlen(string,&len);

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

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

323: /*@C
324:    PetscOptionsInsert - Inserts into the options database from the command line,
325:                    the environmental variable and a file.

327:    Input Parameters:
328: +  argc - count of number of command line arguments
329: .  args - the command line arguments
330: -  file - optional filename, defaults to ~username/.petscrc

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

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

340:    Level: advanced

342:    Concepts: options database^adding

344: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
345: @*/
346: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
347: {
349:   PetscMPIInt    rank;
350:   char           pfile[PETSC_MAX_PATH_LEN];
351:   PetscToken     *token;

354:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

356:   options->argc     = (argc) ? *argc : 0;
357:   options->args     = (args) ? *args : 0;

359:   if (file) {
360:     PetscOptionsInsertFile(file);
361:   } else {
362:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
363:     if (pfile[0]) {
364:       PetscTruth flag;
365:       PetscStrcat(pfile,"/.petscrc");
366:       PetscTestFile(pfile,'r',&flag);
367:       if (flag) {
368:         PetscOptionsInsertFile(pfile);
369:       }
370:     } else {
371:       PetscInfo(0,"Unable to determine home directory; skipping loading ~/.petscrc\n");
372:     }

374:   }

376:   /* insert environmental options */
377:   {
378:     char   *eoptions = 0,*second,*first;
379:     size_t len = 0;
380:     if (!rank) {
381:       eoptions = (char*)getenv("PETSC_OPTIONS");
382:       PetscStrlen(eoptions,&len);
383:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
384:     } else {
385:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
386:       if (len) {
387:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
388:       }
389:     }
390:     if (len) {
391:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
392:       eoptions[len] = 0;
393:        PetscTokenCreate(eoptions,' ',&token);
394:        PetscTokenFind(token,&first);
395:       while (first) {
396:         if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
397:         PetscTokenFind(token,&second);
398:         if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
399:           PetscOptionsSetValue(first,(char *)0);
400:           first = second;
401:         } else {
402:           PetscOptionsSetValue(first,second);
403:           PetscTokenFind(token,&first);
404:         }
405:       }
406:        PetscTokenDestroy(token);
407:       if (rank) {PetscFree(eoptions);}
408:     }
409:   }

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

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

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

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

460: /*@C
461:    PetscOptionsPrint - Prints the options that have been loaded. This is
462:    useful for debugging purposes.

464:    Collective on PETSC_COMM_WORLD

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

469:    Options Database Key:
470: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

472:    Level: advanced

474:    Concepts: options database^printing

476: .seealso: PetscOptionsAllUsed()
477: @*/
478: PetscErrorCode  PetscOptionsPrint(FILE *fd)
479: {
481:   PetscInt       i;

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

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

501:    Not Collective

503:    Output Parameter:
504: .  copts - pointer where string pointer is stored

506:    Level: advanced

508:    Concepts: options database^listing

510: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
511: @*/
512: PetscErrorCode  PetscOptionsGetAll(char *copts[])
513: {
515:   PetscInt       i;
516:   size_t         len = 1,lent;
517:   char           *coptions;

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

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

548: /*@C
549:     PetscOptionsDestroy - Destroys the option database. 

551:     Note:
552:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
553:     typically does not need to call this routine.

555:    Level: developer

557: .seealso: PetscOptionsInsert()
558: @*/
559: PetscErrorCode  PetscOptionsDestroy(void)
560: {
561:   PetscInt i;

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

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

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

587:    Input Parameters:
588: +  name - name of option, this SHOULD have the - prepended
589: -  value - the option value (not used for all options)

591:    Level: intermediate

593:    Note:
594:    Only some options have values associated with them, such as
595:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

597:   Concepts: options database^adding option

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

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

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

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

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

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

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

681:    Input Parameter:
682: .  name - name of option, this SHOULD have the - prepended

684:    Level: intermediate

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

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

700:   name++;

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

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

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

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

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

741:    Level: advanced

743:    Concepts: options database^rejecting option

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

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

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

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

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

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

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

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

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

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

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

858:    Level: advanced

860:    Concepts: options database^rejecting option

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

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

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

891:    Not Collective

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

897:    Output Parameters:
898: .  flg - PETSC_TRUE if found else PETSC_FALSE.

900:    Level: beginner

902:    Concepts: options database^has option name

904:    Notes: Name cannot be simply -h

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

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

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

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

940:    Not Collective

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

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

950:    Level: beginner

952:    Concepts: options database^has int

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

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

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

989:    Not Collective

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

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

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

1005:    Concepts: options database^list

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

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

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

1052:    Not Collective

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

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

1064:    Level: beginner

1066:    Concepts: options database

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

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

1072: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
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(), PetscOptionsGetEList(), PetscOptionsEnum()
1079: @*/
1080: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1081: {
1083:   PetscInt       ntext = 0;

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

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

1101:    Not Collective

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

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

1111:    Level: beginner

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

1117:    Concepts: options database^has logical

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

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

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

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

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

1175:    Not Collective

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

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

1185:    Level: beginner

1187:    Concepts: options database^has double

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

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

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

1221:    Not Collective

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

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

1231:    Level: beginner

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

1237:    Concepts: options database^has scalar

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

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

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

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

1295:    Not Collective

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

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

1307:    Level: beginner

1309:    Concepts: options database^array of doubles

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

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

1333:   if (flg) *flg = PETSC_TRUE;

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

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

1355:    Not Collective

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

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

1367:    Level: beginner

1369:    Concepts: options database^array of ints

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

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

1393:   if (flg) *flg = PETSC_TRUE;

1395:   PetscTokenCreate(value,',',&token);
1396:   PetscTokenFind(token,&value);
1397:   while (n < *nmax) {
1398:     if (!value) break;
1399:     PetscOptionsAtoi(value,dvalue);
1400:     dvalue++;
1401:     PetscTokenFind(token,&value);
1402:     n++;
1403:   }
1404:   PetscTokenDestroy(token);
1405:   *nmax = n;
1406:   return(0);
1407: }

1411: /*@C
1412:    PetscOptionsGetString - Gets the string value for a particular option in
1413:    the database.

1415:    Not Collective

1417:    Input Parameters:
1418: +  pre - string to prepend to name or PETSC_NULL
1419: .  name - the option one is seeking
1420: -  len - maximum string length

1422:    Output Parameters:
1423: +  string - location to copy string
1424: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1426:    Level: beginner

1428:    Fortran Note:
1429:    The Fortran interface is slightly different from the C/C++
1430:    interface (len is not used).  Sample usage in Fortran follows
1431: .vb
1432:       character *20 string
1433:       integer   flg, ierr
1434:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1435: .ve

1437:    Concepts: options database^string

1439: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1440:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1441:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1442:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1443:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1444:           PetscOptionsList(), PetscOptionsEList()
1445: @*/
1446: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1447: {
1448:   char           *value;
1450:   PetscTruth     flag;

1455:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1456:   if (!flag) {
1457:     if (flg) *flg = PETSC_FALSE;
1458:   } else {
1459:     if (flg) *flg = PETSC_TRUE;
1460:     if (value) {
1461:       PetscStrncpy(string,value,len);
1462:     } else {
1463:       PetscMemzero(string,len);
1464:     }
1465:   }
1466:   return(0);
1467: }

1471: /*@C
1472:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1473:    option in the database. The values must be separated with commas with 
1474:    no intervening spaces. 

1476:    Not Collective

1478:    Input Parameters:
1479: +  pre - string to prepend to name or PETSC_NULL
1480: .  name - the option one is seeking
1481: -  nmax - maximum number of strings

1483:    Output Parameter:
1484: +  strings - location to copy strings
1485: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1487:    Level: beginner

1489:    Notes: 
1490:    The user should pass in an array of pointers to char, to hold all the
1491:    strings returned by this function.

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

1496:    Contributed by Matthew Knepley.

1498:    Concepts: options database^array of strings

1500: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1501:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1502:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1503:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1504:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1505:           PetscOptionsList(), PetscOptionsEList()
1506: @*/
1507: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1508: {
1509:   char           *value;
1511:   PetscInt       n;
1512:   PetscTruth     flag;
1513:   PetscToken     *token;
1514: 
1518:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1519:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1520:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1521:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1522:   if (flg) *flg = PETSC_TRUE;

1524:   PetscTokenCreate(value,',',&token);
1525:   PetscTokenFind(token,&value);
1526:   n = 0;
1527:   while (n < *nmax) {
1528:     if (!value) break;
1529:     PetscStrallocpy(value,&strings[n]);
1530:     PetscTokenFind(token,&value);
1531:     n++;
1532:   }
1533:   PetscTokenDestroy(token);
1534:   *nmax = n;
1535:   return(0);
1536: }

1540: /*@C
1541:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1542:    database that have never been selected.

1544:    Not Collective

1546:    Output Parameter:
1547: .   N - count of options not used

1549:    Level: advanced

1551: .seealso: PetscOptionsPrint()
1552: @*/
1553: PetscErrorCode  PetscOptionsAllUsed(int *N)
1554: {
1555:   PetscInt i,n = 0;

1558:   for (i=0; i<options->N; i++) {
1559:     if (!options->used[i]) { n++; }
1560:   }
1561:   *N = n;
1562:   return(0);
1563: }

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

1570:   Not collective

1572:    Options Database Key:
1573: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1575:   Level: advanced

1577: .seealso: PetscOptionsAllUsed()
1578: @*/
1579: PetscErrorCode  PetscOptionsLeft(void)
1580: {
1582:   PetscInt       i;

1585:   for (i=0; i<options->N; i++) {
1586:     if (!options->used[i]) {
1587:       if (options->values[i]) {
1588:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1589:       } else {
1590:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1591:       }
1592:     }
1593:   }
1594:   return(0);
1595: }


1598: /*
1599:     PetscOptionsCreate - Creates the empty options database.

1601: */
1604: PetscErrorCode  PetscOptionsCreate(void)
1605: {

1609:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1610:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1611:   options->namegiven                 = PETSC_FALSE;
1612:   options->N                         = 0;
1613:   options->Naliases                  = 0;
1614:   options->numbermonitors         = 0;
1615: 
1616:   return(0);
1617: }

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

1624:    Collective on PETSC_COMM_WORLD

1626:    Options Database Keys:
1627: +  -options_monitor <optional filename> - prints the names and values of all 
1628:                                  runtime options as they are set. The monitor functionality is not 
1629:                 available for options set through a file, environment variable, or on 
1630:                 the command line. Only options set after PetscInitialize completes will 
1631:                 be monitored.
1632: .  -options_cancelmonitors - cancel all options database monitors    

1634:    Notes:
1635:    To see all options, run your program with the -help option or consult
1636:    the users manual. 

1638:    Level: intermediate

1640: .keywords: set, options, database
1641: @*/
1642: PetscErrorCode  PetscOptionsSetFromOptions()
1643: {
1644:   PetscTruth          flg;
1645:   PetscErrorCode      ierr;
1646:   char                monfilename[PETSC_MAX_PATH_LEN];
1647:   PetscViewer         monviewer;


1651:   PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1652:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1653:   if (flg && (!options->numbermonitors)) {
1654:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1655:     PetscOptionsSetMonitor(PetscOptionsDefaultMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1656:   }
1657: 
1658:   PetscOptionsName("-options_cancelmonitors","Cancel all options database monitors","PetscOptionsClearMonitor",&flg);
1659:   if (flg) { PetscOptionsClearMonitor(); }
1660: 
1661:   PetscOptionsEnd();

1663:   return(0);
1664: }


1669: /*@C
1670:    PetscOptionsDefaultMonitor - Print all options set value events.

1672:    Collective on PETSC_COMM_WORLD

1674:    Input Parameters:
1675: +  name  - option name string
1676: .  value - option value string
1677: -  dummy - unused monitor context 

1679:    Level: intermediate

1681: .keywords: PetscOptions, default, monitor

1683: .seealso: PetscOptionsSetMonitor()
1684: @*/
1685: PetscErrorCode  PetscOptionsDefaultMonitor(const char name[], const char value[], void *dummy)
1686: {
1688:   PetscViewer    viewer = (PetscViewer) dummy;

1691:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PETSC_COMM_WORLD);
1692:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1693:   return(0);
1694: }

1698: /*@C
1699:    PetscOptionsSetMonitor - Sets an ADDITIONAL function to be called at every method that
1700:    modified the PETSc options database.
1701:       
1702:    Not collective

1704:    Input Parameters:
1705: +  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1706: .  mctx    - [optional] context for private data for the
1707:              monitor routine (use PETSC_NULL if no context is desired)
1708: -  monitordestroy - [optional] routine that frees monitor context
1709:           (may be PETSC_NULL)

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

1714: +  name - option name string
1715: .  value - option value string
1716: -  mctx  - optional monitoring context, as set by PetscOptionsSetMonitor()

1718:    Options Database Keys:
1719: +    -options_monitor    - sets PetscOptionsDefaultMonitor()
1720: -    -options_cancelmonitors - cancels all monitors that have
1721:                           been hardwired into a code by 
1722:                           calls to PetscOptionsSetMonitor(), but
1723:                           does not cancel those set via
1724:                           the options database.

1726:    Notes:  
1727:    The default is to do nothing.  To print the name and value of options 
1728:    being inserted into the database, use PetscOptionsDefaultMonitor() as the monitoring routine, 
1729:    with a null monitoring context. 

1731:    Several different monitoring routines may be set by calling
1732:    PetscOptionsSetMonitor() multiple times; all will be called in the 
1733:    order in which they were set.

1735:    Level: beginner

1737: .keywords: PetscOptions, set, monitor

1739: .seealso: PetscOptionsDefaultMonitor(), PetscOptionsClearMonitor()
1740: @*/
1741: PetscErrorCode  PetscOptionsSetMonitor(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1742: {
1744:   if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1745:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1746:   }
1747:   options->monitor[options->numbermonitors]           = monitor;
1748:   options->monitordestroy[options->numbermonitors]    = monitordestroy;
1749:   options->monitorcontext[options->numbermonitors++]  = (void*)mctx;
1750:   return(0);
1751: }

1755: /*@
1756:    PetscOptionsClearMonitor - Clears all monitors for a PetscOptions object.

1758:    Not collective 

1760:    Options Database Key:
1761: .  -options_cancelmonitors - Cancels all monitors that have
1762:     been hardwired into a code by calls to PetscOptionsSetMonitor(), 
1763:     but does not cancel those set via the options database.

1765:    Level: intermediate

1767: .keywords: PetscOptions, set, monitor

1769: .seealso: PetscOptionsDefaultMonitor(), PetscOptionsSetMonitor()
1770: @*/
1771: PetscErrorCode  PetscOptionsClearMonitor()
1772: {
1774:   PetscInt       i;

1777:   for (i=0; i<options->numbermonitors; i++) {
1778:     if (options->monitordestroy[i]) {
1779:       (*options->monitordestroy[i])(options->monitorcontext[i]);
1780:     }
1781:   }
1782:   options->numbermonitors = 0;
1783:   return(0);
1784: }