Actual source code: aoptions.c

  1: #define PETSC_DLL
  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: typedef struct {
 17:   char            *prefix,*mprefix;
 18:   char            *title;
 19:   MPI_Comm        comm;
 20:   PetscTruth      printhelp;
 21:   PetscTruth      changedmethod;
 22: } PetscOptionsPublishObject;
 23: static PetscOptionsPublishObject amspub;
 24: PetscInt                         PetscOptionsPublishCount = 0;

 28: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
 29: {

 33:   PetscStrallocpy(prefix,&amspub.prefix);
 34:   PetscStrallocpy(title,&amspub.title);
 35:   amspub.comm   = comm;
 36:   PetscOptionsHasName(PETSC_NULL,"-help",&amspub.printhelp);
 37:   if (amspub.printhelp && PetscOptionsPublishCount) {
 38:     (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
 39:   }
 40:   return(0);
 41: }

 45: PetscErrorCode PetscOptionsEnd_Private(void)
 46: {

 50:   PetscStrfree(amspub.title); amspub.title  = 0;
 51:   PetscStrfree(amspub.prefix); amspub.prefix = 0;
 52:   return(0);
 53: }

 57: /*@C
 58:    PetscOptionsEnum - Gets the enum value for a particular option in the database.

 60:    Collective on the communicator passed in PetscOptionsBegin()

 62:    Input Parameters:
 63: +  opt - option name
 64: .  text - short string that describes the option
 65: .  man - manual page with additional information on option
 66: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
 67: -  defaultv - the default (current) value

 69:    Output Parameter:
 70: +  value - the  value to return
 71: -  flg - PETSC_TRUE if found, else PETSC_FALSE

 73:    Level: beginner

 75:    Concepts: options database

 77:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

 79:           list is usually something like PCASMTypes or some other predefined list of enum names

 81: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
 82:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
 83:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
 84:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
 85:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
 86:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
 87:           PetscOptionsList(), PetscOptionsEList()
 88: @*/
 89: PetscErrorCode PETSC_DLLEXPORT PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
 90: {
 92:   PetscInt       ntext = 0;

 95:   while (list[ntext++]) {
 96:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
 97:   }
 98:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
 99:   ntext -= 3;
100:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
101:   return(0);
102: }

104: /* -------------------------------------------------------------------------------------------------------------*/
107: /*@C
108:    PetscOptionsInt - Gets the integer value for a particular option in the database.

110:    Collective on the communicator passed in PetscOptionsBegin()

112:    Input Parameters:
113: +  opt - option name
114: .  text - short string that describes the option
115: .  man - manual page with additional information on option
116: -  defaultv - the default (current) value

118:    Output Parameter:
119: +  value - the integer value to return
120: -  flg - PETSC_TRUE if found, else PETSC_FALSE

122:    Level: beginner

124:    Concepts: options database^has int

126:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

128: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
129:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
130:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
131:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
132:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
133:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
134:           PetscOptionsList(), PetscOptionsEList()
135: @*/
136: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
137: {

141:   PetscOptionsGetInt(amspub.prefix,opt,value,set);
142:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
143:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
144:   }
145:   return(0);
146: }

150: /*@C
151:    PetscOptionsString - Gets the string value for a particular option in the database.

153:    Collective on the communicator passed in PetscOptionsBegin()

155:    Input Parameters:
156: +  opt - option name
157: .  text - short string that describes the option
158: .  man - manual page with additional information on option
159: -  defaultv - the default (current) value

161:    Output Parameter:
162: +  value - the value to return
163: -  flg - PETSC_TRUE if found, else PETSC_FALSE

165:    Level: beginner

167:    Concepts: options database^has int

169:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

171: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
172:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
173:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
174:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
175:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
176:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
177:           PetscOptionsList(), PetscOptionsEList()
178: @*/
179: PetscErrorCode PETSC_DLLEXPORT PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
180: {

184:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
185:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
186:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
187:   }
188:   return(0);
189: }

