Actual source code: options.c

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

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

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

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

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

 37: static PetscOptionsTable *options = 0;

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

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

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

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

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

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

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

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

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

120:     Not Collective

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

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

128:    Level: advanced

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

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

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

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

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

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

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


170:   Level: intermediate

172:   Contributed by Boyana Norris

174: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
175:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
176:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
177:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
178:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
179:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

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

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

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

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

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


231:   Level: intermediate

233: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
234:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
235:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
236:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
237:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
238:           PetscOptionsList(), PetscOptionsEList()

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

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

259:       PetscStrlen(string,&len);

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

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

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

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

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

317:    Level: advanced

319:    Concepts: options database^adding

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

331:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

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

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

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

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

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

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

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

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

439:    Collective on PETSC_COMM_WORLD

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

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

447:    Level: advanced

449:    Concepts: options database^printing

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

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

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

476:    Not Collective

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

481:    Level: advanced

483:    Concepts: options database^listing

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

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

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

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

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

530:    Level: developer

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

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

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

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

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

566:    Level: intermediate

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

572:   Concepts: options database^adding option

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

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

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

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

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

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

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

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

658:    Level: intermediate

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

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

674:   name++;

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

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

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

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

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

714:    Level: advanced

716:    Concepts: options database^rejecting option

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

733:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
734:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
735:   if (n >= MAXALIASES) {
736:     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);
737:   }

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

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

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

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

767:   /* append prefix to name */
768:   if (pre) {
769:     PetscStrncpy(tmp,pre,256);
770:     PetscStrlen(tmp,&len);
771:     PetscStrncat(tmp,name+1,256-len-1);
772:   } else {
773:     PetscStrncpy(tmp,name+1,256);
774:   }

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

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

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

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

830:    Level: advanced

832:    Concepts: options database^rejecting option

