Actual source code: options.c

  1: /*$Id: options.c,v 1.246 2001/03/23 23:20:38 balay Exp $*/
  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"        /*I  "petsc.h"   I*/
 11: #include "petscsys.h"
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif
 15: #if defined(PETSC_HAVE_MALLOC_H) && !defined(__cplusplus)
 16: #include <malloc.h>
 17: #endif
 18: #include "petscfix.h"

 20: /* 
 21:     For simplicity, we use a static size database
 22: */
 23: #define MAXOPTIONS 256
 24: #define MAXALIASES 25

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

 35: static PetscOptionsTable *options = 0;

 37: int PetscOptionsAtoi(const char name[],int *a)
 38: {
 39:   int        i,ierr,len;
 40:   PetscTruth decide,tdefault,mouse;

 43:   PetscStrlen(name,&len);
 44:   if (!len) SETERRQ(1,"charactor string of length zero has no numerical value");

 46:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 47:   if (!tdefault) {
 48:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 49:   }
 50:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 51:   if (!decide) {
 52:     PetscStrcasecmp(name,"DECIDE",&decide);
 53:   }
 54:   PetscStrcasecmp(name,"mouse",&mouse);

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

 76: int PetscOptionsAtod(const char name[],PetscReal *a)
 77: {
 78:   int        ierr,len;
 79:   PetscTruth decide,tdefault;

 82:   PetscStrlen(name,&len);
 83:   if (!len) SETERRQ(1,"charactor string of length zero has no numerical value");

 85:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 86:   if (!tdefault) {
 87:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 88:   }
 89:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 90:   if (!decide) {
 91:     PetscStrcasecmp(name,"DECIDE",&decide);
 92:   }

 94:   if (tdefault) {
 95:     *a = PETSC_DEFAULT;
 96:   } else if (decide) {
 97:     *a = PETSC_DECIDE;
 98:   } else {
 99:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
100:       SETERRQ1(1,"Input string %s has no numeric value ",name);
101:     }
102:     *a  = atof(name);
103:   }
104:   return(0);
105: }

107: /*@C
108:     PetscGetProgramName - Gets the name of the running program. 

110:     Not Collective

112:     Input Parameter:
113: .   len - length of the string name

115:     Output Parameter:
116: .   name - the name of the running program

118:    Level: advanced

120:     Notes:
121:     The name of the program is copied into the user-provided character
122:     array of length len.  On some machines the program name includes 
123:     its entire path, so one should generally set len >= 256.
124: @*/
125: int PetscGetProgramName(char name[],int len)
126: {

130:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
131:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
132:   PetscStrncpy(name,options->programname,len);
133:   return(0);
134: }

136: int PetscSetProgramName(const char name[])
137: {
138:   char *sname = 0;
139:   int  ierr;

142:   options->namegiven = PETSC_TRUE;
143:   /* Now strip away the path, if absulute path is specified */
144:   PetscStrrchr(name,'/',&sname);
145:   ierr  = PetscStrncpy(options->programname,sname,256);
146:   return(0);
147: }

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

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

155:   Input Parameter:
156: .   file - name of file


159:   Level: intermediate

161: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
162:           PetscOptionsGetDouble(), PetscOptionsGetString(), PetscOptionsGetIntArray()

