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

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

 38: static PetscOptionsTable *options = 0;

 42: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtoi(const char name[],PetscInt *a)
 43: {
 45:   size_t         i,len;
 46:   PetscTruth     decide,tdefault,mouse;

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

 52:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 53:   if (!tdefault) {
 54:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 55:   }
 56:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 57:   if (!decide) {
 58:     PetscStrcasecmp(name,"DECIDE",&decide);
 59:   }
 60:   PetscStrcasecmp(name,"mouse",&mouse);

 62:   if (tdefault) {
 63:     *a = PETSC_DEFAULT;
 64:   } else if (decide) {
 65:     *a = PETSC_DECIDE;
 66:   } else if (mouse) {
 67:     *a = -1;
 68:   } else {
 69:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
 70:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 71:     }
 72:     for (i=1; i<len; i++) {
 73:       if (name[i] < '0' || name[i] > '9') {
 74:         SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
 75:       }
 76:     }
 77:     *a  = atoi(name);
 78:   }
 79:   return(0);
 80: }

 84: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtod(const char name[],PetscReal *a)
 85: {
 87:   size_t     len;
 88:   PetscTruth decide,tdefault;

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

 94:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 95:   if (!tdefault) {
 96:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 97:   }
 98:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 99:   if (!decide) {
100:     PetscStrcasecmp(name,"DECIDE",&decide);
101:   }

103:   if (tdefault) {
104:     *a = PETSC_DEFAULT;
105:   } else if (decide) {
106:     *a = PETSC_DECIDE;
107:   } else {
108:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
109:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
110:     }
111:     *a  = atof(name);
112:   }
113:   return(0);
114: }

118: /*@C
119:     PetscGetProgramName - Gets the name of the running program. 

121:     Not Collective

123:     Input Parameter:
124: .   len - length of the string name

126:     Output Parameter:
127: .   name - the name of the running program

129:    Level: advanced

131:     Notes:
132:     The name of the program is copied into the user-provided character
133:     array of length len.  On some machines the program name includes 
134:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
135: @*/
136: PetscErrorCode PETSC_DLLEXPORT PetscGetProgramName(char name[],size_t len)
137: {

141:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
142:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
143:   PetscStrncpy(name,options->programname,len);
144:   return(0);
145: }

149: PetscErrorCode PETSC_DLLEXPORT PetscSetProgramName(const char name[])
150: {

154:   options->namegiven = PETSC_TRUE;
155:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
156:   return(0);
157: }

161: /*@C
162:      PetscOptionsInsertString - Inserts options into the database from a string

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

167:   Input Parameter:
168: .   in_str - string that contains options seperated by blanks


171:   Level: intermediate

173:   Contributed by Boyana Norris

175: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
176:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
177:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
178:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
179:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
180:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

182: @*/
183: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertString(const char in_str[])
184: {
185:   char           *str,*first,*second,*third,*final;
186:   size_t         len;
188:   PetscToken     *token;

191:   PetscStrallocpy(in_str, &str);
192:   PetscTokenCreate(str,' ',&token);
193:   PetscTokenFind(token,&first);
194:   PetscTokenFind(token,&second);
195:   if (first && first[0] == '-') {
196:     if (second) {final = second;} else {final = first;}
197:     PetscStrlen(final,&len);
198:     while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
199:       len--; final[len] = 0;
200:     }
201:     PetscOptionsSetValue(first,second);
202:   } else if (first) {
203:     PetscTruth match;
204: 
205:     PetscStrcasecmp(first,"alias",&match);
206:     if (match) {
207:       PetscTokenFind(token,&third);
208:       if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
209:       PetscStrlen(third,&len);
210:       if (third[len-1] == 'n') third[len-1] = 0;
211:       PetscOptionsSetAlias(second,third);
212:     }
213:   }
214:   PetscTokenDestroy(token);
215:   PetscFree(str);
216: 
217:   return(0);
218: }

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

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

228:   Input Parameter:
229: .   file - name of file


232:   Level: intermediate

234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
235:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
236:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
237:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
238:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
239:           PetscOptionsList(), PetscOptionsEList()

