Actual source code: aoptions.c
2: /*
3: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
4: GUI code to display the options and get values from the users.
6: */
8: #include <petsc/private/petscimpl.h>
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: */
20: /*
21: Handles setting up the data structure in a call to PetscOptionsBegin()
22: */
23: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
24: {
31: if (!PetscOptionsObject->alreadyprinted) {
32: if (!PetscOptionsHelpPrintedSingleton) {
33: PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
34: }
35: PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
36: }
37: PetscOptionsObject->next = NULL;
38: PetscOptionsObject->comm = comm;
39: PetscOptionsObject->changedmethod = PETSC_FALSE;
41: PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
42: PetscStrallocpy(title,&PetscOptionsObject->title);
44: PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
45: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
46: if (!PetscOptionsObject->alreadyprinted) {
47: (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
48: }
49: }
50: return(0);
51: }
53: /*
54: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
55: */
56: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
57: {
59: char title[256];
60: PetscBool flg;
64: PetscOptionsObject->object = obj;
65: PetscOptionsObject->alreadyprinted = obj->optionsprinted;
67: PetscStrcmp(obj->description,obj->class_name,&flg);
68: if (flg) {
69: PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
70: } else {
71: PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
72: }
73: PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
74: return(0);
75: }
77: /*
78: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
79: */
80: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
81: {
82: int ierr;
83: PetscOptionItem next;
84: PetscBool valid;
87: PetscOptionsValidKey(opt,&valid);
88: if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);
90: PetscNew(amsopt);
91: (*amsopt)->next = NULL;
92: (*amsopt)->set = PETSC_FALSE;
93: (*amsopt)->type = t;
94: (*amsopt)->data = NULL;
96: PetscStrallocpy(text,&(*amsopt)->text);
97: PetscStrallocpy(opt,&(*amsopt)->option);
98: PetscStrallocpy(man,&(*amsopt)->man);
100: if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
101: else {
102: next = PetscOptionsObject->next;
103: while (next->next) next = next->next;
104: next->next = *amsopt;
105: }
106: return(0);
107: }
109: /*
110: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
112: Collective
114: Input Parameters:
115: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
116: . n - length of the string, must be the same on all processes
117: - str - location to store input
119: Bugs:
120: . Assumes process 0 of the given communicator has access to stdin
122: */
123: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
124: {
125: size_t i;
126: char c;
127: PetscMPIInt rank,nm;
131: MPI_Comm_rank(comm,&rank);
132: if (rank == 0) {
133: c = (char) getchar();
134: i = 0;
135: while (c != '\n' && i < n-1) {
136: str[i++] = c;
137: c = (char)getchar();
138: }
139: str[i] = 0;
140: }
141: PetscMPIIntCast(n,&nm);
142: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
143: return(0);
144: }
146: /*
147: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
148: */
149: static PetscErrorCode PetscStrdup(const char s[],char *t[])
150: {
152: size_t len;
153: char *tmp = NULL;
156: if (s) {
157: PetscStrlen(s,&len);
158: tmp = (char*) malloc((len+1)*sizeof(char));
159: if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
160: PetscStrcpy(tmp,s);
161: }
162: *t = tmp;
163: return(0);
164: }
166: /*
167: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
169: Notes:
170: this isn't really practical, it is just to demonstrate the principle
172: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
173: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
175: Bugs:
176: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
177: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
178: - Only works for PetscInt == int, PetscReal == double etc
180: Developer Notes:
181: Normally the GUI that presents the options the user and retrieves the values would be running in a different
182: address space and communicating with the PETSc program
184: */
185: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
186: {
187: PetscErrorCode ierr;
188: PetscOptionItem next = PetscOptionsObject->next;
189: char str[512];
190: PetscBool bid;
191: PetscReal ir,*valr;
192: PetscInt *vald;
193: size_t i;
196: (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
197: while (next) {
198: switch (next->type) {
199: case OPTION_HEAD:
200: break;
201: case OPTION_INT_ARRAY:
202: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
203: vald = (PetscInt*) next->data;
204: for (i=0; i<next->arraylength; i++) {
205: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
206: if (i < next->arraylength-1) {
207: PetscPrintf(PETSC_COMM_WORLD,",");
208: }
209: }
210: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
211: PetscScanString(PETSC_COMM_WORLD,512,str);
212: if (str[0]) {
213: PetscToken token;
214: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
215: size_t len;
216: char *value;
217: PetscBool foundrange;
219: next->set = PETSC_TRUE;
220: value = str;
221: PetscTokenCreate(value,',',&token);
222: PetscTokenFind(token,&value);
223: while (n < nmax) {
224: if (!value) break;
226: /* look for form d-D where d and D are integers */
227: foundrange = PETSC_FALSE;
228: PetscStrlen(value,&len);
229: if (value[0] == '-') i=2;
230: else i=1;
231: for (;i<len; i++) {
232: if (value[i] == '-') {
233: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
234: value[i] = 0;
235: PetscOptionsStringToInt(value,&start);
236: PetscOptionsStringToInt(value+i+1,&end);
237: 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);
238: 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);
239: for (; start<end; start++) {
240: *dvalue = start; dvalue++;n++;
241: }
242: foundrange = PETSC_TRUE;
243: break;
244: }
245: }
246: if (!foundrange) {
247: PetscOptionsStringToInt(value,dvalue);
248: dvalue++;
249: n++;
250: }
251: PetscTokenFind(token,&value);
252: }
253: PetscTokenDestroy(&token);
254: }
255: break;
256: case OPTION_REAL_ARRAY:
257: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
258: valr = (PetscReal*) next->data;
259: for (i=0; i<next->arraylength; i++) {
260: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
261: if (i < next->arraylength-1) {
262: PetscPrintf(PETSC_COMM_WORLD,",");
263: }
264: }
265: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
266: PetscScanString(PETSC_COMM_WORLD,512,str);
267: if (str[0]) {
268: PetscToken token;
269: PetscInt n = 0,nmax = next->arraylength;
270: PetscReal *dvalue = (PetscReal*)next->data;
271: char *value;
273: next->set = PETSC_TRUE;
274: value = str;
275: PetscTokenCreate(value,',',&token);
276: PetscTokenFind(token,&value);
277: while (n < nmax) {
278: if (!value) break;
279: PetscOptionsStringToReal(value,dvalue);
280: dvalue++;
281: n++;
282: PetscTokenFind(token,&value);
283: }
284: PetscTokenDestroy(&token);
285: }
286: break;
287: case OPTION_INT:
288: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
289: PetscScanString(PETSC_COMM_WORLD,512,str);
290: if (str[0]) {
291: #if defined(PETSC_SIZEOF_LONG_LONG)
292: long long lid;
293: sscanf(str,"%lld",&lid);
294: 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);
295: #else
296: long lid;
297: sscanf(str,"%ld",&lid);
298: 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);
299: #endif
301: next->set = PETSC_TRUE;
302: *((PetscInt*)next->data) = (PetscInt)lid;
303: }
304: break;
305: case OPTION_REAL:
306: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
307: PetscScanString(PETSC_COMM_WORLD,512,str);
308: if (str[0]) {
309: #if defined(PETSC_USE_REAL_SINGLE)
310: sscanf(str,"%e",&ir);
311: #elif defined(PETSC_USE_REAL___FP16)
312: float irtemp;
313: sscanf(str,"%e",&irtemp);
314: ir = irtemp;
315: #elif defined(PETSC_USE_REAL_DOUBLE)
316: sscanf(str,"%le",&ir);
317: #elif defined(PETSC_USE_REAL___FLOAT128)
318: ir = strtoflt128(str,0);
319: #else
320: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
321: #endif
322: next->set = PETSC_TRUE;
323: *((PetscReal*)next->data) = ir;
324: }
325: break;
326: case OPTION_BOOL:
327: 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);
328: PetscScanString(PETSC_COMM_WORLD,512,str);
329: if (str[0]) {
330: PetscOptionsStringToBool(str,&bid);
331: next->set = PETSC_TRUE;
332: *((PetscBool*)next->data) = bid;
333: }
334: break;
335: case OPTION_STRING:
336: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
337: PetscScanString(PETSC_COMM_WORLD,512,str);
338: if (str[0]) {
339: next->set = PETSC_TRUE;
340: /* must use system malloc since SAWs may free this */
341: PetscStrdup(str,(char**)&next->data);
342: }
343: break;
344: case OPTION_FLIST:
345: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
346: PetscScanString(PETSC_COMM_WORLD,512,str);
347: if (str[0]) {
348: PetscOptionsObject->changedmethod = PETSC_TRUE;
349: next->set = PETSC_TRUE;
350: /* must use system malloc since SAWs may free this */
351: PetscStrdup(str,(char**)&next->data);
352: }
353: break;
354: default:
355: break;
356: }
357: next = next->next;
358: }
359: return(0);
360: }
362: #if defined(PETSC_HAVE_SAWS)
363: #include <petscviewersaws.h>
365: static int count = 0;
367: PetscErrorCode PetscOptionsSAWsDestroy(void)
368: {
370: return(0);
371: }
373: static const char *OptionsHeader = "<head>\n"
374: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
375: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
376: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
377: "<script>\n"
378: "jQuery(document).ready(function() {\n"
379: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
380: "})\n"
381: "</script>\n"
382: "</head>\n";
384: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
385: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
387: /*
388: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
390: Bugs:
391: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
392: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
393: - Only works for PetscInt == int, PetscReal == double etc
395: */
396: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
397: {
398: PetscErrorCode ierr;
399: PetscOptionItem next = PetscOptionsObject->next;
400: static int mancount = 0;
401: char options[16];
402: PetscBool changedmethod = PETSC_FALSE;
403: PetscBool stopasking = PETSC_FALSE;
404: char manname[16],textname[16];
405: char dir[1024];
408: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
409: sprintf(options,"Options_%d",count++);
411: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
413: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
414: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
415: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
416: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
417: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
418: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
420: while (next) {
421: sprintf(manname,"_man_%d",mancount);
422: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
423: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
424: sprintf(textname,"_text_%d",mancount++);
425: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
426: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
428: switch (next->type) {
429: case OPTION_HEAD:
430: break;
431: case OPTION_INT_ARRAY:
432: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
433: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
434: break;
435: case OPTION_REAL_ARRAY:
436: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
437: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
438: break;
439: case OPTION_INT:
440: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
441: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
442: break;
443: case OPTION_REAL:
444: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
445: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
446: break;
447: case OPTION_BOOL:
448: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
449: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
450: break;
451: case OPTION_BOOL_ARRAY:
452: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
453: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
454: break;
455: case OPTION_STRING:
456: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
457: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
458: break;
459: case OPTION_STRING_ARRAY:
460: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
461: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
462: break;
463: case OPTION_FLIST:
464: {
465: PetscInt ntext;
466: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
467: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
468: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
469: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
470: }
471: break;
472: case OPTION_ELIST:
473: {
474: PetscInt ntext = next->nlist;
475: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
476: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
477: PetscMalloc1((ntext+1),(char***)&next->edata);
478: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
479: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
480: }
481: break;
482: default:
483: break;
484: }
485: next = next->next;
486: }
488: /* wait until accessor has unlocked the memory */
489: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
490: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
491: PetscSAWsBlock();
492: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
493: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
495: /* determine if any values have been set in GUI */
496: next = PetscOptionsObject->next;
497: while (next) {
498: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
499: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
500: next = next->next;
501: }
503: /* reset counter to -2; this updates the screen with the new options for the selected method */
504: if (changedmethod) PetscOptionsObject->count = -2;
506: if (stopasking) {
507: PetscOptionsPublish = PETSC_FALSE;
508: PetscOptionsObject->count = 0;//do not ask for same thing again
509: }
511: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
512: return(0);
513: }
514: #endif
516: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
517: {
518: PetscErrorCode ierr;
519: PetscOptionItem last;
520: char option[256],value[1024],tmp[32];
521: size_t j;
524: if (PetscOptionsObject->next) {
525: if (!PetscOptionsObject->count) {
526: #if defined(PETSC_HAVE_SAWS)
527: PetscOptionsSAWsInput(PetscOptionsObject);
528: #else
529: PetscOptionsGetFromTextInput(PetscOptionsObject);
530: #endif
531: }
532: }
534: PetscFree(PetscOptionsObject->title);
536: /* reset counter to -2; this updates the screen with the new options for the selected method */
537: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
538: /* reset alreadyprinted flag */
539: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
540: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
541: PetscOptionsObject->object = NULL;
543: while (PetscOptionsObject->next) {
544: if (PetscOptionsObject->next->set) {
545: if (PetscOptionsObject->prefix) {
546: PetscStrcpy(option,"-");
547: PetscStrcat(option,PetscOptionsObject->prefix);
548: PetscStrcat(option,PetscOptionsObject->next->option+1);
549: } else {
550: PetscStrcpy(option,PetscOptionsObject->next->option);
551: }
553: switch (PetscOptionsObject->next->type) {
554: case OPTION_HEAD:
555: break;
556: case OPTION_INT_ARRAY:
557: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
558: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
559: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
560: PetscStrcat(value,",");
561: PetscStrcat(value,tmp);
562: }
563: break;
564: case OPTION_INT:
565: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
566: break;
567: case OPTION_REAL:
568: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
569: break;
570: case OPTION_REAL_ARRAY:
571: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
572: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
573: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
574: PetscStrcat(value,",");
575: PetscStrcat(value,tmp);
576: }
577: break;
578: case OPTION_SCALAR_ARRAY:
579: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
580: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
581: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
582: PetscStrcat(value,",");
583: PetscStrcat(value,tmp);
584: }
585: break;
586: case OPTION_BOOL:
587: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
588: break;
589: case OPTION_BOOL_ARRAY:
590: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
591: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
592: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
593: PetscStrcat(value,",");
594: PetscStrcat(value,tmp);
595: }
596: break;
597: case OPTION_FLIST:
598: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
599: break;
600: case OPTION_ELIST:
601: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
602: break;
603: case OPTION_STRING:
604: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
605: break;
606: case OPTION_STRING_ARRAY:
607: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
608: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
609: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
610: PetscStrcat(value,",");
611: PetscStrcat(value,tmp);
612: }
613: break;
614: }
615: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
616: }
617: if (PetscOptionsObject->next->type == OPTION_ELIST) {
618: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
619: }
620: PetscFree(PetscOptionsObject->next->text);
621: PetscFree(PetscOptionsObject->next->option);
622: PetscFree(PetscOptionsObject->next->man);
623: PetscFree(PetscOptionsObject->next->edata);
625: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
626: free(PetscOptionsObject->next->data);
627: } else {
628: PetscFree(PetscOptionsObject->next->data);
629: }
631: last = PetscOptionsObject->next;
632: PetscOptionsObject->next = PetscOptionsObject->next->next;
633: PetscFree(last);
634: }
635: PetscFree(PetscOptionsObject->prefix);
636: PetscOptionsObject->next = NULL;
637: return(0);
638: }
640: /*MC
641: PetscOptionsEnum - Gets the enum value for a particular option in the database.
643: Logically Collective on the communicator passed in PetscOptionsBegin()
645: Synopsis:
646: #include "petscsys.h"
647: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
649: Input Parameters:
650: + opt - option name
651: . text - short string that describes the option
652: . man - manual page with additional information on option
653: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
654: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
655: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
656: $ value = defaultvalue
657: $ PetscOptionsEnum(..., value,&value,&flg);
658: $ if (flg) {
660: Output Parameters:
661: + value - the value to return
662: - set - PETSC_TRUE if found, else PETSC_FALSE
664: Level: beginner
666: Notes:
667: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
669: list is usually something like PCASMTypes or some other predefined list of enum names
671: If the user does not supply the option at all value is NOT changed. Thus
672: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
674: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
676: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
677: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
678: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
679: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
680: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
681: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
682: PetscOptionsFList(), PetscOptionsEList()
683: M*/
685: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
686: {
688: PetscInt ntext = 0;
689: PetscInt tval;
690: PetscBool tflg;
693: while (list[ntext++]) {
694: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
695: }
696: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
697: ntext -= 3;
698: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
699: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
700: if (tflg) *value = (PetscEnum)tval;
701: if (set) *set = tflg;
702: return(0);
703: }
705: /*MC
706: PetscOptionsEnumArray - Gets an array of enum values for a particular
707: option in the database.
709: Logically Collective on the communicator passed in PetscOptionsBegin()
711: Synopsis:
712: #include "petscsys.h"
713: PetscErrorCode PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
715: Input Parameters:
716: + opt - the option one is seeking
717: . text - short string describing option
718: . man - manual page for option
719: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
720: - n - maximum number of values
722: Output Parameters:
723: + value - location to copy values
724: . n - actual number of values found
725: - set - PETSC_TRUE if found, else PETSC_FALSE
727: Level: beginner
729: Notes:
730: The array must be passed as a comma separated list.
732: There must be no intervening spaces between the values.
734: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
736: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
737: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
738: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
739: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
740: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
741: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
742: M*/
744: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
745: {
746: PetscInt i,nlist = 0;
747: PetscOptionItem amsopt;
748: PetscErrorCode ierr;
751: 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");
752: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
753: nlist -= 3; /* drop enum name, prefix, and null termination */
754: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
755: PetscEnum *vals;
756: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
757: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
758: amsopt->nlist = nlist;
759: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
760: amsopt->arraylength = *n;
761: vals = (PetscEnum*)amsopt->data;
762: for (i=0; i<*n; i++) vals[i] = value[i];
763: }
764: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
765: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
766: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
767: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
768: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
769: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
770: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
771: }
772: return(0);
773: }
775: /*MC
776: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
778: Logically Collective on the communicator passed in PetscOptionsBegin()
780: Synopsis:
781: #include "petscsys.h"
782: PetscErrorCode PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)
784: Input Parameters:
785: + opt - option name
786: . text - short string that describes the option
787: . man - manual page with additional information on option
788: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
789: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
790: $ value = defaultvalue
791: $ PetscOptionsInt(..., value,&value,&flg);
792: $ if (flg) {
793: - bound - the requested value should be greater than or equal this bound or an error is generated
795: Output Parameters:
796: + value - the integer value to return
797: - flg - PETSC_TRUE if found, else PETSC_FALSE
799: Notes:
800: If the user does not supply the option at all value is NOT changed. Thus
801: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
803: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
805: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
807: Level: beginner
809: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
810: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
811: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
812: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
813: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
814: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
815: PetscOptionsFList(), PetscOptionsEList()
816: M*/
818: /*MC
819: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
821: Logically Collective on the communicator passed in PetscOptionsBegin()
823: Synopsis:
824: #include "petscsys.h"
825: PetscErrorCode PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)
827: Input Parameters:
828: + opt - option name
829: . text - short string that describes the option
830: . man - manual page with additional information on option
831: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
832: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
833: $ value = defaultvalue
834: $ PetscOptionsInt(..., value,&value,&flg);
835: $ if (flg) {
836: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
837: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
839: Output Parameters:
840: + value - the integer value to return
841: - flg - PETSC_TRUE if found, else PETSC_FALSE
843: Notes:
844: If the user does not supply the option at all value is NOT changed. Thus
845: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
847: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
849: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
851: Level: beginner
853: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
854: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsBoundedInt()
855: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
856: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
857: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
858: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
859: PetscOptionsFList(), PetscOptionsEList()
860: M*/
862: /*MC
863: PetscOptionsInt - Gets the integer value for a particular option in the database.
865: Logically Collective on the communicator passed in PetscOptionsBegin()
867: Synopsis:
868: #include "petscsys.h"
869: PetscErrorCode PetscOptionsInt(const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))
871: Input Parameters:
872: + opt - option name
873: . text - short string that describes the option
874: . man - manual page with additional information on option
875: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
876: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
877: $ value = defaultvalue
878: $ PetscOptionsInt(..., value,&value,&flg);
879: $ if (flg) {
881: Output Parameters:
882: + value - the integer value to return
883: - flg - PETSC_TRUE if found, else PETSC_FALSE
885: Notes:
886: If the user does not supply the option at all value is NOT changed. Thus
887: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
889: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
891: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
893: Level: beginner
895: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
896: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
897: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
898: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
899: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
900: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
901: PetscOptionsFList(), PetscOptionsEList()
902: M*/
904: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set,PetscInt lb,PetscInt ub)
905: {
906: PetscErrorCode ierr;
907: PetscOptionItem amsopt;
908: PetscBool wasset;
911: if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
912: if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
913: if (!PetscOptionsObject->count) {
914: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
915: PetscMalloc(sizeof(PetscInt),&amsopt->data);
916: *(PetscInt*)amsopt->data = currentvalue;
918: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
919: if (wasset) {
920: *(PetscInt*)amsopt->data = currentvalue;
921: }
922: }
923: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
924: if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
925: if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
926: if (set) *set = wasset;
927: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
928: (*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));
929: }
930: return(0);
931: }
933: /*MC
934: PetscOptionsString - Gets the string value for a particular option in the database.
936: Logically Collective on the communicator passed in PetscOptionsBegin()
938: Synopsis:
939: #include "petscsys.h"
940: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
942: Input Parameters:
943: + opt - option name
944: . text - short string that describes the option
945: . man - manual page with additional information on option
946: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
947: - len - length of the result string including null terminator
949: Output Parameters:
950: + value - the value to return
951: - flg - PETSC_TRUE if found, else PETSC_FALSE
953: Level: beginner
955: Notes:
956: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
958: 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).
960: If the user does not supply the option at all value is NOT changed. Thus
961: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
963: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
965: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
966: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
967: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
968: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
969: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
970: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
971: PetscOptionsFList(), PetscOptionsEList()
972: M*/
974: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
975: {
976: PetscErrorCode ierr;
977: PetscOptionItem amsopt;
978: PetscBool lset;
981: if (!PetscOptionsObject->count) {
982: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
983: /* must use system malloc since SAWs may free this */
984: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
985: }
986: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
987: if (set) *set = lset;
988: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
989: (*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));
990: }
991: return(0);
992: }
994: /*MC
995: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
997: Logically Collective on the communicator passed in PetscOptionsBegin()
999: Synopsis:
1000: #include "petscsys.h"
1001: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1003: Input Parameters:
1004: + opt - option name
1005: . text - short string that describes the option
1006: . man - manual page with additional information on option
1007: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1008: $ PetscOptionsReal(..., obj->value,&obj->value,...) or
1009: $ value = defaultvalue
1010: $ PetscOptionsReal(..., value,&value,&flg);
1011: $ if (flg) {
1013: Output Parameters:
1014: + value - the value to return
1015: - flg - PETSC_TRUE if found, else PETSC_FALSE
1017: Notes:
1018: If the user does not supply the option at all value is NOT changed. Thus
1019: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1021: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1023: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1025: Level: beginner
1027: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1028: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1029: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1030: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1031: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1032: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1033: PetscOptionsFList(), PetscOptionsEList()
1034: M*/
1036: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1037: {
1038: PetscErrorCode ierr;
1039: PetscOptionItem amsopt;
1040: PetscBool lset;
1043: if (!PetscOptionsObject->count) {
1044: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1045: PetscMalloc(sizeof(PetscReal),&amsopt->data);
1047: *(PetscReal*)amsopt->data = currentvalue;
1048: }
1049: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1050: if (set) *set = lset;
1051: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1052: (*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));
1053: }
1054: return(0);
1055: }
1057: /*MC
1058: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
1060: Logically Collective on the communicator passed in PetscOptionsBegin()
1062: Synopsis:
1063: #include "petscsys.h"
1064: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1066: Input Parameters:
1067: + opt - option name
1068: . text - short string that describes the option
1069: . man - manual page with additional information on option
1070: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1071: $ PetscOptionsScalar(..., obj->value,&obj->value,...) or
1072: $ value = defaultvalue
1073: $ PetscOptionsScalar(..., value,&value,&flg);
1074: $ if (flg) {
1076: Output Parameters:
1077: + value - the value to return
1078: - flg - PETSC_TRUE if found, else PETSC_FALSE
1080: Notes:
1081: If the user does not supply the option at all value is NOT changed. Thus
1082: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1084: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1086: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1088: Level: beginner
1090: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1091: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1092: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1093: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1094: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1095: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1096: PetscOptionsFList(), PetscOptionsEList()
1097: M*/
1099: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1100: {
1104: #if !defined(PETSC_USE_COMPLEX)
1105: PetscOptionsReal(opt,text,man,currentvalue,value,set);
1106: #else
1107: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1108: #endif
1109: return(0);
1110: }
1112: /*MC
1113: 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
1114: its value is set to false.
1116: Logically Collective on the communicator passed in PetscOptionsBegin()
1118: Synopsis:
1119: #include "petscsys.h"
1120: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
1122: Input Parameters:
1123: + opt - option name
1124: . text - short string that describes the option
1125: - man - manual page with additional information on option
1127: Output Parameter:
1128: . flg - PETSC_TRUE if found, else PETSC_FALSE
1130: Level: beginner
1132: Notes:
1133: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1135: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1136: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1137: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1138: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1139: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1140: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1141: PetscOptionsFList(), PetscOptionsEList()
1142: M*/
1144: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1145: {
1146: PetscErrorCode ierr;
1147: PetscOptionItem amsopt;
1150: if (!PetscOptionsObject->count) {
1151: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1152: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1154: *(PetscBool*)amsopt->data = PETSC_FALSE;
1155: }
1156: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1157: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1158: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1159: }
1160: return(0);
1161: }
1163: /*MC
1164: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1166: Logically Collective on the communicator passed in PetscOptionsBegin()
1168: Synopsis:
1169: #include "petscsys.h"
1170: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1172: Input Parameters:
1173: + opt - option name
1174: . text - short string that describes the option
1175: . man - manual page with additional information on option
1176: . list - the possible choices
1177: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1178: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1179: $ if (flg) {
1180: - len - the length of the character array value
1182: Output Parameters:
1183: + value - the value to return
1184: - set - PETSC_TRUE if found, else PETSC_FALSE
1186: Level: intermediate
1188: Notes:
1189: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1191: If the user does not supply the option at all value is NOT changed. Thus
1192: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1194: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1196: See PetscOptionsEList() for when the choices are given in a string array
1198: To get a listing of all currently specified options,
1199: see PetscOptionsView() or PetscOptionsGetAll()
1201: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1203: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1204: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1205: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1206: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1207: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1208: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1209: M*/
1211: 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)
1212: {
1213: PetscErrorCode ierr;
1214: PetscOptionItem amsopt;
1215: PetscBool lset;
1218: if (!PetscOptionsObject->count) {
1219: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1220: /* must use system malloc since SAWs may free this */
1221: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1222: amsopt->flist = list;
1223: }
1224: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1225: if (set) *set = lset;
1226: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1227: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1228: }
1229: return(0);
1230: }
1232: /*MC
1233: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1235: Logically Collective on the communicator passed in PetscOptionsBegin()
1237: Synopsis:
1238: #include "petscsys.h"
1239: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1241: Input Parameters:
1242: + opt - option name
1243: . ltext - short string that describes the option
1244: . man - manual page with additional information on option
1245: . list - the possible choices (one of these must be selected, anything else is invalid)
1246: . ntext - number of choices
1247: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1248: $ PetscOptionsElist(..., obj->value,&value,&flg);
1249: $ if (flg) {
1251: Output Parameters:
1252: + value - the index of the value to return
1253: - set - PETSC_TRUE if found, else PETSC_FALSE
1255: Level: intermediate
1257: Notes:
1258: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1260: If the user does not supply the option at all value is NOT changed. Thus
1261: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1263: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1265: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1266: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1267: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1268: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1269: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1270: PetscOptionsFList(), PetscOptionsEnum()
1271: M*/
1273: 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)
1274: {
1275: PetscErrorCode ierr;
1276: PetscInt i;
1277: PetscOptionItem amsopt;
1278: PetscBool lset;
1281: if (!PetscOptionsObject->count) {
1282: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1283: /* must use system malloc since SAWs may free this */
1284: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1285: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1286: amsopt->nlist = ntext;
1287: }
1288: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1289: if (set) *set = lset;
1290: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1291: (*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);
1292: for (i=0; i<ntext; i++) {
1293: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1294: }
1295: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1296: }
1297: return(0);
1298: }
1300: /*MC
1301: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1302: which at most a single value can be true.
1304: Logically Collective on the communicator passed in PetscOptionsBegin()
1306: Synopsis:
1307: #include "petscsys.h"
1308: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1310: Input Parameters:
1311: + opt - option name
1312: . text - short string that describes the option
1313: - man - manual page with additional information on option
1315: Output Parameter:
1316: . flg - whether that option was set or not
1318: Level: intermediate
1320: Notes:
1321: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1323: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1325: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1326: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1327: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1328: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1329: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1330: PetscOptionsFList(), PetscOptionsEList()
1331: M*/
1333: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1334: {
1335: PetscErrorCode ierr;
1336: PetscOptionItem amsopt;
1339: if (!PetscOptionsObject->count) {
1340: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1341: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1343: *(PetscBool*)amsopt->data = PETSC_FALSE;
1344: }
1345: *flg = PETSC_FALSE;
1346: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1347: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1348: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1349: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1350: }
1351: return(0);
1352: }
1354: /*MC
1355: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1356: which at most a single value can be true.
1358: Logically Collective on the communicator passed in PetscOptionsBegin()
1360: Synopsis:
1361: #include "petscsys.h"
1362: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1364: Input Parameters:
1365: + opt - option name
1366: . text - short string that describes the option
1367: - man - manual page with additional information on option
1369: Output Parameter:
1370: . flg - PETSC_TRUE if found, else PETSC_FALSE
1372: Level: intermediate
1374: Notes:
1375: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1377: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1379: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1380: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1381: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1382: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1383: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1384: PetscOptionsFList(), PetscOptionsEList()
1385: M*/
1387: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1388: {
1389: PetscErrorCode ierr;
1390: PetscOptionItem amsopt;
1393: if (!PetscOptionsObject->count) {
1394: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1395: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1397: *(PetscBool*)amsopt->data = PETSC_FALSE;
1398: }
1399: *flg = PETSC_FALSE;
1400: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1401: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1402: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1403: }
1404: return(0);
1405: }
1407: /*MC
1408: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1409: which at most a single value can be true.
1411: Logically Collective on the communicator passed in PetscOptionsBegin()
1413: Synopsis:
1414: #include "petscsys.h"
1415: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1417: Input Parameters:
1418: + opt - option name
1419: . text - short string that describes the option
1420: - man - manual page with additional information on option
1422: Output Parameter:
1423: . flg - PETSC_TRUE if found, else PETSC_FALSE
1425: Level: intermediate
1427: Notes:
1428: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1430: Must follow a PetscOptionsBoolGroupBegin()
1432: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1433: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1434: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1435: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1436: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1437: PetscOptionsFList(), PetscOptionsEList()
1438: M*/
1440: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1441: {
1442: PetscErrorCode ierr;
1443: PetscOptionItem amsopt;
1446: if (!PetscOptionsObject->count) {
1447: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1448: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1450: *(PetscBool*)amsopt->data = PETSC_FALSE;
1451: }
1452: *flg = PETSC_FALSE;
1453: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1454: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1455: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1456: }
1457: return(0);
1458: }
1460: /*MC
1461: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1463: Logically Collective on the communicator passed in PetscOptionsBegin()
1465: Synopsis:
1466: #include "petscsys.h"
1467: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1469: Input Parameters:
1470: + opt - option name
1471: . text - short string that describes the option
1472: . man - manual page with additional information on option
1473: - currentvalue - the current value
1475: Output Parameters:
1476: + flg - PETSC_TRUE or PETSC_FALSE
1477: - set - PETSC_TRUE if found, else PETSC_FALSE
1479: Notes:
1480: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1481: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1483: 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
1484: is equivalent to -requested_bool true
1486: If the user does not supply the option at all flg is NOT changed. Thus
1487: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1489: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1491: Level: beginner
1493: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1494: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1495: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
1496: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1497: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1498: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1499: PetscOptionsFList(), PetscOptionsEList()
1500: M*/
1502: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1503: {
1504: PetscErrorCode ierr;
1505: PetscBool iset;
1506: PetscOptionItem amsopt;
1509: if (!PetscOptionsObject->count) {
1510: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1511: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1513: *(PetscBool*)amsopt->data = currentvalue;
1514: }
1515: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1516: if (set) *set = iset;
1517: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1518: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1519: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1520: }
1521: return(0);
1522: }
1524: /*MC
1525: PetscOptionsRealArray - Gets an array of double values for a particular
1526: option in the database. The values must be separated with commas with
1527: no intervening spaces.
1529: Logically Collective on the communicator passed in PetscOptionsBegin()
1531: Synopsis:
1532: #include "petscsys.h"
1533: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1535: Input Parameters:
1536: + opt - the option one is seeking
1537: . text - short string describing option
1538: . man - manual page for option
1539: - nmax - maximum number of values
1541: Output Parameters:
1542: + value - location to copy values
1543: . nmax - actual number of values found
1544: - set - PETSC_TRUE if found, else PETSC_FALSE
1546: Level: beginner
1548: Notes:
1549: The user should pass in an array of doubles
1551: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1553: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1554: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1555: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1556: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1557: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1558: PetscOptionsFList(), PetscOptionsEList()
1559: M*/
1561: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1562: {
1563: PetscErrorCode ierr;
1564: PetscInt i;
1565: PetscOptionItem amsopt;
1568: if (!PetscOptionsObject->count) {
1569: PetscReal *vals;
1571: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1572: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1573: vals = (PetscReal*)amsopt->data;
1574: for (i=0; i<*n; i++) vals[i] = value[i];
1575: amsopt->arraylength = *n;
1576: }
1577: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1578: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1579: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1580: for (i=1; i<*n; i++) {
1581: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1582: }
1583: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1584: }
1585: return(0);
1586: }
1588: /*MC
1589: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1590: option in the database. The values must be separated with commas with
1591: no intervening spaces.
1593: Logically Collective on the communicator passed in PetscOptionsBegin()
1595: Synopsis:
1596: #include "petscsys.h"
1597: PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1599: Input Parameters:
1600: + opt - the option one is seeking
1601: . text - short string describing option
1602: . man - manual page for option
1603: - nmax - maximum number of values
1605: Output Parameters:
1606: + value - location to copy values
1607: . nmax - actual number of values found
1608: - set - PETSC_TRUE if found, else PETSC_FALSE
1610: Level: beginner
1612: Notes:
1613: The user should pass in an array of doubles
1615: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1617: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1618: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1619: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1620: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1621: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1622: PetscOptionsFList(), PetscOptionsEList()
1623: M*/
1625: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1626: {
1627: PetscErrorCode ierr;
1628: PetscInt i;
1629: PetscOptionItem amsopt;
1632: if (!PetscOptionsObject->count) {
1633: PetscScalar *vals;
1635: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1636: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1637: vals = (PetscScalar*)amsopt->data;
1638: for (i=0; i<*n; i++) vals[i] = value[i];
1639: amsopt->arraylength = *n;
1640: }
1641: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1642: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1643: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1644: for (i=1; i<*n; i++) {
1645: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1646: }
1647: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1648: }
1649: return(0);
1650: }
1652: /*MC
1653: PetscOptionsIntArray - Gets an array of integers for a particular
1654: option in the database.
1656: Logically Collective on the communicator passed in PetscOptionsBegin()
1658: Synopsis:
1659: #include "petscsys.h"
1660: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1662: Input Parameters:
1663: + opt - the option one is seeking
1664: . text - short string describing option
1665: . man - manual page for option
1666: - n - maximum number of values
1668: Output Parameters:
1669: + value - location to copy values
1670: . n - actual number of values found
1671: - set - PETSC_TRUE if found, else PETSC_FALSE
1673: Level: beginner
1675: Notes:
1676: The array can be passed as
1677: a comma separated list: 0,1,2,3,4,5,6,7
1678: a range (start-end+1): 0-8
1679: a range with given increment (start-end+1:inc): 0-7:2
1680: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1682: There must be no intervening spaces between the values.
1684: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1686: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1687: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1688: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1689: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1690: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1691: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1692: M*/
1694: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1695: {
1697: PetscInt i;
1698: PetscOptionItem amsopt;
1701: if (!PetscOptionsObject->count) {
1702: PetscInt *vals;
1704: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1705: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1706: vals = (PetscInt*)amsopt->data;
1707: for (i=0; i<*n; i++) vals[i] = value[i];
1708: amsopt->arraylength = *n;
1709: }
1710: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1711: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1712: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1713: for (i=1; i<*n; i++) {
1714: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1715: }
1716: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1717: }
1718: return(0);
1719: }
1721: /*MC
1722: PetscOptionsStringArray - Gets an array of string values for a particular
1723: option in the database. The values must be separated with commas with
1724: no intervening spaces.
1726: Logically Collective on the communicator passed in PetscOptionsBegin()
1728: Synopsis:
1729: #include "petscsys.h"
1730: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1732: Input Parameters:
1733: + opt - the option one is seeking
1734: . text - short string describing option
1735: . man - manual page for option
1736: - nmax - maximum number of strings
1738: Output Parameters:
1739: + value - location to copy strings
1740: . nmax - actual number of strings found
1741: - set - PETSC_TRUE if found, else PETSC_FALSE
1743: Level: beginner
1745: Notes:
1746: The user should pass in an array of pointers to char, to hold all the
1747: strings returned by this function.
1749: The user is responsible for deallocating the strings that are
1750: returned. The Fortran interface for this routine is not supported.
1752: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1754: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1755: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1756: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1757: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1758: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1759: PetscOptionsFList(), PetscOptionsEList()
1760: M*/
1762: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1763: {
1764: PetscErrorCode ierr;
1765: PetscOptionItem amsopt;
1768: if (!PetscOptionsObject->count) {
1769: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1770: PetscMalloc1(*nmax,(char**)&amsopt->data);
1772: amsopt->arraylength = *nmax;
1773: }
1774: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1775: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1776: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1777: }
1778: return(0);
1779: }
1781: /*MC
1782: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1783: option in the database. The values must be separated with commas with
1784: no intervening spaces.
1786: Logically Collective on the communicator passed in PetscOptionsBegin()
1788: Synopsis:
1789: #include "petscsys.h"
1790: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1792: Input Parameters:
1793: + opt - the option one is seeking
1794: . text - short string describing option
1795: . man - manual page for option
1796: - nmax - maximum number of values
1798: Output Parameters:
1799: + value - location to copy values
1800: . nmax - actual number of values found
1801: - set - PETSC_TRUE if found, else PETSC_FALSE
1803: Level: beginner
1805: Notes:
1806: The user should pass in an array of doubles
1808: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1810: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1811: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1812: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1813: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1814: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1815: PetscOptionsFList(), PetscOptionsEList()
1816: M*/
1818: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1819: {
1820: PetscErrorCode ierr;
1821: PetscInt i;
1822: PetscOptionItem amsopt;
1825: if (!PetscOptionsObject->count) {
1826: PetscBool *vals;
1828: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1829: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1830: vals = (PetscBool*)amsopt->data;
1831: for (i=0; i<*n; i++) vals[i] = value[i];
1832: amsopt->arraylength = *n;
1833: }
1834: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1835: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1836: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1837: for (i=1; i<*n; i++) {
1838: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1839: }
1840: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1841: }
1842: return(0);
1843: }
1845: /*MC
1846: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1848: Logically Collective on the communicator passed in PetscOptionsBegin()
1850: Synopsis:
1851: #include "petscsys.h"
1852: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1854: Input Parameters:
1855: + opt - option name
1856: . text - short string that describes the option
1857: - man - manual page with additional information on option
1859: Output Parameters:
1860: + viewer - the viewer
1861: - set - PETSC_TRUE if found, else PETSC_FALSE
1863: Level: beginner
1865: Notes:
1866: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1868: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1870: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1871: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1872: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1873: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1874: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1875: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1876: PetscOptionsFList(), PetscOptionsEList()
1877: M*/
1879: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1880: {
1881: PetscErrorCode ierr;
1882: PetscOptionItem amsopt;
1885: if (!PetscOptionsObject->count) {
1886: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1887: /* must use system malloc since SAWs may free this */
1888: PetscStrdup("",(char**)&amsopt->data);
1889: }
1890: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1891: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1892: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1893: }
1894: return(0);
1895: }
1897: /*@C
1898: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1899: in KSPSetFromOptions_GMRES().
1901: Logically Collective on the communicator passed in PetscOptionsBegin()
1903: Input Parameter:
1904: . head - the heading text
1906: Level: intermediate
1908: Notes:
1909: Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument
1911: Can be followed by a call to PetscOptionsTail() in the same function.
1913: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1914: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1915: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1916: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1917: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1918: PetscOptionsFList(), PetscOptionsEList()
1919: @*/
1920: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1921: {
1925: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1926: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1927: }
1928: return(0);
1929: }