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=0,acnt=0;
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: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
501: }
503: /* insert environmental options */
504: {
505: char *eoptions = 0;
506: size_t len = 0;
507: if (!rank) {
508: eoptions = (char*)getenv("PETSC_OPTIONS");
509: PetscStrlen(eoptions,&len);
510: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
511: } else {
512: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
513: if (len) {
514: PetscMalloc((len+1)*sizeof(char*),&eoptions);
515: }
516: }
517: if (len) {
518: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
519: if (rank) eoptions[len] = 0;
520: PetscOptionsInsertString(eoptions);
521: if (rank) {PetscFree(eoptions);}
522: }
523: }
525: /* insert command line options */
526: if (argc && args && *argc) {
527: int left = *argc - 1;
528: char **eargs = *args + 1;
529: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
531: while (left) {
532: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
533: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
534: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
535: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
536: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
537: isp4 = (PetscTruth) (isp4 || tisp4);
538: PetscStrcasecmp(eargs[0],"-np",&tisp4);
539: isp4 = (PetscTruth) (isp4 || tisp4);
540: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
542: if (eargs[0][0] != '-') {
543: eargs++; left--;
544: } else if (isoptions_file) {
545: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
546: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
547: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
548: eargs += 2; left -= 2;
550: /*
551: These are "bad" options that MPICH, etc put on the command line
552: we strip them out here.
553: */
554: } else if (tisp4 || isp4rmrank) {
555: eargs += 1; left -= 1;
556: } else if (isp4 || isp4yourname) {
557: eargs += 2; left -= 2;
558: } else if ((left < 2) || ((eargs[1][0] == '-') &&
559: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
560: PetscOptionsSetValue(eargs[0],PETSC_NULL);
561: eargs++; left--;
562: } else {
563: PetscOptionsSetValue(eargs[0],eargs[1]);
564: eargs += 2; left -= 2;
565: }
566: }
567: }
568: return(0);
569: }
573: /*@C
574: PetscOptionsPrint - Prints the options that have been loaded. This is
575: useful for debugging purposes.
577: Collective on PETSC_COMM_WORLD
579: Input Parameter:
580: . FILE fd - location to print options (usually stdout or stderr)
582: Options Database Key:
583: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
585: Level: advanced
587: Concepts: options database^printing
589: .seealso: PetscOptionsAllUsed()
590: @*/
591: PetscErrorCode PetscOptionsPrint(FILE *fd)
592: {
594: PetscInt i;
597: if (!fd) fd = PETSC_STDOUT;
598: if (!options) {PetscOptionsInsert(0,0,0);}
599: if (options->N) {
600: PetscFPrintf(PETSC_COMM_WORLD,fd,"#PETSc Option Table entries:\n");
601: } else {
602: PetscFPrintf(PETSC_COMM_WORLD,fd,"#No PETSc Option Table entries\n");
603: }
604: for (i=0; i<options->N; i++) {
605: if (options->values[i]) {
606: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s %s\n",options->names[i],options->values[i]);
607: } else {
608: PetscFPrintf(PETSC_COMM_WORLD,fd,"-%s\n",options->names[i]);
609: }
610: }
611: if (options->N) {
612: PetscFPrintf(PETSC_COMM_WORLD,fd,"#End o PETSc Option Table entries\n");
613: }
614: return(0);
615: }
619: /*@C
620: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
622: Not Collective
624: Output Parameter:
625: . copts - pointer where string pointer is stored
627: Level: advanced
629: Concepts: options database^listing
631: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
632: @*/
633: PetscErrorCode PetscOptionsGetAll(char *copts[])
634: {
636: PetscInt i;
637: size_t len = 1,lent;
638: char *coptions;
641: if (!options) {PetscOptionsInsert(0,0,0);}
643: /* count the length of the required string */
644: for (i=0; i<options->N; i++) {
645: PetscStrlen(options->names[i],&lent);
646: len += 2 + lent;
647: if (options->values[i]) {
648: PetscStrlen(options->values[i],&lent);
649: len += 1 + lent;
650: }
651: }
652: PetscMalloc(len*sizeof(char),&coptions);
653: coptions[0] = 0;
654: for (i=0; i<options->N; i++) {
655: PetscStrcat(coptions,"-");
656: PetscStrcat(coptions,options->names[i]);
657: PetscStrcat(coptions," ");
658: if (options->values[i]) {
659: PetscStrcat(coptions,options->values[i]);
660: PetscStrcat(coptions," ");
661: }
662: }
663: *copts = coptions;
664: return(0);
665: }
669: /*@C
670: PetscOptionsClear - Removes all options form the database leaving it empty.
672: Level: developer
674: .seealso: PetscOptionsInsert()
675: @*/
676: PetscErrorCode PetscOptionsClear(void)
677: {
678: PetscInt i;
681: if (!options) return(0);
682: for (i=0; i<options->N; i++) {
683: if (options->names[i]) free(options->names[i]);
684: if (options->values[i]) free(options->values[i]);
685: }
686: for (i=0; i<options->Naliases; i++) {
687: free(options->aliases1[i]);
688: free(options->aliases2[i]);
689: }
690: options->N = 0;
691: options->Naliases = 0;
692: return(0);
693: }
697: /*@C
698: PetscOptionsDestroy - Destroys the option database.
700: Note:
701: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
702: typically does not need to call this routine.
704: Level: developer
706: .seealso: PetscOptionsInsert()
707: @*/
708: PetscErrorCode PetscOptionsDestroy(void)
709: {
713: if (!options) return(0);
714: PetscOptionsClear();
715: free(options);
716: options = 0;
717: return(0);
718: }
722: /*@C
723: PetscOptionsSetValue - Sets an option name-value pair in the options
724: database, overriding whatever is already present.
726: Not collective, but setting values on certain processors could cause problems
727: for parallel objects looking for options.
729: Input Parameters:
730: + name - name of option, this SHOULD have the - prepended
731: - value - the option value (not used for all options)
733: Level: intermediate
735: Note:
736: Only some options have values associated with them, such as
737: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
739: Concepts: options database^adding option
741: .seealso: PetscOptionsInsert()
742: @*/
743: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
744: {
745: size_t len;
747: PetscInt N,n,i;
748: char **names;
749: const char *name = (char*)iname;
750: PetscTruth gt,match;
753: if (!options) {PetscOptionsInsert(0,0,0);}
755: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
756: PetscStrcasecmp(name,"-h",&match);
757: if (match) name = "-help";
759: name++;
760: /* first check against aliases */
761: N = options->Naliases;
762: for (i=0; i<N; i++) {
763: PetscStrcasecmp(options->aliases1[i],name,&match);
764: if (match) {
765: name = options->aliases2[i];
766: break;
767: }
768: }
770: N = options->N;
771: n = N;
772: names = options->names;
773:
774: for (i=0; i<N; i++) {
775: PetscStrcasecmp(names[i],name,&match);
776: PetscStrgrt(names[i],name,>);
777: if (match) {
778: if (options->values[i]) free(options->values[i]);
779: PetscStrlen(value,&len);
780: if (len) {
781: options->values[i] = (char*)malloc((len+1)*sizeof(char));
782: PetscStrcpy(options->values[i],value);
783: } else { options->values[i] = 0;}
784: PetscOptionsMonitor(name,value);
785: return(0);
786: } else if (gt) {
787: n = i;
788: break;
789: }
790: }
791: if (N >= MAXOPTIONS) {
792: 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);
793: }
794: /* shift remaining values down 1 */
795: for (i=N; i>n; i--) {
796: options->names[i] = options->names[i-1];
797: options->values[i] = options->values[i-1];
798: options->used[i] = options->used[i-1];
799: }
800: /* insert new name and value */
801: PetscStrlen(name,&len);
802: options->names[n] = (char*)malloc((len+1)*sizeof(char));
803: PetscStrcpy(options->names[n],name);
804: PetscStrlen(value,&len);
805: if (len) {
806: options->values[n] = (char*)malloc((len+1)*sizeof(char));
807: PetscStrcpy(options->values[n],value);
808: } else {options->values[n] = 0;}
809: options->used[n] = PETSC_FALSE;
810: options->N++;
811: PetscOptionsMonitor(name,value);
812: return(0);
813: }
817: /*@C
818: PetscOptionsClearValue - Clears an option name-value pair in the options
819: database, overriding whatever is already present.
821: Not Collective, but setting values on certain processors could cause problems
822: for parallel objects looking for options.
824: Input Parameter:
825: . name - name of option, this SHOULD have the - prepended
827: Level: intermediate
829: Concepts: options database^removing option
830: .seealso: PetscOptionsInsert()
831: @*/
832: PetscErrorCode PetscOptionsClearValue(const char iname[])
833: {
835: PetscInt N,n,i;
836: char **names,*name=(char*)iname;
837: PetscTruth gt,match;
840: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
841: if (!options) {PetscOptionsInsert(0,0,0);}
843: name++;
845: N = options->N; n = 0;
846: names = options->names;
847:
848: for (i=0; i<N; i++) {
849: PetscStrcasecmp(names[i],name,&match);
850: PetscStrgrt(names[i],name,>);
851: if (match) {
852: if (options->names[i]) free(options->names[i]);
853: if (options->values[i]) free(options->values[i]);
854: PetscOptionsMonitor(name,"");
855: break;
856: } else if (gt) {
857: return(0); /* it was not listed */
858: }
859: n++;
860: }
861: if (n == N) return(0); /* it was not listed */
863: /* shift remaining values down 1 */
864: for (i=n; i<N-1; i++) {
865: options->names[i] = options->names[i+1];
866: options->values[i] = options->values[i+1];
867: options->used[i] = options->used[i+1];
868: }
869: options->N--;
870: return(0);
871: }
875: /*@C
876: PetscOptionsReject - Generates an error if a certain option is given.
878: Not Collective, but setting values on certain processors could cause problems
879: for parallel objects looking for options.
881: Input Parameters:
882: + name - the option one is seeking
883: - mess - error message (may be PETSC_NULL)
885: Level: advanced
887: Concepts: options database^rejecting option
889: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
890: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
891: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
892: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
893: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
894: PetscOptionsList(), PetscOptionsEList()
895: @*/
896: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
897: {
899: PetscInt n = options->Naliases;
900: size_t len;
901: char *newname = (char *)inewname,*oldname = (char*)ioldname;
904: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
905: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
906: if (n >= MAXALIASES) {
907: 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);
908: }
910: newname++; oldname++;
911: PetscStrlen(newname,&len);
912: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
913: PetscStrcpy(options->aliases1[n],newname);
914: PetscStrlen(oldname,&len);
915: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
916: PetscStrcpy(options->aliases2[n],oldname);
917: options->Naliases++;
918: return(0);
919: }
923: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
924: {
926: PetscInt i,N;
927: size_t len;
928: char **names,tmp[256];
929: PetscTruth match;
932: if (!options) {PetscOptionsInsert(0,0,0);}
933: N = options->N;
934: names = options->names;
936: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
938: /* append prefix to name */
939: if (pre) {
940: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
941: PetscStrncpy(tmp,pre,256);
942: PetscStrlen(tmp,&len);
943: PetscStrncat(tmp,name+1,256-len-1);
944: } else {
945: PetscStrncpy(tmp,name+1,256);
946: }
948: /* slow search */
949: *flg = PETSC_FALSE;
950: for (i=0; i<N; i++) {
951: PetscStrcasecmp(names[i],tmp,&match);
952: if (match) {
953: *value = options->values[i];
954: options->used[i] = PETSC_TRUE;
955: *flg = PETSC_TRUE;
956: break;
957: }
958: }
959: if (!*flg) {
960: PetscInt j,cnt = 0,locs[16],loce[16];
961: size_t n;
962: PetscStrlen(tmp,&n);
963: /* determine the location and number of all _%d_ in the key */
964: for (i=0; i< (PetscInt)n; i++) {
965: if (tmp[i] == '_') {
966: for (j=i+1; j< (PetscInt)n; j++) {
967: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
968: if (tmp[j] == '_' && j > i+1) { /* found a number */
969: locs[cnt] = i+1;
970: loce[cnt++] = j+1;
971: }
972: break;
973: }
974: }
975: }
976: if (cnt) {
977: char tmp2[256];
978: for (i=0; i<cnt; i++) {
979: PetscStrcpy(tmp2,"-");
980: PetscStrncat(tmp2,tmp,locs[i]);
981: PetscStrcat(tmp2,tmp+loce[i]);
982: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
983: if (*flg) break;
984: }
985: }
986: }
987: return(0);
988: }
992: /*@C
993: PetscOptionsReject - Generates an error if a certain option is given.
995: Not Collective, but setting values on certain processors could cause problems
996: for parallel objects looking for options.
998: Input Parameters:
999: + name - the option one is seeking
1000: - mess - error message (may be PETSC_NULL)
1002: Level: advanced
1004: Concepts: options database^rejecting option
1006: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1007: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1008: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1009: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1010: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1011: PetscOptionsList(), PetscOptionsEList()
1012: @*/
1013: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1014: {
1016: PetscTruth flag;
1019: PetscOptionsHasName(PETSC_NULL,name,&flag);
1020: if (flag) {
1021: if (mess) {
1022: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1023: } else {
1024: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1025: }
1026: }
1027: return(0);
1028: }
1032: /*@C
1033: PetscOptionsHasName - Determines whether a certain option is given in the database.
1035: Not Collective
1037: Input Parameters:
1038: + name - the option one is seeking
1039: - pre - string to prepend to the name or PETSC_NULL
1041: Output Parameters:
1042: . flg - PETSC_TRUE if found else PETSC_FALSE.
1044: Level: beginner
1046: Concepts: options database^has option name
1048: Notes: Name cannot be simply -h
1050: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1051: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1052: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1053: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1054: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1055: PetscOptionsList(), PetscOptionsEList()
1056: @*/
1057: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
1058: {
1059: char *value;
1061: PetscTruth isfalse,flag;
1064: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1066: /* remove if turned off */
1067: if (flag) {
1068: PetscStrcasecmp(value,"FALSE",&isfalse);
1069: if (isfalse) flag = PETSC_FALSE;
1070: PetscStrcasecmp(value,"NO",&isfalse);
1071: if (isfalse) flag = PETSC_FALSE;
1072: PetscStrcasecmp(value,"0",&isfalse);
1073: if (isfalse) flag = PETSC_FALSE;
1074: }
1075: if (flg) *flg = flag;
1076: return(0);
1077: }
1081: /*@C
1082: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1084: Not Collective
1086: Input Parameters:
1087: + pre - the string to prepend to the name or PETSC_NULL
1088: - name - the option one is seeking
1090: Output Parameter:
1091: + ivalue - the integer value to return
1092: - flg - PETSC_TRUE if found, else PETSC_FALSE
1094: Level: beginner
1096: Concepts: options database^has int
1098: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1099: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1100: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1101: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1102: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1103: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1104: PetscOptionsList(), PetscOptionsEList()
1105: @*/
1106: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
1107: {
1108: char *value;
1110: PetscTruth flag;
1115: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1116: if (flag) {
1117: if (!value) {if (flg) *flg = PETSC_FALSE;}
1118: else {
1119: if (flg) *flg = PETSC_TRUE;
1120: PetscOptionsAtoi(value,ivalue);
1121: }
1122: } else {
1123: if (flg) *flg = PETSC_FALSE;
1124: }
1125: return(0);
1126: }
1130: /*@C
1131: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1133: Not Collective
1135: Input Parameters:
1136: + pre - the string to prepend to the name or PETSC_NULL
1137: . opt - option name
1138: . list - the possible choices
1139: . ntext - number of choices
1141: Output Parameter:
1142: + value - the index of the value to return
1143: - set - PETSC_TRUE if found, else PETSC_FALSE
1144:
1145: Level: intermediate
1147: See PetscOptionsList() for when the choices are given in a PetscFList()
1149: Concepts: options database^list
1151: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1152: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1153: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1154: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1155: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1156: PetscOptionsList(), PetscOptionsEList()
1157: @*/
1158: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1159: {
1161: size_t alen,len = 0;
1162: char *svalue;
1163: PetscTruth aset,flg = PETSC_FALSE;
1164: PetscInt i;
1167: for ( i=0; i<ntext; i++) {
1168: PetscStrlen(list[i],&alen);
1169: if (alen > len) len = alen;
1170: }
1171: len += 5; /* a little extra space for user mistypes */
1172: PetscMalloc(len*sizeof(char),&svalue);
1173: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1174: if (aset) {
1175: if (set) *set = PETSC_TRUE;
1176: for (i=0; i<ntext; i++) {
1177: PetscStrcasecmp(svalue,list[i],&flg);
1178: if (flg) {
1179: *value = i;
1180: break;
1181: }
1182: }
1183: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1184: } else if (set) {
1185: *set = PETSC_FALSE;
1186: }
1187: PetscFree(svalue);
1188: return(0);
1189: }
1193: /*@C
1194: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1196: Not Collective
1198: Input Parameters:
1199: + pre - option prefix or PETSC_NULL
1200: . opt - option name
1201: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1202: - defaultv - the default (current) value
1204: Output Parameter:
1205: + value - the value to return
1206: - flg - PETSC_TRUE if found, else PETSC_FALSE
1208: Level: beginner
1210: Concepts: options database
1212: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1214: list is usually something like PCASMTypes or some other predefined list of enum names
1216: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1217: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1218: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1219: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1220: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1221: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1222: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1223: @*/
1224: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1225: {
1227: PetscInt ntext = 0;
1230: while (list[ntext++]) {
1231: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1232: }
1233: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1234: ntext -= 3;
1235: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1236: return(0);
1237: }
1241: /*@C
1242: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1243: option in the database.
1245: Not Collective
1247: Input Parameters:
1248: + pre - the string to prepend to the name or PETSC_NULL
1249: - name - the option one is seeking
1251: Output Parameter:
1252: + ivalue - the logical value to return
1253: - flg - PETSC_TRUE if found, else PETSC_FALSE
1255: Level: beginner
1257: Notes:
1258: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1259: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1261: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1262: you NEED TO ALWAYS initialize the ivalue.
1264: Concepts: options database^has logical
1266: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1267: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1268: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1269: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1270: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1271: PetscOptionsList(), PetscOptionsEList()
1272: @*/
1273: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1274: {
1275: char *value;
1276: PetscTruth flag;
1282: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1283: if (flag) {
1284: if (flg) *flg = PETSC_TRUE;
1285: if (!value) {
1286: *ivalue = PETSC_TRUE;
1287: } else {
1288: PetscOptionsAtol(value, ivalue);
1289: }
1290: } else {
1291: if (flg) *flg = PETSC_FALSE;
1292: }
1293: return(0);
1294: }
1298: /*@C
1299: PetscOptionsGetTruthArray - Gets an array of Logical (true or false) values for a particular
1300: option in the database. The values must be separated with commas with
1301: no intervening spaces.
1303: Not Collective
1305: Input Parameters:
1306: + pre - string to prepend to each name or PETSC_NULL
1307: . name - the option one is seeking
1308: - nmax - maximum number of values to retrieve
1310: Output Parameter:
1311: + dvalue - the integer values to return
1312: . nmax - actual number of values retreived
1313: - flg - PETSC_TRUE if found, else PETSC_FALSE
1315: Level: beginner
1317: Concepts: options database^array of ints
1319: Notes:
1320: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1321: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1323: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1324: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1325: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1326: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1327: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1328: PetscOptionsList(), PetscOptionsEList()
1329: @*/
1330: PetscErrorCode PetscOptionsGetTruthArray(const char pre[],const char name[],PetscTruth dvalue[],PetscInt *nmax,PetscTruth *flg)
1331: {
1332: char *value;
1334: PetscInt n = 0;
1335: PetscTruth flag;
1336: PetscToken token;
1341: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1342: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1343: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1345: if (flg) *flg = PETSC_TRUE;
1347: PetscTokenCreate(value,',',&token);
1348: PetscTokenFind(token,&value);
1349: while (n < *nmax) {
1350: if (!value) break;
1351: PetscOptionsAtol(value,dvalue);
1352: PetscTokenFind(token,&value);
1353: dvalue++;
1354: n++;
1355: }
1356: PetscTokenDestroy(token);
1357: *nmax = n;
1358: return(0);
1359: }
1363: /*@C
1364: PetscOptionsGetReal - Gets the double precision value for a particular
1365: option in the database.
1367: Not Collective
1369: Input Parameters:
1370: + pre - string to prepend to each name or PETSC_NULL
1371: - name - the option one is seeking
1373: Output Parameter:
1374: + dvalue - the double value to return
1375: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1377: Level: beginner
1379: Concepts: options database^has double
1381: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1382: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1383: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1384: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1385: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1386: PetscOptionsList(), PetscOptionsEList()
1387: @*/
1388: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1389: {
1390: char *value;
1392: PetscTruth flag;
1397: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1398: if (flag) {
1399: if (!value) {if (flg) *flg = PETSC_FALSE;}
1400: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1401: } else {
1402: if (flg) *flg = PETSC_FALSE;
1403: }
1404: return(0);
1405: }
1409: /*@C
1410: PetscOptionsGetScalar - Gets the scalar value for a particular
1411: option in the database.
1413: Not Collective
1415: Input Parameters:
1416: + pre - string to prepend to each name or PETSC_NULL
1417: - name - the option one is seeking
1419: Output Parameter:
1420: + dvalue - the double value to return
1421: - flg - PETSC_TRUE if found, else PETSC_FALSE
1423: Level: beginner
1425: Usage:
1426: A complex number 2+3i can be specified as 2,3 at the command line.
1427: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1429: Concepts: options database^has scalar
1431: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1432: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1433: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1434: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1435: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1436: PetscOptionsList(), PetscOptionsEList()
1437: @*/
1438: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1439: {
1440: char *value;
1441: PetscTruth flag;
1447: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1448: if (flag) {
1449: if (!value) {
1450: if (flg) *flg = PETSC_FALSE;
1451: } else {
1452: #if !defined(PETSC_USE_COMPLEX)
1453: PetscOptionsAtod(value,dvalue);
1454: #else
1455: PetscReal re=0.0,im=0.0;
1456: PetscToken token;
1457: char *tvalue = 0;
1459: PetscTokenCreate(value,',',&token);
1460: PetscTokenFind(token,&tvalue);
1461: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1462: PetscOptionsAtod(tvalue,&re);
1463: PetscTokenFind(token,&tvalue);
1464: if (!tvalue) { /* Unknown separator used. using only real value */
1465: *dvalue = re;
1466: } else {
1467: PetscOptionsAtod(tvalue,&im);
1468: *dvalue = re + PETSC_i*im;
1469: }
1470: PetscTokenDestroy(token);
1471: #endif
1472: if (flg) *flg = PETSC_TRUE;
1473: }
1474: } else { /* flag */
1475: if (flg) *flg = PETSC_FALSE;
1476: }
1477: return(0);
1478: }
1482: /*@C
1483: PetscOptionsGetRealArray - Gets an array of double precision values for a
1484: particular option in the database. The values must be separated with
1485: commas with no intervening spaces.
1487: Not Collective
1489: Input Parameters:
1490: + pre - string to prepend to each name or PETSC_NULL
1491: . name - the option one is seeking
1492: - nmax - maximum number of values to retrieve
1494: Output Parameters:
1495: + dvalue - the double value to return
1496: . nmax - actual number of values retreived
1497: - flg - PETSC_TRUE if found, else PETSC_FALSE
1499: Level: beginner
1501: Concepts: options database^array of doubles
1503: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1504: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1505: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1506: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1507: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1508: PetscOptionsList(), PetscOptionsEList()
1509: @*/
1510: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1511: {
1512: char *value;
1514: PetscInt n = 0;
1515: PetscTruth flag;
1516: PetscToken token;
1521: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1522: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1523: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1525: if (flg) *flg = PETSC_TRUE;
1527: PetscTokenCreate(value,',',&token);
1528: PetscTokenFind(token,&value);
1529: while (n < *nmax) {
1530: if (!value) break;
1531: PetscOptionsAtod(value,dvalue++);
1532: PetscTokenFind(token,&value);
1533: n++;
1534: }
1535: PetscTokenDestroy(token);
1536: *nmax = n;
1537: return(0);
1538: }
1542: /*@C
1543: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1544: option in the database. The values must be separated with commas with
1545: no intervening spaces.
1547: Not Collective
1549: Input Parameters:
1550: + pre - string to prepend to each name or PETSC_NULL
1551: . name - the option one is seeking
1552: - nmax - maximum number of values to retrieve
1554: Output Parameter:
1555: + dvalue - the integer values to return
1556: . nmax - actual number of values retreived
1557: - flg - PETSC_TRUE if found, else PETSC_FALSE
1559: Level: beginner
1561: Concepts: options database^array of ints
1563: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1564: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1565: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1566: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1567: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1568: PetscOptionsList(), PetscOptionsEList()
1569: @*/
1570: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1571: {
1572: char *value;
1574: PetscInt n = 0,i,start,end;
1575: size_t len;
1576: PetscTruth flag,foundrange;
1577: PetscToken token;
1582: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1583: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1584: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1586: if (flg) *flg = PETSC_TRUE;
1588: PetscTokenCreate(value,',',&token);
1589: PetscTokenFind(token,&value);
1590: while (n < *nmax) {
1591: if (!value) break;
1592:
1593: /* look for form d-D where d and D are integers */
1594: foundrange = PETSC_FALSE;
1595: PetscStrlen(value,&len);
1596: if (value[0] == '-') i=2;
1597: else i=1;
1598: for (;i<(int)len; i++) {
1599: if (value[i] == '-') {
1600: if (i == (int)len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1601: value[i] = 0;
1602: PetscOptionsAtoi(value,&start);
1603: PetscOptionsAtoi(value+i+1,&end);
1604: if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
1605: 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);
1606: for (;start<end; start++) {
1607: *dvalue = start; dvalue++;n++;
1608: }
1609: foundrange = PETSC_TRUE;
1610: break;
1611: }
1612: }
1613: if (!foundrange) {
1614: PetscOptionsAtoi(value,dvalue);
1615: dvalue++;
1616: n++;
1617: }
1618: PetscTokenFind(token,&value);
1619: }
1620: PetscTokenDestroy(token);
1621: *nmax = n;
1622: return(0);
1623: }
1627: /*@C
1628: PetscOptionsGetString - Gets the string value for a particular option in
1629: the database.
1631: Not Collective
1633: Input Parameters:
1634: + pre - string to prepend to name or PETSC_NULL
1635: . name - the option one is seeking
1636: - len - maximum string length
1638: Output Parameters:
1639: + string - location to copy string
1640: - flg - PETSC_TRUE if found, else PETSC_FALSE
1642: Level: beginner
1644: Fortran Note:
1645: The Fortran interface is slightly different from the C/C++
1646: interface (len is not used). Sample usage in Fortran follows
1647: .vb
1648: character *20 string
1649: integer flg, ierr
1650: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1651: .ve
1653: Concepts: options database^string
1655: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1656: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1657: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1658: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1659: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1660: PetscOptionsList(), PetscOptionsEList()
1661: @*/
1662: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1663: {
1664: char *value;
1666: PetscTruth flag;
1671: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1672: if (!flag) {
1673: if (flg) *flg = PETSC_FALSE;
1674: } else {
1675: if (flg) *flg = PETSC_TRUE;
1676: if (value) {
1677: PetscStrncpy(string,value,len);
1678: } else {
1679: PetscMemzero(string,len);
1680: }
1681: }
1682: return(0);
1683: }
1687: /*@C
1688: PetscOptionsGetStringArray - Gets an array of string values for a particular
1689: option in the database. The values must be separated with commas with
1690: no intervening spaces.
1692: Not Collective
1694: Input Parameters:
1695: + pre - string to prepend to name or PETSC_NULL
1696: . name - the option one is seeking
1697: - nmax - maximum number of strings
1699: Output Parameter:
1700: + strings - location to copy strings
1701: - flg - PETSC_TRUE if found, else PETSC_FALSE
1703: Level: beginner
1705: Notes:
1706: The user should pass in an array of pointers to char, to hold all the
1707: strings returned by this function.
1709: The user is responsible for deallocating the strings that are
1710: returned. The Fortran interface for this routine is not supported.
1712: Contributed by Matthew Knepley.
1714: Concepts: options database^array of strings
1716: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1717: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1718: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1719: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1720: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1721: PetscOptionsList(), PetscOptionsEList()
1722: @*/
1723: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1724: {
1725: char *value;
1727: PetscInt n;
1728: PetscTruth flag;
1729: PetscToken token;
1730:
1734: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1735: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1736: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1737: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1738: if (flg) *flg = PETSC_TRUE;
1740: PetscTokenCreate(value,',',&token);
1741: PetscTokenFind(token,&value);
1742: n = 0;
1743: while (n < *nmax) {
1744: if (!value) break;
1745: PetscStrallocpy(value,&strings[n]);
1746: PetscTokenFind(token,&value);
1747: n++;
1748: }
1749: PetscTokenDestroy(token);
1750: *nmax = n;
1751: return(0);
1752: }
1756: /*@C
1757: PetscOptionsAllUsed - Returns a count of the number of options in the
1758: database that have never been selected.
1760: Not Collective
1762: Output Parameter:
1763: . N - count of options not used
1765: Level: advanced
1767: .seealso: PetscOptionsPrint()
1768: @*/
1769: PetscErrorCode PetscOptionsAllUsed(int *N)
1770: {
1771: PetscInt i,n = 0;
1774: for (i=0; i<options->N; i++) {
1775: if (!options->used[i]) { n++; }
1776: }
1777: *N = n;
1778: return(0);
1779: }
1783: /*@
1784: PetscOptionsLeft - Prints to screen any options that were set and never used.
1786: Not collective
1788: Options Database Key:
1789: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1791: Level: advanced
1793: .seealso: PetscOptionsAllUsed()
1794: @*/
1795: PetscErrorCode PetscOptionsLeft(void)
1796: {
1798: PetscInt i;
1801: for (i=0; i<options->N; i++) {
1802: if (!options->used[i]) {
1803: if (options->values[i]) {
1804: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1805: } else {
1806: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1807: }
1808: }
1809: }
1810: return(0);
1811: }
1814: /*
1815: PetscOptionsCreate - Creates the empty options database.
1817: */
1820: PetscErrorCode PetscOptionsCreate(void)
1821: {
1825: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1826: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1827: options->namegiven = PETSC_FALSE;
1828: options->N = 0;
1829: options->Naliases = 0;
1830: options->numbermonitors = 0;
1832: PetscOptionsObject.prefix = PETSC_NULL;
1833: PetscOptionsObject.title = PETSC_NULL;
1834:
1835: return(0);
1836: }
1840: /*@
1841: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1843: Collective on PETSC_COMM_WORLD
1845: Options Database Keys:
1846: + -options_monitor <optional filename> - prints the names and values of all
1847: runtime options as they are set. The monitor functionality is not
1848: available for options set through a file, environment variable, or on
1849: the command line. Only options set after PetscInitialize completes will
1850: be monitored.
1851: . -options_monitor_cancel - cancel all options database monitors
1853: Notes:
1854: To see all options, run your program with the -help option or consult
1855: the users manual.
1857: Level: intermediate
1859: .keywords: set, options, database
1860: @*/
1861: PetscErrorCode PetscOptionsSetFromOptions(void)
1862: {
1863: PetscTruth flg;
1864: PetscErrorCode ierr;
1865: char monfilename[PETSC_MAX_PATH_LEN];
1866: PetscViewer monviewer;
1870: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1871: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1872: if (flg && (!options->numbermonitors)) {
1873: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1874: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1875: }
1876:
1877: PetscOptionsName("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",&flg);
1878: if (flg) { PetscOptionsMonitorCancel(); }
1879:
1880: PetscOptionsEnd();
1882: return(0);
1883: }
1888: /*@C
1889: PetscOptionsMonitorDefault - Print all options set value events.
1891: Collective on PETSC_COMM_WORLD
1893: Input Parameters:
1894: + name - option name string
1895: . value - option value string
1896: - dummy - unused monitor context
1898: Level: intermediate
1900: .keywords: PetscOptions, default, monitor
1902: .seealso: PetscOptionsMonitorSet()
1903: @*/
1904: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
1905: {
1907: PetscViewer viewer = (PetscViewer) dummy;
1910: if (!viewer) {
1911: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
1912: }
1913: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1914: return(0);
1915: }
1919: /*@C
1920: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
1921: modified the PETSc options database.
1922:
1923: Not collective
1925: Input Parameters:
1926: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1927: . mctx - [optional] context for private data for the
1928: monitor routine (use PETSC_NULL if no context is desired)
1929: - monitordestroy - [optional] routine that frees monitor context
1930: (may be PETSC_NULL)
1932: Calling Sequence of monitor:
1933: $ monitor (const char name[], const char value[], void *mctx)
1935: + name - option name string
1936: . value - option value string
1937: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
1939: Options Database Keys:
1940: + -options_monitor - sets PetscOptionsMonitorDefault()
1941: - -options_monitor_cancel - cancels all monitors that have
1942: been hardwired into a code by
1943: calls to PetscOptionsMonitorSet(), but
1944: does not cancel those set via
1945: the options database.
1947: Notes:
1948: The default is to do nothing. To print the name and value of options
1949: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
1950: with a null monitoring context.
1952: Several different monitoring routines may be set by calling
1953: PetscOptionsMonitorSet() multiple times; all will be called in the
1954: order in which they were set.
1956: Level: beginner
1958: .keywords: PetscOptions, set, monitor
1960: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
1961: @*/
1962: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1963: {
1965: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1966: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1967: }
1968: options->monitor[options->numbermonitors] = monitor;
1969: options->monitordestroy[options->numbermonitors] = monitordestroy;
1970: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1971: return(0);
1972: }
1976: /*@
1977: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
1979: Not collective
1981: Options Database Key:
1982: . -options_monitor_cancel - Cancels all monitors that have
1983: been hardwired into a code by calls to PetscOptionsMonitorSet(),
1984: but does not cancel those set via the options database.
1986: Level: intermediate
1988: .keywords: PetscOptions, set, monitor
1990: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
1991: @*/
1992: PetscErrorCode PetscOptionsMonitorCancel(void)
1993: {
1995: PetscInt i;
1998: for (i=0; i<options->numbermonitors; i++) {
1999: if (options->monitordestroy[i]) {
2000: (*options->monitordestroy[i])(options->monitorcontext[i]);
2001: }
2002: }
2003: options->numbermonitors = 0;
2004: return(0);
2005: }