241: @*/
242: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertFile(const char file[])
243: {
244:   char           string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
246:   size_t         i,len,startIndex;
247:   FILE           *fd;
248:   PetscToken     *token;

251:   PetscFixFilename(file,fname);
252:   fd   = fopen(fname,"r");
253:   if (fd) {
254:     while (fgets(string,128,fd)) {
255:       /* Comments are indicated by #, ! or % in the first column */
256:       if (string[0] == '#') continue;
257:       if (string[0] == '!') continue;
258:       if (string[0] == '%') continue;

260:       PetscStrlen(string,&len);

262:       /* replace tabs, ^M with " " */
263:       for (i=0; i<len; i++) {
264:         if (string[i] == '\t' || string[i] == '\r') {
265:           string[i] = ' ';
266:         }
267:       }
268:       for(startIndex = 0; startIndex < len-1; startIndex++) {
269:         if (string[startIndex] != ' ') break;
270:       }
271:       PetscTokenCreate(&string[startIndex],' ',&token);
272:       PetscTokenFind(token,&first);
273:       PetscTokenFind(token,&second);
274:       if (first && first[0] == '-') {
275:         if (second) {final = second;} else {final = first;}
276:         PetscStrlen(final,&len);
277:         while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
278:           len--; final[len] = 0;
279:         }
280:         PetscOptionsSetValue(first,second);
281:       } else if (first) {
282:         PetscTruth match;

284:         PetscStrcasecmp(first,"alias",&match);
285:         if (match) {
286:           PetscTokenFind(token,&third);
287:           if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
288:           PetscStrlen(third,&len);
289:           if (third[len-1] == '\n') third[len-1] = 0;
290:           PetscOptionsSetAlias(second,third);
291:         }
292:       }
293:       PetscTokenDestroy(token);
294:     }
295:     fclose(fd);
296:   } else {
297:     SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
298:   }
299:   return(0);
300: }

304: /*@C
305:    PetscOptionsInsert - Inserts into the options database from the command line,
306:                    the environmental variable and a file.

308:    Input Parameters:
309: +  argc - count of number of command line arguments
310: .  args - the command line arguments
311: -  file - optional filename, defaults to ~username/.petscrc

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

318:    Level: advanced

320:    Concepts: options database^adding

322: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
323: @*/
324: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsert(int *argc,char ***args,const char file[])
325: {
327:   PetscMPIInt    rank;
328:   char           pfile[PETSC_MAX_PATH_LEN];
329:   PetscToken     *token;

332:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

334:   options->argc     = (argc) ? *argc : 0;
335:   options->args     = (args) ? *args : 0;

337:   if (file) {
338:     PetscOptionsInsertFile(file);
339:   } else {
340:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
341:     if (pfile[0]) {
342:       PetscTruth flag;
343:       PetscStrcat(pfile,"/.petscrc");
344:       PetscTestFile(pfile,'r',&flag);
345:       if (flag) {
346:         PetscOptionsInsertFile(pfile);
347:       }
348:     } else {
349:       PetscLogInfo((0,"PetscOptionsInsert:Unable to determine home directory; skipping loading ~/.petscrc\n"));
350:     }
351:   }

353:   /* insert environmental options */
354:   {
355:     char   *eoptions = 0,*second,*first;
356:     size_t len = 0;
357:     if (!rank) {
358:       eoptions = (char*)getenv("PETSC_OPTIONS");
359:       PetscStrlen(eoptions,&len);
360:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
361:     } else {
362:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
363:       if (len) {
364:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
365:       }
366:     }
367:     if (len) {
368:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
369:       eoptions[len] = 0;
370:        PetscTokenCreate(eoptions,' ',&token);
371:        PetscTokenFind(token,&first);
372:       while (first) {
373:         if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
374:         PetscTokenFind(token,&second);
375:         if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
376:           PetscOptionsSetValue(first,(char *)0);
377:           first = second;
378:         } else {
379:           PetscOptionsSetValue(first,second);
380:           PetscTokenFind(token,&first);
381:         }
382:       }
383:        PetscTokenDestroy(token);
384:       if (rank) {PetscFree(eoptions);}
385:     }
386:   }

