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: #ifndef MAXPATHLEN
24: #define MAXPATHLEN 1024
25: #endif
27: /*
28: For simplicity, we use a static size database
29: */
30: #define MAXOPTIONS 256
31: #define MAXALIASES 25
33: typedef struct {
34: int N,argc,Naliases;
35: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
36: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
37: int used[MAXOPTIONS];
38: PetscTruth namegiven;
39: char programname[MAXPATHLEN]; /* HP includes entire path in name */
40: } PetscOptionsTable;
42: static PetscOptionsTable *options = 0;
44: int PetscOptionsAtoi(const char name[],int *a)
45: {
46: int i,ierr,len;
47: PetscTruth decide,tdefault,mouse;
50: PetscStrlen(name,&len);
51: if (!len) SETERRQ(1,"character string of length zero has no numerical value");
53: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
54: if (!tdefault) {
55: PetscStrcasecmp(name,"DEFAULT",&tdefault);
56: }
57: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
58: if (!decide) {
59: PetscStrcasecmp(name,"DECIDE",&decide);
60: }
61: PetscStrcasecmp(name,"mouse",&mouse);
63: if (tdefault) {
64: *a = PETSC_DEFAULT;
65: } else if (decide) {
66: *a = PETSC_DECIDE;
67: } else if (mouse) {
68: *a = -1;
69: } else {
70: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
71: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
72: }
73: for (i=1; i<len; i++) {
74: if (name[i] < '0' || name[i] > '9') {
75: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
76: }
77: }
78: *a = atoi(name);
79: }
80: return(0);
81: }
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: /*@C
115: PetscGetProgramName - Gets the name of the running program.
117: Not Collective
119: Input Parameter:
120: . len - length of the string name
122: Output Parameter:
123: . name - the name of the running program
125: Level: advanced
127: Notes:
128: The name of the program is copied into the user-provided character
129: array of length len. On some machines the program name includes
130: its entire path, so one should generally set len >= MAXPATHLEN.
131: @*/
132: int PetscGetProgramName(char name[],int len)
133: {
137: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
138: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
139: PetscStrncpy(name,options->programname,len);
140: return(0);
141: }
143: int PetscSetProgramName(const char name[])
144: {
148: options->namegiven = PETSC_TRUE;
149: ierr = PetscStrncpy(options->programname,name,MAXPATHLEN);
150: return(0);
151: }
153: /*@C
154: PetscOptionsInsertString - Inserts options into the database from a string
156: Not collective: but only processes that call this routine will set the options
157: included in the file
159: Input Parameter:
160: . in_str - string that contains options seperated by blanks
163: Level: intermediate
165: Contributed by Boyana Norris
167: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
168: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
169: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
170: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
171: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
172: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
174: @*/
175: int PetscOptionsInsertString(const char* in_str)
176: {
177: char *str,*first,*second,*third,*final;
178: int len,ierr;
179: PetscToken *token;
182: PetscStrlen(in_str,&len);
183: PetscMalloc(len,&str);
184: PetscStrcpy(str, in_str);
186: PetscTokenCreate(str,' ',&token);
187: PetscTokenFind(token,&first);
188: PetscTokenFind(token,&second);
189: if (first && first[0] == '-') {
190: if (second) {final = second;} else {final = first;}
191: PetscStrlen(final,&len);
192: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
193: len--; final[len] = 0;
194: }
195: PetscOptionsSetValue(first,second);
196: } else if (first) {
197: PetscTruth match;
198:
199: PetscStrcmp(first,"alias",&match);
200: if (match) {
201: PetscTokenFind(token,&third);
202: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
203: PetscStrlen(third,&len);
204: if (third[len-1] == 'n') third[len-1] = 0;
205: PetscOptionsSetAlias(second,third);
206: }
207: }
208: PetscTokenDestroy(token);
209: PetscFree(str);
210:
211: return(0);
212: }
214: /*@C
215: PetscOptionsInsertFile - Inserts options into the database from a file.
217: Not collective: but only processes that call this routine will set the options
218: included in the file
220: Input Parameter:
221: . file - name of file
224: Level: intermediate
226: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
227: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
228: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
229: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
230: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
231: PetscOptionsList(), PetscOptionsEList()
233: @*/
234: int PetscOptionsInsertFile(const char file[])
235: {
236: char string[128],fname[256],*first,*second,*third,*final;
237: int len,ierr,i,startIndex;
238: FILE *fd;
239: PetscToken *token;
242: PetscFixFilename(file,fname);
243: fd = fopen(fname,"r");
244: if (fd) {
245: while (fgets(string,128,fd)) {
246: /* Comments are indicated by #, ! or % in the first column */
247: if (string[0] == '#') continue;
248: if (string[0] == '!') continue;
249: if (string[0] == '%') continue;
251: PetscStrlen(string,&len);
253: /* replace tabs, ^M with " " */
254: for (i=0; i<len; i++) {
255: if (string[i] == 't' || string[i] == 'r') {
256: string[i] = ' ';
257: }
258: }
259: for(startIndex = 0; startIndex < len-1; startIndex++) {
260: if (string[startIndex] != ' ') break;
261: }
262: PetscTokenCreate(&string[startIndex],' ',&token);
263: PetscTokenFind(token,&first);
264: PetscTokenFind(token,&second);
265: if (first && first[0] == '-') {
266: if (second) {final = second;} else {final = first;}
267: PetscStrlen(final,&len);
268: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
269: len--; final[len] = 0;
270: }
271: PetscOptionsSetValue(first,second);
272: } else if (first) {
273: PetscTruth match;
275: PetscStrcmp(first,"alias",&match);
276: if (match) {
277: PetscTokenFind(token,&third);
278: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
279: PetscStrlen(third,&len);
280: if (third[len-1] == 'n') third[len-1] = 0;
281: PetscOptionsSetAlias(second,third);
282: }
283: }
284: PetscTokenDestroy(token);
285: }
286: fclose(fd);
287: }
288: return(0);
289: }
291: /*@C
292: PetscOptionsInsert - Inserts into the options database from the command line,
293: the environmental variable and a file.
295: Input Parameters:
296: + argc - count of number of command line arguments
297: . args - the command line arguments
298: - file - optional filename, defaults to ~username/.petscrc
300: Note:
301: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
302: the user does not typically need to call this routine. PetscOptionsInsert()
303: can be called several times, adding additional entries into the database.
305: Level: advanced
307: Concepts: options database^adding
309: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
310: @*/
311: int PetscOptionsInsert(int *argc,char ***args,const char file[])
312: {
313: int ierr,rank;
314: char pfile[256];
315: PetscToken *token;
318: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
320: options->argc = (argc) ? *argc : 0;
321: options->args = (args) ? *args : 0;
323: if (file) {
324: PetscOptionsInsertFile(file);
325: } else {
326: PetscGetHomeDirectory(pfile,240);
327: PetscStrcat(pfile,"/.petscrc");
328: PetscOptionsInsertFile(pfile);
329: }
331: /* insert environmental options */
332: {
333: char *eoptions = 0,*second,*first;
334: int len=0;
335: if (!rank) {
336: eoptions = (char*)getenv("PETSC_OPTIONS");
337: ierr = PetscStrlen(eoptions,&len);
338: ierr = MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
339: } else {
340: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
341: if (len) {
342: PetscMalloc((len+1)*sizeof(char*),&eoptions);
343: }
344: }
345: if (len) {
346: ierr = MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
347: eoptions[len] = 0;
348: ierr = PetscTokenCreate(eoptions,' ',&token);
349: ierr = PetscTokenFind(token,&first);
350: while (first) {
351: if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
352: PetscTokenFind(token,&second);
353: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
354: PetscOptionsSetValue(first,(char *)0);
355: first = second;
356: } else {
357: PetscOptionsSetValue(first,second);
358: PetscTokenFind(token,&first);
359: }
360: }
361: PetscTokenDestroy(token);
362: if (rank) {PetscFree(eoptions);}
363: }
364: }
366: /* insert command line options */
367: if (argc && args && *argc) {
368: int left = *argc - 1;
369: char **eargs = *args + 1;
370: PetscTruth isoptions_file,isp4,tisp4;
372: while (left) {
373: PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
374: PetscStrcmp(eargs[0],"-p4pg",&isp4);
375: PetscStrcmp(eargs[0],"-p4wd",&tisp4);
376: isp4 = (PetscTruth) (isp4 || tisp4);
377: PetscStrcmp(eargs[0],"-np",&tisp4);
378: isp4 = (PetscTruth) (isp4 || tisp4);
379: PetscStrcmp(eargs[0],"-p4amslave",&tisp4);
381: if (eargs[0][0] != '-') {
382: eargs++; left--;
383: } else if (isoptions_file) {
384: PetscOptionsInsertFile(eargs[1]);
385: eargs += 2; left -= 2;
387: /*
388: These are "bad" options that MPICH, etc put on the command line
389: we strip them out here.
390: */
391: } else if (tisp4) {
392: eargs += 1; left -= 1;
393: } else if (isp4) {
394: eargs += 2; left -= 2;
395: } else if ((left < 2) || ((eargs[1][0] == '-') &&
396: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
397: PetscOptionsSetValue(eargs[0],PETSC_NULL);
398: eargs++; left--;
399: } else {
400: PetscOptionsSetValue(eargs[0],eargs[1]);
401: eargs += 2; left -= 2;
402: }
403: }
404: }
405: return(0);
406: }
408: /*@C
409: PetscOptionsPrint - Prints the options that have been loaded. This is
410: useful for debugging purposes.
412: Collective on PETSC_COMM_WORLD
414: Input Parameter:
415: . FILE fd - location to print options (usually stdout or stderr)
417: Options Database Key:
418: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
420: Level: advanced
422: Concepts: options database^printing
424: .seealso: PetscOptionsAllUsed()
425: @*/
426: int PetscOptionsPrint(FILE *fd)
427: {
428: int i,ierr;
431: if (!fd) fd = stdout;
432: if (!options) {PetscOptionsInsert(0,0,0);}
433: for (i=0; i<options->N; i++) {
434: if (options->values[i]) {
435: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %sn",options->names[i],options->values[i]);
436: } else {
437: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%sn",options->names[i]);
438: }
439: }
440: return(0);
441: }
443: /*@C
444: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
446: Not Collective
448: Output Parameter:
449: . copts - pointer where string pointer is stored
451: Level: advanced
453: Concepts: options database^listing
455: .seealso: PetscOptionsAllUsed(), PetscOptionsPrintf()
456: @*/
457: int PetscOptionsGetAll(char *copts[])
458: {
459: int i,ierr,len = 1,lent;
460: char *coptions;
463: if (!options) {PetscOptionsInsert(0,0,0);}
465: /* count the length of the required string */
466: for (i=0; i<options->N; i++) {
467: PetscStrlen(options->names[i],&lent);
468: len += 1 + lent;
469: if (options->values[i]) {
470: PetscStrlen(options->values[i],&lent);
471: len += 1 + lent;
472: }
473: }
474: PetscMalloc(len*sizeof(char),&coptions);
475: coptions[0] = 0;
476: for (i=0; i<options->N; i++) {
477: PetscStrcat(coptions,"-");
478: PetscStrcat(coptions,options->names[i]);
479: PetscStrcat(coptions," ");
480: if (options->values[i]) {
481: PetscStrcat(coptions,options->values[i]);
482: PetscStrcat(coptions," ");
483: }
484: }
485: *copts = coptions;
486: return(0);
487: }
489: /*@C
490: PetscOptionsDestroy - Destroys the option database.
492: Note:
493: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
494: typically does not need to call this routine.
496: Level: developer
498: .seealso: PetscOptionsInsert()
499: @*/
500: int PetscOptionsDestroy(void)
501: {
502: int i;
505: if (!options) return(0);
506: for (i=0; i<options->N; i++) {
507: if (options->names[i]) free(options->names[i]);
508: if (options->values[i]) free(options->values[i]);
509: }
510: for (i=0; i<options->Naliases; i++) {
511: free(options->aliases1[i]);
512: free(options->aliases2[i]);
513: }
514: free(options);
515: options = 0;
516: return(0);
517: }
519: /*@C
520: PetscOptionsSetValue - Sets an option name-value pair in the options
521: database, overriding whatever is already present.
523: Not collective, but setting values on certain processors could cause problems
524: for parallel objects looking for options.
526: Input Parameters:
527: + name - name of option, this SHOULD have the - prepended
528: - value - the option value (not used for all options)
530: Level: intermediate
532: Note:
533: Only some options have values associated with them, such as
534: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
536: Concepts: options database^adding option
538: .seealso: PetscOptionsInsert()
539: @*/
540: int PetscOptionsSetValue(const char iname[],const char value[])
541: {
542: int len,N,n,i,ierr;
543: char **names,*name = (char*)iname;
544: PetscTruth gt,match;
547: if (!options) {PetscOptionsInsert(0,0,0);}
549: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
550: PetscStrcmp(name,"-h",&match);
551: if (match) name = "-help";
553: name++;
554: /* first check against aliases */
555: N = options->Naliases;
556: for (i=0; i<N; i++) {
557: PetscStrcmp(options->aliases1[i],name,&match);
558: if (match) {
559: name = options->aliases2[i];
560: break;
561: }
562: }
564: N = options->N;
565: n = N;
566: names = options->names;
567:
568: for (i=0; i<N; i++) {
569: PetscStrcmp(names[i],name,&match);
570: ierr = PetscStrgrt(names[i],name,>);
571: if (match) {
572: if (options->values[i]) free(options->values[i]);
573: PetscStrlen(value,&len);
574: if (len) {
575: options->values[i] = (char*)malloc((len+1)*sizeof(char));
576: PetscStrcpy(options->values[i],value);
577: } else { options->values[i] = 0;}
578: return(0);
579: } else if (gt) {
580: n = i;
581: break;
582: }
583: }
584: if (N >= MAXOPTIONS) {
585: SETERRQ1(1,"No more room in option table, limit %d recompile n src/sys/src/objects/options.c with larger value for MAXOPTIONSn",MAXOPTIONS);
586: }
587: /* shift remaining values down 1 */
588: for (i=N; i>n; i--) {
589: names[i] = names[i-1];
590: options->values[i] = options->values[i-1];
591: options->used[i] = options->used[i-1];
592: }
593: /* insert new name and value */
594: PetscStrlen(name,&len);
595: names[n] = (char*)malloc((len+1)*sizeof(char));
596: PetscStrcpy(names[n],name);
597: if (value) {
598: PetscStrlen(value,&len);
599: options->values[n] = (char*)malloc((len+1)*sizeof(char));
600: PetscStrcpy(options->values[n],value);
601: } else {options->values[n] = 0;}
602: options->used[n] = 0;
603: options->N++;
604: return(0);
605: }
607: /*@C
608: PetscOptionsClearValue - Clears an option name-value pair in the options
609: database, overriding whatever is already present.
611: Not Collective, but setting values on certain processors could cause problems
612: for parallel objects looking for options.
614: Input Parameter:
615: . name - name of option, this SHOULD have the - prepended
617: Level: intermediate
619: Concepts: options database^removing option
620: .seealso: PetscOptionsInsert()
621: @*/
622: int PetscOptionsClearValue(const char iname[])
623: {
624: int N,n,i,ierr;
625: char **names,*name=(char*)iname;
626: PetscTruth gt,match;
629: if (!options) {PetscOptionsInsert(0,0,0);}
631: name++;
633: N = options->N; n = 0;
634: names = options->names;
635:
636: for (i=0; i<N; i++) {
637: PetscStrcmp(names[i],name,&match);
638: ierr = PetscStrgrt(names[i],name,>);
639: if (match) {
640: if (options->values[i]) free(options->values[i]);
641: break;
642: } else if (gt) {
643: return(0); /* it was not listed */
644: }
645: n++;
646: }
647: /* shift remaining values down 1 */
648: for (i=n; i<N-1; i++) {
649: names[i] = names[i+1];
650: options->values[i] = options->values[i+1];
651: options->used[i] = options->used[i+1];
652: }
653: options->N--;
654: return(0);
655: }
657: /*@C
658: PetscOptionsReject - Generates an error if a certain option is given.
660: Not Collective, but setting values on certain processors could cause problems
661: for parallel objects looking for options.
663: Input Parameters:
664: + name - the option one is seeking
665: - mess - error message (may be PETSC_NULL)
667: Level: advanced
669: Concepts: options database^rejecting option
671: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
672: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
673: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
674: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
675: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
676: PetscOptionsList(), PetscOptionsEList()
677: @*/
678: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
679: {
680: int ierr,len,n = options->Naliases;
681: char *newname = (char *)inewname,*oldname = (char*)ioldname;
684: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
685: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
686: if (n >= MAXALIASES) {
687: 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);
688: }
690: newname++; oldname++;
691: PetscStrlen(newname,&len);
692: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
693: PetscStrcpy(options->aliases1[n],newname);
694: PetscStrlen(oldname,&len);
695: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
696: PetscStrcpy(options->aliases2[n],oldname);
697: options->Naliases++;
698: return(0);
699: }
701: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
702: {
703: int i,N,ierr,len;
704: char **names,tmp[256];
705: PetscTruth match;
708: if (!options) {PetscOptionsInsert(0,0,0);}
709: N = options->N;
710: names = options->names;
712: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
714: /* append prefix to name */
715: if (pre) {
716: PetscStrncpy(tmp,pre,256);
717: PetscStrlen(tmp,&len);
718: PetscStrncat(tmp,name+1,256-len-1);
719: } else {
720: PetscStrncpy(tmp,name+1,256);
721: }
723: /* slow search */
724: *flg = PETSC_FALSE;
725: for (i=0; i<N; i++) {
726: PetscStrcmp(names[i],tmp,&match);
727: if (match) {
728: *value = options->values[i];
729: options->used[i]++;
730: *flg = PETSC_TRUE;
731: break;
732: }
733: }
734: return(0);
735: }
737: /*@C
738: PetscOptionsReject - Generates an error if a certain option is given.
740: Not Collective, but setting values on certain processors could cause problems
741: for parallel objects looking for options.
743: Input Parameters:
744: + name - the option one is seeking
745: - mess - error message (may be PETSC_NULL)
747: Level: advanced
749: Concepts: options database^rejecting option
751: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
752: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
753: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
754: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
755: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
756: PetscOptionsList(), PetscOptionsEList()
757: @*/
758: int PetscOptionsReject(const char name[],const char mess[])
759: {
760: int ierr;
761: PetscTruth flag;
764: PetscOptionsHasName(PETSC_NULL,name,&flag);
765: if (flag) {
766: if (mess) {
767: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
768: } else {
769: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
770: }
771: }
772: return(0);
773: }
775: /*@C
776: PetscOptionsHasName - Determines whether a certain option is given in the database.
778: Not Collective
780: Input Parameters:
781: + name - the option one is seeking
782: - pre - string to prepend to the name or PETSC_NULL
784: Output Parameters:
785: . flg - PETSC_TRUE if found else PETSC_FALSE.
787: Level: beginner
789: Concepts: options database^has option name
791: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
792: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
793: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
794: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
795: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
796: PetscOptionsList(), PetscOptionsEList()
797: @*/
798: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
799: {
800: char *value;
801: int ierr;
802: PetscTruth isfalse,flag;
805: PetscOptionsFindPair_Private(pre,name,&value,&flag);
807: /* remove if turned off */
808: if (flag) {
809: PetscStrcmp(value,"FALSE",&isfalse);
810: if (isfalse) flag = PETSC_FALSE;
811: PetscStrcmp(value,"NO",&isfalse);
812: if (isfalse) flag = PETSC_FALSE;
813: PetscStrcmp(value,"0",&isfalse);
814: if (isfalse) flag = PETSC_FALSE;
815: PetscStrcmp(value,"false",&isfalse);
816: if (isfalse) flag = PETSC_FALSE;
817: PetscStrcmp(value,"no",&isfalse);
818: }
819: if (flg) *flg = flag;
821: return(0);
822: }
824: /*@C
825: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
827: Not Collective
829: Input Parameters:
830: + pre - the string to prepend to the name or PETSC_NULL
831: - name - the option one is seeking
833: Output Parameter:
834: + ivalue - the integer value to return
835: - flg - PETSC_TRUE if found, else PETSC_FALSE
837: Level: beginner
839: Concepts: options database^has int
841: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
842: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
843: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
844: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
845: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
846: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
847: PetscOptionsList(), PetscOptionsEList()
848: @*/
849: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
850: {
851: char *value;
852: int ierr;
853: PetscTruth flag;
857: PetscOptionsFindPair_Private(pre,name,&value,&flag);
858: if (flag) {
859: if (!value) {if (flg) *flg = PETSC_FALSE; *ivalue = 0;}
860: else {
861: if (flg) *flg = PETSC_TRUE;
862: PetscOptionsAtoi(value,ivalue);
863: }
864: } else {
865: if (flg) *flg = PETSC_FALSE;
866: }
867: return(0);
868: }
870: /*@C
871: PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular
872: option in the database.
874: Not Collective
876: Input Parameters:
877: + pre - the string to prepend to the name or PETSC_NULL
878: - name - the option one is seeking
880: Output Parameter:
881: + ivalue - the logical value to return
882: - flg - PETSC_TRUE if found, else PETSC_FALSE
884: Level: beginner
886: Notes:
887: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
888: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
890: Concepts: options database^has logical
892: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
893: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsLogical(),
894: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
895: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
896: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
897: PetscOptionsList(), PetscOptionsEList()
898: @*/
899: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
900: {
901: char *value;
902: PetscTruth flag,istrue,isfalse;
903: int ierr;
907: PetscOptionsFindPair_Private(pre,name,&value,&flag);
908: if (flag) {
909: if (flg) *flg = PETSC_TRUE;
910: if (!value) {
911: *ivalue = PETSC_TRUE;
912: } else {
913: *ivalue = PETSC_TRUE;
914: PetscStrcmp(value,"TRUE",&istrue);
915: if (istrue) return(0);
916: PetscStrcmp(value,"YES",&istrue);
917: if (istrue) return(0);
918: PetscStrcmp(value,"YES",&istrue);
919: if (istrue) return(0);
920: PetscStrcmp(value,"1",&istrue);
921: if (istrue) return(0);
922: PetscStrcmp(value,"true",&istrue);
923: if (istrue) return(0);
924: PetscStrcmp(value,"yes",&istrue);
925: if (istrue) return(0);
926: PetscStrcmp(value,"on",&istrue);
927: if (istrue) return(0);
929: *ivalue = PETSC_FALSE;
930: PetscStrcmp(value,"FALSE",&isfalse);
931: if (isfalse) return(0);
932: PetscStrcmp(value,"NO",&isfalse);
933: if (isfalse) return(0);
934: PetscStrcmp(value,"0",&isfalse);
935: if (isfalse) return(0);
936: PetscStrcmp(value,"false",&isfalse);
937: if (isfalse) return(0);
938: PetscStrcmp(value,"no",&isfalse);
939: if (isfalse) return(0);
940: PetscStrcmp(value,"off",&isfalse);
941: if (isfalse) return(0);
943: SETERRQ1(1,"Unknown logical value: %s",value);
944: }
945: } else {
946: if (flg) *flg = PETSC_FALSE;
947: }
948: return(0);
949: }
951: /*@C
952: PetscOptionsGetReal - Gets the double precision value for a particular
953: option in the database.
955: Not Collective
957: Input Parameters:
958: + pre - string to prepend to each name or PETSC_NULL
959: - name - the option one is seeking
961: Output Parameter:
962: + dvalue - the double value to return
963: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
965: Level: beginner
967: Concepts: options database^has double
969: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
970: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
971: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
972: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
973: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
974: PetscOptionsList(), PetscOptionsEList()
975: @*/
976: int PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
977: {
978: char *value;
979: int ierr;
980: PetscTruth flag;
984: PetscOptionsFindPair_Private(pre,name,&value,&flag);
985: if (flag) {
986: if (!value) {if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;}
987: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
988: } else {
989: if (flg) *flg = PETSC_FALSE;
990: }
991: return(0);
992: }
994: /*@C
995: PetscOptionsGetScalar - Gets the scalar value for a particular
996: option in the database.
998: Not Collective
1000: Input Parameters:
1001: + pre - string to prepend to each name or PETSC_NULL
1002: - name - the option one is seeking
1004: Output Parameter:
1005: + dvalue - the double value to return
1006: - flg - PETSC_TRUE if found, else PETSC_FALSE
1008: Level: beginner
1010: Usage:
1011: A complex number 2+3i can be specified as 2,3 at the command line.
1012: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1014: Concepts: options database^has scalar
1016: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1017: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1018: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1019: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1020: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1021: PetscOptionsList(), PetscOptionsEList()
1022: @*/
1023: int PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1024: {
1025: char *value;
1026: PetscTruth flag;
1027: int ierr;
1031: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1032: if (flag) {
1033: if (!value) {
1034: if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;
1035: } else {
1036: #if !defined(PETSC_USE_COMPLEX)
1037: PetscOptionsAtod(value,dvalue);
1038: #else
1039: PetscReal re=0.0,im=0.0;
1040: PetscToken *token;
1041: char *tvalue = 0;
1043: PetscTokenCreate(value,',',&token);
1044: PetscTokenFind(token,&tvalue);
1045: if (!tvalue) { SETERRQ(1,"unknown string specifiedn"); }
1046: ierr = PetscOptionsAtod(tvalue,&re);
1047: ierr = PetscTokenFind(token,&tvalue);
1048: if (!tvalue) { /* Unknown separator used. using only real value */
1049: *dvalue = re;
1050: } else {
1051: ierr = PetscOptionsAtod(tvalue,&im);
1052: *dvalue = re + PETSC_i*im;
1053: }
1054: ierr = PetscTokenDestroy(token);
1055: #endif
1056: if (flg) *flg = PETSC_TRUE;
1057: }
1058: } else { /* flag */
1059: if (flg) *flg = PETSC_FALSE;
1060: }
1061: return(0);
1062: }
1064: /*@C
1065: PetscOptionsGetRealArray - Gets an array of double precision values for a
1066: particular option in the database. The values must be separated with
1067: commas with no intervening spaces.
1069: Not Collective
1071: Input Parameters:
1072: + pre - string to prepend to each name or PETSC_NULL
1073: . name - the option one is seeking
1074: - nmax - maximum number of values to retrieve
1076: Output Parameters:
1077: + dvalue - the double value to return
1078: . nmax - actual number of values retreived
1079: - flg - PETSC_TRUE if found, else PETSC_FALSE
1081: Level: beginner
1083: Concepts: options database^array of doubles
1085: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1086: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
1087: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1088: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1089: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1090: PetscOptionsList(), PetscOptionsEList()
1091: @*/
1092: int PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],int *nmax,PetscTruth *flg)
1093: {
1094: char *value;
1095: int n = 0,ierr;
1096: PetscTruth flag;
1097: PetscToken *token;
1101: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1102: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1103: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1105: if (flg) *flg = PETSC_TRUE;
1107: PetscTokenCreate(value,',',&token);
1108: PetscTokenFind(token,&value);
1109: while (n < *nmax) {
1110: if (!value) break;
1111: PetscOptionsAtod(value,dvalue++);
1112: PetscTokenFind(token,&value);
1113: n++;
1114: }
1115: PetscTokenDestroy(token);
1116: *nmax = n;
1117: return(0);
1118: }
1120: /*@C
1121: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1122: option in the database. The values must be separated with commas with
1123: no intervening spaces.
1125: Not Collective
1127: Input Parameters:
1128: + pre - string to prepend to each name or PETSC_NULL
1129: . name - the option one is seeking
1130: - nmax - maximum number of values to retrieve
1132: Output Parameter:
1133: + dvalue - the integer values to return
1134: . nmax - actual number of values retreived
1135: - flg - PETSC_TRUE if found, else PETSC_FALSE
1137: Level: beginner
1139: Concepts: options database^array of ints
1141: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1142: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1143: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1144: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1145: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1146: PetscOptionsList(), PetscOptionsEList()
1147: @*/
1148: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1149: {
1150: char *value;
1151: int n = 0,ierr;
1152: PetscTruth flag;
1153: PetscToken *token;
1157: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1158: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1159: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1161: if (flg) *flg = PETSC_TRUE;
1163: PetscTokenCreate(value,',',&token);
1164: PetscTokenFind(token,&value);
1165: while (n < *nmax) {
1166: if (!value) break;
1167: ierr = PetscOptionsAtoi(value,dvalue);
1168: dvalue++;
1169: ierr = PetscTokenFind(token,&value);
1170: n++;
1171: }
1172: ierr = PetscTokenDestroy(token);
1173: *nmax = n;
1174: return(0);
1175: }
1177: /*@C
1178: PetscOptionsGetString - Gets the string value for a particular option in
1179: the database.
1181: Not Collective
1183: Input Parameters:
1184: + pre - string to prepend to name or PETSC_NULL
1185: . name - the option one is seeking
1186: - len - maximum string length
1188: Output Parameters:
1189: + string - location to copy string
1190: - flg - PETSC_TRUE if found, else PETSC_FALSE
1192: Level: beginner
1194: Fortran Note:
1195: The Fortran interface is slightly different from the C/C++
1196: interface (len is not used). Sample usage in Fortran follows
1197: .vb
1198: character *20 string
1199: integer flg, ierr
1200: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1201: .ve
1203: Concepts: options database^string
1205: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1206: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1207: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1208: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1209: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1210: PetscOptionsList(), PetscOptionsEList()
1211: @*/
1212: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1213: {
1214: char *value;
1215: int ierr;
1216: PetscTruth flag;
1220: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1221: if (!flag) {
1222: if (flg) *flg = PETSC_FALSE;
1223: } else {
1224: if (flg) *flg = PETSC_TRUE;
1225: if (value) {
1226: PetscStrncpy(string,value,len);
1227: } else {
1228: PetscMemzero(string,len);
1229: }
1230: }
1231: return(0);
1232: }
1234: /*@C
1235: PetscOptionsGetStringArray - Gets an array of string values for a particular
1236: option in the database. The values must be separated with commas with
1237: no intervening spaces.
1239: Not Collective
1241: Input Parameters:
1242: + pre - string to prepend to name or PETSC_NULL
1243: . name - the option one is seeking
1244: - nmax - maximum number of strings
1246: Output Parameter:
1247: + strings - location to copy strings
1248: - flg - PETSC_TRUE if found, else PETSC_FALSE
1250: Level: beginner
1252: Notes:
1253: The user should pass in an array of pointers to char, to hold all the
1254: strings returned by this function.
1256: The user is responsible for deallocating the strings that are
1257: returned. The Fortran interface for this routine is not supported.
1259: Contributed by Matthew Knepley.
1261: Concepts: options database^array of strings
1263: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1264: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1265: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1266: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1267: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1268: PetscOptionsList(), PetscOptionsEList()
1269: @*/
1270: int PetscOptionsGetStringArray(const char pre[],const char name[],char **strings,int *nmax,PetscTruth *flg)
1271: {
1272: char *value;
1273: int len,n,ierr;
1274: PetscTruth flag;
1275: PetscToken *token;
1276:
1279: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1280: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1281: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1282: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1283: if (flg) *flg = PETSC_TRUE;
1285: PetscTokenCreate(value,',',&token);
1286: PetscTokenFind(token,&value);
1287: n = 0;
1288: while (n < *nmax) {
1289: if (!value) break;
1290: PetscStrlen(value,&len);
1291: PetscMalloc((len+1)*sizeof(char),&strings[n]);
1292: PetscStrcpy(strings[n],value);
1293: PetscTokenFind(token,&value);
1294: n++;
1295: }
1296: PetscTokenDestroy(token);
1297: *nmax = n;
1298: return(0);
1299: }
1301: /*@C
1302: PetscOptionsAllUsed - Returns a count of the number of options in the
1303: database that have never been selected.
1305: Not Collective
1307: Output Parameter:
1308: . N - count of options not used
1310: Level: advanced
1312: .seealso: PetscOptionsPrint()
1313: @*/
1314: int PetscOptionsAllUsed(int *N)
1315: {
1316: int i,n = 0;
1319: for (i=0; i<options->N; i++) {
1320: if (!options->used[i]) { n++; }
1321: }
1322: *N = n;
1323: return(0);
1324: }
1326: /*@
1327: PetscOptionsLeft - Prints to screen any options that were set and never used.
1329: Not collective
1331: Options Database Key:
1332: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1334: Level: advanced
1336: .seealso: PetscOptionsAllUsed()
1337: @*/
1338: int PetscOptionsLeft(void)
1339: {
1340: int i,ierr;
1343: for (i=0; i<options->N; i++) {
1344: if (!options->used[i]) {
1345: if (options->values[i]) {
1346: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %sn",options->names[i],options->values[i]);
1347: } else {
1348: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value n",options->names[i]);
1349: }
1350: }
1351: }
1352: return(0);
1353: }
1355: /*
1356: PetscOptionsCreate - Creates the empty options database.
1358: */
1359: int PetscOptionsCreate(void)
1360: {
1364: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1365: ierr = PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1366: options->namegiven = PETSC_FALSE;
1367: options->N = 0;
1368: options->Naliases = 0;
1369: return(0);
1370: }