Actual source code: options.c

  1: #define PETSC_DLL
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

 10:  #include petsc.h
 11:  #include petscsys.h
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif
 15: #if defined(PETSC_HAVE_MALLOC_H)
 16: #include <malloc.h>
 17: #endif
 18: #if defined(PETSC_HAVE_SYS_PARAM_H)
 19: #include "sys/param.h"
 20: #endif
 21: #include "petscfix.h"

 23: /* 
 24:     For simplicity, we use a static size database
 25: */
 26: #define MAXOPTIONS 512
 27: #define MAXALIASES 25
 28: #define MAXOPTIONSMONITORS 5

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

 38:   /* --------User (or default) routines (most return -1 on error) --------*/
 39:   PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
 40:   PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*);         /* */
 41:   void           *monitorcontext[MAXOPTIONSMONITORS];                  /* to pass arbitrary user data into monitor */
 42:   PetscInt       numbermonitors;                                       /* to, for instance, detect options being set */

 44: } PetscOptionsTable;


 47: static PetscOptionsTable *options = 0;


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

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

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

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

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

105: PetscErrorCode  PetscOptionsAtod(const char name[],PetscReal *a)
106: {
108:   size_t         len;
109:   PetscTruth     decide,tdefault;

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

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

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

139: /*@C
140:     PetscGetProgramName - Gets the name of the running program. 

142:     Not Collective

144:     Input Parameter:
145: .   len - length of the string name

147:     Output Parameter:
148: .   name - the name of the running program

150:    Level: advanced

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

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

170: PetscErrorCode  PetscSetProgramName(const char name[])
171: {

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

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

195: /*@C
196:      PetscOptionsInsertString - Inserts options into the database from a string

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

201:   Input Parameter:
202: .   in_str - string that contains options separated by blanks


205:   Level: intermediate

207:   Contributed by Boyana Norris

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

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

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

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

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

255:   Input Parameter:
256: .   file - name of file


259:   Level: intermediate

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

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

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

287:       PetscStrlen(string,&len);

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

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

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

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

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

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

348:    Level: advanced

350:    Concepts: options database^adding

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

363:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

365:   options->argc     = (argc) ? *argc : 0;
366:   options->args     = (args) ? *args : 0;

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

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

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

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

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

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

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

463:    Collective on PETSC_COMM_WORLD

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

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

471:    Level: advanced

473:    Concepts: options database^printing

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

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

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

500:    Not Collective

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

505:    Level: advanced

507:    Concepts: options database^listing

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

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

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

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

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

554:    Level: developer

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

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

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

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

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

590:    Level: intermediate

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

596:   Concepts: options database^adding option

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

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

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

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

627:   N     = options->N;
628:   n     = N;
629:   names = options->names;
630: 
631:   for (i=0; i<N; i++) {
632:     PetscStrcasecmp(names[i],name,&match);
633:     PetscStrgrt(names[i],name,&gt);
634:     if (match) {
635:       if (options->values[i]) free(options->values[i]);
636:       PetscStrlen(value,&len);
637:       if (len) {
638:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
639:         PetscStrcpy(options->values[i],value);
640:       } else { options->values[i] = 0;}
641:       PetscOptionsMonitor(name,value);
642:       return(0);
643:     } else if (gt) {
644:       n = i;
645:       break;
646:     }
647:   }
648:   if (N >= MAXOPTIONS) {
649:     SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
650:   }
651:   /* shift remaining values down 1 */
652:   for (i=N; i>n; i--) {
653:     names[i]           = names[i-1];
654:     options->values[i] = options->values[i-1];
655:     options->used[i]   = options->used[i-1];
656:   }
657:   /* insert new name and value */
658:   PetscStrlen(name,&len);
659:   names[n] = (char*)malloc((len+1)*sizeof(char));
660:   PetscStrcpy(names[n],name);
661:   if (value) {
662:     PetscStrlen(value,&len);
663:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
664:     PetscStrcpy(options->values[n],value);
665:   } else {options->values[n] = 0;}
666:   options->used[n] = PETSC_FALSE;
667:   options->N++;
668:   PetscOptionsMonitor(name,value);
669:   return(0);
670: }

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

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

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

684:    Level: intermediate

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

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

700:   name++;

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

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

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

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

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

741:    Level: advanced

743:    Concepts: options database^rejecting option

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

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

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

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

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

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

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

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

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

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

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

