Actual source code: aoptions.c
petsc-3.10.5 2019-03-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: - n - maximum number of values
715: Output Parameter:
716: + value - location to copy values
717: . n - actual number of values found
718: - set - PETSC_TRUE if found, else PETSC_FALSE
720: Level: beginner
722: Notes:
723: The array must be passed as a comma separated list.
725: There must be no intervening spaces between the values.
727: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
729: Concepts: options database^array of enums
731: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
732: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
733: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
734: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
735: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
736: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
737: @*/
738: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
739: {
740: PetscInt i,nlist = 0;
741: PetscOptionItem amsopt;
742: PetscErrorCode ierr;
745: 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");
746: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
747: nlist -= 3; /* drop enum name, prefix, and null termination */
748: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
749: PetscEnum *vals;
750: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
751: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
752: amsopt->nlist = nlist;
753: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
754: amsopt->arraylength = *n;
755: vals = (PetscEnum*)amsopt->data;
756: for (i=0; i<*n; i++) vals[i] = value[i];
757: }
758: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
759: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
760: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
761: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
762: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
763: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
764: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
765: }
766: return(0);
767: }
769: /* -------------------------------------------------------------------------------------------------------------*/
770: /*@C
771: PetscOptionsInt - Gets the integer value for a particular option in the database.
773: Logically Collective on the communicator passed in PetscOptionsBegin()
775: Input Parameters:
776: + opt - option name
777: . text - short string that describes the option
778: . man - manual page with additional information on option
779: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
780: $ PetscOptionsInt(..., obj->value,&object->value,...) or
781: $ value = defaultvalue
782: $ PetscOptionsInt(..., value,&value,&flg);
783: $ if (flg) {
785: Output Parameter:
786: + value - the integer value to return
787: - flg - PETSC_TRUE if found, else PETSC_FALSE
789: Notes:
790: If the user does not supply the option at all value is NOT changed. Thus
791: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
793: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
795: Level: beginner
797: Concepts: options database^has int
799: Notes:
800: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
802: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
803: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
804: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
805: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
806: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
807: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
808: PetscOptionsFList(), PetscOptionsEList()
809: @*/
810: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set)
811: {
812: PetscErrorCode ierr;
813: PetscOptionItem amsopt;
814: PetscBool wasset;
817: if (!PetscOptionsObject->count) {
818: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
819: PetscMalloc(sizeof(PetscInt),&amsopt->data);
820: *(PetscInt*)amsopt->data = currentvalue;
822: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
823: if (wasset) {
824: *(PetscInt*)amsopt->data = currentvalue;
825: }
826: }
827: PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
828: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
829: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
830: }
831: return(0);
832: }
834: /*@C
835: PetscOptionsString - Gets the string value for a particular option in the database.
837: Logically Collective on the communicator passed in PetscOptionsBegin()
839: Input Parameters:
840: + opt - option name
841: . text - short string that describes the option
842: . man - manual page with additional information on option
843: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
844: - len - length of the result string including null terminator
846: Output Parameter:
847: + value - the value to return
848: - flg - PETSC_TRUE if found, else PETSC_FALSE
850: Level: beginner
852: Concepts: options database^has int
854: Notes:
855: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
857: 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).
859: If the user does not supply the option at all value is NOT changed. Thus
860: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
862: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
865: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
866: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
867: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
868: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
869: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
870: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
871: PetscOptionsFList(), PetscOptionsEList()
872: @*/
873: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
874: {
875: PetscErrorCode ierr;
876: PetscOptionItem amsopt;
879: if (!PetscOptionsObject->count) {
880: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
881: /* must use system malloc since SAWs may free this */
882: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
883: }
884: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
885: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
886: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
887: }
888: return(0);
889: }
891: /*@C
892: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
894: Logically Collective on the communicator passed in PetscOptionsBegin()
896: Input Parameters:
897: + opt - option name
898: . text - short string that describes the option
899: . man - manual page with additional information on option
900: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
901: $ PetscOptionsReal(..., obj->value,&object->value,...) or
902: $ value = defaultvalue
903: $ PetscOptionsReal(..., value,&value,&flg);
904: $ if (flg) {
906: Output Parameter:
907: + value - the value to return
908: - flg - PETSC_TRUE if found, else PETSC_FALSE
910: Notes:
911: If the user does not supply the option at all value is NOT changed. Thus
912: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
914: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
916: Level: beginner
918: Concepts: options database^has int
920: Notes:
921: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
923: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
924: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
925: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
926: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
927: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
928: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
929: PetscOptionsFList(), PetscOptionsEList()
930: @*/
931: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
932: {
933: PetscErrorCode ierr;
934: PetscOptionItem amsopt;
937: if (!PetscOptionsObject->count) {
938: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
939: PetscMalloc(sizeof(PetscReal),&amsopt->data);
941: *(PetscReal*)amsopt->data = currentvalue;
942: }
943: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
944: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
945: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
946: }
947: return(0);
948: }
950: /*@C
951: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
953: Logically Collective on the communicator passed in PetscOptionsBegin()
955: Input Parameters:
956: + opt - option name
957: . text - short string that describes the option
958: . man - manual page with additional information on option
959: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
960: $ PetscOptionsScalar(..., obj->value,&object->value,...) or
961: $ value = defaultvalue
962: $ PetscOptionsScalar(..., value,&value,&flg);
963: $ if (flg) {
966: Output Parameter:
967: + value - the value to return
968: - flg - PETSC_TRUE if found, else PETSC_FALSE
970: Notes:
971: If the user does not supply the option at all value is NOT changed. Thus
972: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
974: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
976: Level: beginner
978: Concepts: options database^has int
980: Notes:
981: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
983: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
984: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
985: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
986: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
987: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
988: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
989: PetscOptionsFList(), PetscOptionsEList()
990: @*/
991: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
992: {
996: #if !defined(PETSC_USE_COMPLEX)
997: PetscOptionsReal(opt,text,man,currentvalue,value,set);
998: #else
999: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1000: #endif
1001: return(0);
1002: }
1004: /*@C
1005: 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
1006: its value is set to false.
1008: Logically Collective on the communicator passed in PetscOptionsBegin()
1010: Input Parameters:
1011: + opt - option name
1012: . text - short string that describes the option
1013: - man - manual page with additional information on option
1015: Output Parameter:
1016: . flg - PETSC_TRUE if found, else PETSC_FALSE
1018: Level: beginner
1020: Concepts: options database^has int
1022: Notes:
1023: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1025: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1026: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1027: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1028: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1029: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1030: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1031: PetscOptionsFList(), PetscOptionsEList()
1032: @*/
1033: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1034: {
1035: PetscErrorCode ierr;
1036: PetscOptionItem amsopt;
1039: if (!PetscOptionsObject->count) {
1040: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1041: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1043: *(PetscBool*)amsopt->data = PETSC_FALSE;
1044: }
1045: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1046: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1047: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1048: }
1049: return(0);
1050: }
1052: /*@C
1053: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1055: Logically Collective on the communicator passed in PetscOptionsBegin()
1057: Input Parameters:
1058: + opt - option name
1059: . text - short string that describes the option
1060: . man - manual page with additional information on option
1061: . list - the possible choices
1062: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1063: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1064: $ if (flg) {
1065: - len - the length of the character array value
1067: Output Parameter:
1068: + value - the value to return
1069: - set - PETSC_TRUE if found, else PETSC_FALSE
1071: Level: intermediate
1073: Notes:
1074: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1076: If the user does not supply the option at all value is NOT changed. Thus
1077: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1079: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1081: See PetscOptionsEList() for when the choices are given in a string array
1083: To get a listing of all currently specified options,
1084: see PetscOptionsView() or PetscOptionsGetAll()
1086: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1088: Concepts: options database^list
1090: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1091: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1092: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1093: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1094: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1095: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1096: @*/
1097: 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)
1098: {
1099: PetscErrorCode ierr;
1100: PetscOptionItem amsopt;
1103: if (!PetscOptionsObject->count) {
1104: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1105: /* must use system malloc since SAWs may free this */
1106: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1107: amsopt->flist = list;
1108: }
1109: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1110: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1111: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1112: }
1113: return(0);
1114: }
1116: /*@C
1117: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1119: Logically Collective on the communicator passed in PetscOptionsBegin()
1121: Input Parameters:
1122: + opt - option name
1123: . ltext - short string that describes the option
1124: . man - manual page with additional information on option
1125: . list - the possible choices (one of these must be selected, anything else is invalid)
1126: . ntext - number of choices
1127: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1128: $ PetscOptionsElist(..., obj->value,&value,&flg);
1129: $ if (flg) {
1132: Output Parameter:
1133: + value - the index of the value to return
1134: - set - PETSC_TRUE if found, else PETSC_FALSE
1136: Level: intermediate
1138: Notes:
1139: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1141: If the user does not supply the option at all value is NOT changed. Thus
1142: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1144: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1146: Concepts: options database^list
1148: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1149: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1150: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1151: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1152: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1153: PetscOptionsFList(), PetscOptionsEnum()
1154: @*/
1155: 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)
1156: {
1157: PetscErrorCode ierr;
1158: PetscInt i;
1159: PetscOptionItem amsopt;
1162: if (!PetscOptionsObject->count) {
1163: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1164: /* must use system malloc since SAWs may free this */
1165: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1166: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1167: amsopt->nlist = ntext;
1168: }
1169: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1170: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1171: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1172: for (i=0; i<ntext; i++) {
1173: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1174: }
1175: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1176: }
1177: return(0);
1178: }
1180: /*@C
1181: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1182: which at most a single value can be true.
1184: Logically Collective on the communicator passed in PetscOptionsBegin()
1186: Input Parameters:
1187: + opt - option name
1188: . text - short string that describes the option
1189: - man - manual page with additional information on option
1191: Output Parameter:
1192: . flg - whether that option was set or not
1194: Level: intermediate
1196: Notes:
1197: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1199: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1201: Concepts: options database^logical group
1203: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1204: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1205: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1206: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1207: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1208: PetscOptionsFList(), PetscOptionsEList()
1209: @*/
1210: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1211: {
1212: PetscErrorCode ierr;
1213: PetscOptionItem amsopt;
1216: if (!PetscOptionsObject->count) {
1217: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1218: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1220: *(PetscBool*)amsopt->data = PETSC_FALSE;
1221: }
1222: *flg = PETSC_FALSE;
1223: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1224: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1225: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1226: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1227: }
1228: return(0);
1229: }
1231: /*@C
1232: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1233: which at most a single value can be true.
1235: Logically Collective on the communicator passed in PetscOptionsBegin()
1237: Input Parameters:
1238: + opt - option name
1239: . text - short string that describes the option
1240: - man - manual page with additional information on option
1242: Output Parameter:
1243: . flg - PETSC_TRUE if found, else PETSC_FALSE
1245: Level: intermediate
1247: Notes:
1248: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1250: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1252: Concepts: options database^logical group
1254: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1255: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1256: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1257: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1258: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1259: PetscOptionsFList(), PetscOptionsEList()
1260: @*/
1261: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1262: {
1263: PetscErrorCode ierr;
1264: PetscOptionItem amsopt;
1267: if (!PetscOptionsObject->count) {
1268: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1269: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1271: *(PetscBool*)amsopt->data = PETSC_FALSE;
1272: }
1273: *flg = PETSC_FALSE;
1274: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1275: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1276: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1277: }
1278: return(0);
1279: }
1281: /*@C
1282: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1283: which at most a single value can be true.
1285: Logically Collective on the communicator passed in PetscOptionsBegin()
1287: Input Parameters:
1288: + opt - option name
1289: . text - short string that describes the option
1290: - man - manual page with additional information on option
1292: Output Parameter:
1293: . flg - PETSC_TRUE if found, else PETSC_FALSE
1295: Level: intermediate
1297: Notes:
1298: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1300: Must follow a PetscOptionsBoolGroupBegin()
1302: Concepts: options database^logical group
1304: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1305: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1306: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1307: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1308: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1309: PetscOptionsFList(), PetscOptionsEList()
1310: @*/
1311: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1312: {
1313: PetscErrorCode ierr;
1314: PetscOptionItem amsopt;
1317: if (!PetscOptionsObject->count) {
1318: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1319: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1321: *(PetscBool*)amsopt->data = PETSC_FALSE;
1322: }
1323: *flg = PETSC_FALSE;
1324: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1325: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1326: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1327: }
1328: return(0);
1329: }
1331: /*@C
1332: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1334: Logically Collective on the communicator passed in PetscOptionsBegin()
1336: Input Parameters:
1337: + opt - option name
1338: . text - short string that describes the option
1339: . man - manual page with additional information on option
1340: - currentvalue - the current value
1342: Output Parameter:
1343: . flg - PETSC_TRUE or PETSC_FALSE
1344: . set - PETSC_TRUE if found, else PETSC_FALSE
1346: Notes:
1347: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1348: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1350: 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
1351: is equivalent to -requested_bool true
1353: If the user does not supply the option at all flg is NOT changed. Thus
1354: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1356: Level: beginner
1358: Concepts: options database^logical
1360: Notes:
1361: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1363: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1364: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1365: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1366: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1367: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1368: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1369: PetscOptionsFList(), PetscOptionsEList()
1370: @*/
1371: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1372: {
1373: PetscErrorCode ierr;
1374: PetscBool iset;
1375: PetscOptionItem amsopt;
1378: if (!PetscOptionsObject->count) {
1379: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1380: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1382: *(PetscBool*)amsopt->data = currentvalue;
1383: }
1384: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1385: if (set) *set = iset;
1386: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1387: const char *v = PetscBools[currentvalue];
1388: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1389: }
1390: return(0);
1391: }
1393: /*@C
1394: PetscOptionsRealArray - Gets an array of double values for a particular
1395: option in the database. The values must be separated with commas with
1396: no intervening spaces.
1398: Logically Collective on the communicator passed in PetscOptionsBegin()
1400: Input Parameters:
1401: + opt - the option one is seeking
1402: . text - short string describing option
1403: . man - manual page for option
1404: - nmax - maximum number of values
1406: Output Parameter:
1407: + value - location to copy values
1408: . nmax - actual number of values found
1409: - set - PETSC_TRUE if found, else PETSC_FALSE
1411: Level: beginner
1413: Notes:
1414: The user should pass in an array of doubles
1416: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1418: Concepts: options database^array of strings
1420: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1421: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1422: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1423: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1424: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1425: PetscOptionsFList(), PetscOptionsEList()
1426: @*/
1427: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1428: {
1429: PetscErrorCode ierr;
1430: PetscInt i;
1431: PetscOptionItem amsopt;
1434: if (!PetscOptionsObject->count) {
1435: PetscReal *vals;
1437: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1438: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1439: vals = (PetscReal*)amsopt->data;
1440: for (i=0; i<*n; i++) vals[i] = value[i];
1441: amsopt->arraylength = *n;
1442: }
1443: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1444: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1445: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1446: for (i=1; i<*n; i++) {
1447: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1448: }
1449: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1450: }
1451: return(0);
1452: }
1454: /*@C
1455: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1456: option in the database. The values must be separated with commas with
1457: no intervening spaces.
1459: Logically Collective on the communicator passed in PetscOptionsBegin()
1461: Input Parameters:
1462: + opt - the option one is seeking
1463: . text - short string describing option
1464: . man - manual page for option
1465: - nmax - maximum number of values
1467: Output Parameter:
1468: + value - location to copy values
1469: . nmax - actual number of values found
1470: - set - PETSC_TRUE if found, else PETSC_FALSE
1472: Level: beginner
1474: Notes:
1475: The user should pass in an array of doubles
1477: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1479: Concepts: options database^array of strings
1481: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1482: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1483: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1484: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1485: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1486: PetscOptionsFList(), PetscOptionsEList()
1487: @*/
1488: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1489: {
1490: PetscErrorCode ierr;
1491: PetscInt i;
1492: PetscOptionItem amsopt;
1495: if (!PetscOptionsObject->count) {
1496: PetscScalar *vals;
1498: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1499: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1500: vals = (PetscScalar*)amsopt->data;
1501: for (i=0; i<*n; i++) vals[i] = value[i];
1502: amsopt->arraylength = *n;
1503: }
1504: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1505: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1506: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1507: for (i=1; i<*n; i++) {
1508: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1509: }
1510: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1511: }
1512: return(0);
1513: }
1515: /*@C
1516: PetscOptionsIntArray - Gets an array of integers for a particular
1517: option in the database.
1519: Logically Collective on the communicator passed in PetscOptionsBegin()
1521: Input Parameters:
1522: + opt - the option one is seeking
1523: . text - short string describing option
1524: . man - manual page for option
1525: - n - maximum number of values
1527: Output Parameter:
1528: + value - location to copy values
1529: . n - actual number of values found
1530: - set - PETSC_TRUE if found, else PETSC_FALSE
1532: Level: beginner
1534: Notes:
1535: The array can be passed as
1536: a comma separated list: 0,1,2,3,4,5,6,7
1537: a range (start-end+1): 0-8
1538: a range with given increment (start-end+1:inc): 0-7:2
1539: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1541: There must be no intervening spaces between the values.
1543: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1545: Concepts: options database^array of ints
1547: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1548: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1549: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1550: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1551: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1552: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1553: @*/
1554: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1555: {
1557: PetscInt i;
1558: PetscOptionItem amsopt;
1561: if (!PetscOptionsObject->count) {
1562: PetscInt *vals;
1564: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1565: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1566: vals = (PetscInt*)amsopt->data;
1567: for (i=0; i<*n; i++) vals[i] = value[i];
1568: amsopt->arraylength = *n;
1569: }
1570: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1571: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1572: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1573: for (i=1; i<*n; i++) {
1574: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1575: }
1576: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1577: }
1578: return(0);
1579: }
1581: /*@C
1582: PetscOptionsStringArray - Gets an array of string values for a particular
1583: option in the database. The values must be separated with commas with
1584: no intervening spaces.
1586: Logically Collective on the communicator passed in PetscOptionsBegin()
1588: Input Parameters:
1589: + opt - the option one is seeking
1590: . text - short string describing option
1591: . man - manual page for option
1592: - nmax - maximum number of strings
1594: Output Parameter:
1595: + value - location to copy strings
1596: . nmax - actual number of strings found
1597: - set - PETSC_TRUE if found, else PETSC_FALSE
1599: Level: beginner
1601: Notes:
1602: The user should pass in an array of pointers to char, to hold all the
1603: strings returned by this function.
1605: The user is responsible for deallocating the strings that are
1606: returned. The Fortran interface for this routine is not supported.
1608: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1610: Concepts: options database^array of strings
1612: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1613: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1614: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1615: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1616: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1617: PetscOptionsFList(), PetscOptionsEList()
1618: @*/
1619: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1620: {
1621: PetscErrorCode ierr;
1622: PetscOptionItem amsopt;
1625: if (!PetscOptionsObject->count) {
1626: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1627: PetscMalloc1(*nmax,(char**)&amsopt->data);
1629: amsopt->arraylength = *nmax;
1630: }
1631: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1632: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1633: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1634: }
1635: return(0);
1636: }
1638: /*@C
1639: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1640: option in the database. The values must be separated with commas with
1641: no intervening spaces.
1643: Logically Collective on the communicator passed in PetscOptionsBegin()
1645: Input Parameters:
1646: + opt - the option one is seeking
1647: . text - short string describing option
1648: . man - manual page for option
1649: - nmax - maximum number of values
1651: Output Parameter:
1652: + value - location to copy values
1653: . nmax - actual number of values found
1654: - set - PETSC_TRUE if found, else PETSC_FALSE
1656: Level: beginner
1658: Notes:
1659: The user should pass in an array of doubles
1661: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1663: Concepts: options database^array of strings
1665: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1666: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1667: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1668: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1669: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1670: PetscOptionsFList(), PetscOptionsEList()
1671: @*/
1672: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1673: {
1674: PetscErrorCode ierr;
1675: PetscInt i;
1676: PetscOptionItem amsopt;
1679: if (!PetscOptionsObject->count) {
1680: PetscBool *vals;
1682: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1683: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1684: vals = (PetscBool*)amsopt->data;
1685: for (i=0; i<*n; i++) vals[i] = value[i];
1686: amsopt->arraylength = *n;
1687: }
1688: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1689: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1690: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1691: for (i=1; i<*n; i++) {
1692: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1693: }
1694: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1695: }
1696: return(0);
1697: }
1699: /*@C
1700: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1702: Logically Collective on the communicator passed in PetscOptionsBegin()
1704: Input Parameters:
1705: + opt - option name
1706: . text - short string that describes the option
1707: - man - manual page with additional information on option
1709: Output Parameter:
1710: + viewer - the viewer
1711: - set - PETSC_TRUE if found, else PETSC_FALSE
1713: Level: beginner
1715: Concepts: options database^has int
1717: Notes:
1718: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1720: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1722: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1723: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1724: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1725: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1726: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1727: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1728: PetscOptionsFList(), PetscOptionsEList()
1729: @*/
1730: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1731: {
1732: PetscErrorCode ierr;
1733: PetscOptionItem amsopt;
1736: if (!PetscOptionsObject->count) {
1737: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1738: /* must use system malloc since SAWs may free this */
1739: PetscStrdup("",(char**)&amsopt->data);
1740: }
1741: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
1742: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1743: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1744: }
1745: return(0);
1746: }
1749: /*@C
1750: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1751: in KSPSetFromOptions_GMRES().
1753: Logically Collective on the communicator passed in PetscOptionsBegin()
1755: Input Parameter:
1756: . head - the heading text
1759: Level: intermediate
1761: Notes:
1762: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1764: Can be followed by a call to PetscOptionsTail() in the same function.
1766: Concepts: options database^subheading
1768: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1769: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1770: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1771: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1772: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1773: PetscOptionsFList(), PetscOptionsEList()
1774: @*/
1775: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1776: {
1780: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1781: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1782: }
1783: return(0);
1784: }