Actual source code: options.c
1: /*$Id: options.c,v 1.252 2001/08/07 21:28:54 bsmith Exp $*/
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
15: #if defined(PETSC_HAVE_MALLOC_H) && !defined(__cplusplus)
16: #include <malloc.h>
17: #endif
18: #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 256
27: #define MAXALIASES 25
29: typedef struct {
30: int N,argc,Naliases;
31: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
32: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
33: int used[MAXOPTIONS];
34: PetscTruth namegiven;
35: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
36: } PetscOptionsTable;
38: static PetscOptionsTable *options = 0;
40: #undef __FUNCT__
42: int PetscOptionsAtoi(const char name[],int *a)
43: {
44: int i,ierr,len;
45: PetscTruth decide,tdefault,mouse;
48: PetscStrlen(name,&len);
49: if (!len) SETERRQ(1,"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(1,"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(1,"Input string %s has no integer value (do not include . in it)",name);
74: }
75: }
76: *a = atoi(name);
77: }
78: return(0);
79: }
81: #undef __FUNCT__
83: int PetscOptionsAtod(const char name[],PetscReal *a)
84: {
85: int ierr,len;
86: PetscTruth decide,tdefault;
89: PetscStrlen(name,&len);
90: if (!len) SETERRQ(1,"character string of length zero has no numerical value");
92: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
93: if (!tdefault) {
94: PetscStrcasecmp(name,"DEFAULT",&tdefault);
95: }
96: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
97: if (!decide) {
98: PetscStrcasecmp(name,"DECIDE",&decide);
99: }
101: if (tdefault) {
102: *a = PETSC_DEFAULT;
103: } else if (decide) {
104: *a = PETSC_DECIDE;
105: } else {
106: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
107: SETERRQ1(1,"Input string %s has no numeric value ",name);
108: }
109: *a = atof(name);
110: }
111: return(0);
112: }
114: #undef __FUNCT__
116: /*@C
117: PetscGetProgramName - Gets the name of the running program.
119: Not Collective
121: Input Parameter:
122: . len - length of the string name
124: Output Parameter:
125: . name - the name of the running program
127: Level: advanced
129: Notes:
130: The name of the program is copied into the user-provided character
131: array of length len. On some machines the program name includes
132: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
133: @*/
134: int PetscGetProgramName(char name[],int len)
135: {
139: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
140: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
141: PetscStrncpy(name,options->programname,len);
142: return(0);
143: }
145: #undef __FUNCT__
147: int PetscSetProgramName(const char name[])
148: {
152: options->namegiven = PETSC_TRUE;
153: ierr = PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
154: return(0);
155: }
157: #undef __FUNCT__
159: /*@C
160: PetscOptionsInsertString - Inserts options into the database from a string
162: Not collective: but only processes that call this routine will set the options
163: included in the file
165: Input Parameter:
166: . in_str - string that contains options seperated by blanks
169: Level: intermediate
171: Contributed by Boyana Norris
173: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
174: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
175: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
176: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
177: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
178: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
180: @*/
181: int PetscOptionsInsertString(const char* in_str)
182: {
183: char *str,*first,*second,*third,*final;
184: int len,ierr;
185: PetscToken *token;
188: PetscStrlen(in_str,&len);
189: PetscMalloc(len,&str);
190: PetscStrcpy(str, in_str);
192: PetscTokenCreate(str,' ',&token);
193: PetscTokenFind(token,&first);
194: PetscTokenFind(token,&second);
195: if (first && first[0] == '-') {
196: if (second) {final = second;} else {final = first;}
197: PetscStrlen(final,&len);
198: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
199: len--; final[len] = 0;
200: }
201: PetscOptionsSetValue(first,second);
202: } else if (first) {
203: PetscTruth match;
204:
205: PetscStrcmp(first,"alias",&match);
206: if (match) {
207: PetscTokenFind(token,&third);
208: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
209: PetscStrlen(third,&len);
210: if (third[len-1] == 'n') third[len-1] = 0;
211: PetscOptionsSetAlias(second,third);
212: }
213: }
214: PetscTokenDestroy(token);
215: PetscFree(str);
216:
217: return(0);
218: }
220: #undef __FUNCT__
222: /*@C
223: PetscOptionsInsertFile - Inserts options into the database from a file.
225: Not collective: but only processes that call this routine will set the options
226: included in the file
228: Input Parameter:
229: . file - name of file
232: Level: intermediate
234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
235: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
236: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
237: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
238: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
239: PetscOptionsList(), PetscOptionsEList()
241: @*/
242: int PetscOptionsInsertFile(const char file[])
243: {
244: char string[128],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
245: int len,ierr,i,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: }
296: return(0);
297: }
299: #undef __FUNCT__
301: /*@C
302: PetscOptionsInsert - Inserts into the options database from the command line,
303: the environmental variable and a file.
305: Input Parameters:
306: + argc - count of number of command line arguments
307: . args - the command line arguments
308: - file - optional filename, defaults to ~username/.petscrc
310: Note:
311: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
312: the user does not typically need to call this routine. PetscOptionsInsert()
313: can be called several times, adding additional entries into the database.
315: Level: advanced
317: Concepts: options database^adding
319: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
320: @*/
321: int PetscOptionsInsert(int *argc,char ***args,const char file[])
322: {
323: int ierr,rank;
324: char pfile[PETSC_MAX_PATH_LEN];
325: PetscToken *token;
328: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
330: options->argc = (argc) ? *argc : 0;
331: options->args = (args) ? *args : 0;
333: if (file) {
334: PetscOptionsInsertFile(file);
335: } else {
336: PetscGetHomeDirectory(pfile,240);
337: PetscStrcat(pfile,"/.petscrc");
338: PetscOptionsInsertFile(pfile);
339: }
341: /* insert environmental options */
342: {
343: char *eoptions = 0,*second,*first;
344: int len=0;
345: if (!rank) {
346: eoptions = (char*)getenv("PETSC_OPTIONS");
347: ierr = PetscStrlen(eoptions,&len);
348: ierr = MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
349: } else {
350: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
351: if (len) {
352: PetscMalloc((len+1)*sizeof(char*),&eoptions);
353: }
354: }
355: if (len) {
356: ierr = MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
357: eoptions[len] = 0;
358: ierr = PetscTokenCreate(eoptions,' ',&token);
359: ierr = PetscTokenFind(token,&first);
360: while (first) {
361: if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
362: PetscTokenFind(token,&second);
363: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
364: PetscOptionsSetValue(first,(char *)0);
365: first = second;
366: } else {
367: PetscOptionsSetValue(first,second);
368: PetscTokenFind(token,&first);
369: }
370: }
371: PetscTokenDestroy(token);
372: if (rank) {PetscFree(eoptions);}
373: }
374: }
376: /* insert command line options */
377: if (argc && args && *argc) {
378: int left = *argc - 1;
379: char **eargs = *args + 1;
380: PetscTruth isoptions_file,isp4,tisp4;
382: while (left) {
383: PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
384: PetscStrcmp(eargs[0],"-p4pg",&isp4);
385: PetscStrcmp(eargs[0],"-p4wd",&tisp4);
386: isp4 = (PetscTruth) (isp4 || tisp4);
387: PetscStrcmp(eargs[0],"-np",&tisp4);
388: isp4 = (PetscTruth) (isp4 || tisp4);
389: PetscStrcmp(eargs[0],"-p4amslave",&tisp4);
391: if (eargs[0][0] != '-') {
392: eargs++; left--;
393: } else if (isoptions_file) {
394: PetscOptionsInsertFile(eargs[1]);
395: eargs += 2; left -= 2;
397: /*
398: These are "bad" options that MPICH, etc put on the command line
399: we strip them out here.
400: */
401: } else if (tisp4) {
402: eargs += 1; left -= 1;
403: } else if (isp4) {
404: eargs += 2; left -= 2;
405: } else if ((left < 2) || ((eargs[1][0] == '-') &&
406: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
407: PetscOptionsSetValue(eargs[0],PETSC_NULL);
408: eargs++; left--;
409: } else {
410: PetscOptionsSetValue(eargs[0],eargs[1]);
411: eargs += 2; left -= 2;
412: }
413: }
414: }
415: return(0);
416: }
418: #undef __FUNCT__
420: /*@C
421: PetscOptionsPrint - Prints the options that have been loaded. This is
422: useful for debugging purposes.
424: Collective on PETSC_COMM_WORLD
426: Input Parameter:
427: . FILE fd - location to print options (usually stdout or stderr)
429: Options Database Key:
430: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
432: Level: advanced
434: Concepts: options database^printing
436: .seealso: PetscOptionsAllUsed()
437: @*/
438: int PetscOptionsPrint(FILE *fd)
439: {
440: int i,ierr;
443: if (!fd) fd = stdout;
444: if (!options) {PetscOptionsInsert(0,0,0);}
445: for (i=0; i<options->N; i++) {
446: if (options->values[i]) {
447: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %sn",options->names[i],options->values[i]);
448: } else {
449: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%sn",options->names[i]);
450: }
451: }
452: return(0);
453: }
455: #undef __FUNCT__
457: /*@C
458: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
460: Not Collective
462: Output Parameter:
463: . copts - pointer where string pointer is stored
465: Level: advanced
467: Concepts: options database^listing
469: .seealso: PetscOptionsAllUsed(), PetscOptionsPrintf()
470: @*/
471: int PetscOptionsGetAll(char *copts[])
472: {
473: int i,ierr,len = 1,lent;
474: char *coptions;
477: if (!options) {PetscOptionsInsert(0,0,0);}
479: /* count the length of the required string */
480: for (i=0; i<options->N; i++) {
481: PetscStrlen(options->names[i],&lent);
482: len += 2 + lent;
483: if (options->values[i]) {
484: PetscStrlen(options->values[i],&lent);
485: len += 1 + lent;
486: }
487: }
488: PetscMalloc(len*sizeof(char),&coptions);
489: coptions[0] = 0;
490: for (i=0; i<options->N; i++) {
491: PetscStrcat(coptions,"-");
492: PetscStrcat(coptions,options->names[i]);
493: PetscStrcat(coptions," ");
494: if (options->values[i]) {
495: PetscStrcat(coptions,options->values[i]);
496: PetscStrcat(coptions," ");
497: }
498: }
499: *copts = coptions;
500: return(0);
501: }
503: #undef __FUNCT__
505: /*@C
506: PetscOptionsDestroy - Destroys the option database.
508: Note:
509: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
510: typically does not need to call this routine.
512: Level: developer
514: .seealso: PetscOptionsInsert()
515: @*/
516: int PetscOptionsDestroy(void)
517: {
518: int i;
521: if (!options) return(0);
522: for (i=0; i<options->N; i++) {
523: if (options->names[i]) free(options->names[i]);
524: if (options->values[i]) free(options->values[i]);
525: }
526: for (i=0; i<options->Naliases; i++) {
527: free(options->aliases1[i]);
528: free(options->aliases2[i]);
529: }
530: free(options);
531: options = 0;
532: return(0);
533: }
535: #undef __FUNCT__
537: /*@C
538: PetscOptionsSetValue - Sets an option name-value pair in the options
539: database, overriding whatever is already present.
541: Not collective, but setting values on certain processors could cause problems
542: for parallel objects looking for options.
544: Input Parameters:
545: + name - name of option, this SHOULD have the - prepended
546: - value - the option value (not used for all options)
548: Level: intermediate
550: Note:
551: Only some options have values associated with them, such as
552: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
554: Concepts: options database^adding option
556: .seealso: PetscOptionsInsert()
557: @*/
558: int PetscOptionsSetValue(const char iname[],const char value[])
559: {
560: int len,N,n,i,ierr;
561: char **names,*name = (char*)iname;
562: PetscTruth gt,match;
565: if (!options) {PetscOptionsInsert(0,0,0);}
567: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
568: PetscStrcmp(name,"-h",&match);
569: if (match) name = "-help";
571: name++;
572: /* first check against aliases */
573: N = options->Naliases;
574: for (i=0; i<N; i++) {
575: PetscStrcmp(options->aliases1[i],name,&match);
576: if (match) {
577: name = options->aliases2[i];
578: break;
579: }
580: }
582: N = options->N;
583: n = N;
584: names = options->names;
585:
586: for (i=0; i<N; i++) {
587: PetscStrcmp(names[i],name,&match);
588: ierr = PetscStrgrt(names[i],name,>);
589: if (match) {
590: if (options->values[i]) free(options->values[i]);
591: PetscStrlen(value,&len);
592: if (len) {
593: options->values[i] = (char*)malloc((len+1)*sizeof(char));
594: PetscStrcpy(options->values[i],value);
595: } else { options->values[i] = 0;}
596: return(0);
597: } else if (gt) {
598: n = i;
599: break;
600: }
601: }
602: if (N >= MAXOPTIONS) {
603: SETERRQ1(1,"No more room in option table, limit %d recompile n src/sys/src/objects/options.c with larger value for MAXOPTIONSn",MAXOPTIONS);
604: }
605: /* shift remaining values down 1 */
606: for (i=N; i>n; i--) {
607: names[i] = names[i-1];
608: options->values[i] = options->values[i-1];
609: options->used[i] = options->used[i-1];
610: }
611: /* insert new name and value */
612: PetscStrlen(name,&len);
613: names[n] = (char*)malloc((len+1)*sizeof(char));
614: PetscStrcpy(names[n],name);
615: if (value) {
616: PetscStrlen(value,&len);
617: options->values[n] = (char*)malloc((len+1)*sizeof(char));
618: PetscStrcpy(options->values[n],value);
619: } else {options->values[n] = 0;}
620: options->used[n] = 0;
621: options->N++;
622: return(0);
623: }
625: #undef __FUNCT__
627: /*@C
628: PetscOptionsClearValue - Clears an option name-value pair in the options
629: database, overriding whatever is already present.
631: Not Collective, but setting values on certain processors could cause problems
632: for parallel objects looking for options.
634: Input Parameter:
635: . name - name of option, this SHOULD have the - prepended
637: Level: intermediate
639: Concepts: options database^removing option
640: .seealso: PetscOptionsInsert()
641: @*/
642: int PetscOptionsClearValue(const char iname[])
643: {
644: int N,n,i,ierr;
645: char **names,*name=(char*)iname;
646: PetscTruth gt,match;
649: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
650: if (!options) {PetscOptionsInsert(0,0,0);}
652: name++;
654: N = options->N; n = 0;
655: names = options->names;
656:
657: for (i=0; i<N; i++) {
658: ierr = PetscStrcmp(names[i],name,&match);
659: ierr = PetscStrgrt(names[i],name,>);
660: if (match) {
661: if (options->values[i]) free(options->values[i]);
662: break;
663: } else if (gt) {
664: return(0); /* it was not listed */
665: }
666: n++;
667: }
668: if (n == N) return(0); /* it was not listed */
670: /* shift remaining values down 1 */
671: for (i=n; i<N-1; i++) {
672: names[i] = names[i+1];
673: options->values[i] = options->values[i+1];
674: options->used[i] = options->used[i+1];
675: }
676: options->N--;
677: return(0);
678: }
680: #undef __FUNCT__
682: /*@C
683: PetscOptionsReject - Generates an error if a certain option is given.
685: Not Collective, but setting values on certain processors could cause problems
686: for parallel objects looking for options.
688: Input Parameters:
689: + name - the option one is seeking
690: - mess - error message (may be PETSC_NULL)
692: Level: advanced
694: Concepts: options database^rejecting option
696: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
697: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
698: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
699: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
700: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
701: PetscOptionsList(), PetscOptionsEList()
702: @*/
703: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
704: {
705: int ierr,len,n = options->Naliases;
706: char *newname = (char *)inewname,*oldname = (char*)ioldname;
709: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
710: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
711: if (n >= MAXALIASES) {
712: 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);
713: }
715: newname++; oldname++;
716: PetscStrlen(newname,&len);
717: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
718: PetscStrcpy(options->aliases1[n],newname);
719: PetscStrlen(oldname,&len);
720: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
721: PetscStrcpy(options->aliases2[n],oldname);
722: options->Naliases++;
723: return(0);
724: }
726: #undef __FUNCT__
728: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
729: {
730: int i,N,ierr,len;
731: char **names,tmp[256];
732: PetscTruth match;
735: if (!options) {PetscOptionsInsert(0,0,0);}
736: N = options->N;
737: names = options->names;
739: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
741: /* append prefix to name */
742: if (pre) {
743: PetscStrncpy(tmp,pre,256);
744: PetscStrlen(tmp,&len);
745: PetscStrncat(tmp,name+1,256-len-1);
746: } else {
747: PetscStrncpy(tmp,name+1,256);
748: }
750: /* slow search */
751: *flg = PETSC_FALSE;
752: for (i=0; i<N; i++) {
753: PetscStrcmp(names[i],tmp,&match);
754: if (match) {
755: *value = options->values[i];
756: options->used[i]++;
757: *flg = PETSC_TRUE;
758: break;
759: }
760: }
761: return(0);
762: }
764: #undef __FUNCT__
766: /*@C
767: PetscOptionsReject - Generates an error if a certain option is given.
769: Not Collective, but setting values on certain processors could cause problems
770: for parallel objects looking for options.
772: Input Parameters:
773: + name - the option one is seeking
774: - mess - error message (may be PETSC_NULL)
776: Level: advanced
778: Concepts: options database^rejecting option
780: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
781: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
782: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
783: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
784: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
785: PetscOptionsList(), PetscOptionsEList()
786: @*/
787: int PetscOptionsReject(const char name[],const char mess[])
788: {
789: int ierr;
790: PetscTruth flag;
793: PetscOptionsHasName(PETSC_NULL,name,&flag);
794: if (flag) {
795: if (mess) {
796: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
797: } else {
798: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
799: }
800: }
801: return(0);
802: }
804: #undef __FUNCT__
806: /*@C
807: PetscOptionsHasName - Determines whether a certain option is given in the database.
809: Not Collective
811: Input Parameters:
812: + name - the option one is seeking
813: - pre - string to prepend to the name or PETSC_NULL
815: Output Parameters:
816: . flg - PETSC_TRUE if found else PETSC_FALSE.
818: Level: beginner
820: Concepts: options database^has option name
822: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
823: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
824: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
825: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
826: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
827: PetscOptionsList(), PetscOptionsEList()
828: @*/
829: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
830: {
831: char *value;
832: int ierr;
833: PetscTruth isfalse,flag;
836: PetscOptionsFindPair_Private(pre,name,&value,&flag);
838: /* remove if turned off */
839: if (flag) {
840: PetscStrcmp(value,"FALSE",&isfalse);
841: if (isfalse) flag = PETSC_FALSE;
842: PetscStrcmp(value,"NO",&isfalse);
843: if (isfalse) flag = PETSC_FALSE;
844: PetscStrcmp(value,"0",&isfalse);
845: if (isfalse) flag = PETSC_FALSE;
846: PetscStrcmp(value,"false",&isfalse);
847: if (isfalse) flag = PETSC_FALSE;
848: PetscStrcmp(value,"no",&isfalse);
849: }
850: if (flg) *flg = flag;
852: return(0);
853: }
855: #undef __FUNCT__
857: /*@C
858: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
860: Not Collective
862: Input Parameters:
863: + pre - the string to prepend to the name or PETSC_NULL
864: - name - the option one is seeking
866: Output Parameter:
867: + ivalue - the integer value to return
868: - flg - PETSC_TRUE if found, else PETSC_FALSE
870: Level: beginner
872: Concepts: options database^has int
874: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
875: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
876: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
877: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
878: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
879: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
880: PetscOptionsList(), PetscOptionsEList()
881: @*/
882: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
883: {
884: char *value;
885: int ierr;
886: PetscTruth flag;
890: PetscOptionsFindPair_Private(pre,name,&value,&flag);
891: if (flag) {
892: if (!value) {if (flg) *flg = PETSC_FALSE;}
893: else {
894: if (flg) *flg = PETSC_TRUE;
895: PetscOptionsAtoi(value,ivalue);
896: }
897: } else {
898: if (flg) *flg = PETSC_FALSE;
899: }
900: return(0);
901: }
903: #undef __FUNCT__
905: /*@C
906: PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular
907: option in the database.
909: Not Collective
911: Input Parameters:
912: + pre - the string to prepend to the name or PETSC_NULL
913: - name - the option one is seeking
915: Output Parameter:
916: + ivalue - the logical value to return
917: - flg - PETSC_TRUE if found, else PETSC_FALSE
919: Level: beginner
921: Notes:
922: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
923: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
925: Concepts: options database^has logical
927: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
928: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsLogical(),
929: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
930: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
931: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
932: PetscOptionsList(), PetscOptionsEList()
933: @*/
934: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
935: {
936: char *value;
937: PetscTruth flag,istrue,isfalse;
938: int ierr;
942: PetscOptionsFindPair_Private(pre,name,&value,&flag);
943: if (flag) {
944: if (flg) *flg = PETSC_TRUE;
945: if (!value) {
946: *ivalue = PETSC_TRUE;
947: } else {
948: *ivalue = PETSC_TRUE;
949: PetscStrcmp(value,"TRUE",&istrue);
950: if (istrue) return(0);
951: PetscStrcmp(value,"YES",&istrue);
952: if (istrue) return(0);
953: PetscStrcmp(value,"YES",&istrue);
954: if (istrue) return(0);
955: PetscStrcmp(value,"1",&istrue);
956: if (istrue) return(0);
957: PetscStrcmp(value,"true",&istrue);
958: if (istrue) return(0);
959: PetscStrcmp(value,"yes",&istrue);
960: if (istrue) return(0);
961: PetscStrcmp(value,"on",&istrue);
962: if (istrue) return(0);
964: *ivalue = PETSC_FALSE;
965: PetscStrcmp(value,"FALSE",&isfalse);
966: if (isfalse) return(0);
967: PetscStrcmp(value,"NO",&isfalse);
968: if (isfalse) return(0);
969: PetscStrcmp(value,"0",&isfalse);
970: if (isfalse) return(0);
971: PetscStrcmp(value,"false",&isfalse);
972: if (isfalse) return(0);
973: PetscStrcmp(value,"no",&isfalse);
974: if (isfalse) return(0);
975: PetscStrcmp(value,"off",&isfalse);
976: if (isfalse) return(0);
978: SETERRQ1(1,"Unknown logical value: %s",value);
979: }
980: } else {
981: if (flg) *flg = PETSC_FALSE;
982: }
983: return(0);
984: }
986: #undef __FUNCT__
988: /*@C
989: PetscOptionsGetReal - Gets the double precision value for a particular
990: option in the database.
992: Not Collective
994: Input Parameters:
995: + pre - string to prepend to each name or PETSC_NULL
996: - name - the option one is seeking
998: Output Parameter:
999: + dvalue - the double value to return
1000: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1002: Level: beginner
1004: Concepts: options database^has double
1006: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1007: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
1008: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1009: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1010: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1011: PetscOptionsList(), PetscOptionsEList()
1012: @*/
1013: int PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1014: {
1015: char *value;
1016: int ierr;
1017: PetscTruth flag;
1021: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1022: if (flag) {
1023: if (!value) {if (flg) *flg = PETSC_FALSE;}
1024: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1025: } else {
1026: if (flg) *flg = PETSC_FALSE;
1027: }
1028: return(0);
1029: }
1031: #undef __FUNCT__
1033: /*@C
1034: PetscOptionsGetScalar - Gets the scalar value for a particular
1035: option in the database.
1037: Not Collective
1039: Input Parameters:
1040: + pre - string to prepend to each name or PETSC_NULL
1041: - name - the option one is seeking
1043: Output Parameter:
1044: + dvalue - the double value to return
1045: - flg - PETSC_TRUE if found, else PETSC_FALSE
1047: Level: beginner
1049: Usage:
1050: A complex number 2+3i can be specified as 2,3 at the command line.
1051: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1053: Concepts: options database^has scalar
1055: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1056: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1057: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1058: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1059: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1060: PetscOptionsList(), PetscOptionsEList()
1061: @*/
1062: int PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1063: {
1064: char *value;
1065: PetscTruth flag;
1066: int ierr;
1070: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1071: if (flag) {
1072: if (!value) {
1073: if (flg) *flg = PETSC_FALSE;
1074: } else {
1075: #if !defined(PETSC_USE_COMPLEX)
1076: PetscOptionsAtod(value,dvalue);
1077: #else
1078: PetscReal re=0.0,im=0.0;
1079: PetscToken *token;
1080: char *tvalue = 0;
1082: PetscTokenCreate(value,',',&token);
1083: PetscTokenFind(token,&tvalue);
1084: if (!tvalue) { SETERRQ(1,"unknown string specifiedn"); }
1085: ierr = PetscOptionsAtod(tvalue,&re);
1086: ierr = PetscTokenFind(token,&tvalue);
1087: if (!tvalue) { /* Unknown separator used. using only real value */
1088: *dvalue = re;
1089: } else {
1090: ierr = PetscOptionsAtod(tvalue,&im);
1091: *dvalue = re + PETSC_i*im;
1092: }
1093: ierr = PetscTokenDestroy(token);
1094: #endif
1095: if (flg) *flg = PETSC_TRUE;
1096: }
1097: } else { /* flag */
1098: if (flg) *flg = PETSC_FALSE;
1099: }
1100: return(0);
1101: }
1103: #undef __FUNCT__
1105: /*@C
1106: PetscOptionsGetRealArray - Gets an array of double precision values for a
1107: particular option in the database. The values must be separated with
1108: commas with no intervening spaces.
1110: Not Collective
1112: Input Parameters:
1113: + pre - string to prepend to each name or PETSC_NULL
1114: . name - the option one is seeking
1115: - nmax - maximum number of values to retrieve
1117: Output Parameters:
1118: + dvalue - the double value to return
1119: . nmax - actual number of values retreived
1120: - flg - PETSC_TRUE if found, else PETSC_FALSE
1122: Level: beginner
1124: Concepts: options database^array of doubles
1126: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1127: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
1128: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1129: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1130: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1131: PetscOptionsList(), PetscOptionsEList()
1132: @*/
1133: int PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],int *nmax,PetscTruth *flg)
1134: {
1135: char *value;
1136: int n = 0,ierr;
1137: PetscTruth flag;
1138: PetscToken *token;
1142: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1143: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1144: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1146: if (flg) *flg = PETSC_TRUE;
1148: PetscTokenCreate(value,',',&token);
1149: PetscTokenFind(token,&value);
1150: while (n < *nmax) {
1151: if (!value) break;
1152: PetscOptionsAtod(value,dvalue++);
1153: PetscTokenFind(token,&value);
1154: n++;
1155: }
1156: PetscTokenDestroy(token);
1157: *nmax = n;
1158: return(0);
1159: }
1161: #undef __FUNCT__
1163: /*@C
1164: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1165: option in the database. The values must be separated with commas with
1166: 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 Parameter:
1176: + dvalue - the integer values 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 ints
1184: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1185: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1186: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1187: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1188: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1189: PetscOptionsList(), PetscOptionsEList()
1190: @*/
1191: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1192: {
1193: char *value;
1194: int n = 0,ierr;
1195: PetscTruth flag;
1196: PetscToken *token;
1200: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1201: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1202: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1204: if (flg) *flg = PETSC_TRUE;
1206: PetscTokenCreate(value,',',&token);
1207: PetscTokenFind(token,&value);
1208: while (n < *nmax) {
1209: if (!value) break;
1210: ierr = PetscOptionsAtoi(value,dvalue);
1211: dvalue++;
1212: ierr = PetscTokenFind(token,&value);
1213: n++;
1214: }
1215: ierr = PetscTokenDestroy(token);
1216: *nmax = n;
1217: return(0);
1218: }
1220: #undef __FUNCT__
1222: /*@C
1223: PetscOptionsGetString - Gets the string value for a particular option in
1224: the database.
1226: Not Collective
1228: Input Parameters:
1229: + pre - string to prepend to name or PETSC_NULL
1230: . name - the option one is seeking
1231: - len - maximum string length
1233: Output Parameters:
1234: + string - location to copy string
1235: - flg - PETSC_TRUE if found, else PETSC_FALSE
1237: Level: beginner
1239: Fortran Note:
1240: The Fortran interface is slightly different from the C/C++
1241: interface (len is not used). Sample usage in Fortran follows
1242: .vb
1243: character *20 string
1244: integer flg, ierr
1245: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1246: .ve
1248: Concepts: options database^string
1250: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1251: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1252: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1253: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1254: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1255: PetscOptionsList(), PetscOptionsEList()
1256: @*/
1257: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1258: {
1259: char *value;
1260: int ierr;
1261: PetscTruth flag;
1265: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1266: if (!flag) {
1267: if (flg) *flg = PETSC_FALSE;
1268: } else {
1269: if (flg) *flg = PETSC_TRUE;
1270: if (value) {
1271: PetscStrncpy(string,value,len);
1272: } else {
1273: PetscMemzero(string,len);
1274: }
1275: }
1276: return(0);
1277: }
1279: #undef __FUNCT__
1281: /*@C
1282: PetscOptionsGetStringArray - Gets an array of string values for a particular
1283: option in the database. The values must be separated with commas with
1284: no intervening spaces.
1286: Not Collective
1288: Input Parameters:
1289: + pre - string to prepend to name or PETSC_NULL
1290: . name - the option one is seeking
1291: - nmax - maximum number of strings
1293: Output Parameter:
1294: + strings - location to copy strings
1295: - flg - PETSC_TRUE if found, else PETSC_FALSE
1297: Level: beginner
1299: Notes:
1300: The user should pass in an array of pointers to char, to hold all the
1301: strings returned by this function.
1303: The user is responsible for deallocating the strings that are
1304: returned. The Fortran interface for this routine is not supported.
1306: Contributed by Matthew Knepley.
1308: Concepts: options database^array of strings
1310: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1311: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1312: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1313: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1314: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1315: PetscOptionsList(), PetscOptionsEList()
1316: @*/
1317: int PetscOptionsGetStringArray(const char pre[],const char name[],char **strings,int *nmax,PetscTruth *flg)
1318: {
1319: char *value;
1320: int len,n,ierr;
1321: PetscTruth flag;
1322: PetscToken *token;
1323:
1326: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1327: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1328: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1329: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1330: if (flg) *flg = PETSC_TRUE;
1332: PetscTokenCreate(value,',',&token);
1333: PetscTokenFind(token,&value);
1334: n = 0;
1335: while (n < *nmax) {
1336: if (!value) break;
1337: PetscStrlen(value,&len);
1338: PetscMalloc((len+1)*sizeof(char),&strings[n]);
1339: PetscStrcpy(strings[n],value);
1340: PetscTokenFind(token,&value);
1341: n++;
1342: }
1343: PetscTokenDestroy(token);
1344: *nmax = n;
1345: return(0);
1346: }
1348: #undef __FUNCT__
1350: /*@C
1351: PetscOptionsAllUsed - Returns a count of the number of options in the
1352: database that have never been selected.
1354: Not Collective
1356: Output Parameter:
1357: . N - count of options not used
1359: Level: advanced
1361: .seealso: PetscOptionsPrint()
1362: @*/
1363: int PetscOptionsAllUsed(int *N)
1364: {
1365: int i,n = 0;
1368: for (i=0; i<options->N; i++) {
1369: if (!options->used[i]) { n++; }
1370: }
1371: *N = n;
1372: return(0);
1373: }
1375: #undef __FUNCT__
1377: /*@
1378: PetscOptionsLeft - Prints to screen any options that were set and never used.
1380: Not collective
1382: Options Database Key:
1383: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1385: Level: advanced
1387: .seealso: PetscOptionsAllUsed()
1388: @*/
1389: int PetscOptionsLeft(void)
1390: {
1391: int i,ierr;
1394: for (i=0; i<options->N; i++) {
1395: if (!options->used[i]) {
1396: if (options->values[i]) {
1397: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %sn",options->names[i],options->values[i]);
1398: } else {
1399: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value n",options->names[i]);
1400: }
1401: }
1402: }
1403: return(0);
1404: }
1406: /*
1407: PetscOptionsCreate - Creates the empty options database.
1409: */
1410: #undef __FUNCT__
1412: int PetscOptionsCreate(void)
1413: {
1417: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1418: ierr = PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1419: options->namegiven = PETSC_FALSE;
1420: options->N = 0;
1421: options->Naliases = 0;
1422: return(0);
1423: }