Actual source code: aoptions.c
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_LONG_DOUBLE)
289: sscanf(str,"%Le",&ir);
290: #elif defined(PETSC_USE_REAL___FLOAT128)
291: ir = strtoflt128(str,0);
292: #else
293: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
294: #endif
295: next->set = PETSC_TRUE;
296: *((PetscReal*)next->data) = ir;
297: }
298: break;
299: case OPTION_LOGICAL:
300: case OPTION_STRING:
301: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,(char*)next->data,next->text,next->man);
302: PetscScanString(PETSC_COMM_WORLD,512,str);
303: if (str[0]) {
304: next->set = PETSC_TRUE;
305: PetscStrcpy((char*)next->data,str);
306: }
307: break;
308: case OPTION_LIST:
309: PetscFListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
310: PetscScanString(PETSC_COMM_WORLD,512,str);
311: if (str[0]) {
312: PetscOptionsObject.changedmethod = PETSC_TRUE;
313: next->set = PETSC_TRUE;
314: PetscStrcpy((char*)next->data,str);
315: }
316: break;
317: default:
318: break;
319: }
320: next = next->next;
321: }
322: return(0);
323: }
325: #if defined(PETSC_HAVE_AMS)
326: #define CHKERRAMS(err) if (err) {char *msg; AMS_Explain_error((err), &(msg)); SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"AMS Error: %s",msg);}
327: #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);}
329: static int count = 0;
333: PetscErrorCode PetscOptionsAMSDestroy(void)
334: {
336: AMS_Comm acomm = -1;
337: AMS_Memory amem = -1;
338: char options[16];
339: const char *string = "Exit";
341: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
342: PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
343: sprintf(options,"Options_%d",count++);
344: AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
345: AMS_Memory_add_field(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"Exit");
347: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
348: AMS_Memory_publish(amem);CHKERRAMS(ierr);
349: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
350: /* wait until accessor has unlocked the memory */
351: AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
352: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
353: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
354: AMS_Memory_destroy(amem);CHKERRAMS(ierr);
355: return(0);
356: }
360: /*
361: PetscOptionsAMSInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the AMS
363: Bugs:
364: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
365: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
366: - Only works for PetscInt == int, PetscReal == double etc
369: */
370: PetscErrorCode PetscOptionsAMSInput()
371: {
373: PetscOptions next = PetscOptionsObject.next;
374: static int mancount = 0;
375: char options[16];
376: AMS_Comm acomm = -1;
377: AMS_Memory amem = -1;
378: PetscBool changedmethod = PETSC_FALSE;
379: char manname[16];
381: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
382: PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
383: sprintf(options,"Options_%d",count++);
384: AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
385: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
386: PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* AMS will change this, so cannot pass prefix directly */
388: AMS_Memory_add_field(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,PetscOptionsObject.title);
389: /* AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMS(ierr); */
390: AMS_Memory_add_field(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"ChangedMethod");
392: while (next) {
393: AMS_Memory_add_field(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->option);
394: PetscMalloc(sizeof(char*),&next->pman);
395: *(char **)next->pman = next->man;
396: sprintf(manname,"man_%d",mancount++);
397: AMS_Memory_add_field(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,manname);
399: switch (next->type) {
400: case OPTION_HEAD:
401: break;
402: case OPTION_INT_ARRAY:
403: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
404: break;
405: case OPTION_REAL_ARRAY:
406: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
407: break;
408: case OPTION_INT:
409: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
410: break;
411: case OPTION_REAL:
412: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
413: break;
414: case OPTION_LOGICAL:
415: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
416: break;
417: case OPTION_LOGICAL_ARRAY:
418: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
419: break;
420: case OPTION_STRING:
421: AMS_Memory_add_field(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
422: break;
423: case OPTION_STRING_ARRAY:
424: AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
425: break;
426: case OPTION_LIST:
427: {PetscInt ntext;
428: char ldefault[128];
429: PetscStrcpy(ldefault,"DEFAULT:");
430: PetscStrcat(ldefault,next->text);
431: AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
432: PetscFListGet(next->flist,(char***)&next->edata,&ntext);
433: AMS_Memory_add_field(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
434: break;}
435: case OPTION_ELIST:
436: {PetscInt ntext = next->nlist;
437: char ldefault[128];
438: PetscStrcpy(ldefault,"DEFAULT:");
439: PetscStrcat(ldefault,next->text);
440: AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
441: PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
442: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
443: AMS_Memory_add_field(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
444: break;}
445: default:
446: break;
447: }
448: next = next->next;
449: }
451: AMS_Memory_publish(amem);CHKERRAMS(ierr);
452: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
453: /* wait until accessor has unlocked the memory */
454: AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
455: AMS_Memory_take_access(amem);CHKERRAMS(ierr);
456:
457: /* reset counter to -2; this updates the screen with the new options for the selected method */
458: if (changedmethod) PetscOptionsPublishCount = -2;
460: AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
461: AMS_Memory_destroy(amem);CHKERRAMS(ierr);
462: return(0);
463: }
464: #endif
468: PetscErrorCode PetscOptionsEnd_Private(void)
469: {
471: PetscOptions last;
472: char option[256],value[1024],tmp[32];
473: size_t j;
477: CHKMEMQ;
478: if (PetscOptionsObject.next) {
479: if (!PetscOptionsPublishCount) {
480: #if defined(PETSC_HAVE_AMS)
481: PetscOptionsAMSInput();
482: #else
483: PetscOptionsGetFromTextInput();
484: #endif
485: }
486: }
488: PetscFree(PetscOptionsObject.title);
489: PetscFree(PetscOptionsObject.prefix);
491: /* reset counter to -2; this updates the screen with the new options for the selected method */
492: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
493: /* reset alreadyprinted flag */
494: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
495: if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
496: PetscOptionsObject.object = PETSC_NULL;
498: while (PetscOptionsObject.next) {
499: if (PetscOptionsObject.next->set) {
500: if (PetscOptionsObject.prefix) {
501: PetscStrcpy(option,"-");
502: PetscStrcat(option,PetscOptionsObject.prefix);
503: PetscStrcat(option,PetscOptionsObject.next->option+1);
504: } else {
505: PetscStrcpy(option,PetscOptionsObject.next->option);
506: }
508: switch (PetscOptionsObject.next->type) {
509: case OPTION_HEAD:
510: break;
511: case OPTION_INT_ARRAY:
512: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
513: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
514: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
515: PetscStrcat(value,",");
516: PetscStrcat(value,tmp);
517: }
518: break;
519: case OPTION_INT:
520: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
521: break;
522: case OPTION_REAL:
523: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
524: break;
525: case OPTION_REAL_ARRAY:
526: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
527: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
528: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
529: PetscStrcat(value,",");
530: PetscStrcat(value,tmp);
531: }
532: break;
533: case OPTION_LOGICAL:
534: sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
535: break;
536: case OPTION_LOGICAL_ARRAY:
537: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
538: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
539: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
540: PetscStrcat(value,",");
541: PetscStrcat(value,tmp);
542: }
543: break;
544: case OPTION_LIST:
545: case OPTION_ELIST:
546: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
547: break;
548: case OPTION_STRING:
549: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
550: case OPTION_STRING_ARRAY:
551: sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
552: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
553: sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
554: PetscStrcat(value,",");
555: PetscStrcat(value,tmp);
556: }
557: break;
558: }
559: PetscOptionsSetValue(option,value);
560: }
561: PetscFree(PetscOptionsObject.next->text);
562: PetscFree(PetscOptionsObject.next->option);
563: PetscFree(PetscOptionsObject.next->man);
564: PetscFree(PetscOptionsObject.next->data);
565: PetscFree(PetscOptionsObject.next->edata);
566: last = PetscOptionsObject.next;
567: PetscOptionsObject.next = PetscOptionsObject.next->next;
568: PetscFree(last);
569: CHKMEMQ;
570: }
571: CHKMEMQ;
572: PetscOptionsObject.next = 0;
573: return(0);
574: }
578: /*@C
579: PetscOptionsEnum - Gets the enum value for a particular option in the database.
581: Logically Collective on the communicator passed in PetscOptionsBegin()
583: Input Parameters:
584: + opt - option name
585: . text - short string that describes the option
586: . man - manual page with additional information on option
587: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
588: - defaultv - the default (current) value
590: Output Parameter:
591: + value - the value to return
592: - flg - PETSC_TRUE if found, else PETSC_FALSE
594: Level: beginner
596: Concepts: options database
598: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
600: list is usually something like PCASMTypes or some other predefined list of enum names
602: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
603: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
604: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
605: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
606: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
607: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
608: PetscOptionsList(), PetscOptionsEList()
609: @*/
610: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const*list,PetscEnum defaultv,PetscEnum *value,PetscBool *set)
611: {
613: PetscInt ntext = 0;
614: PetscInt tval;
615: PetscBool tflg;
618: while (list[ntext++]) {
619: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
620: }
621: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
622: ntext -= 3;
623: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
624: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
625: if (tflg) *value = (PetscEnum)tval;
626: if (set) *set = tflg;
627: return(0);
628: }
630: /* -------------------------------------------------------------------------------------------------------------*/
633: /*@C
634: PetscOptionsInt - Gets the integer value for a particular option in the database.
636: Logically Collective on the communicator passed in PetscOptionsBegin()
638: Input Parameters:
639: + opt - option name
640: . text - short string that describes the option
641: . man - manual page with additional information on option
642: - defaultv - the default (current) value
644: Output Parameter:
645: + value - the integer value to return
646: - flg - PETSC_TRUE if found, else PETSC_FALSE
648: Level: beginner
650: Concepts: options database^has int
652: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
654: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
655: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
656: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
657: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
658: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
659: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
660: PetscOptionsList(), PetscOptionsEList()
661: @*/
662: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool *set)
663: {
665: PetscOptions amsopt;
668: if (!PetscOptionsPublishCount) {
669: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
670: PetscMalloc(sizeof(PetscInt),&amsopt->data);
671: *(PetscInt*)amsopt->data = defaultv;
672: }
673: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
674: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
675: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
676: }
677: return(0);
678: }
682: /*@C
683: PetscOptionsString - Gets the string value for a particular option in the database.
685: Logically Collective on the communicator passed in PetscOptionsBegin()
687: Input Parameters:
688: + opt - option name
689: . text - short string that describes the option
690: . man - manual page with additional information on option
691: . defaultv - the default (current) value
692: - len - length of the result string including null terminator
694: Output Parameter:
695: + value - the value to return
696: - flg - PETSC_TRUE if found, else PETSC_FALSE
698: Level: beginner
700: Concepts: options database^has int
702: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
704: 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).
706: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
707: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
708: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
709: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
710: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
711: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
712: PetscOptionsList(), PetscOptionsEList()
713: @*/
714: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool *set)
715: {
717: PetscOptions amsopt;
720: if (!PetscOptionsPublishCount) {
721: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
722: PetscMalloc(sizeof(char*),&amsopt->data);
723: *(const char**)amsopt->data = defaultv;
724: }
725: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
726: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
727: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
728: }
729: return(0);
730: }
734: /*@C
735: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
737: Logically Collective on the communicator passed in PetscOptionsBegin()
739: Input Parameters:
740: + opt - option name
741: . text - short string that describes the option
742: . man - manual page with additional information on option
743: - defaultv - the default (current) value
745: Output Parameter:
746: + value - the value to return
747: - flg - PETSC_TRUE if found, else PETSC_FALSE
749: Level: beginner
751: Concepts: options database^has int
753: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
755: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
756: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
757: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
758: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
759: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
760: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
761: PetscOptionsList(), PetscOptionsEList()
762: @*/
763: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool *set)
764: {
766: PetscOptions amsopt;
769: if (!PetscOptionsPublishCount) {
770: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
771: PetscMalloc(sizeof(PetscReal),&amsopt->data);
772: *(PetscReal*)amsopt->data = defaultv;
773: }
774: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
775: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
776: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
777: }
778: return(0);
779: }
783: /*@C
784: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
786: Logically Collective on the communicator passed in PetscOptionsBegin()
788: Input Parameters:
789: + opt - option name
790: . text - short string that describes the option
791: . man - manual page with additional information on option
792: - defaultv - the default (current) value
794: Output Parameter:
795: + value - the value to return
796: - flg - PETSC_TRUE if found, else PETSC_FALSE
798: Level: beginner
800: Concepts: options database^has int
802: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
804: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
805: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
806: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
807: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
808: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
809: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
810: PetscOptionsList(), PetscOptionsEList()
811: @*/
812: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool *set)
813: {
817: #if !defined(PETSC_USE_COMPLEX)
818: PetscOptionsReal(opt,text,man,defaultv,value,set);
819: #else
820: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
821: #endif
822: return(0);
823: }
827: /*@C
828: 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
829: its value is set to false.
831: Logically Collective on the communicator passed in PetscOptionsBegin()
833: Input Parameters:
834: + opt - option name
835: . text - short string that describes the option
836: - man - manual page with additional information on option
838: Output Parameter:
839: . flg - PETSC_TRUE if found, else PETSC_FALSE
841: Level: beginner
843: Concepts: options database^has int
845: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
847: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
848: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
849: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
850: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
851: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
852: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
853: PetscOptionsList(), PetscOptionsEList()
854: @*/
855: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
856: {
858: PetscOptions amsopt;
861: if (!PetscOptionsPublishCount) {
862: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
863: PetscMalloc(sizeof(PetscBool),&amsopt->data);
864: *(PetscBool*)amsopt->data = PETSC_FALSE;
865: }
866: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
867: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
868: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
869: }
870: return(0);
871: }
875: /*@C
876: PetscOptionsList - Puts a list of option values that a single one may be selected from
878: Logically Collective on the communicator passed in PetscOptionsBegin()
880: Input Parameters:
881: + opt - option name
882: . text - short string that describes the option
883: . man - manual page with additional information on option
884: . list - the possible choices
885: . defaultv - the default (current) value
886: - len - the length of the character array value
888: Output Parameter:
889: + value - the value to return
890: - set - PETSC_TRUE if found, else PETSC_FALSE
892: Level: intermediate
893:
894: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
896: See PetscOptionsEList() for when the choices are given in a string array
898: To get a listing of all currently specified options,
899: see PetscOptionsView() or PetscOptionsGetAll()
901: Concepts: options database^list
903: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
904: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
905: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
906: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
907: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
908: PetscOptionsList(), PetscOptionsEList()
909: @*/
910: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],size_t len,PetscBool *set)
911: {
913: PetscOptions amsopt;
916: if (!PetscOptionsPublishCount) {
917: PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
918: PetscMalloc(sizeof(char*),&amsopt->data);
919: *(const char**)amsopt->data = defaultv;
920: amsopt->flist = list;
921: }
922: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
923: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
924: PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
925: }
926: return(0);
927: }
931: /*@C
932: PetscOptionsEList - Puts a list of option values that a single one may be selected from
934: Logically Collective on the communicator passed in PetscOptionsBegin()
936: Input Parameters:
937: + opt - option name
938: . ltext - short string that describes the option
939: . man - manual page with additional information on option
940: . list - the possible choices
941: . ntext - number of choices
942: - defaultv - the default (current) value
944: Output Parameter:
945: + value - the index of the value to return
946: - set - PETSC_TRUE if found, else PETSC_FALSE
947:
948: Level: intermediate
950: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
952: See PetscOptionsList() for when the choices are given in a PetscFList()
954: Concepts: options database^list
956: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
957: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
958: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
959: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
960: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
961: PetscOptionsList(), PetscOptionsEList()
962: @*/
963: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const*list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool *set)
964: {
966: PetscInt i;
967: PetscOptions amsopt;
970: if (!PetscOptionsPublishCount) {
971: PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
972: PetscMalloc(sizeof(char*),&amsopt->data);
973: *(const char**)amsopt->data = defaultv;
974: amsopt->list = list;
975: amsopt->nlist = ntext;
976: }
977: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
978: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
979: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
980: for (i=0; i<ntext; i++){
981: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
982: }
983: (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
984: }
985: return(0);
986: }
990: /*@C
991: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
992: which at most a single value can be true.
994: Logically Collective on the communicator passed in PetscOptionsBegin()
996: Input Parameters:
997: + opt - option name
998: . text - short string that describes the option
999: - man - manual page with additional information on option
1001: Output Parameter:
1002: . flg - whether that option was set or not
1003:
1004: Level: intermediate
1006: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1008: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1010: Concepts: options database^logical group
1012: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1013: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1014: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1015: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1016: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1017: PetscOptionsList(), PetscOptionsEList()
1018: @*/
1019: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1020: {
1022: PetscOptions amsopt;
1025: if (!PetscOptionsPublishCount) {
1026: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1027: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1028: *(PetscBool*)amsopt->data = PETSC_FALSE;
1029: }
1030: *flg = PETSC_FALSE;
1031: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1032: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1033: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
1034: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1035: }
1036: return(0);
1037: }
1041: /*@C
1042: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1043: which at most a single value can be true.
1045: Logically Collective on the communicator passed in PetscOptionsBegin()
1047: Input Parameters:
1048: + opt - option name
1049: . text - short string that describes the option
1050: - man - manual page with additional information on option
1052: Output Parameter:
1053: . flg - PETSC_TRUE if found, else PETSC_FALSE
1054:
1055: Level: intermediate
1057: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1059: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1061: Concepts: options database^logical group
1063: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1064: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1065: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1066: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1067: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1068: PetscOptionsList(), PetscOptionsEList()
1069: @*/
1070: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1071: {
1073: PetscOptions amsopt;
1076: if (!PetscOptionsPublishCount) {
1077: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1078: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1079: *(PetscBool*)amsopt->data = PETSC_FALSE;
1080: }
1081: *flg = PETSC_FALSE;
1082: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1083: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1084: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1085: }
1086: return(0);
1087: }
1091: /*@C
1092: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1093: which at most a single value can be true.
1095: Logically Collective on the communicator passed in PetscOptionsBegin()
1097: Input Parameters:
1098: + opt - option name
1099: . text - short string that describes the option
1100: - man - manual page with additional information on option
1102: Output Parameter:
1103: . flg - PETSC_TRUE if found, else PETSC_FALSE
1104:
1105: Level: intermediate
1107: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1109: Must follow a PetscOptionsBoolGroupBegin()
1111: Concepts: options database^logical group
1113: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1114: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1115: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1116: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1117: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1118: PetscOptionsList(), PetscOptionsEList()
1119: @*/
1120: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1121: {
1123: PetscOptions amsopt;
1126: if (!PetscOptionsPublishCount) {
1127: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1128: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1129: *(PetscBool*)amsopt->data = PETSC_FALSE;
1130: }
1131: *flg = PETSC_FALSE;
1132: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1133: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1134: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1135: }
1136: return(0);
1137: }
1141: /*@C
1142: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1144: Logically Collective on the communicator passed in PetscOptionsBegin()
1146: Input Parameters:
1147: + opt - option name
1148: . text - short string that describes the option
1149: - man - manual page with additional information on option
1151: Output Parameter:
1152: . flg - PETSC_TRUE or PETSC_FALSE
1153: . set - PETSC_TRUE if found, else PETSC_FALSE
1155: Level: beginner
1157: Concepts: options database^logical
1159: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1161: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1162: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1163: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1164: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1165: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1166: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1167: PetscOptionsList(), PetscOptionsEList()
1168: @*/
1169: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool *flg,PetscBool *set)
1170: {
1172: PetscBool iset;
1173: PetscOptions amsopt;
1176: if (!PetscOptionsPublishCount) {
1177: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1178: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1179: *(PetscBool*)amsopt->data = deflt;
1180: }
1181: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1182: if (!iset) {
1183: if (flg) *flg = deflt;
1184: }
1185: if (set) *set = iset;
1186: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1187: const char *v = PetscBools[deflt];
1188: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1189: }
1190: return(0);
1191: }
1195: /*@C
1196: PetscOptionsRealArray - Gets an array of double values for a particular
1197: option in the database. The values must be separated with commas with
1198: no intervening spaces.
1200: Logically Collective on the communicator passed in PetscOptionsBegin()
1202: Input Parameters:
1203: + opt - the option one is seeking
1204: . text - short string describing option
1205: . man - manual page for option
1206: - nmax - maximum number of values
1208: Output Parameter:
1209: + value - location to copy values
1210: . nmax - actual number of values found
1211: - set - PETSC_TRUE if found, else PETSC_FALSE
1213: Level: beginner
1215: Notes:
1216: The user should pass in an array of doubles
1218: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1220: Concepts: options database^array of strings
1222: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1223: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1224: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1225: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1226: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1227: PetscOptionsList(), PetscOptionsEList()
1228: @*/
1229: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1230: {
1232: PetscInt i;
1233: PetscOptions amsopt;
1236: if (!PetscOptionsPublishCount) {
1237: PetscReal *vals;
1239: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1240: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1241: vals = (PetscReal*)amsopt->data;
1242: for (i=0; i<*n; i++) vals[i] = value[i];
1243: amsopt->arraylength = *n;
1244: }
1245: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1246: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1247: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1248: for (i=1; i<*n; i++) {
1249: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1250: }
1251: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1252: }
1253: return(0);
1254: }
1259: /*@C
1260: PetscOptionsIntArray - Gets an array of integers for a particular
1261: option in the database. The values must be separated with commas with
1262: no intervening spaces.
1264: Logically Collective on the communicator passed in PetscOptionsBegin()
1266: Input Parameters:
1267: + opt - the option one is seeking
1268: . text - short string describing option
1269: . man - manual page for option
1270: - n - maximum number of values
1272: Output Parameter:
1273: + value - location to copy values
1274: . n - actual number of values found
1275: - set - PETSC_TRUE if found, else PETSC_FALSE
1277: Level: beginner
1279: Notes:
1280: The user should pass in an array of integers
1282: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1284: Concepts: options database^array of strings
1286: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1287: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1288: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1289: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1290: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1291: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1292: @*/
1293: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1294: {
1296: PetscInt i;
1297: PetscOptions amsopt;
1300: if (!PetscOptionsPublishCount) {
1301: PetscInt *vals;
1303: PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1304: PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1305: vals = (PetscInt*)amsopt->data;
1306: for (i=0; i<*n; i++) vals[i] = value[i];
1307: amsopt->arraylength = *n;
1308: }
1309: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1310: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1311: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1312: for (i=1; i<*n; i++) {
1313: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1314: }
1315: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1316: }
1317: return(0);
1318: }
1322: /*@C
1323: PetscOptionsStringArray - Gets an array of string values for a particular
1324: option in the database. The values must be separated with commas with
1325: no intervening spaces.
1327: Logically Collective on the communicator passed in PetscOptionsBegin()
1329: Input Parameters:
1330: + opt - the option one is seeking
1331: . text - short string describing option
1332: . man - manual page for option
1333: - nmax - maximum number of strings
1335: Output Parameter:
1336: + value - location to copy strings
1337: . nmax - actual number of strings found
1338: - set - PETSC_TRUE if found, else PETSC_FALSE
1340: Level: beginner
1342: Notes:
1343: The user should pass in an array of pointers to char, to hold all the
1344: strings returned by this function.
1346: The user is responsible for deallocating the strings that are
1347: returned. The Fortran interface for this routine is not supported.
1349: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1351: Concepts: options database^array of strings
1353: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1354: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1355: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1356: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1357: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1358: PetscOptionsList(), PetscOptionsEList()
1359: @*/
1360: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1361: {
1363: PetscOptions amsopt;
1366: if (!PetscOptionsPublishCount) {
1367: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1368: PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1369: amsopt->arraylength = *nmax;
1370: }
1371: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1372: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1373: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1374: }
1375: return(0);
1376: }
1380: /*@C
1381: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1382: option in the database. The values must be separated with commas with
1383: no intervening spaces.
1385: Logically Collective on the communicator passed in PetscOptionsBegin()
1387: Input Parameters:
1388: + opt - the option one is seeking
1389: . text - short string describing option
1390: . man - manual page for option
1391: - nmax - maximum number of values
1393: Output Parameter:
1394: + value - location to copy values
1395: . nmax - actual number of values found
1396: - set - PETSC_TRUE if found, else PETSC_FALSE
1398: Level: beginner
1400: Notes:
1401: The user should pass in an array of doubles
1403: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1405: Concepts: options database^array of strings
1407: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1408: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1409: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1410: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1411: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1412: PetscOptionsList(), PetscOptionsEList()
1413: @*/
1414: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1415: {
1417: PetscInt i;
1418: PetscOptions amsopt;
1421: if (!PetscOptionsPublishCount) {
1422: PetscBool *vals;
1424: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
1425: PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
1426: vals = (PetscBool*)amsopt->data;
1427: for (i=0; i<*n; i++) vals[i] = value[i];
1428: amsopt->arraylength = *n;
1429: }
1430: PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1431: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1432: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1433: for (i=1; i<*n; i++) {
1434: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1435: }
1436: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1437: }
1438: return(0);
1439: }
1444: /*@C
1445: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1446: in KSPSetFromOptions_GMRES().
1448: Logically Collective on the communicator passed in PetscOptionsBegin()
1450: Input Parameter:
1451: . head - the heading text
1453:
1454: Level: intermediate
1456: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1458: Can be followed by a call to PetscOptionsTail() in the same function.
1460: Concepts: options database^subheading
1462: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1463: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1464: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1465: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1466: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1467: PetscOptionsList(), PetscOptionsEList()
1468: @*/
1469: PetscErrorCode PetscOptionsHead(const char head[])
1470: {
1474: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1475: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1476: }
1477: return(0);
1478: }