Actual source code: options.c
1: #define PETSC_DLL
3: /* Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
4: #define _XOPEN_SOURCE 600
5: #define _BSD_SOURCE
6: /*
7: These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
8: This provides the low-level interface, the high level interface is in aoptions.c
10: Some routines use regular malloc and free because it cannot know what malloc is requested with the
11: options database until it has already processed the input.
12: */
14: #include petscsys.h
15: #if defined(PETSC_HAVE_STDLIB_H)
16: #include <stdlib.h>
17: #endif
18: #if defined(PETSC_HAVE_MALLOC_H)
19: #include <malloc.h>
20: #endif
21: #if defined(PETSC_HAVE_SYS_PARAM_H)
22: #include "sys/param.h"
23: #endif
25: /*
26: This table holds all the options set by the user. For simplicity, we use a static size database
27: */
28: #define MAXOPTIONS 512
29: #define MAXALIASES 25
30: #define MAXOPTIONSMONITORS 5
32: typedef struct {
33: int N,argc,Naliases;
34: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
35: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
36: PetscTruth used[MAXOPTIONS];
37: PetscTruth namegiven;
38: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
40: /* --------User (or default) routines (most return -1 on error) --------*/
41: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
42: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*); /* */
43: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
44: PetscInt numbermonitors; /* to, for instance, detect options being set */
46: } PetscOptionsTable;
49: static PetscOptionsTable *options = 0;
52: /*
53: Options events monitor
54: */
55: #define PetscOptionsMonitor(name,value) \
56: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
57: for (_i=0; _i<_im; _i++) {\
58: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
59: } \
60: }
64: /*
65: PetscOptionsAtoi - Converts a string to an integer value. Handles special cases such as "default" and "decide"
66: */
67: PetscErrorCode PetscOptionsAtoi(const char name[],PetscInt *a)
68: {
70: size_t i,len;
71: PetscTruth decide,tdefault,mouse;
74: PetscStrlen(name,&len);
75: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
77: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
78: if (!tdefault) {
79: PetscStrcasecmp(name,"DEFAULT",&tdefault);
80: }
81: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
82: if (!decide) {
83: PetscStrcasecmp(name,"DECIDE",&decide);
84: }
85: PetscStrcasecmp(name,"mouse",&mouse);
87: if (tdefault) {
88: *a = PETSC_DEFAULT;
89: } else if (decide) {
90: *a = PETSC_DECIDE;
91: } else if (mouse) {
92: *a = -1;
93: } else {
94: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
95: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
96: }
97: for (i=1; i<len; i++) {
98: if (name[i] < '0' || name[i] > '9') {
99: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
100: }
101: }
102: #if defined(PETSC_USE_64BIT_INDICES)
103: *a = atoll(name);
104: #else
105: *a = atoi(name);
106: #endif
107: }
108: return(0);
109: }
113: /*
114: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
115: */
116: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
117: {
119: size_t len;
120: PetscTruth decide,tdefault;
123: PetscStrlen(name,&len);
124: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
126: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
127: if (!tdefault) {
128: PetscStrcasecmp(name,"DEFAULT",&tdefault);
129: }
130: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
131: if (!decide) {
132: PetscStrcasecmp(name,"DECIDE",&decide);
133: }
135: if (tdefault) {
136: *a = PETSC_DEFAULT;
137: } else if (decide) {
138: *a = PETSC_DECIDE;
139: } else {
140: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
141: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
142: }
143: *a = atof(name);
144: }
145: return(0);
146: }
150: /*
151: PetscOptionsAtol - Converts string to PetscTruth, handles cases like "yes", "no", "true", "false", "0", "1"
152: */
153: PetscErrorCode PetscOptionsAtol(const char value[], PetscTruth *a)
154: {
155: PetscTruth istrue, isfalse;
156: size_t len;
160: PetscStrlen(value, &len);
161: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
162: PetscStrcasecmp(value,"TRUE",&istrue);
163: if (istrue) {*a = PETSC_TRUE; return(0);}
164: PetscStrcasecmp(value,"YES",&istrue);
165: if (istrue) {*a = PETSC_TRUE; return(0);}
166: PetscStrcasecmp(value,"1",&istrue);
167: if (istrue) {*a = PETSC_TRUE; return(0);}
168: PetscStrcasecmp(value,"on",&istrue);
169: if (istrue) {*a = PETSC_TRUE; return(0);}
170: PetscStrcasecmp(value,"FALSE",&isfalse);
171: if (isfalse) {*a = PETSC_FALSE; return(0);}
172: PetscStrcasecmp(value,"NO",&isfalse);
173: if (isfalse) {*a = PETSC_FALSE; return(0);}
174: PetscStrcasecmp(value,"0",&isfalse);
175: if (isfalse) {*a = PETSC_FALSE; return(0);}
176: PetscStrcasecmp(value,"off",&isfalse);
177: if (isfalse) {*a = PETSC_FALSE; return(0);}
178: SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
179: return(0);
180: }
184: /*@C
185: PetscGetProgramName - Gets the name of the running program.
187: Not Collective
189: Input Parameter:
190: . len - length of the string name
192: Output Parameter:
193: . name - the name of the running program
195: Level: advanced
197: Notes:
198: The name of the program is copied into the user-provided character
199: array of length len. On some machines the program name includes
200: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
201: @*/
202: PetscErrorCode PetscGetProgramName(char name[],size_t len)
203: {
207: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
208: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
209: PetscStrncpy(name,options->programname,len);
210: return(0);
211: }
215: PetscErrorCode PetscSetProgramName(const char name[])
216: {
220: options->namegiven = PETSC_TRUE;
221: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
222: return(0);
223: }
227: /*@
228: PetscOptionsValidKey - PETSc Options database keys must begin with a - followed by a letter.
230: Input Parameter:
231: . in_str - string to check if valid
233: Output Parameter:
234: . key - PETSC_TRUE if a valid key
236: Level: intermediate
238: @*/
239: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
240: {
242: *key = PETSC_FALSE;
243: if (!in_str) return(0);
244: if (in_str[0] != '-') return(0);
245: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
246: *key = PETSC_TRUE;
247: return(0);
248: }
252: /*@C
253: PetscOptionsInsertString - Inserts options into the database from a string
255: Not collective: but only processes that call this routine will set the options
256: included in the file
258: Input Parameter:
259: . in_str - string that contains options separated by blanks
262: Level: intermediate
264: Contributed by Boyana Norris
266: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
267: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
268: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
269: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
270: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
271: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
273: @*/
274: PetscErrorCode PetscOptionsInsertString(const char in_str[])
275: {
276: char *first,*second;
278: PetscToken token;
279: PetscTruth key;
282: PetscTokenCreate(in_str,' ',&token);
283: PetscTokenFind(token,&first);
284: while (first) {
285: PetscOptionsValidKey(first,&key);
286: if (key) {
287: PetscTokenFind(token,&second);
288: PetscOptionsValidKey(second,&key);
289: if (!key) {
290: PetscOptionsSetValue(first,second);
291: PetscTokenFind(token,&first);
292: } else {
293: PetscOptionsSetValue(first,PETSC_NULL);
294: first = second;
295: }
296: } else {
297: PetscTokenFind(token,&first);
298: }
299: }
300: PetscTokenDestroy(token);
301: return(0);
302: }
304: /*
305: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
306: */
307: static char *Petscgetline(FILE * f)
308: {
309: size_t size = 0;
310: size_t len = 0;
311: size_t last = 0;
312: char * buf = PETSC_NULL;
314: if (feof(f)) return 0;
315: do {
316: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
317: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
318: /* Actually do the read. Note that fgets puts a terminal '\0' on the
319: end of the string, so we make sure we overwrite this */
320: if (!fgets(buf+len,size,f)) buf[len]=0;
321: PetscStrlen(buf,&len);
322: last = len - 1;
323: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
324: if (len) return buf;
325: free(buf);
326: return 0;
327: }
332: /*@C
333: PetscOptionsInsertFile - Inserts options into the database from a file.
335: Collective on MPI_Comm
337: Input Parameter:
338: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
339: . file - name of file
340: - require - if PETSC_TRUE will generate an error if the file does not exist
343: Level: intermediate
345: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
346: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
347: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
348: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
349: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
350: PetscOptionsList(), PetscOptionsEList()
352: @*/
353: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
354: {
355: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
357: size_t i,len;
358: FILE *fd;
359: PetscToken token;
360: int err;
361: char cmt[3]={'#','!','%'},*cmatch;
362: PetscMPIInt rank,cnt=0,acnt=0;
365: MPI_Comm_rank(comm,&rank);
366: if (!rank) {
367: /* Warning: assume a maximum size for all options in a string */
368: PetscMalloc(128000*sizeof(char),&vstring);
369: vstring[0] = 0;
370: PetscMalloc(64000*sizeof(char),&astring);
371: astring[0] = 0;
372: cnt = 0;
373: acnt = 0;
375: PetscFixFilename(file,fname);
376: fd = fopen(fname,"r");
377: if (fd) {
378: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
379: PetscInfo1(0,"Opened options file %s\n",file);
380: while ((string = Petscgetline(fd))) {
381: /* eliminate comments from each line */
382: for (i=0; i<3; i++){
383: PetscStrchr(string,cmt[i],&cmatch);
384: if (cmatch) *cmatch = 0;
385: }
386: PetscStrlen(string,&len);
387: /* replace tabs, ^M, \n with " " */
388: for (i=0; i<len; i++) {
389: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
390: string[i] = ' ';
391: }
392: }
393: PetscTokenCreate(string,' ',&token);
394: free(string);
395: PetscTokenFind(token,&first);
396: if (!first) {
397: goto destroy;
398: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
399: PetscTokenFind(token,&first);
400: }
401: PetscTokenFind(token,&second);
402: if (!first) {
403: goto destroy;
404: } else if (first[0] == '-') {
405: /* warning: should be making sure we do not overfill vstring */
406: PetscStrcat(vstring,first);
407: PetscStrcat(vstring," ");
408: if (second) {
409: /* protect second with quotes in case it contains strings */
410: PetscStrcat(vstring,"\"");
411: PetscStrcat(vstring,second);
412: PetscStrcat(vstring,"\"");
413: }
414: PetscStrcat(vstring," ");
415: } else {
416: PetscTruth match;
418: PetscStrcasecmp(first,"alias",&match);
419: if (match) {
420: PetscTokenFind(token,&third);
421: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
422: PetscStrcat(astring,second);
423: PetscStrcat(astring," ");
424: PetscStrcat(astring,third);
425: PetscStrcat(astring," ");
426: } else {
427: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
428: }
429: }
430: destroy:
431: PetscTokenDestroy(token);
432: }
433: err = fclose(fd);
434: if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
435: PetscStrlen(astring,&len);
436: acnt = PetscMPIIntCast(len);
437: PetscStrlen(vstring,&len);
438: cnt = PetscMPIIntCast(len);
439: } else if (require) {
440: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
441: }
442: }
444: MPI_Bcast(&acnt,1,MPI_INT,0,comm);
445: if (acnt) {
446: PetscToken token;
447: char *first,*second;
449: if (rank) {
450: PetscMalloc((acnt+1)*sizeof(char),&astring);
451: }
452: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
453: astring[acnt] = 0;
454: PetscTokenCreate(astring,' ',&token);
455: PetscTokenFind(token,&first);
456: while (first) {
457: PetscTokenFind(token,&second);
458: PetscOptionsSetAlias(first,second);
459: PetscTokenFind(token,&first);
460: }
461: PetscTokenDestroy(token);
462: }
464: MPI_Bcast(&cnt,1,MPI_INT,0,comm);
465: if (cnt) {
466: if (rank) {
467: PetscMalloc((cnt+1)*sizeof(char),&vstring);
468: }
469: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
470: vstring[cnt] = 0;
471: PetscOptionsInsertString(vstring);
472: }
473: PetscFree(astring);
474: PetscFree(vstring);
475: return(0);
476: }
480: /*@C
481: PetscOptionsInsert - Inserts into the options database from the command line,
482: the environmental variable and a file.
484: Input Parameters:
485: + argc - count of number of command line arguments
486: . args - the command line arguments
487: - file - optional filename, defaults to ~username/.petscrc
489: Note:
490: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
491: the user does not typically need to call this routine. PetscOptionsInsert()
492: can be called several times, adding additional entries into the database.
494: Options Database Keys:
495: + -options_monitor <optional filename> - print options names and values as they are set
497: Level: advanced
499: Concepts: options database^adding
501: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
502: PetscInitialize()
503: @*/
504: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
505: {
507: PetscMPIInt rank;
508: char pfile[PETSC_MAX_PATH_LEN];
509: PetscTruth flag = PETSC_FALSE;
512: if (options == PETSC_NULL) {
513: fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
514: MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
515: }
516: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
518: options->argc = (argc) ? *argc : 0;
519: options->args = (args) ? *args : PETSC_NULL;
521: if (file) {
522: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
523: }
524: PetscOptionsGetTruth(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
525: if (!flag) {
526: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
527: /* warning: assumes all processes have a home directory or none, but nothing in between */
528: if (pfile[0]) {
529: PetscStrcat(pfile,"/.petscrc");
530: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
531: }
532: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
533: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
534: }
536: /* insert environmental options */
537: {
538: char *eoptions = 0;
539: size_t len = 0;
540: if (!rank) {
541: eoptions = (char*)getenv("PETSC_OPTIONS");
542: PetscStrlen(eoptions,&len);
543: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
544: } else {
545: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
546: if (len) {
547: PetscMalloc((len+1)*sizeof(char*),&eoptions);
548: }
549: }
550: if (len) {
551: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
552: if (rank) eoptions[len] = 0;
553: PetscOptionsInsertString(eoptions);
554: if (rank) {PetscFree(eoptions);}
555: }
556: }
558: /* insert command line options */
559: if (argc && args && *argc) {
560: int left = *argc - 1;
561: char **eargs = *args + 1;
562: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
564: while (left) {
565: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
566: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
567: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
568: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
569: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
570: isp4 = (PetscTruth) (isp4 || tisp4);
571: PetscStrcasecmp(eargs[0],"-np",&tisp4);
572: isp4 = (PetscTruth) (isp4 || tisp4);
573: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
575: if (eargs[0][0] != '-') {
576: eargs++; left--;
577: } else if (isoptions_file) {
578: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
579: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
580: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
581: eargs += 2; left -= 2;
583: /*
584: These are "bad" options that MPICH, etc put on the command line
585: we strip them out here.
586: */
587: } else if (tisp4 || isp4rmrank) {
588: eargs += 1; left -= 1;
589: } else if (isp4 || isp4yourname) {
590: eargs += 2; left -= 2;
591: } else if ((left < 2) || ((eargs[1][0] == '-') &&
592: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
593: PetscOptionsSetValue(eargs[0],PETSC_NULL);
594: eargs++; left--;
595: } else {
596: PetscOptionsSetValue(eargs[0],eargs[1]);
597: eargs += 2; left -= 2;
598: }
599: }
600: }
601: return(0);
602: }
606: /*@C
607: PetscOptionsPrint - Prints the options that have been loaded. This is
608: useful for debugging purposes.
610: Collective on PETSC_COMM_WORLD
612: Input Parameter:
613: . FILE fd - location to print options (usually stdout or stderr)
615: Options Database Key:
616: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
618: Level: advanced
620: Concepts: options database^printing
622: .seealso: PetscOptionsAllUsed()
623: @*/
624: PetscErrorCode PetscOptionsPrint(FILE *fd)
625: {
627: PetscInt i;
630: if (!fd) fd = PETSC_STDOUT;
631: if (!options) {PetscOptionsInsert(0,0,0);}
632: if (options->N) {
633: PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
634: } else {
635: PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
636: }
637: for (i=0; i<options->N; i++) {
638: if (options->values[i]) {
639: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
640: } else {
641: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
642: }
643: }
644: if (options->N) {
645: PetscFPrintf(PETSC_COMM_WORLD,fd,"#End of PETSc Option Table entries\n");
646: }
647: return(0);
648: }
652: /*@C
653: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
655: Not Collective
657: Output Parameter:
658: . copts - pointer where string pointer is stored
660: Notes: the array and each entry in the array should be freed with PetscFree()
662: Level: advanced
664: Concepts: options database^listing
666: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
667: @*/
668: PetscErrorCode PetscOptionsGetAll(char *copts[])
669: {
671: PetscInt i;
672: size_t len = 1,lent;
673: char *coptions;
676: if (!options) {PetscOptionsInsert(0,0,0);}
678: /* count the length of the required string */
679: for (i=0; i<options->N; i++) {
680: PetscStrlen(options->names[i],&lent);
681: len += 2 + lent;
682: if (options->values[i]) {
683: PetscStrlen(options->values[i],&lent);
684: len += 1 + lent;
685: }
686: }
687: PetscMalloc(len*sizeof(char),&coptions);
688: coptions[0] = 0;
689: for (i=0; i<options->N; i++) {
690: PetscStrcat(coptions,"-");
691: PetscStrcat(coptions,options->names[i]);
692: PetscStrcat(coptions," ");
693: if (options->values[i]) {
694: PetscStrcat(coptions,options->values[i]);
695: PetscStrcat(coptions," ");
696: }
697: }
698: *copts = coptions;
699: return(0);
700: }
704: /*@C
705: PetscOptionsClear - Removes all options form the database leaving it empty.
707: Level: developer
709: .seealso: PetscOptionsInsert()
710: @*/
711: PetscErrorCode PetscOptionsClear(void)
712: {
713: PetscInt i;
716: if (!options) return(0);
717: for (i=0; i<options->N; i++) {
718: if (options->names[i]) free(options->names[i]);
719: if (options->values[i]) free(options->values[i]);
720: }
721: for (i=0; i<options->Naliases; i++) {
722: free(options->aliases1[i]);
723: free(options->aliases2[i]);
724: }
725: options->N = 0;
726: options->Naliases = 0;
727: return(0);
728: }
732: /*@C
733: PetscOptionsDestroy - Destroys the option database.
735: Note:
736: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
737: typically does not need to call this routine.
739: Level: developer
741: .seealso: PetscOptionsInsert()
742: @*/
743: PetscErrorCode PetscOptionsDestroy(void)
744: {
748: if (!options) return(0);
749: PetscOptionsClear();
750: free(options);
751: options = 0;
752: return(0);
753: }
757: /*@C
758: PetscOptionsSetValue - Sets an option name-value pair in the options
759: database, overriding whatever is already present.
761: Not collective, but setting values on certain processors could cause problems
762: for parallel objects looking for options.
764: Input Parameters:
765: + name - name of option, this SHOULD have the - prepended
766: - value - the option value (not used for all options)
768: Level: intermediate
770: Note:
771: Only some options have values associated with them, such as
772: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
774: Concepts: options database^adding option
776: .seealso: PetscOptionsInsert()
777: @*/
778: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
779: {
780: size_t len;
782: PetscInt N,n,i;
783: char **names;
784: const char *name = (char*)iname;
785: PetscTruth gt,match;
788: if (!options) {PetscOptionsInsert(0,0,0);}
790: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
791: PetscStrcasecmp(name,"-h",&match);
792: if (match) name = "-help";
794: name++;
795: /* first check against aliases */
796: N = options->Naliases;
797: for (i=0; i<N; i++) {
798: PetscStrcasecmp(options->aliases1[i],name,&match);
799: if (match) {
800: name = options->aliases2[i];
801: break;
802: }
803: }
805: N = options->N;
806: n = N;
807: names = options->names;
808:
809: for (i=0; i<N; i++) {
810: PetscStrcasecmp(names[i],name,&match);
811: PetscStrgrt(names[i],name,>);
812: if (match) {
813: if (options->values[i]) free(options->values[i]);
814: PetscStrlen(value,&len);
815: if (len) {
816: options->values[i] = (char*)malloc((len+1)*sizeof(char));
817: PetscStrcpy(options->values[i],value);
818: } else { options->values[i] = 0;}
819: PetscOptionsMonitor(name,value);
820: return(0);
821: } else if (gt) {
822: n = i;
823: break;
824: }
825: }
826: if (N >= MAXOPTIONS) {
827: 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);
828: }
829: /* shift remaining values down 1 */
830: for (i=N; i>n; i--) {
831: options->names[i] = options->names[i-1];
832: options->values[i] = options->values[i-1];
833: options->used[i] = options->used[i-1];
834: }
835: /* insert new name and value */
836: PetscStrlen(name,&len);
837: options->names[n] = (char*)malloc((len+1)*sizeof(char));
838: PetscStrcpy(options->names[n],name);
839: PetscStrlen(value,&len);
840: if (len) {
841: options->values[n] = (char*)malloc((len+1)*sizeof(char));
842: PetscStrcpy(options->values[n],value);
843: } else {options->values[n] = 0;}
844: options->used[n] = PETSC_FALSE;
845: options->N++;
846: PetscOptionsMonitor(name,value);
847: return(0);
848: }
852: /*@C
853: PetscOptionsClearValue - Clears an option name-value pair in the options
854: database, overriding whatever is already present.
856: Not Collective, but setting values on certain processors could cause problems
857: for parallel objects looking for options.
859: Input Parameter:
860: . name - name of option, this SHOULD have the - prepended
862: Level: intermediate
864: Concepts: options database^removing option
865: .seealso: PetscOptionsInsert()
866: @*/
867: PetscErrorCode PetscOptionsClearValue(const char iname[])
868: {
870: PetscInt N,n,i;
871: char **names,*name=(char*)iname;
872: PetscTruth gt,match;
875: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
876: if (!options) {PetscOptionsInsert(0,0,0);}
878: name++;
880: N = options->N; n = 0;
881: names = options->names;
882:
883: for (i=0; i<N; i++) {
884: PetscStrcasecmp(names[i],name,&match);
885: PetscStrgrt(names[i],name,>);
886: if (match) {
887: if (options->names[i]) free(options->names[i]);
888: if (options->values[i]) free(options->values[i]);
889: PetscOptionsMonitor(name,"");
890: break;
891: } else if (gt) {
892: return(0); /* it was not listed */
893: }
894: n++;
895: }
896: if (n == N) return(0); /* it was not listed */
898: /* shift remaining values down 1 */
899: for (i=n; i<N-1; i++) {
900: options->names[i] = options->names[i+1];
901: options->values[i] = options->values[i+1];
902: options->used[i] = options->used[i+1];
903: }
904: options->N--;
905: return(0);
906: }
910: /*@C
911: PetscOptionsSetAlias - Makes a key and alias for another key
913: Not Collective, but setting values on certain processors could cause problems
914: for parallel objects looking for options.
916: Input Parameters:
917: + inewname - the alias
918: - ioldname - the name that alias will refer to
920: Level: advanced
922: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
923: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
924: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
925: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
926: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
927: PetscOptionsList(), PetscOptionsEList()
928: @*/
929: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
930: {
932: PetscInt n = options->Naliases;
933: size_t len;
934: char *newname = (char *)inewname,*oldname = (char*)ioldname;
937: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
938: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
939: if (n >= MAXALIASES) {
940: 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);
941: }
943: newname++; oldname++;
944: PetscStrlen(newname,&len);
945: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
946: PetscStrcpy(options->aliases1[n],newname);
947: PetscStrlen(oldname,&len);
948: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
949: PetscStrcpy(options->aliases2[n],oldname);
950: options->Naliases++;
951: return(0);
952: }
956: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
957: {
959: PetscInt i,N;
960: size_t len;
961: char **names,tmp[256];
962: PetscTruth match;
965: if (!options) {PetscOptionsInsert(0,0,0);}
966: N = options->N;
967: names = options->names;
969: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
971: /* append prefix to name */
972: if (pre) {
973: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
974: PetscStrncpy(tmp,pre,256);
975: PetscStrlen(tmp,&len);
976: PetscStrncat(tmp,name+1,256-len-1);
977: } else {
978: PetscStrncpy(tmp,name+1,256);
979: }
981: /* slow search */
982: *flg = PETSC_FALSE;
983: for (i=0; i<N; i++) {
984: PetscStrcasecmp(names[i],tmp,&match);
985: if (match) {
986: *value = options->values[i];
987: options->used[i] = PETSC_TRUE;
988: *flg = PETSC_TRUE;
989: break;
990: }
991: }
992: if (!*flg) {
993: PetscInt j,cnt = 0,locs[16],loce[16];
994: size_t n;
995: PetscStrlen(tmp,&n);
996: /* determine the location and number of all _%d_ in the key */
997: for (i=0; i< (PetscInt)n; i++) {
998: if (tmp[i] == '_') {
999: for (j=i+1; j< (PetscInt)n; j++) {
1000: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1001: if (tmp[j] == '_' && j > i+1) { /* found a number */
1002: locs[cnt] = i+1;
1003: loce[cnt++] = j+1;
1004: }
1005: break;
1006: }
1007: }
1008: }
1009: if (cnt) {
1010: char tmp2[256];
1011: for (i=0; i<cnt; i++) {
1012: PetscStrcpy(tmp2,"-");
1013: PetscStrncat(tmp2,tmp,locs[i]);
1014: PetscStrcat(tmp2,tmp+loce[i]);
1015: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1016: if (*flg) break;
1017: }
1018: }
1019: }
1020: return(0);
1021: }
1025: /*@C
1026: PetscOptionsReject - Generates an error if a certain option is given.
1028: Not Collective, but setting values on certain processors could cause problems
1029: for parallel objects looking for options.
1031: Input Parameters:
1032: + name - the option one is seeking
1033: - mess - error message (may be PETSC_NULL)
1035: Level: advanced
1037: Concepts: options database^rejecting option
1039: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1040: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1041: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1042: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1043: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1044: PetscOptionsList(), PetscOptionsEList()
1045: @*/
1046: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1047: {
1049: PetscTruth flag = PETSC_FALSE;
1052: PetscOptionsHasName(PETSC_NULL,name,&flag);
1053: if (flag) {
1054: if (mess) {
1055: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1056: } else {
1057: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1058: }
1059: }
1060: return(0);
1061: }
1065: /*@C
1066: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1067: its value is set to false.
1069: Not Collective
1071: Input Parameters:
1072: + name - the option one is seeking
1073: - pre - string to prepend to the name or PETSC_NULL
1075: Output Parameters:
1076: . flg - PETSC_TRUE if found else PETSC_FALSE.
1078: Level: beginner
1080: Concepts: options database^has option name
1082: Notes: Name cannot be simply -h
1084: In many cases you probably want to use PetscOptionsGetTruth() instead of calling this, to allowing toggling values.
1086: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1087: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1088: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1089: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1090: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1091: PetscOptionsList(), PetscOptionsEList()
1092: @*/
1093: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1094: {
1095: char *value;
1097: PetscTruth flag;
1100: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1101: if (flg) *flg = flag;
1102: return(0);
1103: }
1107: /*@C
1108: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1110: Not Collective
1112: Input Parameters:
1113: + pre - the string to prepend to the name or PETSC_NULL
1114: - name - the option one is seeking
1116: Output Parameter:
1117: + ivalue - the integer value to return
1118: - flg - PETSC_TRUE if found, else PETSC_FALSE
1120: Level: beginner
1122: Concepts: options database^has int
1124: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1125: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1126: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1127: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1128: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1129: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1130: PetscOptionsList(), PetscOptionsEList()
1131: @*/
1132: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1133: {
1134: char *value;
1136: PetscTruth flag;
1141: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1142: if (flag) {
1143: if (!value) {if (flg) *flg = PETSC_FALSE;}
1144: else {
1145: if (flg) *flg = PETSC_TRUE;
1146: PetscOptionsAtoi(value,ivalue);
1147: }
1148: } else {
1149: if (flg) *flg = PETSC_FALSE;
1150: }
1151: return(0);
1152: }
1156: /*@C
1157: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1159: Not Collective
1161: Input Parameters:
1162: + pre - the string to prepend to the name or PETSC_NULL
1163: . opt - option name
1164: . list - the possible choices
1165: . ntext - number of choices
1167: Output Parameter:
1168: + value - the index of the value to return
1169: - set - PETSC_TRUE if found, else PETSC_FALSE
1170:
1171: Level: intermediate
1173: See PetscOptionsList() for when the choices are given in a PetscFList()
1175: Concepts: options database^list
1177: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1178: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1179: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1180: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1181: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1182: PetscOptionsList(), PetscOptionsEList()
1183: @*/
1184: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1185: {
1187: size_t alen,len = 0;
1188: char *svalue;
1189: PetscTruth aset,flg = PETSC_FALSE;
1190: PetscInt i;
1193: for ( i=0; i<ntext; i++) {
1194: PetscStrlen(list[i],&alen);
1195: if (alen > len) len = alen;
1196: }
1197: len += 5; /* a little extra space for user mistypes */
1198: PetscMalloc(len*sizeof(char),&svalue);
1199: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1200: if (aset) {
1201: if (set) *set = PETSC_TRUE;
1202: for (i=0; i<ntext; i++) {
1203: PetscStrcasecmp(svalue,list[i],&flg);
1204: if (flg) {
1205: *value = i;
1206: break;
1207: }
1208: }
1209: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1210: } else if (set) {
1211: *set = PETSC_FALSE;
1212: }
1213: PetscFree(svalue);
1214: return(0);
1215: }
1219: /*@C
1220: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1222: Not Collective
1224: Input Parameters:
1225: + pre - option prefix or PETSC_NULL
1226: . opt - option name
1227: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1228: - defaultv - the default (current) value
1230: Output Parameter:
1231: + value - the value to return
1232: - flg - PETSC_TRUE if found, else PETSC_FALSE
1234: Level: beginner
1236: Concepts: options database
1238: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1240: list is usually something like PCASMTypes or some other predefined list of enum names
1242: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1243: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1244: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1245: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1246: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1247: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1248: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1249: @*/
1250: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscTruth *set)
1251: {
1253: PetscInt ntext = 0,tval;
1254: PetscTruth fset;
1257: while (list[ntext++]) {
1258: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1259: }
1260: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1261: ntext -= 3;
1262: PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1263: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1264: if (fset) *value = (PetscEnum)tval;
1265: if (set) *set = fset;
1266: return(0);
1267: }
1271: /*@C
1272: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1273: option in the database.
1275: Not Collective
1277: Input Parameters:
1278: + pre - the string to prepend to the name or PETSC_NULL
1279: - name - the option one is seeking
1281: Output Parameter:
1282: + ivalue - the logical value to return
1283: - flg - PETSC_TRUE if found, else PETSC_FALSE
1285: Level: beginner
1287: Notes:
1288: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1289: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1291: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1292: you NEED TO ALWAYS initialize the ivalue.
1294: Concepts: options database^has logical
1296: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1297: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1298: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1299: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1300: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1301: PetscOptionsList(), PetscOptionsEList()
1302: @*/
1303: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1304: {
1305: char *value;
1306: PetscTruth flag;
1312: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1313: if (flag) {
1314: if (flg) *flg = PETSC_TRUE;
1315: if (!value) {
1316: *ivalue = PETSC_TRUE;
1317: } else {
1318: PetscOptionsAtol(value, ivalue);
1319: }
1320: } else {
1321: if (flg) *flg = PETSC_FALSE;
1322: }
1323: return(0);
1324: }
1328: /*@C
1329: PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular
1330: option in the database. The values must be separated with commas with
1331: no intervening spaces.
1333: Not Collective
1335: Input Parameters:
1336: + pre - string to prepend to each name or PETSC_NULL
1337: . name - the option one is seeking
1338: - nmax - maximum number of values to retrieve
1340: Output Parameter:
1341: + dvalue - the integer values to return
1342: . nmax - actual number of values retreived
1343: - flg - PETSC_TRUE if found, else PETSC_FALSE
1345: Level: beginner
1347: Concepts: options database^array of ints
1349: Notes:
1350: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1351: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1353: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1354: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1355: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1356: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1357: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1358: PetscOptionsList(), PetscOptionsEList()
1359: @*/
1360: PetscErrorCode PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1361: {
1362: char *value;
1364: PetscInt n = 0;
1365: PetscTruth flag;
1366: PetscToken token;
1371: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1372: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1373: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1375: if (flg) *flg = PETSC_TRUE;
1377: PetscTokenCreate(value,',',&token);
1378: PetscTokenFind(token,&value);
1379: while (n < *nmax) {
1380: if (!value) break;
1381: PetscOptionsAtol(value,dvalue);
1382: PetscTokenFind(token,&value);
1383: dvalue++;
1384: n++;
1385: }
1386: PetscTokenDestroy(token);
1387: *nmax = n;
1388: return(0);
1389: }
1393: /*@C
1394: PetscOptionsGetReal - Gets the double precision value for a particular
1395: option in the database.
1397: Not Collective
1399: Input Parameters:
1400: + pre - string to prepend to each name or PETSC_NULL
1401: - name - the option one is seeking
1403: Output Parameter:
1404: + dvalue - the double value to return
1405: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1407: Level: beginner
1409: Concepts: options database^has double
1411: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1412: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1413: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1414: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1415: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1416: PetscOptionsList(), PetscOptionsEList()
1417: @*/
1418: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1419: {
1420: char *value;
1422: PetscTruth flag;
1427: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1428: if (flag) {
1429: if (!value) {if (flg) *flg = PETSC_FALSE;}
1430: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1431: } else {
1432: if (flg) *flg = PETSC_FALSE;
1433: }
1434: return(0);
1435: }
1439: /*@C
1440: PetscOptionsGetScalar - Gets the scalar value for a particular
1441: option in the database.
1443: Not Collective
1445: Input Parameters:
1446: + pre - string to prepend to each name or PETSC_NULL
1447: - name - the option one is seeking
1449: Output Parameter:
1450: + dvalue - the double value to return
1451: - flg - PETSC_TRUE if found, else PETSC_FALSE
1453: Level: beginner
1455: Usage:
1456: A complex number 2+3i can be specified as 2,3 at the command line.
1457: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1459: Concepts: options database^has scalar
1461: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1462: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1463: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1464: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1465: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1466: PetscOptionsList(), PetscOptionsEList()
1467: @*/
1468: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1469: {
1470: char *value;
1471: PetscTruth flag;
1477: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1478: if (flag) {
1479: if (!value) {
1480: if (flg) *flg = PETSC_FALSE;
1481: } else {
1482: #if !defined(PETSC_USE_COMPLEX)
1483: PetscOptionsAtod(value,dvalue);
1484: #else
1485: PetscReal re=0.0,im=0.0;
1486: PetscToken token;
1487: char *tvalue = 0;
1489: PetscTokenCreate(value,',',&token);
1490: PetscTokenFind(token,&tvalue);
1491: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1492: PetscOptionsAtod(tvalue,&re);
1493: PetscTokenFind(token,&tvalue);
1494: if (!tvalue) { /* Unknown separator used. using only real value */
1495: *dvalue = re;
1496: } else {
1497: PetscOptionsAtod(tvalue,&im);
1498: *dvalue = re + PETSC_i*im;
1499: }
1500: PetscTokenDestroy(token);
1501: #endif
1502: if (flg) *flg = PETSC_TRUE;
1503: }
1504: } else { /* flag */
1505: if (flg) *flg = PETSC_FALSE;
1506: }
1507: return(0);
1508: }
1512: /*@C
1513: PetscOptionsGetRealArray - Gets an array of double precision values for a
1514: particular option in the database. The values must be separated with
1515: commas with no intervening spaces.
1517: Not Collective
1519: Input Parameters:
1520: + pre - string to prepend to each name or PETSC_NULL
1521: . name - the option one is seeking
1522: - nmax - maximum number of values to retrieve
1524: Output Parameters:
1525: + dvalue - the double value to return
1526: . nmax - actual number of values retreived
1527: - flg - PETSC_TRUE if found, else PETSC_FALSE
1529: Level: beginner
1531: Concepts: options database^array of doubles
1533: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1534: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1535: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1536: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1537: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1538: PetscOptionsList(), PetscOptionsEList()
1539: @*/
1540: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1541: {
1542: char *value;
1544: PetscInt n = 0;
1545: PetscTruth flag;
1546: PetscToken token;
1551: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1552: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1553: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1555: if (flg) *flg = PETSC_TRUE;
1557: PetscTokenCreate(value,',',&token);
1558: PetscTokenFind(token,&value);
1559: while (n < *nmax) {
1560: if (!value) break;
1561: PetscOptionsAtod(value,dvalue++);
1562: PetscTokenFind(token,&value);
1563: n++;
1564: }
1565: PetscTokenDestroy(token);
1566: *nmax = n;
1567: return(0);
1568: }
1572: /*@C
1573: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1574: option in the database. The values must be separated with commas with
1575: no intervening spaces.
1577: Not Collective
1579: Input Parameters:
1580: + pre - string to prepend to each name or PETSC_NULL
1581: . name - the option one is seeking
1582: - nmax - maximum number of values to retrieve, can include d-D to indicate d,d+1,..,D-1
1584: Output Parameter:
1585: + dvalue - the integer values to return
1586: . nmax - actual number of values retreived
1587: - flg - PETSC_TRUE if found, else PETSC_FALSE
1589: Level: beginner
1591: Concepts: options database^array of ints
1593: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1594: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1595: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1596: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1597: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1598: PetscOptionsList(), PetscOptionsEList()
1599: @*/
1600: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1601: {
1602: char *value;
1604: PetscInt n = 0,i,start,end;
1605: size_t len;
1606: PetscTruth flag,foundrange;
1607: PetscToken token;
1612: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1613: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1614: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1616: if (flg) *flg = PETSC_TRUE;
1618: PetscTokenCreate(value,',',&token);
1619: PetscTokenFind(token,&value);
1620: while (n < *nmax) {
1621: if (!value) break;
1622:
1623: /* look for form d-D where d and D are integers */
1624: foundrange = PETSC_FALSE;
1625: PetscStrlen(value,&len);
1626: if (value[0] == '-') i=2;
1627: else i=1;
1628: for (;i<(int)len; i++) {
1629: if (value[i] == '-') {
1630: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1631: value[i] = 0;
1632: PetscOptionsAtoi(value,&start);
1633: PetscOptionsAtoi(value+i+1,&end);
1634: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1635: 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);
1636: for (;start<end; start++) {
1637: *dvalue = start; dvalue++;n++;
1638: }
1639: foundrange = PETSC_TRUE;
1640: break;
1641: }
1642: }
1643: if (!foundrange) {
1644: PetscOptionsAtoi(value,dvalue);
1645: dvalue++;
1646: n++;
1647: }
1648: PetscTokenFind(token,&value);
1649: }
1650: PetscTokenDestroy(token);
1651: *nmax = n;
1652: return(0);
1653: }
1657: /*@C
1658: PetscOptionsGetString - Gets the string value for a particular option in
1659: the database.
1661: Not Collective
1663: Input Parameters:
1664: + pre - string to prepend to name or PETSC_NULL
1665: . name - the option one is seeking
1666: - len - maximum string length
1668: Output Parameters:
1669: + string - location to copy string
1670: - flg - PETSC_TRUE if found, else PETSC_FALSE
1672: Level: beginner
1674: Fortran Note:
1675: The Fortran interface is slightly different from the C/C++
1676: interface (len is not used). Sample usage in Fortran follows
1677: .vb
1678: character *20 string
1679: integer flg, ierr
1680: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1681: .ve
1683: Concepts: options database^string
1685: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1686: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1687: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1688: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1689: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1690: PetscOptionsList(), PetscOptionsEList()
1691: @*/
1692: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1693: {
1694: char *value;
1696: PetscTruth flag;
1701: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1702: if (!flag) {
1703: if (flg) *flg = PETSC_FALSE;
1704: } else {
1705: if (flg) *flg = PETSC_TRUE;
1706: if (value) {
1707: PetscStrncpy(string,value,len);
1708: } else {
1709: PetscMemzero(string,len);
1710: }
1711: }
1712: return(0);
1713: }
1717: /*@C
1718: PetscOptionsGetStringArray - Gets an array of string values for a particular
1719: option in the database. The values must be separated with commas with
1720: no intervening spaces.
1722: Not Collective
1724: Input Parameters:
1725: + pre - string to prepend to name or PETSC_NULL
1726: . name - the option one is seeking
1727: - nmax - maximum number of strings
1729: Output Parameter:
1730: + strings - location to copy strings
1731: - flg - PETSC_TRUE if found, else PETSC_FALSE
1733: Level: beginner
1735: Notes:
1736: The user should pass in an array of pointers to char, to hold all the
1737: strings returned by this function.
1739: The user is responsible for deallocating the strings that are
1740: returned. The Fortran interface for this routine is not supported.
1742: Contributed by Matthew Knepley.
1744: Concepts: options database^array of strings
1746: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1747: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1748: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1749: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1750: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1751: PetscOptionsList(), PetscOptionsEList()
1752: @*/
1753: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1754: {
1755: char *value;
1757: PetscInt n;
1758: PetscTruth flag;
1759: PetscToken token;
1760:
1764: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1765: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1766: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1767: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1768: if (flg) *flg = PETSC_TRUE;
1770: PetscTokenCreate(value,',',&token);
1771: PetscTokenFind(token,&value);
1772: n = 0;
1773: while (n < *nmax) {
1774: if (!value) break;
1775: PetscStrallocpy(value,&strings[n]);
1776: PetscTokenFind(token,&value);
1777: n++;
1778: }
1779: PetscTokenDestroy(token);
1780: *nmax = n;
1781: return(0);
1782: }
1786: /*@C
1787: PetscOptionsAllUsed - Returns a count of the number of options in the
1788: database that have never been selected.
1790: Not Collective
1792: Output Parameter:
1793: . N - count of options not used
1795: Level: advanced
1797: .seealso: PetscOptionsPrint()
1798: @*/
1799: PetscErrorCode PetscOptionsAllUsed(int *N)
1800: {
1801: PetscInt i,n = 0;
1804: for (i=0; i<options->N; i++) {
1805: if (!options->used[i]) { n++; }
1806: }
1807: *N = n;
1808: return(0);
1809: }
1813: /*@
1814: PetscOptionsLeft - Prints to screen any options that were set and never used.
1816: Not collective
1818: Options Database Key:
1819: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1821: Level: advanced
1823: .seealso: PetscOptionsAllUsed()
1824: @*/
1825: PetscErrorCode PetscOptionsLeft(void)
1826: {
1828: PetscInt i;
1831: for (i=0; i<options->N; i++) {
1832: if (!options->used[i]) {
1833: if (options->values[i]) {
1834: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1835: } else {
1836: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1837: }
1838: }
1839: }
1840: return(0);
1841: }
1846: /*
1847: PetscOptionsCreate - Creates the empty options database.
1849: */
1850: PetscErrorCode PetscOptionsCreate(void)
1851: {
1855: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1856: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1857: options->namegiven = PETSC_FALSE;
1858: options->N = 0;
1859: options->Naliases = 0;
1860: options->numbermonitors = 0;
1862: PetscOptionsObject.prefix = PETSC_NULL;
1863: PetscOptionsObject.title = PETSC_NULL;
1864:
1865: return(0);
1866: }
1870: /*@
1871: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1873: Collective on PETSC_COMM_WORLD
1875: Options Database Keys:
1876: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
1877: available for options set through a file, environment variable, or on
1878: the command line. Only options set after PetscInitialize completes will
1879: be monitored.
1880: . -options_monitor_cancel - cancel all options database monitors
1882: Notes:
1883: To see all options, run your program with the -help option or consult
1884: the users manual.
1886: Level: intermediate
1888: .keywords: set, options, database
1889: @*/
1890: PetscErrorCode PetscOptionsSetFromOptions(void)
1891: {
1892: PetscTruth flgc,flgm;
1893: PetscErrorCode ierr;
1894: char monfilename[PETSC_MAX_PATH_LEN];
1895: PetscViewer monviewer;
1898: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1899: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
1900: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flgc);
1901: PetscOptionsEnd();
1902: if (flgm) {
1903: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1904: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1905: }
1906: if (flgc) { PetscOptionsMonitorCancel(); }
1907: return(0);
1908: }
1913: /*@C
1914: PetscOptionsMonitorDefault - Print all options set value events.
1916: Collective on PETSC_COMM_WORLD
1918: Input Parameters:
1919: + name - option name string
1920: . value - option value string
1921: - dummy - unused monitor context
1923: Level: intermediate
1925: .keywords: PetscOptions, default, monitor
1927: .seealso: PetscOptionsMonitorSet()
1928: @*/
1929: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1930: {
1932: PetscViewer viewer = (PetscViewer) dummy;
1935: if (!viewer) {
1936: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1937: }
1938: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1939: return(0);
1940: }
1944: /*@C
1945: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1946: modified the PETSc options database.
1947:
1948: Not collective
1950: Input Parameters:
1951: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1952: . mctx - [optional] context for private data for the
1953: monitor routine (use PETSC_NULL if no context is desired)
1954: - monitordestroy - [optional] routine that frees monitor context
1955: (may be PETSC_NULL)
1957: Calling Sequence of monitor:
1958: $ monitor (const char name[], const char value[], void *mctx)
1960: + name - option name string
1961: . value - option value string
1962: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1964: Options Database Keys:
1965: + -options_monitor - sets PetscOptionsMonitorDefault()
1966: - -options_monitor_cancel - cancels all monitors that have
1967: been hardwired into a code by
1968: calls to PetscOptionsMonitorSet(), but
1969: does not cancel those set via
1970: the options database.
1972: Notes:
1973: The default is to do nothing. To print the name and value of options
1974: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1975: with a null monitoring context.
1977: Several different monitoring routines may be set by calling
1978: PetscOptionsMonitorSet() multiple times; all will be called in the
1979: order in which they were set.
1981: Level: beginner
1983: .keywords: PetscOptions, set, monitor
1985: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1986: @*/
1987: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1988: {
1990: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1991: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1992: }
1993: options->monitor[options->numbermonitors] = monitor;
1994: options->monitordestroy[options->numbermonitors] = monitordestroy;
1995: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1996: return(0);
1997: }
2001: /*@
2002: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2004: Not collective
2006: Options Database Key:
2007: . -options_monitor_cancel - Cancels all monitors that have
2008: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2009: but does not cancel those set via the options database.
2011: Level: intermediate
2013: .keywords: PetscOptions, set, monitor
2015: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2016: @*/
2017: PetscErrorCode PetscOptionsMonitorCancel(void)
2018: {
2020: PetscInt i;
2023: for (i=0; i<options->numbermonitors; i++) {
2024: if (options->monitordestroy[i]) {
2025: (*options->monitordestroy[i])(options->monitorcontext[i]);
2026: }
2027: }
2028: options->numbermonitors = 0;
2029: return(0);
2030: }