164: @*/
165: int PetscOptionsInsertFile(const char file[])
166: {
167:   char  string[128],fname[256],*first,*second,*third,*final;
168:   int   len,ierr,i;
169:   FILE  *fd;

172:   PetscFixFilename(file,fname);
173:   fd   = fopen(fname,"r");
174:   if (fd) {
175:     while (fgets(string,128,fd)) {
176:       /* Comments are indicated by #, ! or % in the first column */
177:       if (string[0] == '#') continue;
178:       if (string[0] == '!') continue;
179:       if (string[0] == '%') continue;
180:       /* replace tabs with " " */
181:       PetscStrlen(string,&len);
182:       for (i=0; i<len; i++) {
183:         if (string[i] == 't') {
184:           string[i] = ' ';
185:         }
186:       }
187:       PetscStrtok(string," ",&first);
188:       PetscStrtok(0," ",&second);
189:       if (first && first[0] == '-') {
190:         if (second) {final = second;} else {final = first;}
191:         PetscStrlen(final,&len);
192:         while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
193:           len--; final[len] = 0;
194:         }
195:         PetscOptionsSetValue(first,second);
196:       } else if (first) {
197:         PetscTruth match;

199:         PetscStrcmp(first,"alias",&match);
200:         if (match) {
201:           PetscStrtok(0," ",&third);
202:           if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
203:           PetscStrlen(third,&len);
204:           if (third[len-1] == 'n') third[len-1] = 0;
205:           PetscOptionsSetAlias(second,third);
206:         }
207:       }
208:     }
209:     fclose(fd);
210:   }
211:   return(0);
212: }

214: /*@C
215:    PetscOptionsInsert - Inserts into the options database from the command line,
216:                    the environmental variable and a file.

218:    Input Parameters:
219: +  argc - count of number of command line arguments
220: .  args - the command line arguments
221: -  file - optional filename, defaults to ~username/.petscrc

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

228:    Level: advanced

230:    Concepts: options database^adding

232: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
233: @*/
234: int PetscOptionsInsert(int *argc,char ***args,const char file[])
235: {
236:   int  ierr,rank;
237:   char pfile[256];

240:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

242:   options->argc     = (argc) ? *argc : 0;
243:   options->args     = (args) ? *args : 0;

245:   if (file) {
246:     PetscOptionsInsertFile(file);
247:   } else {
248:     PetscGetHomeDirectory(pfile,240);
249:     PetscStrcat(pfile,"/.petscrc");
250:     PetscOptionsInsertFile(pfile);
251:   }

253:   /* insert environmental options */
254:   {
255:     char *eoptions = 0,*second,*first;
256:     int  len;
257:     if (!rank) {
258:       eoptions = (char*)getenv("PETSC_OPTIONS");
259:       ierr     = PetscStrlen(eoptions,&len);
260:       ierr     = MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
261:     } else {
262:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
263:       if (len) {
264:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
265:       }
266:     }
267:     if (len) {
268:       ierr          = MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
269:       eoptions[len] = 0;
270:       ierr          =  PetscStrtok(eoptions," ",&first);
271:       while (first) {
272:         if (first[0] != '-') {PetscStrtok(0," ",&first); continue;}
273:         PetscStrtok(0," ",&second);
274:         if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
275:           PetscOptionsSetValue(first,(char *)0);
276:           first = second;
277:         } else {
278:           PetscOptionsSetValue(first,second);
279:           PetscStrtok(0," ",&first);
280:         }
281:       }
282:       if (rank) {PetscFree(eoptions);}
283:     }
284:   }

286:   /* insert command line options */
287:   if (argc && args && *argc) {
288:     int        left    = *argc - 1;
289:     char       **eargs = *args + 1;
290:     PetscTruth isoptions_file,isp4,tisp4;

292:     while (left) {
293:       PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
294:       PetscStrcmp(eargs[0],"-p4pg",&isp4);
295:       PetscStrcmp(eargs[0],"-p4wd",&tisp4);
296:       isp4 = (PetscTruth) (isp4 || tisp4);
297:       PetscStrcmp(eargs[0],"-np",&tisp4);
298:       isp4 = (PetscTruth) (isp4 || tisp4);
299:       PetscStrcmp(eargs[0],"-p4amslave",&tisp4);

301:       if (eargs[0][0] != '-') {
302:         eargs++; left--;
303:       } else if (isoptions_file) {
304:         PetscOptionsInsertFile(eargs[1]);
305:         eargs += 2; left -= 2;

307:       /*
308:          These are "bad" options that MPICH, etc put on the command line
309:          we strip them out here.
310:       */
311:       } else if (tisp4) {
312:         eargs += 1; left -= 1;
313:       } else if (isp4) {
314:         eargs += 2; left -= 2;
315:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
316:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
317:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
318:         eargs++; left--;
319:       } else {
320:         PetscOptionsSetValue(eargs[0],eargs[1]);
321:         eargs += 2; left -= 2;
322:       }
323:     }
324:   }
325:   return(0);
326: }