388:   /* insert command line options */
389:   if (argc && args && *argc) {
390:     int        left    = *argc - 1;
391:     char       **eargs = *args + 1;
392:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

394:     while (left) {
395:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
396:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
397:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
398:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
399:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
400:       isp4 = (PetscTruth) (isp4 || tisp4);
401:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
402:       isp4 = (PetscTruth) (isp4 || tisp4);
403:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

405:       if (eargs[0][0] != '-') {
406:         eargs++; left--;
407:       } else if (isoptions_file) {
408:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
409:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
410:         PetscOptionsInsertFile(eargs[1]);
411:         eargs += 2; left -= 2;

413:       /*
414:          These are "bad" options that MPICH, etc put on the command line
415:          we strip them out here.
416:       */
417:       } else if (tisp4 || isp4rmrank) {
418:         eargs += 1; left -= 1;
419:       } else if (isp4 || isp4yourname) {
420:         eargs += 2; left -= 2;
421:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
422:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
423:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
424:         eargs++; left--;
425:       } else {
426:         PetscOptionsSetValue(eargs[0],eargs[1]);
427:         eargs += 2; left -= 2;
428:       }
429:     }
430:   }
431:   return(0);
432: }

436: /*@C
437:    PetscOptionsPrint - Prints the options that have been loaded. This is
438:    useful for debugging purposes.

440:    Collective on PETSC_COMM_WORLD

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

445:    Options Database Key:
446: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

448:    Level: advanced

450:    Concepts: options database^printing

452: .seealso: PetscOptionsAllUsed()
453: @*/
454: PetscErrorCode PETSC_DLLEXPORT PetscOptionsPrint(FILE *fd)
455: {
457:   int i;

460:   if (!fd) fd = stdout;
461:   if (!options) {PetscOptionsInsert(0,0,0);}
462:   for (i=0; i<options->N; i++) {
463:     if (options->values[i]) {
464:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
465:     } else {
466:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
467:     }
468:   }
469:   return(0);
470: }

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

477:    Not Collective

479:    Output Parameter:
480: .  copts - pointer where string pointer is stored

482:    Level: advanced

484:    Concepts: options database^listing

486: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
487: @*/
488: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetAll(char *copts[])
489: {
491:   int    i;
492:   size_t len = 1,lent;
493:   char   *coptions;

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

498:   /* count the length of the required string */
499:   for (i=0; i<options->N; i++) {
500:     PetscStrlen(options->names[i],&lent);
501:     len += 2 + lent;
502:     if (options->values[i]) {
503:       PetscStrlen(options->values[i],&lent);
504:       len += 1 + lent;
505:     }
506:   }
507:   PetscMalloc(len*sizeof(char),&coptions);
508:   coptions[0] = 0;
509:   for (i=0; i<options->N; i++) {
510:     PetscStrcat(coptions,"-");
511:     PetscStrcat(coptions,options->names[i]);
512:     PetscStrcat(coptions," ");
513:     if (options->values[i]) {
514:       PetscStrcat(coptions,options->values[i]);
515:       PetscStrcat(coptions," ");
516:     }
517:   }
518:   *copts = coptions;
519:   return(0);
520: }

524: /*@C
525:     PetscOptionsDestroy - Destroys the option database. 

527:     Note:
528:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
529:     typically does not need to call this routine.

531:    Level: developer

533: .seealso: PetscOptionsInsert()
534: @*/
535: PetscErrorCode PETSC_DLLEXPORT PetscOptionsDestroy(void)
536: {
537:   int i;

540:   if (!options) return(0);
541:   for (i=0; i<options->N; i++) {
542:     if (options->names[i]) free(options->names[i]);
543:     if (options->values[i]) free(options->values[i]);
544:   }
545:   for (i=0; i<options->Naliases; i++) {
546:     free(options->aliases1[i]);
547:     free(options->aliases2[i]);
548:   }
549:   free(options);
550:   options = 0;
551:   return(0);
552: }

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

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

563:    Input Parameters:
564: +  name - name of option, this SHOULD have the - prepended
565: -  value - the option value (not used for all options)

567:    Level: intermediate

569:    Note:
570:    Only some options have values associated with them, such as
571:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

573:   Concepts: options database^adding option

