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: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD} OptionType;
23: typedef struct _p_Options* PetscOptions;
24: struct _p_Options {
25: char *option;
26: char *text;
27: void *data;
28: void *edata;
29: char *man;
30: int arraylength;
31: PetscTruth set;
32: OptionType type;
33: PetscOptions next;
34: };
36: static struct {
37: PetscOptions next;
38: char *prefix,*mprefix;
39: char *title;
40: MPI_Comm comm;
41: PetscTruth printhelp,changedmethod;
42: } PetscOptionsObject;
43: PetscInt PetscOptionsPublishCount = 0;
47: /*
48: Handles setting up the data structure in a call to PetscOptionsBegin()
49: */
50: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
51: {
55: PetscOptionsObject.next = 0;
56: PetscOptionsObject.comm = comm;
57: PetscOptionsObject.changedmethod = PETSC_FALSE;
58: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
59: PetscStrallocpy(title,&PetscOptionsObject.title);
61: PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
62: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
63: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
64: }
65: return(0);
66: }
68: /*
69: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
70: */
73: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
74: {
75: int ierr;
76: PetscOptions next;
79: PetscNew(struct _p_Options,amsopt);
80: (*amsopt)->next = 0;
81: (*amsopt)->set = PETSC_FALSE;
82: (*amsopt)->type = t;
83: (*amsopt)->data = 0;
84: (*amsopt)->edata = 0;
85: PetscStrallocpy(text,&(*amsopt)->text);
86: PetscStrallocpy(opt,&(*amsopt)->option);
87: PetscStrallocpy(man,&(*amsopt)->man);
89: if (!PetscOptionsObject.next) {
90: PetscOptionsObject.next = *amsopt;
91: } else {
92: next = PetscOptionsObject.next;
93: while (next->next) next = next->next;
94: next->next = *amsopt;
95: }
96: return(0);
97: }
101: PetscErrorCode PetscOptionsGetFromGUI()
102: {
104: PetscOptions next = PetscOptionsObject.next;
105: char str[512];
107: (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
108: while (next) {
109: switch (next->type) {
110: case OPTION_HEAD:
111: break;
112: case OPTION_INT:
113: PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
114: scanf("%s\n",str);
115: if (str[0] != '\n') {
116: printf("changing value\n");
117: }
118: break;
119: default:
120: break;
121: }
122: next = next->next;
123: }
124: return(0);
125: }
129: PetscErrorCode PetscOptionsEnd_Private(void)
130: {
132: PetscOptions last;
133: char option[256],value[1024],tmp[32];
134: PetscInt j;
138: /* if (PetscOptionsObject.next) {
139: PetscOptionsGetFromGUI();
140: }*/
142: PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title = 0;
143: PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
145: /* reset counter to -2; this updates the screen with the new options for the selected method */
146: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
148: while (PetscOptionsObject.next) {
149: if (PetscOptionsObject.next->set) {
150: if (PetscOptionsObject.prefix) {
151: PetscStrcpy(option,"-");
152: PetscStrcat(option,PetscOptionsObject.prefix);
153: PetscStrcat(option,PetscOptionsObject.next->option+1);
154: } else {
155: PetscStrcpy(option,PetscOptionsObject.next->option);
156: }
158: switch (PetscOptionsObject.next->type) {
159: case OPTION_HEAD:
160: break;
161: case OPTION_INT:
162: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
163: break;
164: case OPTION_REAL:
165: sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
166: break;
167: case OPTION_REAL_ARRAY:
168: sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
169: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
170: sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
171: PetscStrcat(value,",");
172: PetscStrcat(value,tmp);
173: }
174: break;
175: case OPTION_LOGICAL:
176: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
177: break;
178: case OPTION_LIST:
179: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
180: break;
181: case OPTION_STRING: /* also handles string arrays */
182: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
183: break;
184: }
185: PetscOptionsSetValue(option,value);
186: }
187: PetscStrfree(PetscOptionsObject.next->text);
188: PetscStrfree(PetscOptionsObject.next->option);
189: PetscFree(PetscOptionsObject.next->man);
190: PetscFree(PetscOptionsObject.next->data);
191: PetscFree(PetscOptionsObject.next->edata);
192: last = PetscOptionsObject.next;
193: PetscOptionsObject.next = PetscOptionsObject.next->next;
194: PetscFree(last);
195: }
196: PetscOptionsObject.next = 0;
197: return(0);
198: }
202: /*@C
203: PetscOptionsEnum - Gets the enum value for a particular option in the database.
205: Collective on the communicator passed in PetscOptionsBegin()
207: Input Parameters:
208: + opt - option name
209: . text - short string that describes the option
210: . man - manual page with additional information on option
211: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
212: - defaultv - the default (current) value
214: Output Parameter:
215: + value - the value to return
216: - flg - PETSC_TRUE if found, else PETSC_FALSE
218: Level: beginner
220: Concepts: options database
222: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
224: list is usually something like PCASMTypes or some other predefined list of enum names
226: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
227: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
228: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
229: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
230: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
231: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
232: PetscOptionsList(), PetscOptionsEList()
233: @*/
234: PetscErrorCode PETSC_DLLEXPORT PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
235: {
237: PetscInt ntext = 0;
240: while (list[ntext++]) {
241: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
242: }
243: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
244: ntext -= 3;
245: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
246: return(0);
247: }
249: /* -------------------------------------------------------------------------------------------------------------*/
252: /*@C
253: PetscOptionsInt - Gets the integer value for a particular option in the database.
255: Collective on the communicator passed in PetscOptionsBegin()
257: Input Parameters:
258: + opt - option name
259: . text - short string that describes the option
260: . man - manual page with additional information on option
261: - defaultv - the default (current) value
263: Output Parameter:
264: + value - the integer value to return
265: - flg - PETSC_TRUE if found, else PETSC_FALSE
267: Level: beginner
269: Concepts: options database^has int
271: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
273: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
274: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
275: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
276: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
277: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
278: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
279: PetscOptionsList(), PetscOptionsEList()
280: @*/
281: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
282: {
284: PetscOptions amsopt;
287: if (PetscOptionsPublishCount == 1) {
288: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
289: PetscMalloc(sizeof(PetscInt),&amsopt->data);
290: *(PetscInt*)amsopt->data = defaultv;
291: }
292: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
293: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
294: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
295: }
296: return(0);
297: }
301: /*@C
302: PetscOptionsString - Gets the string value for a particular option in the database.
304: Collective on the communicator passed in PetscOptionsBegin()
306: Input Parameters:
307: + opt - option name
308: . text - short string that describes the option
309: . man - manual page with additional information on option
310: - defaultv - the default (current) value
312: Output Parameter:
313: + value - the value to return
314: - flg - PETSC_TRUE if found, else PETSC_FALSE
316: Level: beginner
318: Concepts: options database^has int
320: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
322: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
323: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
324: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
325: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
326: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
327: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
328: PetscOptionsList(), PetscOptionsEList()
329: @*/
330: PetscErrorCode PETSC_DLLEXPORT PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
331: {
335: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
336: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
337: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
338: }
339: return(0);
340: }
342: /*
343: Publishes an AMS double field (with the default value in it) and with a name
344: given by the text string
345: */
348: /*@C
349: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
351: Collective on the communicator passed in PetscOptionsBegin()
353: Input Parameters:
354: + opt - option name
355: . text - short string that describes the option
356: . man - manual page with additional information on option
357: - defaultv - the default (current) value
359: Output Parameter:
360: + value - the value to return
361: - flg - PETSC_TRUE if found, else PETSC_FALSE
363: Level: beginner
365: Concepts: options database^has int
367: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
369: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
370: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
371: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
372: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
373: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
374: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
375: PetscOptionsList(), PetscOptionsEList()
376: @*/
377: PetscErrorCode PETSC_DLLEXPORT PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
378: {
382: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
383: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
384: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
385: }
386: return(0);
387: }
391: /*@C
392: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
394: Collective on the communicator passed in PetscOptionsBegin()
396: Input Parameters:
397: + opt - option name
398: . text - short string that describes the option
399: . man - manual page with additional information on option
400: - defaultv - the default (current) value
402: Output Parameter:
403: + value - the value to return
404: - flg - PETSC_TRUE if found, else PETSC_FALSE
406: Level: beginner
408: Concepts: options database^has int
410: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
412: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
413: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
414: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
415: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
416: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
417: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
418: PetscOptionsList(), PetscOptionsEList()
419: @*/
420: PetscErrorCode PETSC_DLLEXPORT PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
421: {
425: #if !defined(PETSC_USE_COMPLEX)
426: PetscOptionsReal(opt,text,man,defaultv,value,set);
427: #else
428: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
429: #endif
430: return(0);
431: }
433: /*
434: Publishes an AMS logical field (with the default value in it) and with a name
435: given by the text string
436: */
439: /*@C
440: PetscOptionsName - Determines if a particular option is in the database
442: Collective on the communicator passed in PetscOptionsBegin()
444: Input Parameters:
445: + opt - option name
446: . text - short string that describes the option
447: - man - manual page with additional information on option
449: Output Parameter:
450: . flg - PETSC_TRUE if found, else PETSC_FALSE
452: Level: beginner
454: Concepts: options database^has int
456: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
458: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
459: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
460: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
461: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
462: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
463: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
464: PetscOptionsList(), PetscOptionsEList()
465: @*/
466: PetscErrorCode PETSC_DLLEXPORT PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
467: {
471: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
472: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
473: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
474: }
475: return(0);
476: }
480: /*@C
481: PetscOptionsList - Puts a list of option values that a single one may be selected from
483: Collective on the communicator passed in PetscOptionsBegin()
485: Input Parameters:
486: + opt - option name
487: . text - short string that describes the option
488: . man - manual page with additional information on option
489: . list - the possible choices
490: - defaultv - the default (current) value
492: Output Parameter:
493: + value - the value to return
494: - set - PETSC_TRUE if found, else PETSC_FALSE
496: Level: intermediate
497:
498: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
500: See PetscOptionsEList() for when the choices are given in a string array
502: To get a listing of all currently specified options,
503: see PetscOptionsPrint() or PetscOptionsGetAll()
505: Concepts: options database^list
507: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
508: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
509: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
510: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
511: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
512: PetscOptionsList(), PetscOptionsEList()
513: @*/
514: PetscErrorCode PETSC_DLLEXPORT PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
515: {
519: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
520: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
521: PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list);
522: }
523: return(0);
524: }
528: /*@C
529: PetscOptionsEList - Puts a list of option values that a single one may be selected from
531: Collective on the communicator passed in PetscOptionsBegin()
533: Input Parameters:
534: + opt - option name
535: . ltext - short string that describes the option
536: . man - manual page with additional information on option
537: . list - the possible choices
538: . ntext - number of choices
539: - defaultv - the default (current) value
541: Output Parameter:
542: + value - the index of the value to return
543: - set - PETSC_TRUE if found, else PETSC_FALSE
544:
545: Level: intermediate
547: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
549: See PetscOptionsList() for when the choices are given in a PetscFList()
551: Concepts: options database^list
553: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
554: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
555: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
556: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
557: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
558: PetscOptionsList(), PetscOptionsEList()
559: @*/
560: PetscErrorCode PETSC_DLLEXPORT PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
561: {
563: PetscInt i;
566: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
567: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
568: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
569: for (i=0; i<ntext; i++){
570: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
571: }
572: (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
573: }
574: return(0);
575: }
579: /*@C
580: PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
581: which only a single value can be true.
583: Collective on the communicator passed in PetscOptionsBegin()
585: Input Parameters:
586: + opt - option name
587: . text - short string that describes the option
588: - man - manual page with additional information on option
590: Output Parameter:
591: . flg - whether that option was set or not
592:
593: Level: intermediate
595: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
597: Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()
599: Concepts: options database^logical group
601: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
602: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
603: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
604: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
605: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
606: PetscOptionsList(), PetscOptionsEList()
607: @*/
608: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
609: {
613: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
614: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
615: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
616: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
617: }
618: return(0);
619: }
623: /*@C
624: PetscOptionsTruthGroup - One in a series of logical queries on the options database for
625: which only a single value can be true.
627: Collective on the communicator passed in PetscOptionsBegin()
629: Input Parameters:
630: + opt - option name
631: . text - short string that describes the option
632: - man - manual page with additional information on option
634: Output Parameter:
635: . flg - PETSC_TRUE if found, else PETSC_FALSE
636:
637: Level: intermediate
639: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
641: Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()
643: Concepts: options database^logical group
645: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
646: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
647: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
648: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
649: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
650: PetscOptionsList(), PetscOptionsEList()
651: @*/
652: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
653: {
657: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
658: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
659: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
660: }
661: return(0);
662: }
666: /*@C
667: PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
668: which only a single value can be true.
670: Collective on the communicator passed in PetscOptionsBegin()
672: Input Parameters:
673: + opt - option name
674: . text - short string that describes the option
675: - man - manual page with additional information on option
677: Output Parameter:
678: . flg - PETSC_TRUE if found, else PETSC_FALSE
679:
680: Level: intermediate
682: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
684: Must follow a PetscOptionsTruthGroupBegin()
686: Concepts: options database^logical group
688: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
689: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
690: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
691: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
692: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
693: PetscOptionsList(), PetscOptionsEList()
694: @*/
695: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
696: {
700: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
701: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
702: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
703: }
704: return(0);
705: }
709: /*@C
710: PetscOptionsTruth - Determines if a particular option is in the database with a true or false
712: Collective on the communicator passed in PetscOptionsBegin()
714: Input Parameters:
715: + opt - option name
716: . text - short string that describes the option
717: - man - manual page with additional information on option
719: Output Parameter:
720: . flg - PETSC_TRUE or PETSC_FALSE
721: . set - PETSC_TRUE if found, else PETSC_FALSE
723: Level: beginner
725: Concepts: options database^logical
727: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
729: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
730: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
731: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
732: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
733: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
734: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
735: PetscOptionsList(), PetscOptionsEList()
736: @*/
737: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
738: {
740: PetscTruth iset;
743: PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
744: if (!iset) {
745: if (flg) *flg = deflt;
746: }
747: if (set) *set = iset;
748: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
749: const char *v = PetscTruths[deflt];
750: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
751: }
752: return(0);
753: }
757: /*@C
758: PetscOptionsRealArray - Gets an array of double values for a particular
759: option in the database. The values must be separated with commas with
760: no intervening spaces.
762: Collective on the communicator passed in PetscOptionsBegin()
764: Input Parameters:
765: + opt - the option one is seeking
766: . text - short string describing option
767: . man - manual page for option
768: - nmax - maximum number of values
770: Output Parameter:
771: + value - location to copy values
772: . nmax - actual number of values found
773: - set - PETSC_TRUE if found, else PETSC_FALSE
775: Level: beginner
777: Notes:
778: The user should pass in an array of doubles
780: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
782: Concepts: options database^array of strings
784: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
785: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
786: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
787: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
788: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
789: PetscOptionsList(), PetscOptionsEList()
790: @*/
791: PetscErrorCode PETSC_DLLEXPORT PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
792: {
794: PetscInt i;
797: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
798: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
799: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
800: for (i=1; i<*n; i++) {
801: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
802: }
803: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
804: }
805: return(0);
806: }
811: /*@C
812: PetscOptionsIntArray - Gets an array of integers for a particular
813: option in the database. The values must be separated with commas with
814: no intervening spaces.
816: Collective on the communicator passed in PetscOptionsBegin()
818: Input Parameters:
819: + opt - the option one is seeking
820: . text - short string describing option
821: . man - manual page for option
822: - nmax - maximum number of values
824: Output Parameter:
825: + value - location to copy values
826: . nmax - actual number of values found
827: - set - PETSC_TRUE if found, else PETSC_FALSE
829: Level: beginner
831: Notes:
832: The user should pass in an array of integers
834: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
836: Concepts: options database^array of strings
838: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
839: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
840: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
841: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
842: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
843: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
844: @*/
845: PetscErrorCode PETSC_DLLEXPORT PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
846: {
848: PetscInt i;
851: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
852: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
853: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
854: for (i=1; i<*n; i++) {
855: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
856: }
857: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
858: }
859: return(0);
860: }
864: /*@C
865: PetscOptionsStringArray - Gets an array of string values for a particular
866: option in the database. The values must be separated with commas with
867: no intervening spaces.
869: Collective on the communicator passed in PetscOptionsBegin()
871: Input Parameters:
872: + opt - the option one is seeking
873: . text - short string describing option
874: . man - manual page for option
875: - nmax - maximum number of strings
877: Output Parameter:
878: + value - location to copy strings
879: . nmax - actual number of strings found
880: - set - PETSC_TRUE if found, else PETSC_FALSE
882: Level: beginner
884: Notes:
885: The user should pass in an array of pointers to char, to hold all the
886: strings returned by this function.
888: The user is responsible for deallocating the strings that are
889: returned. The Fortran interface for this routine is not supported.
891: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
893: Concepts: options database^array of strings
895: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
896: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
897: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
898: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
899: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
900: PetscOptionsList(), PetscOptionsEList()
901: @*/
902: PetscErrorCode PETSC_DLLEXPORT PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
903: {
907: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
908: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
909: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
910: }
911: return(0);
912: }
917: /*@C
918: PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
919: in KSPSetFromOptions_GMRES().
921: Collective on the communicator passed in PetscOptionsBegin()
923: Input Parameter:
924: . head - the heading text
926:
927: Level: intermediate
929: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
931: Must be followed by a call to PetscOptionsTail() in the same function.
933: Concepts: options database^subheading
935: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
936: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
937: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
938: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
939: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
940: PetscOptionsList(), PetscOptionsEList()
941: @*/
942: PetscErrorCode PETSC_DLLEXPORT PetscOptionsHead(const char head[])
943: {
947: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
948: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
949: }
950: return(0);
951: }