Actual source code: aoptions.c
1: /*
2: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
3: GUI code to display the options and get values from the users.
5: */
7: #include <petsc/private/petscimpl.h>
8: #include <petscviewer.h>
10: #define ManSection(str) ((str) ? (str) : "None")
12: /*
13: Keep a linked list of options that have been posted and we are waiting for
14: user selection. See the manual page for PetscOptionsBegin()
16: Eventually we'll attach this beast to a MPI_Comm
17: */
19: /*
20: Handles setting up the data structure in a call to PetscOptionsBegin()
21: */
22: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
23: {
30: if (!PetscOptionsObject->alreadyprinted) {
31: if (!PetscOptionsHelpPrintedSingleton) {
32: PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
33: }
34: PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
35: }
36: PetscOptionsObject->next = NULL;
37: PetscOptionsObject->comm = comm;
38: PetscOptionsObject->changedmethod = PETSC_FALSE;
40: PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
41: PetscStrallocpy(title,&PetscOptionsObject->title);
43: PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
44: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
45: if (!PetscOptionsObject->alreadyprinted) {
46: (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
47: }
48: }
49: return(0);
50: }
52: /*
53: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
54: */
55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,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(PetscOptionsObject,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: */
79: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
80: {
81: int ierr;
82: PetscOptionItem next;
83: PetscBool valid;
86: PetscOptionsValidKey(opt,&valid);
87: if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);
89: PetscNew(amsopt);
90: (*amsopt)->next = NULL;
91: (*amsopt)->set = PETSC_FALSE;
92: (*amsopt)->type = t;
93: (*amsopt)->data = NULL;
95: PetscStrallocpy(text,&(*amsopt)->text);
96: PetscStrallocpy(opt,&(*amsopt)->option);
97: PetscStrallocpy(man,&(*amsopt)->man);
99: if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
100: else {
101: next = PetscOptionsObject->next;
102: while (next->next) next = next->next;
103: next->next = *amsopt;
104: }
105: return(0);
106: }
108: /*
109: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
111: Collective
113: Input Parameters:
114: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
115: . n - length of the string, must be the same on all processes
116: - str - location to store input
118: Bugs:
119: . Assumes process 0 of the given communicator has access to stdin
121: */
122: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
123: {
124: size_t i;
125: char c;
126: PetscMPIInt rank,nm;
130: MPI_Comm_rank(comm,&rank);
131: if (rank == 0) {
132: c = (char) getchar();
133: i = 0;
134: while (c != '\n' && i < n-1) {
135: str[i++] = c;
136: c = (char)getchar();
137: }
138: str[i] = 0;
139: }
140: PetscMPIIntCast(n,&nm);
141: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
142: return(0);
143: }
145: /*
146: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
147: */
148: static PetscErrorCode PetscStrdup(const char s[],char *t[])
149: {
151: size_t len;
152: char *tmp = NULL;
155: if (s) {
156: PetscStrlen(s,&len);
157: tmp = (char*) malloc((len+1)*sizeof(char));
158: if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
159: PetscStrcpy(tmp,s);
160: }
161: *t = tmp;
162: return(0);
163: }
165: /*
166: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
168: Notes:
169: this isn't really practical, it is just to demonstrate the principle
171: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
172: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
174: Bugs:
175: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
176: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
177: - Only works for PetscInt == int, PetscReal == double etc
179: Developer Notes:
180: Normally the GUI that presents the options the user and retrieves the values would be running in a different
181: address space and communicating with the PETSc program
183: */
184: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
185: {
186: PetscErrorCode ierr;
187: PetscOptionItem next = PetscOptionsObject->next;
188: char str[512];
189: PetscBool bid;
190: PetscReal ir,*valr;
191: PetscInt *vald;
192: size_t i;
195: (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
196: while (next) {
197: switch (next->type) {
198: case OPTION_HEAD:
199: break;
200: case OPTION_INT_ARRAY:
201: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
202: vald = (PetscInt*) next->data;
203: for (i=0; i<next->arraylength; i++) {
204: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
205: if (i < next->arraylength-1) {
206: PetscPrintf(PETSC_COMM_WORLD,",");
207: }
208: }
209: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
210: PetscScanString(PETSC_COMM_WORLD,512,str);
211: if (str[0]) {
212: PetscToken token;
213: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
214: size_t len;
215: char *value;
216: PetscBool foundrange;
218: next->set = PETSC_TRUE;
219: value = str;
220: PetscTokenCreate(value,',',&token);
221: PetscTokenFind(token,&value);
222: while (n < nmax) {
223: if (!value) break;
225: /* look for form d-D where d and D are integers */
226: foundrange = PETSC_FALSE;
227: PetscStrlen(value,&len);
228: if (value[0] == '-') i=2;
229: else i=1;
230: for (;i<len; i++) {
231: if (value[i] == '-') {
232: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
233: value[i] = 0;
234: PetscOptionsStringToInt(value,&start);
235: PetscOptionsStringToInt(value+i+1,&end);
236: 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);
237: 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);
238: for (; start<end; start++) {
239: *dvalue = start; dvalue++;n++;
240: }
241: foundrange = PETSC_TRUE;
242: break;
243: }
244: }
245: if (!foundrange) {
246: PetscOptionsStringToInt(value,dvalue);
247: dvalue++;
248: n++;
249: }
250: PetscTokenFind(token,&value);
251: }
252: PetscTokenDestroy(&token);
253: }
254: break;
255: case OPTION_REAL_ARRAY:
256: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
257: valr = (PetscReal*) next->data;
258: for (i=0; i<next->arraylength; i++) {
259: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
260: if (i < next->arraylength-1) {
261: PetscPrintf(PETSC_COMM_WORLD,",");
262: }
263: }
264: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
265: PetscScanString(PETSC_COMM_WORLD,512,str);
266: if (str[0]) {
267: PetscToken token;
268: PetscInt n = 0,nmax = next->arraylength;
269: PetscReal *dvalue = (PetscReal*)next->data;
270: char *value;
272: next->set = PETSC_TRUE;
273: value = str;
274: PetscTokenCreate(value,',',&token);
275: PetscTokenFind(token,&value);
276: while (n < nmax) {
277: if (!value) break;
278: PetscOptionsStringToReal(value,dvalue);
279: dvalue++;
280: n++;
281: PetscTokenFind(token,&value);
282: }
283: PetscTokenDestroy(&token);
284: }
285: break;
286: case OPTION_INT:
287: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
288: PetscScanString(PETSC_COMM_WORLD,512,str);
289: if (str[0]) {
290: #if defined(PETSC_SIZEOF_LONG_LONG)
291: long long lid;
292: sscanf(str,"%lld",&lid);
293: if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %lld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
294: #else
295: long lid;
296: sscanf(str,"%ld",&lid);
297: if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %ld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
298: #endif
300: next->set = PETSC_TRUE;
301: *((PetscInt*)next->data) = (PetscInt)lid;
302: }
303: break;
304: case OPTION_REAL:
305: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
306: PetscScanString(PETSC_COMM_WORLD,512,str);
307: if (str[0]) {
308: #if defined(PETSC_USE_REAL_SINGLE)
309: sscanf(str,"%e",&ir);
310: #elif defined(PETSC_USE_REAL___FP16)
311: float irtemp;
312: sscanf(str,"%e",&irtemp);
313: ir = irtemp;
314: #elif defined(PETSC_USE_REAL_DOUBLE)
315: sscanf(str,"%le",&ir);
316: #elif defined(PETSC_USE_REAL___FLOAT128)
317: ir = strtoflt128(str,0);
318: #else
319: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
320: #endif
321: next->set = PETSC_TRUE;
322: *((PetscReal*)next->data) = ir;
323: }
324: break;
325: case OPTION_BOOL:
326: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(PetscBool*)next->data ? "true": "false",next->text,next->man);
327: PetscScanString(PETSC_COMM_WORLD,512,str);
328: if (str[0]) {
329: PetscOptionsStringToBool(str,&bid);
330: next->set = PETSC_TRUE;
331: *((PetscBool*)next->data) = bid;
332: }
333: break;
334: case OPTION_STRING:
335: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
336: PetscScanString(PETSC_COMM_WORLD,512,str);
337: if (str[0]) {
338: next->set = PETSC_TRUE;
339: /* must use system malloc since SAWs may free this */
340: PetscStrdup(str,(char**)&next->data);
341: }
342: break;
343: case OPTION_FLIST:
344: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
345: PetscScanString(PETSC_COMM_WORLD,512,str);
346: if (str[0]) {
347: PetscOptionsObject->changedmethod = PETSC_TRUE;
348: next->set = PETSC_TRUE;
349: /* must use system malloc since SAWs may free this */
350: PetscStrdup(str,(char**)&next->data);
351: }
352: break;
353: default:
354: break;
355: }
356: next = next->next;
357: }
358: return(0);
359: }
361: #if defined(PETSC_HAVE_SAWS)
362: #include <petscviewersaws.h>
364: static int count = 0;
366: PetscErrorCode PetscOptionsSAWsDestroy(void)
367: {
369: return(0);
370: }
372: static const char *OptionsHeader = "<head>\n"
373: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
374: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
375: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
376: "<script>\n"
377: "jQuery(document).ready(function() {\n"
378: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
379: "})\n"
380: "</script>\n"
381: "</head>\n";
383: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
384: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
386: /*
387: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
389: Bugs:
390: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
391: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
392: - Only works for PetscInt == int, PetscReal == double etc
394: */
395: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
396: {
397: PetscErrorCode ierr;
398: PetscOptionItem next = PetscOptionsObject->next;
399: static int mancount = 0;
400: char options[16];
401: PetscBool changedmethod = PETSC_FALSE;
402: PetscBool stopasking = PETSC_FALSE;
403: char manname[16],textname[16];
404: char dir[1024];
407: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
408: sprintf(options,"Options_%d",count++);
410: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
412: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
413: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
414: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
415: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
416: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
417: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
419: while (next) {
420: sprintf(manname,"_man_%d",mancount);
421: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
422: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
423: sprintf(textname,"_text_%d",mancount++);
424: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
425: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
427: switch (next->type) {
428: case OPTION_HEAD:
429: break;
430: case OPTION_INT_ARRAY:
431: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
432: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
433: break;
434: case OPTION_REAL_ARRAY:
435: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
436: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
437: break;
438: case OPTION_INT:
439: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
440: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
441: break;
442: case OPTION_REAL:
443: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
444: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
445: break;
446: case OPTION_BOOL:
447: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
448: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
449: break;
450: case OPTION_BOOL_ARRAY:
451: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
452: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
453: break;
454: case OPTION_STRING:
455: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
456: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
457: break;
458: case OPTION_STRING_ARRAY:
459: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
460: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
461: break;
462: case OPTION_FLIST:
463: {
464: PetscInt ntext;
465: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
466: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
467: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
468: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
469: }
470: break;
471: case OPTION_ELIST:
472: {
473: PetscInt ntext = next->nlist;
474: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
475: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
476: PetscMalloc1((ntext+1),(char***)&next->edata);
477: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
478: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
479: }
480: break;
481: default:
482: break;
483: }
484: next = next->next;
485: }
487: /* wait until accessor has unlocked the memory */
488: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
489: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
490: PetscSAWsBlock();
491: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
492: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
494: /* determine if any values have been set in GUI */
495: next = PetscOptionsObject->next;
496: while (next) {
497: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
498: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
499: next = next->next;
500: }
502: /* reset counter to -2; this updates the screen with the new options for the selected method */
503: if (changedmethod) PetscOptionsObject->count = -2;
505: if (stopasking) {
506: PetscOptionsPublish = PETSC_FALSE;
507: PetscOptionsObject->count = 0;//do not ask for same thing again
508: }
510: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
511: return(0);
512: }
513: #endif
515: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
516: {
517: PetscErrorCode ierr;
518: PetscOptionItem last;
519: char option[256],value[1024],tmp[32];
520: size_t j;
523: if (PetscOptionsObject->next) {
524: if (!PetscOptionsObject->count) {
525: #if defined(PETSC_HAVE_SAWS)
526: PetscOptionsSAWsInput(PetscOptionsObject);
527: #else
528: PetscOptionsGetFromTextInput(PetscOptionsObject);
529: #endif
530: }
531: }
533: PetscFree(PetscOptionsObject->title);
535: /* reset counter to -2; this updates the screen with the new options for the selected method */
536: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
537: /* reset alreadyprinted flag */
538: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
539: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
540: PetscOptionsObject->object = NULL;
542: while (PetscOptionsObject->next) {
543: if (PetscOptionsObject->next->set) {
544: if (PetscOptionsObject->prefix) {
545: PetscStrcpy(option,"-");
546: PetscStrcat(option,PetscOptionsObject->prefix);
547: PetscStrcat(option,PetscOptionsObject->next->option+1);
548: } else {
549: PetscStrcpy(option,PetscOptionsObject->next->option);
550: }
552: switch (PetscOptionsObject->next->type) {
553: case OPTION_HEAD:
554: break;
555: case OPTION_INT_ARRAY:
556: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
557: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
558: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
559: PetscStrcat(value,",");
560: PetscStrcat(value,tmp);
561: }
562: break;
563: case OPTION_INT:
564: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
565: break;
566: case OPTION_REAL:
567: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
568: break;
569: case OPTION_REAL_ARRAY:
570: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
571: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
572: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
573: PetscStrcat(value,",");
574: PetscStrcat(value,tmp);
575: }
576: break;
577: case OPTION_SCALAR_ARRAY:
578: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
579: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
580: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
581: PetscStrcat(value,",");
582: PetscStrcat(value,tmp);
583: }
584: break;
585: case OPTION_BOOL:
586: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
587: break;
588: case OPTION_BOOL_ARRAY:
589: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
590: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
591: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
592: PetscStrcat(value,",");
593: PetscStrcat(value,tmp);
594: }
595: break;
596: case OPTION_FLIST:
597: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
598: break;
599: case OPTION_ELIST:
600: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
601: break;
602: case OPTION_STRING:
603: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
604: break;
605: case OPTION_STRING_ARRAY:
606: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
607: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
608: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
609: PetscStrcat(value,",");
610: PetscStrcat(value,tmp);
611: }
612: break;
613: }
614: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
615: }
616: if (PetscOptionsObject->next->type == OPTION_ELIST) {
617: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
618: }
619: PetscFree(PetscOptionsObject->next->text);
620: PetscFree(PetscOptionsObject->next->option);
621: PetscFree(PetscOptionsObject->next->man);
622: PetscFree(PetscOptionsObject->next->edata);
624: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
625: free(PetscOptionsObject->next->data);
626: } else {
627: PetscFree(PetscOptionsObject->next->data);
628: }
630: last = PetscOptionsObject->next;
631: PetscOptionsObject->next = PetscOptionsObject->next->next;
632: PetscFree(last);
633: }
634: PetscFree(PetscOptionsObject->prefix);
635: PetscOptionsObject->next = NULL;
636: return(0);
637: }
639: /*MC
640: PetscOptionsEnum - Gets the enum value for a particular option in the database.
642: Logically Collective on the communicator passed in PetscOptionsBegin()
644: Synopsis:
645: #include "petscsys.h"
646: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
648: Input Parameters:
649: + opt - option name
650: . text - short string that describes the option
651: . man - manual page with additional information on option
652: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
653: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
654: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
655: $ value = defaultvalue
656: $ PetscOptionsEnum(..., value,&value,&flg);
657: $ if (flg) {
659: Output Parameters:
660: + value - the value to return
661: - set - PETSC_TRUE if found, else PETSC_FALSE
663: Level: beginner
665: Notes:
666: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
668: list is usually something like PCASMTypes or some other predefined list of enum names
670: If the user does not supply the option at all value is NOT changed. Thus
671: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
673: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
675: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
676: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
677: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
678: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
679: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
680: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
681: PetscOptionsFList(), PetscOptionsEList()
682: M*/
684: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
685: {
687: PetscInt ntext = 0;
688: PetscInt tval;
689: PetscBool tflg;
692: while (list[ntext++]) {
693: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
694: }
695: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
696: ntext -= 3;
697: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
698: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
699: if (tflg) *value = (PetscEnum)tval;
700: if (set) *set = tflg;
701: return(0);
702: }
704: /*MC
705: PetscOptionsEnumArray - Gets an array of enum values for a particular
706: option in the database.
708: Logically Collective on the communicator passed in PetscOptionsBegin()
710: Synopsis:
711: #include "petscsys.h"
712: PetscErrorCode PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
714: Input Parameters:
715: + opt - the option one is seeking
716: . text - short string describing option
717: . man - manual page for option
718: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
719: - n - maximum number of values
721: Output Parameters:
722: + value - location to copy values
723: . n - actual number of values found
724: - set - PETSC_TRUE if found, else PETSC_FALSE
726: Level: beginner
728: Notes:
729: The array must be passed as a comma separated list.
731: There must be no intervening spaces between the values.
733: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
735: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
736: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
737: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
738: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
739: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
740: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
741: M*/
743: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
744: {
745: PetscInt i,nlist = 0;
746: PetscOptionItem amsopt;
747: PetscErrorCode ierr;
750: while (list[nlist++]) if (nlist > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
751: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
752: nlist -= 3; /* drop enum name, prefix, and null termination */
753: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
754: PetscEnum *vals;
755: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
756: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
757: amsopt->nlist = nlist;
758: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
759: amsopt->arraylength = *n;
760: vals = (PetscEnum*)amsopt->data;
761: for (i=0; i<*n; i++) vals[i] = value[i];
762: }
763: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
764: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
765: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
766: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
767: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
768: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
769: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
770: }
771: return(0);
772: }
774: /*MC
775: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
777: Logically Collective on the communicator passed in PetscOptionsBegin()
779: Synopsis:
780: #include "petscsys.h"
781: PetscErrorCode PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)
783: Input Parameters:
784: + opt - option name
785: . text - short string that describes the option
786: . man - manual page with additional information on option
787: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
788: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
789: $ value = defaultvalue
790: $ PetscOptionsInt(..., value,&value,&flg);
791: $ if (flg) {
792: - bound - the requested value should be greater than or equal this bound or an error is generated
794: Output Parameters:
795: + value - the integer value to return
796: - flg - PETSC_TRUE if found, else PETSC_FALSE
798: Notes:
799: If the user does not supply the option at all value is NOT changed. Thus
800: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
802: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
804: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
806: Level: beginner
808: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
809: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
810: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
811: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
812: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
813: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
814: PetscOptionsFList(), PetscOptionsEList()
815: M*/
817: /*MC
818: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
820: Logically Collective on the communicator passed in PetscOptionsBegin()
822: Synopsis:
823: #include "petscsys.h"
824: PetscErrorCode PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)
826: Input Parameters:
827: + opt - option name
828: . text - short string that describes the option
829: . man - manual page with additional information on option
830: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
831: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
832: $ value = defaultvalue
833: $ PetscOptionsInt(..., value,&value,&flg);
834: $ if (flg) {
835: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
836: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
838: Output Parameters:
839: + value - the integer value to return
840: - flg - PETSC_TRUE if found, else PETSC_FALSE
842: Notes:
843: If the user does not supply the option at all value is NOT changed. Thus
844: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
846: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
848: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
850: Level: beginner
852: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
853: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsBoundedInt()
854: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
855: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
856: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
857: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
858: PetscOptionsFList(), PetscOptionsEList()
859: M*/
861: /*MC
862: PetscOptionsInt - Gets the integer value for a particular option in the database.
864: Logically Collective on the communicator passed in PetscOptionsBegin()
866: Synopsis:
867: #include "petscsys.h"
868: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))
870: Input Parameters:
871: + opt - option name
872: . text - short string that describes the option
873: . man - manual page with additional information on option
874: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
875: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
876: $ value = defaultvalue
877: $ PetscOptionsInt(..., value,&value,&flg);
878: $ if (flg) {
880: Output Parameters:
881: + value - the integer value to return
882: - flg - PETSC_TRUE if found, else PETSC_FALSE
884: Notes:
885: If the user does not supply the option at all value is NOT changed. Thus
886: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
888: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
890: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
892: Level: beginner
894: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
895: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
896: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
897: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
898: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
899: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
900: PetscOptionsFList(), PetscOptionsEList()
901: M*/
903: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set,PetscInt lb,PetscInt ub)
904: {
905: PetscErrorCode ierr;
906: PetscOptionItem amsopt;
907: PetscBool wasset;
910: if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
911: if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
912: if (!PetscOptionsObject->count) {
913: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
914: PetscMalloc(sizeof(PetscInt),&amsopt->data);
915: *(PetscInt*)amsopt->data = currentvalue;
917: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
918: if (wasset) {
919: *(PetscInt*)amsopt->data = currentvalue;
920: }
921: }
922: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
923: if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
924: if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
925: if (set) *set = wasset;
926: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
927: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %D : formerly %D>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
928: }
929: return(0);
930: }
932: /*MC
933: PetscOptionsString - Gets the string value for a particular option in the database.
935: Logically Collective on the communicator passed in PetscOptionsBegin()
937: Synopsis:
938: #include "petscsys.h"
939: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
941: Input Parameters:
942: + opt - option name
943: . text - short string that describes the option
944: . man - manual page with additional information on option
945: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
946: - len - length of the result string including null terminator
948: Output Parameters:
949: + value - the value to return
950: - flg - PETSC_TRUE if found, else PETSC_FALSE
952: Level: beginner
954: Notes:
955: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
957: 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).
959: If the user does not supply the option at all value is NOT changed. Thus
960: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
962: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
964: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
965: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
966: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
967: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
968: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
969: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
970: PetscOptionsFList(), PetscOptionsEList()
971: M*/
973: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
974: {
975: PetscErrorCode ierr;
976: PetscOptionItem amsopt;
977: PetscBool lset;
980: if (!PetscOptionsObject->count) {
981: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
982: /* must use system malloc since SAWs may free this */
983: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
984: }
985: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
986: if (set) *set = lset;
987: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
988: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %s : formerly %s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? value : currentvalue,currentvalue,text,ManSection(man));
989: }
990: return(0);
991: }
993: /*MC
994: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
996: Logically Collective on the communicator passed in PetscOptionsBegin()
998: Synopsis:
999: #include "petscsys.h"
1000: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1002: Input Parameters:
1003: + opt - option name
1004: . text - short string that describes the option
1005: . man - manual page with additional information on option
1006: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1007: $ PetscOptionsReal(..., obj->value,&obj->value,...) or
1008: $ value = defaultvalue
1009: $ PetscOptionsReal(..., value,&value,&flg);
1010: $ if (flg) {
1012: Output Parameters:
1013: + value - the value to return
1014: - flg - PETSC_TRUE if found, else PETSC_FALSE
1016: Notes:
1017: If the user does not supply the option at all value is NOT changed. Thus
1018: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1020: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1022: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1024: Level: beginner
1026: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1027: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1028: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1029: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1030: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1031: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1032: PetscOptionsFList(), PetscOptionsEList()
1033: M*/
1035: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1036: {
1037: PetscErrorCode ierr;
1038: PetscOptionItem amsopt;
1039: PetscBool lset;
1042: if (!PetscOptionsObject->count) {
1043: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1044: PetscMalloc(sizeof(PetscReal),&amsopt->data);
1046: *(PetscReal*)amsopt->data = currentvalue;
1047: }
1048: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1049: if (set) *set = lset;
1050: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1051: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g : %g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? (double)*value : (double) currentvalue,(double)currentvalue,text,ManSection(man));
1052: }
1053: return(0);
1054: }
1056: /*MC
1057: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
1059: Logically Collective on the communicator passed in PetscOptionsBegin()
1061: Synopsis:
1062: #include "petscsys.h"
1063: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1065: Input Parameters:
1066: + opt - option name
1067: . text - short string that describes the option
1068: . man - manual page with additional information on option
1069: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1070: $ PetscOptionsScalar(..., obj->value,&obj->value,...) or
1071: $ value = defaultvalue
1072: $ PetscOptionsScalar(..., value,&value,&flg);
1073: $ if (flg) {
1075: Output Parameters:
1076: + value - the value to return
1077: - flg - PETSC_TRUE if found, else PETSC_FALSE
1079: Notes:
1080: If the user does not supply the option at all value is NOT changed. Thus
1081: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1083: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1085: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1087: Level: beginner
1089: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1090: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1091: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1092: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1093: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1094: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1095: PetscOptionsFList(), PetscOptionsEList()
1096: M*/
1098: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1099: {
1103: #if !defined(PETSC_USE_COMPLEX)
1104: PetscOptionsReal(opt,text,man,currentvalue,value,set);
1105: #else
1106: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1107: #endif
1108: return(0);
1109: }
1111: /*MC
1112: 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
1113: its value is set to false.
1115: Logically Collective on the communicator passed in PetscOptionsBegin()
1117: Synopsis:
1118: #include "petscsys.h"
1119: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
1121: Input Parameters:
1122: + opt - option name
1123: . text - short string that describes the option
1124: - man - manual page with additional information on option
1126: Output Parameter:
1127: . flg - PETSC_TRUE if found, else PETSC_FALSE
1129: Level: beginner
1131: Notes:
1132: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1134: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1135: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1136: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1137: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1138: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1139: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1140: PetscOptionsFList(), PetscOptionsEList()
1141: M*/
1143: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1144: {
1145: PetscErrorCode ierr;
1146: PetscOptionItem amsopt;
1149: if (!PetscOptionsObject->count) {
1150: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1151: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1153: *(PetscBool*)amsopt->data = PETSC_FALSE;
1154: }
1155: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1156: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1157: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1158: }
1159: return(0);
1160: }
1162: /*MC
1163: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1165: Logically Collective on the communicator passed in PetscOptionsBegin()
1167: Synopsis:
1168: #include "petscsys.h"
1169: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1171: Input Parameters:
1172: + opt - option name
1173: . text - short string that describes the option
1174: . man - manual page with additional information on option
1175: . list - the possible choices
1176: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1177: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1178: $ if (flg) {
1179: - len - the length of the character array value
1181: Output Parameters:
1182: + value - the value to return
1183: - set - PETSC_TRUE if found, else PETSC_FALSE
1185: Level: intermediate
1187: Notes:
1188: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1190: If the user does not supply the option at all value is NOT changed. Thus
1191: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1193: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1195: See PetscOptionsEList() for when the choices are given in a string array
1197: To get a listing of all currently specified options,
1198: see PetscOptionsView() or PetscOptionsGetAll()
1200: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1202: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1203: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1204: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1205: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1206: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1207: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1208: M*/
1210: PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1211: {
1212: PetscErrorCode ierr;
1213: PetscOptionItem amsopt;
1214: PetscBool lset;
1217: if (!PetscOptionsObject->count) {
1218: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1219: /* must use system malloc since SAWs may free this */
1220: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1221: amsopt->flist = list;
1222: }
1223: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1224: if (set) *set = lset;
1225: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1226: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1227: }
1228: return(0);
1229: }
1231: /*MC
1232: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1234: Logically Collective on the communicator passed in PetscOptionsBegin()
1236: Synopsis:
1237: #include "petscsys.h"
1238: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1240: Input Parameters:
1241: + opt - option name
1242: . ltext - short string that describes the option
1243: . man - manual page with additional information on option
1244: . list - the possible choices (one of these must be selected, anything else is invalid)
1245: . ntext - number of choices
1246: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1247: $ PetscOptionsElist(..., obj->value,&value,&flg);
1248: $ if (flg) {
1250: Output Parameters:
1251: + value - the index of the value to return
1252: - set - PETSC_TRUE if found, else PETSC_FALSE
1254: Level: intermediate
1256: Notes:
1257: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1259: If the user does not supply the option at all value is NOT changed. Thus
1260: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1262: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1264: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1265: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1266: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1267: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1268: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1269: PetscOptionsFList(), PetscOptionsEnum()
1270: M*/
1272: PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1273: {
1274: PetscErrorCode ierr;
1275: PetscInt i;
1276: PetscOptionItem amsopt;
1277: PetscBool lset;
1280: if (!PetscOptionsObject->count) {
1281: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1282: /* must use system malloc since SAWs may free this */
1283: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1284: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1285: amsopt->nlist = ntext;
1286: }
1287: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1288: if (set) *set = lset;
1289: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1290: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %s : formerly %s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,lset && value ? list[*value] : currentvalue,currentvalue,ltext);
1291: for (i=0; i<ntext; i++) {
1292: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1293: }
1294: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1295: }
1296: return(0);
1297: }
1299: /*MC
1300: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1301: which at most a single value can be true.
1303: Logically Collective on the communicator passed in PetscOptionsBegin()
1305: Synopsis:
1306: #include "petscsys.h"
1307: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1309: Input Parameters:
1310: + opt - option name
1311: . text - short string that describes the option
1312: - man - manual page with additional information on option
1314: Output Parameter:
1315: . flg - whether that option was set or not
1317: Level: intermediate
1319: Notes:
1320: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1322: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1324: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1325: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1326: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1327: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1328: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1329: PetscOptionsFList(), PetscOptionsEList()
1330: M*/
1332: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1333: {
1334: PetscErrorCode ierr;
1335: PetscOptionItem amsopt;
1338: if (!PetscOptionsObject->count) {
1339: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1340: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1342: *(PetscBool*)amsopt->data = PETSC_FALSE;
1343: }
1344: *flg = PETSC_FALSE;
1345: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1346: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1347: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1348: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1349: }
1350: return(0);
1351: }
1353: /*MC
1354: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1355: which at most a single value can be true.
1357: Logically Collective on the communicator passed in PetscOptionsBegin()
1359: Synopsis:
1360: #include "petscsys.h"
1361: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1363: Input Parameters:
1364: + opt - option name
1365: . text - short string that describes the option
1366: - man - manual page with additional information on option
1368: Output Parameter:
1369: . flg - PETSC_TRUE if found, else PETSC_FALSE
1371: Level: intermediate
1373: Notes:
1374: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1376: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1378: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1379: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1380: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1381: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1382: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1383: PetscOptionsFList(), PetscOptionsEList()
1384: M*/
1386: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1387: {
1388: PetscErrorCode ierr;
1389: PetscOptionItem amsopt;
1392: if (!PetscOptionsObject->count) {
1393: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1394: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1396: *(PetscBool*)amsopt->data = PETSC_FALSE;
1397: }
1398: *flg = PETSC_FALSE;
1399: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1400: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1401: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1402: }
1403: return(0);
1404: }
1406: /*MC
1407: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1408: which at most a single value can be true.
1410: Logically Collective on the communicator passed in PetscOptionsBegin()
1412: Synopsis:
1413: #include "petscsys.h"
1414: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1416: Input Parameters:
1417: + opt - option name
1418: . text - short string that describes the option
1419: - man - manual page with additional information on option
1421: Output Parameter:
1422: . flg - PETSC_TRUE if found, else PETSC_FALSE
1424: Level: intermediate
1426: Notes:
1427: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1429: Must follow a PetscOptionsBoolGroupBegin()
1431: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1432: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1433: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1434: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1435: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1436: PetscOptionsFList(), PetscOptionsEList()
1437: M*/
1439: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1440: {
1441: PetscErrorCode ierr;
1442: PetscOptionItem amsopt;
1445: if (!PetscOptionsObject->count) {
1446: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1447: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1449: *(PetscBool*)amsopt->data = PETSC_FALSE;
1450: }
1451: *flg = PETSC_FALSE;
1452: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1453: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1454: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1455: }
1456: return(0);
1457: }
1459: /*MC
1460: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1462: Logically Collective on the communicator passed in PetscOptionsBegin()
1464: Synopsis:
1465: #include "petscsys.h"
1466: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1468: Input Parameters:
1469: + opt - option name
1470: . text - short string that describes the option
1471: . man - manual page with additional information on option
1472: - currentvalue - the current value
1474: Output Parameters:
1475: + flg - PETSC_TRUE or PETSC_FALSE
1476: - set - PETSC_TRUE if found, else PETSC_FALSE
1478: Notes:
1479: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1480: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1482: If the option is given, but no value is provided, then flg and set are both given the value PETSC_TRUE. That is -requested_bool
1483: is equivalent to -requested_bool true
1485: If the user does not supply the option at all flg is NOT changed. Thus
1486: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1488: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1490: Level: beginner
1492: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1493: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1494: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
1495: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1496: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1497: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1498: PetscOptionsFList(), PetscOptionsEList()
1499: M*/
1501: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1502: {
1503: PetscErrorCode ierr;
1504: PetscBool iset;
1505: PetscOptionItem amsopt;
1508: if (!PetscOptionsObject->count) {
1509: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1510: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1512: *(PetscBool*)amsopt->data = currentvalue;
1513: }
1514: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1515: if (set) *set = iset;
1516: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1517: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1518: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1519: }
1520: return(0);
1521: }
1523: /*MC
1524: PetscOptionsRealArray - Gets an array of double values for a particular
1525: option in the database. The values must be separated with commas with
1526: no intervening spaces.
1528: Logically Collective on the communicator passed in PetscOptionsBegin()
1530: Synopsis:
1531: #include "petscsys.h"
1532: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1534: Input Parameters:
1535: + opt - the option one is seeking
1536: . text - short string describing option
1537: . man - manual page for option
1538: - nmax - maximum number of values
1540: Output Parameters:
1541: + value - location to copy values
1542: . nmax - actual number of values found
1543: - set - PETSC_TRUE if found, else PETSC_FALSE
1545: Level: beginner
1547: Notes:
1548: The user should pass in an array of doubles
1550: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1552: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1553: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1554: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1555: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1556: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1557: PetscOptionsFList(), PetscOptionsEList()
1558: M*/
1560: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1561: {
1562: PetscErrorCode ierr;
1563: PetscInt i;
1564: PetscOptionItem amsopt;
1567: if (!PetscOptionsObject->count) {
1568: PetscReal *vals;
1570: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1571: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1572: vals = (PetscReal*)amsopt->data;
1573: for (i=0; i<*n; i++) vals[i] = value[i];
1574: amsopt->arraylength = *n;
1575: }
1576: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1577: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1578: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1579: for (i=1; i<*n; i++) {
1580: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1581: }
1582: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1583: }
1584: return(0);
1585: }
1587: /*MC
1588: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1589: option in the database. The values must be separated with commas with
1590: no intervening spaces.
1592: Logically Collective on the communicator passed in PetscOptionsBegin()
1594: Synopsis:
1595: #include "petscsys.h"
1596: PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1598: Input Parameters:
1599: + opt - the option one is seeking
1600: . text - short string describing option
1601: . man - manual page for option
1602: - nmax - maximum number of values
1604: Output Parameters:
1605: + value - location to copy values
1606: . nmax - actual number of values found
1607: - set - PETSC_TRUE if found, else PETSC_FALSE
1609: Level: beginner
1611: Notes:
1612: The user should pass in an array of doubles
1614: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1616: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1617: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1618: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1619: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1620: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1621: PetscOptionsFList(), PetscOptionsEList()
1622: M*/
1624: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1625: {
1626: PetscErrorCode ierr;
1627: PetscInt i;
1628: PetscOptionItem amsopt;
1631: if (!PetscOptionsObject->count) {
1632: PetscScalar *vals;
1634: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1635: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1636: vals = (PetscScalar*)amsopt->data;
1637: for (i=0; i<*n; i++) vals[i] = value[i];
1638: amsopt->arraylength = *n;
1639: }
1640: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1641: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1642: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1643: for (i=1; i<*n; i++) {
1644: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1645: }
1646: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1647: }
1648: return(0);
1649: }
1651: /*MC
1652: PetscOptionsIntArray - Gets an array of integers for a particular
1653: option in the database.
1655: Logically Collective on the communicator passed in PetscOptionsBegin()
1657: Synopsis:
1658: #include "petscsys.h"
1659: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1661: Input Parameters:
1662: + opt - the option one is seeking
1663: . text - short string describing option
1664: . man - manual page for option
1665: - n - maximum number of values
1667: Output Parameters:
1668: + value - location to copy values
1669: . n - actual number of values found
1670: - set - PETSC_TRUE if found, else PETSC_FALSE
1672: Level: beginner
1674: Notes:
1675: The array can be passed as
1676: a comma separated list: 0,1,2,3,4,5,6,7
1677: a range (start-end+1): 0-8
1678: a range with given increment (start-end+1:inc): 0-7:2
1679: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1681: There must be no intervening spaces between the values.
1683: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1685: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1686: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1687: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1688: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1689: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1690: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1691: M*/
1693: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1694: {
1696: PetscInt i;
1697: PetscOptionItem amsopt;
1700: if (!PetscOptionsObject->count) {
1701: PetscInt *vals;
1703: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1704: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1705: vals = (PetscInt*)amsopt->data;
1706: for (i=0; i<*n; i++) vals[i] = value[i];
1707: amsopt->arraylength = *n;
1708: }
1709: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1710: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1711: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1712: for (i=1; i<*n; i++) {
1713: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1714: }
1715: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1716: }
1717: return(0);
1718: }
1720: /*MC
1721: PetscOptionsStringArray - Gets an array of string values for a particular
1722: option in the database. The values must be separated with commas with
1723: no intervening spaces.
1725: Logically Collective on the communicator passed in PetscOptionsBegin()
1727: Synopsis:
1728: #include "petscsys.h"
1729: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1731: Input Parameters:
1732: + opt - the option one is seeking
1733: . text - short string describing option
1734: . man - manual page for option
1735: - nmax - maximum number of strings
1737: Output Parameters:
1738: + value - location to copy strings
1739: . nmax - actual number of strings found
1740: - set - PETSC_TRUE if found, else PETSC_FALSE
1742: Level: beginner
1744: Notes:
1745: The user should pass in an array of pointers to char, to hold all the
1746: strings returned by this function.
1748: The user is responsible for deallocating the strings that are
1749: returned. The Fortran interface for this routine is not supported.
1751: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1753: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1754: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1755: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1756: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1757: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1758: PetscOptionsFList(), PetscOptionsEList()
1759: M*/
1761: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1762: {
1763: PetscErrorCode ierr;
1764: PetscOptionItem amsopt;
1767: if (!PetscOptionsObject->count) {
1768: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1769: PetscMalloc1(*nmax,(char**)&amsopt->data);
1771: amsopt->arraylength = *nmax;
1772: }
1773: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1774: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1775: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1776: }
1777: return(0);
1778: }
1780: /*MC
1781: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1782: option in the database. The values must be separated with commas with
1783: no intervening spaces.
1785: Logically Collective on the communicator passed in PetscOptionsBegin()
1787: Synopsis:
1788: #include "petscsys.h"
1789: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1791: Input Parameters:
1792: + opt - the option one is seeking
1793: . text - short string describing option
1794: . man - manual page for option
1795: - nmax - maximum number of values
1797: Output Parameters:
1798: + value - location to copy values
1799: . nmax - actual number of values found
1800: - set - PETSC_TRUE if found, else PETSC_FALSE
1802: Level: beginner
1804: Notes:
1805: The user should pass in an array of doubles
1807: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1809: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1810: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1811: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1812: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1813: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1814: PetscOptionsFList(), PetscOptionsEList()
1815: M*/
1817: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1818: {
1819: PetscErrorCode ierr;
1820: PetscInt i;
1821: PetscOptionItem amsopt;
1824: if (!PetscOptionsObject->count) {
1825: PetscBool *vals;
1827: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1828: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1829: vals = (PetscBool*)amsopt->data;
1830: for (i=0; i<*n; i++) vals[i] = value[i];
1831: amsopt->arraylength = *n;
1832: }
1833: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1834: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1835: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1836: for (i=1; i<*n; i++) {
1837: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1838: }
1839: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1840: }
1841: return(0);
1842: }
1844: /*MC
1845: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1847: Logically Collective on the communicator passed in PetscOptionsBegin()
1849: Synopsis:
1850: #include "petscsys.h"
1851: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1853: Input Parameters:
1854: + opt - option name
1855: . text - short string that describes the option
1856: - man - manual page with additional information on option
1858: Output Parameters:
1859: + viewer - the viewer
1860: - set - PETSC_TRUE if found, else PETSC_FALSE
1862: Level: beginner
1864: Notes:
1865: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1867: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1869: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1870: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1871: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1872: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1873: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1874: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1875: PetscOptionsFList(), PetscOptionsEList()
1876: M*/
1878: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1879: {
1880: PetscErrorCode ierr;
1881: PetscOptionItem amsopt;
1884: if (!PetscOptionsObject->count) {
1885: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1886: /* must use system malloc since SAWs may free this */
1887: PetscStrdup("",(char**)&amsopt->data);
1888: }
1889: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1890: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1891: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1892: }
1893: return(0);
1894: }
1896: /*@C
1897: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1898: in KSPSetFromOptions_GMRES().
1900: Logically Collective on the communicator passed in PetscOptionsBegin()
1902: Input Parameter:
1903: . head - the heading text
1905: Level: intermediate
1907: Notes:
1908: Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument
1910: Can be followed by a call to PetscOptionsTail() in the same function.
1912: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1913: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1914: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1915: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1916: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1917: PetscOptionsFList(), PetscOptionsEList()
1918: @*/
1919: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1920: {
1924: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1925: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1926: }
1927: return(0);
1928: }