575: .seealso: PetscOptionsInsert()
576: @*/
577: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetValue(const char iname[],const char value[])
578: {
579:   size_t     len;
581:   int        N,n,i;
582:   char       **names;
583:   const char *name = (char*)iname;
584:   PetscTruth gt,match;

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

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

593:   name++;
594:   /* first check against aliases */
595:   N = options->Naliases;
596:   for (i=0; i<N; i++) {
597:     PetscStrcasecmp(options->aliases1[i],name,&match);
598:     if (match) {
599:       name = options->aliases2[i];
600:       break;
601:     }
602:   }

604:   N     = options->N;
605:   n     = N;
606:   names = options->names;
607: 
608:   for (i=0; i<N; i++) {
609:     PetscStrcasecmp(names[i],name,&match);
610:     PetscStrgrt(names[i],name,&gt);
611:     if (match) {
612:       if (options->values[i]) free(options->values[i]);
613:       PetscStrlen(value,&len);
614:       if (len) {
615:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
616:         PetscStrcpy(options->values[i],value);
617:       } else { options->values[i] = 0;}
618:       return(0);
619:     } else if (gt) {
620:       n = i;
621:       break;
622:     }
623:   }
624:   if (N >= MAXOPTIONS) {
625:     SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
626:   }
627:   /* shift remaining values down 1 */
628:   for (i=N; i>n; i--) {
629:     names[i]           = names[i-1];
630:     options->values[i] = options->values[i-1];
631:     options->used[i]   = options->used[i-1];
632:   }
633:   /* insert new name and value */
634:   PetscStrlen(name,&len);
635:   names[n] = (char*)malloc((len+1)*sizeof(char));
636:   PetscStrcpy(names[n],name);
637:   if (value) {
638:     PetscStrlen(value,&len);
639:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
640:     PetscStrcpy(options->values[n],value);
641:   } else {options->values[n] = 0;}
642:   options->used[n] = PETSC_FALSE;
643:   options->N++;
644:   return(0);
645: }

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

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

656:    Input Parameter:
657: .  name - name of option, this SHOULD have the - prepended

659:    Level: intermediate

661:    Concepts: options database^removing option
662: .seealso: PetscOptionsInsert()
663: @*/
664: PetscErrorCode PETSC_DLLEXPORT PetscOptionsClearValue(const char iname[])
665: {
667:   int        N,n,i;
668:   char       **names,*name=(char*)iname;
669:   PetscTruth gt,match;

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

675:   name++;

677:   N     = options->N; n = 0;
678:   names = options->names;
679: 
680:   for (i=0; i<N; i++) {
681:     PetscStrcasecmp(names[i],name,&match);
682:     PetscStrgrt(names[i],name,&gt);
683:     if (match) {
684:       if (options->values[i]) free(options->values[i]);
685:       break;
686:     } else if (gt) {
687:       return(0); /* it was not listed */
688:     }
689:     n++;
690:   }
691:   if (n == N) return(0); /* it was not listed */

693:   /* shift remaining values down 1 */
694:   for (i=n; i<N-1; i++) {
695:     names[i]           = names[i+1];
696:     options->values[i] = options->values[i+1];
697:     options->used[i]   = options->used[i+1];
698:   }
699:   options->N--;
700:   return(0);
701: }

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

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

711:    Input Parameters:
712: +  name - the option one is seeking 
713: -  mess - error message (may be PETSC_NULL)

715:    Level: advanced

717:    Concepts: options database^rejecting option

719: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
720:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
721:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
722:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
723:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
724:           PetscOptionsList(), PetscOptionsEList()
725: @*/
726: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetAlias(const char inewname[],const char ioldname[])
727: {
729:   int    n = options->Naliases;
730:   size_t len;
731:   char   *newname = (char *)inewname,*oldname = (char*)ioldname;

734:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
735:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
736:   if (n >= MAXALIASES) {
737:     SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n  src/sys/src/objects/options.c with larger value for MAXALIASES",MAXALIASES);
738:   }

740:   newname++; oldname++;
741:   PetscStrlen(newname,&len);
742:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
743:   PetscStrcpy(options->aliases1[n],newname);
744:   PetscStrlen(oldname,&len);
745:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
746:   PetscStrcpy(options->aliases2[n],oldname);
747:   options->Naliases++;
748:   return(0);
749: }

