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: const char *option;
27: const 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 = 0;
54: int PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const 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(const char opt[],const char text[],const 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(const char opt[],const char text[],const 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(const char opt[],const char text[],const char man[],const 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(const char opt[],const char text[],const 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(const char opt[],const char text[],const 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(const char opt[],const char text[],const 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(const char opt[],const char ltext[],const char man[],PetscFList list,const 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
569: Output Parameter:
570: + value - the index of the value to return
571: - set - PETSC_TRUE if found, else PETSC_FALSE
572:
573: Level: intermediate
575: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
577: See PetscOptionsList() for when the choices are given in a PetscFList()
579: Concepts: options database^list
581: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
582: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
583: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
584: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
585: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
586: PetscOptionsList(), PetscOptionsEList()
587: @*/
588: int PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *list[],int ntext,const char defaultv[],int *value,PetscTruth *set)
589: {
590: int i,ierr,len = 0, alen;
591: char *svalue;
592: PetscTruth aset,flg;
595: #if defined(PETSC_HAVE_AMS)
596: if (!PetscOptionsPublishCount) {
597: PetscOptionsAMS amsopt;
598: char ldefault[128];
600: PetscOptionsCreate_Private(opt,ltext,man,&amsopt);
601: amsopt->type = OPTION_LIST;
602: PetscMalloc(sizeof(char*),&amsopt->data);
603: *(char **)(amsopt->data) = defaultv;
604: PetscStrcpy(ldefault,"DEFAULT:");
605: PetscStrcat(ldefault,ltext);
606: AMS_Memory_add_field(amspub.amem,ldefault,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
608: PetscMalloc((ntext+1)*sizeof(char**),&amsopt->edata);
609: PetscMemcpy(amsopt->edata,list,ntext*sizeof(char*));
610: AMS_Memory_add_field(amspub.amem,ltext,amsopt->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
611: if (set) *set = PETSC_FALSE;
612: return(0);
613: }
614: #endif
615: for ( i=0; i<ntext; i++) {
616: PetscStrlen(list[i],&alen);
617: if (alen > len) len = alen;
618: }
619: len += 5; /* a little extra space for user mistypes */
620: PetscMalloc(len*sizeof(char),&svalue);
621: PetscOptionsGetString(amspub.prefix,opt,svalue,len,&aset);
622: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
623: (*PetscHelpPrintf)(amspub.comm," -%s%s <%s> (one of)",amspub.prefix?amspub.prefix:"",opt+1,defaultv);
624: for (i=0; i<ntext; i++){
625: (*PetscHelpPrintf)(amspub.comm," %s",list[i]);
626: }
627: (*PetscHelpPrintf)(amspub.comm,"\n");
628: }
629: if (aset) {
630: if (set) *set = PETSC_TRUE;
631: for (i=0; i<ntext; i++) {
632: PetscStrcmp(svalue,list[i],&flg);
633: if (flg) {
634: *value = i;
635: PetscFree(svalue);
636: return(0);
637: }
638: }
639: PetscFree(svalue);
640: SETERRQ3(1,"Unknown option %s for -%s%s",svalue,amspub.prefix?amspub.prefix:"",opt+1);
641: } else if (set) {
642: PetscFree(svalue);
643: *set = PETSC_FALSE;
644: }
645: return(0);
646: }
650: /*@C
651: PetscOptionsLogicalGroupBegin - First in a series of logical queries on the options database for
652: which only a single value can be true.
654: Collective on the communicator passed in PetscOptionsBegin()
656: Input Parameters:
657: + opt - option name
658: . text - short string that describes the option
659: - man - manual page with additional information on option
661: Output Parameter:
662: . flg - whether that option was set or not
663:
664: Level: intermediate
666: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
668: Must be followed by 0 or more PetscOptionsLogicalGroup()s and PetscOptionsLogicalGroupEnd()
670: Concepts: options database^logical group
672: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
673: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
674: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
675: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
676: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
677: PetscOptionsList(), PetscOptionsEList()
678: @*/
679: int PetscOptionsLogicalGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
680: {
681: int ierr;
684: #if defined(PETSC_HAVE_AMS)
685: if (!PetscOptionsPublishCount) {
686: PetscOptionsAMS amsopt;
687: PetscOptionsCreate_Private(opt,text,man,&amsopt);
688: amsopt->type = OPTION_LOGICAL;
689: PetscMalloc(sizeof(int),&amsopt->data);
690: *(int*)amsopt->data = 1; /* the first one listed is always the default */
691: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
692: if (flg) *flg = PETSC_FALSE;
693: return(0);
694: }
695: #endif
696: PetscOptionsHasName(amspub.prefix,opt,flg);
697: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
698: (*PetscHelpPrintf)(amspub.comm," Pick at most one of -------------\n");
699: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
700: }
702: return(0);
703: }
707: /*@C
708: PetscOptionsLogicalGroup - One in a series of logical queries on the options database for
709: which only a single value can be true.
711: Collective on the communicator passed in PetscOptionsBegin()
713: Input Parameters:
714: + opt - option name
715: . text - short string that describes the option
716: - man - manual page with additional information on option
718: Output Parameter:
719: . flg - PETSC_TRUE if found, else PETSC_FALSE
720:
721: Level: intermediate
723: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
725: Must follow a PetscOptionsLogicalGroupBegin() and preceded a PetscOptionsLogicalGroupEnd()
727: Concepts: options database^logical group
729: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
730: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
731: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
732: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
733: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
734: PetscOptionsList(), PetscOptionsEList()
735: @*/
736: int PetscOptionsLogicalGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
737: {
738: int ierr;
741: #if defined(PETSC_HAVE_AMS)
742: if (!PetscOptionsPublishCount) {
743: PetscOptionsAMS amsopt;
744: PetscOptionsCreate_Private(opt,text,man,&amsopt);
745: amsopt->type = OPTION_LOGICAL;
746: PetscMalloc(sizeof(int),&amsopt->data);
747: *(int*)amsopt->data = 0;
748: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
749: if (flg) *flg = PETSC_FALSE;
750: return(0);
751: }
752: #endif
753: PetscOptionsHasName(amspub.prefix,opt,flg);
754: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
755: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
756: }
758: return(0);
759: }
763: /*@C
764: PetscOptionsLogicalGroupEnd - Last in a series of logical queries on the options database for
765: which only a single value can be true.
767: Collective on the communicator passed in PetscOptionsBegin()
769: Input Parameters:
770: + opt - option name
771: . text - short string that describes the option
772: - man - manual page with additional information on option
774: Output Parameter:
775: . flg - PETSC_TRUE if found, else PETSC_FALSE
776:
777: Level: intermediate
779: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
781: Must follow a PetscOptionsLogicalGroupBegin()
783: Concepts: options database^logical group
785: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
786: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
787: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
788: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
789: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
790: PetscOptionsList(), PetscOptionsEList()
791: @*/
792: int PetscOptionsLogicalGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
793: {
794: int ierr;
797: #if defined(PETSC_HAVE_AMS)
798: if (!PetscOptionsPublishCount) {
799: PetscOptionsAMS amsopt;
800: PetscOptionsCreate_Private(opt,text,man,&amsopt);
801: amsopt->type = OPTION_LOGICAL;
802: PetscMalloc(sizeof(int),&amsopt->data);
803: *(int*)amsopt->data = 0;
804: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
805: if (flg) *flg = PETSC_FALSE;
806: return(0);
807: }
808: #endif
809: PetscOptionsHasName(amspub.prefix,opt,flg);
810: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
811: (*PetscHelpPrintf)(amspub.comm," -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
812: }
814: return(0);
815: }
819: /*@C
820: PetscOptionsLogical - Determines if a particular option is in the database with a true or false
822: Collective on the communicator passed in PetscOptionsBegin()
824: Input Parameters:
825: + opt - option name
826: . text - short string that describes the option
827: - man - manual page with additional information on option
829: Output Parameter:
830: . flg - PETSC_TRUE or PETSC_FALSE
831: . set - PETSC_TRUE if found, else PETSC_FALSE
833: Level: beginner
835: Concepts: options database^logical
837: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
839: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
840: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
841: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
842: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
843: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
844: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
845: PetscOptionsList(), PetscOptionsEList()
846: @*/
847: int PetscOptionsLogical(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
848: {
849: int ierr;
850: PetscTruth iset;
853: #if defined(PETSC_HAVE_AMS)
854: if (!PetscOptionsPublishCount) {
855: PetscOptionsAMS amsopt;
856: PetscOptionsCreate_Private(opt,text,man,&amsopt);
857: amsopt->type = OPTION_LOGICAL;
858: PetscMalloc(sizeof(int),&amsopt->data);
859: *(int*)amsopt->data = (int)deflt;
860: AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
861: if (flg) *flg = PETSC_FALSE;
862: return(0);
863: }
864: #endif
865: PetscOptionsGetLogical(amspub.prefix,opt,flg,&iset);
866: if (iset == PETSC_FALSE) {
867: if (flg != PETSC_NULL) *flg = deflt;
868: }
869: if (set != PETSC_NULL) *set = iset;
870: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
871: const char *v = (deflt ? "true" : "false");
872: (*PetscHelpPrintf)(amspub.comm," -%s%s: <%s> %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,v,text,man);
873: }
875: return(0);
876: }
880: /*@C
881: PetscOptionsRealArray - Gets an array of double values for a particular
882: option in the database. The values must be separated with commas with
883: no intervening spaces.
885: Collective on the communicator passed in PetscOptionsBegin()
887: Input Parameters:
888: + opt - the option one is seeking
889: . text - short string describing option
890: . man - manual page for option
891: - nmax - maximum number of values
893: Output Parameter:
894: + value - location to copy values
895: . nmax - actual number of values found
896: - set - PETSC_TRUE if found, else PETSC_FALSE
898: Level: beginner
900: Notes:
901: The user should pass in an array of doubles
903: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
905: Concepts: options database^array of strings
907: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
908: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
909: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
910: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
911: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
912: PetscOptionsList(), PetscOptionsEList()
913: @*/
914: int PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal *value,int *n,PetscTruth *set)
915: {
916: int ierr,i;
919: #if defined(PETSC_HAVE_AMS)
920: if (!PetscOptionsPublishCount) {
921: PetscOptionsAMS amsopt;
922: PetscOptionsCreate_Private(opt,text,man,&amsopt);
923: amsopt->type = OPTION_REAL_ARRAY;
924: amsopt->arraylength = *n;
925: PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
926: PetscMemcpy(amsopt->data,value,(*n)*sizeof(PetscReal));
927: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
928: if (set) *set = PETSC_FALSE;
929: return(0);
930: }
931: #endif
932: PetscOptionsGetRealArray(amspub.prefix,opt,value,n,set);
933: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
934: (*PetscHelpPrintf)(amspub.comm," -%s%s <%g",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
935: for (i=1; i<*n; i++) {
936: (*PetscHelpPrintf)(amspub.comm,",%g",value[i]);
937: }
938: (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
939: }
940: return(0);
941: }
946: /*@C
947: PetscOptionsIntArray - Gets an array of integers for a particular
948: option in the database. The values must be separated with commas with
949: no intervening spaces.
951: Collective on the communicator passed in PetscOptionsBegin()
953: Input Parameters:
954: + opt - the option one is seeking
955: . text - short string describing option
956: . man - manual page for option
957: - nmax - maximum number of values
959: Output Parameter:
960: + value - location to copy values
961: . nmax - actual number of values found
962: - set - PETSC_TRUE if found, else PETSC_FALSE
964: Level: beginner
966: Notes:
967: The user should pass in an array of integers
969: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
971: Concepts: options database^array of strings
973: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
974: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
975: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
976: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
977: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
978: PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
979: @*/
980: int PetscOptionsIntArray(const char opt[],const char text[],const char man[],int *value,int *n,PetscTruth *set)
981: {
982: int ierr,i;
985: #if defined(PETSC_HAVE_AMS)
986: if (!PetscOptionsPublishCount) {
987: PetscOptionsAMS amsopt;
988: PetscOptionsCreate_Private(opt,text,man,&amsopt);
989: amsopt->type = OPTION_REAL_ARRAY;
990: amsopt->arraylength = *n;
991: PetscMalloc((*n)*sizeof(int),&amsopt->data);
992: PetscMemcpy(amsopt->data,value,(*n)*sizeof(int));
993: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
994: if (set) *set = PETSC_FALSE;
995: return(0);
996: }
997: #endif
998: PetscOptionsGetIntArray(amspub.prefix,opt,value,n,set);
999: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1000: (*PetscHelpPrintf)(amspub.comm," -%s%s <%d",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
1001: for (i=1; i<*n; i++) {
1002: (*PetscHelpPrintf)(amspub.comm,",%d",value[i]);
1003: }
1004: (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
1005: }
1006: return(0);
1007: }
1011: /*@C
1012: PetscOptionsStringArray - Gets an array of string values for a particular
1013: option in the database. The values must be separated with commas with
1014: no intervening spaces.
1016: Collective on the communicator passed in PetscOptionsBegin()
1018: Input Parameters:
1019: + opt - the option one is seeking
1020: . text - short string describing option
1021: . man - manual page for option
1022: - nmax - maximum number of strings
1024: Output Parameter:
1025: + value - location to copy strings
1026: . nmax - actual number of strings found
1027: - set - PETSC_TRUE if found, else PETSC_FALSE
1029: Level: beginner
1031: Notes:
1032: The user should pass in an array of pointers to char, to hold all the
1033: strings returned by this function.
1035: The user is responsible for deallocating the strings that are
1036: returned. The Fortran interface for this routine is not supported.
1038: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1040: Concepts: options database^array of strings
1042: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1043: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1044: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1045: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1046: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1047: PetscOptionsList(), PetscOptionsEList()
1048: @*/
1049: int PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],int *nmax,PetscTruth *set)
1050: {
1051: int ierr;
1054: #if defined(PETSC_HAVE_AMS)
1055: if (!PetscOptionsPublishCount) {
1056: PetscOptionsAMS amsopt;
1057: PetscOptionsCreate_Private(opt,text,man,&amsopt);
1058: amsopt->type = OPTION_STRING;
1059: PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1060: PetscMemzero(amsopt->data,(*nmax)*sizeof(char*));
1061: AMS_Memory_add_field(amspub.amem,text,amsopt->data,*nmax,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1062: if (set) *set = PETSC_FALSE;
1063: return(0);
1064: }
1065: #endif
1066: PetscOptionsGetStringArray(amspub.prefix,opt,value,nmax,set);
1067: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1068: (*PetscHelpPrintf)(amspub.comm," -%s%s <string1,string2,...>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
1069: }
1070: return(0);
1071: }
1076: /*@C
1077: PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
1078: in KSPSetFromOptions_GMRES().
1080: Collective on the communicator passed in PetscOptionsBegin()
1082: Input Parameter:
1083: . head - the heading text
1085:
1086: Level: intermediate
1088: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1090: Must be followed by a call to PetscOptionsTail() in the same function.
1092: Concepts: options database^subheading
1094: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1095: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1096: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1097: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1098: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1099: PetscOptionsList(), PetscOptionsEList()
1100: @*/
1101: int PetscOptionsHead(const char head[])
1102: {
1103: int ierr;
1106: #if defined(PETSC_HAVE_AMS)
1107: if (!PetscOptionsPublishCount) {
1108: PetscOptionsAMS amsopt;
1109: PetscOptionsCreate_Private("-amshead",head,"None",&amsopt);
1110: amsopt->type = OPTION_HEAD;
1111: PetscMalloc(sizeof(int),&amsopt->data);
1112: *(int*)amsopt->data = 0;
1113: AMS_Memory_add_field(amspub.amem,head,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1114: }
1115: #endif
1116: if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1117: (*PetscHelpPrintf)(amspub.comm," %s\n",head);
1118: }
1120: return(0);
1121: }