Actual source code: aoptions.c
petsc-3.5.4 2015-05-23
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: }
151: /*
152: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
153: */
154: static PetscErrorCode PetscStrdup(const char s[],char *t[])
155: {
157: size_t len;
158: char *tmp = 0;
161: if (s) {
162: PetscStrlen(s,&len);
163: tmp = (char*) malloc((len+1)*sizeof(char*));
164: if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
165: PetscStrcpy(tmp,s);
166: }
167: *t = tmp;
168: return(0);
169: }
174: /*
175: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
177: Notes: this isn't really practical, it is just to demonstrate the principle
179: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
180: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
182: Bugs:
183: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
184: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
185: - Only works for PetscInt == int, PetscReal == double etc
187: Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different
188: address space and communicating with the PETSc program
190: */
191: PetscErrorCode PetscOptionsGetFromTextInput()
192: {
194: PetscOptions next = PetscOptionsObject.next;
195: char str[512];
196: PetscBool bid;
197: PetscReal ir,*valr;
198: PetscInt *vald;
199: size_t i;
201: (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
202: while (next) {
203: switch (next->type) {
204: case OPTION_HEAD:
205: break;
206: case OPTION_INT_ARRAY:
207: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
208: vald = (PetscInt*) next->data;
209: for (i=0; i<next->arraylength; i++) {
210: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
211: if (i < next->arraylength-1) {
212: PetscPrintf(PETSC_COMM_WORLD,",");
213: }
214: }
215: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
216: PetscScanString(PETSC_COMM_WORLD,512,str);
217: if (str[0]) {
218: PetscToken token;
219: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
220: size_t len;
221: char *value;
222: PetscBool foundrange;
224: next->set = PETSC_TRUE;
225: value = str;
226: PetscTokenCreate(value,',',&token);
227: PetscTokenFind(token,&value);
228: while (n < nmax) {
229: if (!value) break;
231: /* look for form d-D where d and D are integers */
232: foundrange = PETSC_FALSE;
233: PetscStrlen(value,&len);
234: if (value[0] == '-') i=2;
235: else i=1;
236: for (;i<len; i++) {
237: if (value[i] == '-') {
238: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
239: value[i] = 0;
240: PetscOptionsStringToInt(value,&start);
241: PetscOptionsStringToInt(value+i+1,&end);
242: 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);
243: 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);
244: for (; start<end; start++) {
245: *dvalue = start; dvalue++;n++;
246: }
247: foundrange = PETSC_TRUE;
248: break;
249: }
250: }
251: if (!foundrange) {
252: PetscOptionsStringToInt(value,dvalue);
253: dvalue++;
254: n++;
255: }
256: PetscTokenFind(token,&value);
257: }
258: PetscTokenDestroy(&token);
259: }
260: break;
261: case OPTION_REAL_ARRAY:
262: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
263: valr = (PetscReal*) next->data;
264: for (i=0; i<next->arraylength; i++) {
265: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
266: if (i < next->arraylength-1) {
267: PetscPrintf(PETSC_COMM_WORLD,",");
268: }
269: }
270: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
271: PetscScanString(PETSC_COMM_WORLD,512,str);
272: if (str[0]) {
273: PetscToken token;
274: PetscInt n = 0,nmax = next->arraylength;
275: PetscReal *dvalue = (PetscReal*)next->data;
276: char *value;
278: next->set = PETSC_TRUE;
279: value = str;
280: PetscTokenCreate(value,',',&token);
281: PetscTokenFind(token,&value);
282: while (n < nmax) {
283: if (!value) break;
284: PetscOptionsStringToReal(value,dvalue);
285: dvalue++;
286: n++;
287: PetscTokenFind(token,&value);
288: }
289: PetscTokenDestroy(&token);
290: }
291: break;
292: case OPTION_INT:
293: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
294: PetscScanString(PETSC_COMM_WORLD,512,str);
295: if (str[0]) {
296: #if defined(PETSC_SIZEOF_LONG_LONG)
297: long long lid;
298: sscanf(str,"%lld",&lid);
299: 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);
300: #else
301: long lid;
302: sscanf(str,"%ld",&lid);
303: 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);
304: #endif
306: next->set = PETSC_TRUE;
307: *((PetscInt*)next->data) = (PetscInt)lid;
308: }
309: break;
310: case OPTION_REAL:
311: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
312: PetscScanString(PETSC_COMM_WORLD,512,str);
313: if (str[0]) {
314: #if defined(PETSC_USE_REAL_SINGLE)
315: sscanf(str,"%e",&ir);
316: #elif defined(PETSC_USE_REAL_DOUBLE)
317: sscanf(str,"%le",&ir);
318: #elif defined(PETSC_USE_REAL___FLOAT128)
319: ir = strtoflt128(str,0);
320: #else
321: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
322: #endif
323: next->set = PETSC_TRUE;
324: *((PetscReal*)next->data) = ir;
325: }
326: break;
327: case OPTION_BOOL:
328: 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);
329: PetscScanString(PETSC_COMM_WORLD,512,str);
330: if (str[0]) {
331: PetscOptionsStringToBool(str,&bid);
332: next->set = PETSC_TRUE;
333: *((PetscBool*)next->data) = bid;
334: }
335: break;
336: case OPTION_STRING:
337: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,(char*)next->data,next->text,next->man);
338: PetscScanString(PETSC_COMM_WORLD,512,str);
339: if (str[0]) {
340: next->set = PETSC_TRUE;
341: /* must use system malloc since SAWs may free this */
342: PetscStrdup(str,(char**)&next->data);
343: }
344: break;
345: case OPTION_FLIST:
346: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
347: PetscScanString(PETSC_COMM_WORLD,512,str);
348: if (str[0]) {
349: PetscOptionsObject.changedmethod = PETSC_TRUE;
350: next->set = PETSC_TRUE;
351: /* must use system malloc since SAWs may free this */
352: PetscStrdup(str,(char**)&next->data);
353: }
354: break;
355: default:
356: break;
357: }
358: next = next->next;
359: }
360: return(0);
361: }
363: #if defined(PETSC_HAVE_SAWS)
364: #include <petscviewersaws.h>
366: static int count = 0;
370: PetscErrorCode PetscOptionsSAWsDestroy(void)
371: {
373: return(0);
374: }
378: /*
379: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
381: Bugs:
382: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
383: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
384: - Only works for PetscInt == int, PetscReal == double etc
387: */
388: PetscErrorCode PetscOptionsSAWsInput()
389: {
391: PetscOptions next = PetscOptionsObject.next;
392: static int mancount = 0;
393: char options[16];
394: PetscBool changedmethod = PETSC_FALSE;
395: char manname[16],textname[16];
396: char dir[1024];
398: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
399: sprintf(options,"Options_%d",count++);
401: PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* SAWs will change this, so cannot pass prefix directly */
403: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
404: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.title,1,SAWs_READ,SAWs_STRING));
405: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
406: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.pprefix,1,SAWs_READ,SAWs_STRING));
407: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
409: while (next) {
410: sprintf(manname,"_man_%d",mancount);
411: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
412: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
413: sprintf(textname,"_text_%d",mancount++);
414: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
415: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
417: switch (next->type) {
418: case OPTION_HEAD:
419: break;
420: case OPTION_INT_ARRAY:
421: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
422: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
423: break;
424: case OPTION_REAL_ARRAY:
425: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
426: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
427: break;
428: case OPTION_INT:
429: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
430: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
431: break;
432: case OPTION_REAL:
433: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
434: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
435: break;
436: case OPTION_BOOL:
437: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
438: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
439: break;
440: case OPTION_BOOL_ARRAY:
441: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
442: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
443: break;
444: case OPTION_STRING:
445: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
446: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
447: break;
448: case OPTION_STRING_ARRAY:
449: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
450: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
451: break;
452: case OPTION_FLIST:
453: {
454: PetscInt ntext;
455: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
456: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
457: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
458: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
459: }
460: break;
461: case OPTION_ELIST:
462: {
463: PetscInt ntext = next->nlist;
464: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
465: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
466: PetscMalloc((ntext+1)*sizeof(char),&next->edata);
467: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
468: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
469: }
470: break;
471: default:
472: break;
473: }
474: next = next->next;
475: }
477: /* wait until accessor has unlocked the memory */
478: PetscSAWsBlock();
480: /* determine if any values have been set in GUI */
481: next = PetscOptionsObject.next;
482: while (next) {
483: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
484: PetscStackCallSAWs(SAWs_Selected,(dir,&next->set));
485: next = next->next;
486: }
488: /* reset counter to -2; this updates the screen with the new options for the selected method */
489: if (changedmethod) PetscOptionsPublishCount = -2;
491: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
492: return(0);
493: }
494: #endif
498: PetscErrorCode PetscOptionsEnd_Private(void)
499: {
501: PetscOptions last;
502: char option[256],value[1024],tmp[32];
503: size_t j;
506: if (PetscOptionsObject.next) {
507: if (!PetscOptionsPublishCount) {
508: #if defined(PETSC_HAVE_SAWS)
509: PetscOptionsSAWsInput();
510: #else
511: PetscOptionsGetFromTextInput();
512: #endif
513: }
514: }
516: PetscFree(PetscOptionsObject.title);
517: PetscFree(PetscOptionsObject.prefix);
519: /* reset counter to -2; this updates the screen with the new options for the selected method */
520: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
521: /* reset alreadyprinted flag */
522: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
523: if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
524: PetscOptionsObject.object = NULL;
526: while (PetscOptionsObject.next) {
527: if (PetscOptionsObject.next->set) {
528: if (PetscOptionsObject.prefix) {
529: PetscStrcpy(option,"-");
530: PetscStrcat(option,PetscOptionsObject.prefix);
531: PetscStrcat(option,PetscOptionsObject.next->option+1);
532: } else {
533: PetscStrcpy(option,PetscOptionsObject.next->option);
534: }
536: switch (PetscOptionsObject.next->type) {
537: case OPTION_HEAD:
538: break;
539: case OPTION_INT_ARRAY:
540: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
541: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
542: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
543: PetscStrcat(value,",");
544: PetscStrcat(value,tmp);
545: }
546: break;
547: case OPTION_INT:
548: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
549: break;
550: case OPTION_REAL:
551: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
552: break;
553: case OPTION_REAL_ARRAY:
554: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
555: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
556: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
557: PetscStrcat(value,",");
558: PetscStrcat(value,tmp);
559: }
560: break;
561: case OPTION_BOOL:
562: sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
563: break;
564: case OPTION_BOOL_ARRAY:
565: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
566: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
567: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
568: PetscStrcat(value,",");
569: PetscStrcat(value,tmp);
570: }
571: break;
572: case OPTION_FLIST:
573: case OPTION_ELIST:
574: PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
575: break;
576: case OPTION_STRING:
577: PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
578: break;
579: case OPTION_STRING_ARRAY:
580: sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
581: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
582: sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
583: PetscStrcat(value,",");
584: PetscStrcat(value,tmp);
585: }
586: break;
587: }
588: PetscOptionsSetValue(option,value);
589: }
590: PetscFree(PetscOptionsObject.next->text);
591: PetscFree(PetscOptionsObject.next->option);
592: PetscFree(PetscOptionsObject.next->man);
593: PetscFree(PetscOptionsObject.next->edata);
595: if ((PetscOptionsObject.next->type == OPTION_STRING) || (PetscOptionsObject.next->type == OPTION_FLIST) || (PetscOptionsObject.next->type == OPTION_ELIST)){
596: /* must use system free since SAWs may have allocated it */
597: free(PetscOptionsObject.next->data);
598: } else {
599: PetscFree(PetscOptionsObject.next->data);
600: }
602: last = PetscOptionsObject.next;
603: PetscOptionsObject.next = PetscOptionsObject.next->next;
604: PetscFree(last);
605: }
606: PetscOptionsObject.next = 0;
607: return(0);
608: }
612: /*@C
613: PetscOptionsEnum - Gets the enum value for a particular option in the database.
615: Logically Collective on the communicator passed in PetscOptionsBegin()
617: Input Parameters:
618: + opt - option name
619: . text - short string that describes the option
620: . man - manual page with additional information on option
621: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
622: - defaultv - the default (current) value
624: Output Parameter:
625: + value - the value to return
626: - set - PETSC_TRUE if found, else PETSC_FALSE
628: Level: beginner
630: Concepts: options database
632: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
634: list is usually something like PCASMTypes or some other predefined list of enum names
636: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
637: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
638: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
639: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
640: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
641: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
642: PetscOptionsFList(), PetscOptionsEList()
643: @*/
644: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool *set)
645: {
647: PetscInt ntext = 0;
648: PetscInt tval;
649: PetscBool tflg;
652: while (list[ntext++]) {
653: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
654: }
655: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
656: ntext -= 3;
657: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
658: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
659: if (tflg) *value = (PetscEnum)tval;
660: if (set) *set = tflg;
661: return(0);
662: }
664: /* -------------------------------------------------------------------------------------------------------------*/
667: /*@C
668: PetscOptionsInt - Gets the integer value for a particular option in the database.
670: Logically Collective on the communicator passed in PetscOptionsBegin()
672: Input Parameters:
673: + opt - option name
674: . text - short string that describes the option
675: . man - manual page with additional information on option
676: - defaultv - the default (current) value, if the user does not provide a value this is returned in value
678: Output Parameter:
679: + value - the integer value to return
680: - flg - PETSC_TRUE if found, else PETSC_FALSE
682: Level: beginner
684: Concepts: options database^has int
686: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
688: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
689: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
690: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
691: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
692: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
693: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
694: PetscOptionsFList(), PetscOptionsEList()
695: @*/
696: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool *set)
697: {
699: PetscOptions amsopt;
702: if (!PetscOptionsPublishCount) {
703: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
704: PetscMalloc(sizeof(PetscInt),&amsopt->data);
706: *(PetscInt*)amsopt->data = defaultv;
707: }
708: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
709: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
710: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
711: }
712: return(0);
713: }
717: /*@C
718: PetscOptionsString - Gets the string value for a particular option in the database.
720: Logically Collective on the communicator passed in PetscOptionsBegin()
722: Input Parameters:
723: + opt - option name
724: . text - short string that describes the option
725: . man - manual page with additional information on option
726: . defaultv - the default (current) value, if the user does not provide a value this is returned in value
727: - len - length of the result string including null terminator
729: Output Parameter:
730: + value - the value to return
731: - flg - PETSC_TRUE if found, else PETSC_FALSE
733: Level: beginner
735: Concepts: options database^has int
737: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
739: 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).
741: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
742: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
743: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
744: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
745: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
746: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
747: PetscOptionsFList(), PetscOptionsEList()
748: @*/
749: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool *set)
750: {
752: PetscOptions amsopt;
755: if (!PetscOptionsPublishCount) {
756: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
757: /* must use system malloc since SAWs may free this */
758: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
759: }
760: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
761: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
762: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
763: }
764: return(0);
765: }
769: /*@C
770: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
772: Logically Collective on the communicator passed in PetscOptionsBegin()
774: Input Parameters:
775: + opt - option name
776: . text - short string that describes the option
777: . man - manual page with additional information on option
778: - defaultv - the default (current) value, if the user does not provide a value this is returned in value
780: Output Parameter:
781: + value - the value to return
782: - flg - PETSC_TRUE if found, else PETSC_FALSE
784: Level: beginner
786: Concepts: options database^has int
788: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
790: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
791: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
792: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
793: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
794: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
795: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
796: PetscOptionsFList(), PetscOptionsEList()
797: @*/
798: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool *set)
799: {
801: PetscOptions amsopt;
804: if (!PetscOptionsPublishCount) {
805: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
806: PetscMalloc(sizeof(PetscReal),&amsopt->data);
808: *(PetscReal*)amsopt->data = defaultv;
809: }
810: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
811: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
812: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,(double)defaultv,text,ManSection(man));
813: }
814: return(0);
815: }
819: /*@C
820: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
822: Logically Collective on the communicator passed in PetscOptionsBegin()
824: Input Parameters:
825: + opt - option name
826: . text - short string that describes the option
827: . man - manual page with additional information on option
828: - defaultv - the default (current) value, if the user does not provide a value this is returned in value
830: Output Parameter:
831: + value - the value to return
832: - flg - PETSC_TRUE if found, else PETSC_FALSE
834: Level: beginner
836: Concepts: options database^has int
838: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
840: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
841: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
842: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
843: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
844: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
845: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
846: PetscOptionsFList(), PetscOptionsEList()
847: @*/
848: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool *set)
849: {
853: #if !defined(PETSC_USE_COMPLEX)
854: PetscOptionsReal(opt,text,man,defaultv,value,set);
855: #else
856: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
857: #endif
858: return(0);
859: }
863: /*@C
864: 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
865: its value is set to false.
867: Logically Collective on the communicator passed in PetscOptionsBegin()
869: Input Parameters:
870: + opt - option name
871: . text - short string that describes the option
872: - man - manual page with additional information on option
874: Output Parameter:
875: . flg - PETSC_TRUE if found, else PETSC_FALSE
877: Level: beginner
879: Concepts: options database^has int
881: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
883: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
884: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
885: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
886: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
887: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
888: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
889: PetscOptionsFList(), PetscOptionsEList()
890: @*/
891: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
892: {
894: PetscOptions amsopt;
897: if (!PetscOptionsPublishCount) {
898: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
899: PetscMalloc(sizeof(PetscBool),&amsopt->data);
901: *(PetscBool*)amsopt->data = PETSC_FALSE;
902: }
903: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
904: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
905: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
906: }
907: return(0);
908: }
912: /*@C
913: PetscOptionsFList - Puts a list of option values that a single one may be selected from
915: Logically Collective on the communicator passed in PetscOptionsBegin()
917: Input Parameters:
918: + opt - option name
919: . text - short string that describes the option
920: . man - manual page with additional information on option
921: . list - the possible choices
922: . defaultv - the default (current) value, if the user does not provide a value this is returned in value
923: - len - the length of the character array value
925: Output Parameter:
926: + value - the value to return
927: - set - PETSC_TRUE if found, else PETSC_FALSE
929: Level: intermediate
931: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
933: See PetscOptionsEList() for when the choices are given in a string array
935: To get a listing of all currently specified options,
936: see PetscOptionsView() or PetscOptionsGetAll()
938: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
940: Concepts: options database^list
942: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
943: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
944: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
945: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
946: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
947: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
948: @*/
949: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool *set)
950: {
952: PetscOptions amsopt;
955: if (!PetscOptionsPublishCount) {
956: PetscOptionsCreate_Private(opt,ltext,man,OPTION_FLIST,&amsopt);
957: /* must use system malloc since SAWs may free this */
958: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
959: amsopt->flist = list;
960: }
961: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
962: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
963: PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
964: }
965: return(0);
966: }
970: /*@C
971: PetscOptionsEList - Puts a list of option values that a single one may be selected from
973: Logically Collective on the communicator passed in PetscOptionsBegin()
975: Input Parameters:
976: + opt - option name
977: . ltext - short string that describes the option
978: . man - manual page with additional information on option
979: . list - the possible choices (one of these must be selected, anything else is invalid)
980: . ntext - number of choices
981: - defaultv - the default (current) value, if the user does not provide a value the index of defaultv is returned
983: Output Parameter:
984: + value - the index of the value to return
985: - set - PETSC_TRUE if found, else PETSC_FALSE
987: Level: intermediate
989: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
991: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
993: Concepts: options database^list
995: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
996: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
997: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
998: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
999: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1000: PetscOptionsFList(), PetscOptionsEnum()
1001: @*/
1002: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool *set)
1003: {
1005: PetscInt i;
1006: PetscOptions amsopt;
1009: if (!PetscOptionsPublishCount) {
1010: PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
1011: /* must use system malloc since SAWs may free this */
1012: PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
1013: amsopt->list = list;
1014: amsopt->nlist = ntext;
1015: }
1016: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
1017: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1018: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
1019: for (i=0; i<ntext; i++) {
1020: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
1021: }
1022: (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
1023: }
1024: return(0);
1025: }
1029: /*@C
1030: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1031: which at most a single value can be true.
1033: Logically Collective on the communicator passed in PetscOptionsBegin()
1035: Input Parameters:
1036: + opt - option name
1037: . text - short string that describes the option
1038: - man - manual page with additional information on option
1040: Output Parameter:
1041: . flg - whether that option was set or not
1043: Level: intermediate
1045: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1047: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1049: Concepts: options database^logical group
1051: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1052: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1053: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1054: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1055: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1056: PetscOptionsFList(), PetscOptionsEList()
1057: @*/
1058: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1059: {
1061: PetscOptions amsopt;
1064: if (!PetscOptionsPublishCount) {
1065: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1066: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1068: *(PetscBool*)amsopt->data = PETSC_FALSE;
1069: }
1070: *flg = PETSC_FALSE;
1071: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1072: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1073: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
1074: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1075: }
1076: return(0);
1077: }
1081: /*@C
1082: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1083: which at most a single value can be true.
1085: Logically Collective on the communicator passed in PetscOptionsBegin()
1087: Input Parameters:
1088: + opt - option name
1089: . text - short string that describes the option
1090: - man - manual page with additional information on option
1092: Output Parameter:
1093: . flg - PETSC_TRUE if found, else PETSC_FALSE
1095: Level: intermediate
1097: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1099: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1101: Concepts: options database^logical group
1103: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1104: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1105: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1106: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1107: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1108: PetscOptionsFList(), PetscOptionsEList()
1109: @*/
1110: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1111: {
1113: PetscOptions amsopt;
1116: if (!PetscOptionsPublishCount) {
1117: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1118: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1120: *(PetscBool*)amsopt->data = PETSC_FALSE;
1121: }
1122: *flg = PETSC_FALSE;
1123: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1124: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1125: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1126: }
1127: return(0);
1128: }
1132: /*@C
1133: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1134: which at most a single value can be true.
1136: Logically Collective on the communicator passed in PetscOptionsBegin()
1138: Input Parameters:
1139: + opt - option name
1140: . text - short string that describes the option
1141: - man - manual page with additional information on option
1143: Output Parameter:
1144: . flg - PETSC_TRUE if found, else PETSC_FALSE
1146: Level: intermediate
1148: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1150: Must follow a PetscOptionsBoolGroupBegin()
1152: Concepts: options database^logical group
1154: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1155: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1156: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1157: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1158: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1159: PetscOptionsFList(), PetscOptionsEList()
1160: @*/
1161: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1162: {
1164: PetscOptions amsopt;
1167: if (!PetscOptionsPublishCount) {
1168: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1169: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1171: *(PetscBool*)amsopt->data = PETSC_FALSE;
1172: }
1173: *flg = PETSC_FALSE;
1174: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1175: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1176: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1177: }
1178: return(0);
1179: }
1183: /*@C
1184: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1186: Logically Collective on the communicator passed in PetscOptionsBegin()
1188: Input Parameters:
1189: + opt - option name
1190: . text - short string that describes the option
1191: . man - manual page with additional information on option
1192: - deflt - the default value, if the user does not set a value then this value is returned in flg
1194: Output Parameter:
1195: . flg - PETSC_TRUE or PETSC_FALSE
1196: . set - PETSC_TRUE if found, else PETSC_FALSE
1198: Level: beginner
1200: Concepts: options database^logical
1202: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1204: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1205: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1206: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1207: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1208: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1209: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1210: PetscOptionsFList(), PetscOptionsEList()
1211: @*/
1212: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool *flg,PetscBool *set)
1213: {
1215: PetscBool iset;
1216: PetscOptions amsopt;
1219: if (!PetscOptionsPublishCount) {
1220: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1221: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1223: *(PetscBool*)amsopt->data = deflt;
1224: }
1225: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1226: if (!iset) {
1227: if (flg) *flg = deflt;
1228: }
1229: if (set) *set = iset;
1230: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1231: const char *v = PetscBools[deflt];
1232: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1233: }
1234: return(0);
1235: }
1239: /*@C
1240: PetscOptionsRealArray - Gets an array of double values for a particular
1241: option in the database. The values must be separated with commas with
1242: no intervening spaces.
1244: Logically Collective on the communicator passed in PetscOptionsBegin()
1246: Input Parameters:
1247: + opt - the option one is seeking
1248: . text - short string describing option
1249: . man - manual page for option
1250: - nmax - maximum number of values
1252: Output Parameter:
1253: + value - location to copy values
1254: . nmax - actual number of values found
1255: - set - PETSC_TRUE if found, else PETSC_FALSE
1257: Level: beginner
1259: Notes:
1260: The user should pass in an array of doubles
1262: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1264: Concepts: options database^array of strings
1266: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1267: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1268: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1269: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1270: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1271: PetscOptionsFList(), PetscOptionsEList()
1272: @*/
1273: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1274: {
1276: PetscInt i;
1277: PetscOptions amsopt;
1280: if (!PetscOptionsPublishCount) {
1281: PetscReal *vals;
1283: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1284: PetscMalloc1((*n),(PetscReal**)&amsopt->data);
1285: vals = (PetscReal*)amsopt->data;
1286: for (i=0; i<*n; i++) vals[i] = value[i];
1287: amsopt->arraylength = *n;
1288: }
1289: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1290: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1291: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%g",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,(double)value[0]);
1292: for (i=1; i<*n; i++) {
1293: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%g",(double)value[i]);
1294: }
1295: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1296: }
1297: return(0);
1298: }
1303: /*@C
1304: PetscOptionsIntArray - Gets an array of integers for a particular
1305: option in the database.
1307: Logically Collective on the communicator passed in PetscOptionsBegin()
1309: Input Parameters:
1310: + opt - the option one is seeking
1311: . text - short string describing option
1312: . man - manual page for option
1313: - n - maximum number of values
1315: Output Parameter:
1316: + value - location to copy values
1317: . n - actual number of values found
1318: - set - PETSC_TRUE if found, else PETSC_FALSE
1320: Level: beginner
1322: Notes:
1323: The array can be passed as
1324: a comma seperated list: 0,1,2,3,4,5,6,7
1325: a range (start-end+1): 0-8
1326: a range with given increment (start-end+1:inc): 0-7:2
1327: a combination of values and ranges seperated by commas: 0,1-8,8-15:2
1329: There must be no intervening spaces between the values.
1331: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1333: Concepts: options database^array of ints
1335: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1336: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1337: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1338: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1339: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1340: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1341: @*/
1342: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1343: {
1345: PetscInt i;
1346: PetscOptions amsopt;
1349: if (!PetscOptionsPublishCount) {
1350: PetscInt *vals;
1352: PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1353: PetscMalloc1((*n),(PetscInt**)&amsopt->data);
1354: vals = (PetscInt*)amsopt->data;
1355: for (i=0; i<*n; i++) vals[i] = value[i];
1356: amsopt->arraylength = *n;
1357: }
1358: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1359: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1360: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1361: for (i=1; i<*n; i++) {
1362: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1363: }
1364: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1365: }
1366: return(0);
1367: }
1371: /*@C
1372: PetscOptionsStringArray - Gets an array of string values for a particular
1373: option in the database. The values must be separated with commas with
1374: no intervening spaces.
1376: Logically Collective on the communicator passed in PetscOptionsBegin()
1378: Input Parameters:
1379: + opt - the option one is seeking
1380: . text - short string describing option
1381: . man - manual page for option
1382: - nmax - maximum number of strings
1384: Output Parameter:
1385: + value - location to copy strings
1386: . nmax - actual number of strings found
1387: - set - PETSC_TRUE if found, else PETSC_FALSE
1389: Level: beginner
1391: Notes:
1392: The user should pass in an array of pointers to char, to hold all the
1393: strings returned by this function.
1395: The user is responsible for deallocating the strings that are
1396: returned. The Fortran interface for this routine is not supported.
1398: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1400: Concepts: options database^array of strings
1402: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1403: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1404: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1405: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1406: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1407: PetscOptionsFList(), PetscOptionsEList()
1408: @*/
1409: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1410: {
1412: PetscOptions amsopt;
1415: if (!PetscOptionsPublishCount) {
1416: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1417: PetscMalloc1((*nmax),(char**)&amsopt->data);
1419: amsopt->arraylength = *nmax;
1420: }
1421: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1422: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1423: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1424: }
1425: return(0);
1426: }
1430: /*@C
1431: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1432: option in the database. The values must be separated with commas with
1433: no intervening spaces.
1435: Logically Collective on the communicator passed in PetscOptionsBegin()
1437: Input Parameters:
1438: + opt - the option one is seeking
1439: . text - short string describing option
1440: . man - manual page for option
1441: - nmax - maximum number of values
1443: Output Parameter:
1444: + value - location to copy values
1445: . nmax - actual number of values found
1446: - set - PETSC_TRUE if found, else PETSC_FALSE
1448: Level: beginner
1450: Notes:
1451: The user should pass in an array of doubles
1453: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1455: Concepts: options database^array of strings
1457: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1458: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1459: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1460: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1461: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1462: PetscOptionsFList(), PetscOptionsEList()
1463: @*/
1464: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1465: {
1467: PetscInt i;
1468: PetscOptions amsopt;
1471: if (!PetscOptionsPublishCount) {
1472: PetscBool *vals;
1474: PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1475: PetscMalloc1((*n),(PetscBool**)&amsopt->data);
1476: vals = (PetscBool*)amsopt->data;
1477: for (i=0; i<*n; i++) vals[i] = value[i];
1478: amsopt->arraylength = *n;
1479: }
1480: PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1481: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1482: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1483: for (i=1; i<*n; i++) {
1484: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1485: }
1486: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1487: }
1488: return(0);
1489: }
1493: /*@C
1494: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1496: Logically Collective on the communicator passed in PetscOptionsBegin()
1498: Input Parameters:
1499: + opt - option name
1500: . text - short string that describes the option
1501: - man - manual page with additional information on option
1503: Output Parameter:
1504: + viewer - the viewer
1505: - set - PETSC_TRUE if found, else PETSC_FALSE
1507: Level: beginner
1509: Concepts: options database^has int
1511: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1513: See PetscOptionsGetVieweer() for the format of the supplied viewer and its options
1515: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1516: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1517: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1518: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1519: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1520: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1521: PetscOptionsFList(), PetscOptionsEList()
1522: @*/
1523: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1524: {
1526: PetscOptions amsopt;
1529: if (!PetscOptionsPublishCount) {
1530: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
1531: /* must use system malloc since SAWs may free this */
1532: PetscStrdup("",(char**)&amsopt->data);
1533: }
1534: PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
1535: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1536: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
1537: }
1538: return(0);
1539: }
1544: /*@C
1545: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1546: in KSPSetFromOptions_GMRES().
1548: Logically Collective on the communicator passed in PetscOptionsBegin()
1550: Input Parameter:
1551: . head - the heading text
1554: Level: intermediate
1556: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1558: Can be followed by a call to PetscOptionsTail() in the same function.
1560: Concepts: options database^subheading
1562: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1563: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1564: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1565: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1566: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1567: PetscOptionsFList(), PetscOptionsEList()
1568: @*/
1569: PetscErrorCode PetscOptionsHead(const char head[])
1570: {
1574: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1575: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1576: }
1577: return(0);
1578: }