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 separated 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:       PetscInfo(0,"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:   PetscInt       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:   PetscInt       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:   PetscInt 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:   PetscInt       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/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:   PetscInt       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:   PetscInt       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/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:    Notes: Name cannot be simply -h

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

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

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

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

914:    Not Collective

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

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

924:    Level: beginner

926:    Concepts: options database^has int

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

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

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

963:    Not Collective

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

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

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

979:    Concepts: options database^list

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

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

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

1026:    Not Collective

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

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

1038:    Level: beginner

1040:    Concepts: options database

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

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

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

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

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

1075:    Not Collective

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

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

1085:    Level: beginner

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

1091:    Concepts: options database^has logical

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

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

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

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

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

1149:    Not Collective

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

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

1159:    Level: beginner

1161:    Concepts: options database^has double

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

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

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

1195:    Not Collective

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

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

1205:    Level: beginner

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

1211:    Concepts: options database^has scalar

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

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

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

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

1269:    Not Collective

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

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

1281:    Level: beginner

1283:    Concepts: options database^array of doubles

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

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

1307:   if (flg) *flg = PETSC_TRUE;

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

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

1329:    Not Collective

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

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

1341:    Level: beginner

1343:    Concepts: options database^array of ints

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

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

1367:   if (flg) *flg = PETSC_TRUE;

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

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

1389:    Not Collective

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

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

1400:    Level: beginner

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

1411:    Concepts: options database^string

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

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

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

1450:    Not Collective

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

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

1461:    Level: beginner

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

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

1470:    Contributed by Matthew Knepley.

1472:    Concepts: options database^array of strings

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

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

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

1518:    Not Collective

1520:    Output Parameter:
1521: .   N - count of options not used

1523:    Level: advanced

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

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

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

1544:   Not collective

1546:    Options Database Key:
1547: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1549:   Level: advanced

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

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

1571: /*
1572:     PetscOptionsCreate - Creates the empty options database.

1574: */
1577: PetscErrorCode PETSC_DLLEXPORT PetscOptionsCreate(void)
1578: {

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