753: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
754: {
756:   PetscInt       i,N;
757:   size_t         len;
758:   char           **names,tmp[256];
759:   PetscTruth     match;

762:   if (!options) {PetscOptionsInsert(0,0,0);}
763:   N = options->N;
764:   names = options->names;

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

768:   /* append prefix to name */
769:   if (pre) {
770:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
771:     PetscStrncpy(tmp,pre,256);
772:     PetscStrlen(tmp,&len);
773:     PetscStrncat(tmp,name+1,256-len-1);
774:   } else {
775:     PetscStrncpy(tmp,name+1,256);
776:   }

778:   /* slow search */
779:   *flg = PETSC_FALSE;
780:   for (i=0; i<N; i++) {
781:     PetscStrcasecmp(names[i],tmp,&match);
782:     if (match) {
783:        *value           = options->values[i];
784:        options->used[i] = PETSC_TRUE;
785:        *flg             = PETSC_TRUE;
786:        break;
787:      }
788:   }
789:   if (!*flg) {
790:     PetscInt j,cnt = 0,locs[16],loce[16];
791:     size_t   n;
792:     PetscStrlen(tmp,&n);
793:     /* determine the location and number of all _%d_ in the key */
794:     for (i=0; i< (PetscInt)n; i++) {
795:       if (tmp[i] == '_') {
796:         for (j=i+1; j< (PetscInt)n; j++) {
797:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
798:           if (tmp[j] == '_' && j > i+1) { /* found a number */
799:             locs[cnt]   = i+1;
800:             loce[cnt++] = j+1;
801:           }
802:           break;
803:         }
804:       }
805:     }
806:     if (cnt) {
807:       char tmp2[256];
808:       for (i=0; i<cnt; i++) {
809:         PetscStrcpy(tmp2,"-");
810:         PetscStrncat(tmp2,tmp,locs[i]);
811:         PetscStrcat(tmp2,tmp+loce[i]);
812:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
813:         if (*flg) break;
814:       }
815:     }
816:   }
817:   return(0);
818: }

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

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

828:    Input Parameters:
829: +  name - the option one is seeking 
830: -  mess - error message (may be PETSC_NULL)

832:    Level: advanced

834:    Concepts: options database^rejecting option

836: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
837:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
838:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
839:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
840:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
841:           PetscOptionsList(), PetscOptionsEList()
842: @*/
843: PetscErrorCode PETSC_DLLEXPORT PetscOptionsReject(const char name[],const char mess[])
844: {
846:   PetscTruth flag;

849:   PetscOptionsHasName(PETSC_NULL,name,&flag);
850:   if (flag) {
851:     if (mess) {
852:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
853:     } else {
854:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
855:     }
856:   }
857:   return(0);
858: }

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

865:    Not Collective

867:    Input Parameters:
868: +  name - the option one is seeking 
869: -  pre - string to prepend to the name or PETSC_NULL

871:    Output Parameters:
872: .  flg - PETSC_TRUE if found else PETSC_FALSE.

874:    Level: beginner

876:    Concepts: options database^has option name

878: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
879:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
880:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
881:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
882:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
883:           PetscOptionsList(), PetscOptionsEList()
884: @*/
885: PetscErrorCode PETSC_DLLEXPORT PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
886: {
887:   char       *value;
889:   PetscTruth isfalse,flag;

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

894:   /* remove if turned off */
895:   if (flag) {
896:     PetscStrcasecmp(value,"FALSE",&isfalse);
897:     if (isfalse) flag = PETSC_FALSE;
898:     PetscStrcasecmp(value,"NO",&isfalse);
899:     if (isfalse) flag = PETSC_FALSE;
900:     PetscStrcasecmp(value,"0",&isfalse);
901:     if (isfalse) flag = PETSC_FALSE;
902:   }
903:   if (flg) *flg = flag;
904:   return(0);
905: }

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

912:    Not Collective

914:    Input Parameters:
915: +  pre - the string to prepend to the name or PETSC_NULL
916: -  name - the option one is seeking

918:    Output Parameter:
919: +  ivalue - the integer value to return
920: -  flg - PETSC_TRUE if found, else PETSC_FALSE

922:    Level: beginner

924:    Concepts: options database^has int

926: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
927:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
928:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
929:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
930:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
931:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
932:           PetscOptionsList(), PetscOptionsEList()
933: @*/
934: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
935: {
936:   char       *value;
938:   PetscTruth flag;

943:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
944:   if (flag) {
945:     if (!value) {if (flg) *flg = PETSC_FALSE;}
946:     else {
947:       if (flg) *flg = PETSC_TRUE;
948:       PetscOptionsAtoi(value,ivalue);
949:     }
950:   } else {
951:     if (flg) *flg = PETSC_FALSE;
952:   }
953:   return(0);
954: }

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

961:    Not Collective

963:    Input Parameters:
964: +  pre - the string to prepend to the name or PETSC_NULL
965: .  opt - option name
966: .  list - the possible choices
967: .  ntext - number of choices

969:    Output Parameter:
970: +  value - the index of the value to return
971: -  set - PETSC_TRUE if found, else PETSC_FALSE
972:    
973:    Level: intermediate

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

977:    Concepts: options database^list

