Actual source code: aoptions.c
petsc-3.13.6 2020-09-29
3: /*
4: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
5: GUI code to display the options and get values from the users.
7: */
9: #include <petsc/private/petscimpl.h>
10: #include <petscviewer.h>
12: #define ManSection(str) ((str) ? (str) : "None")
14: /*
15: Keep a linked list of options that have been posted and we are waiting for
16: user selection. See the manual page for PetscOptionsBegin()
18: Eventually we'll attach this beast to a MPI_Comm
19: */
22: /*
23: Handles setting up the data structure in a call to PetscOptionsBegin()
24: */
25: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
26: {
33: if (!PetscOptionsObject->alreadyprinted) {
34: if (!PetscOptionsHelpPrintedSingleton) {
35: PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
36: }
37: PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
38: }
39: PetscOptionsObject->next = NULL;
40: PetscOptionsObject->comm = comm;
41: PetscOptionsObject->changedmethod = PETSC_FALSE;
43: PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
44: PetscStrallocpy(title,&PetscOptionsObject->title);
46: PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
47: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
48: if (!PetscOptionsObject->alreadyprinted) {
49: (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
50: }
51: }
52: return(0);
53: }
55: /*
56: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
57: */
58: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
59: {
61: char title[256];
62: PetscBool flg;
66: PetscOptionsObject->object = obj;
67: PetscOptionsObject->alreadyprinted = obj->optionsprinted;
69: PetscStrcmp(obj->description,obj->class_name,&flg);
70: if (flg) {
71: PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
72: } else {
73: PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
74: }
75: PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
76: return(0);
77: }
79: /*
80: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
81: */
82: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
83: {
84: int ierr;
85: PetscOptionItem next;
86: PetscBool valid;
89: PetscOptionsValidKey(opt,&valid);
90: if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);
92: PetscNew(amsopt);
93: (*amsopt)->next = NULL;
94: (*amsopt)->set = PETSC_FALSE;
95: (*amsopt)->type = t;
96: (*amsopt)->data = NULL;
98: PetscStrallocpy(text,&(*amsopt)->text);
99: PetscStrallocpy(opt,&(*amsopt)->option);
100: PetscStrallocpy(man,&(*amsopt)->man);
102: if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
103: else {
104: next = PetscOptionsObject->next;
105: while (next->next) next = next->next;
106: next->next = *amsopt;
107: }
108: return(0);
109: }
111: /*
112: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
114: Collective
116: Input Parameters:
117: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
118: . n - length of the string, must be the same on all processes
119: - str - location to store input
121: Bugs:
122: . Assumes process 0 of the given communicator has access to stdin
124: */
125: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
126: {
127: size_t i;
128: char c;
129: PetscMPIInt rank,nm;
133: MPI_Comm_rank(comm,&rank);
134: if (!rank) {
135: c = (char) getchar();
136: i = 0;
137: while (c != '\n' && i < n-1) {
138: str[i++] = c;
139: c = (char)getchar();
140: }
141: str[i] = 0;
142: }
143: PetscMPIIntCast(n,&nm);
144: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
145: return(0);
146: }
148: /*
149: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
150: */
151: static PetscErrorCode PetscStrdup(const char s[],char *t[])
152: {
154: size_t len;
155: char *tmp = NULL;
158: if (s) {
159: PetscStrlen(s,&len);
160: tmp = (char*) malloc((len+1)*sizeof(char));
161: if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
162: PetscStrcpy(tmp,s);
163: }
164: *t = tmp;
165: return(0);
166: }
169: /*
170: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
172: Notes:
173: this isn't really practical, it is just to demonstrate the principle
175: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
176: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
178: Bugs:
179: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
180: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
181: - Only works for PetscInt == int, PetscReal == double etc
183: Developer Notes:
184: Normally the GUI that presents the options the user and retrieves the values would be running in a different
185: address space and communicating with the PETSc program
187: */
188: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
189: {
190: PetscErrorCode ierr;
191: PetscOptionItem next = PetscOptionsObject->next;
192: char str[512];
193: PetscBool bid;
194: PetscReal ir,*valr;
195: PetscInt *vald;
196: size_t i;
199: (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
200: while (next) {
201: switch (next->type) {
202: case OPTION_HEAD:
203: break;
204: case OPTION_INT_ARRAY:
205: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
206: vald = (PetscInt*) next->data;
207: for (i=0; i<next->arraylength; i++) {
208: PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
209: if (i < next->arraylength-1) {
210: PetscPrintf(PETSC_COMM_WORLD,",");
211: }
212: }
213: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
214: PetscScanString(PETSC_COMM_WORLD,512,str);
215: if (str[0]) {
216: PetscToken token;
217: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
218: size_t len;
219: char *value;
220: PetscBool foundrange;
222: next->set = PETSC_TRUE;
223: value = str;
224: PetscTokenCreate(value,',',&token);
225: PetscTokenFind(token,&value);
226: while (n < nmax) {
227: if (!value) break;
229: /* look for form d-D where d and D are integers */
230: foundrange = PETSC_FALSE;
231: PetscStrlen(value,&len);
232: if (value[0] == '-') i=2;
233: else i=1;
234: for (;i<len; i++) {
235: if (value[i] == '-') {
236: if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
237: value[i] = 0;
238: PetscOptionsStringToInt(value,&start);
239: PetscOptionsStringToInt(value+i+1,&end);
240: 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);
241: 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);
242: for (; start<end; start++) {
243: *dvalue = start; dvalue++;n++;
244: }
245: foundrange = PETSC_TRUE;
246: break;
247: }
248: }
249: if (!foundrange) {
250: PetscOptionsStringToInt(value,dvalue);
251: dvalue++;
252: n++;
253: }
254: PetscTokenFind(token,&value);
255: }
256: PetscTokenDestroy(&token);
257: }
258: break;
259: case OPTION_REAL_ARRAY:
260: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
261: valr = (PetscReal*) next->data;
262: for (i=0; i<next->arraylength; i++) {
263: PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
264: if (i < next->arraylength-1) {
265: PetscPrintf(PETSC_COMM_WORLD,",");
266: }
267: }
268: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
269: PetscScanString(PETSC_COMM_WORLD,512,str);
270: if (str[0]) {
271: PetscToken token;
272: PetscInt n = 0,nmax = next->arraylength;
273: PetscReal *dvalue = (PetscReal*)next->data;
274: char *value;
276: next->set = PETSC_TRUE;
277: value = str;
278: PetscTokenCreate(value,',',&token);
279: PetscTokenFind(token,&value);
280: while (n < nmax) {
281: if (!value) break;
282: PetscOptionsStringToReal(value,dvalue);
283: dvalue++;
284: n++;
285: PetscTokenFind(token,&value);
286: }
287: PetscTokenDestroy(&token);
288: }
289: break;
290: case OPTION_INT:
291: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
292: PetscScanString(PETSC_COMM_WORLD,512,str);
293: if (str[0]) {
294: #if defined(PETSC_SIZEOF_LONG_LONG)
295: long long lid;
296: sscanf(str,"%lld",&lid);
297: 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);
298: #else
299: long lid;
300: sscanf(str,"%ld",&lid);
301: 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);
302: #endif
304: next->set = PETSC_TRUE;
305: *((PetscInt*)next->data) = (PetscInt)lid;
306: }
307: break;
308: case OPTION_REAL:
309: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
310: PetscScanString(PETSC_COMM_WORLD,512,str);
311: if (str[0]) {
312: #if defined(PETSC_USE_REAL_SINGLE)
313: sscanf(str,"%e",&ir);
314: #elif defined(PETSC_USE_REAL___FP16)
315: float irtemp;
316: sscanf(str,"%e",&irtemp);
317: ir = irtemp;
318: #elif defined(PETSC_USE_REAL_DOUBLE)
319: sscanf(str,"%le",&ir);
320: #elif defined(PETSC_USE_REAL___FLOAT128)
321: ir = strtoflt128(str,0);
322: #else
323: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
324: #endif
325: next->set = PETSC_TRUE;
326: *((PetscReal*)next->data) = ir;
327: }
328: break;
329: case OPTION_BOOL:
330: 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);
331: PetscScanString(PETSC_COMM_WORLD,512,str);
332: if (str[0]) {
333: PetscOptionsStringToBool(str,&bid);
334: next->set = PETSC_TRUE;
335: *((PetscBool*)next->data) = bid;
336: }
337: break;
338: case OPTION_STRING:
339: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
340: PetscScanString(PETSC_COMM_WORLD,512,str);
341: if (str[0]) {
342: next->set = PETSC_TRUE;
343: /* must use system malloc since SAWs may free this */
344: PetscStrdup(str,(char**)&next->data);
345: }
346: break;
347: case OPTION_FLIST:
348: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
349: PetscScanString(PETSC_COMM_WORLD,512,str);
350: if (str[0]) {
351: PetscOptionsObject->changedmethod = PETSC_TRUE;
352: next->set = PETSC_TRUE;
353: /* must use system malloc since SAWs may free this */
354: PetscStrdup(str,(char**)&next->data);
355: }
356: break;
357: default:
358: break;
359: }
360: next = next->next;
361: }
362: return(0);
363: }
365: #if defined(PETSC_HAVE_SAWS)
366: #include <petscviewersaws.h>
368: static int count = 0;
370: PetscErrorCode PetscOptionsSAWsDestroy(void)
371: {
373: return(0);
374: }
376: static const char *OptionsHeader = "<head>\n"
377: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
378: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
379: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
380: "<script>\n"
381: "jQuery(document).ready(function() {\n"
382: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
383: "})\n"
384: "</script>\n"
385: "</head>\n";
387: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
388: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
390: /*
391: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
393: Bugs:
394: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
395: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
396: - Only works for PetscInt == int, PetscReal == double etc
399: */
400: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
401: {
402: PetscErrorCode ierr;
403: PetscOptionItem next = PetscOptionsObject->next;
404: static int mancount = 0;
405: char options[16];
406: PetscBool changedmethod = PETSC_FALSE;
407: PetscBool stopasking = PETSC_FALSE;
408: char manname[16],textname[16];
409: char dir[1024];
412: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
413: sprintf(options,"Options_%d",count++);
415: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
417: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
418: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
419: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
420: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
421: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
422: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
424: while (next) {
425: sprintf(manname,"_man_%d",mancount);
426: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
427: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
428: sprintf(textname,"_text_%d",mancount++);
429: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
430: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
432: switch (next->type) {
433: case OPTION_HEAD:
434: break;
435: case OPTION_INT_ARRAY:
436: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
437: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
438: break;
439: case OPTION_REAL_ARRAY:
440: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
441: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
442: break;
443: case OPTION_INT:
444: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
445: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
446: break;
447: case OPTION_REAL:
448: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
449: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
450: break;
451: case OPTION_BOOL:
452: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
453: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
454: break;
455: case OPTION_BOOL_ARRAY:
456: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
457: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
458: break;
459: case OPTION_STRING:
460: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
461: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
462: break;
463: case OPTION_STRING_ARRAY:
464: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
465: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
466: break;
467: case OPTION_FLIST:
468: {
469: PetscInt ntext;
470: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
471: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
472: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
473: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
474: }
475: break;
476: case OPTION_ELIST:
477: {
478: PetscInt ntext = next->nlist;
479: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
480: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
481: PetscMalloc1((ntext+1),(char***)&next->edata);
482: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
483: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
484: }
485: break;
486: default:
487: break;
488: }
489: next = next->next;
490: }
492: /* wait until accessor has unlocked the memory */
493: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
494: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
495: PetscSAWsBlock();
496: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
497: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
499: /* determine if any values have been set in GUI */
500: next = PetscOptionsObject->next;
501: while (next) {
502: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
503: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
504: next = next->next;
505: }
507: /* reset counter to -2; this updates the screen with the new options for the selected method */
508: if (changedmethod) PetscOptionsObject->count = -2;
510: if (stopasking) {
511: PetscOptionsPublish = PETSC_FALSE;
512: PetscOptionsObject->count = 0;//do not ask for same thing again
513: }
515: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
516: return(0);
517: }
518: #endif
520: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
521: {
522: PetscErrorCode ierr;
523: PetscOptionItem last;
524: char option[256],value[1024],tmp[32];
525: size_t j;
528: if (PetscOptionsObject->next) {
529: if (!PetscOptionsObject->count) {
530: #if defined(PETSC_HAVE_SAWS)
531: PetscOptionsSAWsInput(PetscOptionsObject);
532: #else
533: PetscOptionsGetFromTextInput(PetscOptionsObject);
534: #endif
535: }
536: }
538: PetscFree(PetscOptionsObject->title);
540: /* reset counter to -2; this updates the screen with the new options for the selected method */
541: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
542: /* reset alreadyprinted flag */
543: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
544: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
545: PetscOptionsObject->object = NULL;
547: while (PetscOptionsObject->next) {
548: if (PetscOptionsObject->next->set) {
549: if (PetscOptionsObject->prefix) {
550: PetscStrcpy(option,"-");
551: PetscStrcat(option,PetscOptionsObject->prefix);
552: PetscStrcat(option,PetscOptionsObject->next->option+1);
553: } else {
554: PetscStrcpy(option,PetscOptionsObject->next->option);
555: }
557: switch (PetscOptionsObject->next->type) {
558: case OPTION_HEAD:
559: break;
560: case OPTION_INT_ARRAY:
561: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
562: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
563: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
564: PetscStrcat(value,",");
565: PetscStrcat(value,tmp);
566: }
567: break;
568: case OPTION_INT:
569: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
570: break;
571: case OPTION_REAL:
572: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
573: break;
574: case OPTION_REAL_ARRAY:
575: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
576: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
577: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
578: PetscStrcat(value,",");
579: PetscStrcat(value,tmp);
580: }
581: break;
582: case OPTION_SCALAR_ARRAY:
583: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
584: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
585: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
586: PetscStrcat(value,",");
587: PetscStrcat(value,tmp);
588: }
589: break;
590: case OPTION_BOOL:
591: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
592: break;
593: case OPTION_BOOL_ARRAY:
594: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
595: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
596: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
597: PetscStrcat(value,",");
598: PetscStrcat(value,tmp);
599: }
600: break;
601: case OPTION_FLIST:
602: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
603: break;
604: case OPTION_ELIST:
605: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
606: break;
607: case OPTION_STRING:
608: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
609: break;
610: case OPTION_STRING_ARRAY:
611: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
612: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
613: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
614: PetscStrcat(value,",");
615: PetscStrcat(value,tmp);
616: }
617: break;
618: }
619: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
620: }
621: if (PetscOptionsObject->next->type == OPTION_ELIST) {
622: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
623: }
624: PetscFree(PetscOptionsObject->next->text);
625: PetscFree(PetscOptionsObject->next->option);
626: PetscFree(PetscOptionsObject->next->man);
627: PetscFree(PetscOptionsObject->next->edata);
629: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
630: free(PetscOptionsObject->next->data);
631: } else {
632: PetscFree(PetscOptionsObject->next->data);
633: }
635: last = PetscOptionsObject->next;
636: PetscOptionsObject->next = PetscOptionsObject->next->next;
637: PetscFree(last);
638: }
639: PetscFree(PetscOptionsObject->prefix);
640: PetscOptionsObject->next = NULL;
641: return(0);
642: }
644: /*MC
645: PetscOptionsEnum - Gets the enum value for a particular option in the database.
647: Logically Collective on the communicator passed in PetscOptionsBegin()
649: Synopsis:
650: #include "petscsys.h"
651: PetscErrorCode PetscOptionsEnum(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
653: Input Parameters:
654: + opt - option name
655: . text - short string that describes the option
656: . man - manual page with additional information on option
657: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
658: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
659: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
660: $ value = defaultvalue
661: $ PetscOptionsEnum(..., value,&value,&flg);
662: $ if (flg) {
664: Output Parameter:
665: + value - the value to return
666: - set - PETSC_TRUE if found, else PETSC_FALSE
668: Level: beginner
670: Notes:
671: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
673: list is usually something like PCASMTypes or some other predefined list of enum names
675: If the user does not supply the option at all value is NOT changed. Thus
676: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
678: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
680: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
681: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
682: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
683: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
684: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
685: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
686: PetscOptionsFList(), PetscOptionsEList()
687: M*/
689: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
690: {
692: PetscInt ntext = 0;
693: PetscInt tval;
694: PetscBool tflg;
697: while (list[ntext++]) {
698: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
699: }
700: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
701: ntext -= 3;
702: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
703: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
704: if (tflg) *value = (PetscEnum)tval;
705: if (set) *set = tflg;
706: return(0);
707: }
709: /*MC
710: PetscOptionsEnumArray - Gets an array of enum values for a particular
711: option in the database.
713: Logically Collective on the communicator passed in PetscOptionsBegin()
715: Synopsis:
716: #include "petscsys.h"
717: PetscErrorCode PetscOptionsEnumArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
719: Input Parameters:
720: + opt - the option one is seeking
721: . text - short string describing option
722: . man - manual page for option
723: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
724: - n - maximum number of values
726: Output Parameter:
727: + value - location to copy values
728: . n - actual number of values found
729: - set - PETSC_TRUE if found, else PETSC_FALSE
731: Level: beginner
733: Notes:
734: The array must be passed as a comma separated list.
736: There must be no intervening spaces between the values.
738: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
740: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
741: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
742: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
743: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
744: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
745: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
746: M*/
748: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
749: {
750: PetscInt i,nlist = 0;
751: PetscOptionItem amsopt;
752: PetscErrorCode ierr;
755: 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");
756: if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
757: nlist -= 3; /* drop enum name, prefix, and null termination */
758: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
759: PetscEnum *vals;
760: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
761: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
762: amsopt->nlist = nlist;
763: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
764: amsopt->arraylength = *n;
765: vals = (PetscEnum*)amsopt->data;
766: for (i=0; i<*n; i++) vals[i] = value[i];
767: }
768: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
769: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
770: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
771: for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
772: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
773: for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
774: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
775: }
776: return(0);
777: }
779: /*MC
780: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
782: Logically Collective on the communicator passed in PetscOptionsBegin()
784: Synopsis:
785: #include "petscsys.h"
786: PetscErrorCode PetscOptionsBoundInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)
788: Input Parameters:
789: + opt - option name
790: . text - short string that describes the option
791: . man - manual page with additional information on option
792: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
793: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
794: $ value = defaultvalue
795: $ PetscOptionsInt(..., value,&value,&flg);
796: $ if (flg) {
797: - bound - the requested value should be greater than or equal this bound or an error is generated
799: Output Parameter:
800: + value - the integer value to return
801: - flg - PETSC_TRUE if found, else PETSC_FALSE
803: Notes:
804: If the user does not supply the option at all value is NOT changed. Thus
805: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
807: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
809: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
811: Level: beginner
813: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
814: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
815: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
816: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
817: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
818: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
819: PetscOptionsFList(), PetscOptionsEList()
820: M*/
822: /*MC
823: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
825: Logically Collective on the communicator passed in PetscOptionsBegin()
827: Synopsis:
828: #include "petscsys.h"
829: PetscErrorCode PetscOptionsRangeInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)
831: Input Parameters:
832: + opt - option name
833: . text - short string that describes the option
834: . man - manual page with additional information on option
835: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
836: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
837: $ value = defaultvalue
838: $ PetscOptionsInt(..., value,&value,&flg);
839: $ if (flg) {
840: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
841: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
843: Output Parameter:
844: + value - the integer value to return
845: - flg - PETSC_TRUE if found, else PETSC_FALSE
847: Notes:
848: If the user does not supply the option at all value is NOT changed. Thus
849: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
851: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
853: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
855: Level: beginner
857: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
858: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsBoundedInt()
859: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
860: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
861: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
862: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
863: PetscOptionsFList(), PetscOptionsEList()
864: M*/
866: /*MC
867: PetscOptionsInt - Gets the integer value for a particular option in the database.
869: Logically Collective on the communicator passed in PetscOptionsBegin()
871: Synopsis:
872: #include "petscsys.h"
873: PetscErrorCode PetscOptionsInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))
876: Input Parameters:
877: + opt - option name
878: . text - short string that describes the option
879: . man - manual page with additional information on option
880: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
881: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
882: $ value = defaultvalue
883: $ PetscOptionsInt(..., value,&value,&flg);
884: $ if (flg) {
886: Output Parameter:
887: + value - the integer value to return
888: - flg - PETSC_TRUE if found, else PETSC_FALSE
890: Notes:
891: If the user does not supply the option at all value is NOT changed. Thus
892: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
894: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
896: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
898: Level: beginner
900: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
901: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
902: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
903: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
904: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
905: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
906: PetscOptionsFList(), PetscOptionsEList()
907: M*/
909: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set,PetscInt lb,PetscInt ub)
910: {
911: PetscErrorCode ierr;
912: PetscOptionItem amsopt;
913: PetscBool wasset;
916: if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
917: if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
918: if (!PetscOptionsObject->count) {
919: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
920: PetscMalloc(sizeof(PetscInt),&amsopt->data);
921: *(PetscInt*)amsopt->data = currentvalue;
923: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
924: if (wasset) {
925: *(PetscInt*)amsopt->data = currentvalue;
926: }
927: }
928: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
929: if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
930: if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
931: if (set) *set = wasset;
932: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
933: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %D : formerly %D>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
934: }
935: return(0);
936: }
938: /*MC
939: PetscOptionsString - Gets the string value for a particular option in the database.
941: Logically Collective on the communicator passed in PetscOptionsBegin()
943: Synopsis:
944: #include "petscsys.h"
945: PetscErrorCode PetscOptionsString(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
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. This is not used to set value
952: - len - length of the result string including null terminator
954: Output Parameter:
955: + value - the value to return
956: - flg - PETSC_TRUE if found, else PETSC_FALSE
958: Level: beginner
960: Notes:
961: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
963: 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).
965: If the user does not supply the option at all value is NOT changed. Thus
966: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
968: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
971: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
972: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
973: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
974: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
975: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
976: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
977: PetscOptionsFList(), PetscOptionsEList()
978: M*/
980: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
981: {
982: PetscErrorCode ierr;
983: PetscOptionItem amsopt;
984: PetscBool lset;
987: if (!PetscOptionsObject->count) {
988: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
989: /* must use system malloc since SAWs may free this */
990: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
991: }
992: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
993: if (set) *set = lset;
994: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
995: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %s : formerly %s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? value : currentvalue,currentvalue,text,ManSection(man));
996: }
997: return(0);
998: }
1000: /*MC
1001: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
1003: Logically Collective on the communicator passed in PetscOptionsBegin()
1005: Synopsis:
1006: #include "petscsys.h"
1007: PetscErrorCode PetscOptionsReal(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1009: Input Parameters:
1010: + opt - option name
1011: . text - short string that describes the option
1012: . man - manual page with additional information on option
1013: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1014: $ PetscOptionsReal(..., obj->value,&obj->value,...) or
1015: $ value = defaultvalue
1016: $ PetscOptionsReal(..., value,&value,&flg);
1017: $ if (flg) {
1019: Output Parameter:
1020: + value - the value to return
1021: - flg - PETSC_TRUE if found, else PETSC_FALSE
1023: Notes:
1024: If the user does not supply the option at all value is NOT changed. Thus
1025: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1027: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1029: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1031: Level: beginner
1033: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1034: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1035: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1036: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1037: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1038: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1039: PetscOptionsFList(), PetscOptionsEList()
1040: M*/
1042: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1043: {
1044: PetscErrorCode ierr;
1045: PetscOptionItem amsopt;
1046: PetscBool lset;
1049: if (!PetscOptionsObject->count) {
1050: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1051: PetscMalloc(sizeof(PetscReal),&amsopt->data);
1053: *(PetscReal*)amsopt->data = currentvalue;
1054: }
1055: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1056: if (set) *set = lset;
1057: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1058: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g : %g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? (double)*value : (double) currentvalue,(double)currentvalue,text,ManSection(man));
1059: }
1060: return(0);
1061: }
1063: /*MC
1064: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
1066: Logically Collective on the communicator passed in PetscOptionsBegin()
1068: Synopsis:
1069: #include "petscsys.h"
1070: PetscErrorCode PetscOptionsScalar(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1072: Input Parameters:
1073: + opt - option name
1074: . text - short string that describes the option
1075: . man - manual page with additional information on option
1076: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1077: $ PetscOptionsScalar(..., obj->value,&obj->value,...) or
1078: $ value = defaultvalue
1079: $ PetscOptionsScalar(..., value,&value,&flg);
1080: $ if (flg) {
1083: Output Parameter:
1084: + value - the value to return
1085: - flg - PETSC_TRUE if found, else PETSC_FALSE
1087: Notes:
1088: If the user does not supply the option at all value is NOT changed. Thus
1089: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1091: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1093: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1095: Level: beginner
1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1098: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1099: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1100: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1101: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1102: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1103: PetscOptionsFList(), PetscOptionsEList()
1104: M*/
1106: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1107: {
1111: #if !defined(PETSC_USE_COMPLEX)
1112: PetscOptionsReal(opt,text,man,currentvalue,value,set);
1113: #else
1114: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1115: #endif
1116: return(0);
1117: }
1119: /*MC
1120: 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
1121: its value is set to false.
1123: Logically Collective on the communicator passed in PetscOptionsBegin()
1125: Synopsis:
1126: #include "petscsys.h"
1127: PetscErrorCode PetscOptionsName(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1129: Input Parameters:
1130: + opt - option name
1131: . text - short string that describes the option
1132: - man - manual page with additional information on option
1134: Output Parameter:
1135: . flg - PETSC_TRUE if found, else PETSC_FALSE
1137: Level: beginner
1139: Notes:
1140: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1142: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1143: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1144: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1145: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1146: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1147: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1148: PetscOptionsFList(), PetscOptionsEList()
1149: M*/
1151: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1152: {
1153: PetscErrorCode ierr;
1154: PetscOptionItem amsopt;
1157: if (!PetscOptionsObject->count) {
1158: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1159: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1161: *(PetscBool*)amsopt->data = PETSC_FALSE;
1162: }
1163: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1164: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1165: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1166: }
1167: return(0);
1168: }
1170: /*MC
1171: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1173: Logically Collective on the communicator passed in PetscOptionsBegin()
1175: Synopsis:
1176: #include "petscsys.h"
1177: PetscErrorCode PetscOptionsFList(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1179: Input Parameters:
1180: + opt - option name
1181: . text - short string that describes the option
1182: . man - manual page with additional information on option
1183: . list - the possible choices
1184: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1185: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1186: $ if (flg) {
1187: - len - the length of the character array value
1189: Output Parameter:
1190: + value - the value to return
1191: - set - PETSC_TRUE if found, else PETSC_FALSE
1193: Level: intermediate
1195: Notes:
1196: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1198: If the user does not supply the option at all value is NOT changed. Thus
1199: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1201: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1203: See PetscOptionsEList() for when the choices are given in a string array
1205: To get a listing of all currently specified options,
1206: see PetscOptionsView() or PetscOptionsGetAll()
1208: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1210: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1211: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1212: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1213: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1214: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1215: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1216: M*/
1218: 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)
1219: {
1220: PetscErrorCode ierr;
1221: PetscOptionItem amsopt;
1222: PetscBool lset;
1225: if (!PetscOptionsObject->count) {
1226: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1227: /* must use system malloc since SAWs may free this */
1228: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1229: amsopt->flist = list;
1230: }
1231: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1232: if (set) *set = lset;
1233: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1234: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1235: }
1236: return(0);
1237: }
1239: /*MC
1240: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1242: Logically Collective on the communicator passed in PetscOptionsBegin()
1244: Synopsis:
1245: #include "petscsys.h"
1246: PetscErrorCode PetscOptionsEList(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1248: Input Parameters:
1249: + opt - option name
1250: . ltext - short string that describes the option
1251: . man - manual page with additional information on option
1252: . list - the possible choices (one of these must be selected, anything else is invalid)
1253: . ntext - number of choices
1254: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1255: $ PetscOptionsElist(..., obj->value,&value,&flg);
1256: $ if (flg) {
1259: Output Parameter:
1260: + value - the index of the value to return
1261: - set - PETSC_TRUE if found, else PETSC_FALSE
1263: Level: intermediate
1265: Notes:
1266: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1268: If the user does not supply the option at all value is NOT changed. Thus
1269: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1271: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1273: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1274: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1275: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1276: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1277: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1278: PetscOptionsFList(), PetscOptionsEnum()
1279: M*/
1281: 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)
1282: {
1283: PetscErrorCode ierr;
1284: PetscInt i;
1285: PetscOptionItem amsopt;
1286: PetscBool lset;
1289: if (!PetscOptionsObject->count) {
1290: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1291: /* must use system malloc since SAWs may free this */
1292: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1293: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1294: amsopt->nlist = ntext;
1295: }
1296: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1297: if (set) *set = lset;
1298: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1299: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %s : formerly %s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,lset && value ? list[*value] : currentvalue,currentvalue,ltext);
1300: for (i=0; i<ntext; i++) {
1301: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1302: }
1303: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1304: }
1305: return(0);
1306: }
1308: /*MC
1309: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1310: which at most a single value can be true.
1312: Logically Collective on the communicator passed in PetscOptionsBegin()
1314: Synopsis:
1315: #include "petscsys.h"
1316: PetscErrorCode PetscOptionsBoolGroupBegin(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1318: Input Parameters:
1319: + opt - option name
1320: . text - short string that describes the option
1321: - man - manual page with additional information on option
1323: Output Parameter:
1324: . flg - whether that option was set or not
1326: Level: intermediate
1328: Notes:
1329: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1331: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1333: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1334: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1335: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1336: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1337: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1338: PetscOptionsFList(), PetscOptionsEList()
1339: M*/
1341: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1342: {
1343: PetscErrorCode ierr;
1344: PetscOptionItem amsopt;
1347: if (!PetscOptionsObject->count) {
1348: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1349: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1351: *(PetscBool*)amsopt->data = PETSC_FALSE;
1352: }
1353: *flg = PETSC_FALSE;
1354: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1355: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1356: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1357: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1358: }
1359: return(0);
1360: }
1362: /*MC
1363: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1364: which at most a single value can be true.
1366: Logically Collective on the communicator passed in PetscOptionsBegin()
1368: Synopsis:
1369: #include "petscsys.h"
1370: PetscErrorCode PetscOptionsBoolGroup(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1372: Input Parameters:
1373: + opt - option name
1374: . text - short string that describes the option
1375: - man - manual page with additional information on option
1377: Output Parameter:
1378: . flg - PETSC_TRUE if found, else PETSC_FALSE
1380: Level: intermediate
1382: Notes:
1383: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1385: Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()
1387: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1388: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1389: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1390: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1391: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1392: PetscOptionsFList(), PetscOptionsEList()
1393: M*/
1395: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1396: {
1397: PetscErrorCode ierr;
1398: PetscOptionItem amsopt;
1401: if (!PetscOptionsObject->count) {
1402: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1403: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1405: *(PetscBool*)amsopt->data = PETSC_FALSE;
1406: }
1407: *flg = PETSC_FALSE;
1408: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1409: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1410: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1411: }
1412: return(0);
1413: }
1415: /*MC
1416: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1417: which at most a single value can be true.
1419: Logically Collective on the communicator passed in PetscOptionsBegin()
1421: Synopsis:
1422: #include "petscsys.h"
1423: PetscErrorCode PetscOptionsBoolGroupEnd(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1425: Input Parameters:
1426: + opt - option name
1427: . text - short string that describes the option
1428: - man - manual page with additional information on option
1430: Output Parameter:
1431: . flg - PETSC_TRUE if found, else PETSC_FALSE
1433: Level: intermediate
1435: Notes:
1436: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1438: Must follow a PetscOptionsBoolGroupBegin()
1440: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1441: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1442: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1443: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1444: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1445: PetscOptionsFList(), PetscOptionsEList()
1446: M*/
1448: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1449: {
1450: PetscErrorCode ierr;
1451: PetscOptionItem amsopt;
1454: if (!PetscOptionsObject->count) {
1455: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1456: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1458: *(PetscBool*)amsopt->data = PETSC_FALSE;
1459: }
1460: *flg = PETSC_FALSE;
1461: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1462: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1463: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1464: }
1465: return(0);
1466: }
1468: /*MC
1469: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1471: Logically Collective on the communicator passed in PetscOptionsBegin()
1473: Synopsis:
1474: #include "petscsys.h"
1475: PetscErrorCode PetscOptionsBool(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1477: Input Parameters:
1478: + opt - option name
1479: . text - short string that describes the option
1480: . man - manual page with additional information on option
1481: - currentvalue - the current value
1483: Output Parameter:
1484: + flg - PETSC_TRUE or PETSC_FALSE
1485: - set - PETSC_TRUE if found, else PETSC_FALSE
1487: Notes:
1488: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1489: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1491: 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
1492: is equivalent to -requested_bool true
1494: If the user does not supply the option at all flg is NOT changed. Thus
1495: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1497: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1499: Level: beginner
1501: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1502: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1503: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1504: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1505: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1506: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1507: PetscOptionsFList(), PetscOptionsEList()
1508: M*/
1510: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1511: {
1512: PetscErrorCode ierr;
1513: PetscBool iset;
1514: PetscOptionItem amsopt;
1517: if (!PetscOptionsObject->count) {
1518: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1519: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1521: *(PetscBool*)amsopt->data = currentvalue;
1522: }
1523: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1524: if (set) *set = iset;
1525: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1526: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1527: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1528: }
1529: return(0);
1530: }
1532: /*MC
1533: PetscOptionsRealArray - Gets an array of double values for a particular
1534: option in the database. The values must be separated with commas with
1535: no intervening spaces.
1537: Logically Collective on the communicator passed in PetscOptionsBegin()
1539: Synopsis:
1540: #include "petscsys.h"
1541: PetscErrorCode PetscOptionsRealArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1543: Input Parameters:
1544: + opt - the option one is seeking
1545: . text - short string describing option
1546: . man - manual page for option
1547: - nmax - maximum number of values
1549: Output Parameter:
1550: + value - location to copy values
1551: . nmax - actual number of values found
1552: - set - PETSC_TRUE if found, else PETSC_FALSE
1554: Level: beginner
1556: Notes:
1557: The user should pass in an array of doubles
1559: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1561: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1562: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1563: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1564: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1565: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1566: PetscOptionsFList(), PetscOptionsEList()
1567: M*/
1569: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1570: {
1571: PetscErrorCode ierr;
1572: PetscInt i;
1573: PetscOptionItem amsopt;
1576: if (!PetscOptionsObject->count) {
1577: PetscReal *vals;
1579: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1580: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1581: vals = (PetscReal*)amsopt->data;
1582: for (i=0; i<*n; i++) vals[i] = value[i];
1583: amsopt->arraylength = *n;
1584: }
1585: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1586: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1587: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1588: for (i=1; i<*n; i++) {
1589: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1590: }
1591: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1592: }
1593: return(0);
1594: }
1596: /*MC
1597: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1598: option in the database. The values must be separated with commas with
1599: no intervening spaces.
1601: Logically Collective on the communicator passed in PetscOptionsBegin()
1603: Synopsis:
1604: #include "petscsys.h"
1605: PetscErrorCode PetscOptionsScalarArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1607: Input Parameters:
1608: + opt - the option one is seeking
1609: . text - short string describing option
1610: . man - manual page for option
1611: - nmax - maximum number of values
1613: Output Parameter:
1614: + value - location to copy values
1615: . nmax - actual number of values found
1616: - set - PETSC_TRUE if found, else PETSC_FALSE
1618: Level: beginner
1620: Notes:
1621: The user should pass in an array of doubles
1623: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1625: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1626: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1627: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1628: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1629: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1630: PetscOptionsFList(), PetscOptionsEList()
1631: M*/
1633: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1634: {
1635: PetscErrorCode ierr;
1636: PetscInt i;
1637: PetscOptionItem amsopt;
1640: if (!PetscOptionsObject->count) {
1641: PetscScalar *vals;
1643: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1644: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1645: vals = (PetscScalar*)amsopt->data;
1646: for (i=0; i<*n; i++) vals[i] = value[i];
1647: amsopt->arraylength = *n;
1648: }
1649: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1650: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1651: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1652: for (i=1; i<*n; i++) {
1653: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1654: }
1655: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1656: }
1657: return(0);
1658: }
1660: /*MC
1661: PetscOptionsIntArray - Gets an array of integers for a particular
1662: option in the database.
1664: Logically Collective on the communicator passed in PetscOptionsBegin()
1666: Synopsis:
1667: #include "petscsys.h"
1668: PetscErrorCode PetscOptionsIntArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1670: Input Parameters:
1671: + opt - the option one is seeking
1672: . text - short string describing option
1673: . man - manual page for option
1674: - n - maximum number of values
1676: Output Parameter:
1677: + value - location to copy values
1678: . n - actual number of values found
1679: - set - PETSC_TRUE if found, else PETSC_FALSE
1681: Level: beginner
1683: Notes:
1684: The array can be passed as
1685: a comma separated list: 0,1,2,3,4,5,6,7
1686: a range (start-end+1): 0-8
1687: a range with given increment (start-end+1:inc): 0-7:2
1688: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1690: There must be no intervening spaces between the values.
1692: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1694: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1695: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1696: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1697: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1698: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1699: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1700: M*/
1702: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1703: {
1705: PetscInt i;
1706: PetscOptionItem amsopt;
1709: if (!PetscOptionsObject->count) {
1710: PetscInt *vals;
1712: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1713: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1714: vals = (PetscInt*)amsopt->data;
1715: for (i=0; i<*n; i++) vals[i] = value[i];
1716: amsopt->arraylength = *n;
1717: }
1718: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1719: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1720: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1721: for (i=1; i<*n; i++) {
1722: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1723: }
1724: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1725: }
1726: return(0);
1727: }
1729: /*MC
1730: PetscOptionsStringArray - Gets an array of string values for a particular
1731: option in the database. The values must be separated with commas with
1732: no intervening spaces.
1734: Logically Collective on the communicator passed in PetscOptionsBegin()
1736: Synopsis:
1737: #include "petscsys.h"
1738: PetscErrorCode PetscOptionsStringArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1740: Input Parameters:
1741: + opt - the option one is seeking
1742: . text - short string describing option
1743: . man - manual page for option
1744: - nmax - maximum number of strings
1746: Output Parameter:
1747: + value - location to copy strings
1748: . nmax - actual number of strings found
1749: - set - PETSC_TRUE if found, else PETSC_FALSE
1751: Level: beginner
1753: Notes:
1754: The user should pass in an array of pointers to char, to hold all the
1755: strings returned by this function.
1757: The user is responsible for deallocating the strings that are
1758: returned. The Fortran interface for this routine is not supported.
1760: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1762: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1763: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1764: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1765: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1766: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1767: PetscOptionsFList(), PetscOptionsEList()
1768: M*/
1770: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1771: {
1772: PetscErrorCode ierr;
1773: PetscOptionItem amsopt;
1776: if (!PetscOptionsObject->count) {
1777: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1778: PetscMalloc1(*nmax,(char**)&amsopt->data);
1780: amsopt->arraylength = *nmax;
1781: }
1782: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1783: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1784: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1785: }
1786: return(0);
1787: }
1789: /*MC
1790: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1791: option in the database. The values must be separated with commas with
1792: no intervening spaces.
1794: Logically Collective on the communicator passed in PetscOptionsBegin()
1796: Synopsis:
1797: #include "petscsys.h"
1798: PetscErrorCode PetscOptionsBoolArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1800: Input Parameters:
1801: + opt - the option one is seeking
1802: . text - short string describing option
1803: . man - manual page for option
1804: - nmax - maximum number of values
1806: Output Parameter:
1807: + value - location to copy values
1808: . nmax - actual number of values found
1809: - set - PETSC_TRUE if found, else PETSC_FALSE
1811: Level: beginner
1813: Notes:
1814: The user should pass in an array of doubles
1816: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1818: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1819: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1820: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1821: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1822: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1823: PetscOptionsFList(), PetscOptionsEList()
1824: M*/
1826: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1827: {
1828: PetscErrorCode ierr;
1829: PetscInt i;
1830: PetscOptionItem amsopt;
1833: if (!PetscOptionsObject->count) {
1834: PetscBool *vals;
1836: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1837: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1838: vals = (PetscBool*)amsopt->data;
1839: for (i=0; i<*n; i++) vals[i] = value[i];
1840: amsopt->arraylength = *n;
1841: }
1842: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1843: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1844: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1845: for (i=1; i<*n; i++) {
1846: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1847: }
1848: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1849: }
1850: return(0);
1851: }
1853: /*MC
1854: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1856: Logically Collective on the communicator passed in PetscOptionsBegin()
1858: Synopsis:
1859: #include "petscsys.h"
1860: PetscErrorCode PetscOptionsViewer(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1862: Input Parameters:
1863: + opt - option name
1864: . text - short string that describes the option
1865: - man - manual page with additional information on option
1867: Output Parameter:
1868: + viewer - the viewer
1869: - set - PETSC_TRUE if found, else PETSC_FALSE
1871: Level: beginner
1873: Notes:
1874: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1876: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1878: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1879: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1880: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1881: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1882: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1883: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1884: PetscOptionsFList(), PetscOptionsEList()
1885: M*/
1887: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1888: {
1889: PetscErrorCode ierr;
1890: PetscOptionItem amsopt;
1893: if (!PetscOptionsObject->count) {
1894: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1895: /* must use system malloc since SAWs may free this */
1896: PetscStrdup("",(char**)&amsopt->data);
1897: }
1898: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1899: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1900: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1901: }
1902: return(0);
1903: }
1905: /*@C
1906: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1907: in KSPSetFromOptions_GMRES().
1909: Logically Collective on the communicator passed in PetscOptionsBegin()
1911: Input Parameter:
1912: . head - the heading text
1915: Level: intermediate
1917: Notes:
1918: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1920: Can be followed by a call to PetscOptionsTail() in the same function.
1922: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1923: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1924: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1925: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1926: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1927: PetscOptionsFList(), PetscOptionsEList()
1928: @*/
1929: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1930: {
1934: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1935: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1936: }
1937: return(0);
1938: }