Actual source code: aoptions.c
petsc-3.8.4 2018-03-24
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: PetscOptionsHasName(PetscOptionsObject->options,NULL,"-help",&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: this isn't really practical, it is just to demonstrate the principle
171: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
172: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
174: Bugs:
175: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
176: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
177: - Only works for PetscInt == int, PetscReal == double etc
179: Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different
180: address space and communicating with the PETSc program
182: */
183: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
184: {
185: PetscErrorCode ierr;
186: PetscOptionItem next = PetscOptionsObject->next;
187: char str[512];
188: PetscBool bid;
189: PetscReal ir,*valr;
190: PetscInt *vald;
191: size_t i;
194: (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject->title);
195: while (next) {
196: switch (next->type) {
197: case OPTION_HEAD:
198: break;
199: case OPTION_INT_ARRAY:
200: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
201: vald = (PetscInt*) next->data;
202: for (i=0; i<next->arraylength; i++) {
203: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
204: if (i < next->arraylength-1) {
205: PetscPrintf(PETSC_COMM_WORLD,",");
206: }
207: }
208: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
209: PetscScanString(PETSC_COMM_WORLD,512,str);
210: if (str[0]) {
211: PetscToken token;
212: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
213: size_t len;
214: char *value;
215: PetscBool foundrange;
217: next->set = PETSC_TRUE;
218: value = str;
219: PetscTokenCreate(value,',',&token);
220: PetscTokenFind(token,&value);
221: while (n < nmax) {
222: if (!value) break;
224: /* look for form d-D where d and D are integers */
225: foundrange = PETSC_FALSE;
226: PetscStrlen(value,&len);
227: if (value[0] == '-') i=2;
228: else i=1;
229: for (;i<len; i++) {
230: if (value[i] == '-') {
231: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
232: value[i] = 0;
233: PetscOptionsStringToInt(value,&start);
234: PetscOptionsStringToInt(value+i+1,&end);
235: 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);
236: 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);
237: for (; start<end; start++) {
238: *dvalue = start; dvalue++;n++;
239: }
240: foundrange = PETSC_TRUE;
241: break;
242: }
243: }
244: if (!foundrange) {
245: PetscOptionsStringToInt(value,dvalue);
246: dvalue++;
247: n++;
248: }
249: PetscTokenFind(token,&value);
250: }
251: PetscTokenDestroy(&token);
252: }
253: break;
254: case OPTION_REAL_ARRAY:
255: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
256: valr = (PetscReal*) next->data;
257: for (i=0; i<next->arraylength; i++) {
258: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
259: if (i < next->arraylength-1) {
260: PetscPrintf(PETSC_COMM_WORLD,",");
261: }
262: }
263: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
264: PetscScanString(PETSC_COMM_WORLD,512,str);
265: if (str[0]) {
266: PetscToken token;
267: PetscInt n = 0,nmax = next->arraylength;
268: PetscReal *dvalue = (PetscReal*)next->data;
269: char *value;
271: next->set = PETSC_TRUE;
272: value = str;
273: PetscTokenCreate(value,',',&token);
274: PetscTokenFind(token,&value);
275: while (n < nmax) {
276: if (!value) break;
277: PetscOptionsStringToReal(value,dvalue);
278: dvalue++;
279: n++;
280: PetscTokenFind(token,&value);
281: }
282: PetscTokenDestroy(&token);
283: }
284: break;
285: case OPTION_INT:
286: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
287: PetscScanString(PETSC_COMM_WORLD,512,str);
288: if (str[0]) {
289: #if defined(PETSC_SIZEOF_LONG_LONG)
290: long long lid;
291: sscanf(str,"%lld",&lid);
292: 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);
293: #else
294: long lid;
295: sscanf(str,"%ld",&lid);
296: 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);
297: #endif
299: next->set = PETSC_TRUE;
300: *((PetscInt*)next->data) = (PetscInt)lid;
301: }
302: break;
303: case OPTION_REAL:
304: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
305: PetscScanString(PETSC_COMM_WORLD,512,str);
306: if (str[0]) {
307: #if defined(PETSC_USE_REAL_SINGLE)
308: sscanf(str,"%e",&ir);
309: #elif defined(PETSC_USE_REAL___FP16)
310: float irtemp;
311: sscanf(str,"%e",&irtemp);
312: ir = irtemp;
313: #elif defined(PETSC_USE_REAL_DOUBLE)
314: sscanf(str,"%le",&ir);
315: #elif defined(PETSC_USE_REAL___FLOAT128)
316: ir = strtoflt128(str,0);
317: #else
318: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
319: #endif
320: next->set = PETSC_TRUE;
321: *((PetscReal*)next->data) = ir;
322: }
323: break;
324: case OPTION_BOOL:
325: 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);
326: PetscScanString(PETSC_COMM_WORLD,512,str);
327: if (str[0]) {
328: PetscOptionsStringToBool(str,&bid);
329: next->set = PETSC_TRUE;
330: *((PetscBool*)next->data) = bid;
331: }
332: break;
333: case OPTION_STRING:
334: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
335: PetscScanString(PETSC_COMM_WORLD,512,str);
336: if (str[0]) {
337: next->set = PETSC_TRUE;
338: /* must use system malloc since SAWs may free this */
339: PetscStrdup(str,(char**)&next->data);
340: }
341: break;
342: case OPTION_FLIST:
343: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
344: PetscScanString(PETSC_COMM_WORLD,512,str);
345: if (str[0]) {
346: PetscOptionsObject->changedmethod = PETSC_TRUE;
347: next->set = PETSC_TRUE;
348: /* must use system malloc since SAWs may free this */
349: PetscStrdup(str,(char**)&next->data);
350: }
351: break;
352: default:
353: break;
354: }
355: next = next->next;
356: }
357: return(0);
358: }
360: #if defined(PETSC_HAVE_SAWS)
361: #include <petscviewersaws.h>
363: static int count = 0;
365: PetscErrorCode PetscOptionsSAWsDestroy(void)
366: {
368: return(0);
369: }
371: static const char *OptionsHeader = "<head>\n"
372: "<script type=\"text/javascript\" src=\"http://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
373: "<script type=\"text/javascript\" src=\"http://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
374: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
375: "<script>\n"
376: "jQuery(document).ready(function() {\n"
377: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
378: "})\n"
379: "</script>\n"
380: "</head>\n";
382: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
383: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
385: /*
386: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
388: Bugs:
389: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
390: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
391: - Only works for PetscInt == int, PetscReal == double etc
394: */
395: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
396: {
397: PetscErrorCode ierr;
398: PetscOptionItem next = PetscOptionsObject->next;
399: static int mancount = 0;
400: char options[16];
401: PetscBool changedmethod = PETSC_FALSE;
402: PetscBool stopasking = PETSC_FALSE;
403: char manname[16],textname[16];
404: char dir[1024];
407: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
408: sprintf(options,"Options_%d",count++);
410: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
412: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
413: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
414: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
415: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
416: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
417: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
419: while (next) {
420: sprintf(manname,"_man_%d",mancount);
421: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
422: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
423: sprintf(textname,"_text_%d",mancount++);
424: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
425: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
427: switch (next->type) {
428: case OPTION_HEAD:
429: break;
430: case OPTION_INT_ARRAY:
431: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
432: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
433: break;
434: case OPTION_REAL_ARRAY:
435: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
436: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
437: break;
438: case OPTION_INT:
439: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
440: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
441: break;
442: case OPTION_REAL:
443: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
444: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
445: break;
446: case OPTION_BOOL:
447: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
448: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
449: break;
450: case OPTION_BOOL_ARRAY:
451: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
452: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
453: break;
454: case OPTION_STRING:
455: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
456: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
457: break;
458: case OPTION_STRING_ARRAY:
459: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
460: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
461: break;
462: case OPTION_FLIST:
463: {
464: PetscInt ntext;
465: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
466: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
467: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
468: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
469: }
470: break;
471: case OPTION_ELIST:
472: {
473: PetscInt ntext = next->nlist;
474: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
475: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
476: PetscMalloc1((ntext+1),(char***)&next->edata);
477: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
478: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
479: }
480: break;
481: default:
482: break;
483: }
484: next = next->next;
485: }
487: /* wait until accessor has unlocked the memory */
488: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
489: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
490: PetscSAWsBlock();
491: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
492: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
494: /* determine if any values have been set in GUI */
495: next = PetscOptionsObject->next;
496: while (next) {
497: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
498: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
499: next = next->next;
500: }
502: /* reset counter to -2; this updates the screen with the new options for the selected method */
503: if (changedmethod) PetscOptionsObject->count = -2;
505: if (stopasking) {
506: PetscOptionsPublish = PETSC_FALSE;
507: PetscOptionsObject->count = 0;//do not ask for same thing again
508: }
510: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
511: return(0);
512: }
513: #endif
515: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
516: {
517: PetscErrorCode ierr;
518: PetscOptionItem last;
519: char option[256],value[1024],tmp[32];
520: size_t j;
523: if (PetscOptionsObject->next) {
524: if (!PetscOptionsObject->count) {
525: #if defined(PETSC_HAVE_SAWS)
526: PetscOptionsSAWsInput(PetscOptionsObject);
527: #else
528: PetscOptionsGetFromTextInput(PetscOptionsObject);
529: #endif
530: }
531: }
533: PetscFree(PetscOptionsObject->title);
535: /* reset counter to -2; this updates the screen with the new options for the selected method */
536: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
537: /* reset alreadyprinted flag */
538: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
539: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
540: PetscOptionsObject->object = NULL;
542: while (PetscOptionsObject->next) {
543: if (PetscOptionsObject->next->set) {
544: if (PetscOptionsObject->prefix) {
545: PetscStrcpy(option,"-");
546: PetscStrcat(option,PetscOptionsObject->prefix);
547: PetscStrcat(option,PetscOptionsObject->next->option+1);
548: } else {
549: PetscStrcpy(option,PetscOptionsObject->next->option);
550: }
552: switch (PetscOptionsObject->next->type) {
553: case OPTION_HEAD:
554: break;
555: case OPTION_INT_ARRAY:
556: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
557: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
558: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
559: PetscStrcat(value,",");
560: PetscStrcat(value,tmp);
561: }
562: break;
563: case OPTION_INT:
564: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
565: break;
566: case OPTION_REAL:
567: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
568: break;
569: case OPTION_REAL_ARRAY:
570: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
571: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
572: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
573: PetscStrcat(value,",");
574: PetscStrcat(value,tmp);
575: }
576: break;
577: case OPTION_SCALAR_ARRAY:
578: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
579: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
580: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
581: PetscStrcat(value,",");
582: PetscStrcat(value,tmp);
583: }
584: break;
585: case OPTION_BOOL:
586: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
587: break;
588: case OPTION_BOOL_ARRAY:
589: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
590: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
591: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
592: PetscStrcat(value,",");
593: PetscStrcat(value,tmp);
594: }
595: break;
596: case OPTION_FLIST:
597: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
598: break;
599: case OPTION_ELIST:
600: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
601: break;
602: case OPTION_STRING:
603: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
604: break;
605: case OPTION_STRING_ARRAY:
606: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
607: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
608: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
609: PetscStrcat(value,",");
610: PetscStrcat(value,tmp);
611: }
612: break;
613: }
614: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
615: }
616: if (PetscOptionsObject->next->type == OPTION_ELIST) {
617: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
618: }
619: PetscFree(PetscOptionsObject->next->text);
620: PetscFree(PetscOptionsObject->next->option);
621: PetscFree(PetscOptionsObject->next->man);
622: PetscFree(PetscOptionsObject->next->edata);
624: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
625: free(PetscOptionsObject->next->data);
626: } else {
627: PetscFree(PetscOptionsObject->next->data);
628: }
630: last = PetscOptionsObject->next;
631: PetscOptionsObject->next = PetscOptionsObject->next->next;
632: PetscFree(last);
633: }
634: PetscFree(PetscOptionsObject->prefix);
635: PetscOptionsObject->next = 0;
636: return(0);
637: }
639: /*@C
640: PetscOptionsEnum - Gets the enum value for a particular option in the database.
642: Logically Collective on the communicator passed in PetscOptionsBegin()
644: Input Parameters:
645: + opt - option name
646: . text - short string that describes the option
647: . man - manual page with additional information on option
648: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
649: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
650: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
651: $ value = defaultvalue
652: $ PetscOptionsEnum(..., value,&value,&flg);
653: $ if (flg) {
655: Output Parameter:
656: + value - the value to return
657: - set - PETSC_TRUE if found, else PETSC_FALSE
659: Level: beginner
661: Concepts: options database
663: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
665: list is usually something like PCASMTypes or some other predefined list of enum names
667: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
668: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
669: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
670: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
671: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
672: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
673: PetscOptionsFList(), PetscOptionsEList()
674: @*/
675: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
676: {
678: PetscInt ntext = 0;
679: PetscInt tval;
680: PetscBool tflg;
683: while (list[ntext++]) {
684: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
685: }
686: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
687: ntext -= 3;
688: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
689: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
690: if (tflg) *value = (PetscEnum)tval;
691: if (set) *set = tflg;
692: return(0);
693: }
695: /*@C
696: PetscOptionsEnumArray - Gets an array of enum values for a particular
697: option in the database.
699: Logically Collective on the communicator passed in PetscOptionsBegin()
701: Input Parameters:
702: + opt - the option one is seeking
703: . text - short string describing option
704: . man - manual page for option
705: - n - maximum number of values
707: Output Parameter:
708: + value - location to copy values
709: . n - actual number of values found
710: - set - PETSC_TRUE if found, else PETSC_FALSE
712: Level: beginner
714: Notes:
715: The array must be passed as a comma separated list.
717: There must be no intervening spaces between the values.
719: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
721: Concepts: options database^array of enums
723: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
724: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
725: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
726: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
727: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
728: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
729: @*/
730: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
731: {
732: PetscInt i,nlist = 0;
733: PetscOptionItem amsopt;
734: PetscErrorCode ierr;
737: 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");
738: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
739: nlist -= 3; /* drop enum name, prefix, and null termination */
740: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
741: PetscEnum *vals;
742: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
743: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
744: amsopt->nlist = nlist;
745: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
746: amsopt->arraylength = *n;
747: vals = (PetscEnum*)amsopt->data;
748: for (i=0; i<*n; i++) vals[i] = value[i];
749: }
750: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
751: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
752: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
753: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
754: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
755: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
756: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
757: }
758: return(0);
759: }
761: /* -------------------------------------------------------------------------------------------------------------*/
762: /*@C
763: PetscOptionsInt - Gets the integer value for a particular option in the database.
765: Logically Collective on the communicator passed in PetscOptionsBegin()
767: Input Parameters:
768: + opt - option name
769: . text - short string that describes the option
770: . man - manual page with additional information on option
771: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
772: $ PetscOptionsInt(..., obj->value,&object->value,...) or
773: $ value = defaultvalue
774: $ PetscOptionsInt(..., value,&value,&flg);
775: $ if (flg) {
777: Output Parameter:
778: + value - the integer value to return
779: - flg - PETSC_TRUE if found, else PETSC_FALSE
781: Level: beginner
783: Concepts: options database^has int
785: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
787: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
788: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
789: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
790: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
791: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
792: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
793: PetscOptionsFList(), PetscOptionsEList()
794: @*/
795: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set)
796: {
797: PetscErrorCode ierr;
798: PetscOptionItem amsopt;
799: PetscBool wasset;
802: if (!PetscOptionsObject->count) {
803: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
804: PetscMalloc(sizeof(PetscInt),&amsopt->data);
805: *(PetscInt*)amsopt->data = currentvalue;
807: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
808: if (wasset) {
809: *(PetscInt*)amsopt->data = currentvalue;
810: }
811: }
812: PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
813: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
814: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
815: }
816: return(0);
817: }
819: /*@C
820: PetscOptionsString - Gets the string value for a particular option in the database.
822: Logically Collective on the communicator passed in PetscOptionsBegin()
824: Input Parameters:
825: + opt - option name
826: . text - short string that describes the option
827: . man - manual page with additional information on option
828: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
829: - len - length of the result string including null terminator
831: Output Parameter:
832: + value - the value to return
833: - flg - PETSC_TRUE if found, else PETSC_FALSE
835: Level: beginner
837: Concepts: options database^has int
839: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
841: 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).
843: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
844: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
845: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
846: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
847: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
848: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
849: PetscOptionsFList(), PetscOptionsEList()
850: @*/
851: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
852: {
853: PetscErrorCode ierr;
854: PetscOptionItem amsopt;
857: if (!PetscOptionsObject->count) {
858: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
859: /* must use system malloc since SAWs may free this */
860: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
861: }
862: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
863: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
864: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
865: }
866: return(0);
867: }
869: /*@C
870: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
872: Logically Collective on the communicator passed in PetscOptionsBegin()
874: Input Parameters:
875: + opt - option name
876: . text - short string that describes the option
877: . man - manual page with additional information on option
878: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
879: $ PetscOptionsReal(..., obj->value,&object->value,...) or
880: $ value = defaultvalue
881: $ PetscOptionsReal(..., value,&value,&flg);
882: $ if (flg) {
884: Output Parameter:
885: + value - the value to return
886: - flg - PETSC_TRUE if found, else PETSC_FALSE
888: Level: beginner
890: Concepts: options database^has int
892: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
894: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
895: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
896: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
897: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
898: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
899: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
900: PetscOptionsFList(), PetscOptionsEList()
901: @*/
902: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
903: {
904: PetscErrorCode ierr;
905: PetscOptionItem amsopt;
908: if (!PetscOptionsObject->count) {
909: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
910: PetscMalloc(sizeof(PetscReal),&amsopt->data);
912: *(PetscReal*)amsopt->data = currentvalue;
913: }
914: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
915: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
916: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
917: }
918: return(0);
919: }
921: /*@C
922: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
924: Logically Collective on the communicator passed in PetscOptionsBegin()
926: Input Parameters:
927: + opt - option name
928: . text - short string that describes the option
929: . man - manual page with additional information on option
930: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
931: $ PetscOptionsScalar(..., obj->value,&object->value,...) or
932: $ value = defaultvalue
933: $ PetscOptionsScalar(..., value,&value,&flg);
934: $ if (flg) {
937: Output Parameter:
938: + value - the value to return
939: - flg - PETSC_TRUE if found, else PETSC_FALSE
941: Level: beginner
943: Concepts: options database^has int
945: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
947: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
948: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
949: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
950: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
951: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
952: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
953: PetscOptionsFList(), PetscOptionsEList()
954: @*/
955: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
956: {
960: #if !defined(PETSC_USE_COMPLEX)
961: PetscOptionsReal(opt,text,man,currentvalue,value,set);
962: #else
963: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
964: #endif
965: return(0);
966: }
968: /*@C
969: 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
970: its value is set to false.
972: Logically Collective on the communicator passed in PetscOptionsBegin()
974: Input Parameters:
975: + opt - option name
976: . text - short string that describes the option
977: - man - manual page with additional information on option
979: Output Parameter:
980: . flg - PETSC_TRUE if found, else PETSC_FALSE
982: Level: beginner
984: Concepts: options database^has int
986: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
988: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
989: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
990: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
991: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
992: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
993: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
994: PetscOptionsFList(), PetscOptionsEList()
995: @*/
996: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
997: {
998: PetscErrorCode ierr;
999: PetscOptionItem amsopt;
1002: if (!PetscOptionsObject->count) {
1003: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1004: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1006: *(PetscBool*)amsopt->data = PETSC_FALSE;
1007: }
1008: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1009: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1010: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1011: }
1012: return(0);
1013: }
1015: /*@C
1016: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1018: Logically Collective on the communicator passed in PetscOptionsBegin()
1020: Input Parameters:
1021: + opt - option name
1022: . text - short string that describes the option
1023: . man - manual page with additional information on option
1024: . list - the possible choices
1025: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1026: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1027: $ if (flg) {
1028: - len - the length of the character array value
1030: Output Parameter:
1031: + value - the value to return
1032: - set - PETSC_TRUE if found, else PETSC_FALSE
1034: Level: intermediate
1036: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1038: See PetscOptionsEList() for when the choices are given in a string array
1040: To get a listing of all currently specified options,
1041: see PetscOptionsView() or PetscOptionsGetAll()
1043: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1045: Concepts: options database^list
1047: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1048: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1049: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1050: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1051: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1052: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1053: @*/
1054: 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)
1055: {
1056: PetscErrorCode ierr;
1057: PetscOptionItem amsopt;
1060: if (!PetscOptionsObject->count) {
1061: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1062: /* must use system malloc since SAWs may free this */
1063: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1064: amsopt->flist = list;
1065: }
1066: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1067: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1068: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1069: }
1070: return(0);
1071: }
1073: /*@C
1074: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1076: Logically Collective on the communicator passed in PetscOptionsBegin()
1078: Input Parameters:
1079: + opt - option name
1080: . ltext - short string that describes the option
1081: . man - manual page with additional information on option
1082: . list - the possible choices (one of these must be selected, anything else is invalid)
1083: . ntext - number of choices
1084: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1085: $ PetscOptionsElist(..., obj->value,&value,&flg);
1086: $ if (flg) {
1089: Output Parameter:
1090: + value - the index of the value to return
1091: - set - PETSC_TRUE if found, else PETSC_FALSE
1093: Level: intermediate
1095: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1097: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1099: Concepts: options database^list
1101: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1102: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1103: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1104: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1105: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1106: PetscOptionsFList(), PetscOptionsEnum()
1107: @*/
1108: 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)
1109: {
1110: PetscErrorCode ierr;
1111: PetscInt i;
1112: PetscOptionItem amsopt;
1115: if (!PetscOptionsObject->count) {
1116: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1117: /* must use system malloc since SAWs may free this */
1118: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1119: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1120: amsopt->nlist = ntext;
1121: }
1122: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1123: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1124: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1125: for (i=0; i<ntext; i++) {
1126: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1127: }
1128: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1129: }
1130: return(0);
1131: }
1133: /*@C
1134: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1135: which at most a single value can be true.
1137: Logically Collective on the communicator passed in PetscOptionsBegin()
1139: Input Parameters:
1140: + opt - option name
1141: . text - short string that describes the option
1142: - man - manual page with additional information on option
1144: Output Parameter:
1145: . flg - whether that option was set or not
1147: Level: intermediate
1149: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1151: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1153: Concepts: options database^logical group
1155: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1156: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1157: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1158: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1159: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1160: PetscOptionsFList(), PetscOptionsEList()
1161: @*/
1162: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1163: {
1164: PetscErrorCode ierr;
1165: PetscOptionItem amsopt;
1168: if (!PetscOptionsObject->count) {
1169: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1170: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1172: *(PetscBool*)amsopt->data = PETSC_FALSE;
1173: }
1174: *flg = PETSC_FALSE;
1175: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1176: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1177: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1178: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1179: }
1180: return(0);
1181: }
1183: /*@C
1184: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1185: which at most a single value can be true.
1187: Logically Collective on the communicator passed in PetscOptionsBegin()
1189: Input Parameters:
1190: + opt - option name
1191: . text - short string that describes the option
1192: - man - manual page with additional information on option
1194: Output Parameter:
1195: . flg - PETSC_TRUE if found, else PETSC_FALSE
1197: Level: intermediate
1199: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1201: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1203: Concepts: options database^logical group
1205: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1206: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1207: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1208: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1209: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1210: PetscOptionsFList(), PetscOptionsEList()
1211: @*/
1212: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1213: {
1214: PetscErrorCode ierr;
1215: PetscOptionItem amsopt;
1218: if (!PetscOptionsObject->count) {
1219: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1220: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1222: *(PetscBool*)amsopt->data = PETSC_FALSE;
1223: }
1224: *flg = PETSC_FALSE;
1225: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1226: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
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: PetscOptionsBoolGroupEnd - Last 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: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1250: Must follow a PetscOptionsBoolGroupBegin()
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 PetscOptionsBoolGroupEnd_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: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1284: Logically Collective on the communicator passed in PetscOptionsBegin()
1286: Input Parameters:
1287: + opt - option name
1288: . text - short string that describes the option
1289: . man - manual page with additional information on option
1290: - currentvalue - the current value
1292: Output Parameter:
1293: . flg - PETSC_TRUE or PETSC_FALSE
1294: . set - PETSC_TRUE if found, else PETSC_FALSE
1296: Level: beginner
1298: Concepts: options database^logical
1300: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1302: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1303: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1304: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1305: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1306: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1307: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1308: PetscOptionsFList(), PetscOptionsEList()
1309: @*/
1310: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1311: {
1312: PetscErrorCode ierr;
1313: PetscBool iset;
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 = currentvalue;
1322: }
1323: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1324: if (set) *set = iset;
1325: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1326: const char *v = PetscBools[currentvalue];
1327: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1328: }
1329: return(0);
1330: }
1332: /*@C
1333: PetscOptionsRealArray - Gets an array of double values for a particular
1334: option in the database. The values must be separated with commas with
1335: no intervening spaces.
1337: Logically Collective on the communicator passed in PetscOptionsBegin()
1339: Input Parameters:
1340: + opt - the option one is seeking
1341: . text - short string describing option
1342: . man - manual page for option
1343: - nmax - maximum number of values
1345: Output Parameter:
1346: + value - location to copy values
1347: . nmax - actual number of values found
1348: - set - PETSC_TRUE if found, else PETSC_FALSE
1350: Level: beginner
1352: Notes:
1353: The user should pass in an array of doubles
1355: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1357: Concepts: options database^array of strings
1359: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1360: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1361: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1362: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1363: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1364: PetscOptionsFList(), PetscOptionsEList()
1365: @*/
1366: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1367: {
1368: PetscErrorCode ierr;
1369: PetscInt i;
1370: PetscOptionItem amsopt;
1373: if (!PetscOptionsObject->count) {
1374: PetscReal *vals;
1376: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1377: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1378: vals = (PetscReal*)amsopt->data;
1379: for (i=0; i<*n; i++) vals[i] = value[i];
1380: amsopt->arraylength = *n;
1381: }
1382: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1383: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1384: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1385: for (i=1; i<*n; i++) {
1386: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1387: }
1388: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1389: }
1390: return(0);
1391: }
1393: /*@C
1394: PetscOptionsScalarArray - Gets an array of Scalar 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 PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1428: {
1429: PetscErrorCode ierr;
1430: PetscInt i;
1431: PetscOptionItem amsopt;
1434: if (!PetscOptionsObject->count) {
1435: PetscScalar *vals;
1437: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1438: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1439: vals = (PetscScalar*)amsopt->data;
1440: for (i=0; i<*n; i++) vals[i] = value[i];
1441: amsopt->arraylength = *n;
1442: }
1443: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1444: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1445: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1446: for (i=1; i<*n; i++) {
1447: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1448: }
1449: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1450: }
1451: return(0);
1452: }
1454: /*@C
1455: PetscOptionsIntArray - Gets an array of integers for a particular
1456: option in the database.
1458: Logically Collective on the communicator passed in PetscOptionsBegin()
1460: Input Parameters:
1461: + opt - the option one is seeking
1462: . text - short string describing option
1463: . man - manual page for option
1464: - n - maximum number of values
1466: Output Parameter:
1467: + value - location to copy values
1468: . n - actual number of values found
1469: - set - PETSC_TRUE if found, else PETSC_FALSE
1471: Level: beginner
1473: Notes:
1474: The array can be passed as
1475: a comma separated list: 0,1,2,3,4,5,6,7
1476: a range (start-end+1): 0-8
1477: a range with given increment (start-end+1:inc): 0-7:2
1478: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1480: There must be no intervening spaces between the values.
1482: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1484: Concepts: options database^array of ints
1486: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1487: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1488: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1489: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1490: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1491: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1492: @*/
1493: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1494: {
1496: PetscInt i;
1497: PetscOptionItem amsopt;
1500: if (!PetscOptionsObject->count) {
1501: PetscInt *vals;
1503: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1504: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1505: vals = (PetscInt*)amsopt->data;
1506: for (i=0; i<*n; i++) vals[i] = value[i];
1507: amsopt->arraylength = *n;
1508: }
1509: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1510: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1511: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1512: for (i=1; i<*n; i++) {
1513: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1514: }
1515: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1516: }
1517: return(0);
1518: }
1520: /*@C
1521: PetscOptionsStringArray - Gets an array of string values for a particular
1522: option in the database. The values must be separated with commas with
1523: no intervening spaces.
1525: Logically Collective on the communicator passed in PetscOptionsBegin()
1527: Input Parameters:
1528: + opt - the option one is seeking
1529: . text - short string describing option
1530: . man - manual page for option
1531: - nmax - maximum number of strings
1533: Output Parameter:
1534: + value - location to copy strings
1535: . nmax - actual number of strings found
1536: - set - PETSC_TRUE if found, else PETSC_FALSE
1538: Level: beginner
1540: Notes:
1541: The user should pass in an array of pointers to char, to hold all the
1542: strings returned by this function.
1544: The user is responsible for deallocating the strings that are
1545: returned. The Fortran interface for this routine is not supported.
1547: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1549: Concepts: options database^array of strings
1551: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1552: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1553: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1554: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1555: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1556: PetscOptionsFList(), PetscOptionsEList()
1557: @*/
1558: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1559: {
1560: PetscErrorCode ierr;
1561: PetscOptionItem amsopt;
1564: if (!PetscOptionsObject->count) {
1565: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1566: PetscMalloc1(*nmax,(char**)&amsopt->data);
1568: amsopt->arraylength = *nmax;
1569: }
1570: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1571: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1572: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1573: }
1574: return(0);
1575: }
1577: /*@C
1578: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1579: option in the database. The values must be separated with commas with
1580: no intervening spaces.
1582: Logically Collective on the communicator passed in PetscOptionsBegin()
1584: Input Parameters:
1585: + opt - the option one is seeking
1586: . text - short string describing option
1587: . man - manual page for option
1588: - nmax - maximum number of values
1590: Output Parameter:
1591: + value - location to copy values
1592: . nmax - actual number of values found
1593: - set - PETSC_TRUE if found, else PETSC_FALSE
1595: Level: beginner
1597: Notes:
1598: The user should pass in an array of doubles
1600: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1602: Concepts: options database^array of strings
1604: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1605: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1606: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1607: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1608: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1609: PetscOptionsFList(), PetscOptionsEList()
1610: @*/
1611: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1612: {
1613: PetscErrorCode ierr;
1614: PetscInt i;
1615: PetscOptionItem amsopt;
1618: if (!PetscOptionsObject->count) {
1619: PetscBool *vals;
1621: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1622: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1623: vals = (PetscBool*)amsopt->data;
1624: for (i=0; i<*n; i++) vals[i] = value[i];
1625: amsopt->arraylength = *n;
1626: }
1627: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1628: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1629: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1630: for (i=1; i<*n; i++) {
1631: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1632: }
1633: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1634: }
1635: return(0);
1636: }
1638: /*@C
1639: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1641: Logically Collective on the communicator passed in PetscOptionsBegin()
1643: Input Parameters:
1644: + opt - option name
1645: . text - short string that describes the option
1646: - man - manual page with additional information on option
1648: Output Parameter:
1649: + viewer - the viewer
1650: - set - PETSC_TRUE if found, else PETSC_FALSE
1652: Level: beginner
1654: Concepts: options database^has int
1656: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1658: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1660: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1661: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1662: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1663: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1664: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1665: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1666: PetscOptionsFList(), PetscOptionsEList()
1667: @*/
1668: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1669: {
1670: PetscErrorCode ierr;
1671: PetscOptionItem amsopt;
1674: if (!PetscOptionsObject->count) {
1675: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1676: /* must use system malloc since SAWs may free this */
1677: PetscStrdup("",(char**)&amsopt->data);
1678: }
1679: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
1680: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1681: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1682: }
1683: return(0);
1684: }
1687: /*@C
1688: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1689: in KSPSetFromOptions_GMRES().
1691: Logically Collective on the communicator passed in PetscOptionsBegin()
1693: Input Parameter:
1694: . head - the heading text
1697: Level: intermediate
1699: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1701: Can be followed by a call to PetscOptionsTail() in the same function.
1703: Concepts: options database^subheading
1705: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1706: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1707: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1708: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1709: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1710: PetscOptionsFList(), PetscOptionsEList()
1711: @*/
1712: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1713: {
1717: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1718: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1719: }
1720: return(0);
1721: }