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: PetscOptionsHelp newhelp;
33: PetscNew(struct _p_PetscOptionsHelp,&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: {
52: PetscErrorCode ierr;
53: PetscOptionsHelp 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: {
72: PetscErrorCode ierr;
73: PetscTruth flg1,flg2,flg3;
74: PetscOptionsHelp 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[],PetscOptionType t,PetscOptions *amsopt)
138: {
139: int ierr;
140: PetscOptions next;
143: PetscNew(struct _p_PetscOptions,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",(int) *(PetscInt*)PetscOptionsObject.next->data);
230: break;
231: case OPTION_REAL:
232: sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
233: break;
234: case OPTION_REAL_ARRAY:
235: sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
236: for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
237: sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
238: PetscStrcat(value,",");
239: PetscStrcat(value,tmp);
240: }
241: break;
242: case OPTION_LOGICAL:
243: sprintf(value,"%d",(int)*(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;
305: PetscInt tval;
306: PetscTruth tflg;
309: while (list[ntext++]) {
310: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
311: }
312: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
313: ntext -= 3;
314: PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
315: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
316: if (tflg) *value = (PetscEnum)tval;
317: if (set) *set = tflg;
318: return(0);
319: }
321: /* -------------------------------------------------------------------------------------------------------------*/
324: /*@C
325: PetscOptionsInt - Gets the integer value for a particular option in the database.
327: Collective on the communicator passed in PetscOptionsBegin()
329: Input Parameters:
330: + opt - option name
331: . text - short string that describes the option
332: . man - manual page with additional information on option
333: - defaultv - the default (current) value
335: Output Parameter:
336: + value - the integer value to return
337: - flg - PETSC_TRUE if found, else PETSC_FALSE
339: Level: beginner
341: Concepts: options database^has int
343: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
345: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
346: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
347: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
348: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
349: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
350: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
351: PetscOptionsList(), PetscOptionsEList()
352: @*/
353: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
354: {
356: PetscOptions amsopt;
359: if (PetscOptionsPublishCount == 1) {
360: PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
361: PetscMalloc(sizeof(PetscInt),&amsopt->data);
362: *(PetscInt*)amsopt->data = defaultv;
363: }
364: PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
365: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
366: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
367: }
368: return(0);
369: }
373: /*@C
374: PetscOptionsString - Gets the string value for a particular option in the database.
376: Collective on the communicator passed in PetscOptionsBegin()
378: Input Parameters:
379: + opt - option name
380: . text - short string that describes the option
381: . man - manual page with additional information on option
382: - defaultv - the default (current) value
384: Output Parameter:
385: + value - the value to return
386: - flg - PETSC_TRUE if found, else PETSC_FALSE
388: Level: beginner
390: Concepts: options database^has int
392: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
394: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
395: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
396: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
397: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
398: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
399: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
400: PetscOptionsList(), PetscOptionsEList()
401: @*/
402: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
403: {
407: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
408: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
409: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
410: }
411: return(0);
412: }
414: /*
415: Publishes an AMS double field (with the default value in it) and with a name
416: given by the text string
417: */
420: /*@C
421: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
423: Collective on the communicator passed in PetscOptionsBegin()
425: Input Parameters:
426: + opt - option name
427: . text - short string that describes the option
428: . man - manual page with additional information on option
429: - defaultv - the default (current) value
431: Output Parameter:
432: + value - the value to return
433: - flg - PETSC_TRUE if found, else PETSC_FALSE
435: Level: beginner
437: Concepts: options database^has int
439: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
441: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
442: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
443: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
444: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
445: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
446: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
447: PetscOptionsList(), PetscOptionsEList()
448: @*/
449: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
450: {
454: PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
455: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
456: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
457: }
458: return(0);
459: }
463: /*@C
464: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
466: Collective on the communicator passed in PetscOptionsBegin()
468: Input Parameters:
469: + opt - option name
470: . text - short string that describes the option
471: . man - manual page with additional information on option
472: - defaultv - the default (current) value
474: Output Parameter:
475: + value - the value to return
476: - flg - PETSC_TRUE if found, else PETSC_FALSE
478: Level: beginner
480: Concepts: options database^has int
482: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
484: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
485: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
486: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
487: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
488: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
489: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
490: PetscOptionsList(), PetscOptionsEList()
491: @*/
492: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
493: {
497: #if !defined(PETSC_USE_COMPLEX)
498: PetscOptionsReal(opt,text,man,defaultv,value,set);
499: #else
500: PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
501: #endif
502: return(0);
503: }
505: /*
506: Publishes an AMS logical field (with the default value in it) and with a name
507: given by the text string
508: */
511: /*@C
512: PetscOptionsName - Determines if a particular option is in the database
514: Collective on the communicator passed in PetscOptionsBegin()
516: Input Parameters:
517: + opt - option name
518: . text - short string that describes the option
519: - man - manual page with additional information on option
521: Output Parameter:
522: . flg - PETSC_TRUE if found, else PETSC_FALSE
524: Level: beginner
526: Concepts: options database^has int
528: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
530: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
531: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
532: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
533: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
534: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
535: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
536: PetscOptionsList(), PetscOptionsEList()
537: @*/
538: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
539: {
543: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
544: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
545: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
546: }
547: return(0);
548: }
552: /*@C
553: PetscOptionsList - Puts a list of option values that a single one may be selected from
555: Collective on the communicator passed in PetscOptionsBegin()
557: Input Parameters:
558: + opt - option name
559: . text - short string that describes the option
560: . man - manual page with additional information on option
561: . list - the possible choices
562: - defaultv - the default (current) value
564: Output Parameter:
565: + value - the value to return
566: - set - PETSC_TRUE if found, else PETSC_FALSE
568: Level: intermediate
569:
570: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
572: See PetscOptionsEList() for when the choices are given in a string array
574: To get a listing of all currently specified options,
575: see PetscOptionsPrint() or PetscOptionsGetAll()
577: Concepts: options database^list
579: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
580: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
581: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
582: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
583: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
584: PetscOptionsList(), PetscOptionsEList()
585: @*/
586: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
587: {
591: PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
592: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
593: PetscFListPrintTypes(list,PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man);
594: }
595: return(0);
596: }
600: /*@C
601: PetscOptionsEList - Puts a list of option values that a single one may be selected from
603: Collective on the communicator passed in PetscOptionsBegin()
605: Input Parameters:
606: + opt - option name
607: . ltext - short string that describes the option
608: . man - manual page with additional information on option
609: . list - the possible choices
610: . ntext - number of choices
611: - defaultv - the default (current) value
613: Output Parameter:
614: + value - the index of the value to return
615: - set - PETSC_TRUE if found, else PETSC_FALSE
616:
617: Level: intermediate
619: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
621: See PetscOptionsList() for when the choices are given in a PetscFList()
623: Concepts: options database^list
625: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
626: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
627: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
628: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
629: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
630: PetscOptionsList(), PetscOptionsEList()
631: @*/
632: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
633: {
635: PetscInt i;
638: PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
639: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
640: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
641: for (i=0; i<ntext; i++){
642: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
643: }
644: (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
645: }
646: return(0);
647: }
651: /*@C
652: PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
653: which only a single value can be true.
655: Collective on the communicator passed in PetscOptionsBegin()
657: Input Parameters:
658: + opt - option name
659: . text - short string that describes the option
660: - man - manual page with additional information on option
662: Output Parameter:
663: . flg - whether that option was set or not
664:
665: Level: intermediate
667: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
669: Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()
671: Concepts: options database^logical group
673: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
674: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
675: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
676: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
677: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
678: PetscOptionsList(), PetscOptionsEList()
679: @*/
680: PetscErrorCode PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
681: {
685: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
686: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
687: (*PetscHelpPrintf)(PetscOptionsObject.comm," Pick at most one of -------------\n");
688: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
689: }
690: return(0);
691: }
695: /*@C
696: PetscOptionsTruthGroup - One in a series of logical queries on the options database for
697: which only a single value can be true.
699: Collective on the communicator passed in PetscOptionsBegin()
701: Input Parameters:
702: + opt - option name
703: . text - short string that describes the option
704: - man - manual page with additional information on option
706: Output Parameter:
707: . flg - PETSC_TRUE if found, else PETSC_FALSE
708:
709: Level: intermediate
711: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
713: Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()
715: Concepts: options database^logical group
717: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
718: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
719: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
720: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
721: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
722: PetscOptionsList(), PetscOptionsEList()
723: @*/
724: PetscErrorCode PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
725: {
729: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
730: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
731: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
732: }
733: return(0);
734: }
738: /*@C
739: PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
740: which only a single value can be true.
742: Collective on the communicator passed in PetscOptionsBegin()
744: Input Parameters:
745: + opt - option name
746: . text - short string that describes the option
747: - man - manual page with additional information on option
749: Output Parameter:
750: . flg - PETSC_TRUE if found, else PETSC_FALSE
751:
752: Level: intermediate
754: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
756: Must follow a PetscOptionsTruthGroupBegin()
758: Concepts: options database^logical group
760: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
761: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
762: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
763: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
764: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
765: PetscOptionsList(), PetscOptionsEList()
766: @*/
767: PetscErrorCode PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
768: {
772: PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
773: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
774: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
775: }
776: return(0);
777: }
781: /*@C
782: PetscOptionsTruth - Determines if a particular option is in the database with a true or false
784: Collective on the communicator passed in PetscOptionsBegin()
786: Input Parameters:
787: + opt - option name
788: . text - short string that describes the option
789: - man - manual page with additional information on option
791: Output Parameter:
792: . flg - PETSC_TRUE or PETSC_FALSE
793: . set - PETSC_TRUE if found, else PETSC_FALSE
795: Level: beginner
797: Concepts: options database^logical
799: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
801: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
802: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
803: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
804: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
805: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
806: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
807: PetscOptionsList(), PetscOptionsEList()
808: @*/
809: PetscErrorCode PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
810: {
812: PetscTruth iset;
815: PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
816: if (!iset) {
817: if (flg) *flg = deflt;
818: }
819: if (set) *set = iset;
820: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
821: const char *v = PetscTruths[deflt];
822: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
823: }
824: return(0);
825: }
829: /*@C
830: PetscOptionsRealArray - Gets an array of double values for a particular
831: option in the database. The values must be separated with commas with
832: no intervening spaces.
834: Collective on the communicator passed in PetscOptionsBegin()
836: Input Parameters:
837: + opt - the option one is seeking
838: . text - short string describing option
839: . man - manual page for option
840: - nmax - maximum number of values
842: Output Parameter:
843: + value - location to copy values
844: . nmax - actual number of values found
845: - set - PETSC_TRUE if found, else PETSC_FALSE
847: Level: beginner
849: Notes:
850: The user should pass in an array of doubles
852: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
854: Concepts: options database^array of strings
856: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
857: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
858: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
859: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
860: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
861: PetscOptionsList(), PetscOptionsEList()
862: @*/
863: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
864: {
866: PetscInt i;
869: PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
870: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
871: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
872: for (i=1; i<*n; i++) {
873: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
874: }
875: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
876: }
877: return(0);
878: }
883: /*@C
884: PetscOptionsIntArray - Gets an array of integers for a particular
885: option in the database. The values must be separated with commas with
886: no intervening spaces.
888: Collective on the communicator passed in PetscOptionsBegin()
890: Input Parameters:
891: + opt - the option one is seeking
892: . text - short string describing option
893: . man - manual page for option
894: - n - maximum number of values
896: Output Parameter:
897: + value - location to copy values
898: . n - actual number of values found
899: - set - PETSC_TRUE if found, else PETSC_FALSE
901: Level: beginner
903: Notes:
904: The user should pass in an array of integers
906: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
908: Concepts: options database^array of strings
910: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
911: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
912: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
913: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
914: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
915: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
916: @*/
917: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
918: {
920: PetscInt i;
923: PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
924: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
925: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
926: for (i=1; i<*n; i++) {
927: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
928: }
929: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
930: }
931: return(0);
932: }
936: /*@C
937: PetscOptionsStringArray - Gets an array of string values for a particular
938: option in the database. The values must be separated with commas with
939: no intervening spaces.
941: Collective on the communicator passed in PetscOptionsBegin()
943: Input Parameters:
944: + opt - the option one is seeking
945: . text - short string describing option
946: . man - manual page for option
947: - nmax - maximum number of strings
949: Output Parameter:
950: + value - location to copy strings
951: . nmax - actual number of strings found
952: - set - PETSC_TRUE if found, else PETSC_FALSE
954: Level: beginner
956: Notes:
957: The user should pass in an array of pointers to char, to hold all the
958: strings returned by this function.
960: The user is responsible for deallocating the strings that are
961: returned. The Fortran interface for this routine is not supported.
963: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
965: Concepts: options database^array of strings
967: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
968: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
969: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
970: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
971: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
972: PetscOptionsList(), PetscOptionsEList()
973: @*/
974: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
975: {
979: PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
980: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
981: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
982: }
983: return(0);
984: }
988: /*@C
989: PetscOptionsTruthArray - Gets an array of logical values (true or false) for a particular
990: option in the database. The values must be separated with commas with
991: no intervening spaces.
993: Collective on the communicator passed in PetscOptionsBegin()
995: Input Parameters:
996: + opt - the option one is seeking
997: . text - short string describing option
998: . man - manual page for option
999: - nmax - maximum number of values
1001: Output Parameter:
1002: + value - location to copy values
1003: . nmax - actual number of values found
1004: - set - PETSC_TRUE if found, else PETSC_FALSE
1006: Level: beginner
1008: Notes:
1009: The user should pass in an array of doubles
1011: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1013: Concepts: options database^array of strings
1015: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1016: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1017: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1018: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1019: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1020: PetscOptionsList(), PetscOptionsEList()
1021: @*/
1022: PetscErrorCode PetscOptionsTruthArray(const char opt[],const char text[],const char man[],PetscTruth value[],PetscInt *n,PetscTruth *set)
1023: {
1025: PetscInt i;
1028: PetscOptionsGetTruthArray(PetscOptionsObject.prefix,opt,value,n,set);
1029: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1030: (*PetscHelpPrintf)(PetscOptionsObject.comm," -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1031: for (i=1; i<*n; i++) {
1032: (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1033: }
1034: (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
1035: }
1036: return(0);
1037: }
1042: /*@C
1043: PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1044: in KSPSetFromOptions_GMRES().
1046: Collective on the communicator passed in PetscOptionsBegin()
1048: Input Parameter:
1049: . head - the heading text
1051:
1052: Level: intermediate
1054: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1056: Can be followed by a call to PetscOptionsTail() in the same function.
1058: Concepts: options database^subheading
1060: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1061: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1062: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1063: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1064: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1065: PetscOptionsList(), PetscOptionsEList()
1066: @*/
1067: PetscErrorCode PetscOptionsHead(const char head[])
1068: {
1072: if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1073: (*PetscHelpPrintf)(PetscOptionsObject.comm," %s\n",head);
1074: }
1075: return(0);
1076: }