979: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
980:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
981:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
982:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
983:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
984:           PetscOptionsList(), PetscOptionsEList()
985: @*/
986: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
987: {
989:   size_t         alen,len = 0;
990:   char           *svalue;
991:   PetscTruth     aset,flg = PETSC_FALSE;
992:   PetscInt       i;

995:   for ( i=0; i<ntext; i++) {
996:     PetscStrlen(list[i],&alen);
997:     if (alen > len) len = alen;
998:   }
999:   len += 5; /* a little extra space for user mistypes */
1000:   PetscMalloc(len*sizeof(char),&svalue);
1001:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
1002:   if (aset) {
1003:     if (set) *set = PETSC_TRUE;
1004:     for (i=0; i<ntext; i++) {
1005:       PetscStrcasecmp(svalue,list[i],&flg);
1006:       if (flg) {
1007:         *value = i;
1008:         break;
1009:       }
1010:     }
1011:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1012:   } else if (set) {
1013:     *set = PETSC_FALSE;
1014:   }
1015:   PetscFree(svalue);
1016:   return(0);
1017: }

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

1024:    Not Collective

1026:    Input Parameters:
1027: +  pre - option prefix or PETSC_NULL
1028: .  opt - option name
1029: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1030: -  defaultv - the default (current) value

1032:    Output Parameter:
1033: +  value - the  value to return
1034: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1036:    Level: beginner

1038:    Concepts: options database

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

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

1044: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1045:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1046:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1047:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1048:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1049:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1050:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1051: @*/
1052: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1053: {
1055:   PetscInt       ntext = 0;

1058:   while (list[ntext++]) {
1059:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1060:   }
1061:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1062:   ntext -= 3;
1063:   PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1064:   return(0);
1065: }

1069: /*@C
1070:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular 
1071:             option in the database.

1073:    Not Collective

1075:    Input Parameters:
1076: +  pre - the string to prepend to the name or PETSC_NULL
1077: -  name - the option one is seeking

1079:    Output Parameter:
1080: +  ivalue - the logical value to return
1081: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

1083:    Level: beginner

1085:    Notes:
1086:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1087:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1089:    Concepts: options database^has logical

1091: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1092:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1093:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1094:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1095:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1096:           PetscOptionsList(), PetscOptionsEList()
1097: @*/
1098: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1099: {
1100:   char           *value;
1101:   PetscTruth     flag,istrue,isfalse;

1107:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1108:   if (flag) {
1109:     if (flg) *flg = PETSC_TRUE;
1110:     if (!value) {
1111:       *ivalue = PETSC_TRUE;
1112:     } else {
1113:       *ivalue = PETSC_TRUE;
1114:       PetscStrcasecmp(value,"TRUE",&istrue);
1115:       if (istrue) return(0);
1116:       PetscStrcasecmp(value,"YES",&istrue);
1117:       if (istrue) return(0);
1118:       PetscStrcasecmp(value,"1",&istrue);
1119:       if (istrue) return(0);
1120:       PetscStrcasecmp(value,"on",&istrue);
1121:       if (istrue) return(0);

1123:       *ivalue = PETSC_FALSE;
1124:       PetscStrcasecmp(value,"FALSE",&isfalse);
1125:       if (isfalse) return(0);
1126:       PetscStrcasecmp(value,"NO",&isfalse);
1127:       if (isfalse) return(0);
1128:       PetscStrcasecmp(value,"0",&isfalse);
1129:       if (isfalse) return(0);
1130:       PetscStrcasecmp(value,"off",&isfalse);
1131:       if (isfalse) return(0);

1133:       SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1134:     }
1135:   } else {
1136:     if (flg) *flg = PETSC_FALSE;
1137:   }
1138:   return(0);
1139: }

1143: /*@C
1144:    PetscOptionsGetReal - Gets the double precision value for a particular 
1145:    option in the database.

1147:    Not Collective

1149:    Input Parameters:
1150: +  pre - string to prepend to each name or PETSC_NULL
1151: -  name - the option one is seeking

1153:    Output Parameter:
1154: +  dvalue - the double value to return
1155: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1157:    Level: beginner

1159:    Concepts: options database^has double

1161: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1162:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1163:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1164:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1165:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1166:           PetscOptionsList(), PetscOptionsEList()
1167: @*/
1168: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1169: {
1170:   char           *value;
1172:   PetscTruth     flag;

1177:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1178:   if (flag) {
1179:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1180:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1181:   } else {
1182:     if (flg) *flg = PETSC_FALSE;
1183:   }
1184:   return(0);
1185: }