328: /*@C
329:    PetscOptionsPrint - Prints the options that have been loaded. This is
330:    useful for debugging purposes.

332:    Collective on PETSC_COMM_WORLD

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

337:    Options Database Key:
338: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

340:    Level: advanced

342:    Concepts: options database^printing

344: .seealso: PetscOptionsAllUsed()
345: @*/
346: int PetscOptionsPrint(FILE *fd)
347: {
348:   int i,ierr;

351:   if (!fd) fd = stdout;
352:   if (!options) {PetscOptionsInsert(0,0,0);}
353:   for (i=0; i<options->N; i++) {
354:     if (options->values[i]) {
355:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %sn",options->names[i],options->values[i]);
356:     } else {
357:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%sn",options->names[i]);
358:     }
359:   }
360:   return(0);
361: }

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

366:    Not Collective

368:    Output Parameter:
369: .  copts - pointer where string pointer is stored

371:    Level: advanced

373:    Concepts: options database^listing

375: .seealso: PetscOptionsAllUsed(), PetscOptionsPrintf()
376: @*/
377: int PetscOptionsGetAll(char *copts[])
378: {
379:   int  i,ierr,len = 1,lent;
380:   char *coptions;

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

385:   /* count the length of the required string */
386:   for (i=0; i<options->N; i++) {
387:     PetscStrlen(options->names[i],&lent);
388:     len += 1 + lent;
389:     if (options->values[i]) {
390:       PetscStrlen(options->values[i],&lent);
391:       len += 1 + lent;
392:     }
393:   }
394:   PetscMalloc(len*sizeof(char),&coptions);
395:   coptions[0] = 0;
396:   for (i=0; i<options->N; i++) {
397:     PetscStrcat(coptions,"-");
398:     PetscStrcat(coptions,options->names[i]);
399:     PetscStrcat(coptions," ");
400:     if (options->values[i]) {
401:       PetscStrcat(coptions,options->values[i]);
402:       PetscStrcat(coptions," ");
403:     }
404:   }
405:   *copts = coptions;
406:   return(0);
407: }

409: /*@C
410:     PetscOptionsDestroy - Destroys the option database. 

412:     Note:
413:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
414:     typically does not need to call this routine.

416:    Level: developer

418: .seealso: PetscOptionsInsert()
419: @*/
420: int PetscOptionsDestroy(void)
421: {
422:   int i;

425:   if (!options) return(0);
426:   for (i=0; i<options->N; i++) {
427:     if (options->names[i]) free(options->names[i]);
428:     if (options->values[i]) free(options->values[i]);
429:   }
430:   for (i=0; i<options->Naliases; i++) {
431:     free(options->aliases1[i]);
432:     free(options->aliases2[i]);
433:   }
434:   free(options);
435:   options = 0;
436:   return(0);
437: }

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

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

446:    Input Parameters:
447: +  name - name of option, this SHOULD have the - prepended
448: -  value - the option value (not used for all options)

450:    Level: intermediate

452:    Note:
453:    Only some options have values associated with them, such as
454:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

456:   Concepts: options database^adding option

