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
29: typedef struct {
30: int N,argc,Naliases;
31: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
32: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
33: PetscTruth used[MAXOPTIONS];
34: PetscTruth namegiven;
35: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
36: } PetscOptionsTable;
38: static PetscOptionsTable *options = 0;
42: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtoi(const char name[],PetscInt *a)
43: {
45: size_t i,len;
46: PetscTruth decide,tdefault,mouse;
49: PetscStrlen(name,&len);
50: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
52: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
53: if (!tdefault) {
54: PetscStrcasecmp(name,"DEFAULT",&tdefault);
55: }
56: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
57: if (!decide) {
58: PetscStrcasecmp(name,"DECIDE",&decide);
59: }
60: PetscStrcasecmp(name,"mouse",&mouse);
62: if (tdefault) {
63: *a = PETSC_DEFAULT;
64: } else if (decide) {
65: *a = PETSC_DECIDE;
66: } else if (mouse) {
67: *a = -1;
68: } else {
69: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
70: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
71: }
72: for (i=1; i<len; i++) {
73: if (name[i] < '0' || name[i] > '9') {
74: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
75: }
76: }
77: *a = atoi(name);
78: }
79: return(0);
80: }
84: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtod(const char name[],PetscReal *a)
85: {
87: size_t len;
88: PetscTruth decide,tdefault;
91: PetscStrlen(name,&len);
92: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
94: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
95: if (!tdefault) {
96: PetscStrcasecmp(name,"DEFAULT",&tdefault);
97: }
98: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
99: if (!decide) {
100: PetscStrcasecmp(name,"DECIDE",&decide);
101: }
103: if (tdefault) {
104: *a = PETSC_DEFAULT;
105: } else if (decide) {
106: *a = PETSC_DECIDE;
107: } else {
108: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
109: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
110: }
111: *a = atof(name);
112: }
113: return(0);
114: }
118: /*@C
119: PetscGetProgramName - Gets the name of the running program.
121: Not Collective
123: Input Parameter:
124: . len - length of the string name
126: Output Parameter:
127: . name - the name of the running program
129: Level: advanced
131: Notes:
132: The name of the program is copied into the user-provided character
133: array of length len. On some machines the program name includes
134: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
135: @*/
136: PetscErrorCode PETSC_DLLEXPORT PetscGetProgramName(char name[],size_t len)
137: {
141: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
142: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
143: PetscStrncpy(name,options->programname,len);
144: return(0);
145: }
149: PetscErrorCode PETSC_DLLEXPORT PetscSetProgramName(const char name[])
150: {
154: options->namegiven = PETSC_TRUE;
155: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
156: return(0);
157: }
161: /*@C
162: PetscOptionsInsertString - Inserts options into the database from a string
164: Not collective: but only processes that call this routine will set the options
165: included in the file
167: Input Parameter:
168: . in_str - string that contains options seperated by blanks
171: Level: intermediate
173: Contributed by Boyana Norris
175: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
176: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
177: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
178: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
179: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
180: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
182: @*/
183: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertString(const char in_str[])
184: {
185: char *str,*first,*second,*third,*final;
186: size_t len;
188: PetscToken *token;
191: PetscStrallocpy(in_str, &str);
192: PetscTokenCreate(str,' ',&token);
193: PetscTokenFind(token,&first);
194: PetscTokenFind(token,&second);
195: if (first && first[0] == '-') {
196: if (second) {final = second;} else {final = first;}
197: PetscStrlen(final,&len);
198: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
199: len--; final[len] = 0;
200: }
201: PetscOptionsSetValue(first,second);
202: } else if (first) {
203: PetscTruth match;
204:
205: PetscStrcasecmp(first,"alias",&match);
206: if (match) {
207: PetscTokenFind(token,&third);
208: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
209: PetscStrlen(third,&len);
210: if (third[len-1] == 'n') third[len-1] = 0;
211: PetscOptionsSetAlias(second,third);
212: }
213: }
214: PetscTokenDestroy(token);
215: PetscFree(str);
216:
217: return(0);
218: }
222: /*@C
223: PetscOptionsInsertFile - Inserts options into the database from a file.
225: Not collective: but only processes that call this routine will set the options
226: included in the file
228: Input Parameter:
229: . file - name of file
232: Level: intermediate
234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
235: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
236: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
237: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
238: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
239: PetscOptionsList(), PetscOptionsEList()
241: @*/
242: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertFile(const char file[])
243: {
244: char string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
246: size_t i,len,startIndex;
247: FILE *fd;
248: PetscToken *token;
251: PetscFixFilename(file,fname);
252: fd = fopen(fname,"r");
253: if (fd) {
254: while (fgets(string,128,fd)) {
255: /* Comments are indicated by #, ! or % in the first column */
256: if (string[0] == '#') continue;
257: if (string[0] == '!') continue;
258: if (string[0] == '%') continue;
260: PetscStrlen(string,&len);
262: /* replace tabs, ^M with " " */
263: for (i=0; i<len; i++) {
264: if (string[i] == '\t' || string[i] == '\r') {
265: string[i] = ' ';
266: }
267: }
268: for(startIndex = 0; startIndex < len-1; startIndex++) {
269: if (string[startIndex] != ' ') break;
270: }
271: PetscTokenCreate(&string[startIndex],' ',&token);
272: PetscTokenFind(token,&first);
273: PetscTokenFind(token,&second);
274: if (first && first[0] == '-') {
275: if (second) {final = second;} else {final = first;}
276: PetscStrlen(final,&len);
277: while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
278: len--; final[len] = 0;
279: }
280: PetscOptionsSetValue(first,second);
281: } else if (first) {
282: PetscTruth match;
284: PetscStrcasecmp(first,"alias",&match);
285: if (match) {
286: PetscTokenFind(token,&third);
287: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
288: PetscStrlen(third,&len);
289: if (third[len-1] == '\n') third[len-1] = 0;
290: PetscOptionsSetAlias(second,third);
291: }
292: }
293: PetscTokenDestroy(token);
294: }
295: fclose(fd);
296: } else {
297: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
298: }
299: return(0);
300: }
304: /*@C
305: PetscOptionsInsert - Inserts into the options database from the command line,
306: the environmental variable and a file.
308: Input Parameters:
309: + argc - count of number of command line arguments
310: . args - the command line arguments
311: - file - optional filename, defaults to ~username/.petscrc
313: Note:
314: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
315: the user does not typically need to call this routine. PetscOptionsInsert()
316: can be called several times, adding additional entries into the database.
318: Level: advanced
320: Concepts: options database^adding
322: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
323: @*/
324: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsert(int *argc,char ***args,const char file[])
325: {
327: PetscMPIInt rank;
328: char pfile[PETSC_MAX_PATH_LEN];
329: PetscToken *token;
332: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
334: options->argc = (argc) ? *argc : 0;
335: options->args = (args) ? *args : 0;
337: if (file) {
338: PetscOptionsInsertFile(file);
339: } else {
340: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
341: if (pfile[0]) {
342: PetscTruth flag;
343: PetscStrcat(pfile,"/.petscrc");
344: PetscTestFile(pfile,'r',&flag);
345: if (flag) {
346: PetscOptionsInsertFile(pfile);
347: }
348: } else {
349: PetscLogInfo((0,"PetscOptionsInsert:Unable to determine home directory; skipping loading ~/.petscrc\n"));
350: }
351: }
353: /* insert environmental options */
354: {
355: char *eoptions = 0,*second,*first;
356: size_t len = 0;
357: if (!rank) {
358: eoptions = (char*)getenv("PETSC_OPTIONS");
359: PetscStrlen(eoptions,&len);
360: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
361: } else {
362: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
363: if (len) {
364: PetscMalloc((len+1)*sizeof(char*),&eoptions);
365: }
366: }
367: if (len) {
368: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
369: eoptions[len] = 0;
370: PetscTokenCreate(eoptions,' ',&token);
371: PetscTokenFind(token,&first);
372: while (first) {
373: if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
374: PetscTokenFind(token,&second);
375: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
376: PetscOptionsSetValue(first,(char *)0);
377: first = second;
378: } else {
379: PetscOptionsSetValue(first,second);
380: PetscTokenFind(token,&first);
381: }
382: }
383: PetscTokenDestroy(token);
384: if (rank) {PetscFree(eoptions);}
385: }
386: }
388: /* insert command line options */
389: if (argc && args && *argc) {
390: int left = *argc - 1;
391: char **eargs = *args + 1;
392: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
394: while (left) {
395: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
396: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
397: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
398: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
399: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
400: isp4 = (PetscTruth) (isp4 || tisp4);
401: PetscStrcasecmp(eargs[0],"-np",&tisp4);
402: isp4 = (PetscTruth) (isp4 || tisp4);
403: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
405: if (eargs[0][0] != '-') {
406: eargs++; left--;
407: } else if (isoptions_file) {
408: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
409: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
410: PetscOptionsInsertFile(eargs[1]);
411: eargs += 2; left -= 2;
413: /*
414: These are "bad" options that MPICH, etc put on the command line
415: we strip them out here.
416: */
417: } else if (tisp4 || isp4rmrank) {
418: eargs += 1; left -= 1;
419: } else if (isp4 || isp4yourname) {
420: eargs += 2; left -= 2;
421: } else if ((left < 2) || ((eargs[1][0] == '-') &&
422: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
423: PetscOptionsSetValue(eargs[0],PETSC_NULL);
424: eargs++; left--;
425: } else {
426: PetscOptionsSetValue(eargs[0],eargs[1]);
427: eargs += 2; left -= 2;
428: }
429: }
430: }
431: return(0);
432: }
436: /*@C
437: PetscOptionsPrint - Prints the options that have been loaded. This is
438: useful for debugging purposes.
440: Collective on PETSC_COMM_WORLD
442: Input Parameter:
443: . FILE fd - location to print options (usually stdout or stderr)
445: Options Database Key:
446: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
448: Level: advanced
450: Concepts: options database^printing
452: .seealso: PetscOptionsAllUsed()
453: @*/
454: PetscErrorCode PETSC_DLLEXPORT PetscOptionsPrint(FILE *fd)
455: {
457: int i;
460: if (!fd) fd = stdout;
461: if (!options) {PetscOptionsInsert(0,0,0);}
462: for (i=0; i<options->N; i++) {
463: if (options->values[i]) {
464: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
465: } else {
466: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
467: }
468: }
469: return(0);
470: }
474: /*@C
475: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
477: Not Collective
479: Output Parameter:
480: . copts - pointer where string pointer is stored
482: Level: advanced
484: Concepts: options database^listing
486: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
487: @*/
488: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetAll(char *copts[])
489: {
491: int i;
492: size_t len = 1,lent;
493: char *coptions;
496: if (!options) {PetscOptionsInsert(0,0,0);}
498: /* count the length of the required string */
499: for (i=0; i<options->N; i++) {
500: PetscStrlen(options->names[i],&lent);
501: len += 2 + lent;
502: if (options->values[i]) {
503: PetscStrlen(options->values[i],&lent);
504: len += 1 + lent;
505: }
506: }
507: PetscMalloc(len*sizeof(char),&coptions);
508: coptions[0] = 0;
509: for (i=0; i<options->N; i++) {
510: PetscStrcat(coptions,"-");
511: PetscStrcat(coptions,options->names[i]);
512: PetscStrcat(coptions," ");
513: if (options->values[i]) {
514: PetscStrcat(coptions,options->values[i]);
515: PetscStrcat(coptions," ");
516: }
517: }
518: *copts = coptions;
519: return(0);
520: }
524: /*@C
525: PetscOptionsDestroy - Destroys the option database.
527: Note:
528: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
529: typically does not need to call this routine.
531: Level: developer
533: .seealso: PetscOptionsInsert()
534: @*/
535: PetscErrorCode PETSC_DLLEXPORT PetscOptionsDestroy(void)
536: {
537: int i;
540: if (!options) return(0);
541: for (i=0; i<options->N; i++) {
542: if (options->names[i]) free(options->names[i]);
543: if (options->values[i]) free(options->values[i]);
544: }
545: for (i=0; i<options->Naliases; i++) {
546: free(options->aliases1[i]);
547: free(options->aliases2[i]);
548: }
549: free(options);
550: options = 0;
551: return(0);
552: }
556: /*@C
557: PetscOptionsSetValue - Sets an option name-value pair in the options
558: database, overriding whatever is already present.
560: Not collective, but setting values on certain processors could cause problems
561: for parallel objects looking for options.
563: Input Parameters:
564: + name - name of option, this SHOULD have the - prepended
565: - value - the option value (not used for all options)
567: Level: intermediate
569: Note:
570: Only some options have values associated with them, such as
571: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
573: Concepts: options database^adding option
575: .seealso: PetscOptionsInsert()
576: @*/
577: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetValue(const char iname[],const char value[])
578: {
579: size_t len;
581: int N,n,i;
582: char **names;
583: const char *name = (char*)iname;
584: PetscTruth gt,match;
587: if (!options) {PetscOptionsInsert(0,0,0);}
589: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
590: PetscStrcasecmp(name,"-h",&match);
591: if (match) name = "-help";
593: name++;
594: /* first check against aliases */
595: N = options->Naliases;
596: for (i=0; i<N; i++) {
597: PetscStrcasecmp(options->aliases1[i],name,&match);
598: if (match) {
599: name = options->aliases2[i];
600: break;
601: }
602: }
604: N = options->N;
605: n = N;
606: names = options->names;
607:
608: for (i=0; i<N; i++) {
609: PetscStrcasecmp(names[i],name,&match);
610: PetscStrgrt(names[i],name,>);
611: if (match) {
612: if (options->values[i]) free(options->values[i]);
613: PetscStrlen(value,&len);
614: if (len) {
615: options->values[i] = (char*)malloc((len+1)*sizeof(char));
616: PetscStrcpy(options->values[i],value);
617: } else { options->values[i] = 0;}
618: return(0);
619: } else if (gt) {
620: n = i;
621: break;
622: }
623: }
624: if (N >= MAXOPTIONS) {
625: SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
626: }
627: /* shift remaining values down 1 */
628: for (i=N; i>n; i--) {
629: names[i] = names[i-1];
630: options->values[i] = options->values[i-1];
631: options->used[i] = options->used[i-1];
632: }
633: /* insert new name and value */
634: PetscStrlen(name,&len);
635: names[n] = (char*)malloc((len+1)*sizeof(char));
636: PetscStrcpy(names[n],name);
637: if (value) {
638: PetscStrlen(value,&len);
639: options->values[n] = (char*)malloc((len+1)*sizeof(char));
640: PetscStrcpy(options->values[n],value);
641: } else {options->values[n] = 0;}
642: options->used[n] = PETSC_FALSE;
643: options->N++;
644: return(0);
645: }
649: /*@C
650: PetscOptionsClearValue - Clears an option name-value pair in the options
651: database, overriding whatever is already present.
653: Not Collective, but setting values on certain processors could cause problems
654: for parallel objects looking for options.
656: Input Parameter:
657: . name - name of option, this SHOULD have the - prepended
659: Level: intermediate
661: Concepts: options database^removing option
662: .seealso: PetscOptionsInsert()
663: @*/
664: PetscErrorCode PETSC_DLLEXPORT PetscOptionsClearValue(const char iname[])
665: {
667: int N,n,i;
668: char **names,*name=(char*)iname;
669: PetscTruth gt,match;
672: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
673: if (!options) {PetscOptionsInsert(0,0,0);}
675: name++;
677: N = options->N; n = 0;
678: names = options->names;
679:
680: for (i=0; i<N; i++) {
681: PetscStrcasecmp(names[i],name,&match);
682: PetscStrgrt(names[i],name,>);
683: if (match) {
684: if (options->values[i]) free(options->values[i]);
685: break;
686: } else if (gt) {
687: return(0); /* it was not listed */
688: }
689: n++;
690: }
691: if (n == N) return(0); /* it was not listed */
693: /* shift remaining values down 1 */
694: for (i=n; i<N-1; i++) {
695: names[i] = names[i+1];
696: options->values[i] = options->values[i+1];
697: options->used[i] = options->used[i+1];
698: }
699: options->N--;
700: return(0);
701: }
705: /*@C
706: PetscOptionsReject - Generates an error if a certain option is given.
708: Not Collective, but setting values on certain processors could cause problems
709: for parallel objects looking for options.
711: Input Parameters:
712: + name - the option one is seeking
713: - mess - error message (may be PETSC_NULL)
715: Level: advanced
717: Concepts: options database^rejecting option
719: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
720: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
721: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
722: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
723: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
724: PetscOptionsList(), PetscOptionsEList()
725: @*/
726: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetAlias(const char inewname[],const char ioldname[])
727: {
729: int n = options->Naliases;
730: size_t len;
731: char *newname = (char *)inewname,*oldname = (char*)ioldname;
734: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
735: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
736: if (n >= MAXALIASES) {
737: SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXALIASES",MAXALIASES);
738: }
740: newname++; oldname++;
741: PetscStrlen(newname,&len);
742: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
743: PetscStrcpy(options->aliases1[n],newname);
744: PetscStrlen(oldname,&len);
745: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
746: PetscStrcpy(options->aliases2[n],oldname);
747: options->Naliases++;
748: return(0);
749: }
753: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
754: {
756: PetscInt i,N;
757: size_t len;
758: char **names,tmp[256];
759: PetscTruth match;
762: if (!options) {PetscOptionsInsert(0,0,0);}
763: N = options->N;
764: names = options->names;
766: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
768: /* append prefix to name */
769: if (pre) {
770: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
771: PetscStrncpy(tmp,pre,256);
772: PetscStrlen(tmp,&len);
773: PetscStrncat(tmp,name+1,256-len-1);
774: } else {
775: PetscStrncpy(tmp,name+1,256);
776: }
778: /* slow search */
779: *flg = PETSC_FALSE;
780: for (i=0; i<N; i++) {
781: PetscStrcasecmp(names[i],tmp,&match);
782: if (match) {
783: *value = options->values[i];
784: options->used[i] = PETSC_TRUE;
785: *flg = PETSC_TRUE;
786: break;
787: }
788: }
789: if (!*flg) {
790: PetscInt j,cnt = 0,locs[16],loce[16];
791: size_t n;
792: PetscStrlen(tmp,&n);
793: /* determine the location and number of all _%d_ in the key */
794: for (i=0; i< (PetscInt)n; i++) {
795: if (tmp[i] == '_') {
796: for (j=i+1; j< (PetscInt)n; j++) {
797: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
798: if (tmp[j] == '_' && j > i+1) { /* found a number */
799: locs[cnt] = i+1;
800: loce[cnt++] = j+1;
801: }
802: break;
803: }
804: }
805: }
806: if (cnt) {
807: char tmp2[256];
808: for (i=0; i<cnt; i++) {
809: PetscStrcpy(tmp2,"-");
810: PetscStrncat(tmp2,tmp,locs[i]);
811: PetscStrcat(tmp2,tmp+loce[i]);
812: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
813: if (*flg) break;
814: }
815: }
816: }
817: return(0);
818: }
822: /*@C
823: PetscOptionsReject - Generates an error if a certain option is given.
825: Not Collective, but setting values on certain processors could cause problems
826: for parallel objects looking for options.
828: Input Parameters:
829: + name - the option one is seeking
830: - mess - error message (may be PETSC_NULL)
832: Level: advanced
834: Concepts: options database^rejecting option
836: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
837: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
838: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
839: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
840: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
841: PetscOptionsList(), PetscOptionsEList()
842: @*/
843: PetscErrorCode PETSC_DLLEXPORT PetscOptionsReject(const char name[],const char mess[])
844: {
846: PetscTruth flag;
849: PetscOptionsHasName(PETSC_NULL,name,&flag);
850: if (flag) {
851: if (mess) {
852: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
853: } else {
854: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
855: }
856: }
857: return(0);
858: }
862: /*@C
863: PetscOptionsHasName - Determines whether a certain option is given in the database.
865: Not Collective
867: Input Parameters:
868: + name - the option one is seeking
869: - pre - string to prepend to the name or PETSC_NULL
871: Output Parameters:
872: . flg - PETSC_TRUE if found else PETSC_FALSE.
874: Level: beginner
876: Concepts: options database^has option name
878: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
879: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
880: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
881: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
882: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
883: PetscOptionsList(), PetscOptionsEList()
884: @*/
885: PetscErrorCode PETSC_DLLEXPORT PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
886: {
887: char *value;
889: PetscTruth isfalse,flag;
892: PetscOptionsFindPair_Private(pre,name,&value,&flag);
894: /* remove if turned off */
895: if (flag) {
896: PetscStrcasecmp(value,"FALSE",&isfalse);
897: if (isfalse) flag = PETSC_FALSE;
898: PetscStrcasecmp(value,"NO",&isfalse);
899: if (isfalse) flag = PETSC_FALSE;
900: PetscStrcasecmp(value,"0",&isfalse);
901: if (isfalse) flag = PETSC_FALSE;
902: }
903: if (flg) *flg = flag;
904: return(0);
905: }
909: /*@C
910: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
912: Not Collective
914: Input Parameters:
915: + pre - the string to prepend to the name or PETSC_NULL
916: - name - the option one is seeking
918: Output Parameter:
919: + ivalue - the integer value to return
920: - flg - PETSC_TRUE if found, else PETSC_FALSE
922: Level: beginner
924: Concepts: options database^has int
926: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
927: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
928: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
929: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
930: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
931: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
932: PetscOptionsList(), PetscOptionsEList()
933: @*/
934: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
935: {
936: char *value;
938: PetscTruth flag;
943: PetscOptionsFindPair_Private(pre,name,&value,&flag);
944: if (flag) {
945: if (!value) {if (flg) *flg = PETSC_FALSE;}
946: else {
947: if (flg) *flg = PETSC_TRUE;
948: PetscOptionsAtoi(value,ivalue);
949: }
950: } else {
951: if (flg) *flg = PETSC_FALSE;
952: }
953: return(0);
954: }
958: /*@C
959: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
961: Not Collective
963: Input Parameters:
964: + pre - the string to prepend to the name or PETSC_NULL
965: . opt - option name
966: . list - the possible choices
967: . ntext - number of choices
969: Output Parameter:
970: + value - the index of the value to return
971: - set - PETSC_TRUE if found, else PETSC_FALSE
972:
973: Level: intermediate
975: See PetscOptionsList() for when the choices are given in a PetscFList()
977: Concepts: options database^list
979: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
980: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
981: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
982: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
983: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
984: PetscOptionsList(), PetscOptionsEList()
985: @*/
986: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
987: {
989: size_t alen,len = 0;
990: char *svalue;
991: PetscTruth aset,flg = PETSC_FALSE;
992: PetscInt i;
995: for ( i=0; i<ntext; i++) {
996: PetscStrlen(list[i],&alen);
997: if (alen > len) len = alen;
998: }
999: len += 5; /* a little extra space for user mistypes */
1000: PetscMalloc(len*sizeof(char),&svalue);
1001: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1002: if (aset) {
1003: if (set) *set = PETSC_TRUE;
1004: for (i=0; i<ntext; i++) {
1005: PetscStrcasecmp(svalue,list[i],&flg);
1006: if (flg) {
1007: *value = i;
1008: break;
1009: }
1010: }
1011: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1012: } else if (set) {
1013: *set = PETSC_FALSE;
1014: }
1015: PetscFree(svalue);
1016: return(0);
1017: }
1021: /*@C
1022: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1024: Not Collective
1026: Input Parameters:
1027: + pre - option prefix or PETSC_NULL
1028: . opt - option name
1029: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1030: - defaultv - the default (current) value
1032: Output Parameter:
1033: + value - the value to return
1034: - flg - PETSC_TRUE if found, else PETSC_FALSE
1036: Level: beginner
1038: Concepts: options database
1040: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1042: list is usually something like PCASMTypes or some other predefined list of enum names
1044: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1045: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1046: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1047: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1048: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1049: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1050: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1051: @*/
1052: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1053: {
1055: PetscInt ntext = 0;
1058: while (list[ntext++]) {
1059: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1060: }
1061: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1062: ntext -= 3;
1063: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1064: return(0);
1065: }
1069: /*@C
1070: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1071: option in the database.
1073: Not Collective
1075: Input Parameters:
1076: + pre - the string to prepend to the name or PETSC_NULL
1077: - name - the option one is seeking
1079: Output Parameter:
1080: + ivalue - the logical value to return
1081: - flg - PETSC_TRUE if found, else PETSC_FALSE
1083: Level: beginner
1085: Notes:
1086: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1087: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1089: Concepts: options database^has logical
1091: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1092: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1093: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1094: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1095: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1096: PetscOptionsList(), PetscOptionsEList()
1097: @*/
1098: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1099: {
1100: char *value;
1101: PetscTruth flag,istrue,isfalse;
1107: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1108: if (flag) {
1109: if (flg) *flg = PETSC_TRUE;
1110: if (!value) {
1111: *ivalue = PETSC_TRUE;
1112: } else {
1113: *ivalue = PETSC_TRUE;
1114: PetscStrcasecmp(value,"TRUE",&istrue);
1115: if (istrue) return(0);
1116: PetscStrcasecmp(value,"YES",&istrue);
1117: if (istrue) return(0);
1118: PetscStrcasecmp(value,"1",&istrue);
1119: if (istrue) return(0);
1120: PetscStrcasecmp(value,"on",&istrue);
1121: if (istrue) return(0);
1123: *ivalue = PETSC_FALSE;
1124: PetscStrcasecmp(value,"FALSE",&isfalse);
1125: if (isfalse) return(0);
1126: PetscStrcasecmp(value,"NO",&isfalse);
1127: if (isfalse) return(0);
1128: PetscStrcasecmp(value,"0",&isfalse);
1129: if (isfalse) return(0);
1130: PetscStrcasecmp(value,"off",&isfalse);
1131: if (isfalse) return(0);
1133: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1134: }
1135: } else {
1136: if (flg) *flg = PETSC_FALSE;
1137: }
1138: return(0);
1139: }
1143: /*@C
1144: PetscOptionsGetReal - Gets the double precision value for a particular
1145: option in the database.
1147: Not Collective
1149: Input Parameters:
1150: + pre - string to prepend to each name or PETSC_NULL
1151: - name - the option one is seeking
1153: Output Parameter:
1154: + dvalue - the double value to return
1155: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1157: Level: beginner
1159: Concepts: options database^has double
1161: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1162: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1163: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1164: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1165: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1166: PetscOptionsList(), PetscOptionsEList()
1167: @*/
1168: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1169: {
1170: char *value;
1172: PetscTruth flag;
1177: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1178: if (flag) {
1179: if (!value) {if (flg) *flg = PETSC_FALSE;}
1180: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1181: } else {
1182: if (flg) *flg = PETSC_FALSE;
1183: }
1184: return(0);
1185: }
1189: /*@C
1190: PetscOptionsGetScalar - Gets the scalar value for a particular
1191: option in the database.
1193: Not Collective
1195: Input Parameters:
1196: + pre - string to prepend to each name or PETSC_NULL
1197: - name - the option one is seeking
1199: Output Parameter:
1200: + dvalue - the double value to return
1201: - flg - PETSC_TRUE if found, else PETSC_FALSE
1203: Level: beginner
1205: Usage:
1206: A complex number 2+3i can be specified as 2,3 at the command line.
1207: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1209: Concepts: options database^has scalar
1211: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1212: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1213: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1214: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1215: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1216: PetscOptionsList(), PetscOptionsEList()
1217: @*/
1218: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1219: {
1220: char *value;
1221: PetscTruth flag;
1227: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1228: if (flag) {
1229: if (!value) {
1230: if (flg) *flg = PETSC_FALSE;
1231: } else {
1232: #if !defined(PETSC_USE_COMPLEX)
1233: PetscOptionsAtod(value,dvalue);
1234: #else
1235: PetscReal re=0.0,im=0.0;
1236: PetscToken *token;
1237: char *tvalue = 0;
1239: PetscTokenCreate(value,',',&token);
1240: PetscTokenFind(token,&tvalue);
1241: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1242: PetscOptionsAtod(tvalue,&re);
1243: PetscTokenFind(token,&tvalue);
1244: if (!tvalue) { /* Unknown separator used. using only real value */
1245: *dvalue = re;
1246: } else {
1247: PetscOptionsAtod(tvalue,&im);
1248: *dvalue = re + PETSC_i*im;
1249: }
1250: PetscTokenDestroy(token);
1251: #endif
1252: if (flg) *flg = PETSC_TRUE;
1253: }
1254: } else { /* flag */
1255: if (flg) *flg = PETSC_FALSE;
1256: }
1257: return(0);
1258: }
1262: /*@C
1263: PetscOptionsGetRealArray - Gets an array of double precision values for a
1264: particular option in the database. The values must be separated with
1265: commas with no intervening spaces.
1267: Not Collective
1269: Input Parameters:
1270: + pre - string to prepend to each name or PETSC_NULL
1271: . name - the option one is seeking
1272: - nmax - maximum number of values to retrieve
1274: Output Parameters:
1275: + dvalue - the double value to return
1276: . nmax - actual number of values retreived
1277: - flg - PETSC_TRUE if found, else PETSC_FALSE
1279: Level: beginner
1281: Concepts: options database^array of doubles
1283: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1284: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1285: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1286: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1287: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1288: PetscOptionsList(), PetscOptionsEList()
1289: @*/
1290: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1291: {
1292: char *value;
1294: PetscInt n = 0;
1295: PetscTruth flag;
1296: PetscToken *token;
1301: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1302: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1303: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1305: if (flg) *flg = PETSC_TRUE;
1307: PetscTokenCreate(value,',',&token);
1308: PetscTokenFind(token,&value);
1309: while (n < *nmax) {
1310: if (!value) break;
1311: PetscOptionsAtod(value,dvalue++);
1312: PetscTokenFind(token,&value);
1313: n++;
1314: }
1315: PetscTokenDestroy(token);
1316: *nmax = n;
1317: return(0);
1318: }
1322: /*@C
1323: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1324: option in the database. The values must be separated with commas with
1325: no intervening spaces.
1327: Not Collective
1329: Input Parameters:
1330: + pre - string to prepend to each name or PETSC_NULL
1331: . name - the option one is seeking
1332: - nmax - maximum number of values to retrieve
1334: Output Parameter:
1335: + dvalue - the integer values to return
1336: . nmax - actual number of values retreived
1337: - flg - PETSC_TRUE if found, else PETSC_FALSE
1339: Level: beginner
1341: Concepts: options database^array of ints
1343: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1344: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1345: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1346: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1347: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1348: PetscOptionsList(), PetscOptionsEList()
1349: @*/
1350: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1351: {
1352: char *value;
1354: PetscInt n = 0;
1355: PetscTruth flag;
1356: PetscToken *token;
1361: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1362: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1363: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1365: if (flg) *flg = PETSC_TRUE;
1367: PetscTokenCreate(value,',',&token);
1368: PetscTokenFind(token,&value);
1369: while (n < *nmax) {
1370: if (!value) break;
1371: PetscOptionsAtoi(value,dvalue);
1372: dvalue++;
1373: PetscTokenFind(token,&value);
1374: n++;
1375: }
1376: PetscTokenDestroy(token);
1377: *nmax = n;
1378: return(0);
1379: }
1383: /*@C
1384: PetscOptionsGetString - Gets the string value for a particular option in
1385: the database.
1387: Not Collective
1389: Input Parameters:
1390: + pre - string to prepend to name or PETSC_NULL
1391: . name - the option one is seeking
1392: - len - maximum string length
1394: Output Parameters:
1395: + string - location to copy string
1396: - flg - PETSC_TRUE if found, else PETSC_FALSE
1398: Level: beginner
1400: Fortran Note:
1401: The Fortran interface is slightly different from the C/C++
1402: interface (len is not used). Sample usage in Fortran follows
1403: .vb
1404: character *20 string
1405: integer flg, ierr
1406: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1407: .ve
1409: Concepts: options database^string
1411: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1412: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1413: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1414: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1415: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1416: PetscOptionsList(), PetscOptionsEList()
1417: @*/
1418: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1419: {
1420: char *value;
1422: PetscTruth flag;
1427: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1428: if (!flag) {
1429: if (flg) *flg = PETSC_FALSE;
1430: } else {
1431: if (flg) *flg = PETSC_TRUE;
1432: if (value) {
1433: PetscStrncpy(string,value,len);
1434: } else {
1435: PetscMemzero(string,len);
1436: }
1437: }
1438: return(0);
1439: }
1443: /*@C
1444: PetscOptionsGetStringArray - Gets an array of string values for a particular
1445: option in the database. The values must be separated with commas with
1446: no intervening spaces.
1448: Not Collective
1450: Input Parameters:
1451: + pre - string to prepend to name or PETSC_NULL
1452: . name - the option one is seeking
1453: - nmax - maximum number of strings
1455: Output Parameter:
1456: + strings - location to copy strings
1457: - flg - PETSC_TRUE if found, else PETSC_FALSE
1459: Level: beginner
1461: Notes:
1462: The user should pass in an array of pointers to char, to hold all the
1463: strings returned by this function.
1465: The user is responsible for deallocating the strings that are
1466: returned. The Fortran interface for this routine is not supported.
1468: Contributed by Matthew Knepley.
1470: Concepts: options database^array of strings
1472: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1473: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1474: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1475: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1476: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1477: PetscOptionsList(), PetscOptionsEList()
1478: @*/
1479: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1480: {
1481: char *value;
1483: PetscInt n;
1484: PetscTruth flag;
1485: PetscToken *token;
1486:
1490: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1491: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1492: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1493: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1494: if (flg) *flg = PETSC_TRUE;
1496: PetscTokenCreate(value,',',&token);
1497: PetscTokenFind(token,&value);
1498: n = 0;
1499: while (n < *nmax) {
1500: if (!value) break;
1501: PetscStrallocpy(value,&strings[n]);
1502: PetscTokenFind(token,&value);
1503: n++;
1504: }
1505: PetscTokenDestroy(token);
1506: *nmax = n;
1507: return(0);
1508: }
1512: /*@C
1513: PetscOptionsAllUsed - Returns a count of the number of options in the
1514: database that have never been selected.
1516: Not Collective
1518: Output Parameter:
1519: . N - count of options not used
1521: Level: advanced
1523: .seealso: PetscOptionsPrint()
1524: @*/
1525: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAllUsed(int *N)
1526: {
1527: PetscInt i,n = 0;
1530: for (i=0; i<options->N; i++) {
1531: if (!options->used[i]) { n++; }
1532: }
1533: *N = n;
1534: return(0);
1535: }
1539: /*@
1540: PetscOptionsLeft - Prints to screen any options that were set and never used.
1542: Not collective
1544: Options Database Key:
1545: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1547: Level: advanced
1549: .seealso: PetscOptionsAllUsed()
1550: @*/
1551: PetscErrorCode PETSC_DLLEXPORT PetscOptionsLeft(void)
1552: {
1554: PetscInt i;
1557: for (i=0; i<options->N; i++) {
1558: if (!options->used[i]) {
1559: if (options->values[i]) {
1560: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1561: } else {
1562: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1563: }
1564: }
1565: }
1566: return(0);
1567: }
1569: /*
1570: PetscOptionsCreate - Creates the empty options database.
1572: */
1575: PetscErrorCode PETSC_DLLEXPORT PetscOptionsCreate(void)
1576: {
1580: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1581: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1582: options->namegiven = PETSC_FALSE;
1583: options->N = 0;
1584: options->Naliases = 0;
1585: return(0);
1586: }