Actual source code: aoptions.c
1: /*
2: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
3: GUI code to display the options and get values from the users.
5: */
7: #include <petsc/private/petscimpl.h>
8: #include <petscviewer.h>
10: #define ManSection(str) ((str) ? (str) : "None")
12: /*
13: Keep a linked list of options that have been posted and we are waiting for
14: user selection. See the manual page for PetscOptionsBegin()
16: Eventually we'll attach this beast to a MPI_Comm
17: */
19: /*
20: Handles setting up the data structure in a call to PetscOptionsBegin()
21: */
22: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
23: {
27: if (!PetscOptionsObject->alreadyprinted) {
28: if (!PetscOptionsHelpPrintedSingleton) PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
29: PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
30: }
31: PetscOptionsObject->next = NULL;
32: PetscOptionsObject->comm = comm;
33: PetscOptionsObject->changedmethod = PETSC_FALSE;
35: PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
36: PetscStrallocpy(title,&PetscOptionsObject->title);
38: PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
39: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
40: if (!PetscOptionsObject->alreadyprinted) {
41: (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
42: }
43: }
44: return 0;
45: }
47: /*
48: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
49: */
50: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
51: {
52: char title[256];
53: PetscBool flg;
57: PetscOptionsObject->object = obj;
58: PetscOptionsObject->alreadyprinted = obj->optionsprinted;
60: PetscStrcmp(obj->description,obj->class_name,&flg);
61: if (flg) PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
62: else PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
63: PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
64: return 0;
65: }
67: /*
68: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
69: */
70: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
71: {
72: PetscOptionItem next;
73: PetscBool valid;
75: PetscOptionsValidKey(opt,&valid);
78: PetscNew(amsopt);
79: (*amsopt)->next = NULL;
80: (*amsopt)->set = PETSC_FALSE;
81: (*amsopt)->type = t;
82: (*amsopt)->data = NULL;
84: PetscStrallocpy(text,&(*amsopt)->text);
85: PetscStrallocpy(opt,&(*amsopt)->option);
86: PetscStrallocpy(man,&(*amsopt)->man);
88: if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
89: else {
90: next = PetscOptionsObject->next;
91: while (next->next) next = next->next;
92: next->next = *amsopt;
93: }
94: return 0;
95: }
97: /*
98: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
100: Collective
102: Input Parameters:
103: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
104: . n - length of the string, must be the same on all processes
105: - str - location to store input
107: Bugs:
108: . Assumes process 0 of the given communicator has access to stdin
110: */
111: static PetscErrorCode PetscScanString(MPI_Comm comm, size_t n, char str[])
112: {
113: PetscMPIInt rank,nm;
115: MPI_Comm_rank(comm,&rank);
116: if (rank == 0) {
117: char c = (char)getchar();
118: size_t i = 0;
120: while (c != '\n' && i < n-1) {
121: str[i++] = c;
122: c = (char)getchar();
123: }
124: str[i] = 0;
125: }
126: PetscMPIIntCast(n,&nm);
127: MPI_Bcast(str,nm,MPI_CHAR,0,comm);
128: return 0;
129: }
131: /*
132: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
133: */
134: static PetscErrorCode PetscStrdup(const char s[], char *t[])
135: {
136: char *tmp = NULL;
138: if (s) {
139: size_t len;
141: PetscStrlen(s,&len);
142: tmp = (char*) malloc((len+1)*sizeof(*tmp));
144: PetscStrcpy(tmp,s);
145: }
146: *t = tmp;
147: return 0;
148: }
150: /*
151: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
153: Notes:
154: this isn't really practical, it is just to demonstrate the principle
156: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
157: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
159: Bugs:
160: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
161: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
162: - Only works for PetscInt == int, PetscReal == double etc
164: Developer Notes:
165: Normally the GUI that presents the options the user and retrieves the values would be running in a different
166: address space and communicating with the PETSc program
168: */
169: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
170: {
171: PetscOptionItem next = PetscOptionsObject->next;
172: char str[512];
173: PetscBool bid;
174: PetscReal ir,*valr;
175: PetscInt *vald;
176: size_t i;
178: (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
179: while (next) {
180: switch (next->type) {
181: case OPTION_HEAD:
182: break;
183: case OPTION_INT_ARRAY:
184: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
185: vald = (PetscInt*) next->data;
186: for (i=0; i<next->arraylength; i++) {
187: PetscPrintf(PETSC_COMM_WORLD,"%" PetscInt_FMT,vald[i]);
188: if (i < next->arraylength-1) {
189: PetscPrintf(PETSC_COMM_WORLD,",");
190: }
191: }
192: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
193: PetscScanString(PETSC_COMM_WORLD,512,str);
194: if (str[0]) {
195: PetscToken token;
196: PetscInt n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
197: size_t len;
198: char *value;
199: PetscBool foundrange;
201: next->set = PETSC_TRUE;
202: value = str;
203: PetscTokenCreate(value,',',&token);
204: PetscTokenFind(token,&value);
205: while (n < nmax) {
206: if (!value) break;
208: /* look for form d-D where d and D are integers */
209: foundrange = PETSC_FALSE;
210: PetscStrlen(value,&len);
211: if (value[0] == '-') i=2;
212: else i=1;
213: for (;i<len; i++) {
214: if (value[i] == '-') {
216: value[i] = 0;
217: PetscOptionsStringToInt(value,&start);
218: PetscOptionsStringToInt(value+i+1,&end);
221: for (; start<end; start++) {
222: *dvalue = start; dvalue++;n++;
223: }
224: foundrange = PETSC_TRUE;
225: break;
226: }
227: }
228: if (!foundrange) {
229: PetscOptionsStringToInt(value,dvalue);
230: dvalue++;
231: n++;
232: }
233: PetscTokenFind(token,&value);
234: }
235: PetscTokenDestroy(&token);
236: }
237: break;
238: case OPTION_REAL_ARRAY:
239: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
240: valr = (PetscReal*) next->data;
241: for (i=0; i<next->arraylength; i++) {
242: PetscPrintf(PETSC_COMM_WORLD,"%g",(double)valr[i]);
243: if (i < next->arraylength-1) {
244: PetscPrintf(PETSC_COMM_WORLD,",");
245: }
246: }
247: PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
248: PetscScanString(PETSC_COMM_WORLD,512,str);
249: if (str[0]) {
250: PetscToken token;
251: PetscInt n = 0,nmax = next->arraylength;
252: PetscReal *dvalue = (PetscReal*)next->data;
253: char *value;
255: next->set = PETSC_TRUE;
256: value = str;
257: PetscTokenCreate(value,',',&token);
258: PetscTokenFind(token,&value);
259: while (n < nmax) {
260: if (!value) break;
261: PetscOptionsStringToReal(value,dvalue);
262: dvalue++;
263: n++;
264: PetscTokenFind(token,&value);
265: }
266: PetscTokenDestroy(&token);
267: }
268: break;
269: case OPTION_INT:
270: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
271: PetscScanString(PETSC_COMM_WORLD,512,str);
272: if (str[0]) {
273: #if defined(PETSC_SIZEOF_LONG_LONG)
274: long long lid;
275: sscanf(str,"%lld",&lid);
277: #else
278: long lid;
279: sscanf(str,"%ld",&lid);
281: #endif
283: next->set = PETSC_TRUE;
284: *((PetscInt*)next->data) = (PetscInt)lid;
285: }
286: break;
287: case OPTION_REAL:
288: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
289: PetscScanString(PETSC_COMM_WORLD,512,str);
290: if (str[0]) {
291: #if defined(PETSC_USE_REAL_SINGLE)
292: sscanf(str,"%e",&ir);
293: #elif defined(PETSC_USE_REAL___FP16)
294: float irtemp;
295: sscanf(str,"%e",&irtemp);
296: ir = irtemp;
297: #elif defined(PETSC_USE_REAL_DOUBLE)
298: sscanf(str,"%le",&ir);
299: #elif defined(PETSC_USE_REAL___FLOAT128)
300: ir = strtoflt128(str,0);
301: #else
302: SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
303: #endif
304: next->set = PETSC_TRUE;
305: *((PetscReal*)next->data) = ir;
306: }
307: break;
308: case OPTION_BOOL:
309: 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);
310: PetscScanString(PETSC_COMM_WORLD,512,str);
311: if (str[0]) {
312: PetscOptionsStringToBool(str,&bid);
313: next->set = PETSC_TRUE;
314: *((PetscBool*)next->data) = bid;
315: }
316: break;
317: case OPTION_STRING:
318: PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
319: PetscScanString(PETSC_COMM_WORLD,512,str);
320: if (str[0]) {
321: next->set = PETSC_TRUE;
322: /* must use system malloc since SAWs may free this */
323: PetscStrdup(str,(char**)&next->data);
324: }
325: break;
326: case OPTION_FLIST:
327: PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
328: PetscScanString(PETSC_COMM_WORLD,512,str);
329: if (str[0]) {
330: PetscOptionsObject->changedmethod = PETSC_TRUE;
331: next->set = PETSC_TRUE;
332: /* must use system malloc since SAWs may free this */
333: PetscStrdup(str,(char**)&next->data);
334: }
335: break;
336: default:
337: break;
338: }
339: next = next->next;
340: }
341: return 0;
342: }
344: #if defined(PETSC_HAVE_SAWS)
345: #include <petscviewersaws.h>
347: static int count = 0;
349: PetscErrorCode PetscOptionsSAWsDestroy(void)
350: {
351: return 0;
352: }
354: static const char *OptionsHeader = "<head>\n"
355: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
356: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
357: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
358: "<script>\n"
359: "jQuery(document).ready(function() {\n"
360: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
361: "})\n"
362: "</script>\n"
363: "</head>\n";
365: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
366: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
368: /*
369: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
371: Bugs:
372: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
373: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
374: - Only works for PetscInt == int, PetscReal == double etc
376: */
377: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
378: {
379: PetscOptionItem next = PetscOptionsObject->next;
380: static int mancount = 0;
381: char options[16];
382: PetscBool changedmethod = PETSC_FALSE;
383: PetscBool stopasking = PETSC_FALSE;
384: char manname[16],textname[16];
385: char dir[1024];
387: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
388: sprintf(options,"Options_%d",count++);
390: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
392: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
393: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
394: PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
395: PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
396: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
397: PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));
399: while (next) {
400: sprintf(manname,"_man_%d",mancount);
401: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
402: PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
403: sprintf(textname,"_text_%d",mancount++);
404: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
405: PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));
407: switch (next->type) {
408: case OPTION_HEAD:
409: break;
410: case OPTION_INT_ARRAY:
411: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
412: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
413: break;
414: case OPTION_REAL_ARRAY:
415: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
416: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
417: break;
418: case OPTION_INT:
419: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
420: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
421: break;
422: case OPTION_REAL:
423: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
424: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
425: break;
426: case OPTION_BOOL:
427: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
428: PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
429: break;
430: case OPTION_BOOL_ARRAY:
431: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
432: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
433: break;
434: case OPTION_STRING:
435: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
436: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
437: break;
438: case OPTION_STRING_ARRAY:
439: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
440: PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
441: break;
442: case OPTION_FLIST:
443: {
444: PetscInt ntext;
445: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
446: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
447: PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
448: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
449: }
450: break;
451: case OPTION_ELIST:
452: {
453: PetscInt ntext = next->nlist;
454: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
455: PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
456: PetscMalloc1((ntext+1),(char***)&next->edata);
457: PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
458: PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
459: }
460: break;
461: default:
462: break;
463: }
464: next = next->next;
465: }
467: /* wait until accessor has unlocked the memory */
468: PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
469: PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
470: PetscSAWsBlock();
471: PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
472: PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));
474: /* determine if any values have been set in GUI */
475: next = PetscOptionsObject->next;
476: while (next) {
477: PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
478: PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
479: next = next->next;
480: }
482: /* reset counter to -2; this updates the screen with the new options for the selected method */
483: if (changedmethod) PetscOptionsObject->count = -2;
485: if (stopasking) {
486: PetscOptionsPublish = PETSC_FALSE;
487: PetscOptionsObject->count = 0;//do not ask for same thing again
488: }
490: PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
491: return 0;
492: }
493: #endif
495: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
496: {
497: PetscOptionItem last;
498: char option[256],value[1024],tmp[32];
499: size_t j;
501: if (PetscOptionsObject->next) {
502: if (!PetscOptionsObject->count) {
503: #if defined(PETSC_HAVE_SAWS)
504: PetscOptionsSAWsInput(PetscOptionsObject);
505: #else
506: PetscOptionsGetFromTextInput(PetscOptionsObject);
507: #endif
508: }
509: }
511: PetscFree(PetscOptionsObject->title);
513: /* reset counter to -2; this updates the screen with the new options for the selected method */
514: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
515: /* reset alreadyprinted flag */
516: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
517: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
518: PetscOptionsObject->object = NULL;
520: while (PetscOptionsObject->next) {
521: if (PetscOptionsObject->next->set) {
522: if (PetscOptionsObject->prefix) {
523: PetscStrcpy(option,"-");
524: PetscStrcat(option,PetscOptionsObject->prefix);
525: PetscStrcat(option,PetscOptionsObject->next->option+1);
526: } else PetscStrcpy(option,PetscOptionsObject->next->option);
528: switch (PetscOptionsObject->next->type) {
529: case OPTION_HEAD:
530: break;
531: case OPTION_INT_ARRAY:
532: sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
533: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
534: sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
535: PetscStrcat(value,",");
536: PetscStrcat(value,tmp);
537: }
538: break;
539: case OPTION_INT:
540: sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
541: break;
542: case OPTION_REAL:
543: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
544: break;
545: case OPTION_REAL_ARRAY:
546: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
547: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
548: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
549: PetscStrcat(value,",");
550: PetscStrcat(value,tmp);
551: }
552: break;
553: case OPTION_SCALAR_ARRAY:
554: sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
555: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
556: sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
557: PetscStrcat(value,",");
558: PetscStrcat(value,tmp);
559: }
560: break;
561: case OPTION_BOOL:
562: sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
563: break;
564: case OPTION_BOOL_ARRAY:
565: sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
566: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
567: sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
568: PetscStrcat(value,",");
569: PetscStrcat(value,tmp);
570: }
571: break;
572: case OPTION_FLIST:
573: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
574: break;
575: case OPTION_ELIST:
576: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
577: break;
578: case OPTION_STRING:
579: PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
580: break;
581: case OPTION_STRING_ARRAY:
582: sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
583: for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
584: sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
585: PetscStrcat(value,",");
586: PetscStrcat(value,tmp);
587: }
588: break;
589: }
590: PetscOptionsSetValue(PetscOptionsObject->options,option,value);
591: }
592: if (PetscOptionsObject->next->type == OPTION_ELIST) {
593: PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
594: }
595: PetscFree(PetscOptionsObject->next->text);
596: PetscFree(PetscOptionsObject->next->option);
597: PetscFree(PetscOptionsObject->next->man);
598: PetscFree(PetscOptionsObject->next->edata);
600: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
601: free(PetscOptionsObject->next->data);
602: } else {
603: PetscFree(PetscOptionsObject->next->data);
604: }
606: last = PetscOptionsObject->next;
607: PetscOptionsObject->next = PetscOptionsObject->next->next;
608: PetscFree(last);
609: }
610: PetscFree(PetscOptionsObject->prefix);
611: PetscOptionsObject->next = NULL;
612: return 0;
613: }
615: /*MC
616: PetscOptionsEnum - Gets the enum value for a particular option in the database.
618: Logically Collective on the communicator passed in PetscOptionsBegin()
620: Synopsis:
621: #include "petscsys.h"
622: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
624: Input Parameters:
625: + opt - option name
626: . text - short string that describes the option
627: . man - manual page with additional information on option
628: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
629: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
630: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
631: $ value = defaultvalue
632: $ PetscOptionsEnum(..., value,&value,&flg);
633: $ if (flg) {
635: Output Parameters:
636: + value - the value to return
637: - set - PETSC_TRUE if found, else PETSC_FALSE
639: Level: beginner
641: Notes:
642: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
644: list is usually something like PCASMTypes or some other predefined list of enum names
646: If the user does not supply the option at all value is NOT changed. Thus
647: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
649: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
651: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
652: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
653: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
654: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
655: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
656: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
657: PetscOptionsFList(), PetscOptionsEList()
658: M*/
660: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
661: {
662: PetscInt ntext = 0;
663: PetscInt tval;
664: PetscBool tflg;
666: while (list[ntext++]) {
668: }
670: ntext -= 3;
671: PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
672: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
673: if (tflg) *value = (PetscEnum)tval;
674: if (set) *set = tflg;
675: return 0;
676: }
678: /*MC
679: PetscOptionsEnumArray - Gets an array of enum values for a particular
680: option in the database.
682: Logically Collective on the communicator passed in PetscOptionsBegin()
684: Synopsis:
685: #include "petscsys.h"
686: PetscErrorCode PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
688: Input Parameters:
689: + opt - the option one is seeking
690: . text - short string describing option
691: . man - manual page for option
692: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
693: - n - maximum number of values allowed in the value array
695: Output Parameters:
696: + value - location to copy values
697: . n - actual number of values found
698: - set - PETSC_TRUE if found, else PETSC_FALSE
700: Level: beginner
702: Notes:
703: The array must be passed as a comma separated list.
705: There must be no intervening spaces between the values.
707: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
709: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
710: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
711: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
712: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
713: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
714: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
715: M*/
717: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
718: {
719: PetscInt i,nlist = 0;
720: PetscOptionItem amsopt;
724: nlist -= 3; /* drop enum name, prefix, and null termination */
725: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
726: PetscEnum *vals;
727: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
728: PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
729: amsopt->nlist = nlist;
730: PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
731: amsopt->arraylength = *n;
732: vals = (PetscEnum*)amsopt->data;
733: for (i=0; i<*n; i++) vals[i] = value[i];
734: }
735: PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
736: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
737: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
738: for (i=1; i<*n; i++) (*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);
739: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
740: for (i=0; i<nlist; i++) (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
741: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
742: }
743: return 0;
744: }
746: /*MC
747: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
749: Logically Collective on the communicator passed in PetscOptionsBegin()
751: Synopsis:
752: #include "petscsys.h"
753: PetscErrorCode PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)
755: Input Parameters:
756: + opt - option name
757: . text - short string that describes the option
758: . man - manual page with additional information on option
759: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
760: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
761: $ value = defaultvalue
762: $ PetscOptionsInt(..., value,&value,&flg);
763: $ if (flg) {
764: - bound - the requested value should be greater than or equal this bound or an error is generated
766: Output Parameters:
767: + value - the integer value to return
768: - flg - PETSC_TRUE if found, else PETSC_FALSE
770: Notes:
771: If the user does not supply the option at all value is NOT changed. Thus
772: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
774: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
776: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
778: Level: beginner
780: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
781: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
782: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
783: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
784: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
785: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
786: PetscOptionsFList(), PetscOptionsEList()
787: M*/
789: /*MC
790: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
792: Logically Collective on the communicator passed in PetscOptionsBegin()
794: Synopsis:
795: #include "petscsys.h"
796: PetscErrorCode PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)
798: Input Parameters:
799: + opt - option name
800: . text - short string that describes the option
801: . man - manual page with additional information on option
802: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
803: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
804: $ value = defaultvalue
805: $ PetscOptionsInt(..., value,&value,&flg);
806: $ if (flg) {
807: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
808: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
810: Output Parameters:
811: + value - the integer value to return
812: - flg - PETSC_TRUE if found, else PETSC_FALSE
814: Notes:
815: If the user does not supply the option at all value is NOT changed. Thus
816: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
818: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
820: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
822: Level: beginner
824: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
825: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsBoundedInt()
826: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
827: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
828: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
829: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
830: PetscOptionsFList(), PetscOptionsEList()
831: M*/
833: /*MC
834: PetscOptionsInt - Gets the integer value for a particular option in the database.
836: Logically Collective on the communicator passed in PetscOptionsBegin()
838: Synopsis:
839: #include "petscsys.h"
840: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))
842: Input Parameters:
843: + opt - option name
844: . text - short string that describes the option
845: . man - manual page with additional information on option
846: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
847: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
848: $ value = defaultvalue
849: $ PetscOptionsInt(..., value,&value,&flg);
850: $ if (flg) {
852: Output Parameters:
853: + value - the integer value to return
854: - flg - PETSC_TRUE if found, else PETSC_FALSE
856: Notes:
857: If the user does not supply the option at all value is NOT changed. Thus
858: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
860: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
862: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
864: Level: beginner
866: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
867: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
868: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
869: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
870: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
871: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
872: PetscOptionsFList(), PetscOptionsEList()
873: M*/
875: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *set,PetscInt lb,PetscInt ub)
876: {
877: PetscOptionItem amsopt;
878: PetscBool wasset;
882: if (!PetscOptionsObject->count) {
883: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
884: PetscMalloc(sizeof(PetscInt),&amsopt->data);
885: *(PetscInt*)amsopt->data = currentvalue;
887: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,¤tvalue,&wasset);
888: if (wasset) {
889: *(PetscInt*)amsopt->data = currentvalue;
890: }
891: }
892: PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
895: if (set) *set = wasset;
896: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
897: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <now %" PetscInt_FMT " : formerly %" PetscInt_FMT ">: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
898: }
899: return 0;
900: }
902: /*MC
903: PetscOptionsString - Gets the string value for a particular option in the database.
905: Logically Collective on the communicator passed in PetscOptionsBegin()
907: Synopsis:
908: #include "petscsys.h"
909: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
911: Input Parameters:
912: + opt - option name
913: . text - short string that describes the option
914: . man - manual page with additional information on option
915: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
916: - len - length of the result string including null terminator
918: Output Parameters:
919: + value - the value to return
920: - flg - PETSC_TRUE if found, else PETSC_FALSE
922: Level: beginner
924: Notes:
925: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
927: 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).
929: If the user does not supply the option at all value is NOT changed. Thus
930: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
932: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
934: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
935: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
936: PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
937: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
938: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
939: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
940: PetscOptionsFList(), PetscOptionsEList()
941: M*/
943: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
944: {
945: PetscOptionItem amsopt;
946: PetscBool lset;
948: if (!PetscOptionsObject->count) {
949: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
950: /* must use system malloc since SAWs may free this */
951: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
952: }
953: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
954: if (set) *set = lset;
955: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
956: (*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));
957: }
958: return 0;
959: }
961: /*MC
962: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
964: Logically Collective on the communicator passed in PetscOptionsBegin()
966: Synopsis:
967: #include "petscsys.h"
968: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
970: Input Parameters:
971: + opt - option name
972: . text - short string that describes the option
973: . man - manual page with additional information on option
974: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
975: $ PetscOptionsReal(..., obj->value,&obj->value,...) or
976: $ value = defaultvalue
977: $ PetscOptionsReal(..., value,&value,&flg);
978: $ if (flg) {
980: Output Parameters:
981: + value - the value to return
982: - flg - PETSC_TRUE if found, else PETSC_FALSE
984: Notes:
985: If the user does not supply the option at all value is NOT changed. Thus
986: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
988: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
990: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
992: Level: beginner
994: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
995: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
996: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
997: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
998: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
999: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1000: PetscOptionsFList(), PetscOptionsEList()
1001: M*/
1003: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
1004: {
1005: PetscOptionItem amsopt;
1006: PetscBool lset;
1008: if (!PetscOptionsObject->count) {
1009: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1010: PetscMalloc(sizeof(PetscReal),&amsopt->data);
1012: *(PetscReal*)amsopt->data = currentvalue;
1013: }
1014: PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1015: if (set) *set = lset;
1016: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1017: (*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));
1018: }
1019: return 0;
1020: }
1022: /*MC
1023: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
1025: Logically Collective on the communicator passed in PetscOptionsBegin()
1027: Synopsis:
1028: #include "petscsys.h"
1029: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1031: Input Parameters:
1032: + opt - option name
1033: . text - short string that describes the option
1034: . man - manual page with additional information on option
1035: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1036: $ PetscOptionsScalar(..., obj->value,&obj->value,...) or
1037: $ value = defaultvalue
1038: $ PetscOptionsScalar(..., value,&value,&flg);
1039: $ if (flg) {
1041: Output Parameters:
1042: + value - the value to return
1043: - flg - PETSC_TRUE if found, else PETSC_FALSE
1045: Notes:
1046: If the user does not supply the option at all value is NOT changed. Thus
1047: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1049: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1051: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1053: Level: beginner
1055: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1056: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1057: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1058: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1059: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1060: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1061: PetscOptionsFList(), PetscOptionsEList()
1062: M*/
1064: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1065: {
1066: #if !defined(PETSC_USE_COMPLEX)
1067: PetscOptionsReal(opt,text,man,currentvalue,value,set);
1068: #else
1069: PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1070: #endif
1071: return 0;
1072: }
1074: /*MC
1075: 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
1076: its value is set to false.
1078: Logically Collective on the communicator passed in PetscOptionsBegin()
1080: Synopsis:
1081: #include "petscsys.h"
1082: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
1084: Input Parameters:
1085: + opt - option name
1086: . text - short string that describes the option
1087: - man - manual page with additional information on option
1089: Output Parameter:
1090: . flg - PETSC_TRUE if found, else PETSC_FALSE
1092: Level: beginner
1094: Notes:
1095: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1098: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
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 PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1107: {
1108: PetscOptionItem amsopt;
1110: if (!PetscOptionsObject->count) {
1111: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1112: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1114: *(PetscBool*)amsopt->data = PETSC_FALSE;
1115: }
1116: PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1117: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1118: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1119: }
1120: return 0;
1121: }
1123: /*MC
1124: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1126: Logically Collective on the communicator passed in PetscOptionsBegin()
1128: Synopsis:
1129: #include "petscsys.h"
1130: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1132: Input Parameters:
1133: + opt - option name
1134: . text - short string that describes the option
1135: . man - manual page with additional information on option
1136: . list - the possible choices
1137: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1138: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1139: $ if (flg) {
1140: - len - the length of the character array value
1142: Output Parameters:
1143: + value - the value to return
1144: - set - PETSC_TRUE if found, else PETSC_FALSE
1146: Level: intermediate
1148: Notes:
1149: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1151: If the user does not supply the option at all value is NOT changed. Thus
1152: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1154: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1156: See PetscOptionsEList() for when the choices are given in a string array
1158: To get a listing of all currently specified options,
1159: see PetscOptionsView() or PetscOptionsGetAll()
1161: Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list
1163: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1164: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1165: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1166: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1167: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1168: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1169: M*/
1171: 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)
1172: {
1173: PetscOptionItem amsopt;
1174: PetscBool lset;
1176: if (!PetscOptionsObject->count) {
1177: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1178: /* must use system malloc since SAWs may free this */
1179: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1180: amsopt->flist = list;
1181: }
1182: PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1183: if (set) *set = lset;
1184: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1185: PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1186: }
1187: return 0;
1188: }
1190: /*MC
1191: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1193: Logically Collective on the communicator passed in PetscOptionsBegin()
1195: Synopsis:
1196: #include "petscsys.h"
1197: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1199: Input Parameters:
1200: + opt - option name
1201: . ltext - short string that describes the option
1202: . man - manual page with additional information on option
1203: . list - the possible choices (one of these must be selected, anything else is invalid)
1204: . ntext - number of choices
1205: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1206: $ PetscOptionsElist(..., obj->value,&value,&flg);
1207: $ if (flg) {
1209: Output Parameters:
1210: + value - the index of the value to return
1211: - set - PETSC_TRUE if found, else PETSC_FALSE
1213: Level: intermediate
1215: Notes:
1216: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1218: If the user does not supply the option at all value is NOT changed. Thus
1219: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1221: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1223: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1224: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1225: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1226: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1227: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1228: PetscOptionsFList(), PetscOptionsEnum()
1229: M*/
1231: 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)
1232: {
1233: PetscInt i;
1234: PetscOptionItem amsopt;
1235: PetscBool lset;
1237: if (!PetscOptionsObject->count) {
1238: PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1239: /* must use system malloc since SAWs may free this */
1240: PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1241: PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1242: amsopt->nlist = ntext;
1243: }
1244: PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1245: if (set) *set = lset;
1246: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1247: (*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);
1248: for (i=0; i<ntext; i++) {
1249: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1250: }
1251: (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1252: }
1253: return 0;
1254: }
1256: /*MC
1257: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1258: which at most a single value can be true.
1260: Logically Collective on the communicator passed in PetscOptionsBegin()
1262: Synopsis:
1263: #include "petscsys.h"
1264: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1266: Input Parameters:
1267: + opt - option name
1268: . text - short string that describes the option
1269: - man - manual page with additional information on option
1271: Output Parameter:
1272: . flg - whether that option was set or not
1274: Level: intermediate
1276: Notes:
1277: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1279: Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()
1281: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1282: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1283: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1284: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1285: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1286: PetscOptionsFList(), PetscOptionsEList()
1287: M*/
1289: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1290: {
1291: PetscOptionItem amsopt;
1293: if (!PetscOptionsObject->count) {
1294: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1295: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1297: *(PetscBool*)amsopt->data = PETSC_FALSE;
1298: }
1299: *flg = PETSC_FALSE;
1300: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1301: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1302: (*PetscHelpPrintf)(PetscOptionsObject->comm," Pick at most one of -------------\n");
1303: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1304: }
1305: return 0;
1306: }
1308: /*MC
1309: PetscOptionsBoolGroup - One 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 PetscOptionsBoolGroup(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 - PETSC_TRUE if found, else PETSC_FALSE
1326: Level: intermediate
1328: Notes:
1329: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1331: Must follow a PetscOptionsBoolGroupBegin() and preceded a 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 PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1342: {
1343: PetscOptionItem amsopt;
1345: if (!PetscOptionsObject->count) {
1346: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1347: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1349: *(PetscBool*)amsopt->data = PETSC_FALSE;
1350: }
1351: *flg = PETSC_FALSE;
1352: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1353: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1354: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1355: }
1356: return 0;
1357: }
1359: /*MC
1360: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1361: which at most a single value can be true.
1363: Logically Collective on the communicator passed in PetscOptionsBegin()
1365: Synopsis:
1366: #include "petscsys.h"
1367: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1369: Input Parameters:
1370: + opt - option name
1371: . text - short string that describes the option
1372: - man - manual page with additional information on option
1374: Output Parameter:
1375: . flg - PETSC_TRUE if found, else PETSC_FALSE
1377: Level: intermediate
1379: Notes:
1380: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1382: Must follow a PetscOptionsBoolGroupBegin()
1384: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1385: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1386: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1387: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1388: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1389: PetscOptionsFList(), PetscOptionsEList()
1390: M*/
1392: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool *flg)
1393: {
1394: PetscOptionItem amsopt;
1396: if (!PetscOptionsObject->count) {
1397: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1398: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1400: *(PetscBool*)amsopt->data = PETSC_FALSE;
1401: }
1402: *flg = PETSC_FALSE;
1403: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1404: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1405: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1406: }
1407: return 0;
1408: }
1410: /*MC
1411: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1413: Logically Collective on the communicator passed in PetscOptionsBegin()
1415: Synopsis:
1416: #include "petscsys.h"
1417: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1419: Input Parameters:
1420: + opt - option name
1421: . text - short string that describes the option
1422: . man - manual page with additional information on option
1423: - currentvalue - the current value
1425: Output Parameters:
1426: + flg - PETSC_TRUE or PETSC_FALSE
1427: - set - PETSC_TRUE if found, else PETSC_FALSE
1429: Notes:
1430: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1431: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1433: 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
1434: is equivalent to -requested_bool true
1436: If the user does not supply the option at all flg is NOT changed. Thus
1437: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1439: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1441: Level: beginner
1443: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1444: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1445: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
1446: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1447: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1448: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1449: PetscOptionsFList(), PetscOptionsEList()
1450: M*/
1452: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1453: {
1454: PetscBool iset;
1455: PetscOptionItem amsopt;
1457: if (!PetscOptionsObject->count) {
1458: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1459: PetscMalloc(sizeof(PetscBool),&amsopt->data);
1461: *(PetscBool*)amsopt->data = currentvalue;
1462: }
1463: PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1464: if (set) *set = iset;
1465: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1466: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1467: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1468: }
1469: return 0;
1470: }
1472: /*MC
1473: PetscOptionsRealArray - Gets an array of double values for a particular
1474: option in the database. The values must be separated with commas with
1475: no intervening spaces.
1477: Logically Collective on the communicator passed in PetscOptionsBegin()
1479: Synopsis:
1480: #include "petscsys.h"
1481: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1483: Input Parameters:
1484: + opt - the option one is seeking
1485: . text - short string describing option
1486: . man - manual page for option
1487: - n - maximum number of values that value has room for
1489: Output Parameters:
1490: + value - location to copy values
1491: . n - actual number of values found
1492: - set - PETSC_TRUE if found, else PETSC_FALSE
1494: Level: beginner
1496: Notes:
1497: The user should pass in an array of doubles
1499: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1501: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1502: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1503: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1504: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1505: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1506: PetscOptionsFList(), PetscOptionsEList()
1507: M*/
1509: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1510: {
1511: PetscInt i;
1512: PetscOptionItem amsopt;
1514: if (!PetscOptionsObject->count) {
1515: PetscReal *vals;
1517: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1518: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1519: vals = (PetscReal*)amsopt->data;
1520: for (i=0; i<*n; i++) vals[i] = value[i];
1521: amsopt->arraylength = *n;
1522: }
1523: PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1524: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1525: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1526: for (i=1; i<*n; i++) {
1527: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1528: }
1529: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1530: }
1531: return 0;
1532: }
1534: /*MC
1535: PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1536: option in the database. The values must be separated with commas with
1537: no intervening spaces.
1539: Logically Collective on the communicator passed in PetscOptionsBegin()
1541: Synopsis:
1542: #include "petscsys.h"
1543: PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1545: Input Parameters:
1546: + opt - the option one is seeking
1547: . text - short string describing option
1548: . man - manual page for option
1549: - n - maximum number of values allowed in the value array
1551: Output Parameters:
1552: + value - location to copy values
1553: . n - actual number of values found
1554: - set - PETSC_TRUE if found, else PETSC_FALSE
1556: Level: beginner
1558: Notes:
1559: The user should pass in an array of doubles
1561: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1563: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1564: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1565: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1566: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1567: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1568: PetscOptionsFList(), PetscOptionsEList()
1569: M*/
1571: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1572: {
1573: PetscInt i;
1574: PetscOptionItem amsopt;
1576: if (!PetscOptionsObject->count) {
1577: PetscScalar *vals;
1579: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1580: PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1581: vals = (PetscScalar*)amsopt->data;
1582: for (i=0; i<*n; i++) vals[i] = value[i];
1583: amsopt->arraylength = *n;
1584: }
1585: PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1586: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1587: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1588: for (i=1; i<*n; i++) {
1589: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1590: }
1591: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1592: }
1593: return 0;
1594: }
1596: /*MC
1597: PetscOptionsIntArray - Gets an array of integers for a particular
1598: option in the database.
1600: Logically Collective on the communicator passed in PetscOptionsBegin()
1602: Synopsis:
1603: #include "petscsys.h"
1604: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1606: Input Parameters:
1607: + opt - the option one is seeking
1608: . text - short string describing option
1609: . man - manual page for option
1610: - n - maximum number of values
1612: Output Parameters:
1613: + value - location to copy values
1614: . n - actual number of values found
1615: - set - PETSC_TRUE if found, else PETSC_FALSE
1617: Level: beginner
1619: Notes:
1620: The array can be passed as
1621: a comma separated list: 0,1,2,3,4,5,6,7
1622: a range (start-end+1): 0-8
1623: a range with given increment (start-end+1:inc): 0-7:2
1624: a combination of values and ranges separated by commas: 0,1-8,8-15:2
1626: There must be no intervening spaces between the values.
1628: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1630: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1631: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1632: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1633: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1634: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1635: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1636: M*/
1638: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1639: {
1640: PetscInt i;
1641: PetscOptionItem amsopt;
1643: if (!PetscOptionsObject->count) {
1644: PetscInt *vals;
1646: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1647: PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1648: vals = (PetscInt*)amsopt->data;
1649: for (i=0; i<*n; i++) vals[i] = value[i];
1650: amsopt->arraylength = *n;
1651: }
1652: PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1653: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1654: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%" PetscInt_FMT,PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1655: for (i=1; i<*n; i++) {
1656: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%" PetscInt_FMT,value[i]);
1657: }
1658: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1659: }
1660: return 0;
1661: }
1663: /*MC
1664: PetscOptionsStringArray - Gets an array of string values for a particular
1665: option in the database. The values must be separated with commas with
1666: no intervening spaces.
1668: Logically Collective on the communicator passed in PetscOptionsBegin()
1670: Synopsis:
1671: #include "petscsys.h"
1672: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1674: Input Parameters:
1675: + opt - the option one is seeking
1676: . text - short string describing option
1677: . man - manual page for option
1678: - nmax - maximum number of strings
1680: Output Parameters:
1681: + value - location to copy strings
1682: . nmax - actual number of strings found
1683: - set - PETSC_TRUE if found, else PETSC_FALSE
1685: Level: beginner
1687: Notes:
1688: The user should pass in an array of pointers to char, to hold all the
1689: strings returned by this function.
1691: The user is responsible for deallocating the strings that are
1692: returned. The Fortran interface for this routine is not supported.
1694: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1696: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1697: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1698: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1699: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1700: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1701: PetscOptionsFList(), PetscOptionsEList()
1702: M*/
1704: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1705: {
1706: PetscOptionItem amsopt;
1708: if (!PetscOptionsObject->count) {
1709: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1710: PetscMalloc1(*nmax,(char**)&amsopt->data);
1712: amsopt->arraylength = *nmax;
1713: }
1714: PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1715: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1716: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1717: }
1718: return 0;
1719: }
1721: /*MC
1722: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1723: option in the database. The values must be separated with commas with
1724: no intervening spaces.
1726: Logically Collective on the communicator passed in PetscOptionsBegin()
1728: Synopsis:
1729: #include "petscsys.h"
1730: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1732: Input Parameters:
1733: + opt - the option one is seeking
1734: . text - short string describing option
1735: . man - manual page for option
1736: - n - maximum number of values allowed in the value array
1738: Output Parameters:
1739: + value - location to copy values
1740: . n - actual number of values found
1741: - set - PETSC_TRUE if found, else PETSC_FALSE
1743: Level: beginner
1745: Notes:
1746: The user should pass in an array of doubles
1748: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1750: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1751: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1752: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1753: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1754: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1755: PetscOptionsFList(), PetscOptionsEList()
1756: M*/
1758: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1759: {
1760: PetscInt i;
1761: PetscOptionItem amsopt;
1763: if (!PetscOptionsObject->count) {
1764: PetscBool *vals;
1766: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1767: PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1768: vals = (PetscBool*)amsopt->data;
1769: for (i=0; i<*n; i++) vals[i] = value[i];
1770: amsopt->arraylength = *n;
1771: }
1772: PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1773: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1774: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1775: for (i=1; i<*n; i++) {
1776: (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1777: }
1778: (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1779: }
1780: return 0;
1781: }
1783: /*MC
1784: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1786: Logically Collective on the communicator passed in PetscOptionsBegin()
1788: Synopsis:
1789: #include "petscsys.h"
1790: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1792: Input Parameters:
1793: + opt - option name
1794: . text - short string that describes the option
1795: - man - manual page with additional information on option
1797: Output Parameters:
1798: + viewer - the viewer
1799: . format - the PetscViewerFormat requested by the user, pass NULL if not needed
1800: - set - PETSC_TRUE if found, else PETSC_FALSE
1802: Level: beginner
1804: Notes:
1805: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1807: See PetscOptionsGetViewer() for the format of the supplied viewer and its options
1809: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1810: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1811: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1812: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1813: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1814: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1815: PetscOptionsFList(), PetscOptionsEList()
1816: M*/
1818: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1819: {
1820: PetscOptionItem amsopt;
1822: if (!PetscOptionsObject->count) {
1823: PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1824: /* must use system malloc since SAWs may free this */
1825: PetscStrdup("",(char**)&amsopt->data);
1826: }
1827: PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1828: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1829: (*PetscHelpPrintf)(PetscOptionsObject->comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1830: }
1831: return 0;
1832: }
1834: /*@C
1835: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1836: in KSPSetFromOptions_GMRES().
1838: Logically Collective on the communicator passed in PetscOptionsBegin()
1840: Input Parameter:
1841: . head - the heading text
1843: Level: intermediate
1845: Notes:
1846: Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument
1848: Can be followed by a call to PetscOptionsTail() in the same function.
1850: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1851: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1852: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1853: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1854: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1855: PetscOptionsFList(), PetscOptionsEList()
1856: @*/
1857: PetscErrorCode PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1858: {
1859: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1860: (*PetscHelpPrintf)(PetscOptionsObject->comm," %s\n",head);
1861: }
1862: return 0;
1863: }