Actual source code: aoptions.c
1: #define PETSC_DLL
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
16: /*
17: Keep a linked list of options that have been posted and we are waiting for
18: user selection
20: Eventually we'll attach this beast to a MPI_Comm
21: */
22: PetscOptionsObjectType PetscOptionsObject;
23: PetscInt PetscOptionsPublishCount = 0;
28: PetscErrorCode PetscOptionsHelpAddList(const char prefix[],const char title[],const char mansec[])
29: {
30: int ierr;
31: OptionsHelp newhelp;
33: PetscNew(struct _p_OptionsHelp,&newhelp);
34: PetscStrallocpy(prefix,&newhelp->prefix);
35: PetscStrallocpy(title,&newhelp->title);
36: PetscStrallocpy(mansec,&newhelp->mansec);
37: newhelp->next = 0;
39: if (!PetscOptionsObject.help) {
40: PetscOptionsObject.help = newhelp;
41: } else {
42: newhelp->next = PetscOptionsObject.help;
43: PetscOptionsObject.help = newhelp;
44: }
45: return(0);
46: }
50: PetscErrorCode PetscOptionsHelpDestroyList(void)
51: {
53: OptionsHelp help = PetscOptionsObject.help, next;
56: while (help) {
57: next = help->next;
58: PetscStrfree(help->prefix);
59: PetscStrfree(help->title);
60: PetscStrfree(help->mansec);
61: PetscFree(help);
62: help = next;
63: }
64: return(0);
65: }
66:
70: PetscErrorCode PetscOptionsHelpFindList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
71: {
73: PetscTruth flg1,flg2,flg3;
74: OptionsHelp help = PetscOptionsObject.help;
76: while (help) {
77: PetscStrcmp(help->prefix,prefix,&flg1);
78: PetscStrcmp(help->title,title,&flg2);
79: PetscStrcmp(help->mansec,mansec,&flg3);
80: if (flg1 && flg2 && flg3) {
81: *flg = PETSC_TRUE;
82: break;
83: }
84: help = help->next;
85: }
86: return(0);
88: }
92: PetscErrorCode PetscOptionsHelpCheckAddList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
93: {
95: PetscOptionsHelpFindList(prefix,title,mansec,flg);
96: if (!(*flg)) PetscOptionsHelpAddList(prefix,title,mansec);
97: return(0);
98: }
102: /*
103: Handles setting up the data structure in a call to PetscOptionsBegin()
104: */
105: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
106: {
110: PetscOptionsObject.next = 0;
111: PetscOptionsObject.comm = comm;
112: PetscOptionsObject.changedmethod = PETSC_FALSE;
113: if (PetscOptionsObject.prefix) {
114: PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
115: }
116: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
117: if (PetscOptionsObject.title) {
118: PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title = 0;
119: }
120: PetscStrallocpy(title,&PetscOptionsObject.title);
122: PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
123: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
124: PetscOptionsHelpCheckAddList(prefix,title,mansec,&PetscOptionsObject.alreadyprinted);
125: if (!PetscOptionsObject.alreadyprinted) {
126: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
127: }
128: }
129: return(0);
130: }
132: /*
133: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
134: */
137: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
138: {
139: int ierr;
140: PetscOptions next;
143: PetscNew(struct _p_Options,amsopt);
144: (*amsopt)->next = 0;
145: (*amsopt)->set = PETSC_FALSE;
146: (*amsopt)->type = t;
147: (*amsopt)->data = 0;
148: (*amsopt)->edata = 0;
150: PetscStrallocpy(text,&(*amsopt)->text);
151: PetscStrallocpy(opt,&(*amsopt)->option);
152: PetscStrallocpy(man,&(*amsopt)->man);
154: if (!PetscOptionsObject.next) {
155: PetscOptionsObject.next = *amsopt;
156: } else {
157: next = PetscOptionsObject.next;
158: while (next->next) next = next->next;
159: next->next = *amsopt;
160: }
161: return(0);
162: }
166: PetscErrorCode PetscOptionsGetFromGUI()
167: {
169: PetscOptions next = PetscOptionsObject.next;
170: char str[512];
172: (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
173: while (next) {
174: switch (next->type) {
175: case OPTION_HEAD:
176: break;
177: case OPTION_INT:
178: PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
179: scanf("%s\n",str);
180: if (str[0] != '\n') {
181: printf("changing value\n");
182: }
183: break;
184: default:
185: break;
186: }
187: next = next->next;
188: }
189: return(0);
190: }
194: PetscErrorCode PetscOptionsEnd_Private(void)
195: {
197: PetscOptions last;
198: char option[256],value[1024],tmp[32];
199: PetscInt j;
203: /* if (PetscOptionsObject.next) {
204: PetscOptionsGetFromGUI();
205: }*/
207: PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title = 0;
208: PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
210: /* reset counter to -2; this updates the screen with the new options for the selected method */
211: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
212: /* reset alreadyprinted flag */
213: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
215: while (PetscOptionsObject.next) {
216: if (PetscOptionsObject.next->set) {
217: if (PetscOptionsObject.prefix) {
218: PetscStrcpy(option,"-");
219: PetscStrcat(option,PetscOptionsObject.prefix);
220: PetscStrcat(option,PetscOptionsObject.next->option+1);
221: } else {
222: PetscStrcpy(option,PetscOptionsObject.next->option);
223: }
225: switch (PetscOptionsObject.next->type) {
226: case OPTION_HEAD:
227: break;
228: case OPTION_INT:
229: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
230: break;
231: case OPTION_REAL:
232: sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
233: break;
234: case OPTION_REAL_ARRAY:
235: sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
236: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
237: sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
238: PetscStrcat(value,",");
239: PetscStrcat(value,tmp);
240: }
241: break;
242: case OPTION_LOGICAL:
243: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
244: break;
245: case OPTION_LIST:
246: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
247: break;
248: case OPTION_STRING: /* also handles string arrays */
249: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
250: break;
251: }
252: PetscOptionsSetValue(option,value);
253: }
254: PetscStrfree(PetscOptionsObject.next->text);
255: PetscStrfree(PetscOptionsObject.next->option);
256: PetscFree(PetscOptionsObject.next->man);
257: PetscFree(PetscOptionsObject.next->data);
258: PetscFree(PetscOptionsObject.next->edata);
259: last = PetscOptionsObject.next;
260: PetscOptionsObject.next = PetscOptionsObject.next->next;
261: PetscFree(last);
262: }
263: PetscOptionsObject.next = 0;
264: return(0);
265: }
269: /*@C
270: PetscOptionsEnum - Gets the enum value for a particular option in the database.
272: Collective on the communicator passed in PetscOptionsBegin()
274: Input Parameters:
275: + opt - option name
276: . text - short string that describes the option
277: . man - manual page with additional information on option
278: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
279: - defaultv - the default (current) value
281: Output Parameter:
282: + value - the value to return
283: - flg - PETSC_TRUE if found, else PETSC_FALSE
285: Level: beginner
287: Concepts: options database
289: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
291: list is usually something like PCASMTypes or some other predefined list of enum names
293: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
294: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
295: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
296: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
297: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
298: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
299: PetscOptionsList(), PetscOptionsEList()
300: @*/
301: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
302: {
304: PetscInt ntext = 0;
307: while (list[ntext++]) {
308: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
309: }
310: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
311: ntext -= 3;
312: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
313: return(0);
314: }
316: /* -------------------------------------------------------------------------------------------------------------*/
319: /*@C
320: PetscOptionsInt - Gets the integer value for a particular option in the database.
322: Collective on the communicator passed in PetscOptionsBegin()
324: Input Parameters:
325: + opt - option name
326: . text - short string that describes the option
327: . man - manual page with additional information on option
328: - defaultv - the default (current) value
330: Output Parameter:
331: + value - the integer value to return
332: - flg - PETSC_TRUE if found, else PETSC_FALSE
334: Level: beginner
336: Concepts: options database^has int
338: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
340: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
341: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
342: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
343: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
344: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
345: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
346: PetscOptionsList(), PetscOptionsEList()
347: @*/
348: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
349: {
351: PetscOptions amsopt;
354: if (PetscOptionsPublishCount == 1) {
355: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
356: PetscMalloc(sizeof(PetscInt),&amsopt->data);
357: *(PetscInt*)amsopt->data = defaultv;
358: }
359: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
360: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
361: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
362: }
363: return(0);
364: }
368: /*@C
369: PetscOptionsString - Gets the string value for a particular option in the database.
371: Collective on the communicator passed in PetscOptionsBegin()
373: Input Parameters:
374: + opt - option name
375: . text - short string that describes the option
376: . man - manual page with additional information on option
377: - defaultv - the default (current) value
379: Output Parameter:
380: + value - the value to return
381: - flg - PETSC_TRUE if found, else PETSC_FALSE
383: Level: beginner
385: Concepts: options database^has int
387: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
389: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
390: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
391: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
392: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
393: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
394: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
395: PetscOptionsList(), PetscOptionsEList()
396: @*/
397: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
398: {
402: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
403: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
404: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
405: }
406: return(0);
407: }
409: /*
410: Publishes an AMS double field (with the default value in it) and with a name
411: given by the text string
412: */
415: /*@C
416: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
418: Collective on the communicator passed in PetscOptionsBegin()
420: Input Parameters:
421: + opt - option name
422: . text - short string that describes the option
423: . man - manual page with additional information on option
424: - defaultv - the default (current) value
426: Output Parameter:
427: + value - the value to return
428: - flg - PETSC_TRUE if found, else PETSC_FALSE
430: Level: beginner
432: Concepts: options database^has int
434: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
436: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
437: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
438: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
439: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
440: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
441: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
442: PetscOptionsList(), PetscOptionsEList()
443: @*/
444: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
445: {
449: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
450: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
451: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
452: }
453: return(0);
454: }
458: /*@C
459: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
461: Collective on the communicator passed in PetscOptionsBegin()
463: Input Parameters:
464: + opt - option name
465: . text - short string that describes the option
466: . man - manual page with additional information on option
467: - defaultv - the default (current) value
469: Output Parameter:
470: + value - the value to return
471: - flg - PETSC_TRUE if found, else PETSC_FALSE
473: Level: beginner
475: Concepts: options database^has int
477: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
479: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
480: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
481: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
482: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
483: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
484: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
485: PetscOptionsList(), PetscOptionsEList()
486: @*/
487: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
488: {
492: #if !defined(PETSC_USE_COMPLEX)
493: PetscOptionsReal(opt,text,man,defaultv,value,set);
494: #else
495: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
496: #endif
497: return(0);
498: }
500: /*
501: Publishes an AMS logical field (with the default value in it) and with a name
502: given by the text string
503: */
506: /*@C
507: PetscOptionsName - Determines if a particular option is in the database
509: Collective on the communicator passed in PetscOptionsBegin()
511: Input Parameters:
512: + opt - option name
513: . text - short string that describes the option
514: - man - manual page with additional information on option
516: Output Parameter:
517: . flg - PETSC_TRUE if found, else PETSC_FALSE
519: Level: beginner
521: Concepts: options database^has int
523: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
525: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
526: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
527: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
528: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
529: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
530: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
531: PetscOptionsList(), PetscOptionsEList()
532: @*/
533: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
534: {
538: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
539: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
540: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
541: }
542: return(0);
543: }
547: /*@C
548: PetscOptionsList - Puts a list of option values that a single one may be selected from
550: Collective on the communicator passed in PetscOptionsBegin()
552: Input Parameters:
553: + opt - option name
554: . text - short string that describes the option
555: . man - manual page with additional information on option
556: . list - the possible choices
557: - defaultv - the default (current) value
559: Output Parameter:
560: + value - the value to return
561: - set - PETSC_TRUE if found, else PETSC_FALSE
563: Level: intermediate
564:
565: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
567: See PetscOptionsEList() for when the choices are given in a string array
569: To get a listing of all currently specified options,
570: see PetscOptionsPrint() or PetscOptionsGetAll()
572: Concepts: options database^list
574: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
575: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
576: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
577: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
578: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
579: PetscOptionsList(), PetscOptionsEList()
580: @*/
581: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
582: {
586: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
587: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
588: PetscFListPrintTypes(list,PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man);
589: }
590: return(0);
591: }
595: /*@C
596: PetscOptionsEList - Puts a list of option values that a single one may be selected from
598: Collective on the communicator passed in PetscOptionsBegin()
600: Input Parameters:
601: + opt - option name
602: . ltext - short string that describes the option
603: . man - manual page with additional information on option
604: . list - the possible choices
605: . ntext - number of choices
606: - defaultv - the default (current) value
608: Output Parameter:
609: + value - the index of the value to return
610: - set - PETSC_TRUE if found, else PETSC_FALSE
611:
612: Level: intermediate
614: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
616: See PetscOptionsList() for when the choices are given in a PetscFList()
618: Concepts: options database^list
620: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
621: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
622: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
623: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
624: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
625: PetscOptionsList(), PetscOptionsEList()
626: @*/
627: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
628: {
630: PetscInt i;
633: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
634: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
635: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
636: for (i=0; i<ntext; i++){
637: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
638: }
639: (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
640: }
641: return(0);
642: }
646: /*@C
647: PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
648: which only a single value can be true.
650: Collective on the communicator passed in PetscOptionsBegin()
652: Input Parameters:
653: + opt - option name
654: . text - short string that describes the option
655: - man - manual page with additional information on option
657: Output Parameter:
658: . flg - whether that option was set or not
659:
660: Level: intermediate
662: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
664: Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()
666: Concepts: options database^logical group
668: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
669: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
670: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
671: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
672: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
673: PetscOptionsList(), PetscOptionsEList()
674: @*/
675: PetscErrorCode PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
676: {
680: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
681: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
682: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
683: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
684: }
685: return(0);
686: }
690: /*@C
691: PetscOptionsTruthGroup - One in a series of logical queries on the options database for
692: which only a single value can be true.
694: Collective on the communicator passed in PetscOptionsBegin()
696: Input Parameters:
697: + opt - option name
698: . text - short string that describes the option
699: - man - manual page with additional information on option
701: Output Parameter:
702: . flg - PETSC_TRUE if found, else PETSC_FALSE
703:
704: Level: intermediate
706: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
708: Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()
710: Concepts: options database^logical group
712: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
713: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
714: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
715: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
716: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
717: PetscOptionsList(), PetscOptionsEList()
718: @*/
719: PetscErrorCode PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
720: {
724: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
725: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
726: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
727: }
728: return(0);
729: }
733: /*@C
734: PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
735: which only a single value can be true.
737: Collective on the communicator passed in PetscOptionsBegin()
739: Input Parameters:
740: + opt - option name
741: . text - short string that describes the option
742: - man - manual page with additional information on option
744: Output Parameter:
745: . flg - PETSC_TRUE if found, else PETSC_FALSE
746:
747: Level: intermediate
749: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
751: Must follow a PetscOptionsTruthGroupBegin()
753: Concepts: options database^logical group
755: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
756: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
757: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
758: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
759: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
760: PetscOptionsList(), PetscOptionsEList()
761: @*/
762: PetscErrorCode PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
763: {
767: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
768: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
769: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
770: }
771: return(0);
772: }
776: /*@C
777: PetscOptionsTruth - Determines if a particular option is in the database with a true or false
779: Collective on the communicator passed in PetscOptionsBegin()
781: Input Parameters:
782: + opt - option name
783: . text - short string that describes the option
784: - man - manual page with additional information on option
786: Output Parameter:
787: . flg - PETSC_TRUE or PETSC_FALSE
788: . set - PETSC_TRUE if found, else PETSC_FALSE
790: Level: beginner
792: Concepts: options database^logical
794: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
796: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
797: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
798: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
799: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
800: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
801: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
802: PetscOptionsList(), PetscOptionsEList()
803: @*/
804: PetscErrorCode PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
805: {
807: PetscTruth iset;
810: PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
811: if (!iset) {
812: if (flg) *flg = deflt;
813: }
814: if (set) *set = iset;
815: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
816: const char *v = PetscTruths[deflt];
817: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
818: }
819: return(0);
820: }
824: /*@C
825: PetscOptionsRealArray - Gets an array of double values for a particular
826: option in the database. The values must be separated with commas with
827: no intervening spaces.
829: Collective on the communicator passed in PetscOptionsBegin()
831: Input Parameters:
832: + opt - the option one is seeking
833: . text - short string describing option
834: . man - manual page for option
835: - nmax - maximum number of values
837: Output Parameter:
838: + value - location to copy values
839: . nmax - actual number of values found
840: - set - PETSC_TRUE if found, else PETSC_FALSE
842: Level: beginner
844: Notes:
845: The user should pass in an array of doubles
847: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
849: Concepts: options database^array of strings
851: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
852: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
853: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
854: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
855: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
856: PetscOptionsList(), PetscOptionsEList()
857: @*/
858: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
859: {
861: PetscInt i;
864: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
865: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
866: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
867: for (i=1; i<*n; i++) {
868: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
869: }
870: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
871: }
872: return(0);
873: }
878: /*@C
879: PetscOptionsIntArray - Gets an array of integers for a particular
880: option in the database. The values must be separated with commas with
881: no intervening spaces.
883: Collective on the communicator passed in PetscOptionsBegin()
885: Input Parameters:
886: + opt - the option one is seeking
887: . text - short string describing option
888: . man - manual page for option
889: - nmax - maximum number of values
891: Output Parameter:
892: + value - location to copy values
893: . nmax - actual number of values found
894: - set - PETSC_TRUE if found, else PETSC_FALSE
896: Level: beginner
898: Notes:
899: The user should pass in an array of integers
901: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
903: Concepts: options database^array of strings
905: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
906: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
907: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
908: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
909: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
910: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
911: @*/
912: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
913: {
915: PetscInt i;
918: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
919: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
920: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
921: for (i=1; i<*n; i++) {
922: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
923: }
924: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
925: }
926: return(0);
927: }
931: /*@C
932: PetscOptionsStringArray - Gets an array of string values for a particular
933: option in the database. The values must be separated with commas with
934: no intervening spaces.
936: Collective on the communicator passed in PetscOptionsBegin()
938: Input Parameters:
939: + opt - the option one is seeking
940: . text - short string describing option
941: . man - manual page for option
942: - nmax - maximum number of strings
944: Output Parameter:
945: + value - location to copy strings
946: . nmax - actual number of strings found
947: - set - PETSC_TRUE if found, else PETSC_FALSE
949: Level: beginner
951: Notes:
952: The user should pass in an array of pointers to char, to hold all the
953: strings returned by this function.
955: The user is responsible for deallocating the strings that are
956: returned. The Fortran interface for this routine is not supported.
958: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
960: Concepts: options database^array of strings
962: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
963: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
964: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
965: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
966: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
967: PetscOptionsList(), PetscOptionsEList()
968: @*/
969: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
970: {
974: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
975: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
976: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
977: }
978: return(0);
979: }
984: /*@C
985: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
986: in KSPSetFromOptions_GMRES().
988: Collective on the communicator passed in PetscOptionsBegin()
990: Input Parameter:
991: . head - the heading text
993:
994: Level: intermediate
996: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
998: Can be followed by a call to PetscOptionsTail() in the same function.
1000: Concepts: options database^subheading
1002: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1003: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1004: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1005: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1006: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1007: PetscOptionsList(), PetscOptionsEList()
1008: @*/
1009: PetscErrorCode PetscOptionsHead(const char head[])
1010: {
1014: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1015: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1016: }
1017: return(0);
1018: }