Actual source code: aoptions.c
petsc-3.12.5 2020-03-29
3: /*
4: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
5: GUI code to display the options and get values from the users.
7: */
9: #include <petsc/private/petscimpl.h>
10: #include <petscviewer.h>
12: #define ManSection(str) ((str) ? (str) : "None")
14: /*
15: Keep a linked list of options that have been posted and we are waiting for
16: user selection. See the manual page for PetscOptionsBegin()
18: Eventually we'll attach this beast to a MPI_Comm
19: */
22: /*
23: Handles setting up the data structure in a call to PetscOptionsBegin()
24: */
25: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
26: {
30: if (!PetscOptionsObject->alreadyprinted) {
31: if (!PetscOptionsHelpPrintedSingleton) {
32: PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
33: }
34: PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
35: }
36: PetscOptionsObject->next = 0;
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,"%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 = 0;
91: (*amsopt)->set = PETSC_FALSE;
92: (*amsopt)->type = t;
93: (*amsopt)->data = 0;
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) {
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 = 0;
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: }
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
396: */
397: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
398: {
399: PetscErrorCode ierr;
400: PetscOptionItem next = PetscOptionsObject->next;
401: static int mancount = 0;
402: char options[16];
403: PetscBool changedmethod = PETSC_FALSE;
404: PetscBool stopasking = PETSC_FALSE;
405: char manname[16],textname[16];
406: char dir[1024];
409: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
410: sprintf(options,"Options_%d",count++);
412: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
414: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
415: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
416: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
417: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
418: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
419: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
421: while (next) {
422: sprintf(manname,"_man_%d",mancount);
423: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
424: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
425: sprintf(textname,"_text_%d",mancount++);
426: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
427: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
429: switch (next->type) {
430: case OPTION_HEAD:
431: break;
432: case OPTION_INT_ARRAY:
433: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
434: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
435: break;
436: case OPTION_REAL_ARRAY:
437: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
438: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
439: break;
440: case OPTION_INT:
441: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
442: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
443: break;
444: case OPTION_REAL:
445: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
446: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
447: break;
448: case OPTION_BOOL:
449: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
450: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
451: break;
452: case OPTION_BOOL_ARRAY:
453: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
454: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
455: break;
456: case OPTION_STRING:
457: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
458: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
459: break;
460: case OPTION_STRING_ARRAY:
461: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
462: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
463: break;
464: case OPTION_FLIST:
465: {
466: PetscInt ntext;
467: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
468: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
469: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
470: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
471: }
472: break;
473: case OPTION_ELIST:
474: {
475: PetscInt ntext = next->nlist;
476: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
477: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
478: PetscMalloc1((ntext+1),(char***)&next->edata);
479: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
480: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
481: }
482: break;
483: default:
484: break;
485: }
486: next = next->next;
487: }
489: /* wait until accessor has unlocked the memory */
490: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
491: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
492: PetscSAWsBlock();
493: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
494: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
496: /* determine if any values have been set in GUI */
497: next = PetscOptionsObject->next;
498: while (next) {
499: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
500: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
501: next = next->next;
502: }
504: /* reset counter to -2; this updates the screen with the new options for the selected method */
505: if (changedmethod) PetscOptionsObject->count = -2;
507: if (stopasking) {
508: PetscOptionsPublish = PETSC_FALSE;
509: PetscOptionsObject->count = 0;//do not ask for same thing again
510: }
512: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
513: return(0);
514: }
515: #endif
517: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
518: {
519: PetscErrorCode ierr;
520: PetscOptionItem last;
521: char option[256],value[1024],tmp[32];
522: size_t j;
525: if (PetscOptionsObject->next) {
526: if (!PetscOptionsObject->count) {
527: #if defined(PETSC_HAVE_SAWS)
528: PetscOptionsSAWsInput(PetscOptionsObject);
529: #else
530: PetscOptionsGetFromTextInput(PetscOptionsObject);
531: #endif
532: }
533: }
535: PetscFree(PetscOptionsObject->title);
537: /* reset counter to -2; this updates the screen with the new options for the selected method */
538: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
539: /* reset alreadyprinted flag */
540: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
541: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
542: PetscOptionsObject->object = NULL;
544: while (PetscOptionsObject->next) {
545: if (PetscOptionsObject->next->set) {
546: if (PetscOptionsObject->prefix) {
547: PetscStrcpy(option,"-");
548: PetscStrcat(option,PetscOptionsObject->prefix);
549: PetscStrcat(option,PetscOptionsObject->next->option+1);
550: } else {
551: PetscStrcpy(option,PetscOptionsObject->next->option);
552: }
554: switch (PetscOptionsObject->next->type) {
555: case OPTION_HEAD:
556: break;
557: case OPTION_INT_ARRAY:
558: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
559: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
560: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
561: PetscStrcat(value,",");
562: PetscStrcat(value,tmp);
563: }
564: break;
565: case OPTION_INT:
566: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
567: break;
568: case OPTION_REAL:
569: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
570: break;
571: case OPTION_REAL_ARRAY:
572: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
573: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
574: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
575: PetscStrcat(value,",");
576: PetscStrcat(value,tmp);
577: }
578: break;
579: case OPTION_SCALAR_ARRAY:
580: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
581: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
582: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
583: PetscStrcat(value,",");
584: PetscStrcat(value,tmp);
585: }
586: break;
587: case OPTION_BOOL:
588: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
589: break;
590: case OPTION_BOOL_ARRAY:
591: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
592: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
593: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
594: PetscStrcat(value,",");
595: PetscStrcat(value,tmp);
596: }
597: break;
598: case OPTION_FLIST:
599: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
600: break;
601: case OPTION_ELIST:
602: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
603: break;
604: case OPTION_STRING:
605: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
606: break;
607: case OPTION_STRING_ARRAY:
608: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
609: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
610: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
611: PetscStrcat(value,",");
612: PetscStrcat(value,tmp);
613: }
614: break;
615: }
616: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
617: }
618: if (PetscOptionsObject->next->type == OPTION_ELIST) {
619: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
620: }
621: PetscFree(PetscOptionsObject->next->text);
622: PetscFree(PetscOptionsObject->next->option);
623: PetscFree(PetscOptionsObject->next->man);
624: PetscFree(PetscOptionsObject->next->edata);
626: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
627: free(PetscOptionsObject->next->data);
628: } else {
629: PetscFree(PetscOptionsObject->next->data);
630: }
632: last = PetscOptionsObject->next;
633: PetscOptionsObject->next = PetscOptionsObject->next->next;
634: PetscFree(last);
635: }
636: PetscFree(PetscOptionsObject->prefix);
637: PetscOptionsObject->next = 0;
638: return(0);
639: }
641: /*@C
642: PetscOptionsEnum - Gets the enum value for a particular option in the database.
644: Logically Collective on the communicator passed in PetscOptionsBegin()
646: Input Parameters:
647: + opt - option name
648: . text - short string that describes the option
649: . man - manual page with additional information on option
650: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
651: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
652: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
653: $ value = defaultvalue
654: $ PetscOptionsEnum(..., value,&value,&flg);
655: $ if (flg) {
657: Output Parameter:
658: + value - the value to return
659: - set - PETSC_TRUE if found, else PETSC_FALSE
661: Level: beginner
663: Notes:
664: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
666: list is usually something like PCASMTypes or some other predefined list of enum names
668: If the user does not supply the option at all value is NOT changed. Thus
669: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
671: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
673: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
674: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
675: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
676: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
677: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
678: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
679: PetscOptionsFList(), PetscOptionsEList()
680: @*/
681: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
682: {
684: PetscInt ntext = 0;
685: PetscInt tval;
686: PetscBool tflg;
689: while (list[ntext++]) {
690: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
691: }
692: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
693: ntext -= 3;
694: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
695: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
696: if (tflg) *value = (PetscEnum)tval;
697: if (set) *set = tflg;
698: return(0);
699: }
701: /*@C
702: PetscOptionsEnumArray - Gets an array of enum values for a particular
703: option in the database.
705: Logically Collective on the communicator passed in PetscOptionsBegin()
707: Input Parameters:
708: + opt - the option one is seeking
709: . text - short string describing option
710: . man - manual page for option
711: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
712: - n - maximum number of values
714: Output Parameter:
715: + value - location to copy values
716: . n - actual number of values found
717: - set - PETSC_TRUE if found, else PETSC_FALSE
719: Level: beginner
721: Notes:
722: The array must be passed as a comma separated list.
724: There must be no intervening spaces between the values.
726: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
728: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
729: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
730: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
731: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
732: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
733: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
734: @*/
735: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
736: {
737: PetscInt i,nlist = 0;
738: PetscOptionItem amsopt;
739: PetscErrorCode ierr;
742: 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");
743: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
744: nlist -= 3; /* drop enum name, prefix, and null termination */
745: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
746: PetscEnum *vals;
747: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
748: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
749: amsopt->nlist = nlist;
750: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
751: amsopt->arraylength = *n;
752: vals = (PetscEnum*)amsopt->data;
753: for (i=0; i<*n; i++) vals[i] = value[i];
754: }
755: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
756: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
757: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
758: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
759: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
760: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
761: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
762: }
763: return(0);
764: }
766: /*@C
767: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
769: Logically Collective on the communicator passed in PetscOptionsBegin()
771: Input Parameters:
772: + opt - option name
773: . text - short string that describes the option
774: . man - manual page with additional information on option
775: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
776: $ PetscOptionsInt(..., obj->value,&object->value,...) or
777: $ value = defaultvalue
778: $ PetscOptionsInt(..., value,&value,&flg);
779: $ if (flg) {
780: - bound - the requested value should be large than this bound
782: Output Parameter:
783: + value - the integer value to return
784: - flg - PETSC_TRUE if found, else PETSC_FALSE
786: Notes:
787: If the user does not supply the option at all value is NOT changed. Thus
788: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
790: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
792: Errors if the supplied integer does not satisfy the bound
794: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
796: Level: beginner
798: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
799: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
800: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
801: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
802: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
803: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
804: PetscOptionsFList(), PetscOptionsEList()
805: @*/
807: /*@C
808: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
810: Logically Collective on the communicator passed in PetscOptionsBegin()
812: Input Parameters:
813: + opt - option name
814: . text - short string that describes the option
815: . man - manual page with additional information on option
816: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
817: $ PetscOptionsInt(..., obj->value,&object->value,...) or
818: $ value = defaultvalue
819: $ PetscOptionsInt(..., value,&value,&flg);
820: $ if (flg) {
821: . lb - the lower bound
822: - ub - the upper bound
824: Output Parameter:
825: + value - the integer value to return
826: - flg - PETSC_TRUE if found, else PETSC_FALSE
828: Notes:
829: If the user does not supply the option at all value is NOT changed. Thus
830: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
832: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
834: Errors if the supplied integer does not satisfy the range
836: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
838: Level: beginner
840: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
841: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsBoundedInt()
842: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
843: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
844: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
845: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
846: PetscOptionsFList(), PetscOptionsEList()
847: @*/
849: /*@C
850: PetscOptionsInt - Gets the integer value for a particular option in the database.
852: Logically Collective on the communicator passed in PetscOptionsBegin()
854: Input Parameters:
855: + opt - option name
856: . text - short string that describes the option
857: . man - manual page with additional information on option
858: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
859: $ PetscOptionsInt(..., obj->value,&object->value,...) or
860: $ value = defaultvalue
861: $ PetscOptionsInt(..., value,&value,&flg);
862: $ if (flg) {
864: Output Parameter:
865: + value - the integer value to return
866: - flg - PETSC_TRUE if found, else PETSC_FALSE
868: Notes:
869: If the user does not supply the option at all value is NOT changed. Thus
870: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
872: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
874: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
876: Level: beginner
878: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
879: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
880: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
881: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
882: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
883: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
884: PetscOptionsFList(), PetscOptionsEList()
885: @*/
886: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set,PetscInt lb,PetscInt ub)
887: {
888: PetscErrorCode ierr;
889: PetscOptionItem amsopt;
890: PetscBool wasset;
893: if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
894: if (currentvalue > ub ) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",currentvalue,ub);
895: if (!PetscOptionsObject->count) {
896: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
897: PetscMalloc(sizeof(PetscInt),&amsopt->data);
898: *(PetscInt*)amsopt->data = currentvalue;
900: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
901: if (wasset) {
902: *(PetscInt*)amsopt->data = currentvalue;
903: }
904: }
905: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
906: if (wasset && *value < lb ) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
907: if (wasset && *value > ub ) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
908: if (set) *set = wasset;
909: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
910: (*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));
911: }
912: return(0);
913: }
915: /*@C
916: PetscOptionsString - Gets the string value for a particular option in the database.
918: Logically Collective on the communicator passed in PetscOptionsBegin()
920: Input Parameters:
921: + opt - option name
922: . text - short string that describes the option
923: . man - manual page with additional information on option
924: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
925: - len - length of the result string including null terminator
927: Output Parameter:
928: + value - the value to return
929: - flg - PETSC_TRUE if found, else PETSC_FALSE
931: Level: beginner
933: Notes:
934: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
936: 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).
938: If the user does not supply the option at all value is NOT changed. Thus
939: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
941: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
944: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
945: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
946: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
947: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
948: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
949: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
950: PetscOptionsFList(), PetscOptionsEList()
951: @*/
952: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
953: {
954: PetscErrorCode ierr;
955: PetscOptionItem amsopt;
956: PetscBool lset;
959: if (!PetscOptionsObject->count) {
960: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
961: /* must use system malloc since SAWs may free this */
962: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
963: }
964: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
965: if (set) *set = lset;
966: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
967: (*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));
968: }
969: return(0);
970: }
972: /*@C
973: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
975: Logically Collective on the communicator passed in PetscOptionsBegin()
977: Input Parameters:
978: + opt - option name
979: . text - short string that describes the option
980: . man - manual page with additional information on option
981: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
982: $ PetscOptionsReal(..., obj->value,&object->value,...) or
983: $ value = defaultvalue
984: $ PetscOptionsReal(..., value,&value,&flg);
985: $ if (flg) {
987: Output Parameter:
988: + value - the value to return
989: - flg - PETSC_TRUE if found, else PETSC_FALSE
991: Notes:
992: If the user does not supply the option at all value is NOT changed. Thus
993: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
995: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
997: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
999: Level: beginner
1001: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1002: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1003: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1004: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1005: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1006: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1007: PetscOptionsFList(), PetscOptionsEList()
1008: @*/
1009: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1010: {
1011: PetscErrorCode ierr;
1012: PetscOptionItem amsopt;
1013: PetscBool lset;
1016: if (!PetscOptionsObject->count) {
1017: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1018: PetscMalloc(sizeof(PetscReal),&amsopt->data);
1020: *(PetscReal*)amsopt->data = currentvalue;
1021: }
1022: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1023: if (set) *set = lset;
1024: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1025: (*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));
1026: }
1027: return(0);
1028: }
1030: /*@C
1031: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
1033: Logically Collective on the communicator passed in PetscOptionsBegin()
1035: Input Parameters:
1036: + opt - option name
1037: . text - short string that describes the option
1038: . man - manual page with additional information on option
1039: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1040: $ PetscOptionsScalar(..., obj->value,&object->value,...) or
1041: $ value = defaultvalue
1042: $ PetscOptionsScalar(..., value,&value,&flg);
1043: $ if (flg) {
1046: Output Parameter:
1047: + value - the value to return
1048: - flg - PETSC_TRUE if found, else PETSC_FALSE
1050: Notes:
1051: If the user does not supply the option at all value is NOT changed. Thus
1052: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1054: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1056: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1058: Level: beginner
1060: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1061: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1062: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1063: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1064: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1065: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1066: PetscOptionsFList(), PetscOptionsEList()
1067: @*/
1068: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1069: {
1073: #if !defined(PETSC_USE_COMPLEX)
1074: PetscOptionsReal(opt,text,man,currentvalue,value,set);
1075: #else
1076: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1077: #endif
1078: return(0);
1079: }
1081: /*@C
1082: 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
1083: its value is set to false.
1085: Logically Collective on the communicator passed in PetscOptionsBegin()
1087: Input Parameters:
1088: + opt - option name
1089: . text - short string that describes the option
1090: - man - manual page with additional information on option
1092: Output Parameter:
1093: . flg - PETSC_TRUE if found, else PETSC_FALSE
1095: Level: beginner
1097: Notes:
1098: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1100: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1101: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1102: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1103: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1104: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1105: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1106: PetscOptionsFList(), PetscOptionsEList()
1107: @*/
1108: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1109: {
1110: PetscErrorCode ierr;
1111: PetscOptionItem amsopt;
1114: if (!PetscOptionsObject->count) {
1115: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1116: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1118: *(PetscBool*)amsopt->data = PETSC_FALSE;
1119: }
1120: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1121: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1122: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1123: }
1124: return(0);
1125: }
1127: /*@C
1128: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1130: Logically Collective on the communicator passed in PetscOptionsBegin()
1132: Input Parameters:
1133: + opt - option name
1134: . text - short string that describes the option
1135: . man - manual page with additional information on option
1136: . list - the possible choices
1137: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1138: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1139: $ if (flg) {
1140: - len - the length of the character array value
1142: Output Parameter:
1143: + value - the value to return
1144: - set - PETSC_TRUE if found, else PETSC_FALSE
1146: Level: intermediate
1148: Notes:
1149: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1151: If the user does not supply the option at all value is NOT changed. Thus
1152: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1154: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1156: See PetscOptionsEList() for when the choices are given in a string array
1158: To get a listing of all currently specified options,
1159: see PetscOptionsView() or PetscOptionsGetAll()
1161: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1163: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1164: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1165: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1166: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1167: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1168: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1169: @*/
1170: 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)
1171: {
1172: PetscErrorCode ierr;
1173: PetscOptionItem amsopt;
1174: PetscBool lset;
1177: if (!PetscOptionsObject->count) {
1178: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1179: /* must use system malloc since SAWs may free this */
1180: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1181: amsopt->flist = list;
1182: }
1183: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1184: if (set) *set = lset;
1185: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1186: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1187: }
1188: return(0);
1189: }
1191: /*@C
1192: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1194: Logically Collective on the communicator passed in PetscOptionsBegin()
1196: Input Parameters:
1197: + opt - option name
1198: . ltext - short string that describes the option
1199: . man - manual page with additional information on option
1200: . list - the possible choices (one of these must be selected, anything else is invalid)
1201: . ntext - number of choices
1202: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1203: $ PetscOptionsElist(..., obj->value,&value,&flg);
1204: $ if (flg) {
1207: Output Parameter:
1208: + value - the index of the value to return
1209: - set - PETSC_TRUE if found, else PETSC_FALSE
1211: Level: intermediate
1213: Notes:
1214: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1216: If the user does not supply the option at all value is NOT changed. Thus
1217: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1219: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1221: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1222: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1223: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1224: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1225: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1226: PetscOptionsFList(), PetscOptionsEnum()
1227: @*/
1228: 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)
1229: {
1230: PetscErrorCode ierr;
1231: PetscInt i;
1232: PetscOptionItem amsopt;
1233: PetscBool lset;
1236: if (!PetscOptionsObject->count) {
1237: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1238: /* must use system malloc since SAWs may free this */
1239: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1240: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1241: amsopt->nlist = ntext;
1242: }
1243: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1244: if (set) *set = lset;
1245: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1246: (*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);
1247: for (i=0; i<ntext; i++) {
1248: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1249: }
1250: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1251: }
1252: return(0);
1253: }
1255: /*@C
1256: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1257: which at most a single value can be true.
1259: Logically Collective on the communicator passed in PetscOptionsBegin()
1261: Input Parameters:
1262: + opt - option name
1263: . text - short string that describes the option
1264: - man - manual page with additional information on option
1266: Output Parameter:
1267: . flg - whether that option was set or not
1269: Level: intermediate
1271: Notes:
1272: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1274: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1276: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1277: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1278: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1279: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1280: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1281: PetscOptionsFList(), PetscOptionsEList()
1282: @*/
1283: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1284: {
1285: PetscErrorCode ierr;
1286: PetscOptionItem amsopt;
1289: if (!PetscOptionsObject->count) {
1290: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1291: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1293: *(PetscBool*)amsopt->data = PETSC_FALSE;
1294: }
1295: *flg = PETSC_FALSE;
1296: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1297: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1298: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1299: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1300: }
1301: return(0);
1302: }
1304: /*@C
1305: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1306: which at most a single value can be true.
1308: Logically Collective on the communicator passed in PetscOptionsBegin()
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 - PETSC_TRUE if found, else PETSC_FALSE
1318: Level: intermediate
1320: Notes:
1321: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1323: Must follow a PetscOptionsBoolGroupBegin() and preceded a 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: @*/
1332: PetscErrorCode PetscOptionsBoolGroup_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," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1348: }
1349: return(0);
1350: }
1352: /*@C
1353: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1354: which at most a single value can be true.
1356: Logically Collective on the communicator passed in PetscOptionsBegin()
1358: Input Parameters:
1359: + opt - option name
1360: . text - short string that describes the option
1361: - man - manual page with additional information on option
1363: Output Parameter:
1364: . flg - PETSC_TRUE if found, else PETSC_FALSE
1366: Level: intermediate
1368: Notes:
1369: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1371: Must follow a PetscOptionsBoolGroupBegin()
1373: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1374: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1375: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1376: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1377: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1378: PetscOptionsFList(), PetscOptionsEList()
1379: @*/
1380: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1381: {
1382: PetscErrorCode ierr;
1383: PetscOptionItem amsopt;
1386: if (!PetscOptionsObject->count) {
1387: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1388: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1390: *(PetscBool*)amsopt->data = PETSC_FALSE;
1391: }
1392: *flg = PETSC_FALSE;
1393: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1394: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1395: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1396: }
1397: return(0);
1398: }
1400: /*@C
1401: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1403: Logically Collective on the communicator passed in PetscOptionsBegin()
1405: Input Parameters:
1406: + opt - option name
1407: . text - short string that describes the option
1408: . man - manual page with additional information on option
1409: - currentvalue - the current value
1411: Output Parameter:
1412: + flg - PETSC_TRUE or PETSC_FALSE
1413: - set - PETSC_TRUE if found, else PETSC_FALSE
1415: Notes:
1416: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1417: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1419: 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
1420: is equivalent to -requested_bool true
1422: If the user does not supply the option at all flg is NOT changed. Thus
1423: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1425: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1427: Level: beginner
1429: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1430: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1431: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1432: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1433: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1434: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1435: PetscOptionsFList(), PetscOptionsEList()
1436: @*/
1437: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1438: {
1439: PetscErrorCode ierr;
1440: PetscBool iset;
1441: PetscOptionItem amsopt;
1444: if (!PetscOptionsObject->count) {
1445: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1446: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1448: *(PetscBool*)amsopt->data = currentvalue;
1449: }
1450: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1451: if (set) *set = iset;
1452: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1453: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1454: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1455: }
1456: return(0);
1457: }
1459: /*@C
1460: PetscOptionsRealArray - Gets an array of double values for a particular
1461: option in the database. The values must be separated with commas with
1462: no intervening spaces.
1464: Logically Collective on the communicator passed in PetscOptionsBegin()
1466: Input Parameters:
1467: + opt - the option one is seeking
1468: . text - short string describing option
1469: . man - manual page for option
1470: - nmax - maximum number of values
1472: Output Parameter:
1473: + value - location to copy values
1474: . nmax - actual number of values found
1475: - set - PETSC_TRUE if found, else PETSC_FALSE
1477: Level: beginner
1479: Notes:
1480: The user should pass in an array of doubles
1482: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1484: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1485: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1486: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1487: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1488: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1489: PetscOptionsFList(), PetscOptionsEList()
1490: @*/
1491: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1492: {
1493: PetscErrorCode ierr;
1494: PetscInt i;
1495: PetscOptionItem amsopt;
1498: if (!PetscOptionsObject->count) {
1499: PetscReal *vals;
1501: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1502: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1503: vals = (PetscReal*)amsopt->data;
1504: for (i=0; i<*n; i++) vals[i] = value[i];
1505: amsopt->arraylength = *n;
1506: }
1507: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1508: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1509: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1510: for (i=1; i<*n; i++) {
1511: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1512: }
1513: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1514: }
1515: return(0);
1516: }
1518: /*@C
1519: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1520: option in the database. The values must be separated with commas with
1521: no intervening spaces.
1523: Logically Collective on the communicator passed in PetscOptionsBegin()
1525: Input Parameters:
1526: + opt - the option one is seeking
1527: . text - short string describing option
1528: . man - manual page for option
1529: - nmax - maximum number of values
1531: Output Parameter:
1532: + value - location to copy values
1533: . nmax - actual number of values found
1534: - set - PETSC_TRUE if found, else PETSC_FALSE
1536: Level: beginner
1538: Notes:
1539: The user should pass in an array of doubles
1541: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1543: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1544: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1545: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1546: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1547: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1548: PetscOptionsFList(), PetscOptionsEList()
1549: @*/
1550: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1551: {
1552: PetscErrorCode ierr;
1553: PetscInt i;
1554: PetscOptionItem amsopt;
1557: if (!PetscOptionsObject->count) {
1558: PetscScalar *vals;
1560: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1561: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1562: vals = (PetscScalar*)amsopt->data;
1563: for (i=0; i<*n; i++) vals[i] = value[i];
1564: amsopt->arraylength = *n;
1565: }
1566: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1567: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1568: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1569: for (i=1; i<*n; i++) {
1570: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1571: }
1572: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1573: }
1574: return(0);
1575: }
1577: /*@C
1578: PetscOptionsIntArray - Gets an array of integers for a particular
1579: option in the database.
1581: Logically Collective on the communicator passed in PetscOptionsBegin()
1583: Input Parameters:
1584: + opt - the option one is seeking
1585: . text - short string describing option
1586: . man - manual page for option
1587: - n - maximum number of values
1589: Output Parameter:
1590: + value - location to copy values
1591: . n - actual number of values found
1592: - set - PETSC_TRUE if found, else PETSC_FALSE
1594: Level: beginner
1596: Notes:
1597: The array can be passed as
1598: a comma separated list: 0,1,2,3,4,5,6,7
1599: a range (start-end+1): 0-8
1600: a range with given increment (start-end+1:inc): 0-7:2
1601: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1603: There must be no intervening spaces between the values.
1605: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1607: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1608: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1609: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1610: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1611: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1612: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1613: @*/
1614: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1615: {
1617: PetscInt i;
1618: PetscOptionItem amsopt;
1621: if (!PetscOptionsObject->count) {
1622: PetscInt *vals;
1624: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1625: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1626: vals = (PetscInt*)amsopt->data;
1627: for (i=0; i<*n; i++) vals[i] = value[i];
1628: amsopt->arraylength = *n;
1629: }
1630: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1631: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1632: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1633: for (i=1; i<*n; i++) {
1634: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1635: }
1636: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1637: }
1638: return(0);
1639: }
1641: /*@C
1642: PetscOptionsStringArray - Gets an array of string values for a particular
1643: option in the database. The values must be separated with commas with
1644: no intervening spaces.
1646: Logically Collective on the communicator passed in PetscOptionsBegin()
1648: Input Parameters:
1649: + opt - the option one is seeking
1650: . text - short string describing option
1651: . man - manual page for option
1652: - nmax - maximum number of strings
1654: Output Parameter:
1655: + value - location to copy strings
1656: . nmax - actual number of strings found
1657: - set - PETSC_TRUE if found, else PETSC_FALSE
1659: Level: beginner
1661: Notes:
1662: The user should pass in an array of pointers to char, to hold all the
1663: strings returned by this function.
1665: The user is responsible for deallocating the strings that are
1666: returned. The Fortran interface for this routine is not supported.
1668: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1670: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1671: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1672: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1673: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1674: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1675: PetscOptionsFList(), PetscOptionsEList()
1676: @*/
1677: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1678: {
1679: PetscErrorCode ierr;
1680: PetscOptionItem amsopt;
1683: if (!PetscOptionsObject->count) {
1684: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1685: PetscMalloc1(*nmax,(char**)&amsopt->data);
1687: amsopt->arraylength = *nmax;
1688: }
1689: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1690: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1691: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1692: }
1693: return(0);
1694: }
1696: /*@C
1697: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1698: option in the database. The values must be separated with commas with
1699: no intervening spaces.
1701: Logically Collective on the communicator passed in PetscOptionsBegin()
1703: Input Parameters:
1704: + opt - the option one is seeking
1705: . text - short string describing option
1706: . man - manual page for option
1707: - nmax - maximum number of values
1709: Output Parameter:
1710: + value - location to copy values
1711: . nmax - actual number of values found
1712: - set - PETSC_TRUE if found, else PETSC_FALSE
1714: Level: beginner
1716: Notes:
1717: The user should pass in an array of doubles
1719: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1721: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1722: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1723: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1724: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1725: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1726: PetscOptionsFList(), PetscOptionsEList()
1727: @*/
1728: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1729: {
1730: PetscErrorCode ierr;
1731: PetscInt i;
1732: PetscOptionItem amsopt;
1735: if (!PetscOptionsObject->count) {
1736: PetscBool *vals;
1738: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1739: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1740: vals = (PetscBool*)amsopt->data;
1741: for (i=0; i<*n; i++) vals[i] = value[i];
1742: amsopt->arraylength = *n;
1743: }
1744: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1745: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1746: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1747: for (i=1; i<*n; i++) {
1748: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1749: }
1750: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1751: }
1752: return(0);
1753: }
1755: /*@C
1756: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1758: Logically Collective on the communicator passed in PetscOptionsBegin()
1760: Input Parameters:
1761: + opt - option name
1762: . text - short string that describes the option
1763: - man - manual page with additional information on option
1765: Output Parameter:
1766: + viewer - the viewer
1767: - set - PETSC_TRUE if found, else PETSC_FALSE
1769: Level: beginner
1771: Notes:
1772: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1774: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1776: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1777: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1778: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1779: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1780: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1781: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1782: PetscOptionsFList(), PetscOptionsEList()
1783: @*/
1784: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1785: {
1786: PetscErrorCode ierr;
1787: PetscOptionItem amsopt;
1790: if (!PetscOptionsObject->count) {
1791: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1792: /* must use system malloc since SAWs may free this */
1793: PetscStrdup("",(char**)&amsopt->data);
1794: }
1795: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1796: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1797: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1798: }
1799: return(0);
1800: }
1803: /*@C
1804: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1805: in KSPSetFromOptions_GMRES().
1807: Logically Collective on the communicator passed in PetscOptionsBegin()
1809: Input Parameter:
1810: . head - the heading text
1813: Level: intermediate
1815: Notes:
1816: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1818: Can be followed by a call to PetscOptionsTail() in the same function.
1820: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1821: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1822: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1823: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1824: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1825: PetscOptionsFList(), PetscOptionsEList()
1826: @*/
1827: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1828: {
1832: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1833: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1834: }
1835: return(0);
1836: }