458: .seealso: PetscOptionsInsert()
459: @*/
460: int PetscOptionsSetValue(const char iname[],const char value[])
461: {
462:   int        len,N,n,i,ierr;
463:   char       **names,*name = (char*)iname;
464:   PetscTruth gt,match;

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

469:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
470:   PetscStrcmp(name,"-h",&match);
471:   if (match) name = "-help";

473:   name++;
474:   /* first check against aliases */
475:   N = options->Naliases;
476:   for (i=0; i<N; i++) {
477:     PetscStrcmp(options->aliases1[i],name,&match);
478:     if (match) {
479:       name = options->aliases2[i];
480:       break;
481:     }
482:   }

484:   N     = options->N;
485:   n     = N;
486:   names = options->names;
487: 
488:   for (i=0; i<N; i++) {
489:     PetscStrcmp(names[i],name,&match);
490:     ierr  = PetscStrgrt(names[i],name,&gt);
491:     if (match) {
492:       if (options->values[i]) free(options->values[i]);
493:       PetscStrlen(value,&len);
494:       if (len) {
495:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
496:         PetscStrcpy(options->values[i],value);
497:       } else { options->values[i] = 0;}
498:       return(0);
499:     } else if (gt) {
500:       n = i;
501:       break;
502:     }
503:   }
504:   if (N >= MAXOPTIONS) {
505:     SETERRQ1(1,"No more room in option table, limit %d recompile n src/sys/src/objects/options.c with larger value for MAXOPTIONSn",MAXOPTIONS);
506:   }
507:   /* shift remaining values down 1 */
508:   for (i=N; i>n; i--) {
509:     names[i]           = names[i-1];
510:     options->values[i] = options->values[i-1];
511:     options->used[i]   = options->used[i-1];
512:   }
513:   /* insert new name and value */
514:   PetscStrlen(name,&len);
515:   names[n] = (char*)malloc((len+1)*sizeof(char));
516:   PetscStrcpy(names[n],name);
517:   if (value) {
518:     PetscStrlen(value,&len);
519:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
520:     PetscStrcpy(options->values[n],value);
521:   } else {options->values[n] = 0;}
522:   options->used[n] = 0;
523:   options->N++;
524:   return(0);
525: }

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

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

534:    Input Parameter:
535: .  name - name of option, this SHOULD have the - prepended

537:    Level: intermediate

539:    Concepts: options database^removing option
540: .seealso: PetscOptionsInsert()
541: @*/
542: int PetscOptionsClearValue(const char iname[])
543: {
544:   int        N,n,i,ierr;
545:   char       **names,*name=(char*)iname;
546:   PetscTruth gt,match;

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

551:   name++;

553:   N     = options->N; n = 0;
554:   names = options->names;
555: 
556:   for (i=0; i<N; i++) {
557:     PetscStrcmp(names[i],name,&match);
558:     ierr  = PetscStrgrt(names[i],name,&gt);
559:     if (match) {
560:       if (options->values[i]) free(options->values[i]);
561:       break;
562:     } else if (gt) {
563:       return(0); /* it was not listed */
564:     }
565:     n++;
566:   }
567:   /* shift remaining values down 1 */
568:   for (i=n; i<N-1; i++) {
569:     names[i]           = names[i+1];
570:     options->values[i] = options->values[i+1];
571:     options->used[i]   = options->used[i+1];
572:   }
573:   options->N--;
574:   return(0);
575: }

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

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

583:    Input Parameters:
584: +  name - the option one is seeking 
585: -  mess - error message (may be PETSC_NULL)

587:    Level: advanced

589:    Concepts: options database^rejecting option

591: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),OptionsHasName(),
592:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
593: @*/
594: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
595: {
596:   int  ierr,len,n = options->Naliases;
597:   char *newname = (char *)inewname,*oldname = (char*)ioldname;

600:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
601:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
602:   if (n >= MAXALIASES) {
603:     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);
604:   }

606:   newname++; oldname++;
607:   PetscStrlen(newname,&len);
608:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
609:   PetscStrcpy(options->aliases1[n],newname);
610:   PetscStrlen(oldname,&len);
611:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
612:   PetscStrcpy(options->aliases2[n],oldname);
613:   options->Naliases++;
614:   return(0);
615: }

