Actual source code: options.c
1: #define PETSC_DLL
2: /*
3: These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
4: This provides the low-level interface, the high level interface is in aoptions.c
6: Some routines use regular malloc and free because it cannot know what malloc is requested with the
7: options database until it has already processed the input.
8: */
10: #include petscsys.h
11: #if defined(PETSC_HAVE_STDLIB_H)
12: #include <stdlib.h>
13: #endif
14: #if defined(PETSC_HAVE_MALLOC_H)
15: #include <malloc.h>
16: #endif
17: #if defined(PETSC_HAVE_SYS_PARAM_H)
18: #include "sys/param.h"
19: #endif
21: /*
22: This table holds all the options set by the user. For simplicity, we use a static size database
23: */
24: #define MAXOPTIONS 512
25: #define MAXALIASES 25
26: #define MAXOPTIONSMONITORS 5
28: typedef struct {
29: int N,argc,Naliases;
30: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
31: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
32: PetscTruth used[MAXOPTIONS];
33: PetscTruth namegiven;
34: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
36: /* --------User (or default) routines (most return -1 on error) --------*/
37: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
38: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*); /* */
39: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
40: PetscInt numbermonitors; /* to, for instance, detect options being set */
42: } PetscOptionsTable;
45: static PetscOptionsTable *options = 0;
48: /*
49: Options events monitor
50: */
51: #define PetscOptionsMonitor(name,value) \
52: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
53: for (_i=0; _i<_im; _i++) {\
54: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
55: } \
56: }
60: /*
61: PetscOptionsAtoi - Converts a string to an integer value. Handles special cases such as "default" and "decide"
62: */
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: /*
106: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
107: */
108: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
109: {
111: size_t len;
112: PetscTruth decide,tdefault;
115: PetscStrlen(name,&len);
116: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
118: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
119: if (!tdefault) {
120: PetscStrcasecmp(name,"DEFAULT",&tdefault);
121: }
122: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
123: if (!decide) {
124: PetscStrcasecmp(name,"DECIDE",&decide);
125: }
127: if (tdefault) {
128: *a = PETSC_DEFAULT;
129: } else if (decide) {
130: *a = PETSC_DECIDE;
131: } else {
132: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
133: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
134: }
135: *a = atof(name);
136: }
137: return(0);
138: }
142: /*
143: PetscOptionsAtol - Converts string to PetscTruth, handles cases like "yes", "no", "true", "false", "0", "1"
144: */
145: PetscErrorCode PetscOptionsAtol(const char value[], PetscTruth *a)
146: {
147: PetscTruth istrue, isfalse;
148: size_t len;
152: PetscStrlen(value, &len);
153: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
154: PetscStrcasecmp(value,"TRUE",&istrue);
155: if (istrue) {*a = PETSC_TRUE; return(0);}
156: PetscStrcasecmp(value,"YES",&istrue);
157: if (istrue) {*a = PETSC_TRUE; return(0);}
158: PetscStrcasecmp(value,"1",&istrue);
159: if (istrue) {*a = PETSC_TRUE; return(0);}
160: PetscStrcasecmp(value,"on",&istrue);
161: if (istrue) {*a = PETSC_TRUE; return(0);}
162: PetscStrcasecmp(value,"FALSE",&isfalse);
163: if (isfalse) {*a = PETSC_FALSE; return(0);}
164: PetscStrcasecmp(value,"NO",&isfalse);
165: if (isfalse) {*a = PETSC_FALSE; return(0);}
166: PetscStrcasecmp(value,"0",&isfalse);
167: if (isfalse) {*a = PETSC_FALSE; return(0);}
168: PetscStrcasecmp(value,"off",&isfalse);
169: if (isfalse) {*a = PETSC_FALSE; return(0);}
170: SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
171: return(0);
172: }
176: /*@C
177: PetscGetProgramName - Gets the name of the running program.
179: Not Collective
181: Input Parameter:
182: . len - length of the string name
184: Output Parameter:
185: . name - the name of the running program
187: Level: advanced
189: Notes:
190: The name of the program is copied into the user-provided character
191: array of length len. On some machines the program name includes
192: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
193: @*/
194: PetscErrorCode PetscGetProgramName(char name[],size_t len)
195: {
199: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
200: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
201: PetscStrncpy(name,options->programname,len);
202: return(0);
203: }
207: PetscErrorCode PetscSetProgramName(const char name[])
208: {
212: options->namegiven = PETSC_TRUE;
213: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
214: return(0);
215: }
219: /*@
220: PetscOptionsValidKey - PETSc Options database keys must begin with a - followed by a letter.
222: Input Parameter:
223: . in_str - string to check if valid
225: Output Parameter:
226: . key - PETSC_TRUE if a valid key
228: Level: intermediate
230: @*/
231: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
232: {
234: *key = PETSC_FALSE;
235: if (!in_str) return(0);
236: if (in_str[0] != '-') return(0);
237: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
238: *key = PETSC_TRUE;
239: return(0);
240: }
244: /*@C
245: PetscOptionsInsertString - Inserts options into the database from a string
247: Not collective: but only processes that call this routine will set the options
248: included in the file
250: Input Parameter:
251: . in_str - string that contains options separated by blanks
254: Level: intermediate
256: Contributed by Boyana Norris
258: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
259: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
260: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
261: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
262: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
263: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
265: @*/
266: PetscErrorCode PetscOptionsInsertString(const char in_str[])
267: {
268: char *first,*second;
270: PetscToken token;
271: PetscTruth key;
274: PetscTokenCreate(in_str,' ',&token);
275: PetscTokenFind(token,&first);
276: while (first) {
277: PetscOptionsValidKey(first,&key);
278: if (key) {
279: PetscTokenFind(token,&second);
280: PetscOptionsValidKey(second,&key);
281: if (!key) {
282: PetscOptionsSetValue(first,second);
283: PetscTokenFind(token,&first);
284: } else {
285: PetscOptionsSetValue(first,PETSC_NULL);
286: first = second;
287: }
288: } else {
289: PetscTokenFind(token,&first);
290: }
291: }
292: PetscTokenDestroy(token);
293: return(0);
294: }
296: /*
297: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
298: */
299: static char *Petscgetline(FILE * f)
300: {
301: size_t size = 0;
302: size_t len = 0;
303: size_t last = 0;
304: char * buf = PETSC_NULL;
306: if (feof(f)) return 0;
307: do {
308: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
309: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
310: /* Actually do the read. Note that fgets puts a terminal '\0' on the
311: end of the string, so we make sure we overwrite this */
312: if (!fgets(buf+len,size,f)) buf[len]=0;
313: PetscStrlen(buf,&len);
314: last = len - 1;
315: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
316: if (len) return buf;
317: free(buf);
318: return 0;
319: }
324: /*@C
325: PetscOptionsInsertFile - Inserts options into the database from a file.
327: Collective on MPI_Comm
329: Input Parameter:
330: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
331: . file - name of file
332: - require - if PETSC_TRUE will generate an error if the file does not exist
335: Level: intermediate
337: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
338: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
339: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
340: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
341: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
342: PetscOptionsList(), PetscOptionsEList()
344: @*/
345: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
346: {
347: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
349: size_t i,len;
350: FILE *fd;
351: PetscToken token;
352: int err;
353: char cmt[3]={'#','!','%'},*cmatch;
354: PetscMPIInt rank,cnt=0,acnt=0;
357: MPI_Comm_rank(comm,&rank);
358: if (!rank) {
359: /* Warning: assume a maximum size for all options in a string */
360: PetscMalloc(128000*sizeof(char),&vstring);
361: vstring[0] = 0;
362: PetscMalloc(64000*sizeof(char),&astring);
363: astring[0] = 0;
364: cnt = 0;
365: acnt = 0;
367: PetscFixFilename(file,fname);
368: fd = fopen(fname,"r");
369: if (fd) {
370: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
371: PetscInfo1(0,"Opened options file %s\n",file);
372: while ((string = Petscgetline(fd))) {
373: /* eliminate comments from each line */
374: for (i=0; i<3; i++){
375: PetscStrchr(string,cmt[i],&cmatch);
376: if (cmatch) *cmatch = 0;
377: }
378: PetscStrlen(string,&len);
379: /* replace tabs, ^M, \n with " " */
380: for (i=0; i<len; i++) {
381: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
382: string[i] = ' ';
383: }
384: }
385: PetscTokenCreate(string,' ',&token);
386: free(string);
387: PetscTokenFind(token,&first);
388: if (!first) {
389: goto destroy;
390: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
391: PetscTokenFind(token,&first);
392: }
393: PetscTokenFind(token,&second);
394: if (!first) {
395: goto destroy;
396: } else if (first[0] == '-') {
397: /* warning: should be making sure we do not overfill vstring */
398: PetscStrcat(vstring,first);
399: PetscStrcat(vstring," ");
400: if (second) {
401: /* protect second with quotes in case it contains strings */
402: PetscStrcat(vstring,"\"");
403: PetscStrcat(vstring,second);
404: PetscStrcat(vstring,"\"");
405: }
406: PetscStrcat(vstring," ");
407: } else {
408: PetscTruth match;
410: PetscStrcasecmp(first,"alias",&match);
411: if (match) {
412: PetscTokenFind(token,&third);
413: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
414: PetscStrcat(astring,second);
415: PetscStrcat(astring," ");
416: PetscStrcat(astring,third);
417: PetscStrcat(astring," ");
418: } else {
419: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
420: }
421: }
422: destroy:
423: PetscTokenDestroy(token);
424: }
425: err = fclose(fd);
426: if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
427: PetscStrlen(astring,&len);
428: acnt = PetscMPIIntCast(len);
429: PetscStrlen(vstring,&len);
430: cnt = PetscMPIIntCast(len);
431: } else if (require) {
432: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
433: }
434: }
436: MPI_Bcast(&acnt,1,MPI_INT,0,comm);
437: if (acnt) {
438: PetscToken token;
439: char *first,*second;
441: if (rank) {
442: PetscMalloc((acnt+1)*sizeof(char),&astring);
443: }
444: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
445: astring[acnt] = 0;
446: PetscTokenCreate(astring,' ',&token);
447: PetscTokenFind(token,&first);
448: while (first) {
449: PetscTokenFind(token,&second);
450: PetscOptionsSetAlias(first,second);
451: PetscTokenFind(token,&first);
452: }
453: PetscTokenDestroy(token);
454: }
456: MPI_Bcast(&cnt,1,MPI_INT,0,comm);
457: if (cnt) {
458: if (rank) {
459: PetscMalloc((cnt+1)*sizeof(char),&vstring);
460: }
461: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
462: vstring[cnt] = 0;
463: PetscOptionsInsertString(vstring);
464: }
465: PetscFree(astring);
466: PetscFree(vstring);
467: return(0);
468: }
472: /*@C
473: PetscOptionsInsert - Inserts into the options database from the command line,
474: the environmental variable and a file.
476: Input Parameters:
477: + argc - count of number of command line arguments
478: . args - the command line arguments
479: - file - optional filename, defaults to ~username/.petscrc
481: Note:
482: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
483: the user does not typically need to call this routine. PetscOptionsInsert()
484: can be called several times, adding additional entries into the database.
486: Options Database Keys:
487: + -options_monitor <optional filename> - print options names and values as they are set
489: Level: advanced
491: Concepts: options database^adding
493: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
494: PetscInitialize()
495: @*/
496: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
497: {
499: PetscMPIInt rank;
500: char pfile[PETSC_MAX_PATH_LEN];
501: PetscTruth flag = PETSC_FALSE;
504: if (options == PETSC_NULL) {
505: fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
506: MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
507: }
508: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
510: options->argc = (argc) ? *argc : 0;
511: options->args = (args) ? *args : PETSC_NULL;
513: if (file) {
514: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
515: }
516: PetscOptionsGetTruth(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
517: if (!flag) {
518: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
519: /* warning: assumes all processes have a home directory or none, but nothing in between */
520: if (pfile[0]) {
521: PetscStrcat(pfile,"/.petscrc");
522: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
523: }
524: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
525: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
526: }
528: /* insert environmental options */
529: {
530: char *eoptions = 0;
531: size_t len = 0;
532: if (!rank) {
533: eoptions = (char*)getenv("PETSC_OPTIONS");
534: PetscStrlen(eoptions,&len);
535: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
536: } else {
537: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
538: if (len) {
539: PetscMalloc((len+1)*sizeof(char*),&eoptions);
540: }
541: }
542: if (len) {
543: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
544: if (rank) eoptions[len] = 0;
545: PetscOptionsInsertString(eoptions);
546: if (rank) {PetscFree(eoptions);}
547: }
548: }
550: /* insert command line options */
551: if (argc && args && *argc) {
552: int left = *argc - 1;
553: char **eargs = *args + 1;
554: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
556: while (left) {
557: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
558: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
559: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
560: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
561: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
562: isp4 = (PetscTruth) (isp4 || tisp4);
563: PetscStrcasecmp(eargs[0],"-np",&tisp4);
564: isp4 = (PetscTruth) (isp4 || tisp4);
565: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
567: if (eargs[0][0] != '-') {
568: eargs++; left--;
569: } else if (isoptions_file) {
570: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
571: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
572: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
573: eargs += 2; left -= 2;
575: /*
576: These are "bad" options that MPICH, etc put on the command line
577: we strip them out here.
578: */
579: } else if (tisp4 || isp4rmrank) {
580: eargs += 1; left -= 1;
581: } else if (isp4 || isp4yourname) {
582: eargs += 2; left -= 2;
583: } else if ((left < 2) || ((eargs[1][0] == '-') &&
584: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
585: PetscOptionsSetValue(eargs[0],PETSC_NULL);
586: eargs++; left--;
587: } else {
588: PetscOptionsSetValue(eargs[0],eargs[1]);
589: eargs += 2; left -= 2;
590: }
591: }
592: }
593: return(0);
594: }
598: /*@C
599: PetscOptionsPrint - Prints the options that have been loaded. This is
600: useful for debugging purposes.
602: Collective on PETSC_COMM_WORLD
604: Input Parameter:
605: . FILE fd - location to print options (usually stdout or stderr)
607: Options Database Key:
608: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
610: Level: advanced
612: Concepts: options database^printing
614: .seealso: PetscOptionsAllUsed()
615: @*/
616: PetscErrorCode PetscOptionsPrint(FILE *fd)
617: {
619: PetscInt i;
622: if (!fd) fd = PETSC_STDOUT;
623: if (!options) {PetscOptionsInsert(0,0,0);}
624: if (options->N) {
625: PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
626: } else {
627: PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
628: }
629: for (i=0; i<options->N; i++) {
630: if (options->values[i]) {
631: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
632: } else {
633: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
634: }
635: }
636: if (options->N) {
637: PetscFPrintf(PETSC_COMM_WORLD,fd,"#End of PETSc Option Table entries\n");
638: }
639: return(0);
640: }
644: /*@C
645: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
647: Not Collective
649: Output Parameter:
650: . copts - pointer where string pointer is stored
652: Notes: the array and each entry in the array should be freed with PetscFree()
654: Level: advanced
656: Concepts: options database^listing
658: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
659: @*/
660: PetscErrorCode PetscOptionsGetAll(char *copts[])
661: {
663: PetscInt i;
664: size_t len = 1,lent;
665: char *coptions;
668: if (!options) {PetscOptionsInsert(0,0,0);}
670: /* count the length of the required string */
671: for (i=0; i<options->N; i++) {
672: PetscStrlen(options->names[i],&lent);
673: len += 2 + lent;
674: if (options->values[i]) {
675: PetscStrlen(options->values[i],&lent);
676: len += 1 + lent;
677: }
678: }
679: PetscMalloc(len*sizeof(char),&coptions);
680: coptions[0] = 0;
681: for (i=0; i<options->N; i++) {
682: PetscStrcat(coptions,"-");
683: PetscStrcat(coptions,options->names[i]);
684: PetscStrcat(coptions," ");
685: if (options->values[i]) {
686: PetscStrcat(coptions,options->values[i]);
687: PetscStrcat(coptions," ");
688: }
689: }
690: *copts = coptions;
691: return(0);
692: }
696: /*@C
697: PetscOptionsClear - Removes all options form the database leaving it empty.
699: Level: developer
701: .seealso: PetscOptionsInsert()
702: @*/
703: PetscErrorCode PetscOptionsClear(void)
704: {
705: PetscInt i;
708: if (!options) return(0);
709: for (i=0; i<options->N; i++) {
710: if (options->names[i]) free(options->names[i]);
711: if (options->values[i]) free(options->values[i]);
712: }
713: for (i=0; i<options->Naliases; i++) {
714: free(options->aliases1[i]);
715: free(options->aliases2[i]);
716: }
717: options->N = 0;
718: options->Naliases = 0;
719: return(0);
720: }
724: /*@C
725: PetscOptionsDestroy - Destroys the option database.
727: Note:
728: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
729: typically does not need to call this routine.
731: Level: developer
733: .seealso: PetscOptionsInsert()
734: @*/
735: PetscErrorCode PetscOptionsDestroy(void)
736: {
740: if (!options) return(0);
741: PetscOptionsClear();
742: free(options);
743: options = 0;
744: return(0);
745: }
749: /*@C
750: PetscOptionsSetValue - Sets an option name-value pair in the options
751: database, overriding whatever is already present.
753: Not collective, but setting values on certain processors could cause problems
754: for parallel objects looking for options.
756: Input Parameters:
757: + name - name of option, this SHOULD have the - prepended
758: - value - the option value (not used for all options)
760: Level: intermediate
762: Note:
763: Only some options have values associated with them, such as
764: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
766: Concepts: options database^adding option
768: .seealso: PetscOptionsInsert()
769: @*/
770: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
771: {
772: size_t len;
774: PetscInt N,n,i;
775: char **names;
776: const char *name = (char*)iname;
777: PetscTruth gt,match;
780: if (!options) {PetscOptionsInsert(0,0,0);}
782: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
783: PetscStrcasecmp(name,"-h",&match);
784: if (match) name = "-help";
786: name++;
787: /* first check against aliases */
788: N = options->Naliases;
789: for (i=0; i<N; i++) {
790: PetscStrcasecmp(options->aliases1[i],name,&match);
791: if (match) {
792: name = options->aliases2[i];
793: break;
794: }
795: }
797: N = options->N;
798: n = N;
799: names = options->names;
800:
801: for (i=0; i<N; i++) {
802: PetscStrcasecmp(names[i],name,&match);
803: PetscStrgrt(names[i],name,>);
804: if (match) {
805: if (options->values[i]) free(options->values[i]);
806: PetscStrlen(value,&len);
807: if (len) {
808: options->values[i] = (char*)malloc((len+1)*sizeof(char));
809: PetscStrcpy(options->values[i],value);
810: } else { options->values[i] = 0;}
811: PetscOptionsMonitor(name,value);
812: return(0);
813: } else if (gt) {
814: n = i;
815: break;
816: }
817: }
818: if (N >= MAXOPTIONS) {
819: 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);
820: }
821: /* shift remaining values down 1 */
822: for (i=N; i>n; i--) {
823: options->names[i] = options->names[i-1];
824: options->values[i] = options->values[i-1];
825: options->used[i] = options->used[i-1];
826: }
827: /* insert new name and value */
828: PetscStrlen(name,&len);
829: options->names[n] = (char*)malloc((len+1)*sizeof(char));
830: PetscStrcpy(options->names[n],name);
831: PetscStrlen(value,&len);
832: if (len) {
833: options->values[n] = (char*)malloc((len+1)*sizeof(char));
834: PetscStrcpy(options->values[n],value);
835: } else {options->values[n] = 0;}
836: options->used[n] = PETSC_FALSE;
837: options->N++;
838: PetscOptionsMonitor(name,value);
839: return(0);
840: }
844: /*@C
845: PetscOptionsClearValue - Clears an option name-value pair in the options
846: database, overriding whatever is already present.
848: Not Collective, but setting values on certain processors could cause problems
849: for parallel objects looking for options.
851: Input Parameter:
852: . name - name of option, this SHOULD have the - prepended
854: Level: intermediate
856: Concepts: options database^removing option
857: .seealso: PetscOptionsInsert()
858: @*/
859: PetscErrorCode PetscOptionsClearValue(const char iname[])
860: {
862: PetscInt N,n,i;
863: char **names,*name=(char*)iname;
864: PetscTruth gt,match;
867: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
868: if (!options) {PetscOptionsInsert(0,0,0);}
870: name++;
872: N = options->N; n = 0;
873: names = options->names;
874:
875: for (i=0; i<N; i++) {
876: PetscStrcasecmp(names[i],name,&match);
877: PetscStrgrt(names[i],name,>);
878: if (match) {
879: if (options->names[i]) free(options->names[i]);
880: if (options->values[i]) free(options->values[i]);
881: PetscOptionsMonitor(name,"");
882: break;
883: } else if (gt) {
884: return(0); /* it was not listed */
885: }
886: n++;
887: }
888: if (n == N) return(0); /* it was not listed */
890: /* shift remaining values down 1 */
891: for (i=n; i<N-1; i++) {
892: options->names[i] = options->names[i+1];
893: options->values[i] = options->values[i+1];
894: options->used[i] = options->used[i+1];
895: }
896: options->N--;
897: return(0);
898: }
902: /*@C
903: PetscOptionsSetAlias - Makes a key and alias for another key
905: Not Collective, but setting values on certain processors could cause problems
906: for parallel objects looking for options.
908: Input Parameters:
909: + inewname - the alias
910: - ioldname - the name that alias will refer to
912: Level: advanced
914: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
915: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
916: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
917: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
918: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
919: PetscOptionsList(), PetscOptionsEList()
920: @*/
921: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
922: {
924: PetscInt n = options->Naliases;
925: size_t len;
926: char *newname = (char *)inewname,*oldname = (char*)ioldname;
929: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
930: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
931: if (n >= MAXALIASES) {
932: 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);
933: }
935: newname++; oldname++;
936: PetscStrlen(newname,&len);
937: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
938: PetscStrcpy(options->aliases1[n],newname);
939: PetscStrlen(oldname,&len);
940: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
941: PetscStrcpy(options->aliases2[n],oldname);
942: options->Naliases++;
943: return(0);
944: }
948: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
949: {
951: PetscInt i,N;
952: size_t len;
953: char **names,tmp[256];
954: PetscTruth match;
957: if (!options) {PetscOptionsInsert(0,0,0);}
958: N = options->N;
959: names = options->names;
961: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
963: /* append prefix to name */
964: if (pre) {
965: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
966: PetscStrncpy(tmp,pre,256);
967: PetscStrlen(tmp,&len);
968: PetscStrncat(tmp,name+1,256-len-1);
969: } else {
970: PetscStrncpy(tmp,name+1,256);
971: }
973: /* slow search */
974: *flg = PETSC_FALSE;
975: for (i=0; i<N; i++) {
976: PetscStrcasecmp(names[i],tmp,&match);
977: if (match) {
978: *value = options->values[i];
979: options->used[i] = PETSC_TRUE;
980: *flg = PETSC_TRUE;
981: break;
982: }
983: }
984: if (!*flg) {
985: PetscInt j,cnt = 0,locs[16],loce[16];
986: size_t n;
987: PetscStrlen(tmp,&n);
988: /* determine the location and number of all _%d_ in the key */
989: for (i=0; i< (PetscInt)n; i++) {
990: if (tmp[i] == '_') {
991: for (j=i+1; j< (PetscInt)n; j++) {
992: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
993: if (tmp[j] == '_' && j > i+1) { /* found a number */
994: locs[cnt] = i+1;
995: loce[cnt++] = j+1;
996: }
997: break;
998: }
999: }
1000: }
1001: if (cnt) {
1002: char tmp2[256];
1003: for (i=0; i<cnt; i++) {
1004: PetscStrcpy(tmp2,"-");
1005: PetscStrncat(tmp2,tmp,locs[i]);
1006: PetscStrcat(tmp2,tmp+loce[i]);
1007: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1008: if (*flg) break;
1009: }
1010: }
1011: }
1012: return(0);
1013: }
1017: /*@C
1018: PetscOptionsReject - Generates an error if a certain option is given.
1020: Not Collective, but setting values on certain processors could cause problems
1021: for parallel objects looking for options.
1023: Input Parameters:
1024: + name - the option one is seeking
1025: - mess - error message (may be PETSC_NULL)
1027: Level: advanced
1029: Concepts: options database^rejecting option
1031: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1032: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1033: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1034: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1035: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1036: PetscOptionsList(), PetscOptionsEList()
1037: @*/
1038: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1039: {
1041: PetscTruth flag = PETSC_FALSE;
1044: PetscOptionsHasName(PETSC_NULL,name,&flag);
1045: if (flag) {
1046: if (mess) {
1047: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1048: } else {
1049: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1050: }
1051: }
1052: return(0);
1053: }
1057: /*@C
1058: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1059: its value is set to false.
1061: Not Collective
1063: Input Parameters:
1064: + name - the option one is seeking
1065: - pre - string to prepend to the name or PETSC_NULL
1067: Output Parameters:
1068: . flg - PETSC_TRUE if found else PETSC_FALSE.
1070: Level: beginner
1072: Concepts: options database^has option name
1074: Notes: Name cannot be simply -h
1076: In many cases you probably want to use PetscOptionsGetTruth() instead of calling this, to allowing toggling values.
1078: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1079: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1080: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1081: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1082: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1083: PetscOptionsList(), PetscOptionsEList()
1084: @*/
1085: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1086: {
1087: char *value;
1089: PetscTruth flag;
1092: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1093: if (flg) *flg = flag;
1094: return(0);
1095: }
1099: /*@C
1100: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1102: Not Collective
1104: Input Parameters:
1105: + pre - the string to prepend to the name or PETSC_NULL
1106: - name - the option one is seeking
1108: Output Parameter:
1109: + ivalue - the integer value to return
1110: - flg - PETSC_TRUE if found, else PETSC_FALSE
1112: Level: beginner
1114: Concepts: options database^has int
1116: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1117: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1118: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1119: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1120: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1121: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1122: PetscOptionsList(), PetscOptionsEList()
1123: @*/
1124: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1125: {
1126: char *value;
1128: PetscTruth flag;
1133: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1134: if (flag) {
1135: if (!value) {if (flg) *flg = PETSC_FALSE;}
1136: else {
1137: if (flg) *flg = PETSC_TRUE;
1138: PetscOptionsAtoi(value,ivalue);
1139: }
1140: } else {
1141: if (flg) *flg = PETSC_FALSE;
1142: }
1143: return(0);
1144: }
1148: /*@C
1149: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1151: Not Collective
1153: Input Parameters:
1154: + pre - the string to prepend to the name or PETSC_NULL
1155: . opt - option name
1156: . list - the possible choices
1157: . ntext - number of choices
1159: Output Parameter:
1160: + value - the index of the value to return
1161: - set - PETSC_TRUE if found, else PETSC_FALSE
1162:
1163: Level: intermediate
1165: See PetscOptionsList() for when the choices are given in a PetscFList()
1167: Concepts: options database^list
1169: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1170: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1171: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1172: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1173: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1174: PetscOptionsList(), PetscOptionsEList()
1175: @*/
1176: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1177: {
1179: size_t alen,len = 0;
1180: char *svalue;
1181: PetscTruth aset,flg = PETSC_FALSE;
1182: PetscInt i;
1185: for ( i=0; i<ntext; i++) {
1186: PetscStrlen(list[i],&alen);
1187: if (alen > len) len = alen;
1188: }
1189: len += 5; /* a little extra space for user mistypes */
1190: PetscMalloc(len*sizeof(char),&svalue);
1191: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1192: if (aset) {
1193: if (set) *set = PETSC_TRUE;
1194: for (i=0; i<ntext; i++) {
1195: PetscStrcasecmp(svalue,list[i],&flg);
1196: if (flg) {
1197: *value = i;
1198: break;
1199: }
1200: }
1201: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1202: } else if (set) {
1203: *set = PETSC_FALSE;
1204: }
1205: PetscFree(svalue);
1206: return(0);
1207: }
1211: /*@C
1212: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1214: Not Collective
1216: Input Parameters:
1217: + pre - option prefix or PETSC_NULL
1218: . opt - option name
1219: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1220: - defaultv - the default (current) value
1222: Output Parameter:
1223: + value - the value to return
1224: - flg - PETSC_TRUE if found, else PETSC_FALSE
1226: Level: beginner
1228: Concepts: options database
1230: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1232: list is usually something like PCASMTypes or some other predefined list of enum names
1234: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1235: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1236: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1237: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1238: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1239: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1240: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1241: @*/
1242: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscTruth *set)
1243: {
1245: PetscInt ntext = 0,tval;
1246: PetscTruth fset;
1249: while (list[ntext++]) {
1250: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1251: }
1252: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1253: ntext -= 3;
1254: PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1255: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1256: if (fset) *value = (PetscEnum)tval;
1257: if (set) *set = fset;
1258: return(0);
1259: }
1263: /*@C
1264: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1265: option in the database.
1267: Not Collective
1269: Input Parameters:
1270: + pre - the string to prepend to the name or PETSC_NULL
1271: - name - the option one is seeking
1273: Output Parameter:
1274: + ivalue - the logical value to return
1275: - flg - PETSC_TRUE if found, else PETSC_FALSE
1277: Level: beginner
1279: Notes:
1280: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1281: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1283: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1284: you NEED TO ALWAYS initialize the ivalue.
1286: Concepts: options database^has logical
1288: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1289: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1290: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1291: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1292: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1293: PetscOptionsList(), PetscOptionsEList()
1294: @*/
1295: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1296: {
1297: char *value;
1298: PetscTruth flag;
1304: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1305: if (flag) {
1306: if (flg) *flg = PETSC_TRUE;
1307: if (!value) {
1308: *ivalue = PETSC_TRUE;
1309: } else {
1310: PetscOptionsAtol(value, ivalue);
1311: }
1312: } else {
1313: if (flg) *flg = PETSC_FALSE;
1314: }
1315: return(0);
1316: }
1320: /*@C
1321: PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular
1322: option in the database. The values must be separated with commas with
1323: no intervening spaces.
1325: Not Collective
1327: Input Parameters:
1328: + pre - string to prepend to each name or PETSC_NULL
1329: . name - the option one is seeking
1330: - nmax - maximum number of values to retrieve
1332: Output Parameter:
1333: + dvalue - the integer values to return
1334: . nmax - actual number of values retreived
1335: - flg - PETSC_TRUE if found, else PETSC_FALSE
1337: Level: beginner
1339: Concepts: options database^array of ints
1341: Notes:
1342: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1343: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1345: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1346: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1347: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1348: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1349: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1350: PetscOptionsList(), PetscOptionsEList()
1351: @*/
1352: PetscErrorCode PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1353: {
1354: char *value;
1356: PetscInt n = 0;
1357: PetscTruth flag;
1358: PetscToken token;
1363: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1364: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1365: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1367: if (flg) *flg = PETSC_TRUE;
1369: PetscTokenCreate(value,',',&token);
1370: PetscTokenFind(token,&value);
1371: while (n < *nmax) {
1372: if (!value) break;
1373: PetscOptionsAtol(value,dvalue);
1374: PetscTokenFind(token,&value);
1375: dvalue++;
1376: n++;
1377: }
1378: PetscTokenDestroy(token);
1379: *nmax = n;
1380: return(0);
1381: }
1385: /*@C
1386: PetscOptionsGetReal - Gets the double precision value for a particular
1387: option in the database.
1389: Not Collective
1391: Input Parameters:
1392: + pre - string to prepend to each name or PETSC_NULL
1393: - name - the option one is seeking
1395: Output Parameter:
1396: + dvalue - the double value to return
1397: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1399: Level: beginner
1401: Concepts: options database^has double
1403: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1404: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1405: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1406: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1407: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1408: PetscOptionsList(), PetscOptionsEList()
1409: @*/
1410: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1411: {
1412: char *value;
1414: PetscTruth flag;
1419: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1420: if (flag) {
1421: if (!value) {if (flg) *flg = PETSC_FALSE;}
1422: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1423: } else {
1424: if (flg) *flg = PETSC_FALSE;
1425: }
1426: return(0);
1427: }
1431: /*@C
1432: PetscOptionsGetScalar - Gets the scalar value for a particular
1433: option in the database.
1435: Not Collective
1437: Input Parameters:
1438: + pre - string to prepend to each name or PETSC_NULL
1439: - name - the option one is seeking
1441: Output Parameter:
1442: + dvalue - the double value to return
1443: - flg - PETSC_TRUE if found, else PETSC_FALSE
1445: Level: beginner
1447: Usage:
1448: A complex number 2+3i can be specified as 2,3 at the command line.
1449: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1451: Concepts: options database^has scalar
1453: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1454: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1455: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1456: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1457: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1458: PetscOptionsList(), PetscOptionsEList()
1459: @*/
1460: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1461: {
1462: char *value;
1463: PetscTruth flag;
1469: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1470: if (flag) {
1471: if (!value) {
1472: if (flg) *flg = PETSC_FALSE;
1473: } else {
1474: #if !defined(PETSC_USE_COMPLEX)
1475: PetscOptionsAtod(value,dvalue);
1476: #else
1477: PetscReal re=0.0,im=0.0;
1478: PetscToken token;
1479: char *tvalue = 0;
1481: PetscTokenCreate(value,',',&token);
1482: PetscTokenFind(token,&tvalue);
1483: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1484: PetscOptionsAtod(tvalue,&re);
1485: PetscTokenFind(token,&tvalue);
1486: if (!tvalue) { /* Unknown separator used. using only real value */
1487: *dvalue = re;
1488: } else {
1489: PetscOptionsAtod(tvalue,&im);
1490: *dvalue = re + PETSC_i*im;
1491: }
1492: PetscTokenDestroy(token);
1493: #endif
1494: if (flg) *flg = PETSC_TRUE;
1495: }
1496: } else { /* flag */
1497: if (flg) *flg = PETSC_FALSE;
1498: }
1499: return(0);
1500: }
1504: /*@C
1505: PetscOptionsGetRealArray - Gets an array of double precision values for a
1506: particular option in the database. The values must be separated with
1507: commas with no intervening spaces.
1509: Not Collective
1511: Input Parameters:
1512: + pre - string to prepend to each name or PETSC_NULL
1513: . name - the option one is seeking
1514: - nmax - maximum number of values to retrieve
1516: Output Parameters:
1517: + dvalue - the double value to return
1518: . nmax - actual number of values retreived
1519: - flg - PETSC_TRUE if found, else PETSC_FALSE
1521: Level: beginner
1523: Concepts: options database^array of doubles
1525: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1526: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1527: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1528: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1529: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1530: PetscOptionsList(), PetscOptionsEList()
1531: @*/
1532: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1533: {
1534: char *value;
1536: PetscInt n = 0;
1537: PetscTruth flag;
1538: PetscToken token;
1543: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1544: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1545: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1547: if (flg) *flg = PETSC_TRUE;
1549: PetscTokenCreate(value,',',&token);
1550: PetscTokenFind(token,&value);
1551: while (n < *nmax) {
1552: if (!value) break;
1553: PetscOptionsAtod(value,dvalue++);
1554: PetscTokenFind(token,&value);
1555: n++;
1556: }
1557: PetscTokenDestroy(token);
1558: *nmax = n;
1559: return(0);
1560: }
1564: /*@C
1565: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1566: option in the database. The values must be separated with commas with
1567: no intervening spaces.
1569: Not Collective
1571: Input Parameters:
1572: + pre - string to prepend to each name or PETSC_NULL
1573: . name - the option one is seeking
1574: - nmax - maximum number of values to retrieve, can include d-D to indicate d,d+1,..,D-1
1576: Output Parameter:
1577: + dvalue - the integer values to return
1578: . nmax - actual number of values retreived
1579: - flg - PETSC_TRUE if found, else PETSC_FALSE
1581: Level: beginner
1583: Concepts: options database^array of ints
1585: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1586: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1587: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1588: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1589: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1590: PetscOptionsList(), PetscOptionsEList()
1591: @*/
1592: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1593: {
1594: char *value;
1596: PetscInt n = 0,i,start,end;
1597: size_t len;
1598: PetscTruth flag,foundrange;
1599: PetscToken token;
1604: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1605: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1606: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1608: if (flg) *flg = PETSC_TRUE;
1610: PetscTokenCreate(value,',',&token);
1611: PetscTokenFind(token,&value);
1612: while (n < *nmax) {
1613: if (!value) break;
1614:
1615: /* look for form d-D where d and D are integers */
1616: foundrange = PETSC_FALSE;
1617: PetscStrlen(value,&len);
1618: if (value[0] == '-') i=2;
1619: else i=1;
1620: for (;i<(int)len; i++) {
1621: if (value[i] == '-') {
1622: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1623: value[i] = 0;
1624: PetscOptionsAtoi(value,&start);
1625: PetscOptionsAtoi(value+i+1,&end);
1626: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1627: 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);
1628: for (;start<end; start++) {
1629: *dvalue = start; dvalue++;n++;
1630: }
1631: foundrange = PETSC_TRUE;
1632: break;
1633: }
1634: }
1635: if (!foundrange) {
1636: PetscOptionsAtoi(value,dvalue);
1637: dvalue++;
1638: n++;
1639: }
1640: PetscTokenFind(token,&value);
1641: }
1642: PetscTokenDestroy(token);
1643: *nmax = n;
1644: return(0);
1645: }
1649: /*@C
1650: PetscOptionsGetString - Gets the string value for a particular option in
1651: the database.
1653: Not Collective
1655: Input Parameters:
1656: + pre - string to prepend to name or PETSC_NULL
1657: . name - the option one is seeking
1658: - len - maximum string length
1660: Output Parameters:
1661: + string - location to copy string
1662: - flg - PETSC_TRUE if found, else PETSC_FALSE
1664: Level: beginner
1666: Fortran Note:
1667: The Fortran interface is slightly different from the C/C++
1668: interface (len is not used). Sample usage in Fortran follows
1669: .vb
1670: character *20 string
1671: integer flg, ierr
1672: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1673: .ve
1675: Concepts: options database^string
1677: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1678: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1679: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1680: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1681: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1682: PetscOptionsList(), PetscOptionsEList()
1683: @*/
1684: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1685: {
1686: char *value;
1688: PetscTruth flag;
1693: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1694: if (!flag) {
1695: if (flg) *flg = PETSC_FALSE;
1696: } else {
1697: if (flg) *flg = PETSC_TRUE;
1698: if (value) {
1699: PetscStrncpy(string,value,len);
1700: } else {
1701: PetscMemzero(string,len);
1702: }
1703: }
1704: return(0);
1705: }
1709: /*@C
1710: PetscOptionsGetStringArray - Gets an array of string values for a particular
1711: option in the database. The values must be separated with commas with
1712: no intervening spaces.
1714: Not Collective
1716: Input Parameters:
1717: + pre - string to prepend to name or PETSC_NULL
1718: . name - the option one is seeking
1719: - nmax - maximum number of strings
1721: Output Parameter:
1722: + strings - location to copy strings
1723: - flg - PETSC_TRUE if found, else PETSC_FALSE
1725: Level: beginner
1727: Notes:
1728: The user should pass in an array of pointers to char, to hold all the
1729: strings returned by this function.
1731: The user is responsible for deallocating the strings that are
1732: returned. The Fortran interface for this routine is not supported.
1734: Contributed by Matthew Knepley.
1736: Concepts: options database^array of strings
1738: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1739: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1740: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1741: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1742: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1743: PetscOptionsList(), PetscOptionsEList()
1744: @*/
1745: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1746: {
1747: char *value;
1749: PetscInt n;
1750: PetscTruth flag;
1751: PetscToken token;
1752:
1756: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1757: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1758: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1759: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1760: if (flg) *flg = PETSC_TRUE;
1762: PetscTokenCreate(value,',',&token);
1763: PetscTokenFind(token,&value);
1764: n = 0;
1765: while (n < *nmax) {
1766: if (!value) break;
1767: PetscStrallocpy(value,&strings[n]);
1768: PetscTokenFind(token,&value);
1769: n++;
1770: }
1771: PetscTokenDestroy(token);
1772: *nmax = n;
1773: return(0);
1774: }
1778: /*@C
1779: PetscOptionsAllUsed - Returns a count of the number of options in the
1780: database that have never been selected.
1782: Not Collective
1784: Output Parameter:
1785: . N - count of options not used
1787: Level: advanced
1789: .seealso: PetscOptionsPrint()
1790: @*/
1791: PetscErrorCode PetscOptionsAllUsed(int *N)
1792: {
1793: PetscInt i,n = 0;
1796: for (i=0; i<options->N; i++) {
1797: if (!options->used[i]) { n++; }
1798: }
1799: *N = n;
1800: return(0);
1801: }
1805: /*@
1806: PetscOptionsLeft - Prints to screen any options that were set and never used.
1808: Not collective
1810: Options Database Key:
1811: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1813: Level: advanced
1815: .seealso: PetscOptionsAllUsed()
1816: @*/
1817: PetscErrorCode PetscOptionsLeft(void)
1818: {
1820: PetscInt i;
1823: for (i=0; i<options->N; i++) {
1824: if (!options->used[i]) {
1825: if (options->values[i]) {
1826: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1827: } else {
1828: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1829: }
1830: }
1831: }
1832: return(0);
1833: }
1838: /*
1839: PetscOptionsCreate - Creates the empty options database.
1841: */
1842: PetscErrorCode PetscOptionsCreate(void)
1843: {
1847: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1848: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1849: options->namegiven = PETSC_FALSE;
1850: options->N = 0;
1851: options->Naliases = 0;
1852: options->numbermonitors = 0;
1854: PetscOptionsObject.prefix = PETSC_NULL;
1855: PetscOptionsObject.title = PETSC_NULL;
1856:
1857: return(0);
1858: }
1862: /*@
1863: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1865: Collective on PETSC_COMM_WORLD
1867: Options Database Keys:
1868: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
1869: available for options set through a file, environment variable, or on
1870: the command line. Only options set after PetscInitialize completes will
1871: be monitored.
1872: . -options_monitor_cancel - cancel all options database monitors
1874: Notes:
1875: To see all options, run your program with the -help option or consult
1876: the users manual.
1878: Level: intermediate
1880: .keywords: set, options, database
1881: @*/
1882: PetscErrorCode PetscOptionsSetFromOptions(void)
1883: {
1884: PetscTruth flgc,flgm;
1885: PetscErrorCode ierr;
1886: char monfilename[PETSC_MAX_PATH_LEN];
1887: PetscViewer monviewer;
1890: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1891: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
1892: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flgc);
1893: PetscOptionsEnd();
1894: if (flgm) {
1895: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1896: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1897: }
1898: if (flgc) { PetscOptionsMonitorCancel(); }
1899: return(0);
1900: }
1905: /*@C
1906: PetscOptionsMonitorDefault - Print all options set value events.
1908: Collective on PETSC_COMM_WORLD
1910: Input Parameters:
1911: + name - option name string
1912: . value - option value string
1913: - dummy - unused monitor context
1915: Level: intermediate
1917: .keywords: PetscOptions, default, monitor
1919: .seealso: PetscOptionsMonitorSet()
1920: @*/
1921: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1922: {
1924: PetscViewer viewer = (PetscViewer) dummy;
1927: if (!viewer) {
1928: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1929: }
1930: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1931: return(0);
1932: }
1936: /*@C
1937: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1938: modified the PETSc options database.
1939:
1940: Not collective
1942: Input Parameters:
1943: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1944: . mctx - [optional] context for private data for the
1945: monitor routine (use PETSC_NULL if no context is desired)
1946: - monitordestroy - [optional] routine that frees monitor context
1947: (may be PETSC_NULL)
1949: Calling Sequence of monitor:
1950: $ monitor (const char name[], const char value[], void *mctx)
1952: + name - option name string
1953: . value - option value string
1954: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1956: Options Database Keys:
1957: + -options_monitor - sets PetscOptionsMonitorDefault()
1958: - -options_monitor_cancel - cancels all monitors that have
1959: been hardwired into a code by
1960: calls to PetscOptionsMonitorSet(), but
1961: does not cancel those set via
1962: the options database.
1964: Notes:
1965: The default is to do nothing. To print the name and value of options
1966: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1967: with a null monitoring context.
1969: Several different monitoring routines may be set by calling
1970: PetscOptionsMonitorSet() multiple times; all will be called in the
1971: order in which they were set.
1973: Level: beginner
1975: .keywords: PetscOptions, set, monitor
1977: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1978: @*/
1979: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1980: {
1982: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1983: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1984: }
1985: options->monitor[options->numbermonitors] = monitor;
1986: options->monitordestroy[options->numbermonitors] = monitordestroy;
1987: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1988: return(0);
1989: }
1993: /*@
1994: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
1996: Not collective
1998: Options Database Key:
1999: . -options_monitor_cancel - Cancels all monitors that have
2000: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2001: but does not cancel those set via the options database.
2003: Level: intermediate
2005: .keywords: PetscOptions, set, monitor
2007: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2008: @*/
2009: PetscErrorCode PetscOptionsMonitorCancel(void)
2010: {
2012: PetscInt i;
2015: for (i=0; i<options->numbermonitors; i++) {
2016: if (options->monitordestroy[i]) {
2017: (*options->monitordestroy[i])(options->monitorcontext[i]);
2018: }
2019: }
2020: options->numbermonitors = 0;
2021: return(0);
2022: }