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: PetscErrorCode PetscOptionsAtol(const char value[], PetscTruth *a)
140: {
141: PetscTruth istrue, isfalse;
142: size_t len;
146: PetscStrlen(value, &len);
147: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
148: PetscStrcasecmp(value,"TRUE",&istrue);
149: if (istrue) {*a = PETSC_TRUE; return(0);}
150: PetscStrcasecmp(value,"YES",&istrue);
151: if (istrue) {*a = PETSC_TRUE; return(0);}
152: PetscStrcasecmp(value,"1",&istrue);
153: if (istrue) {*a = PETSC_TRUE; return(0);}
154: PetscStrcasecmp(value,"on",&istrue);
155: if (istrue) {*a = PETSC_TRUE; return(0);}
156: PetscStrcasecmp(value,"FALSE",&isfalse);
157: if (isfalse) {*a = PETSC_FALSE; return(0);}
158: PetscStrcasecmp(value,"NO",&isfalse);
159: if (isfalse) {*a = PETSC_FALSE; return(0);}
160: PetscStrcasecmp(value,"0",&isfalse);
161: if (isfalse) {*a = PETSC_FALSE; return(0);}
162: PetscStrcasecmp(value,"off",&isfalse);
163: if (isfalse) {*a = PETSC_FALSE; return(0);}
164: SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
165: return(0);
166: }
170: /*@C
171: PetscGetProgramName - Gets the name of the running program.
173: Not Collective
175: Input Parameter:
176: . len - length of the string name
178: Output Parameter:
179: . name - the name of the running program
181: Level: advanced
183: Notes:
184: The name of the program is copied into the user-provided character
185: array of length len. On some machines the program name includes
186: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
187: @*/
188: PetscErrorCode PetscGetProgramName(char name[],size_t len)
189: {
193: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
194: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
195: PetscStrncpy(name,options->programname,len);
196: return(0);
197: }
201: PetscErrorCode PetscSetProgramName(const char name[])
202: {
206: options->namegiven = PETSC_TRUE;
207: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
208: return(0);
209: }
213: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
214: {
216: *key = PETSC_FALSE;
217: if (!in_str) return(0);
218: if (in_str[0] != '-') return(0);
219: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
220: *key = PETSC_TRUE;
221: return(0);
222: }
226: /*@C
227: PetscOptionsInsertString - Inserts options into the database from a string
229: Not collective: but only processes that call this routine will set the options
230: included in the file
232: Input Parameter:
233: . in_str - string that contains options separated by blanks
236: Level: intermediate
238: Contributed by Boyana Norris
240: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
241: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
242: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
243: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
244: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
245: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
247: @*/
248: PetscErrorCode PetscOptionsInsertString(const char in_str[])
249: {
250: char *first,*second;
252: PetscToken token;
253: PetscTruth key;
256: PetscTokenCreate(in_str,' ',&token);
257: PetscTokenFind(token,&first);
258: while (first) {
259: PetscOptionsValidKey(first,&key);
260: if (key) {
261: PetscTokenFind(token,&second);
262: PetscOptionsValidKey(second,&key);
263: if (!key) {
264: PetscOptionsSetValue(first,second);
265: PetscTokenFind(token,&first);
266: } else {
267: PetscOptionsSetValue(first,PETSC_NULL);
268: first = second;
269: }
270: } else {
271: PetscTokenFind(token,&first);
272: }
273: }
274: PetscTokenDestroy(token);
275: return(0);
276: }
280: /*@C
281: PetscOptionsInsertFile - Inserts options into the database from a file.
283: Not collective: but only processes that call this routine will set the options
284: included in the file
286: Input Parameter:
287: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
288: . file - name of file
289: - require - if PETSC_TRUE will generate an error if the file does not exist
292: Level: intermediate
294: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
295: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
296: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
297: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
298: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
299: PetscOptionsList(), PetscOptionsEList()
301: @*/
302: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
303: {
304: char string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring,*astring;
306: size_t i,len;
307: FILE *fd;
308: PetscToken token;
309: int err;
310: char cmt[3]={'#','!','%'},*cmatch;
311: PetscMPIInt rank,cnt,acnt;
314: /* Warning: assume a maximum size for all options in a string */
315: PetscMalloc(64000*sizeof(char),&vstring);
316: vstring[0] = 0;
317: PetscMalloc(64000*sizeof(char),&astring);
318: astring[0] = 0;
319: cnt = 0;
320: acnt = 0;
321: MPI_Comm_rank(comm,&rank);
322: if (!rank) {
323: PetscFixFilename(file,fname);
324: fd = fopen(fname,"r");
325: if (fd) {
326: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
327: PetscInfo1(0,"Opened options file %s\n",file);
328: while (fgets(string,PETSC_MAX_PATH_LEN,fd)) {
329: /* eliminate comments from each line */
330: for (i=0; i<3; i++){
331: PetscStrchr(string,cmt[i],&cmatch);
332: if (cmatch) *cmatch = 0;
333: }
334: PetscStrlen(string,&len);
335: /* replace tabs, ^M, \n with " " */
336: for (i=0; i<len; i++) {
337: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
338: string[i] = ' ';
339: }
340: }
341: PetscTokenCreate(string,' ',&token);
342: PetscTokenFind(token,&first);
343: if (!first) {
344: goto destroy;
345: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
346: PetscTokenFind(token,&first);
347: }
348: PetscTokenFind(token,&second);
349: if (!first) {
350: goto destroy;
351: } else if (first[0] == '-') {
352: /* warning: should be making sure we do not overfill vstring */
353: PetscStrcat(vstring,first);
354: PetscStrcat(vstring," ");
355: if (second) {
356: /* protect second with quotes in case it contains strings */
357: PetscStrcat(vstring,"\"");
358: PetscStrcat(vstring,second);
359: PetscStrcat(vstring,"\"");
360: }
361: PetscStrcat(vstring," ");
362: /* PetscOptionsSetValue(first,second); */
363: } else {
364: PetscTruth match;
366: PetscStrcasecmp(first,"alias",&match);
367: if (match) {
368: PetscTokenFind(token,&third);
369: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
370: PetscStrcat(astring,second);
371: PetscStrcat(astring," ");
372: PetscStrcat(astring,third);
373: PetscStrcat(astring," ");
374: /* PetscOptionsSetAlias(second,third);*/
375: } else {
376: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
377: }
378: }
379: destroy:
380: PetscTokenDestroy(token);
381: }
382: err = fclose(fd);
383: if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
384: PetscStrlen(astring,&len);
385: acnt = PetscMPIIntCast(len);
386: PetscStrlen(vstring,&len);
387: cnt = PetscMPIIntCast(len);
388: } else if (require) {
389: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
390: }
391: }
392: MPI_Bcast(&acnt,1,MPIU_INT,0,comm);
393: if (acnt) {
394: PetscToken token;
395: char *first,*second;
397: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
398: astring[acnt] = 0;
399: PetscTokenCreate(astring,' ',&token);
400: PetscTokenFind(token,&first);
401: while (first) {
402: PetscTokenFind(token,&second);
403: PetscOptionsSetAlias(first,second);
404: PetscTokenFind(token,&first);
405: }
406: PetscTokenDestroy(token);
407: }
409: MPI_Bcast(&cnt,1,MPIU_INT,0,comm);
410: if (cnt) {
411: if (rank && vstring && cnt>64000 ) {
412: PetscFree(vstring);
413: PetscMalloc((cnt+1)*sizeof(char),&vstring);
414: }
415: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
416: vstring[cnt] = 0;
417: PetscOptionsInsertString(vstring);
418: }
419: PetscFree(astring);
420: PetscFree(vstring);
421: return(0);
422: }
426: /*@C
427: PetscOptionsInsert - Inserts into the options database from the command line,
428: the environmental variable and a file.
430: Input Parameters:
431: + argc - count of number of command line arguments
432: . args - the command line arguments
433: - file - optional filename, defaults to ~username/.petscrc
435: Note:
436: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
437: the user does not typically need to call this routine. PetscOptionsInsert()
438: can be called several times, adding additional entries into the database.
440: Options Database Keys:
441: + -options_monitor <optional filename> - print options names and values as they are set
443: Level: advanced
445: Concepts: options database^adding
447: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
448: PetscInitialize()
449: @*/
450: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
451: {
453: PetscMPIInt rank;
454: char pfile[PETSC_MAX_PATH_LEN];
455: PetscTruth flag;
458: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
460: options->argc = (argc) ? *argc : 0;
461: options->args = (args) ? *args : PETSC_NULL;
463: if (file) {
464: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
465: }
466: PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
467: if (!flag) {
468: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
469: /* warning: assumes all processes have a home directory or none, but nothing in between */
470: if (pfile[0]) {
471: PetscStrcat(pfile,"/.petscrc");
472: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
473: }
474: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
475: }
477: /* insert environmental options */
478: {
479: char *eoptions = 0;
480: size_t len = 0;
481: if (!rank) {
482: eoptions = (char*)getenv("PETSC_OPTIONS");
483: PetscStrlen(eoptions,&len);
484: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
485: } else {
486: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
487: if (len) {
488: PetscMalloc((len+1)*sizeof(char*),&eoptions);
489: }
490: }
491: if (len) {
492: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
493: if (rank) eoptions[len] = 0;
494: PetscOptionsInsertString(eoptions);
495: if (rank) {PetscFree(eoptions);}
496: }
497: }
499: /* insert command line options */
500: if (argc && args && *argc) {
501: int left = *argc - 1;
502: char **eargs = *args + 1;
503: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
505: while (left) {
506: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
507: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
508: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
509: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
510: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
511: isp4 = (PetscTruth) (isp4 || tisp4);
512: PetscStrcasecmp(eargs[0],"-np",&tisp4);
513: isp4 = (PetscTruth) (isp4 || tisp4);
514: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
516: if (eargs[0][0] != '-') {
517: eargs++; left--;
518: } else if (isoptions_file) {
519: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
520: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
521: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
522: eargs += 2; left -= 2;
524: /*
525: These are "bad" options that MPICH, etc put on the command line
526: we strip them out here.
527: */
528: } else if (tisp4 || isp4rmrank) {
529: eargs += 1; left -= 1;
530: } else if (isp4 || isp4yourname) {
531: eargs += 2; left -= 2;
532: } else if ((left < 2) || ((eargs[1][0] == '-') &&
533: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
534: PetscOptionsSetValue(eargs[0],PETSC_NULL);
535: eargs++; left--;
536: } else {
537: PetscOptionsSetValue(eargs[0],eargs[1]);
538: eargs += 2; left -= 2;
539: }
540: }
541: }
542: return(0);
543: }
547: /*@C
548: PetscOptionsPrint - Prints the options that have been loaded. This is
549: useful for debugging purposes.
551: Collective on PETSC_COMM_WORLD
553: Input Parameter:
554: . FILE fd - location to print options (usually stdout or stderr)
556: Options Database Key:
557: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
559: Level: advanced
561: Concepts: options database^printing
563: .seealso: PetscOptionsAllUsed()
564: @*/
565: PetscErrorCode PetscOptionsPrint(FILE *fd)
566: {
568: PetscInt i;
571: if (!fd) fd = PETSC_STDOUT;
572: if (!options) {PetscOptionsInsert(0,0,0);}
573: if (options->N) {
574: PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
575: } else {
576: PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
577: }
578: for (i=0; i<options->N; i++) {
579: if (options->values[i]) {
580: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
581: } else {
582: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
583: }
584: }
585: if (options->N) {
586: PetscFPrintf(PETSC_COMM_WORLD,fd,"#End o PETSc Option Table entries\n");
587: }
588: return(0);
589: }
593: /*@C
594: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
596: Not Collective
598: Output Parameter:
599: . copts - pointer where string pointer is stored
601: Level: advanced
603: Concepts: options database^listing
605: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
606: @*/
607: PetscErrorCode PetscOptionsGetAll(char *copts[])
608: {
610: PetscInt i;
611: size_t len = 1,lent;
612: char *coptions;
615: if (!options) {PetscOptionsInsert(0,0,0);}
617: /* count the length of the required string */
618: for (i=0; i<options->N; i++) {
619: PetscStrlen(options->names[i],&lent);
620: len += 2 + lent;
621: if (options->values[i]) {
622: PetscStrlen(options->values[i],&lent);
623: len += 1 + lent;
624: }
625: }
626: PetscMalloc(len*sizeof(char),&coptions);
627: coptions[0] = 0;
628: for (i=0; i<options->N; i++) {
629: PetscStrcat(coptions,"-");
630: PetscStrcat(coptions,options->names[i]);
631: PetscStrcat(coptions," ");
632: if (options->values[i]) {
633: PetscStrcat(coptions,options->values[i]);
634: PetscStrcat(coptions," ");
635: }
636: }
637: *copts = coptions;
638: return(0);
639: }
643: /*@C
644: PetscOptionsClear - Removes all options form the database leaving it empty.
646: Level: developer
648: .seealso: PetscOptionsInsert()
649: @*/
650: PetscErrorCode PetscOptionsClear(void)
651: {
652: PetscInt i;
655: if (!options) return(0);
656: for (i=0; i<options->N; i++) {
657: if (options->names[i]) free(options->names[i]);
658: if (options->values[i]) free(options->values[i]);
659: }
660: for (i=0; i<options->Naliases; i++) {
661: free(options->aliases1[i]);
662: free(options->aliases2[i]);
663: }
664: options->N = 0;
665: options->Naliases = 0;
666: return(0);
667: }
671: /*@C
672: PetscOptionsDestroy - Destroys the option database.
674: Note:
675: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
676: typically does not need to call this routine.
678: Level: developer
680: .seealso: PetscOptionsInsert()
681: @*/
682: PetscErrorCode PetscOptionsDestroy(void)
683: {
687: if (!options) return(0);
688: PetscOptionsClear();
689: free(options);
690: options = 0;
691: return(0);
692: }
696: /*@C
697: PetscOptionsSetValue - Sets an option name-value pair in the options
698: database, overriding whatever is already present.
700: Not collective, but setting values on certain processors could cause problems
701: for parallel objects looking for options.
703: Input Parameters:
704: + name - name of option, this SHOULD have the - prepended
705: - value - the option value (not used for all options)
707: Level: intermediate
709: Note:
710: Only some options have values associated with them, such as
711: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
713: Concepts: options database^adding option
715: .seealso: PetscOptionsInsert()
716: @*/
717: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
718: {
719: size_t len;
721: PetscInt N,n,i;
722: char **names;
723: const char *name = (char*)iname;
724: PetscTruth gt,match;
727: if (!options) {PetscOptionsInsert(0,0,0);}
729: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
730: PetscStrcasecmp(name,"-h",&match);
731: if (match) name = "-help";
733: name++;
734: /* first check against aliases */
735: N = options->Naliases;
736: for (i=0; i<N; i++) {
737: PetscStrcasecmp(options->aliases1[i],name,&match);
738: if (match) {
739: name = options->aliases2[i];
740: break;
741: }
742: }
744: N = options->N;
745: n = N;
746: names = options->names;
747:
748: for (i=0; i<N; i++) {
749: PetscStrcasecmp(names[i],name,&match);
750: PetscStrgrt(names[i],name,>);
751: if (match) {
752: if (options->values[i]) free(options->values[i]);
753: PetscStrlen(value,&len);
754: if (len) {
755: options->values[i] = (char*)malloc((len+1)*sizeof(char));
756: PetscStrcpy(options->values[i],value);
757: } else { options->values[i] = 0;}
758: PetscOptionsMonitor(name,value);
759: return(0);
760: } else if (gt) {
761: n = i;
762: break;
763: }
764: }
765: if (N >= MAXOPTIONS) {
766: 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);
767: }
768: /* shift remaining values down 1 */
769: for (i=N; i>n; i--) {
770: options->names[i] = options->names[i-1];
771: options->values[i] = options->values[i-1];
772: options->used[i] = options->used[i-1];
773: }
774: /* insert new name and value */
775: PetscStrlen(name,&len);
776: options->names[n] = (char*)malloc((len+1)*sizeof(char));
777: PetscStrcpy(options->names[n],name);
778: PetscStrlen(value,&len);
779: if (len) {
780: options->values[n] = (char*)malloc((len+1)*sizeof(char));
781: PetscStrcpy(options->values[n],value);
782: } else {options->values[n] = 0;}
783: options->used[n] = PETSC_FALSE;
784: options->N++;
785: PetscOptionsMonitor(name,value);
786: return(0);
787: }
791: /*@C
792: PetscOptionsClearValue - Clears an option name-value pair in the options
793: database, overriding whatever is already present.
795: Not Collective, but setting values on certain processors could cause problems
796: for parallel objects looking for options.
798: Input Parameter:
799: . name - name of option, this SHOULD have the - prepended
801: Level: intermediate
803: Concepts: options database^removing option
804: .seealso: PetscOptionsInsert()
805: @*/
806: PetscErrorCode PetscOptionsClearValue(const char iname[])
807: {
809: PetscInt N,n,i;
810: char **names,*name=(char*)iname;
811: PetscTruth gt,match;
814: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
815: if (!options) {PetscOptionsInsert(0,0,0);}
817: name++;
819: N = options->N; n = 0;
820: names = options->names;
821:
822: for (i=0; i<N; i++) {
823: PetscStrcasecmp(names[i],name,&match);
824: PetscStrgrt(names[i],name,>);
825: if (match) {
826: if (options->names[i]) free(options->names[i]);
827: if (options->values[i]) free(options->values[i]);
828: PetscOptionsMonitor(name,"");
829: break;
830: } else if (gt) {
831: return(0); /* it was not listed */
832: }
833: n++;
834: }
835: if (n == N) return(0); /* it was not listed */
837: /* shift remaining values down 1 */
838: for (i=n; i<N-1; i++) {
839: options->names[i] = options->names[i+1];
840: options->values[i] = options->values[i+1];
841: options->used[i] = options->used[i+1];
842: }
843: options->N--;
844: return(0);
845: }
849: /*@C
850: PetscOptionsReject - Generates an error if a certain option is given.
852: Not Collective, but setting values on certain processors could cause problems
853: for parallel objects looking for options.
855: Input Parameters:
856: + name - the option one is seeking
857: - mess - error message (may be PETSC_NULL)
859: Level: advanced
861: Concepts: options database^rejecting option
863: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
864: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
865: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
866: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
867: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
868: PetscOptionsList(), PetscOptionsEList()
869: @*/
870: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
871: {
873: PetscInt n = options->Naliases;
874: size_t len;
875: char *newname = (char *)inewname,*oldname = (char*)ioldname;
878: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
879: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
880: if (n >= MAXALIASES) {
881: 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);
882: }
884: newname++; oldname++;
885: PetscStrlen(newname,&len);
886: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
887: PetscStrcpy(options->aliases1[n],newname);
888: PetscStrlen(oldname,&len);
889: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
890: PetscStrcpy(options->aliases2[n],oldname);
891: options->Naliases++;
892: return(0);
893: }
897: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
898: {
900: PetscInt i,N;
901: size_t len;
902: char **names,tmp[256];
903: PetscTruth match;
906: if (!options) {PetscOptionsInsert(0,0,0);}
907: N = options->N;
908: names = options->names;
910: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
912: /* append prefix to name */
913: if (pre) {
914: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
915: PetscStrncpy(tmp,pre,256);
916: PetscStrlen(tmp,&len);
917: PetscStrncat(tmp,name+1,256-len-1);
918: } else {
919: PetscStrncpy(tmp,name+1,256);
920: }
922: /* slow search */
923: *flg = PETSC_FALSE;
924: for (i=0; i<N; i++) {
925: PetscStrcasecmp(names[i],tmp,&match);
926: if (match) {
927: *value = options->values[i];
928: options->used[i] = PETSC_TRUE;
929: *flg = PETSC_TRUE;
930: break;
931: }
932: }
933: if (!*flg) {
934: PetscInt j,cnt = 0,locs[16],loce[16];
935: size_t n;
936: PetscStrlen(tmp,&n);
937: /* determine the location and number of all _%d_ in the key */
938: for (i=0; i< (PetscInt)n; i++) {
939: if (tmp[i] == '_') {
940: for (j=i+1; j< (PetscInt)n; j++) {
941: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
942: if (tmp[j] == '_' && j > i+1) { /* found a number */
943: locs[cnt] = i+1;
944: loce[cnt++] = j+1;
945: }
946: break;
947: }
948: }
949: }
950: if (cnt) {
951: char tmp2[256];
952: for (i=0; i<cnt; i++) {
953: PetscStrcpy(tmp2,"-");
954: PetscStrncat(tmp2,tmp,locs[i]);
955: PetscStrcat(tmp2,tmp+loce[i]);
956: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
957: if (*flg) break;
958: }
959: }
960: }
961: return(0);
962: }
966: /*@C
967: PetscOptionsReject - Generates an error if a certain option is given.
969: Not Collective, but setting values on certain processors could cause problems
970: for parallel objects looking for options.
972: Input Parameters:
973: + name - the option one is seeking
974: - mess - error message (may be PETSC_NULL)
976: Level: advanced
978: Concepts: options database^rejecting option
980: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
981: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
982: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
983: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
984: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
985: PetscOptionsList(), PetscOptionsEList()
986: @*/
987: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
988: {
990: PetscTruth flag;
993: PetscOptionsHasName(PETSC_NULL,name,&flag);
994: if (flag) {
995: if (mess) {
996: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
997: } else {
998: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
999: }
1000: }
1001: return(0);
1002: }
1006: /*@C
1007: PetscOptionsHasName - Determines whether a certain option is given in the database.
1009: Not Collective
1011: Input Parameters:
1012: + name - the option one is seeking
1013: - pre - string to prepend to the name or PETSC_NULL
1015: Output Parameters:
1016: . flg - PETSC_TRUE if found else PETSC_FALSE.
1018: Level: beginner
1020: Concepts: options database^has option name
1022: Notes: Name cannot be simply -h
1024: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1025: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1026: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1027: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1028: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1029: PetscOptionsList(), PetscOptionsEList()
1030: @*/
1031: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1032: {
1033: char *value;
1035: PetscTruth isfalse,flag;
1038: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1040: /* remove if turned off */
1041: if (flag) {
1042: PetscStrcasecmp(value,"FALSE",&isfalse);
1043: if (isfalse) flag = PETSC_FALSE;
1044: PetscStrcasecmp(value,"NO",&isfalse);
1045: if (isfalse) flag = PETSC_FALSE;
1046: PetscStrcasecmp(value,"0",&isfalse);
1047: if (isfalse) flag = PETSC_FALSE;
1048: }
1049: if (flg) *flg = flag;
1050: return(0);
1051: }
1055: /*@C
1056: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1058: Not Collective
1060: Input Parameters:
1061: + pre - the string to prepend to the name or PETSC_NULL
1062: - name - the option one is seeking
1064: Output Parameter:
1065: + ivalue - the integer value to return
1066: - flg - PETSC_TRUE if found, else PETSC_FALSE
1068: Level: beginner
1070: Concepts: options database^has int
1072: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
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()
1079: @*/
1080: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1081: {
1082: char *value;
1084: PetscTruth flag;
1089: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1090: if (flag) {
1091: if (!value) {if (flg) *flg = PETSC_FALSE;}
1092: else {
1093: if (flg) *flg = PETSC_TRUE;
1094: PetscOptionsAtoi(value,ivalue);
1095: }
1096: } else {
1097: if (flg) *flg = PETSC_FALSE;
1098: }
1099: return(0);
1100: }
1104: /*@C
1105: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1107: Not Collective
1109: Input Parameters:
1110: + pre - the string to prepend to the name or PETSC_NULL
1111: . opt - option name
1112: . list - the possible choices
1113: . ntext - number of choices
1115: Output Parameter:
1116: + value - the index of the value to return
1117: - set - PETSC_TRUE if found, else PETSC_FALSE
1118:
1119: Level: intermediate
1121: See PetscOptionsList() for when the choices are given in a PetscFList()
1123: Concepts: options database^list
1125: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1126: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1127: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1128: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1129: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1130: PetscOptionsList(), PetscOptionsEList()
1131: @*/
1132: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1133: {
1135: size_t alen,len = 0;
1136: char *svalue;
1137: PetscTruth aset,flg = PETSC_FALSE;
1138: PetscInt i;
1141: for ( i=0; i<ntext; i++) {
1142: PetscStrlen(list[i],&alen);
1143: if (alen > len) len = alen;
1144: }
1145: len += 5; /* a little extra space for user mistypes */
1146: PetscMalloc(len*sizeof(char),&svalue);
1147: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1148: if (aset) {
1149: if (set) *set = PETSC_TRUE;
1150: for (i=0; i<ntext; i++) {
1151: PetscStrcasecmp(svalue,list[i],&flg);
1152: if (flg) {
1153: *value = i;
1154: break;
1155: }
1156: }
1157: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1158: } else if (set) {
1159: *set = PETSC_FALSE;
1160: }
1161: PetscFree(svalue);
1162: return(0);
1163: }
1167: /*@C
1168: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1170: Not Collective
1172: Input Parameters:
1173: + pre - option prefix or PETSC_NULL
1174: . opt - option name
1175: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1176: - defaultv - the default (current) value
1178: Output Parameter:
1179: + value - the value to return
1180: - flg - PETSC_TRUE if found, else PETSC_FALSE
1182: Level: beginner
1184: Concepts: options database
1186: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1188: list is usually something like PCASMTypes or some other predefined list of enum names
1190: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1191: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1192: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1193: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1194: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1195: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1196: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1197: @*/
1198: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1199: {
1201: PetscInt ntext = 0;
1204: while (list[ntext++]) {
1205: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1206: }
1207: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1208: ntext -= 3;
1209: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1210: return(0);
1211: }
1215: /*@C
1216: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1217: option in the database.
1219: Not Collective
1221: Input Parameters:
1222: + pre - the string to prepend to the name or PETSC_NULL
1223: - name - the option one is seeking
1225: Output Parameter:
1226: + ivalue - the logical value to return
1227: - flg - PETSC_TRUE if found, else PETSC_FALSE
1229: Level: beginner
1231: Notes:
1232: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1233: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1235: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1236: you NEED TO ALWAYS initialize the ivalue.
1238: Concepts: options database^has logical
1240: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1241: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1242: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1243: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1244: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1245: PetscOptionsList(), PetscOptionsEList()
1246: @*/
1247: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1248: {
1249: char *value;
1250: PetscTruth flag;
1256: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1257: if (flag) {
1258: if (flg) *flg = PETSC_TRUE;
1259: if (!value) {
1260: *ivalue = PETSC_TRUE;
1261: } else {
1262: PetscOptionsAtol(value, ivalue);
1263: }
1264: } else {
1265: if (flg) *flg = PETSC_FALSE;
1266: }
1267: return(0);
1268: }
1272: /*@C
1273: PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular
1274: option in the database. The values must be separated with commas with
1275: no intervening spaces.
1277: Not Collective
1279: Input Parameters:
1280: + pre - string to prepend to each name or PETSC_NULL
1281: . name - the option one is seeking
1282: - nmax - maximum number of values to retrieve
1284: Output Parameter:
1285: + dvalue - the integer values to return
1286: . nmax - actual number of values retreived
1287: - flg - PETSC_TRUE if found, else PETSC_FALSE
1289: Level: beginner
1291: Concepts: options database^array of ints
1293: Notes:
1294: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1295: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1297: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1298: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1299: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1300: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1301: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1302: PetscOptionsList(), PetscOptionsEList()
1303: @*/
1304: PetscErrorCode PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1305: {
1306: char *value;
1308: PetscInt n = 0;
1309: PetscTruth flag;
1310: PetscToken token;
1315: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1316: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1317: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1319: if (flg) *flg = PETSC_TRUE;
1321: PetscTokenCreate(value,',',&token);
1322: PetscTokenFind(token,&value);
1323: while (n < *nmax) {
1324: if (!value) break;
1325: PetscOptionsAtol(value,dvalue);
1326: PetscTokenFind(token,&value);
1327: dvalue++;
1328: n++;
1329: }
1330: PetscTokenDestroy(token);
1331: *nmax = n;
1332: return(0);
1333: }
1337: /*@C
1338: PetscOptionsGetReal - Gets the double precision value for a particular
1339: option in the database.
1341: Not Collective
1343: Input Parameters:
1344: + pre - string to prepend to each name or PETSC_NULL
1345: - name - the option one is seeking
1347: Output Parameter:
1348: + dvalue - the double value to return
1349: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1351: Level: beginner
1353: Concepts: options database^has double
1355: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1356: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1357: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1358: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1359: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1360: PetscOptionsList(), PetscOptionsEList()
1361: @*/
1362: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1363: {
1364: char *value;
1366: PetscTruth flag;
1371: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1372: if (flag) {
1373: if (!value) {if (flg) *flg = PETSC_FALSE;}
1374: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1375: } else {
1376: if (flg) *flg = PETSC_FALSE;
1377: }
1378: return(0);
1379: }
1383: /*@C
1384: PetscOptionsGetScalar - Gets the scalar value for a particular
1385: option in the database.
1387: Not Collective
1389: Input Parameters:
1390: + pre - string to prepend to each name or PETSC_NULL
1391: - name - the option one is seeking
1393: Output Parameter:
1394: + dvalue - the double value to return
1395: - flg - PETSC_TRUE if found, else PETSC_FALSE
1397: Level: beginner
1399: Usage:
1400: A complex number 2+3i can be specified as 2,3 at the command line.
1401: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1403: Concepts: options database^has scalar
1405: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1406: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1407: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1408: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1409: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1410: PetscOptionsList(), PetscOptionsEList()
1411: @*/
1412: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1413: {
1414: char *value;
1415: PetscTruth flag;
1421: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1422: if (flag) {
1423: if (!value) {
1424: if (flg) *flg = PETSC_FALSE;
1425: } else {
1426: #if !defined(PETSC_USE_COMPLEX)
1427: PetscOptionsAtod(value,dvalue);
1428: #else
1429: PetscReal re=0.0,im=0.0;
1430: PetscToken token;
1431: char *tvalue = 0;
1433: PetscTokenCreate(value,',',&token);
1434: PetscTokenFind(token,&tvalue);
1435: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1436: PetscOptionsAtod(tvalue,&re);
1437: PetscTokenFind(token,&tvalue);
1438: if (!tvalue) { /* Unknown separator used. using only real value */
1439: *dvalue = re;
1440: } else {
1441: PetscOptionsAtod(tvalue,&im);
1442: *dvalue = re + PETSC_i*im;
1443: }
1444: PetscTokenDestroy(token);
1445: #endif
1446: if (flg) *flg = PETSC_TRUE;
1447: }
1448: } else { /* flag */
1449: if (flg) *flg = PETSC_FALSE;
1450: }
1451: return(0);
1452: }
1456: /*@C
1457: PetscOptionsGetRealArray - Gets an array of double precision values for a
1458: particular option in the database. The values must be separated with
1459: commas with no intervening spaces.
1461: Not Collective
1463: Input Parameters:
1464: + pre - string to prepend to each name or PETSC_NULL
1465: . name - the option one is seeking
1466: - nmax - maximum number of values to retrieve
1468: Output Parameters:
1469: + dvalue - the double value to return
1470: . nmax - actual number of values retreived
1471: - flg - PETSC_TRUE if found, else PETSC_FALSE
1473: Level: beginner
1475: Concepts: options database^array of doubles
1477: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1478: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1479: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1480: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1481: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1482: PetscOptionsList(), PetscOptionsEList()
1483: @*/
1484: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1485: {
1486: char *value;
1488: PetscInt n = 0;
1489: PetscTruth flag;
1490: PetscToken token;
1495: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1496: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1497: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1499: if (flg) *flg = PETSC_TRUE;
1501: PetscTokenCreate(value,',',&token);
1502: PetscTokenFind(token,&value);
1503: while (n < *nmax) {
1504: if (!value) break;
1505: PetscOptionsAtod(value,dvalue++);
1506: PetscTokenFind(token,&value);
1507: n++;
1508: }
1509: PetscTokenDestroy(token);
1510: *nmax = n;
1511: return(0);
1512: }
1516: /*@C
1517: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1518: option in the database. The values must be separated with commas with
1519: no intervening spaces.
1521: Not Collective
1523: Input Parameters:
1524: + pre - string to prepend to each name or PETSC_NULL
1525: . name - the option one is seeking
1526: - nmax - maximum number of values to retrieve
1528: Output Parameter:
1529: + dvalue - the integer values to return
1530: . nmax - actual number of values retreived
1531: - flg - PETSC_TRUE if found, else PETSC_FALSE
1533: Level: beginner
1535: Concepts: options database^array of ints
1537: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1538: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1539: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1540: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1541: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1542: PetscOptionsList(), PetscOptionsEList()
1543: @*/
1544: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1545: {
1546: char *value;
1548: PetscInt n = 0,i,start,end;
1549: size_t len;
1550: PetscTruth flag,foundrange;
1551: PetscToken token;
1556: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1557: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1558: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1560: if (flg) *flg = PETSC_TRUE;
1562: PetscTokenCreate(value,',',&token);
1563: PetscTokenFind(token,&value);
1564: while (n < *nmax) {
1565: if (!value) break;
1566:
1567: /* look for form d-D where d and D are integers */
1568: foundrange = PETSC_FALSE;
1569: PetscStrlen(value,&len);
1570: if (value[0] == '-') i=2;
1571: else i=1;
1572: for (;i<(int)len; i++) {
1573: if (value[i] == '-') {
1574: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1575: value[i] = 0;
1576: PetscOptionsAtoi(value,&start);
1577: PetscOptionsAtoi(value+i+1,&end);
1578: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1579: 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);
1580: for (;start<end; start++) {
1581: *dvalue = start; dvalue++;n++;
1582: }
1583: foundrange = PETSC_TRUE;
1584: break;
1585: }
1586: }
1587: if (!foundrange) {
1588: PetscOptionsAtoi(value,dvalue);
1589: dvalue++;
1590: n++;
1591: }
1592: PetscTokenFind(token,&value);
1593: }
1594: PetscTokenDestroy(token);
1595: *nmax = n;
1596: return(0);
1597: }
1601: /*@C
1602: PetscOptionsGetString - Gets the string value for a particular option in
1603: the database.
1605: Not Collective
1607: Input Parameters:
1608: + pre - string to prepend to name or PETSC_NULL
1609: . name - the option one is seeking
1610: - len - maximum string length
1612: Output Parameters:
1613: + string - location to copy string
1614: - flg - PETSC_TRUE if found, else PETSC_FALSE
1616: Level: beginner
1618: Fortran Note:
1619: The Fortran interface is slightly different from the C/C++
1620: interface (len is not used). Sample usage in Fortran follows
1621: .vb
1622: character *20 string
1623: integer flg, ierr
1624: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1625: .ve
1627: Concepts: options database^string
1629: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1630: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1631: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1632: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1633: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1634: PetscOptionsList(), PetscOptionsEList()
1635: @*/
1636: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1637: {
1638: char *value;
1640: PetscTruth flag;
1645: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1646: if (!flag) {
1647: if (flg) *flg = PETSC_FALSE;
1648: } else {
1649: if (flg) *flg = PETSC_TRUE;
1650: if (value) {
1651: PetscStrncpy(string,value,len);
1652: } else {
1653: PetscMemzero(string,len);
1654: }
1655: }
1656: return(0);
1657: }
1661: /*@C
1662: PetscOptionsGetStringArray - Gets an array of string values for a particular
1663: option in the database. The values must be separated with commas with
1664: no intervening spaces.
1666: Not Collective
1668: Input Parameters:
1669: + pre - string to prepend to name or PETSC_NULL
1670: . name - the option one is seeking
1671: - nmax - maximum number of strings
1673: Output Parameter:
1674: + strings - location to copy strings
1675: - flg - PETSC_TRUE if found, else PETSC_FALSE
1677: Level: beginner
1679: Notes:
1680: The user should pass in an array of pointers to char, to hold all the
1681: strings returned by this function.
1683: The user is responsible for deallocating the strings that are
1684: returned. The Fortran interface for this routine is not supported.
1686: Contributed by Matthew Knepley.
1688: Concepts: options database^array of strings
1690: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1691: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1692: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1693: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1694: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1695: PetscOptionsList(), PetscOptionsEList()
1696: @*/
1697: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1698: {
1699: char *value;
1701: PetscInt n;
1702: PetscTruth flag;
1703: PetscToken token;
1704:
1708: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1709: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1710: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1711: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1712: if (flg) *flg = PETSC_TRUE;
1714: PetscTokenCreate(value,',',&token);
1715: PetscTokenFind(token,&value);
1716: n = 0;
1717: while (n < *nmax) {
1718: if (!value) break;
1719: PetscStrallocpy(value,&strings[n]);
1720: PetscTokenFind(token,&value);
1721: n++;
1722: }
1723: PetscTokenDestroy(token);
1724: *nmax = n;
1725: return(0);
1726: }
1730: /*@C
1731: PetscOptionsAllUsed - Returns a count of the number of options in the
1732: database that have never been selected.
1734: Not Collective
1736: Output Parameter:
1737: . N - count of options not used
1739: Level: advanced
1741: .seealso: PetscOptionsPrint()
1742: @*/
1743: PetscErrorCode PetscOptionsAllUsed(int *N)
1744: {
1745: PetscInt i,n = 0;
1748: for (i=0; i<options->N; i++) {
1749: if (!options->used[i]) { n++; }
1750: }
1751: *N = n;
1752: return(0);
1753: }
1757: /*@
1758: PetscOptionsLeft - Prints to screen any options that were set and never used.
1760: Not collective
1762: Options Database Key:
1763: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1765: Level: advanced
1767: .seealso: PetscOptionsAllUsed()
1768: @*/
1769: PetscErrorCode PetscOptionsLeft(void)
1770: {
1772: PetscInt i;
1775: for (i=0; i<options->N; i++) {
1776: if (!options->used[i]) {
1777: if (options->values[i]) {
1778: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1779: } else {
1780: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1781: }
1782: }
1783: }
1784: return(0);
1785: }
1788: /*
1789: PetscOptionsCreate - Creates the empty options database.
1791: */
1794: PetscErrorCode PetscOptionsCreate(void)
1795: {
1799: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1800: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1801: options->namegiven = PETSC_FALSE;
1802: options->N = 0;
1803: options->Naliases = 0;
1804: options->numbermonitors = 0;
1806: PetscOptionsObject.prefix = PETSC_NULL;
1807: PetscOptionsObject.title = PETSC_NULL;
1808:
1809: return(0);
1810: }
1814: /*@
1815: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1817: Collective on PETSC_COMM_WORLD
1819: Options Database Keys:
1820: + -options_monitor <optional filename> - prints the names and values of all
1821: runtime options as they are set. The monitor functionality is not
1822: available for options set through a file, environment variable, or on
1823: the command line. Only options set after PetscInitialize completes will
1824: be monitored.
1825: . -options_monitor_cancel - cancel all options database monitors
1827: Notes:
1828: To see all options, run your program with the -help option or consult
1829: the users manual.
1831: Level: intermediate
1833: .keywords: set, options, database
1834: @*/
1835: PetscErrorCode PetscOptionsSetFromOptions(void)
1836: {
1837: PetscTruth flg;
1838: PetscErrorCode ierr;
1839: char monfilename[PETSC_MAX_PATH_LEN];
1840: PetscViewer monviewer;
1844: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1845: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1846: if (flg && (!options->numbermonitors)) {
1847: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1848: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1849: }
1850:
1851: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1852: if (flg) { PetscOptionsMonitorCancel(); }
1853:
1854: PetscOptionsEnd();
1856: return(0);
1857: }
1862: /*@C
1863: PetscOptionsMonitorDefault - Print all options set value events.
1865: Collective on PETSC_COMM_WORLD
1867: Input Parameters:
1868: + name - option name string
1869: . value - option value string
1870: - dummy - unused monitor context
1872: Level: intermediate
1874: .keywords: PetscOptions, default, monitor
1876: .seealso: PetscOptionsMonitorSet()
1877: @*/
1878: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1879: {
1881: PetscViewer viewer = (PetscViewer) dummy;
1884: if (!viewer) {
1885: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1886: }
1887: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1888: return(0);
1889: }
1893: /*@C
1894: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1895: modified the PETSc options database.
1896:
1897: Not collective
1899: Input Parameters:
1900: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1901: . mctx - [optional] context for private data for the
1902: monitor routine (use PETSC_NULL if no context is desired)
1903: - monitordestroy - [optional] routine that frees monitor context
1904: (may be PETSC_NULL)
1906: Calling Sequence of monitor:
1907: $ monitor (const char name[], const char value[], void *mctx)
1909: + name - option name string
1910: . value - option value string
1911: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1913: Options Database Keys:
1914: + -options_monitor - sets PetscOptionsMonitorDefault()
1915: - -options_monitor_cancel - cancels all monitors that have
1916: been hardwired into a code by
1917: calls to PetscOptionsMonitorSet(), but
1918: does not cancel those set via
1919: the options database.
1921: Notes:
1922: The default is to do nothing. To print the name and value of options
1923: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1924: with a null monitoring context.
1926: Several different monitoring routines may be set by calling
1927: PetscOptionsMonitorSet() multiple times; all will be called in the
1928: order in which they were set.
1930: Level: beginner
1932: .keywords: PetscOptions, set, monitor
1934: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1935: @*/
1936: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1937: {
1939: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1940: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1941: }
1942: options->monitor[options->numbermonitors] = monitor;
1943: options->monitordestroy[options->numbermonitors] = monitordestroy;
1944: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1945: return(0);
1946: }
1950: /*@
1951: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
1953: Not collective
1955: Options Database Key:
1956: . -options_monitor_cancel - Cancels all monitors that have
1957: been hardwired into a code by calls to PetscOptionsMonitorSet(),
1958: but does not cancel those set via the options database.
1960: Level: intermediate
1962: .keywords: PetscOptions, set, monitor
1964: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1965: @*/
1966: PetscErrorCode PetscOptionsMonitorCancel(void)
1967: {
1969: PetscInt i;
1972: for (i=0; i<options->numbermonitors; i++) {
1973: if (options->monitordestroy[i]) {
1974: (*options->monitordestroy[i])(options->monitorcontext[i]);
1975: }
1976: }
1977: options->numbermonitors = 0;
1978: return(0);
1979: }