1189: /*@C
1190:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1191:    option in the database.

1193:    Not Collective

1195:    Input Parameters:
1196: +  pre - string to prepend to each name or PETSC_NULL
1197: -  name - the option one is seeking

1199:    Output Parameter:
1200: +  dvalue - the double value to return
1201: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1203:    Level: beginner

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

1209:    Concepts: options database^has scalar

1211: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1212:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1213:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1214:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1215:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1216:           PetscOptionsList(), PetscOptionsEList()
1217: @*/
1218: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1219: {
1220:   char           *value;
1221:   PetscTruth     flag;

1227:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1228:   if (flag) {
1229:     if (!value) {
1230:       if (flg) *flg = PETSC_FALSE;
1231:     } else {
1232: #if !defined(PETSC_USE_COMPLEX)
1233:       PetscOptionsAtod(value,dvalue);
1234: #else
1235:       PetscReal  re=0.0,im=0.0;
1236:       PetscToken *token;
1237:       char       *tvalue = 0;

1239:       PetscTokenCreate(value,',',&token);
1240:       PetscTokenFind(token,&tvalue);
1241:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1242:       PetscOptionsAtod(tvalue,&re);
1243:       PetscTokenFind(token,&tvalue);
1244:       if (!tvalue) { /* Unknown separator used. using only real value */
1245:         *dvalue = re;
1246:       } else {
1247:         PetscOptionsAtod(tvalue,&im);
1248:         *dvalue = re + PETSC_i*im;
1249:       }
1250:       PetscTokenDestroy(token);
1251: #endif
1252:       if (flg) *flg    = PETSC_TRUE;
1253:     }
1254:   } else { /* flag */
1255:     if (flg) *flg = PETSC_FALSE;
1256:   }
1257:   return(0);
1258: }

1262: /*@C
1263:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1264:    particular option in the database.  The values must be separated with 
1265:    commas with no intervening spaces.

1267:    Not Collective

1269:    Input Parameters:
1270: +  pre - string to prepend to each name or PETSC_NULL
1271: .  name - the option one is seeking
1272: -  nmax - maximum number of values to retrieve

1274:    Output Parameters:
1275: +  dvalue - the double value to return
1276: .  nmax - actual number of values retreived
1277: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1279:    Level: beginner

1281:    Concepts: options database^array of doubles

1283: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1284:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1285:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1286:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1287:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1288:           PetscOptionsList(), PetscOptionsEList()
1289: @*/
1290: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1291: {
1292:   char           *value;
1294:   PetscInt       n = 0;
1295:   PetscTruth     flag;
1296:   PetscToken     *token;

1301:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1302:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1303:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1305:   if (flg) *flg = PETSC_TRUE;

1307:   PetscTokenCreate(value,',',&token);
1308:   PetscTokenFind(token,&value);
1309:   while (n < *nmax) {
1310:     if (!value) break;
1311:     PetscOptionsAtod(value,dvalue++);
1312:     PetscTokenFind(token,&value);
1313:     n++;
1314:   }
1315:   PetscTokenDestroy(token);
1316:   *nmax = n;
1317:   return(0);
1318: }

1322: /*@C
1323:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1324:    option in the database.  The values must be separated with commas with 
1325:    no intervening spaces. 

1327:    Not Collective

1329:    Input Parameters:
1330: +  pre - string to prepend to each name or PETSC_NULL
1331: .  name - the option one is seeking
1332: -  nmax - maximum number of values to retrieve

1334:    Output Parameter:
1335: +  dvalue - the integer values to return
1336: .  nmax - actual number of values retreived
1337: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1339:    Level: beginner

1341:    Concepts: options database^array of ints

1343: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1344:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1345:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1346:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1347:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1348:           PetscOptionsList(), PetscOptionsEList()
1349: @*/
1350: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1351: {
1352:   char           *value;
1354:   PetscInt       n = 0;
1355:   PetscTruth     flag;
1356:   PetscToken     *token;

1361:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1362:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1363:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1365:   if (flg) *flg = PETSC_TRUE;

1367:   PetscTokenCreate(value,',',&token);
1368:   PetscTokenFind(token,&value);
1369:   while (n < *nmax) {
1370:     if (!value) break;
1371:     PetscOptionsAtoi(value,dvalue);
1372:     dvalue++;
1373:     PetscTokenFind(token,&value);
1374:     n++;
1375:   }
1376:   PetscTokenDestroy(token);
1377:   *nmax = n;
1378:   return(0);
1379: }

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

