Actual source code: aoptions.c
petsc-3.9.4 2018-09-11
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: If the user does not supply the option at all value is NOT changed. Thus
668: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
670: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
672: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
673: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
674: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
675: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
676: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
677: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
678: PetscOptionsFList(), PetscOptionsEList()
679: @*/
680: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
681: {
683: PetscInt ntext = 0;
684: PetscInt tval;
685: PetscBool tflg;
688: while (list[ntext++]) {
689: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
690: }
691: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
692: ntext -= 3;
693: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
694: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
695: if (tflg) *value = (PetscEnum)tval;
696: if (set) *set = tflg;
697: return(0);
698: }
700: /*@C
701: PetscOptionsEnumArray - Gets an array of enum values for a particular
702: option in the database.
704: Logically Collective on the communicator passed in PetscOptionsBegin()
706: Input Parameters:
707: + opt - the option one is seeking
708: . text - short string describing option
709: . man - manual page for option
710: - n - maximum number of values
712: Output Parameter:
713: + value - location to copy values
714: . n - actual number of values found
715: - set - PETSC_TRUE if found, else PETSC_FALSE
717: Level: beginner
719: Notes:
720: The array must be passed as a comma separated list.
722: There must be no intervening spaces between the values.
724: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
726: Concepts: options database^array of enums
728: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
729: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
730: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
731: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
732: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
733: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
734: @*/
735: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
736: {
737: PetscInt i,nlist = 0;
738: PetscOptionItem amsopt;
739: PetscErrorCode ierr;
742: while (list[nlist++]) if (nlist > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
743: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
744: nlist -= 3; /* drop enum name, prefix, and null termination */
745: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
746: PetscEnum *vals;
747: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
748: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
749: amsopt->nlist = nlist;
750: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
751: amsopt->arraylength = *n;
752: vals = (PetscEnum*)amsopt->data;
753: for (i=0; i<*n; i++) vals[i] = value[i];
754: }
755: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
756: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
757: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
758: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
759: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
760: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
761: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
762: }
763: return(0);
764: }
766: /* -------------------------------------------------------------------------------------------------------------*/
767: /*@C
768: PetscOptionsInt - Gets the integer value for a particular option in the database.
770: Logically Collective on the communicator passed in PetscOptionsBegin()
772: Input Parameters:
773: + opt - option name
774: . text - short string that describes the option
775: . man - manual page with additional information on option
776: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
777: $ PetscOptionsInt(..., obj->value,&object->value,...) or
778: $ value = defaultvalue
779: $ PetscOptionsInt(..., value,&value,&flg);
780: $ if (flg) {
782: Output Parameter:
783: + value - the integer value to return
784: - flg - PETSC_TRUE if found, else PETSC_FALSE
786: Notes: If the user does not supply the option at all value is NOT changed. Thus
787: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
789: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
791: Level: beginner
793: Concepts: options database^has int
795: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
797: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
798: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
799: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
800: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
801: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
802: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
803: PetscOptionsFList(), PetscOptionsEList()
804: @*/
805: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set)
806: {
807: PetscErrorCode ierr;
808: PetscOptionItem amsopt;
809: PetscBool wasset;
812: if (!PetscOptionsObject->count) {
813: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
814: PetscMalloc(sizeof(PetscInt),&amsopt->data);
815: *(PetscInt*)amsopt->data = currentvalue;
817: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
818: if (wasset) {
819: *(PetscInt*)amsopt->data = currentvalue;
820: }
821: }
822: PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
823: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
824: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
825: }
826: return(0);
827: }
829: /*@C
830: PetscOptionsString - Gets the string value for a particular option in the database.
832: Logically Collective on the communicator passed in PetscOptionsBegin()
834: Input Parameters:
835: + opt - option name
836: . text - short string that describes the option
837: . man - manual page with additional information on option
838: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
839: - len - length of the result string including null terminator
841: Output Parameter:
842: + value - the value to return
843: - flg - PETSC_TRUE if found, else PETSC_FALSE
845: Level: beginner
847: Concepts: options database^has int
849: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
851: 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).
853: If the user does not supply the option at all value is NOT changed. Thus
854: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
856: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
859: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
860: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
861: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
862: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
863: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
864: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
865: PetscOptionsFList(), PetscOptionsEList()
866: @*/
867: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
868: {
869: PetscErrorCode ierr;
870: PetscOptionItem amsopt;
873: if (!PetscOptionsObject->count) {
874: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
875: /* must use system malloc since SAWs may free this */
876: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
877: }
878: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
879: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
880: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
881: }
882: return(0);
883: }
885: /*@C
886: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
888: Logically Collective on the communicator passed in PetscOptionsBegin()
890: Input Parameters:
891: + opt - option name
892: . text - short string that describes the option
893: . man - manual page with additional information on option
894: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
895: $ PetscOptionsReal(..., obj->value,&object->value,...) or
896: $ value = defaultvalue
897: $ PetscOptionsReal(..., value,&value,&flg);
898: $ if (flg) {
900: Output Parameter:
901: + value - the value to return
902: - flg - PETSC_TRUE if found, else PETSC_FALSE
904: Notes: If the user does not supply the option at all value is NOT changed. Thus
905: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
907: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
909: Level: beginner
911: Concepts: options database^has int
913: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
915: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
916: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
917: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
918: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
919: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
920: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
921: PetscOptionsFList(), PetscOptionsEList()
922: @*/
923: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
924: {
925: PetscErrorCode ierr;
926: PetscOptionItem amsopt;
929: if (!PetscOptionsObject->count) {
930: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
931: PetscMalloc(sizeof(PetscReal),&amsopt->data);
933: *(PetscReal*)amsopt->data = currentvalue;
934: }
935: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
936: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
937: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
938: }
939: return(0);
940: }
942: /*@C
943: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
945: Logically Collective on the communicator passed in PetscOptionsBegin()
947: Input Parameters:
948: + opt - option name
949: . text - short string that describes the option
950: . man - manual page with additional information on option
951: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
952: $ PetscOptionsScalar(..., obj->value,&object->value,...) or
953: $ value = defaultvalue
954: $ PetscOptionsScalar(..., value,&value,&flg);
955: $ if (flg) {
958: Output Parameter:
959: + value - the value to return
960: - flg - PETSC_TRUE if found, else PETSC_FALSE
962: Notes: If the user does not supply the option at all value is NOT changed. Thus
963: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
965: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
967: Level: beginner
969: Concepts: options database^has int
971: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
973: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
974: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
975: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
976: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
977: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
978: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
979: PetscOptionsFList(), PetscOptionsEList()
980: @*/
981: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
982: {
986: #if !defined(PETSC_USE_COMPLEX)
987: PetscOptionsReal(opt,text,man,currentvalue,value,set);
988: #else
989: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
990: #endif
991: return(0);
992: }
994: /*@C
995: 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
996: its value is set to false.
998: Logically Collective on the communicator passed in PetscOptionsBegin()
1000: Input Parameters:
1001: + opt - option name
1002: . text - short string that describes the option
1003: - man - manual page with additional information on option
1005: Output Parameter:
1006: . flg - PETSC_TRUE if found, else PETSC_FALSE
1008: Level: beginner
1010: Concepts: options database^has int
1012: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1014: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1015: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1016: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1017: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1018: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1019: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1020: PetscOptionsFList(), PetscOptionsEList()
1021: @*/
1022: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1023: {
1024: PetscErrorCode ierr;
1025: PetscOptionItem amsopt;
1028: if (!PetscOptionsObject->count) {
1029: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1030: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1032: *(PetscBool*)amsopt->data = PETSC_FALSE;
1033: }
1034: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1035: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1036: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1037: }
1038: return(0);
1039: }
1041: /*@C
1042: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1044: Logically Collective on the communicator passed in PetscOptionsBegin()
1046: Input Parameters:
1047: + opt - option name
1048: . text - short string that describes the option
1049: . man - manual page with additional information on option
1050: . list - the possible choices
1051: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1052: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1053: $ if (flg) {
1054: - len - the length of the character array value
1056: Output Parameter:
1057: + value - the value to return
1058: - set - PETSC_TRUE if found, else PETSC_FALSE
1060: Level: intermediate
1062: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1064: If the user does not supply the option at all value is NOT changed. Thus
1065: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1067: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1069: See PetscOptionsEList() for when the choices are given in a string array
1071: To get a listing of all currently specified options,
1072: see PetscOptionsView() or PetscOptionsGetAll()
1074: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1076: Concepts: options database^list
1078: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1079: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1080: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1081: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1082: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1083: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1084: @*/
1085: 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)
1086: {
1087: PetscErrorCode ierr;
1088: PetscOptionItem amsopt;
1091: if (!PetscOptionsObject->count) {
1092: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1093: /* must use system malloc since SAWs may free this */
1094: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1095: amsopt->flist = list;
1096: }
1097: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1098: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1099: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1100: }
1101: return(0);
1102: }
1104: /*@C
1105: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1107: Logically Collective on the communicator passed in PetscOptionsBegin()
1109: Input Parameters:
1110: + opt - option name
1111: . ltext - short string that describes the option
1112: . man - manual page with additional information on option
1113: . list - the possible choices (one of these must be selected, anything else is invalid)
1114: . ntext - number of choices
1115: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1116: $ PetscOptionsElist(..., obj->value,&value,&flg);
1117: $ if (flg) {
1120: Output Parameter:
1121: + value - the index of the value to return
1122: - set - PETSC_TRUE if found, else PETSC_FALSE
1124: Level: intermediate
1126: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1128: If the user does not supply the option at all value is NOT changed. Thus
1129: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1131: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1133: Concepts: options database^list
1135: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1136: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1137: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1138: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1139: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1140: PetscOptionsFList(), PetscOptionsEnum()
1141: @*/
1142: 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)
1143: {
1144: PetscErrorCode ierr;
1145: PetscInt i;
1146: PetscOptionItem amsopt;
1149: if (!PetscOptionsObject->count) {
1150: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1151: /* must use system malloc since SAWs may free this */
1152: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1153: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1154: amsopt->nlist = ntext;
1155: }
1156: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1157: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1158: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1159: for (i=0; i<ntext; i++) {
1160: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1161: }
1162: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1163: }
1164: return(0);
1165: }
1167: /*@C
1168: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1169: which at most a single value can be true.
1171: Logically Collective on the communicator passed in PetscOptionsBegin()
1173: Input Parameters:
1174: + opt - option name
1175: . text - short string that describes the option
1176: - man - manual page with additional information on option
1178: Output Parameter:
1179: . flg - whether that option was set or not
1181: Level: intermediate
1183: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1185: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1187: Concepts: options database^logical group
1189: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1190: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1191: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1192: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1193: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1194: PetscOptionsFList(), PetscOptionsEList()
1195: @*/
1196: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1197: {
1198: PetscErrorCode ierr;
1199: PetscOptionItem amsopt;
1202: if (!PetscOptionsObject->count) {
1203: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1204: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1206: *(PetscBool*)amsopt->data = PETSC_FALSE;
1207: }
1208: *flg = PETSC_FALSE;
1209: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1210: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1211: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1212: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1213: }
1214: return(0);
1215: }
1217: /*@C
1218: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1219: which at most a single value can be true.
1221: Logically Collective on the communicator passed in PetscOptionsBegin()
1223: Input Parameters:
1224: + opt - option name
1225: . text - short string that describes the option
1226: - man - manual page with additional information on option
1228: Output Parameter:
1229: . flg - PETSC_TRUE if found, else PETSC_FALSE
1231: Level: intermediate
1233: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1235: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1237: Concepts: options database^logical group
1239: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1240: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1241: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1242: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1243: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1244: PetscOptionsFList(), PetscOptionsEList()
1245: @*/
1246: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1247: {
1248: PetscErrorCode ierr;
1249: PetscOptionItem amsopt;
1252: if (!PetscOptionsObject->count) {
1253: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1254: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1256: *(PetscBool*)amsopt->data = PETSC_FALSE;
1257: }
1258: *flg = PETSC_FALSE;
1259: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1260: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1261: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1262: }
1263: return(0);
1264: }
1266: /*@C
1267: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1268: which at most a single value can be true.
1270: Logically Collective on the communicator passed in PetscOptionsBegin()
1272: Input Parameters:
1273: + opt - option name
1274: . text - short string that describes the option
1275: - man - manual page with additional information on option
1277: Output Parameter:
1278: . flg - PETSC_TRUE if found, else PETSC_FALSE
1280: Level: intermediate
1282: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1284: Must follow a PetscOptionsBoolGroupBegin()
1286: Concepts: options database^logical group
1288: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1289: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1290: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1291: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1292: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1293: PetscOptionsFList(), PetscOptionsEList()
1294: @*/
1295: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1296: {
1297: PetscErrorCode ierr;
1298: PetscOptionItem amsopt;
1301: if (!PetscOptionsObject->count) {
1302: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1303: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1305: *(PetscBool*)amsopt->data = PETSC_FALSE;
1306: }
1307: *flg = PETSC_FALSE;
1308: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1309: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1310: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1311: }
1312: return(0);
1313: }
1315: /*@C
1316: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1318: Logically Collective on the communicator passed in PetscOptionsBegin()
1320: Input Parameters:
1321: + opt - option name
1322: . text - short string that describes the option
1323: . man - manual page with additional information on option
1324: - currentvalue - the current value
1326: Output Parameter:
1327: . flg - PETSC_TRUE or PETSC_FALSE
1328: . set - PETSC_TRUE if found, else PETSC_FALSE
1330: Notes:
1331: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1332: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1334: 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
1335: is equivalent to -requested_bool true
1337: If the user does not supply the option at all flg is NOT changed. Thus
1338: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1340: Level: beginner
1342: Concepts: options database^logical
1344: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1346: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1347: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1348: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1349: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1350: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1351: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1352: PetscOptionsFList(), PetscOptionsEList()
1353: @*/
1354: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1355: {
1356: PetscErrorCode ierr;
1357: PetscBool iset;
1358: PetscOptionItem amsopt;
1361: if (!PetscOptionsObject->count) {
1362: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1363: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1365: *(PetscBool*)amsopt->data = currentvalue;
1366: }
1367: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1368: if (set) *set = iset;
1369: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1370: const char *v = PetscBools[currentvalue];
1371: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1372: }
1373: return(0);
1374: }
1376: /*@C
1377: PetscOptionsRealArray - Gets an array of double values for a particular
1378: option in the database. The values must be separated with commas with
1379: no intervening spaces.
1381: Logically Collective on the communicator passed in PetscOptionsBegin()
1383: Input Parameters:
1384: + opt - the option one is seeking
1385: . text - short string describing option
1386: . man - manual page for option
1387: - nmax - maximum number of values
1389: Output Parameter:
1390: + value - location to copy values
1391: . nmax - actual number of values found
1392: - set - PETSC_TRUE if found, else PETSC_FALSE
1394: Level: beginner
1396: Notes:
1397: The user should pass in an array of doubles
1399: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1401: Concepts: options database^array of strings
1403: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1404: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1405: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1406: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1407: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1408: PetscOptionsFList(), PetscOptionsEList()
1409: @*/
1410: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1411: {
1412: PetscErrorCode ierr;
1413: PetscInt i;
1414: PetscOptionItem amsopt;
1417: if (!PetscOptionsObject->count) {
1418: PetscReal *vals;
1420: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1421: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1422: vals = (PetscReal*)amsopt->data;
1423: for (i=0; i<*n; i++) vals[i] = value[i];
1424: amsopt->arraylength = *n;
1425: }
1426: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1427: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1428: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1429: for (i=1; i<*n; i++) {
1430: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1431: }
1432: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1433: }
1434: return(0);
1435: }
1437: /*@C
1438: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1439: option in the database. The values must be separated with commas with
1440: no intervening spaces.
1442: Logically Collective on the communicator passed in PetscOptionsBegin()
1444: Input Parameters:
1445: + opt - the option one is seeking
1446: . text - short string describing option
1447: . man - manual page for option
1448: - nmax - maximum number of values
1450: Output Parameter:
1451: + value - location to copy values
1452: . nmax - actual number of values found
1453: - set - PETSC_TRUE if found, else PETSC_FALSE
1455: Level: beginner
1457: Notes:
1458: The user should pass in an array of doubles
1460: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1462: Concepts: options database^array of strings
1464: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1465: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1466: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1467: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1468: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1469: PetscOptionsFList(), PetscOptionsEList()
1470: @*/
1471: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1472: {
1473: PetscErrorCode ierr;
1474: PetscInt i;
1475: PetscOptionItem amsopt;
1478: if (!PetscOptionsObject->count) {
1479: PetscScalar *vals;
1481: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1482: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1483: vals = (PetscScalar*)amsopt->data;
1484: for (i=0; i<*n; i++) vals[i] = value[i];
1485: amsopt->arraylength = *n;
1486: }
1487: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1488: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1489: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1490: for (i=1; i<*n; i++) {
1491: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1492: }
1493: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1494: }
1495: return(0);
1496: }
1498: /*@C
1499: PetscOptionsIntArray - Gets an array of integers for a particular
1500: option in the database.
1502: Logically Collective on the communicator passed in PetscOptionsBegin()
1504: Input Parameters:
1505: + opt - the option one is seeking
1506: . text - short string describing option
1507: . man - manual page for option
1508: - n - maximum number of values
1510: Output Parameter:
1511: + value - location to copy values
1512: . n - actual number of values found
1513: - set - PETSC_TRUE if found, else PETSC_FALSE
1515: Level: beginner
1517: Notes:
1518: The array can be passed as
1519: a comma separated list: 0,1,2,3,4,5,6,7
1520: a range (start-end+1): 0-8
1521: a range with given increment (start-end+1:inc): 0-7:2
1522: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1524: There must be no intervening spaces between the values.
1526: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1528: Concepts: options database^array of ints
1530: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1531: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1532: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1533: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1534: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1535: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1536: @*/
1537: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1538: {
1540: PetscInt i;
1541: PetscOptionItem amsopt;
1544: if (!PetscOptionsObject->count) {
1545: PetscInt *vals;
1547: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1548: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1549: vals = (PetscInt*)amsopt->data;
1550: for (i=0; i<*n; i++) vals[i] = value[i];
1551: amsopt->arraylength = *n;
1552: }
1553: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1554: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1555: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1556: for (i=1; i<*n; i++) {
1557: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1558: }
1559: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1560: }
1561: return(0);
1562: }
1564: /*@C
1565: PetscOptionsStringArray - Gets an array of string values for a particular
1566: option in the database. The values must be separated with commas with
1567: no intervening spaces.
1569: Logically Collective on the communicator passed in PetscOptionsBegin()
1571: Input Parameters:
1572: + opt - the option one is seeking
1573: . text - short string describing option
1574: . man - manual page for option
1575: - nmax - maximum number of strings
1577: Output Parameter:
1578: + value - location to copy strings
1579: . nmax - actual number of strings found
1580: - set - PETSC_TRUE if found, else PETSC_FALSE
1582: Level: beginner
1584: Notes:
1585: The user should pass in an array of pointers to char, to hold all the
1586: strings returned by this function.
1588: The user is responsible for deallocating the strings that are
1589: returned. The Fortran interface for this routine is not supported.
1591: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1593: Concepts: options database^array of strings
1595: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1596: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1597: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1598: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1599: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1600: PetscOptionsFList(), PetscOptionsEList()
1601: @*/
1602: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1603: {
1604: PetscErrorCode ierr;
1605: PetscOptionItem amsopt;
1608: if (!PetscOptionsObject->count) {
1609: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1610: PetscMalloc1(*nmax,(char**)&amsopt->data);
1612: amsopt->arraylength = *nmax;
1613: }
1614: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1615: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1616: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1617: }
1618: return(0);
1619: }
1621: /*@C
1622: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1623: option in the database. The values must be separated with commas with
1624: no intervening spaces.
1626: Logically Collective on the communicator passed in PetscOptionsBegin()
1628: Input Parameters:
1629: + opt - the option one is seeking
1630: . text - short string describing option
1631: . man - manual page for option
1632: - nmax - maximum number of values
1634: Output Parameter:
1635: + value - location to copy values
1636: . nmax - actual number of values found
1637: - set - PETSC_TRUE if found, else PETSC_FALSE
1639: Level: beginner
1641: Notes:
1642: The user should pass in an array of doubles
1644: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1646: Concepts: options database^array of strings
1648: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1649: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1650: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1651: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1652: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1653: PetscOptionsFList(), PetscOptionsEList()
1654: @*/
1655: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1656: {
1657: PetscErrorCode ierr;
1658: PetscInt i;
1659: PetscOptionItem amsopt;
1662: if (!PetscOptionsObject->count) {
1663: PetscBool *vals;
1665: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1666: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1667: vals = (PetscBool*)amsopt->data;
1668: for (i=0; i<*n; i++) vals[i] = value[i];
1669: amsopt->arraylength = *n;
1670: }
1671: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1672: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1673: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1674: for (i=1; i<*n; i++) {
1675: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1676: }
1677: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1678: }
1679: return(0);
1680: }
1682: /*@C
1683: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1685: Logically Collective on the communicator passed in PetscOptionsBegin()
1687: Input Parameters:
1688: + opt - option name
1689: . text - short string that describes the option
1690: - man - manual page with additional information on option
1692: Output Parameter:
1693: + viewer - the viewer
1694: - set - PETSC_TRUE if found, else PETSC_FALSE
1696: Level: beginner
1698: Concepts: options database^has int
1700: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1702: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1704: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1705: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1706: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1707: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1708: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1709: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1710: PetscOptionsFList(), PetscOptionsEList()
1711: @*/
1712: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1713: {
1714: PetscErrorCode ierr;
1715: PetscOptionItem amsopt;
1718: if (!PetscOptionsObject->count) {
1719: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1720: /* must use system malloc since SAWs may free this */
1721: PetscStrdup("",(char**)&amsopt->data);
1722: }
1723: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
1724: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1725: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1726: }
1727: return(0);
1728: }
1731: /*@C
1732: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1733: in KSPSetFromOptions_GMRES().
1735: Logically Collective on the communicator passed in PetscOptionsBegin()
1737: Input Parameter:
1738: . head - the heading text
1741: Level: intermediate
1743: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1745: Can be followed by a call to PetscOptionsTail() in the same function.
1747: Concepts: options database^subheading
1749: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1750: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1751: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1752: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1753: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1754: PetscOptionsFList(), PetscOptionsEList()
1755: @*/
1756: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1757: {
1761: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1762: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1763: }
1764: return(0);
1765: }