617: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
618: {
619:   int        i,N,ierr,len;
620:   char       **names,tmp[256];
621:   PetscTruth match;

624:   if (!options) {PetscOptionsInsert(0,0,0);}
625:   N = options->N;
626:   names = options->names;

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

630:   /* append prefix to name */
631:   if (pre) {
632:     PetscStrncpy(tmp,pre,256);
633:     PetscStrlen(tmp,&len);
634:     PetscStrncat(tmp,name+1,256-len-1);
635:   } else {
636:     PetscStrncpy(tmp,name+1,256);
637:   }

639:   /* slow search */
640:   *flg = PETSC_FALSE;
641:   for (i=0; i<N; i++) {
642:     PetscStrcmp(names[i],tmp,&match);
643:     if (match) {
644:        *value = options->values[i];
645:        options->used[i]++;
646:        *flg = PETSC_TRUE;
647:        break;
648:      }
649:   }
650:   return(0);
651: }

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

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

659:    Input Parameters:
660: +  name - the option one is seeking 
661: -  mess - error message (may be PETSC_NULL)

663:    Level: advanced

665:    Concepts: options database^rejecting option

667: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),OptionsHasName(),
668:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
669: @*/
670: int PetscOptionsReject(const char name[],const char mess[])
671: {
672:   int        ierr;
673:   PetscTruth flag;

676:   PetscOptionsHasName(PETSC_NULL,name,&flag);
677:   if (flag) {
678:     if (mess) {
679:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
680:     } else {
681:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
682:     }
683:   }
684:   return(0);
685: }

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

690:    Not Collective

692:    Input Parameters:
693: +  name - the option one is seeking 
694: -  pre - string to prepend to the name or PETSC_NULL

696:    Output Parameters:
697: .  flg - PETSC_TRUE if found else PETSC_FALSE.

699:    Level: beginner

701:    Concepts: options database^has option name

703: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
704:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
705: @*/
706: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
707: {
708:   char       *value;
709:   int        ierr;
710:   PetscTruth isfalse,flag;

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

715:   /* remove if turned off */
716:   if (flag) {
717:     PetscStrcmp(value,"FALSE",&isfalse);
718:     if (isfalse) flag = PETSC_FALSE;
719:     PetscStrcmp(value,"NO",&isfalse);
720:     if (isfalse) flag = PETSC_FALSE;
721:     PetscStrcmp(value,"0",&isfalse);
722:     if (isfalse) flag = PETSC_FALSE;
723:     PetscStrcmp(value,"false",&isfalse);
724:     if (isfalse) flag = PETSC_FALSE;
725:     PetscStrcmp(value,"no",&isfalse);
726:   }
727:   if (flg) *flg = flag;

729:   return(0);
730: }

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

735:    Not Collective

737:    Input Parameters:
738: +  pre - the string to prepend to the name or PETSC_NULL
739: -  name - the option one is seeking

741:    Output Parameter:
742: +  ivalue - the integer value to return
743: -  flg - PETSC_TRUE if found, else PETSC_FALSE

745:    Level: beginner

747:    Concepts: options database^has int

749: .seealso: PetscOptionsGetDouble(), PetscOptionsHasName(), PetscOptionsGetString(),
750:           PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
751: @*/
752: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
753: {
754:   char       *value;
755:   int        ierr;
756:   PetscTruth flag;

759:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
760:   if (flag) {
761:     if (!value) {if (flg) *flg = PETSC_FALSE; *ivalue = 0;}
762:     else {
763:       if (flg) *flg = PETSC_TRUE;
764:       PetscOptionsAtoi(value,ivalue);
765:     }
766:   } else {
767:     if (flg) *flg = PETSC_FALSE;
768:   }
769:   return(0);
770: }