1387:    Not Collective

1389:    Input Parameters:
1390: +  pre - string to prepend to name or PETSC_NULL
1391: .  name - the option one is seeking
1392: -  len - maximum string length

1394:    Output Parameters:
1395: +  string - location to copy string
1396: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1398:    Level: beginner

1400:    Fortran Note:
1401:    The Fortran interface is slightly different from the C/C++
1402:    interface (len is not used).  Sample usage in Fortran follows
1403: .vb
1404:       character *20 string
1405:       integer   flg, ierr
1406:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1407: .ve

1409:    Concepts: options database^string

1411: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1412:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1413:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1414:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1415:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1416:           PetscOptionsList(), PetscOptionsEList()
1417: @*/
1418: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1419: {
1420:   char           *value;
1422:   PetscTruth     flag;

1427:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1428:   if (!flag) {
1429:     if (flg) *flg = PETSC_FALSE;
1430:   } else {
1431:     if (flg) *flg = PETSC_TRUE;
1432:     if (value) {
1433:       PetscStrncpy(string,value,len);
1434:     } else {
1435:       PetscMemzero(string,len);
1436:     }
1437:   }
1438:   return(0);
1439: }

1443: /*@C
1444:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1445:    option in the database. The values must be separated with commas with 
1446:    no intervening spaces. 

1448:    Not Collective

1450:    Input Parameters:
1451: +  pre - string to prepend to name or PETSC_NULL
1452: .  name - the option one is seeking
1453: -  nmax - maximum number of strings

1455:    Output Parameter:
1456: +  strings - location to copy strings
1457: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1459:    Level: beginner

1461:    Notes: 
1462:    The user should pass in an array of pointers to char, to hold all the
1463:    strings returned by this function.

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

1468:    Contributed by Matthew Knepley.

1470:    Concepts: options database^array of strings

1472: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1473:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1474:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1475:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1476:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1477:           PetscOptionsList(), PetscOptionsEList()
1478: @*/
1479: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1480: {
1481:   char           *value;
1483:   PetscInt       n;
1484:   PetscTruth     flag;
1485:   PetscToken     *token;
1486: 
1490:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1491:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1492:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1493:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1494:   if (flg) *flg = PETSC_TRUE;

1496:   PetscTokenCreate(value,',',&token);
1497:   PetscTokenFind(token,&value);
1498:   n = 0;
1499:   while (n < *nmax) {
1500:     if (!value) break;
1501:     PetscStrallocpy(value,&strings[n]);
1502:     PetscTokenFind(token,&value);
1503:     n++;
1504:   }
1505:   PetscTokenDestroy(token);
1506:   *nmax = n;
1507:   return(0);
1508: }

1512: /*@C
1513:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1514:    database that have never been selected.

1516:    Not Collective

1518:    Output Parameter:
1519: .   N - count of options not used

1521:    Level: advanced

1523: .seealso: PetscOptionsPrint()
1524: @*/
1525: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAllUsed(int *N)
1526: {
1527:   PetscInt i,n = 0;

1530:   for (i=0; i<options->N; i++) {
1531:     if (!options->used[i]) { n++; }
1532:   }
1533:   *N = n;
1534:   return(0);
1535: }

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

1542:   Not collective

1544:    Options Database Key:
1545: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1547:   Level: advanced

1549: .seealso: PetscOptionsAllUsed()
1550: @*/
1551: PetscErrorCode PETSC_DLLEXPORT PetscOptionsLeft(void)
1552: {
1554:   PetscInt       i;

1557:   for (i=0; i<options->N; i++) {
1558:     if (!options->used[i]) {
1559:       if (options->values[i]) {
1560:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1561:       } else {
1562:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1563:       }
1564:     }
1565:   }
1566:   return(0);
1567: }

1569: /*
1570:     PetscOptionsCreate - Creates the empty options database.

1572: */
1575: PetscErrorCode PETSC_DLLEXPORT PetscOptionsCreate(void)
1576: {

1580:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1581:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1582:   options->namegiven = PETSC_FALSE;
1583:   options->N         = 0;
1584:   options->Naliases  = 0;
1585:   return(0);
1586: }