Actual source code: aoptions.c
petsc-dev 2014-02-02
2: /*
3: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
4: GUI code to display the options and get values from the users.
6: */
8: #include <petsc-private/petscimpl.h> /*I "petscsys.h" I*/
9: #include <petscviewer.h>
11: #define ManSection(str) ((str) ? (str) : "None")
13: /*
14: Keep a linked list of options that have been posted and we are waiting for
15: user selection. See the manual page for PetscOptionsBegin()
17: Eventually we'll attach this beast to a MPI_Comm
18: */
19: PetscOptionsObjectType PetscOptionsObject;
20: PetscInt PetscOptionsPublishCount = 0;
24: /*
25: Handles setting up the data structure in a call to PetscOptionsBegin()
26: */
27: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
28: {
32: PetscOptionsObject.next = 0;
33: PetscOptionsObject.comm = comm;
34: PetscOptionsObject.changedmethod = PETSC_FALSE;
36: PetscFree(PetscOptionsObject.prefix);
37: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
38: PetscFree(PetscOptionsObject.title);
39: PetscStrallocpy(title,&PetscOptionsObject.title);
41: PetscOptionsHasName(NULL,"-help",&PetscOptionsObject.printhelp);
42: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
43: if (!PetscOptionsObject.alreadyprinted) {
44: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
45: }
46: }
47: return(0);
48: }
52: /*
53: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
54: */
55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
56: {
58: char title[256];
59: PetscBool flg;
63: PetscOptionsObject.object = obj;
64: PetscOptionsObject.alreadyprinted = obj->optionsprinted;
66: PetscStrcmp(obj->description,obj->class_name,&flg);
67: if (flg) {
68: PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
69: } else {
70: PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
71: }
72: PetscOptionsBegin_Private(obj->comm,obj->prefix,title,obj->mansec);
73: return(0);
74: }
76: /*
77: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
78: */
81: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
82: {
83: int ierr;
84: PetscOptions next;
85: PetscBool valid;
88: PetscOptionsValidKey(opt,&valid);
89: if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);
91: PetscNew(amsopt);
92: (*amsopt)->next = 0;
93: (*amsopt)->set = PETSC_FALSE;
94: (*amsopt)->type = t;
95: (*amsopt)->data = 0;
97: PetscStrallocpy(text,&(*amsopt)->text);
98: PetscStrallocpy(opt,&(*amsopt)->option);
99: PetscStrallocpy(man,&(*amsopt)->man);
101: if (!PetscOptionsObject.next) PetscOptionsObject.next = *amsopt;
102: else {
103: next = PetscOptionsObject.next;
104: while (next->next) next = next->next;
105: next->next = *amsopt;
106: }
107: return(0);
108: }
112: /*
113: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
115: Collective on MPI_Comm
117: Input Parameters:
118: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
119: . n - length of the string, must be the same on all processes
120: - str - location to store input
122: Bugs:
123: . Assumes process 0 of the given communicator has access to stdin
125: */
126: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
127: {
128: size_t i;
129: char c;
130: PetscMPIInt rank,nm;
134: MPI_Comm_rank(comm,&rank);
135: if (!rank) {
136: c = (char) getchar();
137: i = 0;
138: while (c != '\n' && i < n-1) {
139: str[i++] = c;
140: c = (char)getchar();
141: }
142: str[i] = 0;
143: }
144: PetscMPIIntCast(n,&nm);
145: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
146: return(0);
147: }
149: /*
150: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
151: */
152: static PetscErrorCode PetscStrdup(const char s[],char *t[])
153: {
155: size_t len;
156: char *tmp = 0;
159: if (s) {
160: PetscStrlen(s,&len);
161: tmp = (char*) malloc((len+1)*sizeof(char*));
162: if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
163: PetscStrcpy(tmp,s);
164: }
165: *t = tmp;
166: return(0);
167: }
172: /*
173: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
175: Notes: this isn't really practical, it is just to demonstrate the principle
177: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
178: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
180: Bugs:
181: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
182: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
183: - Only works for PetscInt == int, PetscReal == double etc
185: Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different
186: address space and communicating with the PETSc program
188: */
189: PetscErrorCode PetscOptionsGetFromTextInput()
190: {
192: PetscOptions next = PetscOptionsObject.next;
193: char str[512];
194: PetscBool bid;
195: PetscReal ir,*valr;
196: PetscInt *vald;
197: size_t i;
199: (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
200: while (next) {
201: switch (next->type) {
202: case OPTION_HEAD:
203: break;
204: case OPTION_INT_ARRAY:
205: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
206: vald = (PetscInt*) next->data;
207: for (i=0; i<next->arraylength; i++) {
208: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
209: if (i < next->arraylength-1) {
210: PetscPrintf(PETSC_COMM_WORLD,",");
211: }
212: }
213: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
214: PetscScanString(PETSC_COMM_WORLD,512,str);
215: if (str[0]) {
216: PetscToken token;
217: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
218: size_t len;
219: char *value;
220: PetscBool foundrange;
222: next->set = PETSC_TRUE;
223: value = str;
224: PetscTokenCreate(value,',',&token);
225: PetscTokenFind(token,&value);
226: while (n < nmax) {
227: if (!value) break;
229: /* look for form d-D where d and D are integers */
230: foundrange = PETSC_FALSE;
231: PetscStrlen(value,&len);
232: if (value[0] == '-') i=2;
233: else i=1;
234: for (;i<len; i++) {
235: if (value[i] == '-') {
236: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
237: value[i] = 0;
238: PetscOptionsStringToInt(value,&start);
239: PetscOptionsStringToInt(value+i+1,&end);
240: if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
241: if (n + end - start - 1 >= nmax) SETERRQ4(PETSC_COMM_SELF,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);
242: for (; start<end; start++) {
243: *dvalue = start; dvalue++;n++;
244: }
245: foundrange = PETSC_TRUE;
246: break;
247: }
248: }
249: if (!foundrange) {
250: PetscOptionsStringToInt(value,dvalue);
251: dvalue++;
252: n++;
253: }
254: PetscTokenFind(token,&value);
255: }
256: PetscTokenDestroy(&token);
257: }
258: break;
259: case OPTION_REAL_ARRAY:
260: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
261: valr = (PetscReal*) next->data;
262: for (i=0; i<next->arraylength; i++) {
263: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
264: if (i < next->arraylength-1) {
265: PetscPrintf(PETSC_COMM_WORLD,",");
266: }
267: }
268: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
269: PetscScanString(PETSC_COMM_WORLD,512,str);
270: if (str[0]) {
271: PetscToken token;
272: PetscInt n = 0,nmax = next->arraylength;
273: PetscReal *dvalue = (PetscReal*)next->data;
274: char *value;
276: next->set = PETSC_TRUE;
277: value = str;
278: PetscTokenCreate(value,',',&token);
279: PetscTokenFind(token,&value);
280: while (n < nmax) {
281: if (!value) break;
282: PetscOptionsStringToReal(value,dvalue);
283: dvalue++;
284: n++;
285: PetscTokenFind(token,&value);
286: }
287: PetscTokenDestroy(&token);
288: }
289: break;
290: case OPTION_INT:
291: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
292: PetscScanString(PETSC_COMM_WORLD,512,str);
293: if (str[0]) {
294: #if defined(PETSC_SIZEOF_LONG_LONG)
295: long long lid;
296: sscanf(str,"%lld",&lid);
297: if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %lld",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,lid);
298: #else
299: long lid;
300: sscanf(str,"%ld",&lid);
301: if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %ld",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,lid);
302: #endif
304: next->set = PETSC_TRUE;
305: *((PetscInt*)next->data) = (PetscInt)lid;
306: }
307: break;
308: case OPTION_REAL:
309: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
310: PetscScanString(PETSC_COMM_WORLD,512,str);
311: if (str[0]) {
312: #if defined(PETSC_USE_REAL_SINGLE)
313: sscanf(str,"%e",&ir);
314: #elif defined(PETSC_USE_REAL_DOUBLE)
315: sscanf(str,"%le",&ir);
316: #elif defined(PETSC_USE_REAL___FLOAT128)
317: ir = strtoflt128(str,0);
318: #else
319: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
320: #endif
321: next->set = PETSC_TRUE;
322: *((PetscReal*)next->data) = ir;
323: }
324: break;
325: case OPTION_BOOL:
326: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(PetscBool*)next->data ? "true": "false",next->text,next->man);
327: PetscScanString(PETSC_COMM_WORLD,512,str);
328: if (str[0]) {
329: PetscOptionsStringToBool(str,&bid);
330: next->set = PETSC_TRUE;
331: *((PetscBool*)next->data) = bid;
332: }
333: break;
334: case OPTION_STRING:
335: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,(char*)next->data,next->text,next->man);
336: PetscScanString(PETSC_COMM_WORLD,512,str);
337: if (str[0]) {
338: next->set = PETSC_TRUE;
339: /* must use system malloc since SAWs may free this */
340: PetscStrdup(str,(char**)&next->data);
341: }
342: break;
343: case OPTION_FLIST:
344: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
345: PetscScanString(PETSC_COMM_WORLD,512,str);
346: if (str[0]) {
347: PetscOptionsObject.changedmethod = PETSC_TRUE;
348: next->set = PETSC_TRUE;
349: /* must use system malloc since SAWs may free this */
350: PetscStrdup(str,(char**)&next->data);
351: }
352: break;
353: default:
354: break;
355: }
356: next = next->next;
357: }
358: return(0);
359: }
361: #if defined(PETSC_HAVE_SAWS)
362: #include <petscviewersaws.h>
364: static int count = 0;
368: PetscErrorCode PetscOptionsSAWsDestroy(void)
369: {
371: return(0);
372: }
376: /*
377: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
379: Bugs:
380: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
381: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
382: - Only works for PetscInt == int, PetscReal == double etc
385: */
386: PetscErrorCode PetscOptionsSAWsInput()
387: {
389: PetscOptions next = PetscOptionsObject.next;
390: static int mancount = 0;
391: char options[16];
392: PetscBool changedmethod = PETSC_FALSE;
393: char manname[16],textname[16];
394: char dir[1024];
396: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
397: sprintf(options,"Options_%d",count++);
399: PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* SAWs will change this, so cannot pass prefix directly */
401: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
402: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.title,1,SAWs_READ,SAWs_STRING));
403: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
404: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.pprefix,1,SAWs_READ,SAWs_STRING));
405: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
407: while (next) {
408: sprintf(manname,"_man_%d",mancount);
409: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
410: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
411: sprintf(textname,"_text_%d",mancount++);
412: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
413: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
415: switch (next->type) {
416: case OPTION_HEAD:
417: break;
418: case OPTION_INT_ARRAY:
419: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
420: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
421: break;
422: case OPTION_REAL_ARRAY:
423: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
424: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
425: break;
426: case OPTION_INT:
427: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
428: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
429: break;
430: case OPTION_REAL:
431: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
432: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
433: break;
434: case OPTION_BOOL:
435: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
436: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
437: break;
438: case OPTION_BOOL_ARRAY:
439: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
440: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
441: break;
442: case OPTION_STRING:
443: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
444: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
445: break;
446: case OPTION_STRING_ARRAY:
447: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
448: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
449: break;
450: case OPTION_FLIST:
451: {
452: PetscInt ntext;
453: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
454: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
455: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
456: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
457: }
458: break;
459: case OPTION_ELIST:
460: {
461: PetscInt ntext = next->nlist;
462: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
463: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
464: PetscMalloc1((ntext+1),&next->edata);
465: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
466: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
467: }
468: break;
469: default:
470: break;
471: }
472: next = next->next;
473: }
475: /* wait until accessor has unlocked the memory */
476: PetscSAWsBlock();
478: /* determine if any values have been set in GUI */
479: next = PetscOptionsObject.next;
480: while (next) {
481: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
482: PetscStackCallSAWs(SAWs_Selected,(dir,&next->set));
483: next = next->next;
484: }
486: /* reset counter to -2; this updates the screen with the new options for the selected method */
487: if (changedmethod) PetscOptionsPublishCount = -2;
489: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
490: return(0);
491: }
492: #endif
496: PetscErrorCode PetscOptionsEnd_Private(void)
497: {
499: PetscOptions last;
500: char option[256],value[1024],tmp[32];
501: size_t j;
504: if (PetscOptionsObject.next) {
505: if (!PetscOptionsPublishCount) {
506: #if defined(PETSC_HAVE_SAWS)
507: PetscOptionsSAWsInput();
508: #else
509: PetscOptionsGetFromTextInput();
510: #endif
511: }
512: }
514: PetscFree(PetscOptionsObject.title);
515: PetscFree(PetscOptionsObject.prefix);
517: /* reset counter to -2; this updates the screen with the new options for the selected method */
518: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
519: /* reset alreadyprinted flag */
520: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
521: if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
522: PetscOptionsObject.object = NULL;
524: while (PetscOptionsObject.next) {
525: if (PetscOptionsObject.next->set) {
526: if (PetscOptionsObject.prefix) {
527: PetscStrcpy(option,"-");
528: PetscStrcat(option,PetscOptionsObject.prefix);
529: PetscStrcat(option,PetscOptionsObject.next->option+1);
530: } else {
531: PetscStrcpy(option,PetscOptionsObject.next->option);
532: }
534: switch (PetscOptionsObject.next->type) {
535: case OPTION_HEAD:
536: break;
537: case OPTION_INT_ARRAY:
538: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
539: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
540: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
541: PetscStrcat(value,",");
542: PetscStrcat(value,tmp);
543: }
544: break;
545: case OPTION_INT:
546: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
547: break;
548: case OPTION_REAL:
549: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
550: break;
551: case OPTION_REAL_ARRAY:
552: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
553: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
554: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
555: PetscStrcat(value,",");
556: PetscStrcat(value,tmp);
557: }
558: break;
559: case OPTION_BOOL:
560: sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
561: break;
562: case OPTION_BOOL_ARRAY:
563: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
564: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
565: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
566: PetscStrcat(value,",");
567: PetscStrcat(value,tmp);
568: }
569: break;
570: case OPTION_FLIST:
571: case OPTION_ELIST:
572: PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
573: break;
574: case OPTION_STRING:
575: PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
576: break;
577: case OPTION_STRING_ARRAY:
578: sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
579: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
580: sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
581: PetscStrcat(value,",");
582: PetscStrcat(value,tmp);
583: }
584: break;
585: }
586: PetscOptionsSetValue(option,value);
587: }
588: PetscFree(PetscOptionsObject.next->text);
589: PetscFree(PetscOptionsObject.next->option);
590: PetscFree(PetscOptionsObject.next->man);
591: PetscFree(PetscOptionsObject.next->edata);
593: if ((PetscOptionsObject.next->type == OPTION_STRING) || (PetscOptionsObject.next->type == OPTION_FLIST) || (PetscOptionsObject.next->type == OPTION_ELIST)){
594: /* must use system free since SAWs may have allocated it */
595: free(PetscOptionsObject.next->data);
596: } else {
597: PetscFree(PetscOptionsObject.next->data);
598: }
600: last = PetscOptionsObject.next;
601: PetscOptionsObject.next = PetscOptionsObject.next->next;
602: PetscFree(last);
603: }
604: PetscOptionsObject.next = 0;
605: return(0);
606: }
610: /*@C
611: PetscOptionsEnum - Gets the enum value for a particular option in the database.
613: Logically Collective on the communicator passed in PetscOptionsBegin()
615: Input Parameters:
616: + opt - option name
617: . text - short string that describes the option
618: . man - manual page with additional information on option
619: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
620: - defaultv - the default (current) value
622: Output Parameter:
623: + value - the value to return
624: - set - PETSC_TRUE if found, else PETSC_FALSE
626: Level: beginner
628: Concepts: options database
630: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
632: list is usually something like PCASMTypes or some other predefined list of enum names
634: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
635: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
636: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
637: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
638: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
639: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
640: PetscOptionsFList(), PetscOptionsEList()
641: @*/
642: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool *set)
643: {
645: PetscInt ntext = 0;
646: PetscInt tval;
647: PetscBool tflg;
650: while (list[ntext++]) {
651: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
652: }
653: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
654: ntext -= 3;
655: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
656: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
657: if (tflg) *value = (PetscEnum)tval;
658: if (set) *set = tflg;
659: return(0);
660: }
662: /* -------------------------------------------------------------------------------------------------------------*/
665: /*@C
666: PetscOptionsInt - Gets the integer value for a particular option in the database.
668: Logically Collective on the communicator passed in PetscOptionsBegin()
670: Input Parameters:
671: + opt - option name
672: . text - short string that describes the option
673: . man - manual page with additional information on option
674: - defaultv - the default (current) value
676: Output Parameter:
677: + value - the integer value to return
678: - flg - PETSC_TRUE if found, else PETSC_FALSE
680: Level: beginner
682: Concepts: options database^has int
684: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
686: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
687: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
688: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
689: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
690: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
691: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
692: PetscOptionsFList(), PetscOptionsEList()
693: @*/
694: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool *set)
695: {
697: PetscOptions amsopt;
700: if (!PetscOptionsPublishCount) {
701: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
702: PetscMalloc(sizeof(PetscInt),&amsopt->data);
704: *(PetscInt*)amsopt->data = defaultv;
705: }
706: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
707: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
708: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
709: }
710: return(0);
711: }
715: /*@C
716: PetscOptionsString - Gets the string value for a particular option in the database.
718: Logically Collective on the communicator passed in PetscOptionsBegin()
720: Input Parameters:
721: + opt - option name
722: . text - short string that describes the option
723: . man - manual page with additional information on option
724: . defaultv - the default (current) value
725: - len - length of the result string including null terminator
727: Output Parameter:
728: + value - the value to return
729: - flg - PETSC_TRUE if found, else PETSC_FALSE
731: Level: beginner
733: Concepts: options database^has int
735: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
737: Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls).
739: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
740: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
741: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
742: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
743: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
744: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
745: PetscOptionsFList(), PetscOptionsEList()
746: @*/
747: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool *set)
748: {
750: PetscOptions amsopt;
753: if (!PetscOptionsPublishCount) {
754: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
755: /* must use system malloc since SAWs may free this */
756: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
757: }
758: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
759: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
760: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
761: }
762: return(0);
763: }
767: /*@C
768: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
770: Logically Collective on the communicator passed in PetscOptionsBegin()
772: Input Parameters:
773: + opt - option name
774: . text - short string that describes the option
775: . man - manual page with additional information on option
776: - defaultv - the default (current) value
778: Output Parameter:
779: + value - the value to return
780: - flg - PETSC_TRUE if found, else PETSC_FALSE
782: Level: beginner
784: Concepts: options database^has int
786: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
788: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
789: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
790: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
791: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
792: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
793: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
794: PetscOptionsFList(), PetscOptionsEList()
795: @*/
796: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool *set)
797: {
799: PetscOptions amsopt;
802: if (!PetscOptionsPublishCount) {
803: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
804: PetscMalloc(sizeof(PetscReal),&amsopt->data);
806: *(PetscReal*)amsopt->data = defaultv;
807: }
808: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
809: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
810: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,(double)defaultv,text,ManSection(man));
811: }
812: return(0);
813: }
817: /*@C
818: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
820: Logically Collective on the communicator passed in PetscOptionsBegin()
822: Input Parameters:
823: + opt - option name
824: . text - short string that describes the option
825: . man - manual page with additional information on option
826: - defaultv - the default (current) value
828: Output Parameter:
829: + value - the value to return
830: - flg - PETSC_TRUE if found, else PETSC_FALSE
832: Level: beginner
834: Concepts: options database^has int
836: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
838: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
839: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
840: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
841: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
842: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
843: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
844: PetscOptionsFList(), PetscOptionsEList()
845: @*/
846: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool *set)
847: {
851: #if !defined(PETSC_USE_COMPLEX)
852: PetscOptionsReal(opt,text,man,defaultv,value,set);
853: #else
854: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
855: #endif
856: return(0);
857: }
861: /*@C
862: PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
863: its value is set to false.
865: Logically Collective on the communicator passed in PetscOptionsBegin()
867: Input Parameters:
868: + opt - option name
869: . text - short string that describes the option
870: - man - manual page with additional information on option
872: Output Parameter:
873: . flg - PETSC_TRUE if found, else PETSC_FALSE
875: Level: beginner
877: Concepts: options database^has int
879: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
881: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
882: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
883: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
884: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
885: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
886: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
887: PetscOptionsFList(), PetscOptionsEList()
888: @*/
889: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
890: {
892: PetscOptions amsopt;
895: if (!PetscOptionsPublishCount) {
896: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
897: PetscMalloc(sizeof(PetscBool),&amsopt->data);
899: *(PetscBool*)amsopt->data = PETSC_FALSE;
900: }
901: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
902: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
903: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
904: }
905: return(0);
906: }
910: /*@C
911: PetscOptionsFList - Puts a list of option values that a single one may be selected from
913: Logically Collective on the communicator passed in PetscOptionsBegin()
915: Input Parameters:
916: + opt - option name
917: . text - short string that describes the option
918: . man - manual page with additional information on option
919: . list - the possible choices
920: . defaultv - the default (current) value
921: - len - the length of the character array value
923: Output Parameter:
924: + value - the value to return
925: - set - PETSC_TRUE if found, else PETSC_FALSE
927: Level: intermediate
929: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
931: See PetscOptionsEList() for when the choices are given in a string array
933: To get a listing of all currently specified options,
934: see PetscOptionsView() or PetscOptionsGetAll()
936: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
938: Concepts: options database^list
940: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
941: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
942: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
943: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
944: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
945: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
946: @*/
947: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool *set)
948: {
950: PetscOptions amsopt;
953: if (!PetscOptionsPublishCount) {
954: PetscOptionsCreate_Private(opt,ltext,man,OPTION_FLIST,&amsopt);
955: /* must use system malloc since SAWs may free this */
956: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
957: amsopt->flist = list;
958: }
959: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
960: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
961: PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
962: }
963: return(0);
964: }
968: /*@C
969: PetscOptionsEList - Puts a list of option values that a single one may be selected from
971: Logically Collective on the communicator passed in PetscOptionsBegin()
973: Input Parameters:
974: + opt - option name
975: . ltext - short string that describes the option
976: . man - manual page with additional information on option
977: . list - the possible choices (one of these must be selected, anything else is invalid)
978: . ntext - number of choices
979: - defaultv - the default (current) value
981: Output Parameter:
982: + value - the index of the value to return
983: - set - PETSC_TRUE if found, else PETSC_FALSE
985: Level: intermediate
987: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
989: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
991: Concepts: options database^list
993: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
994: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
995: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
996: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
997: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
998: PetscOptionsFList(), PetscOptionsEnum()
999: @*/
1000: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool *set)
1001: {
1003: PetscInt i;
1004: PetscOptions amsopt;
1007: if (!PetscOptionsPublishCount) {
1008: PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
1009: /* must use system malloc since SAWs may free this */
1010: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
1011: amsopt->list = list;
1012: amsopt->nlist = ntext;
1013: }
1014: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
1015: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1016: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
1017: for (i=0; i<ntext; i++) {
1018: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
1019: }
1020: (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
1021: }
1022: return(0);
1023: }
1027: /*@C
1028: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1029: which at most a single value can be true.
1031: Logically Collective on the communicator passed in PetscOptionsBegin()
1033: Input Parameters:
1034: + opt - option name
1035: . text - short string that describes the option
1036: - man - manual page with additional information on option
1038: Output Parameter:
1039: . flg - whether that option was set or not
1041: Level: intermediate
1043: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1045: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1047: Concepts: options database^logical group
1049: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1050: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1051: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1052: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1053: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1054: PetscOptionsFList(), PetscOptionsEList()
1055: @*/
1056: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1057: {
1059: PetscOptions amsopt;
1062: if (!PetscOptionsPublishCount) {
1063: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1064: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1066: *(PetscBool*)amsopt->data = PETSC_FALSE;
1067: }
1068: *flg = PETSC_FALSE;
1069: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1070: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1071: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
1072: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1073: }
1074: return(0);
1075: }
1079: /*@C
1080: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1081: which at most a single value can be true.
1083: Logically Collective on the communicator passed in PetscOptionsBegin()
1085: Input Parameters:
1086: + opt - option name
1087: . text - short string that describes the option
1088: - man - manual page with additional information on option
1090: Output Parameter:
1091: . flg - PETSC_TRUE if found, else PETSC_FALSE
1093: Level: intermediate
1095: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1097: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1099: Concepts: options database^logical group
1101: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1102: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1103: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1104: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1105: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1106: PetscOptionsFList(), PetscOptionsEList()
1107: @*/
1108: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1109: {
1111: PetscOptions amsopt;
1114: if (!PetscOptionsPublishCount) {
1115: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1116: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1118: *(PetscBool*)amsopt->data = PETSC_FALSE;
1119: }
1120: *flg = PETSC_FALSE;
1121: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1122: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1123: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1124: }
1125: return(0);
1126: }
1130: /*@C
1131: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1132: which at most a single value can be true.
1134: Logically Collective on the communicator passed in PetscOptionsBegin()
1136: Input Parameters:
1137: + opt - option name
1138: . text - short string that describes the option
1139: - man - manual page with additional information on option
1141: Output Parameter:
1142: . flg - PETSC_TRUE if found, else PETSC_FALSE
1144: Level: intermediate
1146: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1148: Must follow a PetscOptionsBoolGroupBegin()
1150: Concepts: options database^logical group
1152: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1153: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1154: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1155: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1156: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1157: PetscOptionsFList(), PetscOptionsEList()
1158: @*/
1159: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1160: {
1162: PetscOptions amsopt;
1165: if (!PetscOptionsPublishCount) {
1166: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1167: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1169: *(PetscBool*)amsopt->data = PETSC_FALSE;
1170: }
1171: *flg = PETSC_FALSE;
1172: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1173: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1174: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1175: }
1176: return(0);
1177: }
1181: /*@C
1182: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1184: Logically Collective on the communicator passed in PetscOptionsBegin()
1186: Input Parameters:
1187: + opt - option name
1188: . text - short string that describes the option
1189: - man - manual page with additional information on option
1191: Output Parameter:
1192: . flg - PETSC_TRUE or PETSC_FALSE
1193: . set - PETSC_TRUE if found, else PETSC_FALSE
1195: Level: beginner
1197: Concepts: options database^logical
1199: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1201: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1202: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1203: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1204: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1205: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1206: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1207: PetscOptionsFList(), PetscOptionsEList()
1208: @*/
1209: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool *flg,PetscBool *set)
1210: {
1212: PetscBool iset;
1213: PetscOptions amsopt;
1216: if (!PetscOptionsPublishCount) {
1217: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1218: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1220: *(PetscBool*)amsopt->data = deflt;
1221: }
1222: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1223: if (!iset) {
1224: if (flg) *flg = deflt;
1225: }
1226: if (set) *set = iset;
1227: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1228: const char *v = PetscBools[deflt];
1229: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1230: }
1231: return(0);
1232: }
1236: /*@C
1237: PetscOptionsRealArray - Gets an array of double values for a particular
1238: option in the database. The values must be separated with commas with
1239: no intervening spaces.
1241: Logically Collective on the communicator passed in PetscOptionsBegin()
1243: Input Parameters:
1244: + opt - the option one is seeking
1245: . text - short string describing option
1246: . man - manual page for option
1247: - nmax - maximum number of values
1249: Output Parameter:
1250: + value - location to copy values
1251: . nmax - actual number of values found
1252: - set - PETSC_TRUE if found, else PETSC_FALSE
1254: Level: beginner
1256: Notes:
1257: The user should pass in an array of doubles
1259: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1261: Concepts: options database^array of strings
1263: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1264: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1265: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1266: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1267: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1268: PetscOptionsFList(), PetscOptionsEList()
1269: @*/
1270: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1271: {
1273: PetscInt i;
1274: PetscOptions amsopt;
1277: if (!PetscOptionsPublishCount) {
1278: PetscReal *vals;
1280: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1281: PetscMalloc1((*n),(PetscReal**)&amsopt->data);
1282: vals = (PetscReal*)amsopt->data;
1283: for (i=0; i<*n; i++) vals[i] = value[i];
1284: amsopt->arraylength = *n;
1285: }
1286: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1287: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1288: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%g",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,(double)value[0]);
1289: for (i=1; i<*n; i++) {
1290: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%g",(double)value[i]);
1291: }
1292: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1293: }
1294: return(0);
1295: }
1300: /*@C
1301: PetscOptionsIntArray - Gets an array of integers for a particular
1302: option in the database.
1304: Logically Collective on the communicator passed in PetscOptionsBegin()
1306: Input Parameters:
1307: + opt - the option one is seeking
1308: . text - short string describing option
1309: . man - manual page for option
1310: - n - maximum number of values
1312: Output Parameter:
1313: + value - location to copy values
1314: . n - actual number of values found
1315: - set - PETSC_TRUE if found, else PETSC_FALSE
1317: Level: beginner
1319: Notes:
1320: The array can be passed as
1321: a comma seperated list: 0,1,2,3,4,5,6,7
1322: a range (start-end+1): 0-8
1323: a range with given increment (start-end+1:inc): 0-7:2
1324: a combination of values and ranges seperated by commas: 0,1-8,8-15:2
1326: There must be no intervening spaces between the values.
1328: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1330: Concepts: options database^array of ints
1332: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1333: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1334: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1335: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1336: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1337: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1338: @*/
1339: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1340: {
1342: PetscInt i;
1343: PetscOptions amsopt;
1346: if (!PetscOptionsPublishCount) {
1347: PetscInt *vals;
1349: PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1350: PetscMalloc1((*n),(PetscInt**)&amsopt->data);
1351: vals = (PetscInt*)amsopt->data;
1352: for (i=0; i<*n; i++) vals[i] = value[i];
1353: amsopt->arraylength = *n;
1354: }
1355: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1356: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1357: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1358: for (i=1; i<*n; i++) {
1359: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1360: }
1361: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1362: }
1363: return(0);
1364: }
1368: /*@C
1369: PetscOptionsStringArray - Gets an array of string values for a particular
1370: option in the database. The values must be separated with commas with
1371: no intervening spaces.
1373: Logically Collective on the communicator passed in PetscOptionsBegin()
1375: Input Parameters:
1376: + opt - the option one is seeking
1377: . text - short string describing option
1378: . man - manual page for option
1379: - nmax - maximum number of strings
1381: Output Parameter:
1382: + value - location to copy strings
1383: . nmax - actual number of strings found
1384: - set - PETSC_TRUE if found, else PETSC_FALSE
1386: Level: beginner
1388: Notes:
1389: The user should pass in an array of pointers to char, to hold all the
1390: strings returned by this function.
1392: The user is responsible for deallocating the strings that are
1393: returned. The Fortran interface for this routine is not supported.
1395: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1397: Concepts: options database^array of strings
1399: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1400: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1401: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1402: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1403: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1404: PetscOptionsFList(), PetscOptionsEList()
1405: @*/
1406: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1407: {
1409: PetscOptions amsopt;
1412: if (!PetscOptionsPublishCount) {
1413: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1414: PetscMalloc1((*nmax),(char**)&amsopt->data);
1416: amsopt->arraylength = *nmax;
1417: }
1418: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1419: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1420: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1421: }
1422: return(0);
1423: }
1427: /*@C
1428: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1429: option in the database. The values must be separated with commas with
1430: no intervening spaces.
1432: Logically Collective on the communicator passed in PetscOptionsBegin()
1434: Input Parameters:
1435: + opt - the option one is seeking
1436: . text - short string describing option
1437: . man - manual page for option
1438: - nmax - maximum number of values
1440: Output Parameter:
1441: + value - location to copy values
1442: . nmax - actual number of values found
1443: - set - PETSC_TRUE if found, else PETSC_FALSE
1445: Level: beginner
1447: Notes:
1448: The user should pass in an array of doubles
1450: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1452: Concepts: options database^array of strings
1454: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1455: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1456: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1457: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1458: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1459: PetscOptionsFList(), PetscOptionsEList()
1460: @*/
1461: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1462: {
1464: PetscInt i;
1465: PetscOptions amsopt;
1468: if (!PetscOptionsPublishCount) {
1469: PetscBool *vals;
1471: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1472: PetscMalloc1((*n),(PetscBool**)&amsopt->data);
1473: vals = (PetscBool*)amsopt->data;
1474: for (i=0; i<*n; i++) vals[i] = value[i];
1475: amsopt->arraylength = *n;
1476: }
1477: PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1478: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1479: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1480: for (i=1; i<*n; i++) {
1481: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1482: }
1483: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1484: }
1485: return(0);
1486: }
1490: /*@C
1491: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1493: Logically Collective on the communicator passed in PetscOptionsBegin()
1495: Input Parameters:
1496: + opt - option name
1497: . text - short string that describes the option
1498: - man - manual page with additional information on option
1500: Output Parameter:
1501: + viewer - the viewer
1502: - set - PETSC_TRUE if found, else PETSC_FALSE
1504: Level: beginner
1506: Concepts: options database^has int
1508: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1510: See PetscOptionsGetVieweer() for the format of the supplied viewer and its options
1512: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1513: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1514: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1515: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1516: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1517: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1518: PetscOptionsFList(), PetscOptionsEList()
1519: @*/
1520: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1521: {
1523: PetscOptions amsopt;
1526: if (!PetscOptionsPublishCount) {
1527: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
1528: /* must use system malloc since SAWs may free this */
1529: PetscStrdup("",(char**)&amsopt->data);
1530: }
1531: PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
1532: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1533: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
1534: }
1535: return(0);
1536: }
1541: /*@C
1542: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1543: in KSPSetFromOptions_GMRES().
1545: Logically Collective on the communicator passed in PetscOptionsBegin()
1547: Input Parameter:
1548: . head - the heading text
1551: Level: intermediate
1553: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1555: Can be followed by a call to PetscOptionsTail() in the same function.
1557: Concepts: options database^subheading
1559: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1560: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1561: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1562: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1563: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1564: PetscOptionsFList(), PetscOptionsEList()
1565: @*/
1566: PetscErrorCode PetscOptionsHead(const char head[])
1567: {
1571: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1572: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1573: }
1574: return(0);
1575: }