191: /*
192:      Publishes an AMS double field (with the default value in it) and with a name
193:    given by the text string
194: */
197: /*@C
198:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

200:    Collective on the communicator passed in PetscOptionsBegin()

202:    Input Parameters:
203: +  opt - option name
204: .  text - short string that describes the option
205: .  man - manual page with additional information on option
206: -  defaultv - the default (current) value

208:    Output Parameter:
209: +  value - the value to return
210: -  flg - PETSC_TRUE if found, else PETSC_FALSE

212:    Level: beginner

214:    Concepts: options database^has int

216:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

218: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
219:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
220:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
221:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
222:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
223:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
224:           PetscOptionsList(), PetscOptionsEList()
225: @*/
226: PetscErrorCode PETSC_DLLEXPORT PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
227: {

231:   PetscOptionsGetReal(amspub.prefix,opt,value,set);
232:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
233:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%g>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
234:   }
235:   return(0);
236: }

240: /*@C
241:    PetscOptionsScalar - Gets the scalar value for a particular option in the database.

243:    Collective on the communicator passed in PetscOptionsBegin()

245:    Input Parameters:
246: +  opt - option name
247: .  text - short string that describes the option
248: .  man - manual page with additional information on option
249: -  defaultv - the default (current) value

251:    Output Parameter:
252: +  value - the value to return
253: -  flg - PETSC_TRUE if found, else PETSC_FALSE

255:    Level: beginner

257:    Concepts: options database^has int

259:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

261: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
262:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
263:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
264:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
265:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
266:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
267:           PetscOptionsList(), PetscOptionsEList()
268: @*/
269: PetscErrorCode PETSC_DLLEXPORT PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
270: {

274: #if !defined(PETSC_USE_COMPLEX)
275:   PetscOptionsReal(opt,text,man,defaultv,value,set);
276: #else
277:   PetscOptionsGetScalar(amspub.prefix,opt,value,set);
278: #endif
279:   return(0);
280: }

282: /*
283:      Publishes an AMS logical field (with the default value in it) and with a name
284:    given by the text string
285: */
288: /*@C
289:    PetscOptionsName - Determines if a particular option is in the database

291:    Collective on the communicator passed in PetscOptionsBegin()

293:    Input Parameters:
294: +  opt - option name
295: .  text - short string that describes the option
296: -  man - manual page with additional information on option

298:    Output Parameter:
299: .  flg - PETSC_TRUE if found, else PETSC_FALSE

301:    Level: beginner

303:    Concepts: options database^has int

305:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

307: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
308:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
309:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
310:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
311:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
312:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
313:           PetscOptionsList(), PetscOptionsEList()
314: @*/
315: PetscErrorCode PETSC_DLLEXPORT PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
316: {

320:   PetscOptionsHasName(amspub.prefix,opt,flg);
321:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
322:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
323:   }
324:   return(0);
325: }

329: /*@C
330:      PetscOptionsList - Puts a list of option values that a single one may be selected from

332:    Collective on the communicator passed in PetscOptionsBegin()

334:    Input Parameters:
335: +  opt - option name
336: .  text - short string that describes the option
337: .  man - manual page with additional information on option
338: .  list - the possible choices
339: -  defaultv - the default (current) value

341:    Output Parameter:
342: +  value - the value to return
343: -  set - PETSC_TRUE if found, else PETSC_FALSE

345:    Level: intermediate
346:    
347:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

349:    See PetscOptionsEList() for when the choices are given in a string array

351:    To get a listing of all currently specified options,
352:     see PetscOptionsPrint() or PetscOptionsGetAll()

354:    Concepts: options database^list

356: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
357:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
358:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
359:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
360:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
361:           PetscOptionsList(), PetscOptionsEList()
362: @*/
363: PetscErrorCode PETSC_DLLEXPORT PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
364: {

368:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
369:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
370:     PetscFListPrintTypes(amspub.comm,stdout,amspub.prefix,opt,ltext,man,list);
371:   }
372:   return(0);
373: }

377: /*@C
378:      PetscOptionsEList - Puts a list of option values that a single one may be selected from

380:    Collective on the communicator passed in PetscOptionsBegin()

382:    Input Parameters:
383: +  opt - option name
384: .  ltext - short string that describes the option
385: .  man - manual page with additional information on option
386: .  list - the possible choices
387: .  ntext - number of choices
388: -  defaultv - the default (current) value

390:    Output Parameter:
391: +  value - the index of the value to return
392: -  set - PETSC_TRUE if found, else PETSC_FALSE
393:    
394:    Level: intermediate

396:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

398:    See PetscOptionsList() for when the choices are given in a PetscFList()

400:    Concepts: options database^list

402: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
403:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
404:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
405:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
406:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
407:           PetscOptionsList(), PetscOptionsEList()
408: @*/
409: PetscErrorCode PETSC_DLLEXPORT PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
410: {
412:   PetscInt       i;

415:   PetscOptionsGetEList(amspub.prefix,opt,list,ntext,value,set);
416:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
417:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s> (choose one of)",amspub.prefix?amspub.prefix:"",opt+1,defaultv);
418:     for (i=0; i<ntext; i++){
419:       (*PetscHelpPrintf)(amspub.comm," %s",list[i]);
420:     }
421:     (*PetscHelpPrintf)(amspub.comm,"\n");
422:   }
423:   return(0);
424: }

428: /*@C
429:      PetscOptionsTruthGroupBegin - First in a series of logical queries on the options database for
430:        which only a single value can be true.

432:    Collective on the communicator passed in PetscOptionsBegin()

434:    Input Parameters:
435: +  opt - option name
436: .  text - short string that describes the option
437: -  man - manual page with additional information on option

439:    Output Parameter:
440: .  flg - whether that option was set or not
441:    
442:    Level: intermediate

444:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

446:    Must be followed by 0 or more PetscOptionsTruthGroup()s and PetscOptionsTruthGroupEnd()

448:     Concepts: options database^logical group

450: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
451:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
452:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
453:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
454:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
455:           PetscOptionsList(), PetscOptionsEList()
456: @*/
457: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
458: {

462:   PetscOptionsHasName(amspub.prefix,opt,flg);
463:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
464:     (*PetscHelpPrintf)(amspub.comm,"  Pick at most one of -------------\n");
465:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
466:   }
467:   return(0);
468: }

472: /*@C
473:      PetscOptionsTruthGroup - One in a series of logical queries on the options database for
474:        which only a single value can be true.

476:    Collective on the communicator passed in PetscOptionsBegin()

478:    Input Parameters:
479: +  opt - option name
480: .  text - short string that describes the option
481: -  man - manual page with additional information on option

483:    Output Parameter:
484: .  flg - PETSC_TRUE if found, else PETSC_FALSE
485:    
486:    Level: intermediate

488:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

490:    Must follow a PetscOptionsTruthGroupBegin() and preceded a PetscOptionsTruthGroupEnd()

492:     Concepts: options database^logical group

494: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
495:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
496:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
497:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
498:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
499:           PetscOptionsList(), PetscOptionsEList()
500: @*/
501: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
502: {

506:   PetscOptionsHasName(amspub.prefix,opt,flg);
507:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
508:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
509:   }
510:   return(0);
511: }

515: /*@C
516:      PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
517:        which only a single value can be true.

519:    Collective on the communicator passed in PetscOptionsBegin()

521:    Input Parameters:
522: +  opt - option name
523: .  text - short string that describes the option
524: -  man - manual page with additional information on option

526:    Output Parameter:
527: .  flg - PETSC_TRUE if found, else PETSC_FALSE
528:    
529:    Level: intermediate

531:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

533:    Must follow a PetscOptionsTruthGroupBegin()

535:     Concepts: options database^logical group

537: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
538:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
539:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
540:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
541:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
542:           PetscOptionsList(), PetscOptionsEList()
543: @*/
544: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
545: {

549:   PetscOptionsHasName(amspub.prefix,opt,flg);
550:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
551:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
552:   }
553:   return(0);
554: }

558: /*@C
559:    PetscOptionsTruth - Determines if a particular option is in the database with a true or false

561:    Collective on the communicator passed in PetscOptionsBegin()

563:    Input Parameters:
564: +  opt - option name
565: .  text - short string that describes the option
566: -  man - manual page with additional information on option

568:    Output Parameter:
569: .  flg - PETSC_TRUE or PETSC_FALSE
570: .  set - PETSC_TRUE if found, else PETSC_FALSE

572:    Level: beginner

574:    Concepts: options database^logical

576:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

578: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
579:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
580:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
581:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
582:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
583:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
584:           PetscOptionsList(), PetscOptionsEList()
585: @*/
586: PetscErrorCode PETSC_DLLEXPORT PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
587: {
589:   PetscTruth     iset;

592:   PetscOptionsGetTruth(amspub.prefix,opt,flg,&iset);
593:   if (!iset) {
594:     if (flg) *flg = deflt;
595:   }
596:   if (set) *set = iset;
597:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
598:     const char *v = PetscTruths[deflt];
599:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: <%s> %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,v,text,man);
600:   }
601:   return(0);
602: }

606: /*@C
607:    PetscOptionsRealArray - Gets an array of double values for a particular
608:    option in the database. The values must be separated with commas with 
609:    no intervening spaces. 

611:    Collective on the communicator passed in PetscOptionsBegin()

613:    Input Parameters:
614: +  opt - the option one is seeking
615: .  text - short string describing option
616: .  man - manual page for option
617: -  nmax - maximum number of values

619:    Output Parameter:
620: +  value - location to copy values
621: .  nmax - actual number of values found
622: -  set - PETSC_TRUE if found, else PETSC_FALSE

624:    Level: beginner

626:    Notes: 
627:    The user should pass in an array of doubles

629:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

631:    Concepts: options database^array of strings

633: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
634:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
635:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
636:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
637:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
638:           PetscOptionsList(), PetscOptionsEList()
639: @*/
640: PetscErrorCode PETSC_DLLEXPORT PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
641: {
643:   PetscInt       i;

646:   PetscOptionsGetRealArray(amspub.prefix,opt,value,n,set);
647:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
648:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%g",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
649:     for (i=1; i<*n; i++) {
650:       (*PetscHelpPrintf)(amspub.comm,",%g",value[i]);
651:     }
652:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
653:   }
654:   return(0);
655: }


660: /*@C
661:    PetscOptionsIntArray - Gets an array of integers for a particular
662:    option in the database. The values must be separated with commas with 
663:    no intervening spaces. 

665:    Collective on the communicator passed in PetscOptionsBegin()

667:    Input Parameters:
668: +  opt - the option one is seeking
669: .  text - short string describing option
670: .  man - manual page for option
671: -  nmax - maximum number of values

673:    Output Parameter:
674: +  value - location to copy values
675: .  nmax - actual number of values found
676: -  set - PETSC_TRUE if found, else PETSC_FALSE

678:    Level: beginner

680:    Notes: 
681:    The user should pass in an array of integers

683:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

685:    Concepts: options database^array of strings

687: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
688:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
689:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
690:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
691:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
692:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
693: @*/
694: PetscErrorCode PETSC_DLLEXPORT PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
695: {
697:   PetscInt       i;

700:   PetscOptionsGetIntArray(amspub.prefix,opt,value,n,set);
701:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
702:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
703:     for (i=1; i<*n; i++) {
704:       (*PetscHelpPrintf)(amspub.comm,",%d",value[i]);
705:     }
706:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
707:   }
708:   return(0);
709: }

713: /*@C
714:    PetscOptionsStringArray - Gets an array of string values for a particular
715:    option in the database. The values must be separated with commas with 
716:    no intervening spaces. 

718:    Collective on the communicator passed in PetscOptionsBegin()

720:    Input Parameters:
721: +  opt - the option one is seeking
722: .  text - short string describing option
723: .  man - manual page for option
724: -  nmax - maximum number of strings

726:    Output Parameter:
727: +  value - location to copy strings
728: .  nmax - actual number of strings found
729: -  set - PETSC_TRUE if found, else PETSC_FALSE

731:    Level: beginner

733:    Notes: 
734:    The user should pass in an array of pointers to char, to hold all the
735:    strings returned by this function.

737:    The user is responsible for deallocating the strings that are
738:    returned. The Fortran interface for this routine is not supported.

740:    Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

742:    Concepts: options database^array of strings

744: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
745:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
746:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
747:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
748:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
749:           PetscOptionsList(), PetscOptionsEList()
750: @*/
751: PetscErrorCode PETSC_DLLEXPORT PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
752: {

756:   PetscOptionsGetStringArray(amspub.prefix,opt,value,nmax,set);
757:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
758:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
759:   }
760:   return(0);
761: }


766: /*@C
767:      PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
768:             in KSPSetFromOptions_GMRES().

770:    Collective on the communicator passed in PetscOptionsBegin()

772:    Input Parameter:
773: .   head - the heading text

775:    
776:    Level: intermediate

778:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

780:           Must be followed by a call to PetscOptionsTail() in the same function.

782:    Concepts: options database^subheading

784: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
785:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
786:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
787:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
788:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
789:           PetscOptionsList(), PetscOptionsEList()
790: @*/
791: PetscErrorCode PETSC_DLLEXPORT PetscOptionsHead(const char head[])
792: {

796:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
797:     (*PetscHelpPrintf)(amspub.comm,"  %s\n",head);
798:   }
799:   return(0);
800: }