834: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
835:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
836:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
837:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
838:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
839:           PetscOptionsList(), PetscOptionsEList()
840: @*/
841: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
842: {
844:   PetscTruth flag;

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

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

863:    Not Collective

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

869:    Output Parameters:
870: .  flg - PETSC_TRUE if found else PETSC_FALSE.

872:    Level: beginner

874:    Concepts: options database^has option name

876: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
877:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
878:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
879:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
880:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
881:           PetscOptionsList(), PetscOptionsEList()
882: @*/
883: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
884: {
885:   char       *value;
887:   PetscTruth isfalse,flag;

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

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

906:   return(0);
907: }

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

914:    Not Collective

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

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

924:    Level: beginner

926:    Concepts: options database^has int

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

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

960: /*@C
961:    PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular 
962:             option in the database.

964:    Not Collective

966:    Input Parameters:
967: +  pre - the string to prepend to the name or PETSC_NULL
968: -  name - the option one is seeking

970:    Output Parameter:
971: +  ivalue - the logical value to return
972: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

974:    Level: beginner

976:    Notes:
977:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
978:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

980:    Concepts: options database^has logical

982: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
983:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsLogical(),
984:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
985:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
986:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
987:           PetscOptionsList(), PetscOptionsEList()
988: @*/
989: PetscErrorCode PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
990: {
991:   char       *value;
992:   PetscTruth flag,istrue,isfalse;

998:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
999:   if (flag) {
1000:     if (flg) *flg = PETSC_TRUE;
1001:     if (!value) {
1002:       *ivalue = PETSC_TRUE;
1003:     } else {
1004:       *ivalue = PETSC_TRUE;
1005:       PetscStrcmp(value,"TRUE",&istrue);
1006:       if (istrue) return(0);
1007:       PetscStrcmp(value,"YES",&istrue);
1008:       if (istrue) return(0);
1009:       PetscStrcmp(value,"YES",&istrue);
1010:       if (istrue) return(0);
1011:       PetscStrcmp(value,"1",&istrue);
1012:       if (istrue) return(0);
1013:       PetscStrcmp(value,"true",&istrue);
1014:       if (istrue) return(0);
1015:       PetscStrcmp(value,"yes",&istrue);
1016:       if (istrue) return(0);
1017:       PetscStrcmp(value,"on",&istrue);
1018:       if (istrue) return(0);

1020:       *ivalue = PETSC_FALSE;
1021:       PetscStrcmp(value,"FALSE",&isfalse);
1022:       if (isfalse) return(0);
1023:       PetscStrcmp(value,"NO",&isfalse);
1024:       if (isfalse) return(0);
1025:       PetscStrcmp(value,"0",&isfalse);
1026:       if (isfalse) return(0);
1027:       PetscStrcmp(value,"false",&isfalse);
1028:       if (isfalse) return(0);
1029:       PetscStrcmp(value,"no",&isfalse);
1030:       if (isfalse) return(0);
1031:       PetscStrcmp(value,"off",&isfalse);
1032:       if (isfalse) return(0);

1034:       SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1035:     }
1036:   } else {
1037:     if (flg) *flg = PETSC_FALSE;
1038:   }
1039:   return(0);
1040: }

1044: /*@C
1045:    PetscOptionsGetReal - Gets the double precision value for a particular 
1046:    option in the database.

1048:    Not Collective

1050:    Input Parameters:
1051: +  pre - string to prepend to each name or PETSC_NULL
1052: -  name - the option one is seeking

1054:    Output Parameter:
1055: +  dvalue - the double value to return
1056: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1058:    Level: beginner

1060:    Concepts: options database^has double

1062: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1063:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
1064:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1065:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1066:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1067:           PetscOptionsList(), PetscOptionsEList()
1068: @*/
1069: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1070: {
1071:   char       *value;
1073:   PetscTruth flag;

1078:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1079:   if (flag) {
1080:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1081:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1082:   } else {
1083:     if (flg) *flg = PETSC_FALSE;
1084:   }
1085:   return(0);
1086: }

1090: /*@C
1091:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1092:    option in the database.

1094:    Not Collective

1096:    Input Parameters:
1097: +  pre - string to prepend to each name or PETSC_NULL
1098: -  name - the option one is seeking

1100:    Output Parameter:
1101: +  dvalue - the double value to return
1102: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1104:    Level: beginner

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

1110:    Concepts: options database^has scalar

1112: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1113:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1114:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1115:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1116:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1117:           PetscOptionsList(), PetscOptionsEList()
1118: @*/
1119: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1120: {
1121:   char       *value;
1122:   PetscTruth flag;

1128:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1129:   if (flag) {
1130:     if (!value) {
1131:       if (flg) *flg = PETSC_FALSE;
1132:     } else {
1133: #if !defined(PETSC_USE_COMPLEX)
1134:       PetscOptionsAtod(value,dvalue);
1135: #else
1136:       PetscReal  re=0.0,im=0.0;
1137:       PetscToken *token;
1138:       char       *tvalue = 0;

1140:       PetscTokenCreate(value,',',&token);
1141:       PetscTokenFind(token,&tvalue);
1142:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1143:       PetscOptionsAtod(tvalue,&re);
1144:       PetscTokenFind(token,&tvalue);
1145:       if (!tvalue) { /* Unknown separator used. using only real value */
1146:         *dvalue = re;
1147:       } else {
1148:         PetscOptionsAtod(tvalue,&im);
1149:         *dvalue = re + PETSC_i*im;
1150:       }
1151:       PetscTokenDestroy(token);
1152: #endif
1153:       if (flg) *flg    = PETSC_TRUE;
1154:     }
1155:   } else { /* flag */
1156:     if (flg) *flg = PETSC_FALSE;
1157:   }
1158:   return(0);
1159: }

1163: /*@C
1164:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1165:    particular option in the database.  The values must be separated with 
1166:    commas with no intervening spaces.

1168:    Not Collective

1170:    Input Parameters:
1171: +  pre - string to prepend to each name or PETSC_NULL
1172: .  name - the option one is seeking
1173: -  nmax - maximum number of values to retrieve

1175:    Output Parameters:
1176: +  dvalue - the double value to return
1177: .  nmax - actual number of values retreived
1178: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1180:    Level: beginner

1182:    Concepts: options database^array of doubles

1184: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1185:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
1186:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1187:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1188:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1189:           PetscOptionsList(), PetscOptionsEList()
1190: @*/
1191: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1192: {
1193:   char       *value;
1195:   int        n = 0;
1196:   PetscTruth flag;
1197:   PetscToken *token;

1202:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1203:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1204:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1206:   if (flg) *flg = PETSC_TRUE;

1208:   PetscTokenCreate(value,',',&token);
1209:   PetscTokenFind(token,&value);
1210:   while (n < *nmax) {
1211:     if (!value) break;
1212:     PetscOptionsAtod(value,dvalue++);
1213:     PetscTokenFind(token,&value);
1214:     n++;
1215:   }
1216:   PetscTokenDestroy(token);
1217:   *nmax = n;
1218:   return(0);
1219: }

1223: /*@C
1224:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1225:    option in the database.  The values must be separated with commas with 
1226:    no intervening spaces. 

1228:    Not Collective

1230:    Input Parameters:
1231: +  pre - string to prepend to each name or PETSC_NULL
1232: .  name - the option one is seeking
1233: -  nmax - maximum number of values to retrieve

1235:    Output Parameter:
1236: +  dvalue - the integer values to return
1237: .  nmax - actual number of values retreived
1238: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1240:    Level: beginner

1242:    Concepts: options database^array of ints

1244: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1245:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1246:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1247:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1248:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1249:           PetscOptionsList(), PetscOptionsEList()
1250: @*/
1251: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1252: {
1253:   char           *value;
1255:   PetscInt       n = 0;
1256:   PetscTruth     flag;
1257:   PetscToken     *token;

1262:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1263:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1264:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1266:   if (flg) *flg = PETSC_TRUE;

1268:   PetscTokenCreate(value,',',&token);
1269:   PetscTokenFind(token,&value);
1270:   while (n < *nmax) {
1271:     if (!value) break;
1272:     PetscOptionsAtoi(value,dvalue);
1273:     dvalue++;
1274:     PetscTokenFind(token,&value);
1275:     n++;
1276:   }
1277:   PetscTokenDestroy(token);
1278:   *nmax = n;
1279:   return(0);
1280: }

1284: /*@C
1285:    PetscOptionsGetString - Gets the string value for a particular option in
1286:    the database.

1288:    Not Collective

1290:    Input Parameters:
1291: +  pre - string to prepend to name or PETSC_NULL
1292: .  name - the option one is seeking
1293: -  len - maximum string length

1295:    Output Parameters:
1296: +  string - location to copy string
1297: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1299:    Level: beginner

1301:    Fortran Note:
1302:    The Fortran interface is slightly different from the C/C++
1303:    interface (len is not used).  Sample usage in Fortran follows
1304: .vb
1305:       character *20 string
1306:       integer   flg, ierr
1307:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1308: .ve

1310:    Concepts: options database^string

1312: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1313:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1314:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1315:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1316:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1317:           PetscOptionsList(), PetscOptionsEList()
1318: @*/
1319: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1320: {
1321:   char       *value;
1323:   PetscTruth flag;

1328:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1329:   if (!flag) {
1330:     if (flg) *flg = PETSC_FALSE;
1331:   } else {
1332:     if (flg) *flg = PETSC_TRUE;
1333:     if (value) {
1334:       PetscStrncpy(string,value,len);
1335:     } else {
1336:       PetscMemzero(string,len);
1337:     }
1338:   }
1339:   return(0);
1340: }

1344: /*@C
1345:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1346:    option in the database. The values must be separated with commas with 
1347:    no intervening spaces. 

1349:    Not Collective

1351:    Input Parameters:
1352: +  pre - string to prepend to name or PETSC_NULL
1353: .  name - the option one is seeking
1354: -  nmax - maximum number of strings

1356:    Output Parameter:
1357: +  strings - location to copy strings
1358: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1360:    Level: beginner

1362:    Notes: 
1363:    The user should pass in an array of pointers to char, to hold all the
1364:    strings returned by this function.

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

1369:    Contributed by Matthew Knepley.

1371:    Concepts: options database^array of strings

1373: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1374:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1375:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1376:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1377:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1378:           PetscOptionsList(), PetscOptionsEList()
1379: @*/
1380: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1381: {
1382:   char           *value;
1384:   PetscInt       n;
1385:   PetscTruth     flag;
1386:   PetscToken     *token;
1387: 
1391:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1392:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1393:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1394:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1395:   if (flg) *flg = PETSC_TRUE;

1397:   PetscTokenCreate(value,',',&token);
1398:   PetscTokenFind(token,&value);
1399:   n = 0;
1400:   while (n < *nmax) {
1401:     if (!value) break;
1402:     PetscStrallocpy(value,&strings[n]);
1403:     PetscTokenFind(token,&value);
1404:     n++;
1405:   }
1406:   PetscTokenDestroy(token);
1407:   *nmax = n;
1408:   return(0);
1409: }

1413: /*@C
1414:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1415:    database that have never been selected.

1417:    Not Collective

1419:    Output Parameter:
1420: .   N - count of options not used

1422:    Level: advanced

1424: .seealso: PetscOptionsPrint()
1425: @*/
1426: PetscErrorCode PetscOptionsAllUsed(int *N)
1427: {
1428:   int  i,n = 0;

1431:   for (i=0; i<options->N; i++) {
1432:     if (!options->used[i]) { n++; }
1433:   }
1434:   *N = n;
1435:   return(0);
1436: }

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

1443:   Not collective

1445:    Options Database Key:
1446: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1448:   Level: advanced

1450: .seealso: PetscOptionsAllUsed()
1451: @*/
1452: PetscErrorCode PetscOptionsLeft(void)
1453: {
1455:   int        i;

1458:   for (i=0; i<options->N; i++) {
1459:     if (!options->used[i]) {
1460:       if (options->values[i]) {
1461:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1462:       } else {
1463:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1464:       }
1465:     }
1466:   }
1467:   return(0);
1468: }

1470: /*
1471:     PetscOptionsCreate - Creates the empty options database.

1473: */
1476: PetscErrorCode PetscOptionsCreate(void)
1477: {

1481:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1482:   PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1483:   options->namegiven = PETSC_FALSE;
1484:   options->N         = 0;
1485:   options->Naliases  = 0;
1486:   return(0);
1487: }