858:    Level: advanced

860:    Concepts: options database^rejecting option

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

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

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

891:    Not Collective

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

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

900:    Level: beginner

902:    Concepts: options database^has option name

904:    Notes: Name cannot be simply -h

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

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

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

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

940:    Not Collective

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

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

950:    Level: beginner

952:    Concepts: options database^has int

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

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

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

989:    Not Collective

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

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

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

1005:    Concepts: options database^list

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

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

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

1052:    Not Collective

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

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

1064:    Level: beginner

1066:    Concepts: options database

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

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

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

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

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

1101:    Not Collective

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

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

1111:    Level: beginner

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

1117:    Concepts: options database^has logical

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

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

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

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

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

1175:    Not Collective

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

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

1185:    Level: beginner

1187:    Concepts: options database^has double

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

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

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

1221:    Not Collective

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

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

1231:    Level: beginner

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

1237:    Concepts: options database^has scalar

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

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

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

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

1295:    Not Collective

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

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

1307:    Level: beginner

1309:    Concepts: options database^array of doubles

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

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

1333:   if (flg) *flg = PETSC_TRUE;

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

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

1355:    Not Collective

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

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

1367:    Level: beginner

1369:    Concepts: options database^array of ints

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

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

1394:   if (flg) *flg = PETSC_TRUE;

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

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

1439:    Not Collective

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

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

1450:    Level: beginner

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

1461:    Concepts: options database^string

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

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

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

1500:    Not Collective

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

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

1511:    Level: beginner

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

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

1520:    Contributed by Matthew Knepley.

1522:    Concepts: options database^array of strings

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

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

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

1568:    Not Collective

1570:    Output Parameter:
1571: .   N - count of options not used

1573:    Level: advanced

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

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

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

1594:   Not collective

1596:    Options Database Key:
1597: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1599:   Level: advanced

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

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


1622: /*
1623:     PetscOptionsCreate - Creates the empty options database.

1625: */
1628: PetscErrorCode  PetscOptionsCreate(void)
1629: {

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

1640:   PetscOptionsObject.prefix = PETSC_NULL;
1641:   PetscOptionsObject.title  = PETSC_NULL;
1642: 
1643:   return(0);
1644: }

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

1651:    Collective on PETSC_COMM_WORLD

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

1661:    Notes:
1662:    To see all options, run your program with the -help option or consult
1663:    the users manual. 

1665:    Level: intermediate

1667: .keywords: set, options, database
1668: @*/
1669: PetscErrorCode  PetscOptionsSetFromOptions(void)
1670: {
1671:   PetscTruth          flg;
1672:   PetscErrorCode      ierr;
1673:   char                monfilename[PETSC_MAX_PATH_LEN];
1674:   PetscViewer         monviewer;


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

1690:   return(0);
1691: }


1696: /*@C
1697:    PetscOptionsMonitorDefault - Print all options set value events.

1699:    Collective on PETSC_COMM_WORLD

1701:    Input Parameters:
1702: +  name  - option name string
1703: .  value - option value string
1704: -  dummy - unused monitor context 

1706:    Level: intermediate

1708: .keywords: PetscOptions, default, monitor

1710: .seealso: PetscOptionsMonitorSet()
1711: @*/
1712: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1713: {
1715:   PetscViewer    viewer = (PetscViewer) dummy;

1718:   if (!viewer) {
1719:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1720:   }
1721:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1722:   return(0);
1723: }

1727: /*@C
1728:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1729:    modified the PETSc options database.
1730:       
1731:    Not collective

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

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

1743: +  name - option name string
1744: .  value - option value string
1745: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

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

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

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

1764:    Level: beginner

1766: .keywords: PetscOptions, set, monitor

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

1784: /*@
1785:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

1787:    Not collective 

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

1794:    Level: intermediate

1796: .keywords: PetscOptions, set, monitor

1798: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1799: @*/
1800: PetscErrorCode  PetscOptionsMonitorCancel(void)
1801: {
1803:   PetscInt       i;

1806:   for (i=0; i<options->numbermonitors; i++) {
1807:     if (options->monitordestroy[i]) {
1808:       (*options->monitordestroy[i])(options->monitorcontext[i]);
1809:     }
1810:   }
1811:   options->numbermonitors = 0;
1812:   return(0);
1813: }