772: /*@C
773:    PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular 
774:             option in the database.

776:    Not Collective

778:    Input Parameters:
779: +  pre - the string to prepend to the name or PETSC_NULL
780: -  name - the option one is seeking

782:    Output Parameter:
783: +  ivalue - the logical value to return
784: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

786:    Level: beginner

788:    Notes:
789:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
790:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

792:    Concepts: options database^has logical

794: .seealso: PetscOptionsGetDouble(), PetscOptionsHasName(), PetscOptionsGetString(),
795:           PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray(), PetscOptionsGetInt()
796: @*/
797: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
798: {
799:   char       *value;
800:   PetscTruth flag,istrue,isfalse;
801:   int        ierr;

804:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
805:   if (flag) {
806:     if (flg) *flg = PETSC_TRUE;
807:     if (!value) {
808:       *ivalue = PETSC_TRUE;
809:     } else {
810:       *ivalue = PETSC_TRUE;
811:       PetscStrcmp(value,"TRUE",&istrue);
812:       if (istrue) return(0);
813:       PetscStrcmp(value,"YES",&istrue);
814:       if (istrue) return(0);
815:       PetscStrcmp(value,"YES",&istrue);
816:       if (istrue) return(0);
817:       PetscStrcmp(value,"1",&istrue);
818:       if (istrue) return(0);
819:       PetscStrcmp(value,"true",&istrue);
820:       if (istrue) return(0);
821:       PetscStrcmp(value,"yes",&istrue);
822:       if (istrue) return(0);

824:       *ivalue = PETSC_FALSE;
825:       PetscStrcmp(value,"FALSE",&isfalse);
826:       if (isfalse) return(0);
827:       PetscStrcmp(value,"NO",&isfalse);
828:       if (isfalse) return(0);
829:       PetscStrcmp(value,"0",&isfalse);
830:       if (isfalse) return(0);
831:       PetscStrcmp(value,"false",&isfalse);
832:       if (isfalse) return(0);
833:       PetscStrcmp(value,"no",&isfalse);
834:       if (isfalse) return(0);

836:       SETERRQ1(1,"Unknown logical value: %s",value);
837:     }
838:   } else {
839:     if (flg) *flg = PETSC_FALSE;
840:   }
841:   return(0);
842: }

844: /*@C
845:    PetscOptionsGetDouble - Gets the double precision value for a particular 
846:    option in the database.

848:    Not Collective

850:    Input Parameters:
851: +  pre - string to prepend to each name or PETSC_NULL
852: -  name - the option one is seeking

854:    Output Parameter:
855: +  dvalue - the double value to return
856: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

858:    Level: beginner

860:    Concepts: options database^has double

862: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
863:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
864: @*/
865: int PetscOptionsGetDouble(const char pre[],const char name[],double *dvalue,PetscTruth *flg)
866: {
867:   char       *value;
868:   int        ierr;
869:   PetscTruth flag;

872:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
873:   if (flag) {
874:     if (!value) {if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;}
875:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
876:   } else {
877:     if (flg) *flg = PETSC_FALSE;
878:   }
879:   return(0);
880: }

882: /*@C
883:    PetscOptionsGetScalar - Gets the scalar value for a particular 
884:    option in the database.

886:    Not Collective

888:    Input Parameters:
889: +  pre - string to prepend to each name or PETSC_NULL
890: -  name - the option one is seeking

892:    Output Parameter:
893: +  dvalue - the double value to return
894: -  flg - PETSC_TRUE if found, else PETSC_FALSE

896:    Level: beginner

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

902:    Concepts: options database^has scalar

904: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
905:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
906: @*/
907: int PetscOptionsGetScalar(const char pre[],const char name[],Scalar *dvalue,PetscTruth *flg)
908: {
909:   char       *value;
910:   PetscTruth flag;
911:   int        ierr;
912: 
914:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
915:   if (flag) {
916:     if (!value) {
917:       if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;
918:     } else {
919: #if !defined(PETSC_USE_COMPLEX)
920:       PetscOptionsAtod(value,dvalue);
921: #else
922:       double re=0.0,im=0.0;
923:       char   *tvalue = 0;

925:       PetscStrtok(value,",",&tvalue);
926:       if (!tvalue) { SETERRQ(1,"unknown string specifiedn"); }
927:       ierr    = PetscOptionsAtod(tvalue,&re);
928:       ierr    = PetscStrtok(0,",",&tvalue);
929:       if (!tvalue) { /* Unknown separator used. using only real value */
930:         *dvalue = re;
931:       } else {
932:         ierr    = PetscOptionsAtod(tvalue,&im);
933:         *dvalue = re + PETSC_i*im;
934:       }
935: #endif
936:       if (flg) *flg    = PETSC_TRUE;
937:     }
938:   } else { /* flag */
939:     if (flg) *flg = PETSC_FALSE;
940:   }
941:   return(0);
942: }

