Actual source code: petscoptions.h
1: /*
2: Routines to determine options set in the options database.
3: */
6: #include petscsys.h
9: EXTERN PetscErrorCode PetscOptionsHasName(const char[],const char[],PetscTruth*);
10: PetscPolymorphicSubroutine(PetscOptionsHasName,(const char b[],PetscTruth *f),(PETSC_NULL,b,f))
11: EXTERN PetscErrorCode PetscOptionsGetInt(const char[],const char [],PetscInt *,PetscTruth*);
12: PetscPolymorphicSubroutine(PetscOptionsGetInt,(const char b[],PetscInt *i,PetscTruth *f),(PETSC_NULL,b,i,f))
13: EXTERN PetscErrorCode PetscOptionsGetTruth(const char[],const char [],PetscTruth *,PetscTruth*);
14: PetscPolymorphicSubroutine(PetscOptionsGetTruth,(const char b[],PetscTruth *i,PetscTruth *f),(PETSC_NULL,b,i,f))
15: EXTERN PetscErrorCode PetscOptionsGetReal(const char[],const char[],PetscReal *,PetscTruth*);
16: PetscPolymorphicSubroutine(PetscOptionsGetReal,(const char b[],PetscReal *i,PetscTruth *f),(PETSC_NULL,b,i,f))
17: EXTERN PetscErrorCode PetscOptionsGetScalar(const char[],const char[],PetscScalar *,PetscTruth*);
18: PetscPolymorphicSubroutine(PetscOptionsGetScalar,(const char b[],PetscScalar i[],PetscTruth *f),(PETSC_NULL,b,i,f))
19: EXTERN PetscErrorCode PetscOptionsGetIntArray(const char[],const char[],PetscInt[],PetscInt *,PetscTruth*);
20: PetscPolymorphicSubroutine(PetscOptionsGetIntArray,(const char b[],PetscInt i[],PetscInt *ii,PetscTruth *f),(PETSC_NULL,b,i,ii,f))
21: EXTERN PetscErrorCode PetscOptionsGetRealArray(const char[],const char[],PetscReal[],PetscInt *,PetscTruth*);
22: PetscPolymorphicSubroutine(PetscOptionsGetRealArray,(const char b[],PetscReal i[],PetscInt *ii,PetscTruth *f),(PETSC_NULL,b,i,ii,f))
23: EXTERN PetscErrorCode PetscOptionsGetTruthArray(const char[],const char[],PetscTruth[],PetscInt *,PetscTruth*);
24: PetscPolymorphicSubroutine(PetscOptionsGetTruthArray,(const char b[],PetscTruth i[],PetscInt *ii,PetscTruth *f),(PETSC_NULL,b,i,ii,f))
25: EXTERN PetscErrorCode PetscOptionsGetString(const char[],const char[],char[],size_t,PetscTruth*);
26: PetscPolymorphicSubroutine(PetscOptionsGetString,(const char b[],char i[],size_t s,PetscTruth *f),(PETSC_NULL,b,i,s,f))
27: EXTERN PetscErrorCode PetscOptionsGetStringArray(const char[],const char[],char*[],PetscInt*,PetscTruth*);
28: PetscPolymorphicSubroutine(PetscOptionsGetStringArray,(const char b[],char *i[],PetscInt *ii,PetscTruth *f),(PETSC_NULL,b,i,ii,f))
29: EXTERN PetscErrorCode PetscOptionsGetEList(const char[],const char[],const char*const*,PetscInt,PetscInt*,PetscTruth*);
30: EXTERN PetscErrorCode PetscOptionsGetEnum(const char[],const char[],const char*const*,PetscEnum*,PetscTruth*);
31: EXTERN PetscErrorCode PetscOptionsValidKey(const char[],PetscTruth*);
33: EXTERN PetscErrorCode PetscOptionsSetAlias(const char[],const char[]);
34: EXTERN PetscErrorCode PetscOptionsSetValue(const char[],const char[]);
35: EXTERN PetscErrorCode PetscOptionsClearValue(const char[]);
37: EXTERN PetscErrorCode PetscOptionsAllUsed(int*);
38: EXTERN PetscErrorCode PetscOptionsLeft(void);
39: EXTERN PetscErrorCode PetscOptionsPrint(FILE *);
41: EXTERN PetscErrorCode PetscOptionsCreate(void);
42: EXTERN PetscErrorCode PetscOptionsInsert(int*,char ***,const char[]);
43: EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm,const char[],PetscTruth);
44: EXTERN PetscErrorCode PetscOptionsInsertString(const char[]);
45: EXTERN PetscErrorCode PetscOptionsDestroy(void);
46: EXTERN PetscErrorCode PetscOptionsClear(void);
48: EXTERN PetscErrorCode PetscOptionsReject(const char[],const char[]);
49: EXTERN PetscErrorCode PetscOptionsGetAll(char*[]);
51: EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm,const char[],char[],size_t,PetscTruth *);
52: EXTERN PetscErrorCode PetscOptionsAtoi(const char[],PetscInt*);
53: EXTERN PetscErrorCode PetscOptionsAtod(const char[],PetscReal*);
55: EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], void*), void *, PetscErrorCode (*)(void*));
56: EXTERN PetscErrorCode PetscOptionsMonitorCancel(void);
57: EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], void *);
62: /*MC
63: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
64: displayed on the same window of a GUI that allows the user to set the options interactively.
66: Synopsis: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
68: Collective on MPI_Comm
70: Input Parameters:
71: + comm - communicator that shares GUI
72: . prefix - options prefix for all options displayed on window
73: . title - short descriptive text, for example "Krylov Solver Options"
74: - mansec - section of manual pages for options, for example KSP
76: Level: intermediate
78: Notes: Needs to be ended by a call the PetscOptionsEnd()
79: Can add subheadings with PetscOptionsHead()
81: Developer notes: PetscOptionsPublish is set in PetscOptionsCheckInitial_Private() with -options_gui. When PetscOptionsPublish is set the
82: $ loop between PetscOptionsBegin() and PetscOptionsEnd() is run THREE times with PetscOptionsPublishCount of values -1,0,1 otherwise
83: $ the loop is run ONCE with a PetscOptionsPublishCount of 1.
84: $ = -1 : The PetscOptionsInt() etc just call the PetscOptionsGetInt() etc
85: $ = 0 : The GUI objects are created in PetscOptionsInt() etc and displayed in PetscOptionsEnd() and the options
86: $ database updated updated with user changes; PetscOptionsGetInt() etc are also called
87: $ = 1 : The PetscOptionsInt() etc again call the PetscOptionsGetInt() etc (possibly getting new values), in addition the help message and
88: $ default values are printed if -help was given.
89: $ When PetscOptionsObject.changedmethod is set this causes PetscOptionsPublishCount to be reset to -2 (so in the next loop iteration it is -1)
90: $ and the whole process is repeated. This is to handle when, for example, the KSPType is changed thus changing the list of
91: $ options available so they need to be redisplayed so the user can change the. Chaning PetscOptionsObjects.changedmethod is never
92: $ currently set.
95: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
96: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
97: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
98: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
99: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
100: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
101: PetscOptionsList(), PetscOptionsEList()
103: M*/
104: #define PetscOptionsBegin(comm,prefix,mess,sec) 0; {\
105: for (PetscOptionsPublishCount=(PetscOptionsPublish?-1:1); PetscOptionsPublishCount<2; PetscOptionsPublishCount++) {\
106: PetscErrorCode _5_PetscOptionsBegin_Private(comm,prefix,mess,sec);CHKERRQ(_5_ierr);
108: /*MC
109: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
110: displayed on the same window of a GUI that allows the user to set the options interactively.
112: Collective on the MPI_Comm used in PetscOptionsBegin()
114: Synopsis: PetscErrorCode PetscOptionsEnd(void)
116: Level: intermediate
118: Notes: Needs to be preceded by a call to PetscOptionsBegin()
120: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
121: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
122: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
123: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
124: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
125: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
126: PetscOptionsList(), PetscOptionsEList()
128: M*/
129: #define PetscOptionsEnd() _5_PetscOptionsEnd_Private();CHKERRQ(_5_ierr);}}
131: EXTERN PetscErrorCode PetscOptionsBegin_Private(MPI_Comm,const char[],const char[],const char[]);
132: EXTERN PetscErrorCode PetscOptionsEnd_Private(void);
133: EXTERN PetscErrorCode PetscOptionsHead(const char[]);
135: /*MC
136: PetscOptionsTail - Ends a section of options begun with PetscOptionsHead()
137: See, for example, KSPSetFromOptions_GMRES().
139: Collective on the communicator passed in PetscOptionsBegin()
141: Synopsis: PetscErrorCode PetscOptionsTail(void)
143: Level: intermediate
145: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
147: Must be preceded by a call to PetscOptionsHead() in the same function.
149: This needs to be used only if the code below PetscOptionsTail() can be run ONLY once.
150: See, for example, PCSetFromOptions_Composite(). This is a return(0) in it for early exit
151: from the function.
153: This is only for use with the PETSc options GUI; which does not currently exist.
155: Concepts: options database^subheading
157: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
158: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
159: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
160: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
161: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
162: PetscOptionsList(), PetscOptionsEList(), PetscOptionsEnum()
163: M*/
164: #define PetscOptionsTail() 0; {if (PetscOptionsPublishCount != 1) return(0);}
166: EXTERN PetscErrorCode PetscOptionsEnum(const char[],const char[],const char[],const char *const*,PetscEnum,PetscEnum*,PetscTruth*);
167: EXTERN PetscErrorCode PetscOptionsInt(const char[],const char[],const char[],PetscInt,PetscInt*,PetscTruth*);
168: EXTERN PetscErrorCode PetscOptionsReal(const char[],const char[],const char[],PetscReal,PetscReal*,PetscTruth*);
169: EXTERN PetscErrorCode PetscOptionsScalar(const char[],const char[],const char[],PetscScalar,PetscScalar*,PetscTruth*);
170: EXTERN PetscErrorCode PetscOptionsName(const char[],const char[],const char[],PetscTruth*);
171: EXTERN PetscErrorCode PetscOptionsString(const char[],const char[],const char[],const char[],char*,size_t,PetscTruth*);
172: EXTERN PetscErrorCode PetscOptionsTruth(const char[],const char[],const char[],PetscTruth,PetscTruth*,PetscTruth*);
173: EXTERN PetscErrorCode PetscOptionsTruthGroupBegin(const char[],const char[],const char[],PetscTruth*);
174: EXTERN PetscErrorCode PetscOptionsTruthGroup(const char[],const char[],const char[],PetscTruth*);
175: EXTERN PetscErrorCode PetscOptionsTruthGroupEnd(const char[],const char[],const char[],PetscTruth*);
176: EXTERN PetscErrorCode PetscOptionsList(const char[],const char[],const char[],PetscFList,const char[],char[],size_t,PetscTruth*);
177: EXTERN PetscErrorCode PetscOptionsEList(const char[],const char[],const char[],const char*const*,PetscInt,const char[],PetscInt*,PetscTruth*);
178: EXTERN PetscErrorCode PetscOptionsRealArray(const char[],const char[],const char[],PetscReal[],PetscInt*,PetscTruth*);
179: EXTERN PetscErrorCode PetscOptionsIntArray(const char[],const char[],const char[],PetscInt[],PetscInt*,PetscTruth*);
180: EXTERN PetscErrorCode PetscOptionsStringArray(const char[],const char[],const char[],char*[],PetscInt*,PetscTruth*);
181: EXTERN PetscErrorCode PetscOptionsTruthArray(const char[],const char[],const char[],PetscTruth[],PetscInt*,PetscTruth*);
183: EXTERN PetscErrorCode PetscOptionsSetFromOptions(void);
186: /*
187: See manual page for PetscOptionsBegin()
188: */
189: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD,OPTION_INT_ARRAY} PetscOptionType;
190: typedef struct _p_PetscOptions* PetscOptions;
191: struct _p_PetscOptions {
192: char *option;
193: char *text;
194: void *data; /* used to hold the default value and then any value it is changed to by GUI */
195: PetscFList flist; /* used for available values for PetscOptionsList() */
196: char *man;
197: size_t arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc) */
198: PetscTruth set; /* the user has changed this value in the GUI */
199: PetscOptionType type;
200: PetscOptions next;
201: };
203: typedef struct {
204: PetscOptions next;
205: char *prefix,*mprefix;
206: char *title;
207: MPI_Comm comm;
208: PetscTruth printhelp,changedmethod,alreadyprinted;
209: } PetscOptionsObjectType;
210: #endif