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: }