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;
49: /*
50: Options events monitor
51: */
52: #define PetscOptionsMonitor(name,value) \
53: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
54: for (_i=0; _i<_im; _i++) {\
55: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
56: } \
57: }
61: PetscErrorCode PetscOptionsAtoi(const char name[],PetscInt *a)
62: {
64: size_t i,len;
65: PetscTruth decide,tdefault,mouse;
68: PetscStrlen(name,&len);
69: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
71: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
72: if (!tdefault) {
73: PetscStrcasecmp(name,"DEFAULT",&tdefault);
74: }
75: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
76: if (!decide) {
77: PetscStrcasecmp(name,"DECIDE",&decide);
78: }
79: PetscStrcasecmp(name,"mouse",&mouse);
81: if (tdefault) {
82: *a = PETSC_DEFAULT;
83: } else if (decide) {
84: *a = PETSC_DECIDE;
85: } else if (mouse) {
86: *a = -1;
87: } else {
88: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
89: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
90: }
91: for (i=1; i<len; i++) {
92: if (name[i] < '0' || name[i] > '9') {
93: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
94: }
95: }
96: *a = atoi(name);
97: }
98: return(0);
99: }
103: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
104: {
106: size_t len;
107: PetscTruth decide,tdefault;
110: PetscStrlen(name,&len);
111: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
113: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
114: if (!tdefault) {
115: PetscStrcasecmp(name,"DEFAULT",&tdefault);
116: }
117: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
118: if (!decide) {
119: PetscStrcasecmp(name,"DECIDE",&decide);
120: }
122: if (tdefault) {
123: *a = PETSC_DEFAULT;
124: } else if (decide) {
125: *a = PETSC_DECIDE;
126: } else {
127: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
128: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
129: }
130: *a = atof(name);
131: }
132: return(0);
133: }
137: /*@C
138: PetscGetProgramName - Gets the name of the running program.
140: Not Collective
142: Input Parameter:
143: . len - length of the string name
145: Output Parameter:
146: . name - the name of the running program
148: Level: advanced
150: Notes:
151: The name of the program is copied into the user-provided character
152: array of length len. On some machines the program name includes
153: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
154: @*/
155: PetscErrorCode PetscGetProgramName(char name[],size_t len)
156: {
160: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
161: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
162: PetscStrncpy(name,options->programname,len);
163: return(0);
164: }
168: PetscErrorCode PetscSetProgramName(const char name[])
169: {
173: options->namegiven = PETSC_TRUE;
174: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
175: return(0);
176: }
180: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
181: {
183: *key = PETSC_FALSE;
184: if (!in_str) return(0);
185: if (in_str[0] != '-') return(0);
186: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
187: *key = PETSC_TRUE;
188: return(0);
189: }
193: /*@C
194: PetscOptionsInsertString - Inserts options into the database from a string
196: Not collective: but only processes that call this routine will set the options
197: included in the file
199: Input Parameter:
200: . in_str - string that contains options separated by blanks
203: Level: intermediate
205: Contributed by Boyana Norris
207: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
208: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
209: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
210: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
211: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
212: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
214: @*/
215: PetscErrorCode PetscOptionsInsertString(const char in_str[])
216: {
217: char *first,*second;
219: PetscToken *token;
220: PetscTruth key;
223: PetscTokenCreate(in_str,' ',&token);
224: PetscTokenFind(token,&first);
225: while (first) {
226: PetscOptionsValidKey(first,&key);
227: if (key) {
228: PetscTokenFind(token,&second);
229: PetscOptionsValidKey(second,&key);
230: if (!key) {
231: PetscOptionsSetValue(first,second);
232: PetscTokenFind(token,&first);
233: } else {
234: PetscOptionsSetValue(first,PETSC_NULL);
235: first = second;
236: }
237: } else {
238: PetscTokenFind(token,&first);
239: }
240: }
241: PetscTokenDestroy(token);
242: return(0);
243: }
247: /*@C
248: PetscOptionsInsertFile - Inserts options into the database from a file.
250: Not collective: but only processes that call this routine will set the options
251: included in the file
253: Input Parameter:
254: . file - name of file
257: Level: intermediate
259: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
260: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
261: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
262: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
263: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
264: PetscOptionsList(), PetscOptionsEList()
266: @*/
267: PetscErrorCode PetscOptionsInsertFile(const char file[])
268: {
269: char string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
271: size_t i,len,startIndex;
272: FILE *fd;
273: PetscToken *token;
276: PetscFixFilename(file,fname);
277: fd = fopen(fname,"r");
278: if (fd) {
279: while (fgets(string,128,fd)) {
280: /* Comments are indicated by #, ! or % in the first column */
281: if (string[0] == '#') continue;
282: if (string[0] == '!') continue;
283: if (string[0] == '%') continue;
285: PetscStrlen(string,&len);
287: /* replace tabs, ^M with " " */
288: for (i=0; i<len; i++) {
289: if (string[i] == '\t' || string[i] == '\r') {
290: string[i] = ' ';
291: }
292: }
293: for(startIndex = 0; startIndex < len-1; startIndex++) {
294: if (string[startIndex] != ' ') break;
295: }
296: PetscTokenCreate(&string[startIndex],' ',&token);
297: PetscTokenFind(token,&first);
298: PetscTokenFind(token,&second);
299: if (first && first[0] == '-') {
300: if (second) {final = second;} else {final = first;}
301: PetscStrlen(final,&len);
302: while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
303: len--; final[len] = 0;
304: }
305: PetscOptionsSetValue(first,second);
306: } else if (first) {
307: PetscTruth match;
309: PetscStrcasecmp(first,"alias",&match);
310: if (match) {
311: PetscTokenFind(token,&third);
312: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
313: PetscStrlen(third,&len);
314: if (third[len-1] == '\n') third[len-1] = 0;
315: PetscOptionsSetAlias(second,third);
316: }
317: }
318: PetscTokenDestroy(token);
319: }
320: fclose(fd);
321: } else {
322: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
323: }
324: return(0);
325: }
329: /*@C
330: PetscOptionsInsert - Inserts into the options database from the command line,
331: the environmental variable and a file.
333: Input Parameters:
334: + argc - count of number of command line arguments
335: . args - the command line arguments
336: - file - optional filename, defaults to ~username/.petscrc
338: Note:
339: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
340: the user does not typically need to call this routine. PetscOptionsInsert()
341: can be called several times, adding additional entries into the database.
343: Options Database Keys:
344: + -options_monitor <optional filename> - print options names and values as they are set
346: Level: advanced
348: Concepts: options database^adding
350: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
351: PetscInitialize()
352: @*/
353: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
354: {
356: PetscMPIInt rank;
357: char pfile[PETSC_MAX_PATH_LEN];
358: PetscTruth flag;
361: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
363: options->argc = (argc) ? *argc : 0;
364: options->args = (args) ? *args : 0;
366: if (file) {
367: PetscOptionsInsertFile(file);
368: }
369: PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
370: if (!flag) {
371: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
372: if (pfile[0]) {
373: PetscStrcat(pfile,"/.petscrc");
374: PetscTestFile(pfile,'r',&flag);
375: if (flag) {
376: PetscOptionsInsertFile(pfile);
377: PetscInfo(0,"Loading ~/.petscrc\n");
378: }
379: }
380: PetscTestFile(".petscrc",'r',&flag);
381: if (flag) {
382: PetscOptionsInsertFile(".petscrc");
383: PetscInfo(0,"Loading local directory file .petscrc\n");
384: }
385: }
387: /* insert environmental options */
388: {
389: char *eoptions = 0;
390: size_t len = 0;
391: if (!rank) {
392: eoptions = (char*)getenv("PETSC_OPTIONS");
393: PetscStrlen(eoptions,&len);
394: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
395: } else {
396: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
397: if (len) {
398: PetscMalloc((len+1)*sizeof(char*),&eoptions);
399: }
400: }
401: if (len) {
402: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
403: if (rank) eoptions[len] = 0;
404: PetscOptionsInsertString(eoptions);
405: if (rank) {PetscFree(eoptions);}
406: }
407: }
409: /* insert command line options */
410: if (argc && args && *argc) {
411: int left = *argc - 1;
412: char **eargs = *args + 1;
413: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
415: while (left) {
416: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
417: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
418: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
419: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
420: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
421: isp4 = (PetscTruth) (isp4 || tisp4);
422: PetscStrcasecmp(eargs[0],"-np",&tisp4);
423: isp4 = (PetscTruth) (isp4 || tisp4);
424: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
426: if (eargs[0][0] != '-') {
427: eargs++; left--;
428: } else if (isoptions_file) {
429: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
430: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
431: PetscOptionsInsertFile(eargs[1]);
432: eargs += 2; left -= 2;
434: /*
435: These are "bad" options that MPICH, etc put on the command line
436: we strip them out here.
437: */
438: } else if (tisp4 || isp4rmrank) {
439: eargs += 1; left -= 1;
440: } else if (isp4 || isp4yourname) {
441: eargs += 2; left -= 2;
442: } else if ((left < 2) || ((eargs[1][0] == '-') &&
443: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
444: PetscOptionsSetValue(eargs[0],PETSC_NULL);
445: eargs++; left--;
446: } else {
447: PetscOptionsSetValue(eargs[0],eargs[1]);
448: eargs += 2; left -= 2;
449: }
450: }
451: }
452: return(0);
453: }
457: /*@C
458: PetscOptionsPrint - Prints the options that have been loaded. This is
459: useful for debugging purposes.
461: Collective on PETSC_COMM_WORLD
463: Input Parameter:
464: . FILE fd - location to print options (usually stdout or stderr)
466: Options Database Key:
467: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
469: Level: advanced
471: Concepts: options database^printing
473: .seealso: PetscOptionsAllUsed()
474: @*/
475: PetscErrorCode PetscOptionsPrint(FILE *fd)
476: {
478: PetscInt i;
481: if (!fd) fd = stdout;
482: if (!options) {PetscOptionsInsert(0,0,0);}
483: for (i=0; i<options->N; i++) {
484: if (options->values[i]) {
485: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
486: } else {
487: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
488: }
489: }
490: return(0);
491: }
495: /*@C
496: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
498: Not Collective
500: Output Parameter:
501: . copts - pointer where string pointer is stored
503: Level: advanced
505: Concepts: options database^listing
507: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
508: @*/
509: PetscErrorCode PetscOptionsGetAll(char *copts[])
510: {
512: PetscInt i;
513: size_t len = 1,lent;
514: char *coptions;
517: if (!options) {PetscOptionsInsert(0,0,0);}
519: /* count the length of the required string */
520: for (i=0; i<options->N; i++) {
521: PetscStrlen(options->names[i],&lent);
522: len += 2 + lent;
523: if (options->values[i]) {
524: PetscStrlen(options->values[i],&lent);
525: len += 1 + lent;
526: }
527: }
528: PetscMalloc(len*sizeof(char),&coptions);
529: coptions[0] = 0;
530: for (i=0; i<options->N; i++) {
531: PetscStrcat(coptions,"-");
532: PetscStrcat(coptions,options->names[i]);
533: PetscStrcat(coptions," ");
534: if (options->values[i]) {
535: PetscStrcat(coptions,options->values[i]);
536: PetscStrcat(coptions," ");
537: }
538: }
539: *copts = coptions;
540: return(0);
541: }
545: /*@C
546: PetscOptionsDestroy - Destroys the option database.
548: Note:
549: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
550: typically does not need to call this routine.
552: Level: developer
554: .seealso: PetscOptionsInsert()
555: @*/
556: PetscErrorCode PetscOptionsDestroy(void)
557: {
558: PetscInt i;
561: if (!options) return(0);
562: for (i=0; i<options->N; i++) {
563: if (options->names[i]) free(options->names[i]);
564: if (options->values[i]) free(options->values[i]);
565: }
566: for (i=0; i<options->Naliases; i++) {
567: free(options->aliases1[i]);
568: free(options->aliases2[i]);
569: }
570: free(options);
571: options = 0;
572: return(0);
573: }
577: /*@C
578: PetscOptionsSetValue - Sets an option name-value pair in the options
579: database, overriding whatever is already present.
581: Not collective, but setting values on certain processors could cause problems
582: for parallel objects looking for options.
584: Input Parameters:
585: + name - name of option, this SHOULD have the - prepended
586: - value - the option value (not used for all options)
588: Level: intermediate
590: Note:
591: Only some options have values associated with them, such as
592: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
594: Concepts: options database^adding option
596: .seealso: PetscOptionsInsert()
597: @*/
598: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
599: {
600: size_t len;
602: PetscInt N,n,i;
603: char **names;
604: const char *name = (char*)iname;
605: PetscTruth gt,match;
608: if (!options) {PetscOptionsInsert(0,0,0);}
610: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
611: PetscStrcasecmp(name,"-h",&match);
612: if (match) name = "-help";
614: name++;
615: /* first check against aliases */
616: N = options->Naliases;
617: for (i=0; i<N; i++) {
618: PetscStrcasecmp(options->aliases1[i],name,&match);
619: if (match) {
620: name = options->aliases2[i];
621: break;
622: }
623: }
625: N = options->N;
626: n = N;
627: names = options->names;
628:
629: for (i=0; i<N; i++) {
630: PetscStrcasecmp(names[i],name,&match);
631: PetscStrgrt(names[i],name,>);
632: if (match) {
633: if (options->values[i]) free(options->values[i]);
634: PetscStrlen(value,&len);
635: if (len) {
636: options->values[i] = (char*)malloc((len+1)*sizeof(char));
637: PetscStrcpy(options->values[i],value);
638: } else { options->values[i] = 0;}
639: PetscOptionsMonitor(name,value);
640: return(0);
641: } else if (gt) {
642: n = i;
643: break;
644: }
645: }
646: if (N >= MAXOPTIONS) {
647: 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);
648: }
649: /* shift remaining values down 1 */
650: for (i=N; i>n; i--) {
651: names[i] = names[i-1];
652: options->values[i] = options->values[i-1];
653: options->used[i] = options->used[i-1];
654: }
655: /* insert new name and value */
656: PetscStrlen(name,&len);
657: names[n] = (char*)malloc((len+1)*sizeof(char));
658: PetscStrcpy(names[n],name);
659: if (value) {
660: PetscStrlen(value,&len);
661: options->values[n] = (char*)malloc((len+1)*sizeof(char));
662: PetscStrcpy(options->values[n],value);
663: } else {options->values[n] = 0;}
664: options->used[n] = PETSC_FALSE;
665: options->N++;
666: PetscOptionsMonitor(name,value);
667: return(0);
668: }
672: /*@C
673: PetscOptionsClearValue - Clears an option name-value pair in the options
674: database, overriding whatever is already present.
676: Not Collective, but setting values on certain processors could cause problems
677: for parallel objects looking for options.
679: Input Parameter:
680: . name - name of option, this SHOULD have the - prepended
682: Level: intermediate
684: Concepts: options database^removing option
685: .seealso: PetscOptionsInsert()
686: @*/
687: PetscErrorCode PetscOptionsClearValue(const char iname[])
688: {
690: PetscInt N,n,i;
691: char **names,*name=(char*)iname;
692: PetscTruth gt,match;
695: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
696: if (!options) {PetscOptionsInsert(0,0,0);}
698: name++;
700: N = options->N; n = 0;
701: names = options->names;
702:
703: for (i=0; i<N; i++) {
704: PetscStrcasecmp(names[i],name,&match);
705: PetscStrgrt(names[i],name,>);
706: if (match) {
707: if (options->values[i]) free(options->values[i]);
708: PetscOptionsMonitor(name,"");
709: break;
710: } else if (gt) {
711: return(0); /* it was not listed */
712: }
713: n++;
714: }
715: if (n == N) return(0); /* it was not listed */
717: /* shift remaining values down 1 */
718: for (i=n; i<N-1; i++) {
719: names[i] = names[i+1];
720: options->values[i] = options->values[i+1];
721: options->used[i] = options->used[i+1];
722: }
723: options->N--;
724: return(0);
725: }
729: /*@C
730: PetscOptionsReject - Generates an error if a certain option is given.
732: Not Collective, but setting values on certain processors could cause problems
733: for parallel objects looking for options.
735: Input Parameters:
736: + name - the option one is seeking
737: - mess - error message (may be PETSC_NULL)
739: Level: advanced
741: Concepts: options database^rejecting option
743: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
744: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
745: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
746: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
747: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
748: PetscOptionsList(), PetscOptionsEList()
749: @*/
750: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
751: {
753: PetscInt n = options->Naliases;
754: size_t len;
755: char *newname = (char *)inewname,*oldname = (char*)ioldname;
758: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
759: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
760: if (n >= MAXALIASES) {
761: 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);
762: }
764: newname++; oldname++;
765: PetscStrlen(newname,&len);
766: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
767: PetscStrcpy(options->aliases1[n],newname);
768: PetscStrlen(oldname,&len);
769: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
770: PetscStrcpy(options->aliases2[n],oldname);
771: options->Naliases++;
772: return(0);
773: }
777: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
778: {
780: PetscInt i,N;
781: size_t len;
782: char **names,tmp[256];
783: PetscTruth match;
786: if (!options) {PetscOptionsInsert(0,0,0);}
787: N = options->N;
788: names = options->names;
790: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
792: /* append prefix to name */
793: if (pre) {
794: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
795: PetscStrncpy(tmp,pre,256);
796: PetscStrlen(tmp,&len);
797: PetscStrncat(tmp,name+1,256-len-1);
798: } else {
799: PetscStrncpy(tmp,name+1,256);
800: }
802: /* slow search */
803: *flg = PETSC_FALSE;
804: for (i=0; i<N; i++) {
805: PetscStrcasecmp(names[i],tmp,&match);
806: if (match) {
807: *value = options->values[i];
808: options->used[i] = PETSC_TRUE;
809: *flg = PETSC_TRUE;
810: break;
811: }
812: }
813: if (!*flg) {
814: PetscInt j,cnt = 0,locs[16],loce[16];
815: size_t n;
816: PetscStrlen(tmp,&n);
817: /* determine the location and number of all _%d_ in the key */
818: for (i=0; i< (PetscInt)n; i++) {
819: if (tmp[i] == '_') {
820: for (j=i+1; j< (PetscInt)n; j++) {
821: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
822: if (tmp[j] == '_' && j > i+1) { /* found a number */
823: locs[cnt] = i+1;
824: loce[cnt++] = j+1;
825: }
826: break;
827: }
828: }
829: }
830: if (cnt) {
831: char tmp2[256];
832: for (i=0; i<cnt; i++) {
833: PetscStrcpy(tmp2,"-");
834: PetscStrncat(tmp2,tmp,locs[i]);
835: PetscStrcat(tmp2,tmp+loce[i]);
836: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
837: if (*flg) break;
838: }
839: }
840: }
841: return(0);
842: }
846: /*@C
847: PetscOptionsReject - Generates an error if a certain option is given.
849: Not Collective, but setting values on certain processors could cause problems
850: for parallel objects looking for options.
852: Input Parameters:
853: + name - the option one is seeking
854: - mess - error message (may be PETSC_NULL)
856: Level: advanced
858: Concepts: options database^rejecting option
860: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
861: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
862: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
863: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
864: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
865: PetscOptionsList(), PetscOptionsEList()
866: @*/
867: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
868: {
870: PetscTruth flag;
873: PetscOptionsHasName(PETSC_NULL,name,&flag);
874: if (flag) {
875: if (mess) {
876: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
877: } else {
878: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
879: }
880: }
881: return(0);
882: }
886: /*@C
887: PetscOptionsHasName - Determines whether a certain option is given in the database.
889: Not Collective
891: Input Parameters:
892: + name - the option one is seeking
893: - pre - string to prepend to the name or PETSC_NULL
895: Output Parameters:
896: . flg - PETSC_TRUE if found else PETSC_FALSE.
898: Level: beginner
900: Concepts: options database^has option name
902: Notes: Name cannot be simply -h
904: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
905: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
906: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
907: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
908: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
909: PetscOptionsList(), PetscOptionsEList()
910: @*/
911: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
912: {
913: char *value;
915: PetscTruth isfalse,flag;
918: PetscOptionsFindPair_Private(pre,name,&value,&flag);
920: /* remove if turned off */
921: if (flag) {
922: PetscStrcasecmp(value,"FALSE",&isfalse);
923: if (isfalse) flag = PETSC_FALSE;
924: PetscStrcasecmp(value,"NO",&isfalse);
925: if (isfalse) flag = PETSC_FALSE;
926: PetscStrcasecmp(value,"0",&isfalse);
927: if (isfalse) flag = PETSC_FALSE;
928: }
929: if (flg) *flg = flag;
930: return(0);
931: }
935: /*@C
936: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
938: Not Collective
940: Input Parameters:
941: + pre - the string to prepend to the name or PETSC_NULL
942: - name - the option one is seeking
944: Output Parameter:
945: + ivalue - the integer value to return
946: - flg - PETSC_TRUE if found, else PETSC_FALSE
948: Level: beginner
950: Concepts: options database^has int
952: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
953: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
954: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
955: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
956: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
957: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
958: PetscOptionsList(), PetscOptionsEList()
959: @*/
960: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
961: {
962: char *value;
964: PetscTruth flag;
969: PetscOptionsFindPair_Private(pre,name,&value,&flag);
970: if (flag) {
971: if (!value) {if (flg) *flg = PETSC_FALSE;}
972: else {
973: if (flg) *flg = PETSC_TRUE;
974: PetscOptionsAtoi(value,ivalue);
975: }
976: } else {
977: if (flg) *flg = PETSC_FALSE;
978: }
979: return(0);
980: }
984: /*@C
985: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
987: Not Collective
989: Input Parameters:
990: + pre - the string to prepend to the name or PETSC_NULL
991: . opt - option name
992: . list - the possible choices
993: . ntext - number of choices
995: Output Parameter:
996: + value - the index of the value to return
997: - set - PETSC_TRUE if found, else PETSC_FALSE
998:
999: Level: intermediate
1001: See PetscOptionsList() for when the choices are given in a PetscFList()
1003: Concepts: options database^list
1005: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1006: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1007: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1008: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1009: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1010: PetscOptionsList(), PetscOptionsEList()
1011: @*/
1012: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1013: {
1015: size_t alen,len = 0;
1016: char *svalue;
1017: PetscTruth aset,flg = PETSC_FALSE;
1018: PetscInt i;
1021: for ( i=0; i<ntext; i++) {
1022: PetscStrlen(list[i],&alen);
1023: if (alen > len) len = alen;
1024: }
1025: len += 5; /* a little extra space for user mistypes */
1026: PetscMalloc(len*sizeof(char),&svalue);
1027: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1028: if (aset) {
1029: if (set) *set = PETSC_TRUE;
1030: for (i=0; i<ntext; i++) {
1031: PetscStrcasecmp(svalue,list[i],&flg);
1032: if (flg) {
1033: *value = i;
1034: break;
1035: }
1036: }
1037: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1038: } else if (set) {
1039: *set = PETSC_FALSE;
1040: }
1041: PetscFree(svalue);
1042: return(0);
1043: }
1047: /*@C
1048: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1050: Not Collective
1052: Input Parameters:
1053: + pre - option prefix or PETSC_NULL
1054: . opt - option name
1055: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1056: - defaultv - the default (current) value
1058: Output Parameter:
1059: + value - the value to return
1060: - flg - PETSC_TRUE if found, else PETSC_FALSE
1062: Level: beginner
1064: Concepts: options database
1066: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1068: list is usually something like PCASMTypes or some other predefined list of enum names
1070: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1071: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1072: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1073: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1074: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1075: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1076: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1077: @*/
1078: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1079: {
1081: PetscInt ntext = 0;
1084: while (list[ntext++]) {
1085: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1086: }
1087: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1088: ntext -= 3;
1089: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1090: return(0);
1091: }
1095: /*@C
1096: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1097: option in the database.
1099: Not Collective
1101: Input Parameters:
1102: + pre - the string to prepend to the name or PETSC_NULL
1103: - name - the option one is seeking
1105: Output Parameter:
1106: + ivalue - the logical value to return
1107: - flg - PETSC_TRUE if found, else PETSC_FALSE
1109: Level: beginner
1111: Notes:
1112: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1113: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1115: Concepts: options database^has logical
1117: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1118: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1119: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1120: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1121: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1122: PetscOptionsList(), PetscOptionsEList()
1123: @*/
1124: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1125: {
1126: char *value;
1127: PetscTruth flag,istrue,isfalse;
1133: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1134: if (flag) {
1135: if (flg) *flg = PETSC_TRUE;
1136: if (!value) {
1137: *ivalue = PETSC_TRUE;
1138: } else {
1139: *ivalue = PETSC_TRUE;
1140: PetscStrcasecmp(value,"TRUE",&istrue);
1141: if (istrue) return(0);
1142: PetscStrcasecmp(value,"YES",&istrue);
1143: if (istrue) return(0);
1144: PetscStrcasecmp(value,"1",&istrue);
1145: if (istrue) return(0);
1146: PetscStrcasecmp(value,"on",&istrue);
1147: if (istrue) return(0);
1149: *ivalue = PETSC_FALSE;
1150: PetscStrcasecmp(value,"FALSE",&isfalse);
1151: if (isfalse) return(0);
1152: PetscStrcasecmp(value,"NO",&isfalse);
1153: if (isfalse) return(0);
1154: PetscStrcasecmp(value,"0",&isfalse);
1155: if (isfalse) return(0);
1156: PetscStrcasecmp(value,"off",&isfalse);
1157: if (isfalse) return(0);
1159: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1160: }
1161: } else {
1162: if (flg) *flg = PETSC_FALSE;
1163: }
1164: return(0);
1165: }
1169: /*@C
1170: PetscOptionsGetReal - Gets the double precision value for a particular
1171: option in the database.
1173: Not Collective
1175: Input Parameters:
1176: + pre - string to prepend to each name or PETSC_NULL
1177: - name - the option one is seeking
1179: Output Parameter:
1180: + dvalue - the double value to return
1181: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1183: Level: beginner
1185: Concepts: options database^has double
1187: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1188: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1189: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1190: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1191: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1192: PetscOptionsList(), PetscOptionsEList()
1193: @*/
1194: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1195: {
1196: char *value;
1198: PetscTruth flag;
1203: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1204: if (flag) {
1205: if (!value) {if (flg) *flg = PETSC_FALSE;}
1206: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1207: } else {
1208: if (flg) *flg = PETSC_FALSE;
1209: }
1210: return(0);
1211: }
1215: /*@C
1216: PetscOptionsGetScalar - Gets the scalar value for a particular
1217: option in the database.
1219: Not Collective
1221: Input Parameters:
1222: + pre - string to prepend to each name or PETSC_NULL
1223: - name - the option one is seeking
1225: Output Parameter:
1226: + dvalue - the double value to return
1227: - flg - PETSC_TRUE if found, else PETSC_FALSE
1229: Level: beginner
1231: Usage:
1232: A complex number 2+3i can be specified as 2,3 at the command line.
1233: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1235: Concepts: options database^has scalar
1237: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1238: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1239: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1240: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1241: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1242: PetscOptionsList(), PetscOptionsEList()
1243: @*/
1244: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1245: {
1246: char *value;
1247: PetscTruth flag;
1253: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1254: if (flag) {
1255: if (!value) {
1256: if (flg) *flg = PETSC_FALSE;
1257: } else {
1258: #if !defined(PETSC_USE_COMPLEX)
1259: PetscOptionsAtod(value,dvalue);
1260: #else
1261: PetscReal re=0.0,im=0.0;
1262: PetscToken *token;
1263: char *tvalue = 0;
1265: PetscTokenCreate(value,',',&token);
1266: PetscTokenFind(token,&tvalue);
1267: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1268: PetscOptionsAtod(tvalue,&re);
1269: PetscTokenFind(token,&tvalue);
1270: if (!tvalue) { /* Unknown separator used. using only real value */
1271: *dvalue = re;
1272: } else {
1273: PetscOptionsAtod(tvalue,&im);
1274: *dvalue = re + PETSC_i*im;
1275: }
1276: PetscTokenDestroy(token);
1277: #endif
1278: if (flg) *flg = PETSC_TRUE;
1279: }
1280: } else { /* flag */
1281: if (flg) *flg = PETSC_FALSE;
1282: }
1283: return(0);
1284: }
1288: /*@C
1289: PetscOptionsGetRealArray - Gets an array of double precision values for a
1290: particular option in the database. The values must be separated with
1291: commas with no intervening spaces.
1293: Not Collective
1295: Input Parameters:
1296: + pre - string to prepend to each name or PETSC_NULL
1297: . name - the option one is seeking
1298: - nmax - maximum number of values to retrieve
1300: Output Parameters:
1301: + dvalue - the double value to return
1302: . nmax - actual number of values retreived
1303: - flg - PETSC_TRUE if found, else PETSC_FALSE
1305: Level: beginner
1307: Concepts: options database^array of doubles
1309: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1310: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1311: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1312: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1313: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1314: PetscOptionsList(), PetscOptionsEList()
1315: @*/
1316: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1317: {
1318: char *value;
1320: PetscInt n = 0;
1321: PetscTruth flag;
1322: PetscToken *token;
1327: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1328: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1329: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1331: if (flg) *flg = PETSC_TRUE;
1333: PetscTokenCreate(value,',',&token);
1334: PetscTokenFind(token,&value);
1335: while (n < *nmax) {
1336: if (!value) break;
1337: PetscOptionsAtod(value,dvalue++);
1338: PetscTokenFind(token,&value);
1339: n++;
1340: }
1341: PetscTokenDestroy(token);
1342: *nmax = n;
1343: return(0);
1344: }
1348: /*@C
1349: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1350: option in the database. The values must be separated with commas with
1351: no intervening spaces.
1353: Not Collective
1355: Input Parameters:
1356: + pre - string to prepend to each name or PETSC_NULL
1357: . name - the option one is seeking
1358: - nmax - maximum number of values to retrieve
1360: Output Parameter:
1361: + dvalue - the integer values to return
1362: . nmax - actual number of values retreived
1363: - flg - PETSC_TRUE if found, else PETSC_FALSE
1365: Level: beginner
1367: Concepts: options database^array of ints
1369: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1370: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1371: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1372: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1373: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1374: PetscOptionsList(), PetscOptionsEList()
1375: @*/
1376: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1377: {
1378: char *value;
1380: PetscInt n = 0,i,start,end;
1381: size_t len;
1382: PetscTruth flag,foundrange;
1383: PetscToken *token;
1388: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1389: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1390: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1392: if (flg) *flg = PETSC_TRUE;
1394: PetscTokenCreate(value,',',&token);
1395: PetscTokenFind(token,&value);
1396: while (n < *nmax) {
1397: if (!value) break;
1398:
1399: /* look for form d-D where d and D are integers */
1400: foundrange = PETSC_FALSE;
1401: PetscStrlen(value,&len);
1402: if (value[0] == '-') i=2;
1403: else i=1;
1404: for (;i<(int)len; i++) {
1405: if (value[i] == '-') {
1406: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1407: value[i] = 0;
1408: PetscOptionsAtoi(value,&start);
1409: PetscOptionsAtoi(value+i+1,&end);
1410: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1411: if (n + end - start - 1 >= *nmax) SETERRQ4(PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
1412: for (;start<end; start++) {
1413: *dvalue = start; dvalue++;n++;
1414: }
1415: foundrange = PETSC_TRUE;
1416: break;
1417: }
1418: }
1419: if (!foundrange) {
1420: PetscOptionsAtoi(value,dvalue);
1421: dvalue++;
1422: n++;
1423: }
1424: PetscTokenFind(token,&value);
1425: }
1426: PetscTokenDestroy(token);
1427: *nmax = n;
1428: return(0);
1429: }
1433: /*@C
1434: PetscOptionsGetString - Gets the string value for a particular option in
1435: the database.
1437: Not Collective
1439: Input Parameters:
1440: + pre - string to prepend to name or PETSC_NULL
1441: . name - the option one is seeking
1442: - len - maximum string length
1444: Output Parameters:
1445: + string - location to copy string
1446: - flg - PETSC_TRUE if found, else PETSC_FALSE
1448: Level: beginner
1450: Fortran Note:
1451: The Fortran interface is slightly different from the C/C++
1452: interface (len is not used). Sample usage in Fortran follows
1453: .vb
1454: character *20 string
1455: integer flg, ierr
1456: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1457: .ve
1459: Concepts: options database^string
1461: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1462: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1463: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1464: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1465: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1466: PetscOptionsList(), PetscOptionsEList()
1467: @*/
1468: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1469: {
1470: char *value;
1472: PetscTruth flag;
1477: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1478: if (!flag) {
1479: if (flg) *flg = PETSC_FALSE;
1480: } else {
1481: if (flg) *flg = PETSC_TRUE;
1482: if (value) {
1483: PetscStrncpy(string,value,len);
1484: } else {
1485: PetscMemzero(string,len);
1486: }
1487: }
1488: return(0);
1489: }
1493: /*@C
1494: PetscOptionsGetStringArray - Gets an array of string values for a particular
1495: option in the database. The values must be separated with commas with
1496: no intervening spaces.
1498: Not Collective
1500: Input Parameters:
1501: + pre - string to prepend to name or PETSC_NULL
1502: . name - the option one is seeking
1503: - nmax - maximum number of strings
1505: Output Parameter:
1506: + strings - location to copy strings
1507: - flg - PETSC_TRUE if found, else PETSC_FALSE
1509: Level: beginner
1511: Notes:
1512: The user should pass in an array of pointers to char, to hold all the
1513: strings returned by this function.
1515: The user is responsible for deallocating the strings that are
1516: returned. The Fortran interface for this routine is not supported.
1518: Contributed by Matthew Knepley.
1520: Concepts: options database^array of strings
1522: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1523: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1524: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1525: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1526: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1527: PetscOptionsList(), PetscOptionsEList()
1528: @*/
1529: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1530: {
1531: char *value;
1533: PetscInt n;
1534: PetscTruth flag;
1535: PetscToken *token;
1536:
1540: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1541: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1542: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1543: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1544: if (flg) *flg = PETSC_TRUE;
1546: PetscTokenCreate(value,',',&token);
1547: PetscTokenFind(token,&value);
1548: n = 0;
1549: while (n < *nmax) {
1550: if (!value) break;
1551: PetscStrallocpy(value,&strings[n]);
1552: PetscTokenFind(token,&value);
1553: n++;
1554: }
1555: PetscTokenDestroy(token);
1556: *nmax = n;
1557: return(0);
1558: }
1562: /*@C
1563: PetscOptionsAllUsed - Returns a count of the number of options in the
1564: database that have never been selected.
1566: Not Collective
1568: Output Parameter:
1569: . N - count of options not used
1571: Level: advanced
1573: .seealso: PetscOptionsPrint()
1574: @*/
1575: PetscErrorCode PetscOptionsAllUsed(int *N)
1576: {
1577: PetscInt i,n = 0;
1580: for (i=0; i<options->N; i++) {
1581: if (!options->used[i]) { n++; }
1582: }
1583: *N = n;
1584: return(0);
1585: }
1589: /*@
1590: PetscOptionsLeft - Prints to screen any options that were set and never used.
1592: Not collective
1594: Options Database Key:
1595: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1597: Level: advanced
1599: .seealso: PetscOptionsAllUsed()
1600: @*/
1601: PetscErrorCode PetscOptionsLeft(void)
1602: {
1604: PetscInt i;
1607: for (i=0; i<options->N; i++) {
1608: if (!options->used[i]) {
1609: if (options->values[i]) {
1610: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1611: } else {
1612: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1613: }
1614: }
1615: }
1616: return(0);
1617: }
1620: /*
1621: PetscOptionsCreate - Creates the empty options database.
1623: */
1626: PetscErrorCode PetscOptionsCreate(void)
1627: {
1631: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1632: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1633: options->namegiven = PETSC_FALSE;
1634: options->N = 0;
1635: options->Naliases = 0;
1636: options->numbermonitors = 0;
1637:
1638: return(0);
1639: }
1643: /*@
1644: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1646: Collective on PETSC_COMM_WORLD
1648: Options Database Keys:
1649: + -options_monitor <optional filename> - prints the names and values of all
1650: runtime options as they are set. The monitor functionality is not
1651: available for options set through a file, environment variable, or on
1652: the command line. Only options set after PetscInitialize completes will
1653: be monitored.
1654: . -options_monitor_cancel - cancel all options database monitors
1656: Notes:
1657: To see all options, run your program with the -help option or consult
1658: the users manual.
1660: Level: intermediate
1662: .keywords: set, options, database
1663: @*/
1664: PetscErrorCode PetscOptionsSetFromOptions()
1665: {
1666: PetscTruth flg;
1667: PetscErrorCode ierr;
1668: char monfilename[PETSC_MAX_PATH_LEN];
1669: PetscViewer monviewer;
1673: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1674: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1675: if (flg && (!options->numbermonitors)) {
1676: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1677: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1678: }
1679:
1680: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1681: if (flg) { PetscOptionsMonitorCancel(); }
1682:
1683: PetscOptionsEnd();
1685: return(0);
1686: }
1691: /*@C
1692: PetscOptionsMonitorDefault - Print all options set value events.
1694: Collective on PETSC_COMM_WORLD
1696: Input Parameters:
1697: + name - option name string
1698: . value - option value string
1699: - dummy - unused monitor context
1701: Level: intermediate
1703: .keywords: PetscOptions, default, monitor
1705: .seealso: PetscOptionsMonitorSet()
1706: @*/
1707: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1708: {
1710: PetscViewer viewer = (PetscViewer) dummy;
1713: if (!viewer) {
1714: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1715: }
1716: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1717: return(0);
1718: }
1722: /*@C
1723: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1724: modified the PETSc options database.
1725:
1726: Not collective
1728: Input Parameters:
1729: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1730: . mctx - [optional] context for private data for the
1731: monitor routine (use PETSC_NULL if no context is desired)
1732: - monitordestroy - [optional] routine that frees monitor context
1733: (may be PETSC_NULL)
1735: Calling Sequence of monitor:
1736: $ monitor (const char name[], const char value[], void *mctx)
1738: + name - option name string
1739: . value - option value string
1740: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1742: Options Database Keys:
1743: + -options_monitor - sets PetscOptionsMonitorDefault()
1744: - -options_monitor_cancel - cancels all monitors that have
1745: been hardwired into a code by
1746: calls to PetscOptionsMonitorSet(), but
1747: does not cancel those set via
1748: the options database.
1750: Notes:
1751: The default is to do nothing. To print the name and value of options
1752: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1753: with a null monitoring context.
1755: Several different monitoring routines may be set by calling
1756: PetscOptionsMonitorSet() multiple times; all will be called in the
1757: order in which they were set.
1759: Level: beginner
1761: .keywords: PetscOptions, set, monitor
1763: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1764: @*/
1765: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1766: {
1768: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1769: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1770: }
1771: options->monitor[options->numbermonitors] = monitor;
1772: options->monitordestroy[options->numbermonitors] = monitordestroy;
1773: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1774: return(0);
1775: }
1779: /*@
1780: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
1782: Not collective
1784: Options Database Key:
1785: . -options_monitor_cancel - Cancels all monitors that have
1786: been hardwired into a code by calls to PetscOptionsMonitorSet(),
1787: but does not cancel those set via the options database.
1789: Level: intermediate
1791: .keywords: PetscOptions, set, monitor
1793: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1794: @*/
1795: PetscErrorCode PetscOptionsMonitorCancel(void)
1796: {
1798: PetscInt i;
1801: for (i=0; i<options->numbermonitors; i++) {
1802: if (options->monitordestroy[i]) {
1803: (*options->monitordestroy[i])(options->monitorcontext[i]);
1804: }
1805: }
1806: options->numbermonitors = 0;
1807: return(0);
1808: }