944: /*@C
945:    PetscOptionsGetDoubleArray - Gets an array of double precision values for a 
946:    particular option in the database.  The values must be separated with 
947:    commas with no intervening spaces.

949:    Not Collective

951:    Input Parameters:
952: +  pre - string to prepend to each name or PETSC_NULL
953: .  name - the option one is seeking
954: -  nmax - maximum number of values to retrieve

956:    Output Parameters:
957: +  dvalue - the double value to return
958: .  nmax - actual number of values retreived
959: -  flg - PETSC_TRUE if found, else PETSC_FALSE

961:    Level: beginner

963:    Concepts: options database^array of doubles

965: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
966:            PetscOptionsGetString(), PetscOptionsGetIntArray()
967: @*/
968: int PetscOptionsGetDoubleArray(const char pre[],const char name[],double dvalue[],int *nmax,PetscTruth *flg)
969: {
970:   char       *value,*cpy;
971:   int        n = 0,ierr;
972:   PetscTruth flag;

975:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
976:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
977:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

979:   if (flg) *flg = PETSC_TRUE;
980:   /* make a copy of the values, otherwise we destroy the old values */
981:   ierr  = PetscStrallocpy(value,&cpy);
982:   value = cpy;

984:   PetscStrtok(value,",",&value);
985:   while (n < *nmax) {
986:     if (!value) break;
987:     PetscOptionsAtod(value,dvalue++);
988:     PetscStrtok(0,",",&value);
989:     n++;
990:   }
991:   *nmax = n;
992:   PetscFree(cpy);
993:   return(0);
994: }

996: /*@C
997:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
998:    option in the database.  The values must be separated with commas with 
999:    no intervening spaces. 

1001:    Not Collective

1003:    Input Parameters:
1004: +  pre - string to prepend to each name or PETSC_NULL
1005: .  name - the option one is seeking
1006: -  nmax - maximum number of values to retrieve

1008:    Output Parameter:
1009: +  dvalue - the integer values to return
1010: .  nmax - actual number of values retreived
1011: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1013:    Level: beginner

1015:    Concepts: options database^array of ints

1017: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1018:            PetscOptionsGetString(), PetscOptionsGetDoubleArray()
1019: @*/
1020: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1021: {
1022:   char       *value,*cpy;
1023:   int        n = 0,ierr;
1024:   PetscTruth flag;

1027:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1028:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1029:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1031:   if (flg) *flg = PETSC_TRUE;
1032:   /* make a copy of the values, otherwise we destroy the old values */
1033:   ierr  = PetscStrallocpy(value,&cpy);
1034:   value = cpy;

1036:   PetscStrtok(value,",",&value);
1037:   while (n < *nmax) {
1038:     if (!value) break;
1039:     ierr      = PetscOptionsAtoi(value,dvalue);
1040:     dvalue++;
1041:     ierr      = PetscStrtok(0,",",&value);
1042:     n++;
1043:   }
1044:   *nmax = n;
1045:   PetscFree(cpy);
1046:   return(0);
1047: }

