Actual source code: aoptions.c
petsc-3.11.4 2019-09-28
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 on MPI_Comm
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);
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=\"http://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
375: "<script type=\"text/javascript\" src=\"http://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: Concepts: options database
665: Notes:
666: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
668: list is usually something like PCASMTypes or some other predefined list of enum names
670: If the user does not supply the option at all value is NOT changed. Thus
671: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
673: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
675: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
676: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
677: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
678: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
679: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
680: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
681: PetscOptionsFList(), PetscOptionsEList()
682: @*/
683: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
684: {
686: PetscInt ntext = 0;
687: PetscInt tval;
688: PetscBool tflg;
691: while (list[ntext++]) {
692: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
693: }
694: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
695: ntext -= 3;
696: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
697: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
698: if (tflg) *value = (PetscEnum)tval;
699: if (set) *set = tflg;
700: return(0);
701: }
703: /*@C
704: PetscOptionsEnumArray - Gets an array of enum values for a particular
705: option in the database.
707: Logically Collective on the communicator passed in PetscOptionsBegin()
709: Input Parameters:
710: + opt - the option one is seeking
711: . text - short string describing option
712: . man - manual page for option
713: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
714: - n - maximum number of values
716: Output Parameter:
717: + value - location to copy values
718: . n - actual number of values found
719: - set - PETSC_TRUE if found, else PETSC_FALSE
721: Level: beginner
723: Notes:
724: The array must be passed as a comma separated list.
726: There must be no intervening spaces between the values.
728: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
730: Concepts: options database^array of enums
732: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
733: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
734: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
735: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
736: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
737: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
738: @*/
739: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
740: {
741: PetscInt i,nlist = 0;
742: PetscOptionItem amsopt;
743: PetscErrorCode ierr;
746: 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");
747: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
748: nlist -= 3; /* drop enum name, prefix, and null termination */
749: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
750: PetscEnum *vals;
751: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
752: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
753: amsopt->nlist = nlist;
754: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
755: amsopt->arraylength = *n;
756: vals = (PetscEnum*)amsopt->data;
757: for (i=0; i<*n; i++) vals[i] = value[i];
758: }
759: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
760: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
761: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
762: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
763: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
764: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
765: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
766: }
767: return(0);
768: }
770: /* -------------------------------------------------------------------------------------------------------------*/
771: /*@C
772: PetscOptionsInt - Gets the integer value for a particular option in the database.
774: Logically Collective on the communicator passed in PetscOptionsBegin()
776: Input Parameters:
777: + opt - option name
778: . text - short string that describes the option
779: . man - manual page with additional information on option
780: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
781: $ PetscOptionsInt(..., obj->value,&object->value,...) or
782: $ value = defaultvalue
783: $ PetscOptionsInt(..., value,&value,&flg);
784: $ if (flg) {
786: Output Parameter:
787: + value - the integer value to return
788: - flg - PETSC_TRUE if found, else PETSC_FALSE
790: Notes:
791: If the user does not supply the option at all value is NOT changed. Thus
792: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
794: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
796: Level: beginner
798: Concepts: options database^has int
800: Notes:
801: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
803: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
804: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
805: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
806: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
807: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
808: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
809: PetscOptionsFList(), PetscOptionsEList()
810: @*/
811: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set)
812: {
813: PetscErrorCode ierr;
814: PetscOptionItem amsopt;
815: PetscBool wasset;
818: if (!PetscOptionsObject->count) {
819: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
820: PetscMalloc(sizeof(PetscInt),&amsopt->data);
821: *(PetscInt*)amsopt->data = currentvalue;
823: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
824: if (wasset) {
825: *(PetscInt*)amsopt->data = currentvalue;
826: }
827: }
828: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
829: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
830: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
831: }
832: return(0);
833: }
835: /*@C
836: PetscOptionsString - Gets the string value for a particular option in the database.
838: Logically Collective on the communicator passed in PetscOptionsBegin()
840: Input Parameters:
841: + opt - option name
842: . text - short string that describes the option
843: . man - manual page with additional information on option
844: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
845: - len - length of the result string including null terminator
847: Output Parameter:
848: + value - the value to return
849: - flg - PETSC_TRUE if found, else PETSC_FALSE
851: Level: beginner
853: Concepts: options database^has int
855: Notes:
856: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
858: 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).
860: If the user does not supply the option at all value is NOT changed. Thus
861: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
863: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
866: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
867: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
868: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
869: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
870: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
871: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
872: PetscOptionsFList(), PetscOptionsEList()
873: @*/
874: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
875: {
876: PetscErrorCode ierr;
877: PetscOptionItem amsopt;
880: if (!PetscOptionsObject->count) {
881: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
882: /* must use system malloc since SAWs may free this */
883: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
884: }
885: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
886: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
887: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
888: }
889: return(0);
890: }
892: /*@C
893: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
895: Logically Collective on the communicator passed in PetscOptionsBegin()
897: Input Parameters:
898: + opt - option name
899: . text - short string that describes the option
900: . man - manual page with additional information on option
901: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
902: $ PetscOptionsReal(..., obj->value,&object->value,...) or
903: $ value = defaultvalue
904: $ PetscOptionsReal(..., value,&value,&flg);
905: $ if (flg) {
907: Output Parameter:
908: + value - the value to return
909: - flg - PETSC_TRUE if found, else PETSC_FALSE
911: Notes:
912: If the user does not supply the option at all value is NOT changed. Thus
913: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
915: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
917: Level: beginner
919: Concepts: options database^has int
921: Notes:
922: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
924: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
925: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
926: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
927: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
928: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
929: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
930: PetscOptionsFList(), PetscOptionsEList()
931: @*/
932: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
933: {
934: PetscErrorCode ierr;
935: PetscOptionItem amsopt;
938: if (!PetscOptionsObject->count) {
939: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
940: PetscMalloc(sizeof(PetscReal),&amsopt->data);
942: *(PetscReal*)amsopt->data = currentvalue;
943: }
944: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
945: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
946: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
947: }
948: return(0);
949: }
951: /*@C
952: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
954: Logically Collective on the communicator passed in PetscOptionsBegin()
956: Input Parameters:
957: + opt - option name
958: . text - short string that describes the option
959: . man - manual page with additional information on option
960: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
961: $ PetscOptionsScalar(..., obj->value,&object->value,...) or
962: $ value = defaultvalue
963: $ PetscOptionsScalar(..., value,&value,&flg);
964: $ if (flg) {
967: Output Parameter:
968: + value - the value to return
969: - flg - PETSC_TRUE if found, else PETSC_FALSE
971: Notes:
972: If the user does not supply the option at all value is NOT changed. Thus
973: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
975: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
977: Level: beginner
979: Concepts: options database^has int
981: Notes:
982: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
984: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
985: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
986: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
987: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
988: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
989: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
990: PetscOptionsFList(), PetscOptionsEList()
991: @*/
992: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
993: {
997: #if !defined(PETSC_USE_COMPLEX)
998: PetscOptionsReal(opt,text,man,currentvalue,value,set);
999: #else
1000: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1001: #endif
1002: return(0);
1003: }
1005: /*@C
1006: 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
1007: its value is set to false.
1009: Logically Collective on the communicator passed in PetscOptionsBegin()
1011: Input Parameters:
1012: + opt - option name
1013: . text - short string that describes the option
1014: - man - manual page with additional information on option
1016: Output Parameter:
1017: . flg - PETSC_TRUE if found, else PETSC_FALSE
1019: Level: beginner
1021: Concepts: options database^has int
1023: Notes:
1024: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1026: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1027: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1028: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1029: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1030: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1031: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1032: PetscOptionsFList(), PetscOptionsEList()
1033: @*/
1034: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1035: {
1036: PetscErrorCode ierr;
1037: PetscOptionItem amsopt;
1040: if (!PetscOptionsObject->count) {
1041: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1042: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1044: *(PetscBool*)amsopt->data = PETSC_FALSE;
1045: }
1046: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1047: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1048: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1049: }
1050: return(0);
1051: }
1053: /*@C
1054: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1056: Logically Collective on the communicator passed in PetscOptionsBegin()
1058: Input Parameters:
1059: + opt - option name
1060: . text - short string that describes the option
1061: . man - manual page with additional information on option
1062: . list - the possible choices
1063: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1064: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1065: $ if (flg) {
1066: - len - the length of the character array value
1068: Output Parameter:
1069: + value - the value to return
1070: - set - PETSC_TRUE if found, else PETSC_FALSE
1072: Level: intermediate
1074: Notes:
1075: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1077: If the user does not supply the option at all value is NOT changed. Thus
1078: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1080: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1082: See PetscOptionsEList() for when the choices are given in a string array
1084: To get a listing of all currently specified options,
1085: see PetscOptionsView() or PetscOptionsGetAll()
1087: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1089: Concepts: options database^list
1091: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1092: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1093: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1094: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1095: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1096: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1097: @*/
1098: 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)
1099: {
1100: PetscErrorCode ierr;
1101: PetscOptionItem amsopt;
1104: if (!PetscOptionsObject->count) {
1105: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1106: /* must use system malloc since SAWs may free this */
1107: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1108: amsopt->flist = list;
1109: }
1110: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1111: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1112: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1113: }
1114: return(0);
1115: }
1117: /*@C
1118: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1120: Logically Collective on the communicator passed in PetscOptionsBegin()
1122: Input Parameters:
1123: + opt - option name
1124: . ltext - short string that describes the option
1125: . man - manual page with additional information on option
1126: . list - the possible choices (one of these must be selected, anything else is invalid)
1127: . ntext - number of choices
1128: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1129: $ PetscOptionsElist(..., obj->value,&value,&flg);
1130: $ if (flg) {
1133: Output Parameter:
1134: + value - the index of the value to return
1135: - set - PETSC_TRUE if found, else PETSC_FALSE
1137: Level: intermediate
1139: Notes:
1140: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1142: If the user does not supply the option at all value is NOT changed. Thus
1143: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1145: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1147: Concepts: options database^list
1149: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1150: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1151: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1152: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1153: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1154: PetscOptionsFList(), PetscOptionsEnum()
1155: @*/
1156: 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)
1157: {
1158: PetscErrorCode ierr;
1159: PetscInt i;
1160: PetscOptionItem amsopt;
1163: if (!PetscOptionsObject->count) {
1164: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1165: /* must use system malloc since SAWs may free this */
1166: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1167: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1168: amsopt->nlist = ntext;
1169: }
1170: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1171: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1172: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1173: for (i=0; i<ntext; i++) {
1174: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1175: }
1176: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1177: }
1178: return(0);
1179: }
1181: /*@C
1182: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1183: which at most a single value can be true.
1185: Logically Collective on the communicator passed in PetscOptionsBegin()
1187: Input Parameters:
1188: + opt - option name
1189: . text - short string that describes the option
1190: - man - manual page with additional information on option
1192: Output Parameter:
1193: . flg - whether that option was set or not
1195: Level: intermediate
1197: Notes:
1198: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1200: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1202: Concepts: options database^logical group
1204: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1205: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1206: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1207: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1208: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1209: PetscOptionsFList(), PetscOptionsEList()
1210: @*/
1211: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1212: {
1213: PetscErrorCode ierr;
1214: PetscOptionItem amsopt;
1217: if (!PetscOptionsObject->count) {
1218: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1219: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1221: *(PetscBool*)amsopt->data = PETSC_FALSE;
1222: }
1223: *flg = PETSC_FALSE;
1224: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1225: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1226: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1227: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1228: }
1229: return(0);
1230: }
1232: /*@C
1233: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1234: which at most a single value can be true.
1236: Logically Collective on the communicator passed in PetscOptionsBegin()
1238: Input Parameters:
1239: + opt - option name
1240: . text - short string that describes the option
1241: - man - manual page with additional information on option
1243: Output Parameter:
1244: . flg - PETSC_TRUE if found, else PETSC_FALSE
1246: Level: intermediate
1248: Notes:
1249: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1251: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1253: Concepts: options database^logical group
1255: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1256: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1257: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1258: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1259: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1260: PetscOptionsFList(), PetscOptionsEList()
1261: @*/
1262: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1263: {
1264: PetscErrorCode ierr;
1265: PetscOptionItem amsopt;
1268: if (!PetscOptionsObject->count) {
1269: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1270: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1272: *(PetscBool*)amsopt->data = PETSC_FALSE;
1273: }
1274: *flg = PETSC_FALSE;
1275: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1276: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1277: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1278: }
1279: return(0);
1280: }
1282: /*@C
1283: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1284: which at most a single value can be true.
1286: Logically Collective on the communicator passed in PetscOptionsBegin()
1288: Input Parameters:
1289: + opt - option name
1290: . text - short string that describes the option
1291: - man - manual page with additional information on option
1293: Output Parameter:
1294: . flg - PETSC_TRUE if found, else PETSC_FALSE
1296: Level: intermediate
1298: Notes:
1299: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1301: Must follow a PetscOptionsBoolGroupBegin()
1303: Concepts: options database^logical group
1305: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1306: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1307: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1308: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1309: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1310: PetscOptionsFList(), PetscOptionsEList()
1311: @*/
1312: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1313: {
1314: PetscErrorCode ierr;
1315: PetscOptionItem amsopt;
1318: if (!PetscOptionsObject->count) {
1319: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1320: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1322: *(PetscBool*)amsopt->data = PETSC_FALSE;
1323: }
1324: *flg = PETSC_FALSE;
1325: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1326: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1327: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1328: }
1329: return(0);
1330: }
1332: /*@C
1333: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1335: Logically Collective on the communicator passed in PetscOptionsBegin()
1337: Input Parameters:
1338: + opt - option name
1339: . text - short string that describes the option
1340: . man - manual page with additional information on option
1341: - currentvalue - the current value
1343: Output Parameter:
1344: . flg - PETSC_TRUE or PETSC_FALSE
1345: . set - PETSC_TRUE if found, else PETSC_FALSE
1347: Notes:
1348: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1349: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1351: 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
1352: is equivalent to -requested_bool true
1354: If the user does not supply the option at all flg is NOT changed. Thus
1355: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1357: Level: beginner
1359: Concepts: options database^logical
1361: Notes:
1362: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1364: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1365: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1366: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1367: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1368: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1369: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1370: PetscOptionsFList(), PetscOptionsEList()
1371: @*/
1372: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1373: {
1374: PetscErrorCode ierr;
1375: PetscBool iset;
1376: PetscOptionItem amsopt;
1379: if (!PetscOptionsObject->count) {
1380: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1381: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1383: *(PetscBool*)amsopt->data = currentvalue;
1384: }
1385: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1386: if (set) *set = iset;
1387: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1388: const char *v = PetscBools[currentvalue];
1389: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1390: }
1391: return(0);
1392: }
1394: /*@C
1395: PetscOptionsRealArray - Gets an array of double values for a particular
1396: option in the database. The values must be separated with commas with
1397: no intervening spaces.
1399: Logically Collective on the communicator passed in PetscOptionsBegin()
1401: Input Parameters:
1402: + opt - the option one is seeking
1403: . text - short string describing option
1404: . man - manual page for option
1405: - nmax - maximum number of values
1407: Output Parameter:
1408: + value - location to copy values
1409: . nmax - actual number of values found
1410: - set - PETSC_TRUE if found, else PETSC_FALSE
1412: Level: beginner
1414: Notes:
1415: The user should pass in an array of doubles
1417: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1419: Concepts: options database^array of strings
1421: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1422: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1423: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1424: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1425: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1426: PetscOptionsFList(), PetscOptionsEList()
1427: @*/
1428: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1429: {
1430: PetscErrorCode ierr;
1431: PetscInt i;
1432: PetscOptionItem amsopt;
1435: if (!PetscOptionsObject->count) {
1436: PetscReal *vals;
1438: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1439: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1440: vals = (PetscReal*)amsopt->data;
1441: for (i=0; i<*n; i++) vals[i] = value[i];
1442: amsopt->arraylength = *n;
1443: }
1444: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1445: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1446: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1447: for (i=1; i<*n; i++) {
1448: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1449: }
1450: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1451: }
1452: return(0);
1453: }
1455: /*@C
1456: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1457: option in the database. The values must be separated with commas with
1458: no intervening spaces.
1460: Logically Collective on the communicator passed in PetscOptionsBegin()
1462: Input Parameters:
1463: + opt - the option one is seeking
1464: . text - short string describing option
1465: . man - manual page for option
1466: - nmax - maximum number of values
1468: Output Parameter:
1469: + value - location to copy values
1470: . nmax - actual number of values found
1471: - set - PETSC_TRUE if found, else PETSC_FALSE
1473: Level: beginner
1475: Notes:
1476: The user should pass in an array of doubles
1478: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1480: Concepts: options database^array of strings
1482: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1483: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1484: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1485: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1486: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1487: PetscOptionsFList(), PetscOptionsEList()
1488: @*/
1489: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1490: {
1491: PetscErrorCode ierr;
1492: PetscInt i;
1493: PetscOptionItem amsopt;
1496: if (!PetscOptionsObject->count) {
1497: PetscScalar *vals;
1499: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1500: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1501: vals = (PetscScalar*)amsopt->data;
1502: for (i=0; i<*n; i++) vals[i] = value[i];
1503: amsopt->arraylength = *n;
1504: }
1505: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1506: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1507: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1508: for (i=1; i<*n; i++) {
1509: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1510: }
1511: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1512: }
1513: return(0);
1514: }
1516: /*@C
1517: PetscOptionsIntArray - Gets an array of integers for a particular
1518: option in the database.
1520: Logically Collective on the communicator passed in PetscOptionsBegin()
1522: Input Parameters:
1523: + opt - the option one is seeking
1524: . text - short string describing option
1525: . man - manual page for option
1526: - n - maximum number of values
1528: Output Parameter:
1529: + value - location to copy values
1530: . n - actual number of values found
1531: - set - PETSC_TRUE if found, else PETSC_FALSE
1533: Level: beginner
1535: Notes:
1536: The array can be passed as
1537: a comma separated list: 0,1,2,3,4,5,6,7
1538: a range (start-end+1): 0-8
1539: a range with given increment (start-end+1:inc): 0-7:2
1540: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1542: There must be no intervening spaces between the values.
1544: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1546: Concepts: options database^array of ints
1548: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1549: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1550: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1551: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1552: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1553: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1554: @*/
1555: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1556: {
1558: PetscInt i;
1559: PetscOptionItem amsopt;
1562: if (!PetscOptionsObject->count) {
1563: PetscInt *vals;
1565: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1566: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1567: vals = (PetscInt*)amsopt->data;
1568: for (i=0; i<*n; i++) vals[i] = value[i];
1569: amsopt->arraylength = *n;
1570: }
1571: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1572: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1573: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1574: for (i=1; i<*n; i++) {
1575: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1576: }
1577: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1578: }
1579: return(0);
1580: }
1582: /*@C
1583: PetscOptionsStringArray - Gets an array of string values for a particular
1584: option in the database. The values must be separated with commas with
1585: no intervening spaces.
1587: Logically Collective on the communicator passed in PetscOptionsBegin()
1589: Input Parameters:
1590: + opt - the option one is seeking
1591: . text - short string describing option
1592: . man - manual page for option
1593: - nmax - maximum number of strings
1595: Output Parameter:
1596: + value - location to copy strings
1597: . nmax - actual number of strings found
1598: - set - PETSC_TRUE if found, else PETSC_FALSE
1600: Level: beginner
1602: Notes:
1603: The user should pass in an array of pointers to char, to hold all the
1604: strings returned by this function.
1606: The user is responsible for deallocating the strings that are
1607: returned. The Fortran interface for this routine is not supported.
1609: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1611: Concepts: options database^array of strings
1613: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1614: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1615: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1616: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1617: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1618: PetscOptionsFList(), PetscOptionsEList()
1619: @*/
1620: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1621: {
1622: PetscErrorCode ierr;
1623: PetscOptionItem amsopt;
1626: if (!PetscOptionsObject->count) {
1627: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1628: PetscMalloc1(*nmax,(char**)&amsopt->data);
1630: amsopt->arraylength = *nmax;
1631: }
1632: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1633: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1634: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1635: }
1636: return(0);
1637: }
1639: /*@C
1640: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1641: option in the database. The values must be separated with commas with
1642: no intervening spaces.
1644: Logically Collective on the communicator passed in PetscOptionsBegin()
1646: Input Parameters:
1647: + opt - the option one is seeking
1648: . text - short string describing option
1649: . man - manual page for option
1650: - nmax - maximum number of values
1652: Output Parameter:
1653: + value - location to copy values
1654: . nmax - actual number of values found
1655: - set - PETSC_TRUE if found, else PETSC_FALSE
1657: Level: beginner
1659: Notes:
1660: The user should pass in an array of doubles
1662: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1664: Concepts: options database^array of strings
1666: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1667: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1668: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1669: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1670: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1671: PetscOptionsFList(), PetscOptionsEList()
1672: @*/
1673: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1674: {
1675: PetscErrorCode ierr;
1676: PetscInt i;
1677: PetscOptionItem amsopt;
1680: if (!PetscOptionsObject->count) {
1681: PetscBool *vals;
1683: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1684: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1685: vals = (PetscBool*)amsopt->data;
1686: for (i=0; i<*n; i++) vals[i] = value[i];
1687: amsopt->arraylength = *n;
1688: }
1689: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1690: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1691: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1692: for (i=1; i<*n; i++) {
1693: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1694: }
1695: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1696: }
1697: return(0);
1698: }
1700: /*@C
1701: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1703: Logically Collective on the communicator passed in PetscOptionsBegin()
1705: Input Parameters:
1706: + opt - option name
1707: . text - short string that describes the option
1708: - man - manual page with additional information on option
1710: Output Parameter:
1711: + viewer - the viewer
1712: - set - PETSC_TRUE if found, else PETSC_FALSE
1714: Level: beginner
1716: Concepts: options database^has int
1718: Notes:
1719: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1721: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1723: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1724: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1725: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1726: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1727: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1728: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1729: PetscOptionsFList(), PetscOptionsEList()
1730: @*/
1731: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1732: {
1733: PetscErrorCode ierr;
1734: PetscOptionItem amsopt;
1737: if (!PetscOptionsObject->count) {
1738: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1739: /* must use system malloc since SAWs may free this */
1740: PetscStrdup("",(char**)&amsopt->data);
1741: }
1742: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1743: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1744: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1745: }
1746: return(0);
1747: }
1750: /*@C
1751: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1752: in KSPSetFromOptions_GMRES().
1754: Logically Collective on the communicator passed in PetscOptionsBegin()
1756: Input Parameter:
1757: . head - the heading text
1760: Level: intermediate
1762: Notes:
1763: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1765: Can be followed by a call to PetscOptionsTail() in the same function.
1767: Concepts: options database^subheading
1769: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1770: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1771: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1772: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1773: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1774: PetscOptionsFList(), PetscOptionsEList()
1775: @*/
1776: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1777: {
1781: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1782: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1783: }
1784: return(0);
1785: }