Actual source code: aoptions.c
1: /*$Id: aoptions.c,v 1.34 2001/08/31 16:19:18 bsmith Exp $*/
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
16: #if defined(PETSC_HAVE_AMS)
17: /*
18: We keep a linked list of options that have been posted and we are waiting for
19: user selection
21: Eventually we'll attach this beast to a MPI_Comm
22: */
23: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD} OptionType;
24: typedef struct _p_OptionsAMS* PetscOptionsAMS;
25: struct _p_OptionsAMS {
26: char *option;
27: char *text;
28: void *data;
29: void *edata;
30: int arraylength;
31: PetscTruth set;
32: OptionType type;
33: PetscOptionsAMS next;
34: char *man;
35: };
36: #endif
38: typedef struct {
39: #if defined(PETSC_HAVE_AMS)
40: AMS_Memory amem;
41: PetscOptionsAMS next;
42: #endif
43: char *prefix,*mprefix; /* publish mprefix, not prefix cause the AMS will change it BUT we need to free it*/
44: char *title;
45: MPI_Comm comm;
46: PetscTruth printhelp;
47: PetscTruth changedmethod;
48: } PetscOptionsPublishObject;
49: static PetscOptionsPublishObject amspub;
50: int PetscOptionsPublishCount;
54: int PetscOptionsBegin_Private(MPI_Comm comm,char *prefix,char *title,char *mansec)
55: {
56: int ierr;
59: PetscStrallocpy(prefix,&amspub.prefix);
60: PetscStrallocpy(title,&amspub.title);
61: amspub.comm = comm;
62: PetscOptionsHasName(PETSC_NULL,"-help",&amspub.printhelp);
63: if (amspub.printhelp && PetscOptionsPublishCount) {
64: (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
65: }
66:
67: #if defined(PETSC_HAVE_AMS)
68: if (!PetscOptionsPublishCount) {
69: AMS_Comm acomm;
70: static int count = 0;
71: char options[16];
72: /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
73: PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
74: sprintf(options,"Options_%d",count++);
75: AMS_Memory_create(acomm,options,&amspub.amem);
76: AMS_Memory_take_access(amspub.amem);
77: amspub.mprefix = amspub.prefix;
78: AMS_Memory_add_field(amspub.amem,title,&amspub.mprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
79: AMS_Memory_add_field(amspub.amem,mansec,&amspub.mprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
80: amspub.changedmethod = PETSC_FALSE;
81: AMS_Memory_add_field(amspub.amem,"ChangedMethod",&amspub.changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
82: }
83: #endif
84: return(0);
85: }
89: int PetscOptionsEnd_Private(void)
90: {
94: #if defined(PETSC_HAVE_AMS)
95: if (!PetscOptionsPublishCount) {
96: PetscOptionsAMS last;
97: char option[256],value[1024],tmp[32];
98: int j;
100: if (amspub.amem < 0) SETERRQ(1,"Called without a call to PetscOptionsBegin()");
101: AMS_Memory_publish(amspub.amem);
102: AMS_Memory_grant_access(amspub.amem);
103: /* wait until accessor has unlocked the memory */
104: AMS_Memory_lock(amspub.amem,0);
105: AMS_Memory_take_access(amspub.amem);
107: /* reset counter to -2; this updates the screen with the new options for the selected method */
108: if (amspub.changedmethod) PetscOptionsPublishCount = -2;
110: /*
111: Free all the PetscOptions in the linked list and add any changed ones to the database
112: */
113: while (amspub.next) {
114: if (amspub.next->set) {
115: if (amspub.prefix) {
116: PetscStrcpy(option,"-");
117: PetscStrcat(option,amspub.prefix);
118: PetscStrcat(option,amspub.next->option+1);
119: } else {
120: PetscStrcpy(option,amspub.next->option);
121: }
123: switch (amspub.next->type) {
124: case OPTION_HEAD:
125: break;
126: case OPTION_INT:
127: sprintf(value,"%d",*(int*)amspub.next->data);
128: break;
129: case OPTION_REAL:
130: sprintf(value,"%g",*(double*)amspub.next->data);
131: break;
132: case OPTION_REAL_ARRAY:
133: sprintf(value,"%g",((PetscReal*)amspub.next->data)[0]);
134: for (j=1; j<amspub.next->arraylength; j++) {
135: sprintf(tmp,"%g",((PetscReal*)amspub.next->data)[j]);
136: PetscStrcat(value,",");
137: PetscStrcat(value,tmp);
138: }
139: break;
140: case OPTION_LOGICAL:
141: sprintf(value,"%d",*(int*)amspub.next->data);
142: break;
143: case OPTION_LIST:
144: PetscStrcpy(value,*(char**)amspub.next->data);
145: break;
146: case OPTION_STRING: /* also handles string arrays */
147: PetscStrcpy(value,*(char**)amspub.next->data);
148: break;
149: }
150: PetscOptionsSetValue(option,value);
151: }
152: PetscStrfree(amspub.next->text);
153: PetscStrfree(amspub.next->option);
154: PetscFree(amspub.next->man);
155: if (amspub.next->data) {PetscFree(amspub.next->data);}
156: if (amspub.next->edata) {PetscFree(amspub.next->edata);}
157: last = amspub.next;
158: amspub.next = amspub.next->next;
159: PetscFree(last);
160: }
161: AMS_Memory_grant_access(amspub.amem);
162: AMS_Memory_destroy(amspub.amem);
163: }
164: #endif
165: PetscStrfree(amspub.title); amspub.title = 0;
166: PetscStrfree(amspub.prefix); amspub.prefix = 0;
167: return(0);
168: }
170: #if defined(PETSC_HAVE_AMS)
171: /*
172: Publishes the "lock" for an option; with a name that is the command line
173: option name. This is the first item that is always published for an option
174: */
177: static int PetscOptionsCreate_Private(char *opt,char *text,char *man,PetscOptionsAMS *amsopt)
178: {
179: int ierr;
180: static int mancount = 0;
181: PetscOptionsAMS next;
182: char manname[16];
185: PetscNew(struct _p_OptionsAMS,amsopt);
186: (*amsopt)->next = 0;
187: (*amsopt)->set = PETSC_FALSE;
188: (*amsopt)->data = 0;
189: (*amsopt)->edata = 0;
190: PetscStrallocpy(text,&(*amsopt)->text);
191: PetscStrallocpy(opt,&(*amsopt)->option);
192: AMS_Memory_add_field(amspub.amem,opt,&(*amsopt)->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
193: sprintf(manname,"man_%d",mancount++);
194: PetscMalloc(sizeof(char*),&(*amsopt)->man);
195: *(char **)(*amsopt)->man = man;
196: AMS_Memory_add_field(amspub.amem,manname,(*amsopt)->man,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
198: if (!amspub.next) {
199: amspub.next = *amsopt;
200: } else {
201: next = amspub.next;
202: while (next->next) next = next->next;
203: next->next = *amsopt;
204: }
205: return(0);
206: }
207: #endif
209: /* -------------------------------------------------------------------------------------------------------------*/
210: /*
211: Publishes an AMS int field (with the default value in it) and with a name
212: given by the text string
213: */
216: /*@C
217: PetscOptionsInt - Gets the integer value for a particular option in the database.
219: Collective on the communicator passed in PetscOptionsBegin()
221: Input Parameters:
222: + opt - option name
223: . text - short string that describes the option
224: . man - manual page with additional information on option
225: - defaultv - the default (current) value
227: Output Parameter:
228: + value - the integer value to return
229: - flg - PETSC_TRUE if found, else PETSC_FALSE
231: Level: beginner
233: Concepts: options database^has int
235: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
237: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
238: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
239: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
240: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
241: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
242: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
243: PetscOptionsList(), PetscOptionsEList()
244: @*/
245: int PetscOptionsInt(char *opt,char *text,char *man,int defaultv,int *value,PetscTruth *set)
246: {
247: int ierr;
250: #if defined(PETSC_HAVE_AMS)
251: if (!PetscOptionsPublishCount) {
252: PetscOptionsAMS amsopt;
253: PetscOptionsCreate_Private(opt,text,man,&amsopt);
254: amsopt->type = OPTION_INT;
255: PetscMalloc(sizeof(int),&amsopt->data);
256: *(int*)amsopt->data = defaultv;
257: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
258: if (set) *set = PETSC_FALSE;
259: return(0);
260: }
261: #endif
262: PetscOptionsGetInt(amspub.prefix,opt,value,set);
263: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
264: (*PetscHelpPrintf)(amspub.comm," -%s%s <%d>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
265: }
266: return(0);
267: }
271: /*@C
272: PetscOptionsString - Gets the string value for a particular option in the database.
274: Collective on the communicator passed in PetscOptionsBegin()
276: Input Parameters:
277: + opt - option name
278: . text - short string that describes the option
279: . man - manual page with additional information on option
280: - defaultv - the default (current) value
282: Output Parameter:
283: + value - the value to return
284: - flg - PETSC_TRUE if found, else PETSC_FALSE
286: Level: beginner
288: Concepts: options database^has int
290: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
292: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
293: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
294: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
295: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
296: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
297: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
298: PetscOptionsList(), PetscOptionsEList()
299: @*/
300: int PetscOptionsString(char *opt,char *text,char *man,char *defaultv,char *value,int len,PetscTruth *set)
301: {
302: int ierr;
305: #if defined(PETSC_HAVE_AMS)
306: if (!PetscOptionsPublishCount) {
307: PetscOptionsAMS amsopt;
308: PetscOptionsCreate_Private(opt,text,man,&amsopt);
309: amsopt->type = OPTION_STRING;
310: PetscMalloc(sizeof(char*),&amsopt->data);
311: *(char**)amsopt->data = defaultv;
312: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
313: if (set) *set = PETSC_FALSE;
314: return(0);
315: }
316: #endif
317: PetscOptionsGetString(amspub.prefix,opt,value,len,set);
318: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
319: (*PetscHelpPrintf)(amspub.comm," -%s%s <%s>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
320: }
321: return(0);
322: }
324: /*
325: Publishes an AMS double field (with the default value in it) and with a name
326: given by the text string
327: */
330: /*@C
331: PetscOptionsReal - Gets the PetscReal value for a particular option in the database.
333: Collective on the communicator passed in PetscOptionsBegin()
335: Input Parameters:
336: + opt - option name
337: . text - short string that describes the option
338: . man - manual page with additional information on option
339: - defaultv - the default (current) value
341: Output Parameter:
342: + value - the value to return
343: - flg - PETSC_TRUE if found, else PETSC_FALSE
345: Level: beginner
347: Concepts: options database^has int
349: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
351: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
352: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
353: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
354: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
355: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
356: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
357: PetscOptionsList(), PetscOptionsEList()
358: @*/
359: int PetscOptionsReal(char *opt,char *text,char *man,PetscReal defaultv,PetscReal *value,PetscTruth *set)
360: {
361: int ierr;
364: #if defined(PETSC_HAVE_AMS)
365: if (!PetscOptionsPublishCount) {
366: PetscOptionsAMS amsopt;
367: PetscOptionsCreate_Private(opt,text,man,&amsopt);
368: amsopt->type = OPTION_REAL;
369: PetscMalloc(sizeof(PetscReal),&amsopt->data);
370: *(PetscReal*)amsopt->data = defaultv;
371: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
372: if (set) *set = PETSC_FALSE;
373: return(0);
374: }
375: #endif
376: PetscOptionsGetReal(amspub.prefix,opt,value,set);
377: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
378: (*PetscHelpPrintf)(amspub.comm," -%s%s <%g>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
379: }
380: return(0);
381: }
385: /*@C
386: PetscOptionsScalar - Gets the scalar value for a particular option in the database.
388: Collective on the communicator passed in PetscOptionsBegin()
390: Input Parameters:
391: + opt - option name
392: . text - short string that describes the option
393: . man - manual page with additional information on option
394: - defaultv - the default (current) value
396: Output Parameter:
397: + value - the value to return
398: - flg - PETSC_TRUE if found, else PETSC_FALSE
400: Level: beginner
402: Concepts: options database^has int
404: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
406: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
407: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
408: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
409: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
410: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
411: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
412: PetscOptionsList(), PetscOptionsEList()
413: @*/
414: int PetscOptionsScalar(char *opt,char *text,char *man,PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
415: {
419: #if !defined(PETSC_USE_COMPLEX)
420: PetscOptionsReal(opt,text,man,defaultv,value,set);
421: #else
422: PetscOptionsGetScalar(amspub.prefix,opt,value,set);
423: #endif
424: return(0);
425: }
427: /*
428: Publishes an AMS logical field (with the default value in it) and with a name
429: given by the text string
430: */
433: /*@C
434: PetscOptionsName - Determines if a particular option is in the database
436: Collective on the communicator passed in PetscOptionsBegin()
438: Input Parameters:
439: + opt - option name
440: . text - short string that describes the option
441: - man - manual page with additional information on option
443: Output Parameter:
444: . flg - PETSC_TRUE if found, else PETSC_FALSE
446: Level: beginner
448: Concepts: options database^has int
450: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
452: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
453: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
454: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
455: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
456: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
457: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
458: PetscOptionsList(), PetscOptionsEList()
459: @*/
460: int PetscOptionsName(char *opt,char *text,char *man,PetscTruth *flg)
461: {
462: int ierr;
465: #if defined(PETSC_HAVE_AMS)
466: if (!PetscOptionsPublishCount) {
467: PetscOptionsAMS amsopt;
468: PetscOptionsCreate_Private(opt,text,man,&amsopt);
469: amsopt->type = OPTION_LOGICAL;
470: PetscMalloc(sizeof(int),&amsopt->data);
471: *(int*)amsopt->data = 0;
472: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
473: if (flg) *flg = PETSC_FALSE;
474: return(0);
475: }
476: #endif
477: PetscOptionsHasName(amspub.prefix,opt,flg);
478: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
479: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
480: }
482: return(0);
483: }
487: /*@C
488: PetscOptionsList - Puts a list of option values that a single one may be selected from
490: Collective on the communicator passed in PetscOptionsBegin()
492: Input Parameters:
493: + opt - option name
494: . text - short string that describes the option
495: . man - manual page with additional information on option
496: . list - the possible choices
497: - defaultv - the default (current) value
499: Output Parameter:
500: + value - the value to return
501: - set - PETSC_TRUE if found, else PETSC_FALSE
503: Level: intermediate
504:
505: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
507: See PetscOptionsEList() for when the choices are given in a string array
509: To get a listing of all currently specified options,
510: see PetscOptionsPrint() or PetscOptionsGetAll()
512: Concepts: options database^list
514: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
515: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
516: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
517: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
518: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
519: PetscOptionsList(), PetscOptionsEList()
520: @*/
521: int PetscOptionsList(char *opt,char *ltext,char *man,PetscFList list,char *defaultv,char *value,int len,PetscTruth *set)
522: {
523: int ierr;
526: #if defined(PETSC_HAVE_AMS)
527: if (!PetscOptionsPublishCount) {
528: PetscOptionsAMS amsopt;
529: int ntext;
530: char ldefault[128];
532: PetscOptionsCreate_Private(opt,ltext,man,&amsopt);
533: amsopt->type = OPTION_LIST;
534: PetscMalloc(sizeof(char*),&amsopt->data);
535: *(char **)(amsopt->data) = defaultv;
536: PetscStrcpy(ldefault,"DEFAULT:");
537: PetscStrcat(ldefault,ltext);
538: AMS_Memory_add_field(amspub.amem,ldefault,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
540: PetscFListGet(list,(char***)&amsopt->edata,&ntext);
541: AMS_Memory_add_field(amspub.amem,ltext,amsopt->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
542: if (set) *set = PETSC_FALSE;
543: return(0);
544: }
545: #endif
546: PetscOptionsGetString(amspub.prefix,opt,value,len,set);
547: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
548: PetscFListPrintTypes(amspub.comm,stdout,amspub.prefix,opt,ltext,man,list);
549: }
551: return(0);
552: }
556: /*@C
557: PetscOptionsEList - Puts a list of option values that a single one may be selected from
559: Collective on the communicator passed in PetscOptionsBegin()
561: Input Parameters:
562: + opt - option name
563: . text - short string that describes the option
564: . man - manual page with additional information on option
565: . list - the possible choices
566: . ntext - number of choices
567: . defaultv - the default (current) value
568: - len - the size of the output value array
570: Output Parameter:
571: + value - the value to return
572: - set - PETSC_TRUE if found, else PETSC_FALSE
573:
574: Level: intermediate
576: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
578: See PetscOptionsList() for when the choices are given in a PetscFList()
580: Concepts: options database^list
582: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
583: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
584: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
585: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
586: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
587: PetscOptionsList(), PetscOptionsEList()
588: @*/
589: int PetscOptionsEList(char *opt,char *ltext,char *man,char **list,int ntext,char *defaultv,char *value,int len,PetscTruth *set)
590: {
591: int i,ierr;
594: #if defined(PETSC_HAVE_AMS)
595: if (!PetscOptionsPublishCount) {
596: PetscOptionsAMS amsopt;
597: char ldefault[128];
599: PetscOptionsCreate_Private(opt,ltext,man,&amsopt);
600: amsopt->type = OPTION_LIST;
601: PetscMalloc(sizeof(char*),&amsopt->data);
602: *(char **)(amsopt->data) = defaultv;
603: PetscStrcpy(ldefault,"DEFAULT:");
604: PetscStrcat(ldefault,ltext);
605: AMS_Memory_add_field(amspub.amem,ldefault,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
607: PetscMalloc((ntext+1)*sizeof(char**),&amsopt->edata);
608: PetscMemcpy(amsopt->edata,list,ntext*sizeof(char*));
609: AMS_Memory_add_field(amspub.amem,ltext,amsopt->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
610: if (set) *set = PETSC_FALSE;
611: return(0);
612: }
613: #endif
614: PetscOptionsGetString(amspub.prefix,opt,value,len,set);
615: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
616: (*PetscHelpPrintf)(amspub.comm," -%s%s <%s> (one of)",amspub.prefix?amspub.prefix:"",opt+1,defaultv);
617: for (i=0; i<ntext; i++){
618: (*PetscHelpPrintf)(amspub.comm," %s",list[i]);
619: }
620: (*PetscHelpPrintf)(amspub.comm,"\n");
621: }
623: return(0);
624: }
628: /*@C
629: PetscOptionsLogicalGroupBegin - First in a series of logical queries on the options database for
630: which only a single value can be true.
632: Collective on the communicator passed in PetscOptionsBegin()
634: Input Parameters:
635: + opt - option name
636: . text - short string that describes the option
637: - man - manual page with additional information on option
639: Output Parameter:
640: . flg - whether that option was set or not
641:
642: Level: intermediate
644: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
646: Must be followed by 0 or more PetscOptionsLogicalGroup()s and PetscOptionsLogicalGroupEnd()
648: Concepts: options database^logical group
650: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
651: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
652: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
653: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
654: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
655: PetscOptionsList(), PetscOptionsEList()
656: @*/
657: int PetscOptionsLogicalGroupBegin(char *opt,char *text,char *man,PetscTruth *flg)
658: {
659: int ierr;
662: #if defined(PETSC_HAVE_AMS)
663: if (!PetscOptionsPublishCount) {
664: PetscOptionsAMS amsopt;
665: PetscOptionsCreate_Private(opt,text,man,&amsopt);
666: amsopt->type = OPTION_LOGICAL;
667: PetscMalloc(sizeof(int),&amsopt->data);
668: *(int*)amsopt->data = 1; /* the first one listed is always the default */
669: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
670: if (flg) *flg = PETSC_FALSE;
671: return(0);
672: }
673: #endif
674: PetscOptionsHasName(amspub.prefix,opt,flg);
675: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
676: (*PetscHelpPrintf)(amspub.comm," Pick at most one of -------------\n");
677: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
678: }
680: return(0);
681: }
685: /*@C
686: PetscOptionsLogicalGroup - One in a series of logical queries on the options database for
687: which only a single value can be true.
689: Collective on the communicator passed in PetscOptionsBegin()
691: Input Parameters:
692: + opt - option name
693: . text - short string that describes the option
694: - man - manual page with additional information on option
696: Output Parameter:
697: . flg - PETSC_TRUE if found, else PETSC_FALSE
698:
699: Level: intermediate
701: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
703: Must follow a PetscOptionsLogicalGroupBegin() and preceded a PetscOptionsLogicalGroupEnd()
705: Concepts: options database^logical group
707: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
708: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
709: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
710: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
711: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
712: PetscOptionsList(), PetscOptionsEList()
713: @*/
714: int PetscOptionsLogicalGroup(char *opt,char *text,char *man,PetscTruth *flg)
715: {
716: int ierr;
719: #if defined(PETSC_HAVE_AMS)
720: if (!PetscOptionsPublishCount) {
721: PetscOptionsAMS amsopt;
722: PetscOptionsCreate_Private(opt,text,man,&amsopt);
723: amsopt->type = OPTION_LOGICAL;
724: PetscMalloc(sizeof(int),&amsopt->data);
725: *(int*)amsopt->data = 0;
726: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
727: if (flg) *flg = PETSC_FALSE;
728: return(0);
729: }
730: #endif
731: PetscOptionsHasName(amspub.prefix,opt,flg);
732: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
733: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
734: }
736: return(0);
737: }
741: /*@C
742: PetscOptionsLogicalGroupEnd - Last in a series of logical queries on the options database for
743: which only a single value can be true.
745: Collective on the communicator passed in PetscOptionsBegin()
747: Input Parameters:
748: + opt - option name
749: . text - short string that describes the option
750: - man - manual page with additional information on option
752: Output Parameter:
753: . flg - PETSC_TRUE if found, else PETSC_FALSE
754:
755: Level: intermediate
757: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
759: Must follow a PetscOptionsLogicalGroupBegin()
761: Concepts: options database^logical group
763: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
764: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
765: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
766: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
767: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
768: PetscOptionsList(), PetscOptionsEList()
769: @*/
770: int PetscOptionsLogicalGroupEnd(char *opt,char *text,char *man,PetscTruth *flg)
771: {
772: int ierr;
775: #if defined(PETSC_HAVE_AMS)
776: if (!PetscOptionsPublishCount) {
777: PetscOptionsAMS amsopt;
778: PetscOptionsCreate_Private(opt,text,man,&amsopt);
779: amsopt->type = OPTION_LOGICAL;
780: PetscMalloc(sizeof(int),&amsopt->data);
781: *(int*)amsopt->data = 0;
782: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
783: if (flg) *flg = PETSC_FALSE;
784: return(0);
785: }
786: #endif
787: PetscOptionsHasName(amspub.prefix,opt,flg);
788: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
789: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
790: }
792: return(0);
793: }
797: /*@C
798: PetscOptionsLogical - Determines if a particular option is in the database with a true or false
800: Collective on the communicator passed in PetscOptionsBegin()
802: Input Parameters:
803: + opt - option name
804: . text - short string that describes the option
805: - man - manual page with additional information on option
807: Output Parameter:
808: . flg - PETSC_TRUE or PETSC_FALSE
809: . set - PETSC_TRUE if found, else PETSC_FALSE
811: Level: beginner
813: Concepts: options database^logical
815: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
817: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
818: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
819: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
820: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
821: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
822: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
823: PetscOptionsList(), PetscOptionsEList()
824: @*/
825: int PetscOptionsLogical(char *opt,char *text,char *man,PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
826: {
827: int ierr;
828: PetscTruth iset;
831: #if defined(PETSC_HAVE_AMS)
832: if (!PetscOptionsPublishCount) {
833: PetscOptionsAMS amsopt;
834: PetscOptionsCreate_Private(opt,text,man,&amsopt);
835: amsopt->type = OPTION_LOGICAL;
836: PetscMalloc(sizeof(int),&amsopt->data);
837: *(int*)amsopt->data = (int)deflt;
838: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
839: if (flg) *flg = PETSC_FALSE;
840: return(0);
841: }
842: #endif
843: PetscOptionsGetLogical(amspub.prefix,opt,flg,&iset);
844: if (iset == PETSC_FALSE) {
845: if (flg != PETSC_NULL) *flg = deflt;
846: }
847: if (set != PETSC_NULL) *set = iset;
848: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
849: const char *v = (deflt ? "true" : "false");
850: (*PetscHelpPrintf)(amspub.comm," -%s%s: <%s> %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,v,text,man);
851: }
853: return(0);
854: }
858: /*@C
859: PetscOptionsRealArray - Gets an array of double values for a particular
860: option in the database. The values must be separated with commas with
861: no intervening spaces.
863: Collective on the communicator passed in PetscOptionsBegin()
865: Input Parameters:
866: + opt - the option one is seeking
867: . text - short string describing option
868: . man - manual page for option
869: - nmax - maximum number of values
871: Output Parameter:
872: + value - location to copy values
873: . nmax - actual number of values found
874: - set - PETSC_TRUE if found, else PETSC_FALSE
876: Level: beginner
878: Notes:
879: The user should pass in an array of doubles
881: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
883: Concepts: options database^array of strings
885: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
886: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
887: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
888: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
889: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
890: PetscOptionsList(), PetscOptionsEList()
891: @*/
892: int PetscOptionsRealArray(char *opt,char *text,char *man,PetscReal *value,int *n,PetscTruth *set)
893: {
894: int ierr,i;
897: #if defined(PETSC_HAVE_AMS)
898: if (!PetscOptionsPublishCount) {
899: PetscOptionsAMS amsopt;
900: PetscOptionsCreate_Private(opt,text,man,&amsopt);
901: amsopt->type = OPTION_REAL_ARRAY;
902: amsopt->arraylength = *n;
903: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
904: PetscMemcpy(amsopt->data,value,(*n)*sizeof(PetscReal));
905: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
906: if (set) *set = PETSC_FALSE;
907: return(0);
908: }
909: #endif
910: PetscOptionsGetRealArray(amspub.prefix,opt,value,n,set);
911: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
912: (*PetscHelpPrintf)(amspub.comm," -%s%s <%g",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
913: for (i=1; i<*n; i++) {
914: (*PetscHelpPrintf)(amspub.comm,",%g",value[i]);
915: }
916: (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
917: }
918: return(0);
919: }
924: /*@C
925: PetscOptionsIntArray - Gets an array of integers for a particular
926: option in the database. The values must be separated with commas with
927: no intervening spaces.
929: Collective on the communicator passed in PetscOptionsBegin()
931: Input Parameters:
932: + opt - the option one is seeking
933: . text - short string describing option
934: . man - manual page for option
935: - nmax - maximum number of values
937: Output Parameter:
938: + value - location to copy values
939: . nmax - actual number of values found
940: - set - PETSC_TRUE if found, else PETSC_FALSE
942: Level: beginner
944: Notes:
945: The user should pass in an array of integers
947: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
949: Concepts: options database^array of strings
951: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
952: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
953: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
954: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
955: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
956: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
957: @*/
958: int PetscOptionsIntArray(char *opt,char *text,char *man,int *value,int *n,PetscTruth *set)
959: {
960: int ierr,i;
963: #if defined(PETSC_HAVE_AMS)
964: if (!PetscOptionsPublishCount) {
965: PetscOptionsAMS amsopt;
966: PetscOptionsCreate_Private(opt,text,man,&amsopt);
967: amsopt->type = OPTION_REAL_ARRAY;
968: amsopt->arraylength = *n;
969: PetscMalloc((*n)*sizeof(int),&amsopt->data);
970: PetscMemcpy(amsopt->data,value,(*n)*sizeof(int));
971: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
972: if (set) *set = PETSC_FALSE;
973: return(0);
974: }
975: #endif
976: PetscOptionsGetIntArray(amspub.prefix,opt,value,n,set);
977: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
978: (*PetscHelpPrintf)(amspub.comm," -%s%s <%d",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
979: for (i=1; i<*n; i++) {
980: (*PetscHelpPrintf)(amspub.comm,",%d",value[i]);
981: }
982: (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
983: }
984: return(0);
985: }
989: /*@C
990: PetscOptionsStringArray - Gets an array of string values for a particular
991: option in the database. The values must be separated with commas with
992: no intervening spaces.
994: Collective on the communicator passed in PetscOptionsBegin()
996: Input Parameters:
997: + opt - the option one is seeking
998: . text - short string describing option
999: . man - manual page for option
1000: - nmax - maximum number of strings
1002: Output Parameter:
1003: + value - location to copy strings
1004: . nmax - actual number of strings found
1005: - set - PETSC_TRUE if found, else PETSC_FALSE
1007: Level: beginner
1009: Notes:
1010: The user should pass in an array of pointers to char, to hold all the
1011: strings returned by this function.
1013: The user is responsible for deallocating the strings that are
1014: returned. The Fortran interface for this routine is not supported.
1016: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1018: Concepts: options database^array of strings
1020: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1021: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1022: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1023: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1024: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1025: PetscOptionsList(), PetscOptionsEList()
1026: @*/
1027: int PetscOptionsStringArray(char *opt,char *text,char *man,char **value,int *nmax,PetscTruth *set)
1028: {
1029: int ierr;
1032: #if defined(PETSC_HAVE_AMS)
1033: if (!PetscOptionsPublishCount) {
1034: PetscOptionsAMS amsopt;
1035: PetscOptionsCreate_Private(opt,text,man,&amsopt);
1036: amsopt->type = OPTION_STRING;
1037: PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1038: PetscMemzero(amsopt->data,(*nmax)*sizeof(char*));
1039: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*nmax,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1040: if (set) *set = PETSC_FALSE;
1041: return(0);
1042: }
1043: #endif
1044: PetscOptionsGetStringArray(amspub.prefix,opt,value,nmax,set);
1045: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1046: (*PetscHelpPrintf)(amspub.comm," -%s%s <string1,string2,...>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
1047: }
1048: return(0);
1049: }
1054: /*@C
1055: PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
1056: in KSPSetFromOptions_GMRES().
1058: Collective on the communicator passed in PetscOptionsBegin()
1060: Input Parameter:
1061: . head - the heading text
1063:
1064: Level: intermediate
1066: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1068: Must be followed by a call to PetscOptionsTail() in the same function.
1070: Concepts: options database^subheading
1072: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1073: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1074: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1075: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1076: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1077: PetscOptionsList(), PetscOptionsEList()
1078: @*/
1079: int PetscOptionsHead(char *head)
1080: {
1081: int ierr;
1084: #if defined(PETSC_HAVE_AMS)
1085: if (!PetscOptionsPublishCount) {
1086: PetscOptionsAMS amsopt;
1087: PetscOptionsCreate_Private("-amshead",head,"None",&amsopt);
1088: amsopt->type = OPTION_HEAD;
1089: PetscMalloc(sizeof(int),&amsopt->data);
1090: *(int*)amsopt->data = 0;
1091: AMS_Memory_add_field(amspub.amem,head,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1092: }
1093: #endif
1094: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1095: (*PetscHelpPrintf)(amspub.comm," %s\n",head);
1096: }
1098: return(0);
1099: }