Actual source code: aoptions.c
petsc-3.3-p7 2013-05-11
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 <petscsys.h> /*I "petscsys.h" I*/
9: #if defined(PETSC_HAVE_STDLIB_H)
10: #include <stdlib.h>
11: #endif
13: #define ManSection(str) ((str)?(str):"None")
15: /*
16: Keep a linked list of options that have been posted and we are waiting for
17: user selection. See the manual page for PetscOptionsBegin()
19: Eventually we'll attach this beast to a MPI_Comm
20: */
21: PetscOptionsObjectType PetscOptionsObject;
22: PetscInt PetscOptionsPublishCount = 0;
26: /*
27: Handles setting up the data structure in a call to PetscOptionsBegin()
28: */
29: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
30: {
34: PetscOptionsObject.next = 0;
35: PetscOptionsObject.comm = comm;
36: PetscOptionsObject.changedmethod = PETSC_FALSE;
37: PetscFree(PetscOptionsObject.prefix);
38: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
39: PetscFree(PetscOptionsObject.title);
40: PetscStrallocpy(title,&PetscOptionsObject.title);
42: PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
43: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
44: if (!PetscOptionsObject.alreadyprinted) {
45: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
46: }
47: }
48: return(0);
49: }
53: /*
54: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
55: */
56: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
57: {
59: char title[256];
60: PetscBool flg;
64: PetscOptionsObject.object = obj;
65: 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(struct _n_PetscOptions,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) {
102: PetscOptionsObject.next = *amsopt;
103: } else {
104: next = PetscOptionsObject.next;
105: while (next->next) next = next->next;
106: next->next = *amsopt;
107: }
108: return(0);
109: }
113: /*
114: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
116: Collective on MPI_Comm
118: Input Parameters:
119: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
120: . n - length of the string, must be the same on all processes
121: - str - location to store input
123: Bugs:
124: . Assumes process 0 of the given communicator has access to stdin
126: */
127: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
128: {
129: size_t i;
130: char c;
131: PetscMPIInt rank,nm;
135: MPI_Comm_rank(comm,&rank);
136: if (!rank) {
137: c = (char) getchar();
138: i = 0;
139: while ( c != '\n' && i < n-1) {
140: str[i++] = c;
141: c = (char) getchar();
142: }
143: str[i] = 0;
144: }
145: nm = PetscMPIIntCast(n);
146: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
147: return(0);
148: }
152: /*
153: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
155: Notes: this isn't really practical, it is just to demonstrate the principle
157: Bugs:
158: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
159: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
160: - Only works for PetscInt == int, PetscReal == double etc
162: Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different
163: address space and communicating with the PETSc program
165: */
166: PetscErrorCode PetscOptionsGetFromTextInput()
167: {
169: PetscOptions next = PetscOptionsObject.next;
170: char str[512];
171: PetscInt id;
172: PetscReal ir,*valr;
173: PetscInt *vald;
174: size_t i;
175:
176: (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
177: while (next) {
178: switch (next->type) {
179: case OPTION_HEAD:
180: break;
181: case OPTION_INT_ARRAY:
182: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
183: vald = (PetscInt*) next->data;
184: for (i=0; i<next->arraylength; i++) {
185: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
186: if (i < next->arraylength-1) {
187: PetscPrintf(PETSC_COMM_WORLD,",");
188: }
189: }
190: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
191: PetscScanString(PETSC_COMM_WORLD,512,str);
192: if (str[0]) {
193: PetscToken token;
194: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
195: size_t len;
196: char* value;
197: PetscBool foundrange;
199: next->set = PETSC_TRUE;
200: value = str;
201: PetscTokenCreate(value,',',&token);
202: PetscTokenFind(token,&value);
203: while (n < nmax) {
204: if (!value) break;
205:
206: /* look for form d-D where d and D are integers */
207: foundrange = PETSC_FALSE;
208: PetscStrlen(value,&len);
209: if (value[0] == '-') i=2;
210: else i=1;
211: for (;i<len; i++) {
212: if (value[i] == '-') {
213: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
214: value[i] = 0;
215: PetscOptionsStringToInt(value,&start);
216: PetscOptionsStringToInt(value+i+1,&end);
217: 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);
218: 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);
219: for (;start<end; start++) {
220: *dvalue = start; dvalue++;n++;
221: }
222: foundrange = PETSC_TRUE;
223: break;
224: }
225: }
226: if (!foundrange) {
227: PetscOptionsStringToInt(value,dvalue);
228: dvalue++;
229: n++;
230: }
231: PetscTokenFind(token,&value);
232: }
233: PetscTokenDestroy(&token);
234: }
235: break;
236: case OPTION_REAL_ARRAY:
237: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
238: valr = (PetscReal*) next->data;
239: for (i=0; i<next->arraylength; i++) {
240: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
241: if (i < next->arraylength-1) {
242: PetscPrintf(PETSC_COMM_WORLD,",");
243: }
244: }
245: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
246: PetscScanString(PETSC_COMM_WORLD,512,str);
247: if (str[0]) {
248: PetscToken token;
249: PetscInt n=0,nmax = next->arraylength;
250: PetscReal *dvalue = (PetscReal*)next->data;
251: char* value;
253: next->set = PETSC_TRUE;
254: value = str;
255: PetscTokenCreate(value,',',&token);
256: PetscTokenFind(token,&value);
257: while (n < nmax) {
258: if (!value) break;
259: PetscOptionsStringToReal(value,dvalue);
260: dvalue++;
261: n++;
262: PetscTokenFind(token,&value);
263: }
264: PetscTokenDestroy(&token);
265: }
266: break;
267: case OPTION_INT:
268: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(int*)next->data,next->text,next->man);
269: PetscScanString(PETSC_COMM_WORLD,512,str);
270: if (str[0]) {
271: #if defined(PETSC_USE_64BIT_INDICES)
272: sscanf(str,"%lld",&id);
273: #else
274: sscanf(str,"%d",&id);
275: #endif
276: next->set = PETSC_TRUE;
277: *((PetscInt*)next->data) = id;
278: }
279: break;
280: case OPTION_REAL:
281: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(double*)next->data,next->text,next->man);
282: PetscScanString(PETSC_COMM_WORLD,512,str);
283: if (str[0]) {
284: #if defined(PETSC_USE_REAL_SINGLE)
285: sscanf(str,"%e",&ir);
286: #elif defined(PETSC_USE_REAL_DOUBLE)
287: sscanf(str,"%le",&ir);
288: #elif defined(PETSC_USE_REAL___FLOAT128)
289: ir = strtoflt128(str,0);
290: #else
291: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
292: #endif
293: next->set = PETSC_TRUE;
294: *((PetscReal*)next->data) = ir;
295: }
296: break;
297: case OPTION_LOGICAL:
298: case OPTION_STRING:
299: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,(char*)next->data,next->text,next->man);
300: PetscScanString(PETSC_COMM_WORLD,512,str);
301: if (str[0]) {
302: next->set = PETSC_TRUE;
303: PetscStrcpy((char*)next->data,str);
304: }
305: break;
306: case OPTION_LIST:
307: PetscFListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
308: PetscScanString(PETSC_COMM_WORLD,512,str);
309: if (str[0]) {
310: PetscOptionsObject.changedmethod = PETSC_TRUE;
311: next->set = PETSC_TRUE;
312: PetscStrcpy((char*)next->data,str);
313: }
314: break;
315: default:
316: break;
317: }
318: next = next->next;
319: }
320: return(0);
321: }
323: #if defined(PETSC_HAVE_AMS)
324: #define CHKERRAMS(err) if (err) {char *msg; AMS_Explain_error((err), &(msg)); SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"AMS Error: %s",msg);}
325: #define CHKERRAMSFieldName(err,fn) if (err) {char *msg; AMS_Explain_error((err), &(msg)); SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Fieldname %s, AMS Error: %s",fn,msg);}
327: static int count = 0;
331: PetscErrorCode PetscOptionsAMSDestroy(void)
332: {
334: AMS_Comm acomm = -1;
335: AMS_Memory amem = -1;
336: char options[16];
337: const char *string = "Exit";
339: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
340: PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
341: sprintf(options,"Options_%d",count++);
342: AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
343: AMS_Memory_add_field(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"Exit");
345: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
346: AMS_Memory_publish(amem);CHKERRAMS(ierr);
347: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
348: /* wait until accessor has unlocked the memory */
349: AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
350: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
351: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
352: AMS_Memory_destroy(amem);CHKERRAMS(ierr);
353: return(0);
354: }
358: /*
359: PetscOptionsAMSInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the AMS
361: Bugs:
362: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
363: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
364: - Only works for PetscInt == int, PetscReal == double etc
367: */
368: PetscErrorCode PetscOptionsAMSInput()
369: {
371: PetscOptions next = PetscOptionsObject.next;
372: static int mancount = 0;
373: char options[16];
374: AMS_Comm acomm = -1;
375: AMS_Memory amem = -1;
376: PetscBool changedmethod = PETSC_FALSE;
377: char manname[16];
379: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
380: PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
381: sprintf(options,"Options_%d",count++);
382: AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
383: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
384: PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* AMS will change this, so cannot pass prefix directly */
386: AMS_Memory_add_field(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,PetscOptionsObject.title);
387: /* AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMS(ierr); */
388: AMS_Memory_add_field(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"ChangedMethod");
390: while (next) {
391: AMS_Memory_add_field(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->option);
392: PetscMalloc(sizeof(char*),&next->pman);
393: *(char **)next->pman = next->man;
394: sprintf(manname,"man_%d",mancount++);
395: AMS_Memory_add_field(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,manname);
397: switch (next->type) {
398: case OPTION_HEAD:
399: break;
400: case OPTION_INT_ARRAY:
401: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
402: break;
403: case OPTION_REAL_ARRAY:
404: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
405: break;
406: case OPTION_INT:
407: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
408: break;
409: case OPTION_REAL:
410: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
411: break;
412: case OPTION_LOGICAL:
413: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
414: break;
415: case OPTION_LOGICAL_ARRAY:
416: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
417: break;
418: case OPTION_STRING:
419: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
420: break;
421: case OPTION_STRING_ARRAY:
422: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
423: break;
424: case OPTION_LIST:
425: {PetscInt ntext;
426: char ldefault[128];
427: PetscStrcpy(ldefault,"DEFAULT:");
428: PetscStrcat(ldefault,next->text);
429: AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
430: PetscFListGet(next->flist,(char***)&next->edata,&ntext);
431: AMS_Memory_add_field(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
432: break;}
433: case OPTION_ELIST:
434: {PetscInt ntext = next->nlist;
435: char ldefault[128];
436: PetscStrcpy(ldefault,"DEFAULT:");
437: PetscStrcat(ldefault,next->text);
438: AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
439: PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
440: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
441: AMS_Memory_add_field(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
442: break;}
443: default:
444: break;
445: }
446: next = next->next;
447: }
449: AMS_Memory_publish(amem);CHKERRAMS(ierr);
450: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
451: /* wait until accessor has unlocked the memory */
452: AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
453: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
454:
455: /* reset counter to -2; this updates the screen with the new options for the selected method */
456: if (changedmethod) PetscOptionsPublishCount = -2;
458: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
459: AMS_Memory_destroy(amem);CHKERRAMS(ierr);
460: return(0);
461: }
462: #endif
466: PetscErrorCode PetscOptionsEnd_Private(void)
467: {
469: PetscOptions last;
470: char option[256],value[1024],tmp[32];
471: size_t j;
475: CHKMEMQ;
476: if (PetscOptionsObject.next) {
477: if (!PetscOptionsPublishCount) {
478: #if defined(PETSC_HAVE_AMS)
479: PetscOptionsAMSInput();
480: #else
481: PetscOptionsGetFromTextInput();
482: #endif
483: }
484: }
486: PetscFree(PetscOptionsObject.title);
487: PetscFree(PetscOptionsObject.prefix);
489: /* reset counter to -2; this updates the screen with the new options for the selected method */
490: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
491: /* reset alreadyprinted flag */
492: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
493: if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
494: PetscOptionsObject.object = PETSC_NULL;
496: while (PetscOptionsObject.next) {
497: if (PetscOptionsObject.next->set) {
498: if (PetscOptionsObject.prefix) {
499: PetscStrcpy(option,"-");
500: PetscStrcat(option,PetscOptionsObject.prefix);
501: PetscStrcat(option,PetscOptionsObject.next->option+1);
502: } else {
503: PetscStrcpy(option,PetscOptionsObject.next->option);
504: }
506: switch (PetscOptionsObject.next->type) {
507: case OPTION_HEAD:
508: break;
509: case OPTION_INT_ARRAY:
510: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
511: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
512: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
513: PetscStrcat(value,",");
514: PetscStrcat(value,tmp);
515: }
516: break;
517: case OPTION_INT:
518: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
519: break;
520: case OPTION_REAL:
521: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
522: break;
523: case OPTION_REAL_ARRAY:
524: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
525: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
526: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
527: PetscStrcat(value,",");
528: PetscStrcat(value,tmp);
529: }
530: break;
531: case OPTION_LOGICAL:
532: sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
533: break;
534: case OPTION_LOGICAL_ARRAY:
535: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
536: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
537: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
538: PetscStrcat(value,",");
539: PetscStrcat(value,tmp);
540: }
541: break;
542: case OPTION_LIST:
543: case OPTION_ELIST:
544: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
545: break;
546: case OPTION_STRING:
547: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
548: case OPTION_STRING_ARRAY:
549: sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
550: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
551: sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
552: PetscStrcat(value,",");
553: PetscStrcat(value,tmp);
554: }
555: break;
556: }
557: PetscOptionsSetValue(option,value);
558: }
559: PetscFree(PetscOptionsObject.next->text);
560: PetscFree(PetscOptionsObject.next->option);
561: PetscFree(PetscOptionsObject.next->man);
562: PetscFree(PetscOptionsObject.next->data);
563: PetscFree(PetscOptionsObject.next->edata);
564: last = PetscOptionsObject.next;
565: PetscOptionsObject.next = PetscOptionsObject.next->next;
566: PetscFree(last);
567: CHKMEMQ;
568: }
569: CHKMEMQ;
570: PetscOptionsObject.next = 0;
571: return(0);
572: }
576: /*@C
577: PetscOptionsEnum - Gets the enum value for a particular option in the database.
579: Logically Collective on the communicator passed in PetscOptionsBegin()
581: Input Parameters:
582: + opt - option name
583: . text - short string that describes the option
584: . man - manual page with additional information on option
585: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
586: - defaultv - the default (current) value
588: Output Parameter:
589: + value - the value to return
590: - flg - PETSC_TRUE if found, else PETSC_FALSE
592: Level: beginner
594: Concepts: options database
596: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
598: list is usually something like PCASMTypes or some other predefined list of enum names
600: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
601: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
602: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
603: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
604: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
605: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
606: PetscOptionsList(), PetscOptionsEList()
607: @*/
608: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const*list,PetscEnum defaultv,PetscEnum *value,PetscBool *set)
609: {
611: PetscInt ntext = 0;
612: PetscInt tval;
613: PetscBool tflg;
616: while (list[ntext++]) {
617: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
618: }
619: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
620: ntext -= 3;
621: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
622: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
623: if (tflg) *value = (PetscEnum)tval;
624: if (set) *set = tflg;
625: return(0);
626: }
628: /* -------------------------------------------------------------------------------------------------------------*/
631: /*@C
632: PetscOptionsInt - Gets the integer value for a particular option in the database.
634: Logically Collective on the communicator passed in PetscOptionsBegin()
636: Input Parameters:
637: + opt - option name
638: . text - short string that describes the option
639: . man - manual page with additional information on option
640: - defaultv - the default (current) value
642: Output Parameter:
643: + value - the integer value to return
644: - flg - PETSC_TRUE if found, else PETSC_FALSE
646: Level: beginner
648: Concepts: options database^has int
650: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
652: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
653: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
654: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
655: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
656: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
657: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
658: PetscOptionsList(), PetscOptionsEList()
659: @*/
660: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool *set)
661: {
663: PetscOptions amsopt;
666: if (!PetscOptionsPublishCount) {
667: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
668: PetscMalloc(sizeof(PetscInt),&amsopt->data);
669: *(PetscInt*)amsopt->data = defaultv;
670: }
671: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
672: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
673: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
674: }
675: return(0);
676: }
680: /*@C
681: PetscOptionsString - Gets the string value for a particular option in the database.
683: Logically Collective on the communicator passed in PetscOptionsBegin()
685: Input Parameters:
686: + opt - option name
687: . text - short string that describes the option
688: . man - manual page with additional information on option
689: . defaultv - the default (current) value
690: - len - length of the result string including null terminator
692: Output Parameter:
693: + value - the value to return
694: - flg - PETSC_TRUE if found, else PETSC_FALSE
696: Level: beginner
698: Concepts: options database^has int
700: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
702: 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).
704: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
705: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
706: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
707: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
708: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
709: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
710: PetscOptionsList(), PetscOptionsEList()
711: @*/
712: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool *set)
713: {
715: PetscOptions amsopt;
718: if (!PetscOptionsPublishCount) {
719: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
720: PetscMalloc(sizeof(char*),&amsopt->data);
721: *(const char**)amsopt->data = defaultv;
722: }
723: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
724: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
725: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
726: }
727: return(0);
728: }
732: /*@C
733: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
735: Logically Collective on the communicator passed in PetscOptionsBegin()
737: Input Parameters:
738: + opt - option name
739: . text - short string that describes the option
740: . man - manual page with additional information on option
741: - defaultv - the default (current) value
743: Output Parameter:
744: + value - the value to return
745: - flg - PETSC_TRUE if found, else PETSC_FALSE
747: Level: beginner
749: Concepts: options database^has int
751: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
753: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
754: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
755: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
756: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
757: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
758: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
759: PetscOptionsList(), PetscOptionsEList()
760: @*/
761: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool *set)
762: {
764: PetscOptions amsopt;
767: if (!PetscOptionsPublishCount) {
768: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
769: PetscMalloc(sizeof(PetscReal),&amsopt->data);
770: *(PetscReal*)amsopt->data = defaultv;
771: }
772: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
773: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
774: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
775: }
776: return(0);
777: }
781: /*@C
782: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
784: Logically Collective on the communicator passed in PetscOptionsBegin()
786: Input Parameters:
787: + opt - option name
788: . text - short string that describes the option
789: . man - manual page with additional information on option
790: - defaultv - the default (current) value
792: Output Parameter:
793: + value - the value to return
794: - flg - PETSC_TRUE if found, else PETSC_FALSE
796: Level: beginner
798: Concepts: options database^has int
800: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
802: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
803: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
804: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
805: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
806: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
807: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
808: PetscOptionsList(), PetscOptionsEList()
809: @*/
810: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool *set)
811: {
815: #if !defined(PETSC_USE_COMPLEX)
816: PetscOptionsReal(opt,text,man,defaultv,value,set);
817: #else
818: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
819: #endif
820: return(0);
821: }
825: /*@C
826: 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
827: its value is set to false.
829: Logically Collective on the communicator passed in PetscOptionsBegin()
831: Input Parameters:
832: + opt - option name
833: . text - short string that describes the option
834: - man - manual page with additional information on option
836: Output Parameter:
837: . flg - PETSC_TRUE if found, else PETSC_FALSE
839: Level: beginner
841: Concepts: options database^has int
843: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
845: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
846: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
847: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
848: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
849: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
850: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
851: PetscOptionsList(), PetscOptionsEList()
852: @*/
853: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
854: {
856: PetscOptions amsopt;
859: if (!PetscOptionsPublishCount) {
860: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
861: PetscMalloc(sizeof(PetscBool),&amsopt->data);
862: *(PetscBool*)amsopt->data = PETSC_FALSE;
863: }
864: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
865: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
866: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
867: }
868: return(0);
869: }
873: /*@C
874: PetscOptionsList - Puts a list of option values that a single one may be selected from
876: Logically Collective on the communicator passed in PetscOptionsBegin()
878: Input Parameters:
879: + opt - option name
880: . text - short string that describes the option
881: . man - manual page with additional information on option
882: . list - the possible choices
883: . defaultv - the default (current) value
884: - len - the length of the character array value
886: Output Parameter:
887: + value - the value to return
888: - set - PETSC_TRUE if found, else PETSC_FALSE
890: Level: intermediate
891:
892: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
894: See PetscOptionsEList() for when the choices are given in a string array
896: To get a listing of all currently specified options,
897: see PetscOptionsView() or PetscOptionsGetAll()
899: Concepts: options database^list
901: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
902: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
903: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
904: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
905: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
906: PetscOptionsList(), PetscOptionsEList(), PetscOptionsEnum()
907: @*/
908: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],size_t len,PetscBool *set)
909: {
911: PetscOptions amsopt;
914: if (!PetscOptionsPublishCount) {
915: PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
916: PetscMalloc(sizeof(char*),&amsopt->data);
917: *(const char**)amsopt->data = defaultv;
918: amsopt->flist = list;
919: }
920: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
921: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
922: PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
923: }
924: return(0);
925: }
929: /*@C
930: PetscOptionsEList - Puts a list of option values that a single one may be selected from
932: Logically Collective on the communicator passed in PetscOptionsBegin()
934: Input Parameters:
935: + opt - option name
936: . ltext - short string that describes the option
937: . man - manual page with additional information on option
938: . list - the possible choices
939: . ntext - number of choices
940: - defaultv - the default (current) value
942: Output Parameter:
943: + value - the index of the value to return
944: - set - PETSC_TRUE if found, else PETSC_FALSE
945:
946: Level: intermediate
948: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
950: See PetscOptionsList() for when the choices are given in a PetscFList()
952: Concepts: options database^list
954: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
955: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
956: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
957: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
958: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
959: PetscOptionsList(), PetscOptionsEnum()
960: @*/
961: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const*list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool *set)
962: {
964: PetscInt i;
965: PetscOptions amsopt;
968: if (!PetscOptionsPublishCount) {
969: PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
970: PetscMalloc(sizeof(char*),&amsopt->data);
971: *(const char**)amsopt->data = defaultv;
972: amsopt->list = list;
973: amsopt->nlist = ntext;
974: }
975: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
976: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
977: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
978: for (i=0; i<ntext; i++){
979: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
980: }
981: (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
982: }
983: return(0);
984: }
988: /*@C
989: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
990: which at most a single value can be true.
992: Logically Collective on the communicator passed in PetscOptionsBegin()
994: Input Parameters:
995: + opt - option name
996: . text - short string that describes the option
997: - man - manual page with additional information on option
999: Output Parameter:
1000: . flg - whether that option was set or not
1001:
1002: Level: intermediate
1004: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1006: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1008: Concepts: options database^logical group
1010: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1011: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1012: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1013: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1014: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1015: PetscOptionsList(), PetscOptionsEList()
1016: @*/
1017: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1018: {
1020: PetscOptions amsopt;
1023: if (!PetscOptionsPublishCount) {
1024: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1025: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1026: *(PetscBool*)amsopt->data = PETSC_FALSE;
1027: }
1028: *flg = PETSC_FALSE;
1029: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1030: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1031: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
1032: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1033: }
1034: return(0);
1035: }
1039: /*@C
1040: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1041: which at most a single value can be true.
1043: Logically Collective on the communicator passed in PetscOptionsBegin()
1045: Input Parameters:
1046: + opt - option name
1047: . text - short string that describes the option
1048: - man - manual page with additional information on option
1050: Output Parameter:
1051: . flg - PETSC_TRUE if found, else PETSC_FALSE
1052:
1053: Level: intermediate
1055: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1057: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1059: Concepts: options database^logical group
1061: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1062: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1063: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1064: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1065: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1066: PetscOptionsList(), PetscOptionsEList()
1067: @*/
1068: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1069: {
1071: PetscOptions amsopt;
1074: if (!PetscOptionsPublishCount) {
1075: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1076: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1077: *(PetscBool*)amsopt->data = PETSC_FALSE;
1078: }
1079: *flg = PETSC_FALSE;
1080: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1081: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1082: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1083: }
1084: return(0);
1085: }
1089: /*@C
1090: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1091: which at most a single value can be true.
1093: Logically Collective on the communicator passed in PetscOptionsBegin()
1095: Input Parameters:
1096: + opt - option name
1097: . text - short string that describes the option
1098: - man - manual page with additional information on option
1100: Output Parameter:
1101: . flg - PETSC_TRUE if found, else PETSC_FALSE
1102:
1103: Level: intermediate
1105: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1107: Must follow a PetscOptionsBoolGroupBegin()
1109: Concepts: options database^logical group
1111: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1112: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1113: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1114: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1115: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1116: PetscOptionsList(), PetscOptionsEList()
1117: @*/
1118: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1119: {
1121: PetscOptions amsopt;
1124: if (!PetscOptionsPublishCount) {
1125: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1126: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1127: *(PetscBool*)amsopt->data = PETSC_FALSE;
1128: }
1129: *flg = PETSC_FALSE;
1130: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1131: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1132: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1133: }
1134: return(0);
1135: }
1139: /*@C
1140: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1142: Logically Collective on the communicator passed in PetscOptionsBegin()
1144: Input Parameters:
1145: + opt - option name
1146: . text - short string that describes the option
1147: - man - manual page with additional information on option
1149: Output Parameter:
1150: . flg - PETSC_TRUE or PETSC_FALSE
1151: . set - PETSC_TRUE if found, else PETSC_FALSE
1153: Level: beginner
1155: Concepts: options database^logical
1157: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1159: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1160: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1161: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1162: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1163: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1164: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1165: PetscOptionsList(), PetscOptionsEList()
1166: @*/
1167: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool *flg,PetscBool *set)
1168: {
1170: PetscBool iset;
1171: PetscOptions amsopt;
1174: if (!PetscOptionsPublishCount) {
1175: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1176: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1177: *(PetscBool*)amsopt->data = deflt;
1178: }
1179: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1180: if (!iset) {
1181: if (flg) *flg = deflt;
1182: }
1183: if (set) *set = iset;
1184: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1185: const char *v = PetscBools[deflt];
1186: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1187: }
1188: return(0);
1189: }
1193: /*@C
1194: PetscOptionsRealArray - Gets an array of double values for a particular
1195: option in the database. The values must be separated with commas with
1196: no intervening spaces.
1198: Logically Collective on the communicator passed in PetscOptionsBegin()
1200: Input Parameters:
1201: + opt - the option one is seeking
1202: . text - short string describing option
1203: . man - manual page for option
1204: - nmax - maximum number of values
1206: Output Parameter:
1207: + value - location to copy values
1208: . nmax - actual number of values found
1209: - set - PETSC_TRUE if found, else PETSC_FALSE
1211: Level: beginner
1213: Notes:
1214: The user should pass in an array of doubles
1216: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1218: Concepts: options database^array of strings
1220: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1221: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1222: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1223: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1224: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1225: PetscOptionsList(), PetscOptionsEList()
1226: @*/
1227: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1228: {
1230: PetscInt i;
1231: PetscOptions amsopt;
1234: if (!PetscOptionsPublishCount) {
1235: PetscReal *vals;
1237: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1238: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1239: vals = (PetscReal*)amsopt->data;
1240: for (i=0; i<*n; i++) vals[i] = value[i];
1241: amsopt->arraylength = *n;
1242: }
1243: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1244: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1245: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1246: for (i=1; i<*n; i++) {
1247: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1248: }
1249: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1250: }
1251: return(0);
1252: }
1257: /*@C
1258: PetscOptionsIntArray - Gets an array of integers for a particular
1259: option in the database.
1261: Logically Collective on the communicator passed in PetscOptionsBegin()
1263: Input Parameters:
1264: + opt - the option one is seeking
1265: . text - short string describing option
1266: . man - manual page for option
1267: - n - maximum number of values
1269: Output Parameter:
1270: + value - location to copy values
1271: . n - actual number of values found
1272: - set - PETSC_TRUE if found, else PETSC_FALSE
1274: Level: beginner
1276: Notes:
1277: The array can be passed as
1278: a comma seperated list: 0,1,2,3,4,5,6,7
1279: a range (start-end+1): 0-8
1280: a range with given increment (start-end+1:inc): 0-7:2
1281: a combination of values and ranges seperated by commas: 0,1-8,8-15:2
1283: There must be no intervening spaces between the values.
1285: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1287: Concepts: options database^array of ints
1289: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1290: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1291: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1292: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1293: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1294: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1295: @*/
1296: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1297: {
1299: PetscInt i;
1300: PetscOptions amsopt;
1303: if (!PetscOptionsPublishCount) {
1304: PetscInt *vals;
1306: PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1307: PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1308: vals = (PetscInt*)amsopt->data;
1309: for (i=0; i<*n; i++) vals[i] = value[i];
1310: amsopt->arraylength = *n;
1311: }
1312: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1313: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1314: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1315: for (i=1; i<*n; i++) {
1316: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1317: }
1318: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1319: }
1320: return(0);
1321: }
1325: /*@C
1326: PetscOptionsStringArray - Gets an array of string values for a particular
1327: option in the database. The values must be separated with commas with
1328: no intervening spaces.
1330: Logically Collective on the communicator passed in PetscOptionsBegin()
1332: Input Parameters:
1333: + opt - the option one is seeking
1334: . text - short string describing option
1335: . man - manual page for option
1336: - nmax - maximum number of strings
1338: Output Parameter:
1339: + value - location to copy strings
1340: . nmax - actual number of strings found
1341: - set - PETSC_TRUE if found, else PETSC_FALSE
1343: Level: beginner
1345: Notes:
1346: The user should pass in an array of pointers to char, to hold all the
1347: strings returned by this function.
1349: The user is responsible for deallocating the strings that are
1350: returned. The Fortran interface for this routine is not supported.
1352: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1354: Concepts: options database^array of strings
1356: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1357: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1358: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1359: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1360: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1361: PetscOptionsList(), PetscOptionsEList()
1362: @*/
1363: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1364: {
1366: PetscOptions amsopt;
1369: if (!PetscOptionsPublishCount) {
1370: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1371: PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1372: amsopt->arraylength = *nmax;
1373: }
1374: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1375: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1376: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1377: }
1378: return(0);
1379: }
1383: /*@C
1384: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1385: option in the database. The values must be separated with commas with
1386: no intervening spaces.
1388: Logically Collective on the communicator passed in PetscOptionsBegin()
1390: Input Parameters:
1391: + opt - the option one is seeking
1392: . text - short string describing option
1393: . man - manual page for option
1394: - nmax - maximum number of values
1396: Output Parameter:
1397: + value - location to copy values
1398: . nmax - actual number of values found
1399: - set - PETSC_TRUE if found, else PETSC_FALSE
1401: Level: beginner
1403: Notes:
1404: The user should pass in an array of doubles
1406: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1408: Concepts: options database^array of strings
1410: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1411: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1412: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1413: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1414: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1415: PetscOptionsList(), PetscOptionsEList()
1416: @*/
1417: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1418: {
1420: PetscInt i;
1421: PetscOptions amsopt;
1424: if (!PetscOptionsPublishCount) {
1425: PetscBool *vals;
1427: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
1428: PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
1429: vals = (PetscBool*)amsopt->data;
1430: for (i=0; i<*n; i++) vals[i] = value[i];
1431: amsopt->arraylength = *n;
1432: }
1433: PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1434: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1435: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1436: for (i=1; i<*n; i++) {
1437: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1438: }
1439: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1440: }
1441: return(0);
1442: }
1447: /*@C
1448: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1449: in KSPSetFromOptions_GMRES().
1451: Logically Collective on the communicator passed in PetscOptionsBegin()
1453: Input Parameter:
1454: . head - the heading text
1456:
1457: Level: intermediate
1459: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1461: Can be followed by a call to PetscOptionsTail() in the same function.
1463: Concepts: options database^subheading
1465: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1466: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1467: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1468: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1469: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1470: PetscOptionsList(), PetscOptionsEList()
1471: @*/
1472: PetscErrorCode PetscOptionsHead(const char head[])
1473: {
1477: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1478: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1479: }
1480: return(0);
1481: }