1049: /*@C
1050:    PetscOptionsGetString - Gets the string value for a particular option in
1051:    the database.

1053:    Not Collective

1055:    Input Parameters:
1056: +  pre - string to prepend to name or PETSC_NULL
1057: .  name - the option one is seeking
1058: -  len - maximum string length

1060:    Output Parameters:
1061: +  string - location to copy string
1062: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1064:    Level: beginner

1066:    Fortran Note:
1067:    The Fortran interface is slightly different from the C/C++
1068:    interface (len is not used).  Sample usage in Fortran follows
1069: .vb
1070:       character *20 string
1071:       integer   flg, ierr
1072:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1073: .ve

1075:    Concepts: options database^string

1077: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),  
1078:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1079: @*/
1080: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1081: {
1082:   char       *value;
1083:   int        ierr;
1084:   PetscTruth flag;

1087:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1088:   if (!flag) {
1089:     if (flg) *flg = PETSC_FALSE;
1090:   } else {
1091:     if (flg) *flg = PETSC_TRUE;
1092:     if (value) {
1093:       PetscStrncpy(string,value,len);
1094:     } else {
1095:       PetscMemzero(string,len);
1096:     }
1097:   }
1098:   return(0);
1099: }

1101: /*@C
1102:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1103:    option in the database. The values must be separated with commas with 
1104:    no intervening spaces. 

1106:    Not Collective

1108:    Input Parameters:
1109: +  pre - string to prepend to name or PETSC_NULL
1110: .  name - the option one is seeking
1111: -  nmax - maximum number of strings

1113:    Output Parameter:
1114: +  strings - location to copy strings
1115: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1117:    Level: beginner

1119:    Notes: 
1120:    The user should pass in an array of pointers to char, to hold all the
1121:    strings returned by this function.

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

1126:    Contributed by Matthew Knepley.

1128:    Concepts: options database^array of strings

1130: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),  
1131:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1132: @*/
1133: int PetscOptionsGetStringArray(const char pre[],const char name[],char **strings,int *nmax,PetscTruth *flg)
1134: {
1135:   char       *value,*cpy;
1136:   int        len,n,ierr;
1137:   PetscTruth flag;

1140:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1141:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1142:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1143:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1144:   if (flg) *flg = PETSC_TRUE;

1146:   /* make a copy of the values, otherwise we destroy the old values */
1147:   ierr  = PetscStrallocpy(value,&cpy);
1148:   value = cpy;

1150:   PetscStrtok(value,",",&value);
1151:   n = 0;
1152:   while (n < *nmax) {
1153:     if (!value) break;
1154:     PetscStrlen(value,&len);
1155:     PetscMalloc((len+1)*sizeof(char),&strings[n]);
1156:     PetscStrcpy(strings[n],value);
1157:     PetscStrtok(0,",",&value);
1158:     n++;
1159:   }
1160:   *nmax = n;
1161:   PetscFree(cpy);
1162:   return(0);
1163: }

1165: /*@C
1166:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1167:    database that have never been selected.

1169:    Not Collective

1171:    Output Parameter:
1172: .   N - count of options not used

1174:    Level: advanced

1176: .seealso: PetscOptionsPrint()
1177: @*/
1178: int PetscOptionsAllUsed(int *N)
1179: {
1180:   int  i,n = 0;

1183:   for (i=0; i<options->N; i++) {
1184:     if (!options->used[i]) { n++; }
1185:   }
1186:   *N = n;
1187:   return(0);
1188: }

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

1193:   Not collective

1195:    Options Database Key:
1196: .  -optionsleft - Activates OptionsAllUsed() within PetscFinalize()

1198:   Level: advanced

1200: .seealso: PetscOptionsAllUsed()
1201: @*/
1202: int PetscOptionsLeft(void)
1203: {
1204:   int        i,ierr;

1207:   for (i=0; i<options->N; i++) {
1208:     if (!options->used[i]) {
1209:       if (options->values[i]) {
1210:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %sn",options->names[i],options->values[i]);
1211:       } else {
1212:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value n",options->names[i]);
1213:       }
1214:     }
1215:   }
1216:   return(0);
1217: }

1219: /*
1220:     PetscOptionsCreate - Creates the empty options database.

1222: */
1223: int PetscOptionsCreate(void)
1224: {

1228:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1229:   ierr    = PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1230:   options->namegiven = PETSC_FALSE;
1231:   options->N         = 0;
1232:   options->Naliases  = 0;
1233:   return(0);
1234: }