Actual source code: aoptions.c
petsc-3.4.5 2014-06-29
2: /*
3: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
4: GUI code to display the options and get values from the users.
6: */
8: #include <petsc-private/petscimpl.h> /*I "petscsys.h" I*/
9: #include <petscviewer.h>
11: #define ManSection(str) ((str) ? (str) : "None")
13: /*
14: Keep a linked list of options that have been posted and we are waiting for
15: user selection. See the manual page for PetscOptionsBegin()
17: Eventually we'll attach this beast to a MPI_Comm
18: */
19: PetscOptionsObjectType PetscOptionsObject;
20: PetscInt PetscOptionsPublishCount = 0;
24: /*
25: Handles setting up the data structure in a call to PetscOptionsBegin()
26: */
27: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
28: {
32: PetscOptionsObject.next = 0;
33: PetscOptionsObject.comm = comm;
34: PetscOptionsObject.changedmethod = PETSC_FALSE;
36: PetscFree(PetscOptionsObject.prefix);
37: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
38: PetscFree(PetscOptionsObject.title);
39: PetscStrallocpy(title,&PetscOptionsObject.title);
41: PetscOptionsHasName(NULL,"-help",&PetscOptionsObject.printhelp);
42: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
43: if (!PetscOptionsObject.alreadyprinted) {
44: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
45: }
46: }
47: return(0);
48: }
52: /*
53: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
54: */
55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
56: {
58: char title[256];
59: PetscBool flg;
63: PetscOptionsObject.object = obj;
64: PetscOptionsObject.alreadyprinted = obj->optionsprinted;
66: PetscStrcmp(obj->description,obj->class_name,&flg);
67: if (flg) {
68: PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
69: } else {
70: PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
71: }
72: PetscOptionsBegin_Private(obj->comm,obj->prefix,title,obj->mansec);
73: return(0);
74: }
76: /*
77: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
78: */
81: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
82: {
83: int ierr;
84: PetscOptions next;
85: PetscBool valid;
88: PetscOptionsValidKey(opt,&valid);
89: if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);
91: PetscNew(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) PetscOptionsObject.next = *amsopt;
102: else {
103: next = PetscOptionsObject.next;
104: while (next->next) next = next->next;
105: next->next = *amsopt;
106: }
107: return(0);
108: }
112: /*
113: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
115: Collective on MPI_Comm
117: Input Parameters:
118: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
119: . n - length of the string, must be the same on all processes
120: - str - location to store input
122: Bugs:
123: . Assumes process 0 of the given communicator has access to stdin
125: */
126: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
127: {
128: size_t i;
129: char c;
130: PetscMPIInt rank,nm;
134: MPI_Comm_rank(comm,&rank);
135: if (!rank) {
136: c = (char) getchar();
137: i = 0;
138: while (c != '\n' && i < n-1) {
139: str[i++] = c;
140: c = (char)getchar();
141: }
142: str[i] = 0;
143: }
144: PetscMPIIntCast(n,&nm);
145: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
146: return(0);
147: }
151: /*
152: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
154: Notes: this isn't really practical, it is just to demonstrate the principle
156: Bugs:
157: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
158: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
159: - Only works for PetscInt == int, PetscReal == double etc
161: Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different
162: address space and communicating with the PETSc program
164: */
165: PetscErrorCode PetscOptionsGetFromTextInput()
166: {
168: PetscOptions next = PetscOptionsObject.next;
169: char str[512];
170: PetscInt id;
171: PetscReal ir,*valr;
172: PetscInt *vald;
173: size_t i;
175: (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
176: while (next) {
177: switch (next->type) {
178: case OPTION_HEAD:
179: break;
180: case OPTION_INT_ARRAY:
181: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
182: vald = (PetscInt*) next->data;
183: for (i=0; i<next->arraylength; i++) {
184: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
185: if (i < next->arraylength-1) {
186: PetscPrintf(PETSC_COMM_WORLD,",");
187: }
188: }
189: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
190: PetscScanString(PETSC_COMM_WORLD,512,str);
191: if (str[0]) {
192: PetscToken token;
193: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
194: size_t len;
195: char *value;
196: PetscBool foundrange;
198: next->set = PETSC_TRUE;
199: value = str;
200: PetscTokenCreate(value,',',&token);
201: PetscTokenFind(token,&value);
202: while (n < nmax) {
203: if (!value) break;
205: /* look for form d-D where d and D are integers */
206: foundrange = PETSC_FALSE;
207: PetscStrlen(value,&len);
208: if (value[0] == '-') i=2;
209: else i=1;
210: for (;i<len; i++) {
211: if (value[i] == '-') {
212: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
213: value[i] = 0;
214: PetscOptionsStringToInt(value,&start);
215: PetscOptionsStringToInt(value+i+1,&end);
216: 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);
217: 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);
218: for (; start<end; start++) {
219: *dvalue = start; dvalue++;n++;
220: }
221: foundrange = PETSC_TRUE;
222: break;
223: }
224: }
225: if (!foundrange) {
226: PetscOptionsStringToInt(value,dvalue);
227: dvalue++;
228: n++;
229: }
230: PetscTokenFind(token,&value);
231: }
232: PetscTokenDestroy(&token);
233: }
234: break;
235: case OPTION_REAL_ARRAY:
236: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
237: valr = (PetscReal*) next->data;
238: for (i=0; i<next->arraylength; i++) {
239: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
240: if (i < next->arraylength-1) {
241: PetscPrintf(PETSC_COMM_WORLD,",");
242: }
243: }
244: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
245: PetscScanString(PETSC_COMM_WORLD,512,str);
246: if (str[0]) {
247: PetscToken token;
248: PetscInt n = 0,nmax = next->arraylength;
249: PetscReal *dvalue = (PetscReal*)next->data;
250: char *value;
252: next->set = PETSC_TRUE;
253: value = str;
254: PetscTokenCreate(value,',',&token);
255: PetscTokenFind(token,&value);
256: while (n < nmax) {
257: if (!value) break;
258: PetscOptionsStringToReal(value,dvalue);
259: dvalue++;
260: n++;
261: PetscTokenFind(token,&value);
262: }
263: PetscTokenDestroy(&token);
264: }
265: break;
266: case OPTION_INT:
267: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
268: PetscScanString(PETSC_COMM_WORLD,512,str);
269: if (str[0]) {
270: #if defined(PETSC_USE_64BIT_INDICES)
271: sscanf(str,"%lld",&id);
272: #else
273: sscanf(str,"%d",&id);
274: #endif
275: 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;
304: PetscStrcpy((char*)next->data,str);
305: }
306: break;
307: case OPTION_LIST:
308: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
309: PetscScanString(PETSC_COMM_WORLD,512,str);
310: if (str[0]) {
311: PetscOptionsObject.changedmethod = PETSC_TRUE;
312: next->set = PETSC_TRUE;
313: PetscStrcpy((char*)next->data,str);
314: }
315: break;
316: default:
317: break;
318: }
319: next = next->next;
320: }
321: return(0);
322: }
324: #if defined(PETSC_HAVE_AMS)
325: #include <petscviewerams.h>
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: PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
343: PetscStackCallAMS(AMS_Memory_add_field,(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));
345: PetscStackCallAMS(AMS_Memory_take_access,(amem));
346: PetscStackCallAMS(AMS_Memory_publish,(amem));
347: PetscStackCallAMS(AMS_Memory_grant_access,(amem));
348: /* wait until accessor has unlocked the memory */
349: PetscStackCallAMS(AMS_Memory_lock,(amem,0));
350: PetscStackCallAMS(AMS_Memory_take_access,(amem));
351: PetscStackCallAMS(AMS_Memory_grant_access,(amem));
352: PetscStackCallAMS(AMS_Memory_destroy,(amem));
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: PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
383: PetscStackCallAMS(AMS_Memory_take_access,(amem));
385: PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* AMS will change this, so cannot pass prefix directly */
387: PetscStackCallAMS(AMS_Memory_add_field,(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));
388: /* PetscStackCallAMS(AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF)); */
389: PetscStackCallAMS(AMS_Memory_add_field,(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
391: while (next) {
392: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
393: PetscMalloc(sizeof(char*),&next->pman);
395: *(char**)next->pman = next->man;
396: sprintf(manname,"man_%d",mancount++);
397: PetscStackCallAMS(AMS_Memory_add_field,(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));
399: switch (next->type) {
400: case OPTION_HEAD:
401: break;
402: case OPTION_INT_ARRAY:
403: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
404: break;
405: case OPTION_REAL_ARRAY:
406: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
407: break;
408: case OPTION_INT:
409: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
410: break;
411: case OPTION_REAL:
412: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
413: break;
414: case OPTION_LOGICAL:
415: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
416: break;
417: case OPTION_LOGICAL_ARRAY:
418: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
419: break;
420: case OPTION_STRING:
421: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
422: break;
423: case OPTION_STRING_ARRAY:
424: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
425: break;
426: case OPTION_LIST:
427: {PetscInt ntext;
428: char ldefault[128];
429: PetscStrcpy(ldefault,"DEFAULT:");
430: PetscStrcat(ldefault,next->text);
431: PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
432: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
433: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
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: PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
441: PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
442: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
443: PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
444: break;}
445: default:
446: break;
447: }
448: next = next->next;
449: }
451: PetscStackCallAMS(AMS_Memory_publish,(amem));
452: PetscStackCallAMS(AMS_Memory_grant_access,(amem));
453: /* wait until accessor has unlocked the memory */
454: PetscStackCallAMS(AMS_Memory_lock,(amem,0));
455: PetscStackCallAMS(AMS_Memory_take_access,(amem));
457: /* reset counter to -2; this updates the screen with the new options for the selected method */
458: if (changedmethod) PetscOptionsPublishCount = -2;
460: PetscStackCallAMS(AMS_Memory_grant_access,(amem));
461: PetscStackCallAMS(AMS_Memory_destroy,(amem));
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;
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 = 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);
565: last = PetscOptionsObject.next;
566: PetscOptionsObject.next = PetscOptionsObject.next->next;
567: PetscFree(last);
568: }
569: PetscOptionsObject.next = 0;
570: return(0);
571: }
575: /*@C
576: PetscOptionsEnum - Gets the enum value for a particular option in the database.
578: Logically Collective on the communicator passed in PetscOptionsBegin()
580: Input Parameters:
581: + opt - option name
582: . text - short string that describes the option
583: . man - manual page with additional information on option
584: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
585: - defaultv - the default (current) value
587: Output Parameter:
588: + value - the value to return
589: - set - PETSC_TRUE if found, else PETSC_FALSE
591: Level: beginner
593: Concepts: options database
595: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
597: list is usually something like PCASMTypes or some other predefined list of enum names
599: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
600: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
601: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
602: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
603: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
604: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
605: PetscOptionsList(), PetscOptionsEList()
606: @*/
607: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool *set)
608: {
610: PetscInt ntext = 0;
611: PetscInt tval;
612: PetscBool tflg;
615: while (list[ntext++]) {
616: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
617: }
618: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
619: ntext -= 3;
620: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
621: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
622: if (tflg) *value = (PetscEnum)tval;
623: if (set) *set = tflg;
624: return(0);
625: }
627: /* -------------------------------------------------------------------------------------------------------------*/
630: /*@C
631: PetscOptionsInt - Gets the integer value for a particular option in the database.
633: Logically Collective on the communicator passed in PetscOptionsBegin()
635: Input Parameters:
636: + opt - option name
637: . text - short string that describes the option
638: . man - manual page with additional information on option
639: - defaultv - the default (current) value
641: Output Parameter:
642: + value - the integer value to return
643: - flg - PETSC_TRUE if found, else PETSC_FALSE
645: Level: beginner
647: Concepts: options database^has int
649: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
651: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
652: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
653: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
654: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
655: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
656: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
657: PetscOptionsList(), PetscOptionsEList()
658: @*/
659: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool *set)
660: {
662: PetscOptions amsopt;
665: if (!PetscOptionsPublishCount) {
666: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
667: 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);
722: *(const char**)amsopt->data = defaultv;
723: }
724: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
725: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
726: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
727: }
728: return(0);
729: }
733: /*@C
734: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
736: Logically Collective on the communicator passed in PetscOptionsBegin()
738: Input Parameters:
739: + opt - option name
740: . text - short string that describes the option
741: . man - manual page with additional information on option
742: - defaultv - the default (current) value
744: Output Parameter:
745: + value - the value to return
746: - flg - PETSC_TRUE if found, else PETSC_FALSE
748: Level: beginner
750: Concepts: options database^has int
752: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
754: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
755: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
756: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
757: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
758: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
759: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
760: PetscOptionsList(), PetscOptionsEList()
761: @*/
762: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool *set)
763: {
765: PetscOptions amsopt;
768: if (!PetscOptionsPublishCount) {
769: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
770: 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);
865: *(PetscBool*)amsopt->data = PETSC_FALSE;
866: }
867: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
868: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
869: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
870: }
871: return(0);
872: }
876: /*@C
877: PetscOptionsList - Puts a list of option values that a single one may be selected from
879: Logically Collective on the communicator passed in PetscOptionsBegin()
881: Input Parameters:
882: + opt - option name
883: . text - short string that describes the option
884: . man - manual page with additional information on option
885: . list - the possible choices
886: . defaultv - the default (current) value
887: - len - the length of the character array value
889: Output Parameter:
890: + value - the value to return
891: - set - PETSC_TRUE if found, else PETSC_FALSE
893: Level: intermediate
895: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
897: See PetscOptionsEList() for when the choices are given in a string array
899: To get a listing of all currently specified options,
900: see PetscOptionsView() or PetscOptionsGetAll()
902: Concepts: options database^list
904: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
905: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
906: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
907: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
908: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
909: PetscOptionsList(), PetscOptionsEList(), PetscOptionsEnum()
910: @*/
911: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool *set)
912: {
914: PetscOptions amsopt;
917: if (!PetscOptionsPublishCount) {
918: PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
919: PetscMalloc(sizeof(char*),&amsopt->data);
921: *(const char**)amsopt->data = defaultv;
923: amsopt->flist = list;
924: }
925: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
926: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
927: PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
928: }
929: return(0);
930: }
934: /*@C
935: PetscOptionsEList - Puts a list of option values that a single one may be selected from
937: Logically Collective on the communicator passed in PetscOptionsBegin()
939: Input Parameters:
940: + opt - option name
941: . ltext - short string that describes the option
942: . man - manual page with additional information on option
943: . list - the possible choices
944: . ntext - number of choices
945: - defaultv - the default (current) value
947: Output Parameter:
948: + value - the index of the value to return
949: - set - PETSC_TRUE if found, else PETSC_FALSE
951: Level: intermediate
953: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
955: See PetscOptionsList() for when the choices are given in a PetscFunctionList()
957: Concepts: options database^list
959: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
960: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
961: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
962: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
963: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
964: PetscOptionsList(), PetscOptionsEnum()
965: @*/
966: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool *set)
967: {
969: PetscInt i;
970: PetscOptions amsopt;
973: if (!PetscOptionsPublishCount) {
974: PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
975: PetscMalloc(sizeof(char*),&amsopt->data);
977: *(const char**)amsopt->data = defaultv;
979: amsopt->list = list;
980: amsopt->nlist = ntext;
981: }
982: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
983: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
984: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
985: for (i=0; i<ntext; i++) {
986: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
987: }
988: (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
989: }
990: return(0);
991: }
995: /*@C
996: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
997: which at most a single value can be true.
999: Logically Collective on the communicator passed in PetscOptionsBegin()
1001: Input Parameters:
1002: + opt - option name
1003: . text - short string that describes the option
1004: - man - manual page with additional information on option
1006: Output Parameter:
1007: . flg - whether that option was set or not
1009: Level: intermediate
1011: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1013: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1015: Concepts: options database^logical group
1017: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1018: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1019: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1020: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1021: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1022: PetscOptionsList(), PetscOptionsEList()
1023: @*/
1024: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1025: {
1027: PetscOptions amsopt;
1030: if (!PetscOptionsPublishCount) {
1031: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1032: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1034: *(PetscBool*)amsopt->data = PETSC_FALSE;
1035: }
1036: *flg = PETSC_FALSE;
1037: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1038: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1039: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
1040: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1041: }
1042: return(0);
1043: }
1047: /*@C
1048: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1049: which at most a single value can be true.
1051: Logically Collective on the communicator passed in PetscOptionsBegin()
1053: Input Parameters:
1054: + opt - option name
1055: . text - short string that describes the option
1056: - man - manual page with additional information on option
1058: Output Parameter:
1059: . flg - PETSC_TRUE if found, else PETSC_FALSE
1061: Level: intermediate
1063: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1065: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1067: Concepts: options database^logical group
1069: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1070: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1071: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1072: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1073: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1074: PetscOptionsList(), PetscOptionsEList()
1075: @*/
1076: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1077: {
1079: PetscOptions amsopt;
1082: if (!PetscOptionsPublishCount) {
1083: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1084: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1086: *(PetscBool*)amsopt->data = PETSC_FALSE;
1087: }
1088: *flg = PETSC_FALSE;
1089: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1090: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1091: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1092: }
1093: return(0);
1094: }
1098: /*@C
1099: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1100: which at most a single value can be true.
1102: Logically Collective on the communicator passed in PetscOptionsBegin()
1104: Input Parameters:
1105: + opt - option name
1106: . text - short string that describes the option
1107: - man - manual page with additional information on option
1109: Output Parameter:
1110: . flg - PETSC_TRUE if found, else PETSC_FALSE
1112: Level: intermediate
1114: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1116: Must follow a PetscOptionsBoolGroupBegin()
1118: Concepts: options database^logical group
1120: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1121: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1122: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1123: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1124: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1125: PetscOptionsList(), PetscOptionsEList()
1126: @*/
1127: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1128: {
1130: PetscOptions amsopt;
1133: if (!PetscOptionsPublishCount) {
1134: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1135: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1137: *(PetscBool*)amsopt->data = PETSC_FALSE;
1138: }
1139: *flg = PETSC_FALSE;
1140: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1141: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1142: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1143: }
1144: return(0);
1145: }
1149: /*@C
1150: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1152: Logically Collective on the communicator passed in PetscOptionsBegin()
1154: Input Parameters:
1155: + opt - option name
1156: . text - short string that describes the option
1157: - man - manual page with additional information on option
1159: Output Parameter:
1160: . flg - PETSC_TRUE or PETSC_FALSE
1161: . set - PETSC_TRUE if found, else PETSC_FALSE
1163: Level: beginner
1165: Concepts: options database^logical
1167: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1169: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1170: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1171: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1172: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1173: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1174: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1175: PetscOptionsList(), PetscOptionsEList()
1176: @*/
1177: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool *flg,PetscBool *set)
1178: {
1180: PetscBool iset;
1181: PetscOptions amsopt;
1184: if (!PetscOptionsPublishCount) {
1185: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1186: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1188: *(PetscBool*)amsopt->data = deflt;
1189: }
1190: PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1191: if (!iset) {
1192: if (flg) *flg = deflt;
1193: }
1194: if (set) *set = iset;
1195: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1196: const char *v = PetscBools[deflt];
1197: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1198: }
1199: return(0);
1200: }
1204: /*@C
1205: PetscOptionsRealArray - Gets an array of double values for a particular
1206: option in the database. The values must be separated with commas with
1207: no intervening spaces.
1209: Logically Collective on the communicator passed in PetscOptionsBegin()
1211: Input Parameters:
1212: + opt - the option one is seeking
1213: . text - short string describing option
1214: . man - manual page for option
1215: - nmax - maximum number of values
1217: Output Parameter:
1218: + value - location to copy values
1219: . nmax - actual number of values found
1220: - set - PETSC_TRUE if found, else PETSC_FALSE
1222: Level: beginner
1224: Notes:
1225: The user should pass in an array of doubles
1227: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1229: Concepts: options database^array of strings
1231: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1232: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1233: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1234: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1235: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1236: PetscOptionsList(), PetscOptionsEList()
1237: @*/
1238: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1239: {
1241: PetscInt i;
1242: PetscOptions amsopt;
1245: if (!PetscOptionsPublishCount) {
1246: PetscReal *vals;
1248: PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1249: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1250: vals = (PetscReal*)amsopt->data;
1251: for (i=0; i<*n; i++) vals[i] = value[i];
1252: amsopt->arraylength = *n;
1253: }
1254: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1255: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1256: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1257: for (i=1; i<*n; i++) {
1258: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1259: }
1260: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1261: }
1262: return(0);
1263: }
1268: /*@C
1269: PetscOptionsIntArray - Gets an array of integers for a particular
1270: option in the database.
1272: Logically Collective on the communicator passed in PetscOptionsBegin()
1274: Input Parameters:
1275: + opt - the option one is seeking
1276: . text - short string describing option
1277: . man - manual page for option
1278: - n - maximum number of values
1280: Output Parameter:
1281: + value - location to copy values
1282: . n - actual number of values found
1283: - set - PETSC_TRUE if found, else PETSC_FALSE
1285: Level: beginner
1287: Notes:
1288: The array can be passed as
1289: a comma seperated list: 0,1,2,3,4,5,6,7
1290: a range (start-end+1): 0-8
1291: a range with given increment (start-end+1:inc): 0-7:2
1292: a combination of values and ranges seperated by commas: 0,1-8,8-15:2
1294: There must be no intervening spaces between the values.
1296: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1298: Concepts: options database^array of ints
1300: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1301: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1302: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1303: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1304: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1305: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1306: @*/
1307: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1308: {
1310: PetscInt i;
1311: PetscOptions amsopt;
1314: if (!PetscOptionsPublishCount) {
1315: PetscInt *vals;
1317: PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1318: PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1319: vals = (PetscInt*)amsopt->data;
1320: for (i=0; i<*n; i++) vals[i] = value[i];
1321: amsopt->arraylength = *n;
1322: }
1323: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1324: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1325: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1326: for (i=1; i<*n; i++) {
1327: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1328: }
1329: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1330: }
1331: return(0);
1332: }
1336: /*@C
1337: PetscOptionsStringArray - Gets an array of string values for a particular
1338: option in the database. The values must be separated with commas with
1339: no intervening spaces.
1341: Logically Collective on the communicator passed in PetscOptionsBegin()
1343: Input Parameters:
1344: + opt - the option one is seeking
1345: . text - short string describing option
1346: . man - manual page for option
1347: - nmax - maximum number of strings
1349: Output Parameter:
1350: + value - location to copy strings
1351: . nmax - actual number of strings found
1352: - set - PETSC_TRUE if found, else PETSC_FALSE
1354: Level: beginner
1356: Notes:
1357: The user should pass in an array of pointers to char, to hold all the
1358: strings returned by this function.
1360: The user is responsible for deallocating the strings that are
1361: returned. The Fortran interface for this routine is not supported.
1363: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1365: Concepts: options database^array of strings
1367: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1368: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1369: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1370: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1371: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1372: PetscOptionsList(), PetscOptionsEList()
1373: @*/
1374: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1375: {
1377: PetscOptions amsopt;
1380: if (!PetscOptionsPublishCount) {
1381: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1382: PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1384: amsopt->arraylength = *nmax;
1385: }
1386: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1387: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1388: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1389: }
1390: return(0);
1391: }
1395: /*@C
1396: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1397: option in the database. The values must be separated with commas with
1398: no intervening spaces.
1400: Logically Collective on the communicator passed in PetscOptionsBegin()
1402: Input Parameters:
1403: + opt - the option one is seeking
1404: . text - short string describing option
1405: . man - manual page for option
1406: - nmax - maximum number of values
1408: Output Parameter:
1409: + value - location to copy values
1410: . nmax - actual number of values found
1411: - set - PETSC_TRUE if found, else PETSC_FALSE
1413: Level: beginner
1415: Notes:
1416: The user should pass in an array of doubles
1418: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1420: Concepts: options database^array of strings
1422: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1423: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1424: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1425: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1426: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1427: PetscOptionsList(), PetscOptionsEList()
1428: @*/
1429: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1430: {
1432: PetscInt i;
1433: PetscOptions amsopt;
1436: if (!PetscOptionsPublishCount) {
1437: PetscBool *vals;
1439: PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
1440: PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
1441: vals = (PetscBool*)amsopt->data;
1442: for (i=0; i<*n; i++) vals[i] = value[i];
1443: amsopt->arraylength = *n;
1444: }
1445: PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1446: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1447: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1448: for (i=1; i<*n; i++) {
1449: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1450: }
1451: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1452: }
1453: return(0);
1454: }
1458: /*@C
1459: PetscOptionsInt - Gets a viewer appropriate for the type indicated by the user
1461: Logically Collective on the communicator passed in PetscOptionsBegin()
1463: Input Parameters:
1464: + opt - option name
1465: . text - short string that describes the option
1466: - man - manual page with additional information on option
1468: Output Parameter:
1469: + viewer - the viewer
1470: - set - PETSC_TRUE if found, else PETSC_FALSE
1472: Level: beginner
1474: Concepts: options database^has int
1476: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1477: If no value is provided ascii:stdout is used
1478: $ ascii[:[filename][:format]] defaults to stdout - format can be one of info, info_detailed, or matlab, for example ascii::info prints just the info
1479: $ about the object to standard out
1480: $ binary[:filename] defaults to binaryoutput
1481: $ draw
1482: $ socket[:port] defaults to the standard output port
1484: Use PetscRestoreViewerDestroy() after using the viewer, otherwise a memory leak will occur
1486: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1487: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1488: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1489: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1490: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1491: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1492: PetscOptionsList(), PetscOptionsEList()
1493: @*/
1494: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1495: {
1497: PetscOptions amsopt;
1500: if (!PetscOptionsPublishCount) {
1501: PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
1502: PetscMalloc(sizeof(PetscInt),&amsopt->data);
1504: *(const char**)amsopt->data = "";
1505: }
1506: PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
1507: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1508: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
1509: }
1510: return(0);
1511: }
1516: /*@C
1517: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1518: in KSPSetFromOptions_GMRES().
1520: Logically Collective on the communicator passed in PetscOptionsBegin()
1522: Input Parameter:
1523: . head - the heading text
1526: Level: intermediate
1528: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1530: Can be followed by a call to PetscOptionsTail() in the same function.
1532: Concepts: options database^subheading
1534: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1535: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1536: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1537: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1538: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1539: PetscOptionsList(), PetscOptionsEList()
1540: @*/
1541: PetscErrorCode PetscOptionsHead(const char head[])
1542: {
1546: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1547: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1548: }
1549: return(0);
1550: }