Actual source code: options.c
1: #define PETSC_DLL
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
15: #if defined(PETSC_HAVE_MALLOC_H)
16: #include <malloc.h>
17: #endif
18: #if defined(PETSC_HAVE_SYS_PARAM_H)
19: #include "sys/param.h"
20: #endif
21: #include "petscfix.h"
23: /*
24: For simplicity, we use a static size database
25: */
26: #define MAXOPTIONS 512
27: #define MAXALIASES 25
28: #define MAXOPTIONSMONITORS 5
30: typedef struct {
31: int N,argc,Naliases;
32: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
33: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
34: PetscTruth used[MAXOPTIONS];
35: PetscTruth namegiven;
36: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
38: /* --------User (or default) routines (most return -1 on error) --------*/
39: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
40: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*); /* */
41: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
42: PetscInt numbermonitors; /* to, for instance, detect options being set */
44: } PetscOptionsTable;
47: static PetscOptionsTable *options = 0;
51: /*
52: Options events monitor
53: */
54: #define PetscOptionsMonitor(name,value) \
55: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
56: for (_i=0; _i<_im; _i++) {\
57: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
58: } \
59: }
63: PetscErrorCode PetscOptionsAtoi(const char name[],PetscInt *a)
64: {
66: size_t i,len;
67: PetscTruth decide,tdefault,mouse;
70: PetscStrlen(name,&len);
71: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
73: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
74: if (!tdefault) {
75: PetscStrcasecmp(name,"DEFAULT",&tdefault);
76: }
77: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
78: if (!decide) {
79: PetscStrcasecmp(name,"DECIDE",&decide);
80: }
81: PetscStrcasecmp(name,"mouse",&mouse);
83: if (tdefault) {
84: *a = PETSC_DEFAULT;
85: } else if (decide) {
86: *a = PETSC_DECIDE;
87: } else if (mouse) {
88: *a = -1;
89: } else {
90: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
91: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
92: }
93: for (i=1; i<len; i++) {
94: if (name[i] < '0' || name[i] > '9') {
95: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
96: }
97: }
98: *a = atoi(name);
99: }
100: return(0);
101: }
105: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
106: {
108: size_t len;
109: PetscTruth decide,tdefault;
112: PetscStrlen(name,&len);
113: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
115: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
116: if (!tdefault) {
117: PetscStrcasecmp(name,"DEFAULT",&tdefault);
118: }
119: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
120: if (!decide) {
121: PetscStrcasecmp(name,"DECIDE",&decide);
122: }
124: if (tdefault) {
125: *a = PETSC_DEFAULT;
126: } else if (decide) {
127: *a = PETSC_DECIDE;
128: } else {
129: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
130: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
131: }
132: *a = atof(name);
133: }
134: return(0);
135: }
139: PetscErrorCode PetscOptionsAtol(const char value[], PetscTruth *a)
140: {
141: PetscTruth istrue, isfalse;
142: size_t len;
146: PetscStrlen(value, &len);
147: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
148: PetscStrcasecmp(value,"TRUE",&istrue);
149: if (istrue) {*a = PETSC_TRUE; return(0);}
150: PetscStrcasecmp(value,"YES",&istrue);
151: if (istrue) {*a = PETSC_TRUE; return(0);}
152: PetscStrcasecmp(value,"1",&istrue);
153: if (istrue) {*a = PETSC_TRUE; return(0);}
154: PetscStrcasecmp(value,"on",&istrue);
155: if (istrue) {*a = PETSC_TRUE; return(0);}
156: PetscStrcasecmp(value,"FALSE",&isfalse);
157: if (isfalse) {*a = PETSC_FALSE; return(0);}
158: PetscStrcasecmp(value,"NO",&isfalse);
159: if (isfalse) {*a = PETSC_FALSE; return(0);}
160: PetscStrcasecmp(value,"0",&isfalse);
161: if (isfalse) {*a = PETSC_FALSE; return(0);}
162: PetscStrcasecmp(value,"off",&isfalse);
163: if (isfalse) {*a = PETSC_FALSE; return(0);}
164: SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
165: return(0);
166: }
170: /*@C
171: PetscGetProgramName - Gets the name of the running program.
173: Not Collective
175: Input Parameter:
176: . len - length of the string name
178: Output Parameter:
179: . name - the name of the running program
181: Level: advanced
183: Notes:
184: The name of the program is copied into the user-provided character
185: array of length len. On some machines the program name includes
186: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
187: @*/
188: PetscErrorCode PetscGetProgramName(char name[],size_t len)
189: {
193: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
194: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
195: PetscStrncpy(name,options->programname,len);
196: return(0);
197: }
201: PetscErrorCode PetscSetProgramName(const char name[])
202: {
206: options->namegiven = PETSC_TRUE;
207: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
208: return(0);
209: }
213: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscTruth *key)
214: {
216: *key = PETSC_FALSE;
217: if (!in_str) return(0);
218: if (in_str[0] != '-') return(0);
219: if ((in_str[1] < 'A') || (in_str[1] > 'z')) return(0);
220: *key = PETSC_TRUE;
221: return(0);
222: }
226: /*@C
227: PetscOptionsInsertString - Inserts options into the database from a string
229: Not collective: but only processes that call this routine will set the options
230: included in the file
232: Input Parameter:
233: . in_str - string that contains options separated by blanks
236: Level: intermediate
238: Contributed by Boyana Norris
240: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
241: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
242: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
243: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
244: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
245: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
247: @*/
248: PetscErrorCode PetscOptionsInsertString(const char in_str[])
249: {
250: char *first,*second;
252: PetscToken token;
253: PetscTruth key;
256: PetscTokenCreate(in_str,' ',&token);
257: PetscTokenFind(token,&first);
258: while (first) {
259: PetscOptionsValidKey(first,&key);
260: if (key) {
261: PetscTokenFind(token,&second);
262: PetscOptionsValidKey(second,&key);
263: if (!key) {
264: PetscOptionsSetValue(first,second);
265: PetscTokenFind(token,&first);
266: } else {
267: PetscOptionsSetValue(first,PETSC_NULL);
268: first = second;
269: }
270: } else {
271: PetscTokenFind(token,&first);
272: }
273: }
274: PetscTokenDestroy(token);
275: return(0);
276: }
278: static char *Petscgetline(FILE * f)
279: {
280: size_t size = 0;
281: size_t len = 0;
282: size_t last = 0;
283: char * buf = PETSC_NULL;
285: if (feof(f)) return 0;
286: do {
287: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
288: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
289: /* Actually do the read. Note that fgets puts a terminal '\0' on the
290: end of the string, so we make sure we overwrite this */
291: if (!fgets(buf+len,size,f)) buf[len]=0;
292: PetscStrlen(buf,&len);
293: last = len - 1;
294: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
295: if (len) return buf;
296: free(buf);
297: return 0;
298: }
303: /*@C
304: PetscOptionsInsertFile - Inserts options into the database from a file.
306: Collective on MPI_Comm
308: Input Parameter:
309: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
310: . file - name of file
311: - require - if PETSC_TRUE will generate an error if the file does not exist
314: Level: intermediate
316: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
317: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
318: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
319: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
320: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
321: PetscOptionsList(), PetscOptionsEList()
323: @*/
324: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscTruth require)
325: {
326: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
328: size_t i,len;
329: FILE *fd;
330: PetscToken token;
331: int err;
332: char cmt[3]={'#','!','%'},*cmatch;
333: PetscMPIInt rank,cnt,acnt;
336: MPI_Comm_rank(comm,&rank);
337: if (!rank) {
338: /* Warning: assume a maximum size for all options in a string */
339: PetscMalloc(128000*sizeof(char),&vstring);
340: vstring[0] = 0;
341: PetscMalloc(64000*sizeof(char),&astring);
342: astring[0] = 0;
343: cnt = 0;
344: acnt = 0;
346: PetscFixFilename(file,fname);
347: fd = fopen(fname,"r");
348: if (fd) {
349: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
350: PetscInfo1(0,"Opened options file %s\n",file);
351: while ((string = Petscgetline(fd))) {
352: /* eliminate comments from each line */
353: for (i=0; i<3; i++){
354: PetscStrchr(string,cmt[i],&cmatch);
355: if (cmatch) *cmatch = 0;
356: }
357: PetscStrlen(string,&len);
358: /* replace tabs, ^M, \n with " " */
359: for (i=0; i<len; i++) {
360: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
361: string[i] = ' ';
362: }
363: }
364: PetscTokenCreate(string,' ',&token);
365: free(string);
366: PetscTokenFind(token,&first);
367: if (!first) {
368: goto destroy;
369: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
370: PetscTokenFind(token,&first);
371: }
372: PetscTokenFind(token,&second);
373: if (!first) {
374: goto destroy;
375: } else if (first[0] == '-') {
376: /* warning: should be making sure we do not overfill vstring */
377: PetscStrcat(vstring,first);
378: PetscStrcat(vstring," ");
379: if (second) {
380: /* protect second with quotes in case it contains strings */
381: PetscStrcat(vstring,"\"");
382: PetscStrcat(vstring,second);
383: PetscStrcat(vstring,"\"");
384: }
385: PetscStrcat(vstring," ");
386: } else {
387: PetscTruth match;
389: PetscStrcasecmp(first,"alias",&match);
390: if (match) {
391: PetscTokenFind(token,&third);
392: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
393: PetscStrcat(astring,second);
394: PetscStrcat(astring," ");
395: PetscStrcat(astring,third);
396: PetscStrcat(astring," ");
397: } else {
398: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
399: }
400: }
401: destroy:
402: PetscTokenDestroy(token);
403: }
404: err = fclose(fd);
405: if (err) SETERRQ(PETSC_ERR_SYS,"fclose() failed on file");
406: PetscStrlen(astring,&len);
407: acnt = PetscMPIIntCast(len);
408: PetscStrlen(vstring,&len);
409: cnt = PetscMPIIntCast(len);
410: } else if (require) {
411: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
412: }
413: }
415: MPI_Bcast(&acnt,1,MPIU_INT,0,comm);
416: if (acnt) {
417: PetscToken token;
418: char *first,*second;
420: if (rank) {
421: PetscMalloc((acnt+1)*sizeof(char),&astring);
422: }
423: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
424: astring[acnt] = 0;
425: PetscTokenCreate(astring,' ',&token);
426: PetscTokenFind(token,&first);
427: while (first) {
428: PetscTokenFind(token,&second);
429: PetscOptionsSetAlias(first,second);
430: PetscTokenFind(token,&first);
431: }
432: PetscTokenDestroy(token);
433: }
435: MPI_Bcast(&cnt,1,MPIU_INT,0,comm);
436: if (cnt) {
437: if (rank) {
438: PetscMalloc((cnt+1)*sizeof(char),&vstring);
439: }
440: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
441: vstring[cnt] = 0;
442: PetscOptionsInsertString(vstring);
443: }
444: PetscFree(astring);
445: PetscFree(vstring);
446: return(0);
447: }
451: /*@C
452: PetscOptionsInsert - Inserts into the options database from the command line,
453: the environmental variable and a file.
455: Input Parameters:
456: + argc - count of number of command line arguments
457: . args - the command line arguments
458: - file - optional filename, defaults to ~username/.petscrc
460: Note:
461: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
462: the user does not typically need to call this routine. PetscOptionsInsert()
463: can be called several times, adding additional entries into the database.
465: Options Database Keys:
466: + -options_monitor <optional filename> - print options names and values as they are set
468: Level: advanced
470: Concepts: options database^adding
472: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
473: PetscInitialize()
474: @*/
475: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
476: {
478: PetscMPIInt rank;
479: char pfile[PETSC_MAX_PATH_LEN];
480: PetscTruth flag;
483: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
485: options->argc = (argc) ? *argc : 0;
486: options->args = (args) ? *args : PETSC_NULL;
488: if (file) {
489: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
490: }
491: PetscOptionsHasName(PETSC_NULL,"-skip_petscrc",&flag);
492: if (!flag) {
493: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
494: /* warning: assumes all processes have a home directory or none, but nothing in between */
495: if (pfile[0]) {
496: PetscStrcat(pfile,"/.petscrc");
497: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
498: }
499: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
500: }
502: /* insert environmental options */
503: {
504: char *eoptions = 0;
505: size_t len = 0;
506: if (!rank) {
507: eoptions = (char*)getenv("PETSC_OPTIONS");
508: PetscStrlen(eoptions,&len);
509: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
510: } else {
511: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
512: if (len) {
513: PetscMalloc((len+1)*sizeof(char*),&eoptions);
514: }
515: }
516: if (len) {
517: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
518: if (rank) eoptions[len] = 0;
519: PetscOptionsInsertString(eoptions);
520: if (rank) {PetscFree(eoptions);}
521: }
522: }
524: /* insert command line options */
525: if (argc && args && *argc) {
526: int left = *argc - 1;
527: char **eargs = *args + 1;
528: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
530: while (left) {
531: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
532: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
533: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
534: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
535: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
536: isp4 = (PetscTruth) (isp4 || tisp4);
537: PetscStrcasecmp(eargs[0],"-np",&tisp4);
538: isp4 = (PetscTruth) (isp4 || tisp4);
539: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
541: if (eargs[0][0] != '-') {
542: eargs++; left--;
543: } else if (isoptions_file) {
544: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
545: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
546: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
547: eargs += 2; left -= 2;
549: /*
550: These are "bad" options that MPICH, etc put on the command line
551: we strip them out here.
552: */
553: } else if (tisp4 || isp4rmrank) {
554: eargs += 1; left -= 1;
555: } else if (isp4 || isp4yourname) {
556: eargs += 2; left -= 2;
557: } else if ((left < 2) || ((eargs[1][0] == '-') &&
558: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
559: PetscOptionsSetValue(eargs[0],PETSC_NULL);
560: eargs++; left--;
561: } else {
562: PetscOptionsSetValue(eargs[0],eargs[1]);
563: eargs += 2; left -= 2;
564: }
565: }
566: }
567: return(0);
568: }
572: /*@C
573: PetscOptionsPrint - Prints the options that have been loaded. This is
574: useful for debugging purposes.
576: Collective on PETSC_COMM_WORLD
578: Input Parameter:
579: . FILE fd - location to print options (usually stdout or stderr)
581: Options Database Key:
582: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
584: Level: advanced
586: Concepts: options database^printing
588: .seealso: PetscOptionsAllUsed()
589: @*/
590: PetscErrorCode PetscOptionsPrint(FILE *fd)
591: {
593: PetscInt i;
596: if (!fd) fd = PETSC_STDOUT;
597: if (!options) {PetscOptionsInsert(0,0,0);}
598: if (options->N) {
599: PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
600: } else {
601: PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
602: }
603: for (i=0; i<options->N; i++) {
604: if (options->values[i]) {
605: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
606: } else {
607: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
608: }
609: }
610: if (options->N) {
611: PetscFPrintf(PETSC_COMM_WORLD,fd,"#End o PETSc Option Table entries\n");
612: }
613: return(0);
614: }
618: /*@C
619: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
621: Not Collective
623: Output Parameter:
624: . copts - pointer where string pointer is stored
626: Level: advanced
628: Concepts: options database^listing
630: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
631: @*/
632: PetscErrorCode PetscOptionsGetAll(char *copts[])
633: {
635: PetscInt i;
636: size_t len = 1,lent;
637: char *coptions;
640: if (!options) {PetscOptionsInsert(0,0,0);}
642: /* count the length of the required string */
643: for (i=0; i<options->N; i++) {
644: PetscStrlen(options->names[i],&lent);
645: len += 2 + lent;
646: if (options->values[i]) {
647: PetscStrlen(options->values[i],&lent);
648: len += 1 + lent;
649: }
650: }
651: PetscMalloc(len*sizeof(char),&coptions);
652: coptions[0] = 0;
653: for (i=0; i<options->N; i++) {
654: PetscStrcat(coptions,"-");
655: PetscStrcat(coptions,options->names[i]);
656: PetscStrcat(coptions," ");
657: if (options->values[i]) {
658: PetscStrcat(coptions,options->values[i]);
659: PetscStrcat(coptions," ");
660: }
661: }
662: *copts = coptions;
663: return(0);
664: }
668: /*@C
669: PetscOptionsClear - Removes all options form the database leaving it empty.
671: Level: developer
673: .seealso: PetscOptionsInsert()
674: @*/
675: PetscErrorCode PetscOptionsClear(void)
676: {
677: PetscInt i;
680: if (!options) return(0);
681: for (i=0; i<options->N; i++) {
682: if (options->names[i]) free(options->names[i]);
683: if (options->values[i]) free(options->values[i]);
684: }
685: for (i=0; i<options->Naliases; i++) {
686: free(options->aliases1[i]);
687: free(options->aliases2[i]);
688: }
689: options->N = 0;
690: options->Naliases = 0;
691: return(0);
692: }
696: /*@C
697: PetscOptionsDestroy - Destroys the option database.
699: Note:
700: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
701: typically does not need to call this routine.
703: Level: developer
705: .seealso: PetscOptionsInsert()
706: @*/
707: PetscErrorCode PetscOptionsDestroy(void)
708: {
712: if (!options) return(0);
713: PetscOptionsClear();
714: free(options);
715: options = 0;
716: return(0);
717: }
721: /*@C
722: PetscOptionsSetValue - Sets an option name-value pair in the options
723: database, overriding whatever is already present.
725: Not collective, but setting values on certain processors could cause problems
726: for parallel objects looking for options.
728: Input Parameters:
729: + name - name of option, this SHOULD have the - prepended
730: - value - the option value (not used for all options)
732: Level: intermediate
734: Note:
735: Only some options have values associated with them, such as
736: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
738: Concepts: options database^adding option
740: .seealso: PetscOptionsInsert()
741: @*/
742: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
743: {
744: size_t len;
746: PetscInt N,n,i;
747: char **names;
748: const char *name = (char*)iname;
749: PetscTruth gt,match;
752: if (!options) {PetscOptionsInsert(0,0,0);}
754: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
755: PetscStrcasecmp(name,"-h",&match);
756: if (match) name = "-help";
758: name++;
759: /* first check against aliases */
760: N = options->Naliases;
761: for (i=0; i<N; i++) {
762: PetscStrcasecmp(options->aliases1[i],name,&match);
763: if (match) {
764: name = options->aliases2[i];
765: break;
766: }
767: }
769: N = options->N;
770: n = N;
771: names = options->names;
772:
773: for (i=0; i<N; i++) {
774: PetscStrcasecmp(names[i],name,&match);
775: PetscStrgrt(names[i],name,>);
776: if (match) {
777: if (options->values[i]) free(options->values[i]);
778: PetscStrlen(value,&len);
779: if (len) {
780: options->values[i] = (char*)malloc((len+1)*sizeof(char));
781: PetscStrcpy(options->values[i],value);
782: } else { options->values[i] = 0;}
783: PetscOptionsMonitor(name,value);
784: return(0);
785: } else if (gt) {
786: n = i;
787: break;
788: }
789: }
790: if (N >= MAXOPTIONS) {
791: 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);
792: }
793: /* shift remaining values down 1 */
794: for (i=N; i>n; i--) {
795: options->names[i] = options->names[i-1];
796: options->values[i] = options->values[i-1];
797: options->used[i] = options->used[i-1];
798: }
799: /* insert new name and value */
800: PetscStrlen(name,&len);
801: options->names[n] = (char*)malloc((len+1)*sizeof(char));
802: PetscStrcpy(options->names[n],name);
803: PetscStrlen(value,&len);
804: if (len) {
805: options->values[n] = (char*)malloc((len+1)*sizeof(char));
806: PetscStrcpy(options->values[n],value);
807: } else {options->values[n] = 0;}
808: options->used[n] = PETSC_FALSE;
809: options->N++;
810: PetscOptionsMonitor(name,value);
811: return(0);
812: }
816: /*@C
817: PetscOptionsClearValue - Clears an option name-value pair in the options
818: database, overriding whatever is already present.
820: Not Collective, but setting values on certain processors could cause problems
821: for parallel objects looking for options.
823: Input Parameter:
824: . name - name of option, this SHOULD have the - prepended
826: Level: intermediate
828: Concepts: options database^removing option
829: .seealso: PetscOptionsInsert()
830: @*/
831: PetscErrorCode PetscOptionsClearValue(const char iname[])
832: {
834: PetscInt N,n,i;
835: char **names,*name=(char*)iname;
836: PetscTruth gt,match;
839: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
840: if (!options) {PetscOptionsInsert(0,0,0);}
842: name++;
844: N = options->N; n = 0;
845: names = options->names;
846:
847: for (i=0; i<N; i++) {
848: PetscStrcasecmp(names[i],name,&match);
849: PetscStrgrt(names[i],name,>);
850: if (match) {
851: if (options->names[i]) free(options->names[i]);
852: if (options->values[i]) free(options->values[i]);
853: PetscOptionsMonitor(name,"");
854: break;
855: } else if (gt) {
856: return(0); /* it was not listed */
857: }
858: n++;
859: }
860: if (n == N) return(0); /* it was not listed */
862: /* shift remaining values down 1 */
863: for (i=n; i<N-1; i++) {
864: options->names[i] = options->names[i+1];
865: options->values[i] = options->values[i+1];
866: options->used[i] = options->used[i+1];
867: }
868: options->N--;
869: return(0);
870: }
874: /*@C
875: PetscOptionsReject - Generates an error if a certain option is given.
877: Not Collective, but setting values on certain processors could cause problems
878: for parallel objects looking for options.
880: Input Parameters:
881: + name - the option one is seeking
882: - mess - error message (may be PETSC_NULL)
884: Level: advanced
886: Concepts: options database^rejecting option
888: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
889: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
890: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
891: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
892: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
893: PetscOptionsList(), PetscOptionsEList()
894: @*/
895: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
896: {
898: PetscInt n = options->Naliases;
899: size_t len;
900: char *newname = (char *)inewname,*oldname = (char*)ioldname;
903: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
904: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
905: if (n >= MAXALIASES) {
906: 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);
907: }
909: newname++; oldname++;
910: PetscStrlen(newname,&len);
911: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
912: PetscStrcpy(options->aliases1[n],newname);
913: PetscStrlen(oldname,&len);
914: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
915: PetscStrcpy(options->aliases2[n],oldname);
916: options->Naliases++;
917: return(0);
918: }
922: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
923: {
925: PetscInt i,N;
926: size_t len;
927: char **names,tmp[256];
928: PetscTruth match;
931: if (!options) {PetscOptionsInsert(0,0,0);}
932: N = options->N;
933: names = options->names;
935: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
937: /* append prefix to name */
938: if (pre) {
939: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
940: PetscStrncpy(tmp,pre,256);
941: PetscStrlen(tmp,&len);
942: PetscStrncat(tmp,name+1,256-len-1);
943: } else {
944: PetscStrncpy(tmp,name+1,256);
945: }
947: /* slow search */
948: *flg = PETSC_FALSE;
949: for (i=0; i<N; i++) {
950: PetscStrcasecmp(names[i],tmp,&match);
951: if (match) {
952: *value = options->values[i];
953: options->used[i] = PETSC_TRUE;
954: *flg = PETSC_TRUE;
955: break;
956: }
957: }
958: if (!*flg) {
959: PetscInt j,cnt = 0,locs[16],loce[16];
960: size_t n;
961: PetscStrlen(tmp,&n);
962: /* determine the location and number of all _%d_ in the key */
963: for (i=0; i< (PetscInt)n; i++) {
964: if (tmp[i] == '_') {
965: for (j=i+1; j< (PetscInt)n; j++) {
966: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
967: if (tmp[j] == '_' && j > i+1) { /* found a number */
968: locs[cnt] = i+1;
969: loce[cnt++] = j+1;
970: }
971: break;
972: }
973: }
974: }
975: if (cnt) {
976: char tmp2[256];
977: for (i=0; i<cnt; i++) {
978: PetscStrcpy(tmp2,"-");
979: PetscStrncat(tmp2,tmp,locs[i]);
980: PetscStrcat(tmp2,tmp+loce[i]);
981: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
982: if (*flg) break;
983: }
984: }
985: }
986: return(0);
987: }
991: /*@C
992: PetscOptionsReject - Generates an error if a certain option is given.
994: Not Collective, but setting values on certain processors could cause problems
995: for parallel objects looking for options.
997: Input Parameters:
998: + name - the option one is seeking
999: - mess - error message (may be PETSC_NULL)
1001: Level: advanced
1003: Concepts: options database^rejecting option
1005: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1006: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1007: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1008: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1009: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1010: PetscOptionsList(), PetscOptionsEList()
1011: @*/
1012: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1013: {
1015: PetscTruth flag;
1018: PetscOptionsHasName(PETSC_NULL,name,&flag);
1019: if (flag) {
1020: if (mess) {
1021: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1022: } else {
1023: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1024: }
1025: }
1026: return(0);
1027: }
1031: /*@C
1032: PetscOptionsHasName - Determines whether a certain option is given in the database.
1034: Not Collective
1036: Input Parameters:
1037: + name - the option one is seeking
1038: - pre - string to prepend to the name or PETSC_NULL
1040: Output Parameters:
1041: . flg - PETSC_TRUE if found else PETSC_FALSE.
1043: Level: beginner
1045: Concepts: options database^has option name
1047: Notes: Name cannot be simply -h
1049: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1050: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1051: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1052: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1053: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1054: PetscOptionsList(), PetscOptionsEList()
1055: @*/
1056: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1057: {
1058: char *value;
1060: PetscTruth isfalse,flag;
1063: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1065: /* remove if turned off */
1066: if (flag) {
1067: PetscStrcasecmp(value,"FALSE",&isfalse);
1068: if (isfalse) flag = PETSC_FALSE;
1069: PetscStrcasecmp(value,"NO",&isfalse);
1070: if (isfalse) flag = PETSC_FALSE;
1071: PetscStrcasecmp(value,"0",&isfalse);
1072: if (isfalse) flag = PETSC_FALSE;
1073: }
1074: if (flg) *flg = flag;
1075: return(0);
1076: }
1080: /*@C
1081: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1083: Not Collective
1085: Input Parameters:
1086: + pre - the string to prepend to the name or PETSC_NULL
1087: - name - the option one is seeking
1089: Output Parameter:
1090: + ivalue - the integer value to return
1091: - flg - PETSC_TRUE if found, else PETSC_FALSE
1093: Level: beginner
1095: Concepts: options database^has int
1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1098: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1099: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1100: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1101: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1102: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1103: PetscOptionsList(), PetscOptionsEList()
1104: @*/
1105: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1106: {
1107: char *value;
1109: PetscTruth flag;
1114: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1115: if (flag) {
1116: if (!value) {if (flg) *flg = PETSC_FALSE;}
1117: else {
1118: if (flg) *flg = PETSC_TRUE;
1119: PetscOptionsAtoi(value,ivalue);
1120: }
1121: } else {
1122: if (flg) *flg = PETSC_FALSE;
1123: }
1124: return(0);
1125: }
1129: /*@C
1130: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1132: Not Collective
1134: Input Parameters:
1135: + pre - the string to prepend to the name or PETSC_NULL
1136: . opt - option name
1137: . list - the possible choices
1138: . ntext - number of choices
1140: Output Parameter:
1141: + value - the index of the value to return
1142: - set - PETSC_TRUE if found, else PETSC_FALSE
1143:
1144: Level: intermediate
1146: See PetscOptionsList() for when the choices are given in a PetscFList()
1148: Concepts: options database^list
1150: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1151: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1152: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1153: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1154: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1155: PetscOptionsList(), PetscOptionsEList()
1156: @*/
1157: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1158: {
1160: size_t alen,len = 0;
1161: char *svalue;
1162: PetscTruth aset,flg = PETSC_FALSE;
1163: PetscInt i;
1166: for ( i=0; i<ntext; i++) {
1167: PetscStrlen(list[i],&alen);
1168: if (alen > len) len = alen;
1169: }
1170: len += 5; /* a little extra space for user mistypes */
1171: PetscMalloc(len*sizeof(char),&svalue);
1172: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1173: if (aset) {
1174: if (set) *set = PETSC_TRUE;
1175: for (i=0; i<ntext; i++) {
1176: PetscStrcasecmp(svalue,list[i],&flg);
1177: if (flg) {
1178: *value = i;
1179: break;
1180: }
1181: }
1182: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1183: } else if (set) {
1184: *set = PETSC_FALSE;
1185: }
1186: PetscFree(svalue);
1187: return(0);
1188: }
1192: /*@C
1193: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1195: Not Collective
1197: Input Parameters:
1198: + pre - option prefix or PETSC_NULL
1199: . opt - option name
1200: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1201: - defaultv - the default (current) value
1203: Output Parameter:
1204: + value - the value to return
1205: - flg - PETSC_TRUE if found, else PETSC_FALSE
1207: Level: beginner
1209: Concepts: options database
1211: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1213: list is usually something like PCASMTypes or some other predefined list of enum names
1215: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1216: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1217: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1218: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1219: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1220: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1221: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1222: @*/
1223: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1224: {
1226: PetscInt ntext = 0;
1229: while (list[ntext++]) {
1230: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1231: }
1232: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1233: ntext -= 3;
1234: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1235: return(0);
1236: }
1240: /*@C
1241: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1242: option in the database.
1244: Not Collective
1246: Input Parameters:
1247: + pre - the string to prepend to the name or PETSC_NULL
1248: - name - the option one is seeking
1250: Output Parameter:
1251: + ivalue - the logical value to return
1252: - flg - PETSC_TRUE if found, else PETSC_FALSE
1254: Level: beginner
1256: Notes:
1257: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1258: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1260: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1261: you NEED TO ALWAYS initialize the ivalue.
1263: Concepts: options database^has logical
1265: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1266: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1267: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1268: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1269: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1270: PetscOptionsList(), PetscOptionsEList()
1271: @*/
1272: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1273: {
1274: char *value;
1275: PetscTruth flag;
1281: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1282: if (flag) {
1283: if (flg) *flg = PETSC_TRUE;
1284: if (!value) {
1285: *ivalue = PETSC_TRUE;
1286: } else {
1287: PetscOptionsAtol(value, ivalue);
1288: }
1289: } else {
1290: if (flg) *flg = PETSC_FALSE;
1291: }
1292: return(0);
1293: }
1297: /*@C
1298: PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular
1299: option in the database. The values must be separated with commas with
1300: no intervening spaces.
1302: Not Collective
1304: Input Parameters:
1305: + pre - string to prepend to each name or PETSC_NULL
1306: . name - the option one is seeking
1307: - nmax - maximum number of values to retrieve
1309: Output Parameter:
1310: + dvalue - the integer values to return
1311: . nmax - actual number of values retreived
1312: - flg - PETSC_TRUE if found, else PETSC_FALSE
1314: Level: beginner
1316: Concepts: options database^array of ints
1318: Notes:
1319: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1320: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1322: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1323: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1324: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1325: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1326: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1327: PetscOptionsList(), PetscOptionsEList()
1328: @*/
1329: PetscErrorCode PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1330: {
1331: char *value;
1333: PetscInt n = 0;
1334: PetscTruth flag;
1335: PetscToken token;
1340: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1341: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1342: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1344: if (flg) *flg = PETSC_TRUE;
1346: PetscTokenCreate(value,',',&token);
1347: PetscTokenFind(token,&value);
1348: while (n < *nmax) {
1349: if (!value) break;
1350: PetscOptionsAtol(value,dvalue);
1351: PetscTokenFind(token,&value);
1352: dvalue++;
1353: n++;
1354: }
1355: PetscTokenDestroy(token);
1356: *nmax = n;
1357: return(0);
1358: }
1362: /*@C
1363: PetscOptionsGetReal - Gets the double precision value for a particular
1364: option in the database.
1366: Not Collective
1368: Input Parameters:
1369: + pre - string to prepend to each name or PETSC_NULL
1370: - name - the option one is seeking
1372: Output Parameter:
1373: + dvalue - the double value to return
1374: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1376: Level: beginner
1378: Concepts: options database^has double
1380: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1381: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1382: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1383: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1384: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1385: PetscOptionsList(), PetscOptionsEList()
1386: @*/
1387: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1388: {
1389: char *value;
1391: PetscTruth flag;
1396: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1397: if (flag) {
1398: if (!value) {if (flg) *flg = PETSC_FALSE;}
1399: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1400: } else {
1401: if (flg) *flg = PETSC_FALSE;
1402: }
1403: return(0);
1404: }
1408: /*@C
1409: PetscOptionsGetScalar - Gets the scalar value for a particular
1410: option in the database.
1412: Not Collective
1414: Input Parameters:
1415: + pre - string to prepend to each name or PETSC_NULL
1416: - name - the option one is seeking
1418: Output Parameter:
1419: + dvalue - the double value to return
1420: - flg - PETSC_TRUE if found, else PETSC_FALSE
1422: Level: beginner
1424: Usage:
1425: A complex number 2+3i can be specified as 2,3 at the command line.
1426: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1428: Concepts: options database^has scalar
1430: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1431: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1432: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1433: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1434: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1435: PetscOptionsList(), PetscOptionsEList()
1436: @*/
1437: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1438: {
1439: char *value;
1440: PetscTruth flag;
1446: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1447: if (flag) {
1448: if (!value) {
1449: if (flg) *flg = PETSC_FALSE;
1450: } else {
1451: #if !defined(PETSC_USE_COMPLEX)
1452: PetscOptionsAtod(value,dvalue);
1453: #else
1454: PetscReal re=0.0,im=0.0;
1455: PetscToken token;
1456: char *tvalue = 0;
1458: PetscTokenCreate(value,',',&token);
1459: PetscTokenFind(token,&tvalue);
1460: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1461: PetscOptionsAtod(tvalue,&re);
1462: PetscTokenFind(token,&tvalue);
1463: if (!tvalue) { /* Unknown separator used. using only real value */
1464: *dvalue = re;
1465: } else {
1466: PetscOptionsAtod(tvalue,&im);
1467: *dvalue = re + PETSC_i*im;
1468: }
1469: PetscTokenDestroy(token);
1470: #endif
1471: if (flg) *flg = PETSC_TRUE;
1472: }
1473: } else { /* flag */
1474: if (flg) *flg = PETSC_FALSE;
1475: }
1476: return(0);
1477: }
1481: /*@C
1482: PetscOptionsGetRealArray - Gets an array of double precision values for a
1483: particular option in the database. The values must be separated with
1484: commas with no intervening spaces.
1486: Not Collective
1488: Input Parameters:
1489: + pre - string to prepend to each name or PETSC_NULL
1490: . name - the option one is seeking
1491: - nmax - maximum number of values to retrieve
1493: Output Parameters:
1494: + dvalue - the double value to return
1495: . nmax - actual number of values retreived
1496: - flg - PETSC_TRUE if found, else PETSC_FALSE
1498: Level: beginner
1500: Concepts: options database^array of doubles
1502: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1503: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1504: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1505: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1506: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1507: PetscOptionsList(), PetscOptionsEList()
1508: @*/
1509: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1510: {
1511: char *value;
1513: PetscInt n = 0;
1514: PetscTruth flag;
1515: PetscToken token;
1520: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1521: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1522: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1524: if (flg) *flg = PETSC_TRUE;
1526: PetscTokenCreate(value,',',&token);
1527: PetscTokenFind(token,&value);
1528: while (n < *nmax) {
1529: if (!value) break;
1530: PetscOptionsAtod(value,dvalue++);
1531: PetscTokenFind(token,&value);
1532: n++;
1533: }
1534: PetscTokenDestroy(token);
1535: *nmax = n;
1536: return(0);
1537: }
1541: /*@C
1542: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1543: option in the database. The values must be separated with commas with
1544: no intervening spaces.
1546: Not Collective
1548: Input Parameters:
1549: + pre - string to prepend to each name or PETSC_NULL
1550: . name - the option one is seeking
1551: - nmax - maximum number of values to retrieve
1553: Output Parameter:
1554: + dvalue - the integer values to return
1555: . nmax - actual number of values retreived
1556: - flg - PETSC_TRUE if found, else PETSC_FALSE
1558: Level: beginner
1560: Concepts: options database^array of ints
1562: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1563: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1564: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1565: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1566: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1567: PetscOptionsList(), PetscOptionsEList()
1568: @*/
1569: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1570: {
1571: char *value;
1573: PetscInt n = 0,i,start,end;
1574: size_t len;
1575: PetscTruth flag,foundrange;
1576: PetscToken token;
1581: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1582: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1583: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1585: if (flg) *flg = PETSC_TRUE;
1587: PetscTokenCreate(value,',',&token);
1588: PetscTokenFind(token,&value);
1589: while (n < *nmax) {
1590: if (!value) break;
1591:
1592: /* look for form d-D where d and D are integers */
1593: foundrange = PETSC_FALSE;
1594: PetscStrlen(value,&len);
1595: if (value[0] == '-') i=2;
1596: else i=1;
1597: for (;i<(int)len; i++) {
1598: if (value[i] == '-') {
1599: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1600: value[i] = 0;
1601: PetscOptionsAtoi(value,&start);
1602: PetscOptionsAtoi(value+i+1,&end);
1603: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1604: 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);
1605: for (;start<end; start++) {
1606: *dvalue = start; dvalue++;n++;
1607: }
1608: foundrange = PETSC_TRUE;
1609: break;
1610: }
1611: }
1612: if (!foundrange) {
1613: PetscOptionsAtoi(value,dvalue);
1614: dvalue++;
1615: n++;
1616: }
1617: PetscTokenFind(token,&value);
1618: }
1619: PetscTokenDestroy(token);
1620: *nmax = n;
1621: return(0);
1622: }
1626: /*@C
1627: PetscOptionsGetString - Gets the string value for a particular option in
1628: the database.
1630: Not Collective
1632: Input Parameters:
1633: + pre - string to prepend to name or PETSC_NULL
1634: . name - the option one is seeking
1635: - len - maximum string length
1637: Output Parameters:
1638: + string - location to copy string
1639: - flg - PETSC_TRUE if found, else PETSC_FALSE
1641: Level: beginner
1643: Fortran Note:
1644: The Fortran interface is slightly different from the C/C++
1645: interface (len is not used). Sample usage in Fortran follows
1646: .vb
1647: character *20 string
1648: integer flg, ierr
1649: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1650: .ve
1652: Concepts: options database^string
1654: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1655: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1656: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1657: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1658: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1659: PetscOptionsList(), PetscOptionsEList()
1660: @*/
1661: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1662: {
1663: char *value;
1665: PetscTruth flag;
1670: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1671: if (!flag) {
1672: if (flg) *flg = PETSC_FALSE;
1673: } else {
1674: if (flg) *flg = PETSC_TRUE;
1675: if (value) {
1676: PetscStrncpy(string,value,len);
1677: } else {
1678: PetscMemzero(string,len);
1679: }
1680: }
1681: return(0);
1682: }
1686: /*@C
1687: PetscOptionsGetStringArray - Gets an array of string values for a particular
1688: option in the database. The values must be separated with commas with
1689: no intervening spaces.
1691: Not Collective
1693: Input Parameters:
1694: + pre - string to prepend to name or PETSC_NULL
1695: . name - the option one is seeking
1696: - nmax - maximum number of strings
1698: Output Parameter:
1699: + strings - location to copy strings
1700: - flg - PETSC_TRUE if found, else PETSC_FALSE
1702: Level: beginner
1704: Notes:
1705: The user should pass in an array of pointers to char, to hold all the
1706: strings returned by this function.
1708: The user is responsible for deallocating the strings that are
1709: returned. The Fortran interface for this routine is not supported.
1711: Contributed by Matthew Knepley.
1713: Concepts: options database^array of strings
1715: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1716: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1717: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1718: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1719: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1720: PetscOptionsList(), PetscOptionsEList()
1721: @*/
1722: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1723: {
1724: char *value;
1726: PetscInt n;
1727: PetscTruth flag;
1728: PetscToken token;
1729:
1733: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1734: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1735: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1736: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1737: if (flg) *flg = PETSC_TRUE;
1739: PetscTokenCreate(value,',',&token);
1740: PetscTokenFind(token,&value);
1741: n = 0;
1742: while (n < *nmax) {
1743: if (!value) break;
1744: PetscStrallocpy(value,&strings[n]);
1745: PetscTokenFind(token,&value);
1746: n++;
1747: }
1748: PetscTokenDestroy(token);
1749: *nmax = n;
1750: return(0);
1751: }
1755: /*@C
1756: PetscOptionsAllUsed - Returns a count of the number of options in the
1757: database that have never been selected.
1759: Not Collective
1761: Output Parameter:
1762: . N - count of options not used
1764: Level: advanced
1766: .seealso: PetscOptionsPrint()
1767: @*/
1768: PetscErrorCode PetscOptionsAllUsed(int *N)
1769: {
1770: PetscInt i,n = 0;
1773: for (i=0; i<options->N; i++) {
1774: if (!options->used[i]) { n++; }
1775: }
1776: *N = n;
1777: return(0);
1778: }
1782: /*@
1783: PetscOptionsLeft - Prints to screen any options that were set and never used.
1785: Not collective
1787: Options Database Key:
1788: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1790: Level: advanced
1792: .seealso: PetscOptionsAllUsed()
1793: @*/
1794: PetscErrorCode PetscOptionsLeft(void)
1795: {
1797: PetscInt i;
1800: for (i=0; i<options->N; i++) {
1801: if (!options->used[i]) {
1802: if (options->values[i]) {
1803: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1804: } else {
1805: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1806: }
1807: }
1808: }
1809: return(0);
1810: }
1813: /*
1814: PetscOptionsCreate - Creates the empty options database.
1816: */
1819: PetscErrorCode PetscOptionsCreate(void)
1820: {
1824: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1825: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1826: options->namegiven = PETSC_FALSE;
1827: options->N = 0;
1828: options->Naliases = 0;
1829: options->numbermonitors = 0;
1831: PetscOptionsObject.prefix = PETSC_NULL;
1832: PetscOptionsObject.title = PETSC_NULL;
1833:
1834: return(0);
1835: }
1839: /*@
1840: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1842: Collective on PETSC_COMM_WORLD
1844: Options Database Keys:
1845: + -options_monitor <optional filename> - prints the names and values of all
1846: runtime options as they are set. The monitor functionality is not
1847: available for options set through a file, environment variable, or on
1848: the command line. Only options set after PetscInitialize completes will
1849: be monitored.
1850: . -options_monitor_cancel - cancel all options database monitors
1852: Notes:
1853: To see all options, run your program with the -help option or consult
1854: the users manual.
1856: Level: intermediate
1858: .keywords: set, options, database
1859: @*/
1860: PetscErrorCode PetscOptionsSetFromOptions(void)
1861: {
1862: PetscTruth flg;
1863: PetscErrorCode ierr;
1864: char monfilename[PETSC_MAX_PATH_LEN];
1865: PetscViewer monviewer;
1869: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1870: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1871: if (flg && (!options->numbermonitors)) {
1872: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1873: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1874: }
1875:
1876: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1877: if (flg) { PetscOptionsMonitorCancel(); }
1878:
1879: PetscOptionsEnd();
1881: return(0);
1882: }
1887: /*@C
1888: PetscOptionsMonitorDefault - Print all options set value events.
1890: Collective on PETSC_COMM_WORLD
1892: Input Parameters:
1893: + name - option name string
1894: . value - option value string
1895: - dummy - unused monitor context
1897: Level: intermediate
1899: .keywords: PetscOptions, default, monitor
1901: .seealso: PetscOptionsMonitorSet()
1902: @*/
1903: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1904: {
1906: PetscViewer viewer = (PetscViewer) dummy;
1909: if (!viewer) {
1910: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1911: }
1912: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1913: return(0);
1914: }
1918: /*@C
1919: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1920: modified the PETSc options database.
1921:
1922: Not collective
1924: Input Parameters:
1925: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1926: . mctx - [optional] context for private data for the
1927: monitor routine (use PETSC_NULL if no context is desired)
1928: - monitordestroy - [optional] routine that frees monitor context
1929: (may be PETSC_NULL)
1931: Calling Sequence of monitor:
1932: $ monitor (const char name[], const char value[], void *mctx)
1934: + name - option name string
1935: . value - option value string
1936: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1938: Options Database Keys:
1939: + -options_monitor - sets PetscOptionsMonitorDefault()
1940: - -options_monitor_cancel - cancels all monitors that have
1941: been hardwired into a code by
1942: calls to PetscOptionsMonitorSet(), but
1943: does not cancel those set via
1944: the options database.
1946: Notes:
1947: The default is to do nothing. To print the name and value of options
1948: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1949: with a null monitoring context.
1951: Several different monitoring routines may be set by calling
1952: PetscOptionsMonitorSet() multiple times; all will be called in the
1953: order in which they were set.
1955: Level: beginner
1957: .keywords: PetscOptions, set, monitor
1959: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1960: @*/
1961: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1962: {
1964: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1965: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1966: }
1967: options->monitor[options->numbermonitors] = monitor;
1968: options->monitordestroy[options->numbermonitors] = monitordestroy;
1969: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1970: return(0);
1971: }
1975: /*@
1976: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
1978: Not collective
1980: Options Database Key:
1981: . -options_monitor_cancel - Cancels all monitors that have
1982: been hardwired into a code by calls to PetscOptionsMonitorSet(),
1983: but does not cancel those set via the options database.
1985: Level: intermediate
1987: .keywords: PetscOptions, set, monitor
1989: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1990: @*/
1991: PetscErrorCode PetscOptionsMonitorCancel(void)
1992: {
1994: PetscInt i;
1997: for (i=0; i<options->numbermonitors; i++) {
1998: if (options->monitordestroy[i]) {
1999: (*options->monitordestroy[i])(options->monitorcontext[i]);
2000: }
2001: }
2002: options->numbermonitors = 0;
2003: return(0);
2004: }