Actual source code: aoptions.c
1: /*
2: Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
3: GUI code to display the options and get values from the users.
5: */
7: #include <petsc/private/petscimpl.h>
8: #include <petscviewer.h>
10: #define ManSection(str) ((str) ? (str) : "None")
12: /*
13: Keep a linked list of options that have been posted and we are waiting for
14: user selection. See the manual page for PetscOptionsBegin()
16: Eventually we'll attach this beast to a MPI_Comm
17: */
19: /*
20: Handles setting up the data structure in a call to PetscOptionsBegin()
21: */
22: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject, MPI_Comm comm, const char prefix[], const char title[], const char mansec[])
23: {
24: PetscFunctionBegin;
28: if (!PetscOptionsObject->alreadyprinted) {
29: if (!PetscOptionsHelpPrintedSingleton) PetscCall(PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton));
30: PetscCall(PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton, prefix, title, &PetscOptionsObject->alreadyprinted));
31: }
32: PetscOptionsObject->next = NULL;
33: PetscOptionsObject->comm = comm;
34: PetscOptionsObject->changedmethod = PETSC_FALSE;
36: PetscCall(PetscStrallocpy(prefix, &PetscOptionsObject->prefix));
37: PetscCall(PetscStrallocpy(title, &PetscOptionsObject->title));
39: PetscCall(PetscOptionsHasHelp(PetscOptionsObject->options, &PetscOptionsObject->printhelp));
40: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
41: if (!PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(comm, "----------------------------------------\n%s:\n", title));
42: }
43: PetscFunctionReturn(PETSC_SUCCESS);
44: }
46: /*
47: Handles setting up the data structure in a call to PetscObjectOptionsBegin()
48: */
49: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj, PetscOptionItems *PetscOptionsObject)
50: {
51: char title[256];
52: PetscBool flg;
54: PetscFunctionBegin;
57: PetscOptionsObject->object = obj;
58: PetscOptionsObject->alreadyprinted = obj->optionsprinted;
60: PetscCall(PetscStrcmp(obj->description, obj->class_name, &flg));
61: if (flg) PetscCall(PetscSNPrintf(title, sizeof(title), "%s options", obj->class_name));
62: else PetscCall(PetscSNPrintf(title, sizeof(title), "%s (%s) options", obj->description, obj->class_name));
63: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, obj->comm, obj->prefix, title, obj->mansec));
64: PetscFunctionReturn(PETSC_SUCCESS);
65: }
67: /*
68: Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
69: */
70: static PetscErrorCode PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscOptionType t, PetscOptionItem *amsopt)
71: {
72: PetscOptionItem next;
73: PetscBool valid;
75: PetscFunctionBegin;
76: PetscCall(PetscOptionsValidKey(opt, &valid));
77: PetscCheck(valid, PETSC_COMM_WORLD, PETSC_ERR_ARG_INCOMP, "The option '%s' is not a valid key", opt);
79: PetscCall(PetscNew(amsopt));
80: (*amsopt)->next = NULL;
81: (*amsopt)->set = PETSC_FALSE;
82: (*amsopt)->type = t;
83: (*amsopt)->data = NULL;
85: PetscCall(PetscStrallocpy(text, &(*amsopt)->text));
86: PetscCall(PetscStrallocpy(opt, &(*amsopt)->option));
87: PetscCall(PetscStrallocpy(man, &(*amsopt)->man));
89: if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
90: else {
91: next = PetscOptionsObject->next;
92: while (next->next) next = next->next;
93: next->next = *amsopt;
94: }
95: PetscFunctionReturn(PETSC_SUCCESS);
96: }
98: /*
99: PetscScanString - Gets user input via stdin from process and broadcasts to all processes
101: Collective
103: Input Parameters:
104: + commm - communicator for the broadcast, must be PETSC_COMM_WORLD
105: . n - length of the string, must be the same on all processes
106: - str - location to store input
108: Bugs:
109: . Assumes process 0 of the given communicator has access to stdin
111: */
112: static PetscErrorCode PetscScanString(MPI_Comm comm, size_t n, char str[])
113: {
114: PetscMPIInt rank, nm;
116: PetscFunctionBegin;
117: PetscCallMPI(MPI_Comm_rank(comm, &rank));
118: if (rank == 0) {
119: char c = (char)getchar();
120: size_t i = 0;
122: while (c != '\n' && i < n - 1) {
123: str[i++] = c;
124: c = (char)getchar();
125: }
126: str[i] = 0;
127: }
128: PetscCall(PetscMPIIntCast(n, &nm));
129: PetscCallMPI(MPI_Bcast(str, nm, MPI_CHAR, 0, comm));
130: PetscFunctionReturn(PETSC_SUCCESS);
131: }
133: /*
134: This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
135: */
136: static PetscErrorCode PetscStrdup(const char s[], char *t[])
137: {
138: char *tmp = NULL;
140: PetscFunctionBegin;
141: if (s) {
142: size_t len;
144: PetscCall(PetscStrlen(s, &len));
145: tmp = (char *)malloc((len + 1) * sizeof(*tmp));
146: PetscCheck(tmp, PETSC_COMM_SELF, PETSC_ERR_MEM, "No memory to duplicate string");
147: PetscCall(PetscStrcpy(tmp, s));
148: }
149: *t = tmp;
150: PetscFunctionReturn(PETSC_SUCCESS);
151: }
153: /*
154: PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime
156: Notes:
157: this isn't really practical, it is just to demonstrate the principle
159: A carriage return indicates no change from the default; but this like -ksp_monitor <stdout> the default is actually not stdout the default
160: is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?
162: Bugs:
163: + All processes must traverse through the exact same set of option queries due to the call to PetscScanString()
164: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
165: - Only works for PetscInt == int, PetscReal == double etc
167: Developer Note:
168: Normally the GUI that presents the options the user and retrieves the values would be running in a different
169: address space and communicating with the PETSc program
171: */
172: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
173: {
174: PetscOptionItem next = PetscOptionsObject->next;
175: char str[512];
176: PetscBool bid;
177: PetscReal ir, *valr;
178: PetscInt *vald;
179: size_t i;
181: PetscFunctionBegin;
182: PetscCall((*PetscPrintf)(PETSC_COMM_WORLD, "%s --------------------\n", PetscOptionsObject->title));
183: while (next) {
184: switch (next->type) {
185: case OPTION_HEAD:
186: break;
187: case OPTION_INT_ARRAY:
188: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1));
189: vald = (PetscInt *)next->data;
190: for (i = 0; i < next->arraylength; i++) {
191: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "%" PetscInt_FMT, vald[i]));
192: if (i < next->arraylength - 1) PetscCall(PetscPrintf(PETSC_COMM_WORLD, ","));
193: }
194: PetscCall(PetscPrintf(PETSC_COMM_WORLD, ">: %s (%s) ", next->text, next->man));
195: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
196: if (str[0]) {
197: PetscToken token;
198: PetscInt n = 0, nmax = next->arraylength, *dvalue = (PetscInt *)next->data, start, end;
199: size_t len;
200: char *value;
201: PetscBool foundrange;
203: next->set = PETSC_TRUE;
204: value = str;
205: PetscCall(PetscTokenCreate(value, ',', &token));
206: PetscCall(PetscTokenFind(token, &value));
207: while (n < nmax) {
208: if (!value) break;
210: /* look for form d-D where d and D are integers */
211: foundrange = PETSC_FALSE;
212: PetscCall(PetscStrlen(value, &len));
213: if (value[0] == '-') i = 2;
214: else i = 1;
215: for (; i < len; i++) {
216: if (value[i] == '-') {
217: PetscCheck(i != len - 1, PETSC_COMM_SELF, PETSC_ERR_USER, "Error in %" PetscInt_FMT "-th array entry %s", n, value);
218: value[i] = 0;
219: PetscCall(PetscOptionsStringToInt(value, &start));
220: PetscCall(PetscOptionsStringToInt(value + i + 1, &end));
221: PetscCheck(end > start, PETSC_COMM_SELF, PETSC_ERR_USER, "Error in %" PetscInt_FMT "-th array entry, %s-%s cannot have decreasing list", n, value, value + i + 1);
222: PetscCheck(n + end - start - 1 < nmax, PETSC_COMM_SELF, PETSC_ERR_USER, "Error in %" PetscInt_FMT "-th array entry, not enough space in left in array (%" PetscInt_FMT ") to contain entire range from %" PetscInt_FMT " to %" PetscInt_FMT, n, nmax - n, start, end);
223: for (; start < end; start++) {
224: *dvalue = start;
225: dvalue++;
226: n++;
227: }
228: foundrange = PETSC_TRUE;
229: break;
230: }
231: }
232: if (!foundrange) {
233: PetscCall(PetscOptionsStringToInt(value, dvalue));
234: dvalue++;
235: n++;
236: }
237: PetscCall(PetscTokenFind(token, &value));
238: }
239: PetscCall(PetscTokenDestroy(&token));
240: }
241: break;
242: case OPTION_REAL_ARRAY:
243: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1));
244: valr = (PetscReal *)next->data;
245: for (i = 0; i < next->arraylength; i++) {
246: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "%g", (double)valr[i]));
247: if (i < next->arraylength - 1) PetscCall(PetscPrintf(PETSC_COMM_WORLD, ","));
248: }
249: PetscCall(PetscPrintf(PETSC_COMM_WORLD, ">: %s (%s) ", next->text, next->man));
250: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
251: if (str[0]) {
252: PetscToken token;
253: PetscInt n = 0, nmax = next->arraylength;
254: PetscReal *dvalue = (PetscReal *)next->data;
255: char *value;
257: next->set = PETSC_TRUE;
258: value = str;
259: PetscCall(PetscTokenCreate(value, ',', &token));
260: PetscCall(PetscTokenFind(token, &value));
261: while (n < nmax) {
262: if (!value) break;
263: PetscCall(PetscOptionsStringToReal(value, dvalue));
264: dvalue++;
265: n++;
266: PetscCall(PetscTokenFind(token, &value));
267: }
268: PetscCall(PetscTokenDestroy(&token));
269: }
270: break;
271: case OPTION_INT:
272: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <%d>: %s (%s) ", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, *(int *)next->data, next->text, next->man));
273: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
274: if (str[0]) {
275: #if defined(PETSC_SIZEOF_LONG_LONG)
276: long long lid;
277: sscanf(str, "%lld", &lid);
278: PetscCheck(lid <= PETSC_MAX_INT && lid >= PETSC_MIN_INT, PETSC_COMM_WORLD, PETSC_ERR_ARG_OUTOFRANGE, "Argument: -%s%s %lld", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, lid);
279: #else
280: long lid;
281: sscanf(str, "%ld", &lid);
282: PetscCheck(lid <= PETSC_MAX_INT && lid >= PETSC_MIN_INT, PETSC_COMM_WORLD, PETSC_ERR_ARG_OUTOFRANGE, "Argument: -%s%s %ld", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, lid);
283: #endif
285: next->set = PETSC_TRUE;
286: *((PetscInt *)next->data) = (PetscInt)lid;
287: }
288: break;
289: case OPTION_REAL:
290: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <%g>: %s (%s) ", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, *(double *)next->data, next->text, next->man));
291: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
292: if (str[0]) {
293: #if defined(PETSC_USE_REAL_SINGLE)
294: sscanf(str, "%e", &ir);
295: #elif defined(PETSC_USE_REAL___FP16)
296: float irtemp;
297: sscanf(str, "%e", &irtemp);
298: ir = irtemp;
299: #elif defined(PETSC_USE_REAL_DOUBLE)
300: sscanf(str, "%le", &ir);
301: #elif defined(PETSC_USE_REAL___FLOAT128)
302: ir = strtoflt128(str, 0);
303: #else
304: SETERRQ(PETSC_COMM_SELF, PETSC_ERR_LIB, "Unknown scalar type");
305: #endif
306: next->set = PETSC_TRUE;
307: *((PetscReal *)next->data) = ir;
308: }
309: break;
310: case OPTION_BOOL:
311: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <%s>: %s (%s) ", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, *(PetscBool *)next->data ? "true" : "false", next->text, next->man));
312: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
313: if (str[0]) {
314: PetscCall(PetscOptionsStringToBool(str, &bid));
315: next->set = PETSC_TRUE;
316: *((PetscBool *)next->data) = bid;
317: }
318: break;
319: case OPTION_STRING:
320: PetscCall(PetscPrintf(PETSC_COMM_WORLD, "-%s%s <%s>: %s (%s) ", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", next->option + 1, (char *)next->data, next->text, next->man));
321: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
322: if (str[0]) {
323: next->set = PETSC_TRUE;
324: /* must use system malloc since SAWs may free this */
325: PetscCall(PetscStrdup(str, (char **)&next->data));
326: }
327: break;
328: case OPTION_FLIST:
329: PetscCall(PetscFunctionListPrintTypes(PETSC_COMM_WORLD, stdout, PetscOptionsObject->prefix, next->option, next->text, next->man, next->flist, (char *)next->data, (char *)next->data));
330: PetscCall(PetscScanString(PETSC_COMM_WORLD, 512, str));
331: if (str[0]) {
332: PetscOptionsObject->changedmethod = PETSC_TRUE;
333: next->set = PETSC_TRUE;
334: /* must use system malloc since SAWs may free this */
335: PetscCall(PetscStrdup(str, (char **)&next->data));
336: }
337: break;
338: default:
339: break;
340: }
341: next = next->next;
342: }
343: PetscFunctionReturn(PETSC_SUCCESS);
344: }
346: #if defined(PETSC_HAVE_SAWS)
347: #include <petscviewersaws.h>
349: static int count = 0;
351: PetscErrorCode PetscOptionsSAWsDestroy(void)
352: {
353: PetscFunctionBegin;
354: PetscFunctionReturn(PETSC_SUCCESS);
355: }
357: static const char *OptionsHeader = "<head>\n"
358: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
359: "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
360: "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
361: "<script>\n"
362: "jQuery(document).ready(function() {\n"
363: "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
364: "})\n"
365: "</script>\n"
366: "</head>\n";
368: /* Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
369: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";
371: /*
372: PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs
374: Bugs:
375: + All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
376: . Internal strings have arbitrary length and string copies are not checked that they fit into string space
377: - Only works for PetscInt == int, PetscReal == double etc
379: */
380: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
381: {
382: PetscOptionItem next = PetscOptionsObject->next;
383: static int mancount = 0;
384: char options[16];
385: PetscBool changedmethod = PETSC_FALSE;
386: PetscBool stopasking = PETSC_FALSE;
387: char manname[16], textname[16];
388: char dir[1024];
390: PetscFunctionBegin;
391: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
392: PetscCall(PetscSNPrintf(options, PETSC_STATIC_ARRAY_LENGTH(options), "Options_%d", count++));
394: PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */
396: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", "_title"));
397: PetscCallSAWs(SAWs_Register, (dir, &PetscOptionsObject->title, 1, SAWs_READ, SAWs_STRING));
398: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", "prefix"));
399: PetscCallSAWs(SAWs_Register, (dir, &PetscOptionsObject->pprefix, 1, SAWs_READ, SAWs_STRING));
400: PetscCallSAWs(SAWs_Register, ("/PETSc/Options/ChangedMethod", &changedmethod, 1, SAWs_WRITE, SAWs_BOOLEAN));
401: PetscCallSAWs(SAWs_Register, ("/PETSc/Options/StopAsking", &stopasking, 1, SAWs_WRITE, SAWs_BOOLEAN));
403: while (next) {
404: PetscCall(PetscSNPrintf(manname, PETSC_STATIC_ARRAY_LENGTH(manname), "_man_%d", mancount));
405: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", manname));
406: PetscCallSAWs(SAWs_Register, (dir, &next->man, 1, SAWs_READ, SAWs_STRING));
407: PetscCall(PetscSNPrintf(textname, PETSC_STATIC_ARRAY_LENGTH(textname), "_text_%d", mancount++));
408: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", textname));
409: PetscCallSAWs(SAWs_Register, (dir, &next->text, 1, SAWs_READ, SAWs_STRING));
411: switch (next->type) {
412: case OPTION_HEAD:
413: break;
414: case OPTION_INT_ARRAY:
415: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
416: PetscCallSAWs(SAWs_Register, (dir, next->data, next->arraylength, SAWs_WRITE, SAWs_INT));
417: break;
418: case OPTION_REAL_ARRAY:
419: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
420: PetscCallSAWs(SAWs_Register, (dir, next->data, next->arraylength, SAWs_WRITE, SAWs_DOUBLE));
421: break;
422: case OPTION_INT:
423: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
424: PetscCallSAWs(SAWs_Register, (dir, next->data, 1, SAWs_WRITE, SAWs_INT));
425: break;
426: case OPTION_REAL:
427: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
428: PetscCallSAWs(SAWs_Register, (dir, next->data, 1, SAWs_WRITE, SAWs_DOUBLE));
429: break;
430: case OPTION_BOOL:
431: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
432: PetscCallSAWs(SAWs_Register, (dir, next->data, 1, SAWs_WRITE, SAWs_BOOLEAN));
433: break;
434: case OPTION_BOOL_ARRAY:
435: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
436: PetscCallSAWs(SAWs_Register, (dir, next->data, next->arraylength, SAWs_WRITE, SAWs_BOOLEAN));
437: break;
438: case OPTION_STRING:
439: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
440: PetscCallSAWs(SAWs_Register, (dir, &next->data, 1, SAWs_WRITE, SAWs_STRING));
441: break;
442: case OPTION_STRING_ARRAY:
443: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
444: PetscCallSAWs(SAWs_Register, (dir, next->data, next->arraylength, SAWs_WRITE, SAWs_STRING));
445: break;
446: case OPTION_FLIST: {
447: PetscInt ntext;
448: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
449: PetscCallSAWs(SAWs_Register, (dir, &next->data, 1, SAWs_WRITE, SAWs_STRING));
450: PetscCall(PetscFunctionListGet(next->flist, (const char ***)&next->edata, &ntext));
451: PetscCallSAWs(SAWs_Set_Legal_Variable_Values, (dir, ntext, next->edata));
452: } break;
453: case OPTION_ELIST: {
454: PetscInt ntext = next->nlist;
455: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
456: PetscCallSAWs(SAWs_Register, (dir, &next->data, 1, SAWs_WRITE, SAWs_STRING));
457: PetscCall(PetscMalloc1((ntext + 1), (char ***)&next->edata));
458: PetscCall(PetscMemcpy(next->edata, next->list, ntext * sizeof(char *)));
459: PetscCallSAWs(SAWs_Set_Legal_Variable_Values, (dir, ntext, next->edata));
460: } break;
461: default:
462: break;
463: }
464: next = next->next;
465: }
467: /* wait until accessor has unlocked the memory */
468: PetscCallSAWs(SAWs_Push_Header, ("index.html", OptionsHeader));
469: PetscCallSAWs(SAWs_Push_Body, ("index.html", 2, OptionsBodyBottom));
470: PetscCall(PetscSAWsBlock());
471: PetscCallSAWs(SAWs_Pop_Header, ("index.html"));
472: PetscCallSAWs(SAWs_Pop_Body, ("index.html", 2));
474: /* determine if any values have been set in GUI */
475: next = PetscOptionsObject->next;
476: while (next) {
477: PetscCall(PetscSNPrintf(dir, 1024, "/PETSc/Options/%s", next->option));
478: PetscCallSAWs(SAWs_Selected, (dir, (int *)&next->set));
479: next = next->next;
480: }
482: /* reset counter to -2; this updates the screen with the new options for the selected method */
483: if (changedmethod) PetscOptionsObject->count = -2;
485: if (stopasking) {
486: PetscOptionsPublish = PETSC_FALSE;
487: PetscOptionsObject->count = 0; //do not ask for same thing again
488: }
490: PetscCallSAWs(SAWs_Delete, ("/PETSc/Options"));
491: PetscFunctionReturn(PETSC_SUCCESS);
492: }
493: #endif
495: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
496: {
497: PetscOptionItem last;
498: char option[256], value[1024], tmp[32];
499: size_t j;
501: PetscFunctionBegin;
502: if (PetscOptionsObject->next) {
503: if (!PetscOptionsObject->count) {
504: #if defined(PETSC_HAVE_SAWS)
505: PetscCall(PetscOptionsSAWsInput(PetscOptionsObject));
506: #else
507: PetscCall(PetscOptionsGetFromTextInput(PetscOptionsObject));
508: #endif
509: }
510: }
512: PetscCall(PetscFree(PetscOptionsObject->title));
514: /* reset counter to -2; this updates the screen with the new options for the selected method */
515: if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
516: /* reset alreadyprinted flag */
517: PetscOptionsObject->alreadyprinted = PETSC_FALSE;
518: if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
519: PetscOptionsObject->object = NULL;
521: while (PetscOptionsObject->next) {
522: if (PetscOptionsObject->next->set) {
523: if (PetscOptionsObject->prefix) {
524: PetscCall(PetscStrcpy(option, "-"));
525: PetscCall(PetscStrcat(option, PetscOptionsObject->prefix));
526: PetscCall(PetscStrcat(option, PetscOptionsObject->next->option + 1));
527: } else PetscCall(PetscStrcpy(option, PetscOptionsObject->next->option));
529: switch (PetscOptionsObject->next->type) {
530: case OPTION_HEAD:
531: break;
532: case OPTION_INT_ARRAY:
533: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%d", (int)((PetscInt *)PetscOptionsObject->next->data)[0]));
534: for (j = 1; j < PetscOptionsObject->next->arraylength; j++) {
535: PetscCall(PetscSNPrintf(tmp, PETSC_STATIC_ARRAY_LENGTH(tmp), "%d", (int)((PetscInt *)PetscOptionsObject->next->data)[j]));
536: PetscCall(PetscStrcat(value, ","));
537: PetscCall(PetscStrcat(value, tmp));
538: }
539: break;
540: case OPTION_INT:
541: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%d", (int)*(PetscInt *)PetscOptionsObject->next->data));
542: break;
543: case OPTION_REAL:
544: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%g", (double)*(PetscReal *)PetscOptionsObject->next->data));
545: break;
546: case OPTION_REAL_ARRAY:
547: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%g", (double)((PetscReal *)PetscOptionsObject->next->data)[0]));
548: for (j = 1; j < PetscOptionsObject->next->arraylength; j++) {
549: PetscCall(PetscSNPrintf(tmp, PETSC_STATIC_ARRAY_LENGTH(tmp), "%g", (double)((PetscReal *)PetscOptionsObject->next->data)[j]));
550: PetscCall(PetscStrcat(value, ","));
551: PetscCall(PetscStrcat(value, tmp));
552: }
553: break;
554: case OPTION_SCALAR_ARRAY:
555: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%g+%gi", (double)PetscRealPart(((PetscScalar *)PetscOptionsObject->next->data)[0]), (double)PetscImaginaryPart(((PetscScalar *)PetscOptionsObject->next->data)[0])));
556: for (j = 1; j < PetscOptionsObject->next->arraylength; j++) {
557: PetscCall(PetscSNPrintf(tmp, PETSC_STATIC_ARRAY_LENGTH(tmp), "%g+%gi", (double)PetscRealPart(((PetscScalar *)PetscOptionsObject->next->data)[j]), (double)PetscImaginaryPart(((PetscScalar *)PetscOptionsObject->next->data)[j])));
558: PetscCall(PetscStrcat(value, ","));
559: PetscCall(PetscStrcat(value, tmp));
560: }
561: break;
562: case OPTION_BOOL:
563: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%d", *(int *)PetscOptionsObject->next->data));
564: break;
565: case OPTION_BOOL_ARRAY:
566: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%d", (int)((PetscBool *)PetscOptionsObject->next->data)[0]));
567: for (j = 1; j < PetscOptionsObject->next->arraylength; j++) {
568: PetscCall(PetscSNPrintf(tmp, PETSC_STATIC_ARRAY_LENGTH(tmp), "%d", (int)((PetscBool *)PetscOptionsObject->next->data)[j]));
569: PetscCall(PetscStrcat(value, ","));
570: PetscCall(PetscStrcat(value, tmp));
571: }
572: break;
573: case OPTION_FLIST:
574: PetscCall(PetscStrcpy(value, (char *)PetscOptionsObject->next->data));
575: break;
576: case OPTION_ELIST:
577: PetscCall(PetscStrcpy(value, (char *)PetscOptionsObject->next->data));
578: break;
579: case OPTION_STRING:
580: PetscCall(PetscStrcpy(value, (char *)PetscOptionsObject->next->data));
581: break;
582: case OPTION_STRING_ARRAY:
583: PetscCall(PetscSNPrintf(value, PETSC_STATIC_ARRAY_LENGTH(value), "%s", ((char **)PetscOptionsObject->next->data)[0]));
584: for (j = 1; j < PetscOptionsObject->next->arraylength; j++) {
585: PetscCall(PetscSNPrintf(tmp, PETSC_STATIC_ARRAY_LENGTH(tmp), "%s", ((char **)PetscOptionsObject->next->data)[j]));
586: PetscCall(PetscStrcat(value, ","));
587: PetscCall(PetscStrcat(value, tmp));
588: }
589: break;
590: }
591: PetscCall(PetscOptionsSetValue(PetscOptionsObject->options, option, value));
592: }
593: if (PetscOptionsObject->next->type == OPTION_ELIST) PetscCall(PetscStrNArrayDestroy(PetscOptionsObject->next->nlist, (char ***)&PetscOptionsObject->next->list));
594: PetscCall(PetscFree(PetscOptionsObject->next->text));
595: PetscCall(PetscFree(PetscOptionsObject->next->option));
596: PetscCall(PetscFree(PetscOptionsObject->next->man));
597: PetscCall(PetscFree(PetscOptionsObject->next->edata));
599: if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
600: free(PetscOptionsObject->next->data);
601: } else {
602: PetscCall(PetscFree(PetscOptionsObject->next->data));
603: }
605: last = PetscOptionsObject->next;
606: PetscOptionsObject->next = PetscOptionsObject->next->next;
607: PetscCall(PetscFree(last));
608: }
609: PetscCall(PetscFree(PetscOptionsObject->prefix));
610: PetscOptionsObject->next = NULL;
611: PetscFunctionReturn(PETSC_SUCCESS);
612: }
614: /*MC
615: PetscOptionsEnum - Gets the enum value for a particular option in the database.
617: Logically Collective on the communicator passed in `PetscOptionsBegin()`
619: Synopsis:
620: #include "petscsys.h"
621: PetscErrorCode PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool *set)
623: Input Parameters:
624: + opt - option name
625: . text - short string that describes the option
626: . man - manual page with additional information on option
627: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
628: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
629: $ PetscOptionsEnum(..., obj->value,&object->value,...) or
630: $ value = defaultvalue
631: $ PetscOptionsEnum(..., value,&value,&flg);
632: $ if (flg) {
634: Output Parameters:
635: + value - the value to return
636: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
638: Level: beginner
640: Notes:
641: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
643: list is usually something like `PCASMTypes` or some other predefined list of enum names
645: If the user does not supply the option at all value is NOT changed. Thus
646: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
648: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
650: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
651: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
652: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
653: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
654: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
655: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
656: `PetscOptionsFList()`, `PetscOptionsEList()`
657: M*/
659: PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
660: {
661: PetscInt ntext = 0;
662: PetscInt tval;
663: PetscBool tflg;
665: PetscFunctionBegin;
666: while (list[ntext++]) PetscCheck(ntext <= 50, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "List argument appears to be wrong or have more than 50 entries");
667: PetscCheck(ntext >= 3, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "List argument must have at least two entries: typename and type prefix");
668: ntext -= 3;
669: PetscCall(PetscOptionsEList_Private(PetscOptionsObject, opt, text, man, list, ntext, list[currentvalue], &tval, &tflg));
670: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
671: if (tflg) *value = (PetscEnum)tval;
672: if (set) *set = tflg;
673: PetscFunctionReturn(PETSC_SUCCESS);
674: }
676: /*MC
677: PetscOptionsEnumArray - Gets an array of enum values for a particular
678: option in the database.
680: Logically Collective on the communicator passed in `PetscOptionsBegin()`
682: Synopsis:
683: #include "petscsys.h"
684: PetscErrorCode PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool *set)
686: Input Parameters:
687: + opt - the option one is seeking
688: . text - short string describing option
689: . man - manual page for option
690: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
691: - n - maximum number of values allowed in the value array
693: Output Parameters:
694: + value - location to copy values
695: . n - actual number of values found
696: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
698: Level: beginner
700: Notes:
701: The array must be passed as a comma separated list.
703: There must be no intervening spaces between the values.
705: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
707: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
708: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
709: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
710: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
711: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
712: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRealArray()`
713: M*/
715: PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
716: {
717: PetscInt i, nlist = 0;
718: PetscOptionItem amsopt;
720: PetscFunctionBegin;
721: while (list[nlist++]) PetscCheck(nlist <= 50, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "List argument appears to be wrong or have more than 50 entries");
722: PetscCheck(nlist >= 3, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "List argument must have at least two entries: typename and type prefix");
723: nlist -= 3; /* drop enum name, prefix, and null termination */
724: if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
725: PetscEnum *vals;
726: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_INT_ARRAY /*XXX OPTION_ENUM_ARRAY*/, &amsopt));
727: PetscCall(PetscStrNArrayallocpy(nlist, list, (char ***)&amsopt->list));
728: amsopt->nlist = nlist;
729: PetscCall(PetscMalloc1(*n, (PetscEnum **)&amsopt->data));
730: amsopt->arraylength = *n;
731: vals = (PetscEnum *)amsopt->data;
732: for (i = 0; i < *n; i++) vals[i] = value[i];
733: }
734: PetscCall(PetscOptionsGetEnumArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, list, value, n, set));
735: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
736: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%s", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, list[value[0]]));
737: for (i = 1; i < *n; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ",%s", list[value[i]]));
738: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ">: %s (choose from)", text));
739: for (i = 0; i < nlist; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s", list[i]));
740: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " (%s)\n", ManSection(man)));
741: }
742: PetscFunctionReturn(PETSC_SUCCESS);
743: }
745: /*MC
746: PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.
748: Logically Collective on the communicator passed in `PetscOptionsBegin()`
750: Synopsis:
751: #include "petscsys.h"
752: PetscErrorCode PetscOptionsBoundedInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)
754: Input Parameters:
755: + opt - option name
756: . text - short string that describes the option
757: . man - manual page with additional information on option
758: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
759: .vb
760: PetscOptionsInt(..., obj->value,&obj->value,...)
761: .ve
762: or
763: .vb
764: value = defaultvalue
765: PetscOptionsInt(..., value,&value,&flg);
766: if (flg) {
767: .ve
768: - bound - the requested value should be greater than or equal this bound or an error is generated
770: Output Parameters:
771: + value - the integer value to return
772: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
774: Notes:
775: If the user does not supply the option at all value is NOT changed. Thus
776: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
778: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
780: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
782: Level: beginner
784: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
785: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
786: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
787: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
788: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
789: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
790: `PetscOptionsFList()`, `PetscOptionsEList()`
791: M*/
793: /*MC
794: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
796: Logically Collective on the communicator passed in `PetscOptionsBegin()`
798: Synopsis:
799: #include "petscsys.h"
800: PetscErrorCode PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)
802: Input Parameters:
803: + opt - option name
804: . text - short string that describes the option
805: . man - manual page with additional information on option
806: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
807: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
808: $ value = defaultvalue
809: $ PetscOptionsInt(..., value,&value,&flg);
810: $ if (flg) {
811: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
812: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
814: Output Parameters:
815: + value - the integer value to return
816: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
818: Notes:
819: If the user does not supply the option at all value is NOT changed. Thus
820: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
822: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
824: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
826: Level: beginner
828: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
829: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
830: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
831: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
832: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
833: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
834: `PetscOptionsFList()`, `PetscOptionsEList()`
835: M*/
837: /*MC
838: PetscOptionsInt - Gets the integer value for a particular option in the database.
840: Logically Collective on the communicator passed in `PetscOptionsBegin()`
842: Synopsis:
843: #include "petscsys.h"
844: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))
846: Input Parameters:
847: + opt - option name
848: . text - short string that describes the option
849: . man - manual page with additional information on option
850: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
851: $ PetscOptionsInt(..., obj->value,&obj->value,...) or
852: $ value = defaultvalue
853: $ PetscOptionsInt(..., value,&value,&flg);
854: $ if (flg) {
856: Output Parameters:
857: + value - the integer value to return
858: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
860: Notes:
861: If the user does not supply the option at all value is NOT changed. Thus
862: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
864: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
866: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
868: Level: beginner
870: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
871: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
872: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
873: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
874: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
875: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
876: `PetscOptionsFList()`, `PetscOptionsEList()`
877: M*/
879: PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
880: {
881: PetscOptionItem amsopt;
882: PetscBool wasset;
884: PetscFunctionBegin;
885: PetscCheck(currentvalue >= lb, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Current value %" PetscInt_FMT " less than allowed bound %" PetscInt_FMT, currentvalue, lb);
886: PetscCheck(currentvalue <= ub, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Current value %" PetscInt_FMT " greater than allowed bound %" PetscInt_FMT, currentvalue, ub);
887: if (!PetscOptionsObject->count) {
888: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_INT, &amsopt));
889: PetscCall(PetscMalloc(sizeof(PetscInt), &amsopt->data));
890: *(PetscInt *)amsopt->data = currentvalue;
892: PetscCall(PetscOptionsGetInt(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, ¤tvalue, &wasset));
893: if (wasset) *(PetscInt *)amsopt->data = currentvalue;
894: }
895: PetscCall(PetscOptionsGetInt(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, &wasset));
896: PetscCheck(!wasset || *value >= lb, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Newly set value %" PetscInt_FMT " less than allowed bound %" PetscInt_FMT, *value, lb);
897: PetscCheck(!wasset || *value <= ub, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Newly set value %" PetscInt_FMT " greater than allowed bound %" PetscInt_FMT, *value, ub);
898: if (set) *set = wasset;
899: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
900: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <now %" PetscInt_FMT " : formerly %" PetscInt_FMT ">: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, wasset && value ? *value : currentvalue, currentvalue, text, ManSection(man)));
901: }
902: PetscFunctionReturn(PETSC_SUCCESS);
903: }
905: /*MC
906: PetscOptionsString - Gets the string value for a particular option in the database.
908: Logically Collective on the communicator passed in `PetscOptionsBegin()`
910: Synopsis:
911: #include "petscsys.h"
912: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool *set)
914: Input Parameters:
915: + opt - option name
916: . text - short string that describes the option
917: . man - manual page with additional information on option
918: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
919: - len - length of the result string including null terminator
921: Output Parameters:
922: + value - the value to return
923: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
925: Level: beginner
927: Notes:
928: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
930: Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls).
932: If the user does not supply the option at all value is NOT changed. Thus
933: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
935: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
937: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
938: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
939: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
940: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
941: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
942: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
943: `PetscOptionsFList()`, `PetscOptionsEList()`
944: M*/
946: PetscErrorCode PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
947: {
948: PetscOptionItem amsopt;
949: PetscBool lset;
951: PetscFunctionBegin;
952: if (!PetscOptionsObject->count) {
953: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_STRING, &amsopt));
954: /* must use system malloc since SAWs may free this */
955: PetscCall(PetscStrdup(currentvalue ? currentvalue : "", (char **)&amsopt->data));
956: }
957: PetscCall(PetscOptionsGetString(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, len, &lset));
958: if (set) *set = lset;
959: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
960: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <now %s : formerly %s>: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, lset && value ? value : currentvalue, currentvalue, text, ManSection(man)));
961: }
962: PetscFunctionReturn(PETSC_SUCCESS);
963: }
965: /*MC
966: PetscOptionsReal - Gets the `PetscReal` value for a particular option in the database.
968: Logically Collective on the communicator passed in `PetscOptionsBegin()`
970: Synopsis:
971: #include "petscsys.h"
972: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool *set)
974: Input Parameters:
975: + opt - option name
976: . text - short string that describes the option
977: . man - manual page with additional information on option
978: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
979: $ PetscOptionsReal(..., obj->value,&obj->value,...) or
980: $ value = defaultvalue
981: $ PetscOptionsReal(..., value,&value,&flg);
982: $ if (flg) {
984: Output Parameters:
985: + value - the value to return
986: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
988: Notes:
989: If the user does not supply the option at all value is NOT changed. Thus
990: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
992: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
994: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
996: Level: beginner
998: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
999: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1000: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
1001: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1002: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1003: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1004: `PetscOptionsFList()`, `PetscOptionsEList()`
1005: M*/
1007: PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
1008: {
1009: PetscOptionItem amsopt;
1010: PetscBool lset;
1012: PetscFunctionBegin;
1013: if (!PetscOptionsObject->count) {
1014: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_REAL, &amsopt));
1015: PetscCall(PetscMalloc(sizeof(PetscReal), &amsopt->data));
1017: *(PetscReal *)amsopt->data = currentvalue;
1018: }
1019: PetscCall(PetscOptionsGetReal(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, &lset));
1020: if (set) *set = lset;
1021: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1022: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%g : %g>: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, lset && value ? (double)*value : (double)currentvalue, (double)currentvalue, text, ManSection(man)));
1023: }
1024: PetscFunctionReturn(PETSC_SUCCESS);
1025: }
1027: /*MC
1028: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
1030: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1032: Synopsis:
1033: #include "petscsys.h"
1034: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool *set)
1036: Input Parameters:
1037: + opt - option name
1038: . text - short string that describes the option
1039: . man - manual page with additional information on option
1040: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1041: $ PetscOptionsScalar(..., obj->value,&obj->value,...) or
1042: $ value = defaultvalue
1043: $ PetscOptionsScalar(..., value,&value,&flg);
1044: $ if (flg) {
1046: Output Parameters:
1047: + value - the value to return
1048: - flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
1050: Notes:
1051: If the user does not supply the option at all value is NOT changed. Thus
1052: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1054: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1056: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1058: Level: beginner
1060: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1061: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1062: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
1063: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1064: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1065: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1066: `PetscOptionsFList()`, `PetscOptionsEList()`
1067: M*/
1069: PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
1070: {
1071: PetscFunctionBegin;
1072: #if !defined(PETSC_USE_COMPLEX)
1073: PetscCall(PetscOptionsReal(opt, text, man, currentvalue, value, set));
1074: #else
1075: PetscCall(PetscOptionsGetScalar(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, set));
1076: #endif
1077: PetscFunctionReturn(PETSC_SUCCESS);
1078: }
1080: /*MC
1081: PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
1082: its value is set to false.
1084: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1086: Synopsis:
1087: #include "petscsys.h"
1088: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool *flg)
1090: Input Parameters:
1091: + opt - option name
1092: . text - short string that describes the option
1093: - man - manual page with additional information on option
1095: Output Parameter:
1096: . flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
1098: Level: beginner
1100: Note:
1101: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1103: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1104: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1105: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
1106: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1107: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1108: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1109: `PetscOptionsFList()`, `PetscOptionsEList()`
1110: M*/
1112: PetscErrorCode PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool *flg)
1113: {
1114: PetscOptionItem amsopt;
1116: PetscFunctionBegin;
1117: if (!PetscOptionsObject->count) {
1118: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL, &amsopt));
1119: PetscCall(PetscMalloc(sizeof(PetscBool), &amsopt->data));
1121: *(PetscBool *)amsopt->data = PETSC_FALSE;
1122: }
1123: PetscCall(PetscOptionsHasName(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, flg));
1124: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1125: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, text, ManSection(man)));
1126: }
1127: PetscFunctionReturn(PETSC_SUCCESS);
1128: }
1130: /*MC
1131: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1133: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1135: Synopsis:
1136: #include "petscsys.h"
1137: PetscErrorCode PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool *set)
1139: Input Parameters:
1140: + opt - option name
1141: . text - short string that describes the option
1142: . man - manual page with additional information on option
1143: . list - the possible choices
1144: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1145: $ PetscOptionsFlist(..., obj->value,value,len,&flg);
1146: $ if (flg) {
1147: - len - the length of the character array value
1149: Output Parameters:
1150: + value - the value to return
1151: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1153: Level: intermediate
1155: Notes:
1156: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1158: If the user does not supply the option at all value is NOT changed. Thus
1159: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1161: The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.
1163: See `PetscOptionsEList()` for when the choices are given in a string array
1165: To get a listing of all currently specified options,
1166: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1168: Developer Note:
1169: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1171: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1172: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1173: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1174: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1175: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1176: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1177: M*/
1179: PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1180: {
1181: PetscOptionItem amsopt;
1182: PetscBool lset;
1184: PetscFunctionBegin;
1185: if (!PetscOptionsObject->count) {
1186: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, ltext, man, OPTION_FLIST, &amsopt));
1187: /* must use system malloc since SAWs may free this */
1188: PetscCall(PetscStrdup(currentvalue ? currentvalue : "", (char **)&amsopt->data));
1189: amsopt->flist = list;
1190: }
1191: PetscCall(PetscOptionsGetString(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, len, &lset));
1192: if (set) *set = lset;
1193: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1194: PetscCall(PetscFunctionListPrintTypes(PetscOptionsObject->comm, stdout, PetscOptionsObject->prefix, opt, ltext, man, list, currentvalue, lset && value ? value : currentvalue));
1195: }
1196: PetscFunctionReturn(PETSC_SUCCESS);
1197: }
1199: /*MC
1200: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1202: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1204: Synopsis:
1205: #include "petscsys.h"
1206: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool *set)
1208: Input Parameters:
1209: + opt - option name
1210: . ltext - short string that describes the option
1211: . man - manual page with additional information on option
1212: . list - the possible choices (one of these must be selected, anything else is invalid)
1213: . ntext - number of choices
1214: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1215: $ PetscOptionsElist(..., obj->value,&value,&flg);
1216: $ if (flg) {
1218: Output Parameters:
1219: + value - the index of the value to return
1220: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1222: Level: intermediate
1224: Notes:
1225: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1227: If the user does not supply the option at all value is NOT changed. Thus
1228: you should ALWAYS initialize value if you access it without first checking if the set flag is true.
1230: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1232: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1233: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1234: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1235: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1236: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1237: `PetscOptionsFList()`, `PetscOptionsEnum()`
1238: M*/
1240: PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1241: {
1242: PetscInt i;
1243: PetscOptionItem amsopt;
1244: PetscBool lset;
1246: PetscFunctionBegin;
1247: if (!PetscOptionsObject->count) {
1248: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, ltext, man, OPTION_ELIST, &amsopt));
1249: /* must use system malloc since SAWs may free this */
1250: PetscCall(PetscStrdup(currentvalue ? currentvalue : "", (char **)&amsopt->data));
1251: PetscCall(PetscStrNArrayallocpy(ntext, list, (char ***)&amsopt->list));
1252: amsopt->nlist = ntext;
1253: }
1254: PetscCall(PetscOptionsGetEList(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, list, ntext, value, &lset));
1255: if (set) *set = lset;
1256: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1257: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <now %s : formerly %s> %s (choose one of)", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, lset && value ? list[*value] : currentvalue, currentvalue, ltext));
1258: for (i = 0; i < ntext; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s", list[i]));
1259: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " (%s)\n", ManSection(man)));
1260: }
1261: PetscFunctionReturn(PETSC_SUCCESS);
1262: }
1264: /*MC
1265: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1266: which at most a single value can be true.
1268: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1270: Synopsis:
1271: #include "petscsys.h"
1272: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool *flg)
1274: Input Parameters:
1275: + opt - option name
1276: . text - short string that describes the option
1277: - man - manual page with additional information on option
1279: Output Parameter:
1280: . flg - whether that option was set or not
1282: Level: intermediate
1284: Notes:
1285: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1287: Must be followed by 0 or more P`etscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1289: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1290: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1291: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1292: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1293: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1294: `PetscOptionsFList()`, `PetscOptionsEList()`
1295: M*/
1297: PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool *flg)
1298: {
1299: PetscOptionItem amsopt;
1301: PetscFunctionBegin;
1302: if (!PetscOptionsObject->count) {
1303: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL, &amsopt));
1304: PetscCall(PetscMalloc(sizeof(PetscBool), &amsopt->data));
1306: *(PetscBool *)amsopt->data = PETSC_FALSE;
1307: }
1308: *flg = PETSC_FALSE;
1309: PetscCall(PetscOptionsGetBool(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, flg, NULL));
1310: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1311: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " Pick at most one of -------------\n"));
1312: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, text, ManSection(man)));
1313: }
1314: PetscFunctionReturn(PETSC_SUCCESS);
1315: }
1317: /*MC
1318: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1319: which at most a single value can be true.
1321: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1323: Synopsis:
1324: #include "petscsys.h"
1325: PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool *flg)
1327: Input Parameters:
1328: + opt - option name
1329: . text - short string that describes the option
1330: - man - manual page with additional information on option
1332: Output Parameter:
1333: . flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
1335: Level: intermediate
1337: Notes:
1338: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1340: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1342: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1343: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1344: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1345: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1346: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1347: `PetscOptionsFList()`, `PetscOptionsEList()`
1348: M*/
1350: PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool *flg)
1351: {
1352: PetscOptionItem amsopt;
1354: PetscFunctionBegin;
1355: if (!PetscOptionsObject->count) {
1356: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL, &amsopt));
1357: PetscCall(PetscMalloc(sizeof(PetscBool), &amsopt->data));
1359: *(PetscBool *)amsopt->data = PETSC_FALSE;
1360: }
1361: *flg = PETSC_FALSE;
1362: PetscCall(PetscOptionsGetBool(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, flg, NULL));
1363: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1364: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, text, ManSection(man)));
1365: }
1366: PetscFunctionReturn(PETSC_SUCCESS);
1367: }
1369: /*MC
1370: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1371: which at most a single value can be true.
1373: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1375: Synopsis:
1376: #include "petscsys.h"
1377: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool *flg)
1379: Input Parameters:
1380: + opt - option name
1381: . text - short string that describes the option
1382: - man - manual page with additional information on option
1384: Output Parameter:
1385: . flg - `PETSC_TRUE` if found, else `PETSC_FALSE`
1387: Level: intermediate
1389: Notes:
1390: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1392: Must follow a `PetscOptionsBoolGroupBegin()`
1394: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1395: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1396: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1397: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1398: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1399: `PetscOptionsFList()`, `PetscOptionsEList()`
1400: M*/
1402: PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool *flg)
1403: {
1404: PetscOptionItem amsopt;
1406: PetscFunctionBegin;
1407: if (!PetscOptionsObject->count) {
1408: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL, &amsopt));
1409: PetscCall(PetscMalloc(sizeof(PetscBool), &amsopt->data));
1411: *(PetscBool *)amsopt->data = PETSC_FALSE;
1412: }
1413: *flg = PETSC_FALSE;
1414: PetscCall(PetscOptionsGetBool(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, flg, NULL));
1415: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1416: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, text, ManSection(man)));
1417: }
1418: PetscFunctionReturn(PETSC_SUCCESS);
1419: }
1421: /*MC
1422: PetscOptionsBool - Determines if a particular option is in the database with a true or false
1424: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1426: Synopsis:
1427: #include "petscsys.h"
1428: PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool *flg,PetscBool *set)
1430: Input Parameters:
1431: + opt - option name
1432: . text - short string that describes the option
1433: . man - manual page with additional information on option
1434: - currentvalue - the current value
1436: Output Parameters:
1437: + flg -` PETSC_TRUE` or `PETSC_FALSE`
1438: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1440: Notes:
1441: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
1442: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
1444: If the option is given, but no value is provided, then flg and set are both given the value `PETSC_TRUE`. That is -requested_bool
1445: is equivalent to -requested_bool true
1447: If the user does not supply the option at all flg is NOT changed. Thus
1448: you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.
1450: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1452: Level: beginner
1454: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1455: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1456: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1457: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1458: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1459: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1460: `PetscOptionsFList()`, `PetscOptionsEList()`
1461: M*/
1463: PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
1464: {
1465: PetscBool iset;
1466: PetscOptionItem amsopt;
1468: PetscFunctionBegin;
1469: if (!PetscOptionsObject->count) {
1470: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL, &amsopt));
1471: PetscCall(PetscMalloc(sizeof(PetscBool), &amsopt->data));
1473: *(PetscBool *)amsopt->data = currentvalue;
1474: }
1475: PetscCall(PetscOptionsGetBool(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, flg, &iset));
1476: if (set) *set = iset;
1477: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1478: const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1479: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s: <%s : %s> %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, v, vn, text, ManSection(man)));
1480: }
1481: PetscFunctionReturn(PETSC_SUCCESS);
1482: }
1484: /*MC
1485: PetscOptionsRealArray - Gets an array of double values for a particular
1486: option in the database. The values must be separated with commas with
1487: no intervening spaces.
1489: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1491: Synopsis:
1492: #include "petscsys.h"
1493: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool *set)
1495: Input Parameters:
1496: + opt - the option one is seeking
1497: . text - short string describing option
1498: . man - manual page for option
1499: - n - maximum number of values that value has room for
1501: Output Parameters:
1502: + value - location to copy values
1503: . n - actual number of values found
1504: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1506: Level: beginner
1508: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1510: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1511: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1512: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1513: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1514: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1515: `PetscOptionsFList()`, `PetscOptionsEList()`
1516: M*/
1518: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1519: {
1520: PetscInt i;
1521: PetscOptionItem amsopt;
1523: PetscFunctionBegin;
1524: if (!PetscOptionsObject->count) {
1525: PetscReal *vals;
1527: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_REAL_ARRAY, &amsopt));
1528: PetscCall(PetscMalloc((*n) * sizeof(PetscReal), &amsopt->data));
1529: vals = (PetscReal *)amsopt->data;
1530: for (i = 0; i < *n; i++) vals[i] = value[i];
1531: amsopt->arraylength = *n;
1532: }
1533: PetscCall(PetscOptionsGetRealArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, n, set));
1534: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1535: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%g", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, (double)value[0]));
1536: for (i = 1; i < *n; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ",%g", (double)value[i]));
1537: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ">: %s (%s)\n", text, ManSection(man)));
1538: }
1539: PetscFunctionReturn(PETSC_SUCCESS);
1540: }
1542: /*MC
1543: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1544: option in the database. The values must be separated with commas with
1545: no intervening spaces.
1547: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1549: Synopsis:
1550: #include "petscsys.h"
1551: PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool *set)
1553: Input Parameters:
1554: + opt - the option one is seeking
1555: . text - short string describing option
1556: . man - manual page for option
1557: - n - maximum number of values allowed in the value array
1559: Output Parameters:
1560: + value - location to copy values
1561: . n - actual number of values found
1562: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1564: Level: beginner
1566: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1568: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1569: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1570: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1571: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1572: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1573: `PetscOptionsFList()`, `PetscOptionsEList()`
1574: M*/
1576: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1577: {
1578: PetscInt i;
1579: PetscOptionItem amsopt;
1581: PetscFunctionBegin;
1582: if (!PetscOptionsObject->count) {
1583: PetscScalar *vals;
1585: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_SCALAR_ARRAY, &amsopt));
1586: PetscCall(PetscMalloc((*n) * sizeof(PetscScalar), &amsopt->data));
1587: vals = (PetscScalar *)amsopt->data;
1588: for (i = 0; i < *n; i++) vals[i] = value[i];
1589: amsopt->arraylength = *n;
1590: }
1591: PetscCall(PetscOptionsGetScalarArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, n, set));
1592: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1593: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%g+%gi", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, (double)PetscRealPart(value[0]), (double)PetscImaginaryPart(value[0])));
1594: for (i = 1; i < *n; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ",%g+%gi", (double)PetscRealPart(value[i]), (double)PetscImaginaryPart(value[i])));
1595: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ">: %s (%s)\n", text, ManSection(man)));
1596: }
1597: PetscFunctionReturn(PETSC_SUCCESS);
1598: }
1600: /*MC
1601: PetscOptionsIntArray - Gets an array of integers for a particular
1602: option in the database.
1604: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1606: Synopsis:
1607: #include "petscsys.h"
1608: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool *set)
1610: Input Parameters:
1611: + opt - the option one is seeking
1612: . text - short string describing option
1613: . man - manual page for option
1614: - n - maximum number of values
1616: Output Parameters:
1617: + value - location to copy values
1618: . n - actual number of values found
1619: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1621: Level: beginner
1623: Notes:
1624: The array can be passed as
1625: + a comma separated list - 0,1,2,3,4,5,6,7
1626: . a range (start\-end+1) - 0-8
1627: . a range with given increment (start\-end+1:inc) - 0-7:2
1628: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1630: There must be no intervening spaces between the values.
1632: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1634: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1635: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1636: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1637: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1638: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1639: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRealArray()`
1640: M*/
1642: PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1643: {
1644: PetscInt i;
1645: PetscOptionItem amsopt;
1647: PetscFunctionBegin;
1648: if (!PetscOptionsObject->count) {
1649: PetscInt *vals;
1651: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_INT_ARRAY, &amsopt));
1652: PetscCall(PetscMalloc1(*n, (PetscInt **)&amsopt->data));
1653: vals = (PetscInt *)amsopt->data;
1654: for (i = 0; i < *n; i++) vals[i] = value[i];
1655: amsopt->arraylength = *n;
1656: }
1657: PetscCall(PetscOptionsGetIntArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, n, set));
1658: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1659: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%" PetscInt_FMT, PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, value[0]));
1660: for (i = 1; i < *n; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ",%" PetscInt_FMT, value[i]));
1661: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ">: %s (%s)\n", text, ManSection(man)));
1662: }
1663: PetscFunctionReturn(PETSC_SUCCESS);
1664: }
1666: /*MC
1667: PetscOptionsStringArray - Gets an array of string values for a particular
1668: option in the database. The values must be separated with commas with
1669: no intervening spaces.
1671: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1673: Synopsis:
1674: #include "petscsys.h"
1675: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool *set)
1677: Input Parameters:
1678: + opt - the option one is seeking
1679: . text - short string describing option
1680: . man - manual page for option
1681: - nmax - maximum number of strings
1683: Output Parameters:
1684: + value - location to copy strings
1685: . nmax - actual number of strings found
1686: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1688: Level: beginner
1690: Notes:
1691: The user should pass in an array of pointers to char, to hold all the
1692: strings returned by this function.
1694: The user is responsible for deallocating the strings that are
1695: returned.
1697: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1699: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1700: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1701: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1702: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1703: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1704: `PetscOptionsFList()`, `PetscOptionsEList()`
1705: M*/
1707: PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1708: {
1709: PetscOptionItem amsopt;
1711: PetscFunctionBegin;
1712: if (!PetscOptionsObject->count) {
1713: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_STRING_ARRAY, &amsopt));
1714: PetscCall(PetscMalloc1(*nmax, (char **)&amsopt->data));
1716: amsopt->arraylength = *nmax;
1717: }
1718: PetscCall(PetscOptionsGetStringArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, nmax, set));
1719: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1720: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <string1,string2,...>: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, text, ManSection(man)));
1721: }
1722: PetscFunctionReturn(PETSC_SUCCESS);
1723: }
1725: /*MC
1726: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1727: option in the database. The values must be separated with commas with
1728: no intervening spaces.
1730: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1732: Synopsis:
1733: #include "petscsys.h"
1734: PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1736: Input Parameters:
1737: + opt - the option one is seeking
1738: . text - short string describing option
1739: . man - manual page for option
1740: - n - maximum number of values allowed in the value array
1742: Output Parameters:
1743: + value - location to copy values
1744: . n - actual number of values found
1745: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1747: Level: beginner
1749: Notes:
1750: The user should pass in an array of doubles
1752: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1754: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1755: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1756: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1757: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1758: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1759: `PetscOptionsFList()`, `PetscOptionsEList()`
1760: M*/
1762: PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1763: {
1764: PetscInt i;
1765: PetscOptionItem amsopt;
1767: PetscFunctionBegin;
1768: if (!PetscOptionsObject->count) {
1769: PetscBool *vals;
1771: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_BOOL_ARRAY, &amsopt));
1772: PetscCall(PetscMalloc1(*n, (PetscBool **)&amsopt->data));
1773: vals = (PetscBool *)amsopt->data;
1774: for (i = 0; i < *n; i++) vals[i] = value[i];
1775: amsopt->arraylength = *n;
1776: }
1777: PetscCall(PetscOptionsGetBoolArray(PetscOptionsObject->options, PetscOptionsObject->prefix, opt, value, n, set));
1778: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1779: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%d", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, value[0]));
1780: for (i = 1; i < *n; i++) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ",%d", value[i]));
1781: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, ">: %s (%s)\n", text, ManSection(man)));
1782: }
1783: PetscFunctionReturn(PETSC_SUCCESS);
1784: }
1786: /*MC
1787: PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user
1789: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1791: Synopsis:
1792: #include "petscsys.h"
1793: PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)
1795: Input Parameters:
1796: + opt - option name
1797: . text - short string that describes the option
1798: - man - manual page with additional information on option
1800: Output Parameters:
1801: + viewer - the viewer
1802: . format - the PetscViewerFormat requested by the user, pass NULL if not needed
1803: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1805: Level: beginner
1807: Notes:
1808: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1810: See `PetscOptionsGetViewer()` for the format of the supplied viewer and its options
1812: .seealso: `PetscOptionsGetViewer()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1813: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
1814: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
1815: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1816: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1817: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1818: `PetscOptionsFList()`, `PetscOptionsEList()`
1819: M*/
1821: PetscErrorCode PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject, const char opt[], const char text[], const char man[], PetscViewer *viewer, PetscViewerFormat *format, PetscBool *set)
1822: {
1823: PetscOptionItem amsopt;
1825: PetscFunctionBegin;
1826: if (!PetscOptionsObject->count) {
1827: PetscCall(PetscOptionItemCreate_Private(PetscOptionsObject, opt, text, man, OPTION_STRING, &amsopt));
1828: /* must use system malloc since SAWs may free this */
1829: PetscCall(PetscStrdup("", (char **)&amsopt->data));
1830: }
1831: PetscCall(PetscOptionsGetViewer(PetscOptionsObject->comm, PetscOptionsObject->options, PetscOptionsObject->prefix, opt, viewer, format, set));
1832: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1833: PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " -%s%s <%s>: %s (%s)\n", PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "", opt + 1, "", text, ManSection(man)));
1834: }
1835: PetscFunctionReturn(PETSC_SUCCESS);
1836: }