Actual source code: options.c
1: #define PETSC_DLL
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
15: #if defined(PETSC_HAVE_MALLOC_H)
16: #include <malloc.h>
17: #endif
18: #if defined(PETSC_HAVE_SYS_PARAM_H)
19: #include "sys/param.h"
20: #endif
21: #include "petscfix.h"
23: /*
24: For simplicity, we use a static size database
25: */
26: #define MAXOPTIONS 512
27: #define MAXALIASES 25
28: #define MAXOPTIONSMONITORS 5
30: typedef struct {
31: int N,argc,Naliases;
32: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
33: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
34: PetscTruth used[MAXOPTIONS];
35: PetscTruth namegiven;
36: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
38: /* --------User (or default) routines (most return -1 on error) --------*/
39: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
40: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*); /* */
41: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
42: PetscInt numbermonitors; /* to, for instance, detect options being set */
44: } PetscOptionsTable;
47: static PetscOptionsTable *options = 0;
51: /*
52: Options events monitor
53: */
54: #define PetscOptionsMonitor(name,value) \
55: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
56: for (_i=0; _i<_im; _i++) {\
57: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
58: } \
59: }
63: PetscErrorCode PetscOptionsAtoi(const char name[],PetscInt *a)
64: {
66: size_t i,len;
67: PetscTruth decide,tdefault,mouse;
70: PetscStrlen(name,&len);
71: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
73: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
74: if (!tdefault) {
75: PetscStrcasecmp(name,"DEFAULT",&tdefault);
76: }
77: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
78: if (!decide) {
79: PetscStrcasecmp(name,"DECIDE",&decide);
80: }
81: PetscStrcasecmp(name,"mouse",&mouse);
83: if (tdefault) {
84: *a = PETSC_DEFAULT;
85: } else if (decide) {
86: *a = PETSC_DECIDE;
87: } else if (mouse) {
88: *a = -1;
89: } else {
90: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
91: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
92: }
93: for (i=1; i<len; i++) {
94: if (name[i] < '0' || name[i] > '9') {
95: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
96: }
97: }
98: *a = atoi(name);
99: }
100: return(0);
101: }
105: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
106: {
108: size_t len;
109: PetscTruth decide,tdefault;
112: PetscStrlen(name,&len);
113: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
115: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
116: if (!tdefault) {
117: PetscStrcasecmp(name,"DEFAULT",&tdefault);
118: }
119: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
120: if (!decide) {
121: PetscStrcasecmp(name,"DECIDE",&decide);
122: }
124: if (tdefault) {
125: *a = PETSC_DEFAULT;
126: } else if (decide) {
127: *a = PETSC_DECIDE;
128: } else {
129: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
130: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
131: }
132: *a = atof(name);
133: }
134: return(0);
135: }
139: /*@C
140: PetscGetProgramName - Gets the name of the running program.
142: Not Collective
144: Input Parameter:
145: . len - length of the string name
147: Output Parameter:
148: . name - the name of the running program
150: Level: advanced
152: Notes:
153: The name of the program is copied into the user-provided character
154: array of length len. On some machines the program name includes
155: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
156: @*/
157: PetscErrorCode PetscGetProgramName(char name[],size_t len)
158: {
162: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
163: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
164: PetscStrncpy(name,options->programname,len);
165: return(0);
166: }
170: PetscErrorCode PetscSetProgramName(const char name[])
171: {
175: options->namegiven = PETSC_TRUE;
176: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
177: return(0);
178: }
182: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
183: {
185: *key = PETSC_FALSE;
186: if (!in_str) return(0);
187: if (in_str[0] != '-') return(0);
188: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
189: *key = PETSC_TRUE;
190: return(0);
191: }
195: /*@C
196: PetscOptionsInsertString - Inserts options into the database from a string
198: Not collective: but only processes that call this routine will set the options
199: included in the file
201: Input Parameter:
202: . in_str - string that contains options separated by blanks
205: Level: intermediate
207: Contributed by Boyana Norris
209: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
210: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
211: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
212: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
213: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
214: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
216: @*/
217: PetscErrorCode PetscOptionsInsertString(const char in_str[])
218: {
219: char *first,*second;
221: PetscToken *token;
222: PetscTruth key;
225: PetscTokenCreate(in_str,' ',&token);
226: PetscTokenFind(token,&first);
227: while (first) {
228: PetscOptionsValidKey(first,&key);
229: if (key) {
230: PetscTokenFind(token,&second);
231: PetscOptionsValidKey(second,&key);
232: if (!key) {
233: PetscOptionsSetValue(first,second);
234: PetscTokenFind(token,&first);
235: } else {
236: PetscOptionsSetValue(first,PETSC_NULL);
237: first = second;
238: }
239: } else {
240: PetscTokenFind(token,&first);
241: }
242: }
243: PetscTokenDestroy(token);
244: return(0);
245: }
249: /*@C
250: PetscOptionsInsertFile - Inserts options into the database from a file.
252: Not collective: but only processes that call this routine will set the options
253: included in the file
255: Input Parameter:
256: . file - name of file
259: Level: intermediate
261: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
262: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
263: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
264: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
265: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
266: PetscOptionsList(), PetscOptionsEList()
268: @*/
269: PetscErrorCode PetscOptionsInsertFile(const char file[])
270: {
271: char string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
273: size_t i,len,startIndex;
274: FILE *fd;
275: PetscToken *token;
278: PetscFixFilename(file,fname);
279: fd = fopen(fname,"r");
280: if (fd) {
281: while (fgets(string,128,fd)) {
282: /* Comments are indicated by #, ! or % in the first column */
283: if (string[0] == '#') continue;
284: if (string[0] == '!') continue;
285: if (string[0] == '%') continue;
287: PetscStrlen(string,&len);
289: /* replace tabs, ^M with " " */
290: for (i=0; i<len; i++) {
291: if (string[i] == '\t' || string[i] == '\r') {
292: string[i] = ' ';
293: }
294: }
295: for(startIndex = 0; startIndex < len-1; startIndex++) {
296: if (string[startIndex] != ' ') break;
297: }
298: PetscTokenCreate(&string[startIndex],' ',&token);
299: PetscTokenFind(token,&first);
300: PetscTokenFind(token,&second);
301: if (first && first[0] == '-') {
302: if (second) {final = second;} else {final = first;}
303: PetscStrlen(final,&len);
304: while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
305: len--; final[len] = 0;
306: }
307: PetscOptionsSetValue(first,second);
308: } else if (first) {
309: PetscTruth match;
311: PetscStrcasecmp(first,"alias",&match);
312: if (match) {
313: PetscTokenFind(token,&third);
314: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
315: PetscStrlen(third,&len);
316: if (third[len-1] == '\n') third[len-1] = 0;
317: PetscOptionsSetAlias(second,third);
318: }
319: }
320: PetscTokenDestroy(token);
321: }
322: fclose(fd);
323: } else {
324: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
325: }
326: return(0);
327: }
331: /*@C
332: PetscOptionsInsert - Inserts into the options database from the command line,
333: the environmental variable and a file.
335: Input Parameters:
336: + argc - count of number of command line arguments
337: . args - the command line arguments
338: - file - optional filename, defaults to ~username/.petscrc
340: Note:
341: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
342: the user does not typically need to call this routine. PetscOptionsInsert()
343: can be called several times, adding additional entries into the database.
345: Options Database Keys:
346: + -options_monitor <optional filename> - print options names and values as they are set
348: Level: advanced
350: Concepts: options database^adding
352: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
353: PetscInitialize()
354: @*/
355: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
356: {
358: PetscMPIInt rank;
359: char pfile[PETSC_MAX_PATH_LEN];
360: PetscTruth flag;
363: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
365: options->argc = (argc) ? *argc : 0;
366: options->args = (args) ? *args : 0;
368: if (file) {
369: PetscOptionsInsertFile(file);
370: }
371: PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
372: if (!flag) {
373: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
374: if (pfile[0]) {
375: PetscStrcat(pfile,"/.petscrc");
376: PetscTestFile(pfile,'r',&flag);
377: if (flag) {
378: PetscOptionsInsertFile(pfile);
379: PetscInfo(0,"Loading ~/.petscrc\n");
380: }
381: }
382: PetscTestFile(".petscrc",'r',&flag);
383: if (flag) {
384: PetscOptionsInsertFile(".petscrc");
385: PetscInfo(0,"Loading local directory file .petscrc\n");
386: }
387: }
389: /* insert environmental options */
390: {
391: char *eoptions = 0;
392: size_t len = 0;
393: if (!rank) {
394: eoptions = (char*)getenv("PETSC_OPTIONS");
395: PetscStrlen(eoptions,&len);
396: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
397: } else {
398: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
399: if (len) {
400: PetscMalloc((len+1)*sizeof(char*),&eoptions);
401: }
402: }
403: if (len) {
404: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
405: if (rank) eoptions[len] = 0;
406: PetscOptionsInsertString(eoptions);
407: if (rank) {PetscFree(eoptions);}
408: }
409: }
411: /* insert command line options */
412: if (argc && args && *argc) {
413: int left = *argc - 1;
414: char **eargs = *args + 1;
415: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
417: while (left) {
418: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
419: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
420: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
421: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
422: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
423: isp4 = (PetscTruth) (isp4 || tisp4);
424: PetscStrcasecmp(eargs[0],"-np",&tisp4);
425: isp4 = (PetscTruth) (isp4 || tisp4);
426: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
428: if (eargs[0][0] != '-') {
429: eargs++; left--;
430: } else if (isoptions_file) {
431: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
432: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
433: PetscOptionsInsertFile(eargs[1]);
434: eargs += 2; left -= 2;
436: /*
437: These are "bad" options that MPICH, etc put on the command line
438: we strip them out here.
439: */
440: } else if (tisp4 || isp4rmrank) {
441: eargs += 1; left -= 1;
442: } else if (isp4 || isp4yourname) {
443: eargs += 2; left -= 2;
444: } else if ((left < 2) || ((eargs[1][0] == '-') &&
445: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
446: PetscOptionsSetValue(eargs[0],PETSC_NULL);
447: eargs++; left--;
448: } else {
449: PetscOptionsSetValue(eargs[0],eargs[1]);
450: eargs += 2; left -= 2;
451: }
452: }
453: }
454: return(0);
455: }
459: /*@C
460: PetscOptionsPrint - Prints the options that have been loaded. This is
461: useful for debugging purposes.
463: Collective on PETSC_COMM_WORLD
465: Input Parameter:
466: . FILE fd - location to print options (usually stdout or stderr)
468: Options Database Key:
469: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
471: Level: advanced
473: Concepts: options database^printing
475: .seealso: PetscOptionsAllUsed()
476: @*/
477: PetscErrorCode PetscOptionsPrint(FILE *fd)
478: {
480: PetscInt i;
483: if (!fd) fd = stdout;
484: if (!options) {PetscOptionsInsert(0,0,0);}
485: for (i=0; i<options->N; i++) {
486: if (options->values[i]) {
487: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
488: } else {
489: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
490: }
491: }
492: return(0);
493: }
497: /*@C
498: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
500: Not Collective
502: Output Parameter:
503: . copts - pointer where string pointer is stored
505: Level: advanced
507: Concepts: options database^listing
509: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
510: @*/
511: PetscErrorCode PetscOptionsGetAll(char *copts[])
512: {
514: PetscInt i;
515: size_t len = 1,lent;
516: char *coptions;
519: if (!options) {PetscOptionsInsert(0,0,0);}
521: /* count the length of the required string */
522: for (i=0; i<options->N; i++) {
523: PetscStrlen(options->names[i],&lent);
524: len += 2 + lent;
525: if (options->values[i]) {
526: PetscStrlen(options->values[i],&lent);
527: len += 1 + lent;
528: }
529: }
530: PetscMalloc(len*sizeof(char),&coptions);
531: coptions[0] = 0;
532: for (i=0; i<options->N; i++) {
533: PetscStrcat(coptions,"-");
534: PetscStrcat(coptions,options->names[i]);
535: PetscStrcat(coptions," ");
536: if (options->values[i]) {
537: PetscStrcat(coptions,options->values[i]);
538: PetscStrcat(coptions," ");
539: }
540: }
541: *copts = coptions;
542: return(0);
543: }
547: /*@C
548: PetscOptionsDestroy - Destroys the option database.
550: Note:
551: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
552: typically does not need to call this routine.
554: Level: developer
556: .seealso: PetscOptionsInsert()
557: @*/
558: PetscErrorCode PetscOptionsDestroy(void)
559: {
560: PetscInt i;
563: if (!options) return(0);
564: for (i=0; i<options->N; i++) {
565: if (options->names[i]) free(options->names[i]);
566: if (options->values[i]) free(options->values[i]);
567: }
568: for (i=0; i<options->Naliases; i++) {
569: free(options->aliases1[i]);
570: free(options->aliases2[i]);
571: }
572: free(options);
573: options = 0;
574: return(0);
575: }
579: /*@C
580: PetscOptionsSetValue - Sets an option name-value pair in the options
581: database, overriding whatever is already present.
583: Not collective, but setting values on certain processors could cause problems
584: for parallel objects looking for options.
586: Input Parameters:
587: + name - name of option, this SHOULD have the - prepended
588: - value - the option value (not used for all options)
590: Level: intermediate
592: Note:
593: Only some options have values associated with them, such as
594: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
596: Concepts: options database^adding option
598: .seealso: PetscOptionsInsert()
599: @*/
600: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
601: {
602: size_t len;
604: PetscInt N,n,i;
605: char **names;
606: const char *name = (char*)iname;
607: PetscTruth gt,match;
610: if (!options) {PetscOptionsInsert(0,0,0);}
612: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
613: PetscStrcasecmp(name,"-h",&match);
614: if (match) name = "-help";
616: name++;
617: /* first check against aliases */
618: N = options->Naliases;
619: for (i=0; i<N; i++) {
620: PetscStrcasecmp(options->aliases1[i],name,&match);
621: if (match) {
622: name = options->aliases2[i];
623: break;
624: }
625: }
627: N = options->N;
628: n = N;
629: names = options->names;
630:
631: for (i=0; i<N; i++) {
632: PetscStrcasecmp(names[i],name,&match);
633: PetscStrgrt(names[i],name,>);
634: if (match) {
635: if (options->values[i]) free(options->values[i]);
636: PetscStrlen(value,&len);
637: if (len) {
638: options->values[i] = (char*)malloc((len+1)*sizeof(char));
639: PetscStrcpy(options->values[i],value);
640: } else { options->values[i] = 0;}
641: PetscOptionsMonitor(name,value);
642: return(0);
643: } else if (gt) {
644: n = i;
645: break;
646: }
647: }
648: if (N >= MAXOPTIONS) {
649: SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
650: }
651: /* shift remaining values down 1 */
652: for (i=N; i>n; i--) {
653: names[i] = names[i-1];
654: options->values[i] = options->values[i-1];
655: options->used[i] = options->used[i-1];
656: }
657: /* insert new name and value */
658: PetscStrlen(name,&len);
659: names[n] = (char*)malloc((len+1)*sizeof(char));
660: PetscStrcpy(names[n],name);
661: if (value) {
662: PetscStrlen(value,&len);
663: options->values[n] = (char*)malloc((len+1)*sizeof(char));
664: PetscStrcpy(options->values[n],value);
665: } else {options->values[n] = 0;}
666: options->used[n] = PETSC_FALSE;
667: options->N++;
668: PetscOptionsMonitor(name,value);
669: return(0);
670: }
674: /*@C
675: PetscOptionsClearValue - Clears an option name-value pair in the options
676: database, overriding whatever is already present.
678: Not Collective, but setting values on certain processors could cause problems
679: for parallel objects looking for options.
681: Input Parameter:
682: . name - name of option, this SHOULD have the - prepended
684: Level: intermediate
686: Concepts: options database^removing option
687: .seealso: PetscOptionsInsert()
688: @*/
689: PetscErrorCode PetscOptionsClearValue(const char iname[])
690: {
692: PetscInt N,n,i;
693: char **names,*name=(char*)iname;
694: PetscTruth gt,match;
697: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
698: if (!options) {PetscOptionsInsert(0,0,0);}
700: name++;
702: N = options->N; n = 0;
703: names = options->names;
704:
705: for (i=0; i<N; i++) {
706: PetscStrcasecmp(names[i],name,&match);
707: PetscStrgrt(names[i],name,>);
708: if (match) {
709: if (options->values[i]) free(options->values[i]);
710: PetscOptionsMonitor(name,"");
711: break;
712: } else if (gt) {
713: return(0); /* it was not listed */
714: }
715: n++;
716: }
717: if (n == N) return(0); /* it was not listed */
719: /* shift remaining values down 1 */
720: for (i=n; i<N-1; i++) {
721: names[i] = names[i+1];
722: options->values[i] = options->values[i+1];
723: options->used[i] = options->used[i+1];
724: }
725: options->N--;
726: return(0);
727: }
731: /*@C
732: PetscOptionsReject - Generates an error if a certain option is given.
734: Not Collective, but setting values on certain processors could cause problems
735: for parallel objects looking for options.
737: Input Parameters:
738: + name - the option one is seeking
739: - mess - error message (may be PETSC_NULL)
741: Level: advanced
743: Concepts: options database^rejecting option
745: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
746: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
747: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
748: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
749: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
750: PetscOptionsList(), PetscOptionsEList()
751: @*/
752: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
753: {
755: PetscInt n = options->Naliases;
756: size_t len;
757: char *newname = (char *)inewname,*oldname = (char*)ioldname;
760: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
761: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
762: if (n >= MAXALIASES) {
763: SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n src/sys/objects/options.c with larger value for MAXALIASES",MAXALIASES);
764: }
766: newname++; oldname++;
767: PetscStrlen(newname,&len);
768: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
769: PetscStrcpy(options->aliases1[n],newname);
770: PetscStrlen(oldname,&len);
771: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
772: PetscStrcpy(options->aliases2[n],oldname);
773: options->Naliases++;
774: return(0);
775: }
779: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
780: {
782: PetscInt i,N;
783: size_t len;
784: char **names,tmp[256];
785: PetscTruth match;
788: if (!options) {PetscOptionsInsert(0,0,0);}
789: N = options->N;
790: names = options->names;
792: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
794: /* append prefix to name */
795: if (pre) {
796: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
797: PetscStrncpy(tmp,pre,256);
798: PetscStrlen(tmp,&len);
799: PetscStrncat(tmp,name+1,256-len-1);
800: } else {
801: PetscStrncpy(tmp,name+1,256);
802: }
804: /* slow search */
805: *flg = PETSC_FALSE;
806: for (i=0; i<N; i++) {
807: PetscStrcasecmp(names[i],tmp,&match);
808: if (match) {
809: *value = options->values[i];
810: options->used[i] = PETSC_TRUE;
811: *flg = PETSC_TRUE;
812: break;
813: }
814: }
815: if (!*flg) {
816: PetscInt j,cnt = 0,locs[16],loce[16];
817: size_t n;
818: PetscStrlen(tmp,&n);
819: /* determine the location and number of all _%d_ in the key */
820: for (i=0; i< (PetscInt)n; i++) {
821: if (tmp[i] == '_') {
822: for (j=i+1; j< (PetscInt)n; j++) {
823: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
824: if (tmp[j] == '_' && j > i+1) { /* found a number */
825: locs[cnt] = i+1;
826: loce[cnt++] = j+1;
827: }
828: break;
829: }
830: }
831: }
832: if (cnt) {
833: char tmp2[256];
834: for (i=0; i<cnt; i++) {
835: PetscStrcpy(tmp2,"-");
836: PetscStrncat(tmp2,tmp,locs[i]);
837: PetscStrcat(tmp2,tmp+loce[i]);
838: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
839: if (*flg) break;
840: }
841: }
842: }
843: return(0);
844: }
848: /*@C
849: PetscOptionsReject - Generates an error if a certain option is given.
851: Not Collective, but setting values on certain processors could cause problems
852: for parallel objects looking for options.
854: Input Parameters:
855: + name - the option one is seeking
856: - mess - error message (may be PETSC_NULL)
858: Level: advanced
860: Concepts: options database^rejecting option
862: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
863: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
864: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
865: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
866: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
867: PetscOptionsList(), PetscOptionsEList()
868: @*/
869: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
870: {
872: PetscTruth flag;
875: PetscOptionsHasName(PETSC_NULL,name,&flag);
876: if (flag) {
877: if (mess) {
878: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
879: } else {
880: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
881: }
882: }
883: return(0);
884: }
888: /*@C
889: PetscOptionsHasName - Determines whether a certain option is given in the database.
891: Not Collective
893: Input Parameters:
894: + name - the option one is seeking
895: - pre - string to prepend to the name or PETSC_NULL
897: Output Parameters:
898: . flg - PETSC_TRUE if found else PETSC_FALSE.
900: Level: beginner
902: Concepts: options database^has option name
904: Notes: Name cannot be simply -h
906: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
907: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
908: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
909: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
910: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
911: PetscOptionsList(), PetscOptionsEList()
912: @*/
913: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
914: {
915: char *value;
917: PetscTruth isfalse,flag;
920: PetscOptionsFindPair_Private(pre,name,&value,&flag);
922: /* remove if turned off */
923: if (flag) {
924: PetscStrcasecmp(value,"FALSE",&isfalse);
925: if (isfalse) flag = PETSC_FALSE;
926: PetscStrcasecmp(value,"NO",&isfalse);
927: if (isfalse) flag = PETSC_FALSE;
928: PetscStrcasecmp(value,"0",&isfalse);
929: if (isfalse) flag = PETSC_FALSE;
930: }
931: if (flg) *flg = flag;
932: return(0);
933: }
937: /*@C
938: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
940: Not Collective
942: Input Parameters:
943: + pre - the string to prepend to the name or PETSC_NULL
944: - name - the option one is seeking
946: Output Parameter:
947: + ivalue - the integer value to return
948: - flg - PETSC_TRUE if found, else PETSC_FALSE
950: Level: beginner
952: Concepts: options database^has int
954: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
955: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
956: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
957: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
958: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
959: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
960: PetscOptionsList(), PetscOptionsEList()
961: @*/
962: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
963: {
964: char *value;
966: PetscTruth flag;
971: PetscOptionsFindPair_Private(pre,name,&value,&flag);
972: if (flag) {
973: if (!value) {if (flg) *flg = PETSC_FALSE;}
974: else {
975: if (flg) *flg = PETSC_TRUE;
976: PetscOptionsAtoi(value,ivalue);
977: }
978: } else {
979: if (flg) *flg = PETSC_FALSE;
980: }
981: return(0);
982: }
986: /*@C
987: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
989: Not Collective
991: Input Parameters:
992: + pre - the string to prepend to the name or PETSC_NULL
993: . opt - option name
994: . list - the possible choices
995: . ntext - number of choices
997: Output Parameter:
998: + value - the index of the value to return
999: - set - PETSC_TRUE if found, else PETSC_FALSE
1000:
1001: Level: intermediate
1003: See PetscOptionsList() for when the choices are given in a PetscFList()
1005: Concepts: options database^list
1007: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1008: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1009: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1010: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1011: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1012: PetscOptionsList(), PetscOptionsEList()
1013: @*/
1014: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1015: {
1017: size_t alen,len = 0;
1018: char *svalue;
1019: PetscTruth aset,flg = PETSC_FALSE;
1020: PetscInt i;
1023: for ( i=0; i<ntext; i++) {
1024: PetscStrlen(list[i],&alen);
1025: if (alen > len) len = alen;
1026: }
1027: len += 5; /* a little extra space for user mistypes */
1028: PetscMalloc(len*sizeof(char),&svalue);
1029: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1030: if (aset) {
1031: if (set) *set = PETSC_TRUE;
1032: for (i=0; i<ntext; i++) {
1033: PetscStrcasecmp(svalue,list[i],&flg);
1034: if (flg) {
1035: *value = i;
1036: break;
1037: }
1038: }
1039: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1040: } else if (set) {
1041: *set = PETSC_FALSE;
1042: }
1043: PetscFree(svalue);
1044: return(0);
1045: }
1049: /*@C
1050: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1052: Not Collective
1054: Input Parameters:
1055: + pre - option prefix or PETSC_NULL
1056: . opt - option name
1057: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1058: - defaultv - the default (current) value
1060: Output Parameter:
1061: + value - the value to return
1062: - flg - PETSC_TRUE if found, else PETSC_FALSE
1064: Level: beginner
1066: Concepts: options database
1068: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1070: list is usually something like PCASMTypes or some other predefined list of enum names
1072: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1073: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1074: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1075: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1076: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1077: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1078: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1079: @*/
1080: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1081: {
1083: PetscInt ntext = 0;
1086: while (list[ntext++]) {
1087: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1088: }
1089: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1090: ntext -= 3;
1091: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1092: return(0);
1093: }
1097: /*@C
1098: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1099: option in the database.
1101: Not Collective
1103: Input Parameters:
1104: + pre - the string to prepend to the name or PETSC_NULL
1105: - name - the option one is seeking
1107: Output Parameter:
1108: + ivalue - the logical value to return
1109: - flg - PETSC_TRUE if found, else PETSC_FALSE
1111: Level: beginner
1113: Notes:
1114: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1115: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1117: Concepts: options database^has logical
1119: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1120: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1121: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1122: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1123: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1124: PetscOptionsList(), PetscOptionsEList()
1125: @*/
1126: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1127: {
1128: char *value;
1129: PetscTruth flag,istrue,isfalse;
1135: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1136: if (flag) {
1137: if (flg) *flg = PETSC_TRUE;
1138: if (!value) {
1139: *ivalue = PETSC_TRUE;
1140: } else {
1141: *ivalue = PETSC_TRUE;
1142: PetscStrcasecmp(value,"TRUE",&istrue);
1143: if (istrue) return(0);
1144: PetscStrcasecmp(value,"YES",&istrue);
1145: if (istrue) return(0);
1146: PetscStrcasecmp(value,"1",&istrue);
1147: if (istrue) return(0);
1148: PetscStrcasecmp(value,"on",&istrue);
1149: if (istrue) return(0);
1151: *ivalue = PETSC_FALSE;
1152: PetscStrcasecmp(value,"FALSE",&isfalse);
1153: if (isfalse) return(0);
1154: PetscStrcasecmp(value,"NO",&isfalse);
1155: if (isfalse) return(0);
1156: PetscStrcasecmp(value,"0",&isfalse);
1157: if (isfalse) return(0);
1158: PetscStrcasecmp(value,"off",&isfalse);
1159: if (isfalse) return(0);
1161: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1162: }
1163: } else {
1164: if (flg) *flg = PETSC_FALSE;
1165: }
1166: return(0);
1167: }
1171: /*@C
1172: PetscOptionsGetReal - Gets the double precision value for a particular
1173: option in the database.
1175: Not Collective
1177: Input Parameters:
1178: + pre - string to prepend to each name or PETSC_NULL
1179: - name - the option one is seeking
1181: Output Parameter:
1182: + dvalue - the double value to return
1183: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1185: Level: beginner
1187: Concepts: options database^has double
1189: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1190: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1191: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1192: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1193: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1194: PetscOptionsList(), PetscOptionsEList()
1195: @*/
1196: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1197: {
1198: char *value;
1200: PetscTruth flag;
1205: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1206: if (flag) {
1207: if (!value) {if (flg) *flg = PETSC_FALSE;}
1208: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1209: } else {
1210: if (flg) *flg = PETSC_FALSE;
1211: }
1212: return(0);
1213: }
1217: /*@C
1218: PetscOptionsGetScalar - Gets the scalar value for a particular
1219: option in the database.
1221: Not Collective
1223: Input Parameters:
1224: + pre - string to prepend to each name or PETSC_NULL
1225: - name - the option one is seeking
1227: Output Parameter:
1228: + dvalue - the double value to return
1229: - flg - PETSC_TRUE if found, else PETSC_FALSE
1231: Level: beginner
1233: Usage:
1234: A complex number 2+3i can be specified as 2,3 at the command line.
1235: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1237: Concepts: options database^has scalar
1239: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1240: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1241: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1242: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1243: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1244: