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: typedef struct _p_OptionsHelp* OptionsHelp;
37: struct _p_OptionsHelp {
38: char *prefix;
39: char *title;
40: char *mansec;
41: OptionsHelp next;
42: };
44: static struct {
45: PetscOptions next;
46: char *prefix,*mprefix;
47: char *title;
48: MPI_Comm comm;
49: PetscTruth printhelp,changedmethod,alreadyprinted;
50: OptionsHelp help;
51: } PetscOptionsObject;
52: PetscInt PetscOptionsPublishCount = 0;
57: PetscErrorCode PetscOptionsHelpAddList(const char prefix[],const char title[],const char mansec[])
58: {
59: int ierr;
60: OptionsHelp newhelp;
62: PetscNew(struct _p_OptionsHelp,&newhelp);
63: PetscStrallocpy(prefix,&newhelp->prefix);
64: PetscStrallocpy(title,&newhelp->title);
65: PetscStrallocpy(mansec,&newhelp->mansec);
66: newhelp->next = 0;
68: if (!PetscOptionsObject.help) {
69: PetscOptionsObject.help = newhelp;
70: } else {
71: newhelp->next = PetscOptionsObject.help;
72: PetscOptionsObject.help = newhelp;
73: }
74: return(0);
75: }
79: PetscErrorCode PetscOptionsHelpDestroyList(void)
80: {
82: OptionsHelp help = PetscOptionsObject.help, next;
85: while (help) {
86: next = help->next;
87: PetscStrfree(help->prefix);
88: PetscStrfree(help->title);
89: PetscStrfree(help->mansec);
90: PetscFree(help);
91: help = next;
92: }
93: return(0);
94: }
95:
99: PetscErrorCode PetscOptionsHelpFindList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
100: {
102: PetscTruth flg1,flg2,flg3;
103: OptionsHelp help = PetscOptionsObject.help;
105: while (help) {
106: PetscStrcmp(help->prefix,prefix,&flg1);
107: PetscStrcmp(help->title,title,&flg2);
108: PetscStrcmp(help->mansec,mansec,&flg3);
109: if (flg1 && flg2 && flg3) {
110: *flg = PETSC_TRUE;
111: break;
112: }
113: help = help->next;
114: }
115: return(0);
117: }
121: PetscErrorCode PetscOptionsHelpCheckAddList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
122: {
124: PetscOptionsHelpFindList(prefix,title,mansec,flg);
125: if (!(*flg)) PetscOptionsHelpAddList(prefix,title,mansec);
126: return(0);
127: }
131: /*
132: Handles setting up the data structure in a call to PetscOptionsBegin()
133: */
134: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
135: {
139: PetscOptionsObject.next = 0;
140: PetscOptionsObject.comm = comm;
141: PetscOptionsObject.changedmethod = PETSC_FALSE;
142: PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
143: PetscStrallocpy(title,&PetscOptionsObject.title);
145: PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
146: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
147: PetscOptionsHelpCheckAddList(prefix,title,mansec,&PetscOptionsObject.alreadyprinted);
148: if (!PetscOptionsObject.alreadyprinted) {
149: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
150: }
151: }
152: return(0);
153: }
155: /*
156: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
157: */
160: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
161: {
162: int ierr;
163: PetscOptions next;
166: PetscNew(struct _p_Options,amsopt);
167: (*amsopt)->next = 0;
168: (*amsopt)->set = PETSC_FALSE;
169: (*amsopt)->type = t;
170: (*amsopt)->data = 0;
171: (*amsopt)->edata = 0;
173: PetscStrallocpy(text,&(*amsopt)->text);
174: PetscStrallocpy(opt,&(*amsopt)->option);
175: PetscStrallocpy(man,&(*amsopt)->man);
177: if (!PetscOptionsObject.next) {
178: PetscOptionsObject.next = *amsopt;
179: } else {
180: next = PetscOptionsObject.next;
181: while (next->next) next = next->next;
182: next->next = *amsopt;
183: }
184: return(0);
185: }
189: PetscErrorCode PetscOptionsGetFromGUI()
190: {
192: PetscOptions next = PetscOptionsObject.next;
193: char str[512];
195: (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
196: while (next) {
197: switch (next->type) {
198: case OPTION_HEAD:
199: break;
200: case OPTION_INT:
201: PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
202: scanf("%s\n",str);
203: if (str[0] != '\n') {
204: printf("changing value\n");
205: }
206: break;
207: default:
208: break;
209: }
210: next = next->next;
211: }
212: return(0);
213: }
217: PetscErrorCode PetscOptionsEnd_Private(void)
218: {
220: PetscOptions last;
221: char option[256],value[1024],tmp[32];
222: PetscInt j;
226: /* if (PetscOptionsObject.next) {
227: PetscOptionsGetFromGUI();
228: }*/
230: PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title = 0;
231: PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
233: /* reset counter to -2; this updates the screen with the new options for the selected method */
234: if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
235: /* reset alreadyprinted flag */
236: PetscOptionsObject.alreadyprinted = PETSC_FALSE;
238: while (PetscOptionsObject.next) {
239: if (PetscOptionsObject.next->set) {
240: if (PetscOptionsObject.prefix) {
241: PetscStrcpy(option,"-");
242: PetscStrcat(option,PetscOptionsObject.prefix);
243: PetscStrcat(option,PetscOptionsObject.next->option+1);
244: } else {
245: PetscStrcpy(option,PetscOptionsObject.next->option);
246: }
248: switch (PetscOptionsObject.next->type) {
249: case OPTION_HEAD:
250: break;
251: case OPTION_INT:
252: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
253: break;
254: case OPTION_REAL:
255: sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
256: break;
257: case OPTION_REAL_ARRAY:
258: sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
259: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
260: sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
261: PetscStrcat(value,",");
262: PetscStrcat(value,tmp);
263: }
264: break;
265: case OPTION_LOGICAL:
266: sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
267: break;
268: case OPTION_LIST:
269: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
270: break;
271: case OPTION_STRING: /* also handles string arrays */
272: PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
273: break;
274: }
275: PetscOptionsSetValue(option,value);
276: }
277: PetscStrfree(PetscOptionsObject.next->text);
278: PetscStrfree(PetscOptionsObject.next->option);
279: PetscFree(PetscOptionsObject.next->man);
280: PetscFree(PetscOptionsObject.next->data);
281: PetscFree(PetscOptionsObject.next->edata);
282: last = PetscOptionsObject.next;
283: PetscOptionsObject.next = PetscOptionsObject.next->next;
284: PetscFree(last);
285: }
286: PetscOptionsObject.next = 0;
287: return(0);
288: }
292: /*@C
293: PetscOptionsEnum - Gets the enum value for a particular option in the database.
295: Collective on the communicator passed in PetscOptionsBegin()
297: Input Parameters:
298: + opt - option name
299: . text - short string that describes the option
300: . man - manual page with additional information on option
301: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
302: - defaultv - the default (current) value
304: Output Parameter:
305: + value - the value to return
306: - flg - PETSC_TRUE if found, else PETSC_FALSE
308: Level: beginner
310: Concepts: options database
312: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
314: list is usually something like PCASMTypes or some other predefined list of enum names
316: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
317: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
318: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
319: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
320: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
321: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
322: PetscOptionsList(), PetscOptionsEList()
323: @*/
324: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
325: {
327: PetscInt ntext = 0;
330: while (list[ntext++]) {
331: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
332: }
333: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
334: ntext -= 3;
335: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
336: return(0);
337: }
339: /* -------------------------------------------------------------------------------------------------------------*/
342: /*@C
343: PetscOptionsInt - Gets the integer value for a particular option in the database.
345: Collective on the communicator passed in PetscOptionsBegin()
347: Input Parameters:
348: + opt - option name
349: . text - short string that describes the option
350: . man - manual page with additional information on option
351: - defaultv - the default (current) value
353: Output Parameter:
354: + value - the integer value to return
355: - flg - PETSC_TRUE if found, else PETSC_FALSE
357: Level: beginner
359: Concepts: options database^has int
361: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
363: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
364: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
365: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
366: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
367: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
368: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
369: PetscOptionsList(), PetscOptionsEList()
370: @*/
371: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
372: {
374: PetscOptions amsopt;
377: if (PetscOptionsPublishCount == 1) {
378: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
379: PetscMalloc(sizeof(PetscInt),&amsopt->data);
380: *(PetscInt*)amsopt->data = defaultv;
381: }
382: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
383: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
384: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
385: }
386: return(0);
387: }
391: /*@C
392: PetscOptionsString - Gets the string 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 PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
421: {
425: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
426: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
427: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
428: }
429: return(0);
430: }
432: /*
433: Publishes an AMS double field (with the default value in it) and with a name
434: given by the text string
435: */
438: /*@C
439: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
441: Collective on the communicator passed in PetscOptionsBegin()
443: Input Parameters:
444: + opt - option name
445: . text - short string that describes the option
446: . man - manual page with additional information on option
447: - defaultv - the default (current) value
449: Output Parameter:
450: + value - the value to return
451: - flg - PETSC_TRUE if found, else PETSC_FALSE
453: Level: beginner
455: Concepts: options database^has int
457: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
459: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
460: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
461: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
462: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
463: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
464: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
465: PetscOptionsList(), PetscOptionsEList()
466: @*/
467: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
468: {
472: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
473: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
474: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
475: }
476: return(0);
477: }
481: /*@C
482: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
484: Collective on the communicator passed in PetscOptionsBegin()
486: Input Parameters:
487: + opt - option name
488: . text - short string that describes the option
489: . man - manual page with additional information on option
490: - defaultv - the default (current) value
492: Output Parameter:
493: + value - the value to return
494: - flg - PETSC_TRUE if found, else PETSC_FALSE
496: Level: beginner
498: Concepts: options database^has int
500: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
502: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
503: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
504: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
505: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
506: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
507: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
508: PetscOptionsList(), PetscOptionsEList()
509: @*/
510: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
511: {
515: #if !defined(PETSC_USE_COMPLEX)
516: PetscOptionsReal(opt,text,man,defaultv,value,set);
517: #else
518: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
519: #endif
520: return(0);
521: }
523: /*
524: Publishes an AMS logical field (with the default value in it) and with a name
525: given by the text string
526: */
529: /*@C
530: PetscOptionsName - Determines if a particular option is in the database
532: Collective on the communicator passed in PetscOptionsBegin()
534: Input Parameters:
535: + opt - option name
536: . text - short string that describes the option
537: - man - manual page with additional information on option
539: Output Parameter:
540: . flg - PETSC_TRUE if found, else PETSC_FALSE
542: Level: beginner
544: Concepts: options database^has int
546: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
548: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
549: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
550: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
551: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
552: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
553: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
554: PetscOptionsList(), PetscOptionsEList()
555: @*/
556: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
557: {
561: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
562: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
563: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
564: }
565: return(0);
566: }
570: /*@C
571: PetscOptionsList - Puts a list of option values that a single one may be selected from
573: Collective on the communicator passed in PetscOptionsBegin()
575: Input Parameters:
576: + opt - option name
577: . text - short string that describes the option
578: . man - manual page with additional information on option
579: . list - the possible choices
580: - defaultv - the default (current) value
582: Output Parameter:
583: + value - the value to return
584: - set - PETSC_TRUE if found, else PETSC_FALSE
586: Level: intermediate
587:
588: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
590: See PetscOptionsEList() for when the choices are given in a string array
592: To get a listing of all currently specified options,
593: see PetscOptionsPrint() or PetscOptionsGetAll()
595: Concepts: options database^list
597: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
598: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
599: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
600: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
601: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
602: PetscOptionsList(), PetscOptionsEList()
603: @*/
604: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
605: {
609: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
610: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
611: PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list);
612: }
613: return(0);
614: }
618: /*@C
619: PetscOptionsEList - Puts a list of option values that a single one may be selected from
621: Collective on the communicator passed in PetscOptionsBegin()
623: Input Parameters:
624: + opt - option name
625: . ltext - short string that describes the option
626: . man - manual page with additional information on option
627: . list - the possible choices
628: . ntext - number of choices
629: - defaultv - the default (current) value
631: Output Parameter:
632: + value - the index of the value to return
633: - set - PETSC_TRUE if found, else PETSC_FALSE
634:
635: Level: intermediate
637: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
639: See PetscOptionsList() for when the choices are given in a PetscFList()
641: Concepts: options database^list
643: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
644: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
645: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
646: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
647: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
648: PetscOptionsList(), PetscOptionsEList()
649: @*/
650: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
651: {
653: PetscInt i;
656: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
657: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
658: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
659: for (i=0; i<ntext; i++){
660: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
661: }
662: (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
663: }
664: return(0);
665: }
669: /*@C
670: PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
671: which only a single value can be true.
673: Collective on the communicator passed in PetscOptionsBegin()
675: Input Parameters:
676: + opt - option name
677: . text - short string that describes the option
678: - man - manual page with additional information on option
680: Output Parameter:
681: . flg - whether that option was set or not
682:
683: Level: intermediate
685: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
687: Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()
689: Concepts: options database^logical group
691: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
692: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
693: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
694: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
695: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
696: PetscOptionsList(), PetscOptionsEList()
697: @*/
698: PetscErrorCode PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
699: {
703: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
704: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
705: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
706: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
707: }
708: return(0);
709: }
713: /*@C
714: PetscOptionsTruthGroup - One in a series of logical queries on the options database for
715: which only a single value can be true.
717: Collective on the communicator passed in PetscOptionsBegin()
719: Input Parameters:
720: + opt - option name
721: . text - short string that describes the option
722: - man - manual page with additional information on option
724: Output Parameter:
725: . flg - PETSC_TRUE if found, else PETSC_FALSE
726:
727: Level: intermediate
729: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
731: Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()
733: Concepts: options database^logical group
735: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
736: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
737: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
738: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
739: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
740: PetscOptionsList(), PetscOptionsEList()
741: @*/
742: PetscErrorCode PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
743: {
747: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
748: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
749: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
750: }
751: return(0);
752: }
756: /*@C
757: PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
758: which only a single value can be true.
760: Collective on the communicator passed in PetscOptionsBegin()
762: Input Parameters:
763: + opt - option name
764: . text - short string that describes the option
765: - man - manual page with additional information on option
767: Output Parameter:
768: . flg - PETSC_TRUE if found, else PETSC_FALSE
769:
770: Level: intermediate
772: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
774: Must follow a PetscOptionsTruthGroupBegin()
776: Concepts: options database^logical group
778: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
779: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
780: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
781: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
782: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
783: PetscOptionsList(), PetscOptionsEList()
784: @*/
785: PetscErrorCode PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
786: {
790: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
791: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
792: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
793: }
794: return(0);
795: }
799: /*@C
800: PetscOptionsTruth - Determines if a particular option is in the database with a true or false
802: Collective on the communicator passed in PetscOptionsBegin()
804: Input Parameters:
805: + opt - option name
806: . text - short string that describes the option
807: - man - manual page with additional information on option
809: Output Parameter:
810: . flg - PETSC_TRUE or PETSC_FALSE
811: . set - PETSC_TRUE if found, else PETSC_FALSE
813: Level: beginner
815: Concepts: options database^logical
817: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
819: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
820: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
821: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
822: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
823: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
824: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
825: PetscOptionsList(), PetscOptionsEList()
826: @*/
827: PetscErrorCode PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
828: {
830: PetscTruth iset;
833: PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
834: if (!iset) {
835: if (flg) *flg = deflt;
836: }
837: if (set) *set = iset;
838: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
839: const char *v = PetscTruths[deflt];
840: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
841: }
842: return(0);
843: }
847: /*@C
848: PetscOptionsRealArray - Gets an array of double values for a particular
849: option in the database. The values must be separated with commas with
850: no intervening spaces.
852: Collective on the communicator passed in PetscOptionsBegin()
854: Input Parameters:
855: + opt - the option one is seeking
856: . text - short string describing option
857: . man - manual page for option
858: - nmax - maximum number of values
860: Output Parameter:
861: + value - location to copy values
862: . nmax - actual number of values found
863: - set - PETSC_TRUE if found, else PETSC_FALSE
865: Level: beginner
867: Notes:
868: The user should pass in an array of doubles
870: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
872: Concepts: options database^array of strings
874: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
875: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
876: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
877: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
878: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
879: PetscOptionsList(), PetscOptionsEList()
880: @*/
881: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
882: {
884: PetscInt i;
887: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
888: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
889: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
890: for (i=1; i<*n; i++) {
891: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
892: }
893: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
894: }
895: return(0);
896: }
901: /*@C
902: PetscOptionsIntArray - Gets an array of integers for a particular
903: option in the database. The values must be separated with commas with
904: no intervening spaces.
906: Collective on the communicator passed in PetscOptionsBegin()
908: Input Parameters:
909: + opt - the option one is seeking
910: . text - short string describing option
911: . man - manual page for option
912: - nmax - maximum number of values
914: Output Parameter:
915: + value - location to copy values
916: . nmax - actual number of values found
917: - set - PETSC_TRUE if found, else PETSC_FALSE
919: Level: beginner
921: Notes:
922: The user should pass in an array of integers
924: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
926: Concepts: options database^array of strings
928: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
929: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
930: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
931: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
932: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
933: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
934: @*/
935: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
936: {
938: PetscInt i;
941: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
942: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
943: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
944: for (i=1; i<*n; i++) {
945: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
946: }
947: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
948: }
949: return(0);
950: }
954: /*@C
955: PetscOptionsStringArray - Gets an array of string values for a particular
956: option in the database. The values must be separated with commas with
957: no intervening spaces.
959: Collective on the communicator passed in PetscOptionsBegin()
961: Input Parameters:
962: + opt - the option one is seeking
963: . text - short string describing option
964: . man - manual page for option
965: - nmax - maximum number of strings
967: Output Parameter:
968: + value - location to copy strings
969: . nmax - actual number of strings found
970: - set - PETSC_TRUE if found, else PETSC_FALSE
972: Level: beginner
974: Notes:
975: The user should pass in an array of pointers to char, to hold all the
976: strings returned by this function.
978: The user is responsible for deallocating the strings that are
979: returned. The Fortran interface for this routine is not supported.
981: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
983: Concepts: options database^array of strings
985: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
986: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
987: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
988: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
989: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
990: PetscOptionsList(), PetscOptionsEList()
991: @*/
992: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
993: {
997: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
998: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
999: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
1000: }
1001: return(0);
1002: }
1007: /*@C
1008: PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
1009: in KSPSetFromOptions_GMRES().
1011: Collective on the communicator passed in PetscOptionsBegin()
1013: Input Parameter:
1014: . head - the heading text
1016:
1017: Level: intermediate
1019: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1021: Must be followed by a call to PetscOptionsTail() in the same function.
1023: Concepts: options database^subheading
1025: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1026: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1027: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1028: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1029: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1030: PetscOptionsList(), PetscOptionsEList()
1031: @*/
1032: PetscErrorCode PetscOptionsHead(const char head[])
1033: {
1037: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1038: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1039: }
1040: return(0);
1041: }