Actual source code: aoptions.c

  1: /*
  2:    These routines simplify the use of command line, file options, etc.,
  3:    and are used to manipulate the options database.

  5:   This file uses regular malloc and free because it cannot know 
  6:   what malloc is being used until it has already processed the input.
  7: */

 9:  #include petsc.h
 10:  #include petscsys.h
 11: #if defined(PETSC_HAVE_STDLIB_H)
 12: #include <stdlib.h>
 13: #endif

 15: typedef struct {
 16:   char            *prefix,*mprefix;
 17:   char            *title;
 18:   MPI_Comm        comm;
 19:   PetscTruth      printhelp;
 20:   PetscTruth      changedmethod;
 21: } PetscOptionsPublishObject;
 22: static PetscOptionsPublishObject amspub;
 23: int PetscOptionsPublishCount = 0;

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

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

 44: PetscErrorCode PetscOptionsEnd_Private(void)
 45: {

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


 55: /* -------------------------------------------------------------------------------------------------------------*/
 58: /*@C
 59:    PetscOptionsInt - Gets the integer value for a particular option in the database.

 61:    Collective on the communicator passed in PetscOptionsBegin()

 63:    Input Parameters:
 64: +  opt - option name
 65: .  text - short string that describes the option
 66: .  man - manual page with additional information on option
 67: -  defaultv - the default (current) value

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

 73:    Level: beginner

 75:    Concepts: options database^has int

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

 79: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
 80:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
 81:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
 82:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
 83:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
 84:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
 85:           PetscOptionsList(), PetscOptionsEList()
 86: @*/
 87: PetscErrorCode PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
 88: {

 92:   PetscOptionsGetInt(amspub.prefix,opt,value,set);
 93:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
 94:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
 95:   }
 96:   return(0);
 97: }

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

104:    Collective on the communicator passed in PetscOptionsBegin()

106:    Input Parameters:
107: +  opt - option name
108: .  text - short string that describes the option
109: .  man - manual page with additional information on option
110: -  defaultv - the default (current) value

112:    Output Parameter:
113: +  value - the value to return
114: -  flg - PETSC_TRUE if found, else PETSC_FALSE

116:    Level: beginner

118:    Concepts: options database^has int

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

122: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
123:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
124:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
125:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
126:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
127:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
128:           PetscOptionsList(), PetscOptionsEList()
129: @*/
130: PetscErrorCode PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
131: {

135:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
136:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
137:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
138:   }
139:   return(0);
140: }

142: /*
143:      Publishes an AMS double field (with the default value in it) and with a name
144:    given by the text string
145: */
148: /*@C
149:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

151:    Collective on the communicator passed in PetscOptionsBegin()

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

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

163:    Level: beginner

165:    Concepts: options database^has int

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

169: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
170:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
171:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
172:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
173:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
174:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
175:           PetscOptionsList(), PetscOptionsEList()
176: @*/
177: PetscErrorCode PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
178: {

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

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

194:    Collective on the communicator passed in PetscOptionsBegin()

196:    Input Parameters:
197: +  opt - option name
198: .  text - short string that describes the option
199: .  man - manual page with additional information on option
200: -  defaultv - the default (current) value

202:    Output Parameter:
203: +  value - the value to return
204: -  flg - PETSC_TRUE if found, else PETSC_FALSE

206:    Level: beginner

208:    Concepts: options database^has int

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

212: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
213:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
214:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
215:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
216:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
217:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
218:           PetscOptionsList(), PetscOptionsEList()
219: @*/
220: PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
221: {

225: #if !defined(PETSC_USE_COMPLEX)
226:   PetscOptionsReal(opt,text,man,defaultv,value,set);
227: #else
228:   PetscOptionsGetScalar(amspub.prefix,opt,value,set);
229: #endif
230:   return(0);
231: }

233: /*
234:      Publishes an AMS logical field (with the default value in it) and with a name
235:    given by the text string
236: */
239: /*@C
240:    PetscOptionsName - Determines if a particular option is in the database

242:    Collective on the communicator passed in PetscOptionsBegin()

244:    Input Parameters:
245: +  opt - option name
246: .  text - short string that describes the option
247: -  man - manual page with additional information on option

249:    Output Parameter:
250: .  flg - PETSC_TRUE if found, else PETSC_FALSE

252:    Level: beginner

254:    Concepts: options database^has int

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

258: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
259:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
260:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
261:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
262:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
263:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
264:           PetscOptionsList(), PetscOptionsEList()
265: @*/
266: PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
267: {

271:   PetscOptionsHasName(amspub.prefix,opt,flg);
272:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
273:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
274:   }
275:   return(0);
276: }

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

283:    Collective on the communicator passed in PetscOptionsBegin()

285:    Input Parameters:
286: +  opt - option name
287: .  text - short string that describes the option
288: .  man - manual page with additional information on option
289: .  list - the possible choices
290: -  defaultv - the default (current) value

292:    Output Parameter:
293: +  value - the value to return
294: -  set - PETSC_TRUE if found, else PETSC_FALSE

296:    Level: intermediate
297:    
298:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

305:    Concepts: options database^list

307: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
308:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
309:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
310:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
311:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
312:           PetscOptionsList(), PetscOptionsEList()
313: @*/
314: PetscErrorCode PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
315: {

319:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
320:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
321:     PetscFListPrintTypes(amspub.comm,stdout,amspub.prefix,opt,ltext,man,list);
322:   }
323:   return(0);
324: }

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

331:    Collective on the communicator passed in PetscOptionsBegin()

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

341:    Output Parameter:
342: +  value - the index of the value to return
343: -  set - PETSC_TRUE if found, else PETSC_FALSE
344:    
345:    Level: intermediate

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

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

351:    Concepts: options database^list

353: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
354:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
355:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
356:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
357:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
358:           PetscOptionsList(), PetscOptionsEList()
359: @*/
360: PetscErrorCode PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *list[],PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
361: {
363:   size_t         alen,len = 0;
364:   char           *svalue;
365:   PetscTruth     aset,flg;
366:   PetscInt       i;

369:   for ( i=0; i<ntext; i++) {
370:     PetscStrlen(list[i],&alen);
371:     if (alen > len) len = alen;
372:   }
373:   len += 5; /* a little extra space for user mistypes */
374:   PetscMalloc(len*sizeof(char),&svalue);
375:   PetscOptionsGetString(amspub.prefix,opt,svalue,len,&aset);
376:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
377:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s> (one of)",amspub.prefix?amspub.prefix:"",opt+1,defaultv);
378:     for (i=0; i<ntext; i++){
379:       (*PetscHelpPrintf)(amspub.comm," %s",list[i]);
380:     }
381:     (*PetscHelpPrintf)(amspub.comm,"\n");
382:   }
383:   if (aset) {
384:     if (set) *set = PETSC_TRUE;
385:     for (i=0; i<ntext; i++) {
386:       PetscStrcmp(svalue,list[i],&flg);
387:       if (flg) {
388:         *value = i;
389:         PetscFree(svalue);
390:         return(0);
391:       }
392:     }
393:     PetscFree(svalue);
394:     SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,amspub.prefix?amspub.prefix:"",opt+1);
395:   } else if (set) {
396:     PetscFree(svalue);
397:     *set = PETSC_FALSE;
398:   } else {
399:     PetscFree(svalue);
400:   }
401:   return(0);
402: }

406: /*@C
407:      PetscOptionsLogicalGroupBegin - First in a series of logical queries on the options database for
408:        which only a single value can be true.

410:    Collective on the communicator passed in PetscOptionsBegin()

412:    Input Parameters:
413: +  opt - option name
414: .  text - short string that describes the option
415: -  man - manual page with additional information on option

417:    Output Parameter:
418: .  flg - whether that option was set or not
419:    
420:    Level: intermediate

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

424:    Must be followed by 0 or more PetscOptionsLogicalGroup()s and PetscOptionsLogicalGroupEnd()

426:     Concepts: options database^logical group

428: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
429:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
430:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
431:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
432:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
433:           PetscOptionsList(), PetscOptionsEList()
434: @*/
435: PetscErrorCode PetscOptionsLogicalGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
436: {

440:   PetscOptionsHasName(amspub.prefix,opt,flg);
441:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
442:     (*PetscHelpPrintf)(amspub.comm,"  Pick at most one of -------------\n");
443:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
444:   }
445:   return(0);
446: }

450: /*@C
451:      PetscOptionsLogicalGroup - One in a series of logical queries on the options database for
452:        which only a single value can be true.

454:    Collective on the communicator passed in PetscOptionsBegin()

456:    Input Parameters:
457: +  opt - option name
458: .  text - short string that describes the option
459: -  man - manual page with additional information on option

461:    Output Parameter:
462: .  flg - PETSC_TRUE if found, else PETSC_FALSE
463:    
464:    Level: intermediate

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

468:    Must follow a PetscOptionsLogicalGroupBegin() and preceded a PetscOptionsLogicalGroupEnd()

470:     Concepts: options database^logical group

472: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
473:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
474:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
475:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
476:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
477:           PetscOptionsList(), PetscOptionsEList()
478: @*/
479: PetscErrorCode PetscOptionsLogicalGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
480: {

484:   PetscOptionsHasName(amspub.prefix,opt,flg);
485:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
486:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
487:   }
488:   return(0);
489: }

493: /*@C
494:      PetscOptionsLogicalGroupEnd - Last in a series of logical queries on the options database for
495:        which only a single value can be true.

497:    Collective on the communicator passed in PetscOptionsBegin()

499:    Input Parameters:
500: +  opt - option name
501: .  text - short string that describes the option
502: -  man - manual page with additional information on option

504:    Output Parameter:
505: .  flg - PETSC_TRUE if found, else PETSC_FALSE
506:    
507:    Level: intermediate

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

511:    Must follow a PetscOptionsLogicalGroupBegin()

513:     Concepts: options database^logical group

515: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
516:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
517:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
518:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
519:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
520:           PetscOptionsList(), PetscOptionsEList()
521: @*/
522: PetscErrorCode PetscOptionsLogicalGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
523: {

527:   PetscOptionsHasName(amspub.prefix,opt,flg);
528:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
529:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
530:   }
531:   return(0);
532: }

536: /*@C
537:    PetscOptionsLogical - Determines if a particular option is in the database with a true or false

539:    Collective on the communicator passed in PetscOptionsBegin()

541:    Input Parameters:
542: +  opt - option name
543: .  text - short string that describes the option
544: -  man - manual page with additional information on option

546:    Output Parameter:
547: .  flg - PETSC_TRUE or PETSC_FALSE
548: .  set - PETSC_TRUE if found, else PETSC_FALSE

550:    Level: beginner

552:    Concepts: options database^logical

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

556: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
557:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
558:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
559:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
560:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
561:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
562:           PetscOptionsList(), PetscOptionsEList()
563: @*/
564: PetscErrorCode PetscOptionsLogical(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
565: {
567:   PetscTruth     iset;

570:   PetscOptionsGetLogical(amspub.prefix,opt,flg,&iset);
571:   if (iset == PETSC_FALSE) {
572:     if (flg != PETSC_NULL) *flg = deflt;
573:   }
574:   if (set != PETSC_NULL) *set = iset;
575:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
576:     const char *v = (deflt ? "true" : "false");
577:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: <%s> %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,v,text,man);
578:   }
579:   return(0);
580: }

584: /*@C
585:    PetscOptionsRealArray - Gets an array of double values for a particular
586:    option in the database. The values must be separated with commas with 
587:    no intervening spaces. 

589:    Collective on the communicator passed in PetscOptionsBegin()

591:    Input Parameters:
592: +  opt - the option one is seeking
593: .  text - short string describing option
594: .  man - manual page for option
595: -  nmax - maximum number of values

597:    Output Parameter:
598: +  value - location to copy values
599: .  nmax - actual number of values found
600: -  set - PETSC_TRUE if found, else PETSC_FALSE

602:    Level: beginner

604:    Notes: 
605:    The user should pass in an array of doubles

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

609:    Concepts: options database^array of strings

611: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
612:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
613:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
614:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
615:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
616:           PetscOptionsList(), PetscOptionsEList()
617: @*/
618: PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
619: {
621:   PetscInt       i;

624:   PetscOptionsGetRealArray(amspub.prefix,opt,value,n,set);
625:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
626:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%g",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
627:     for (i=1; i<*n; i++) {
628:       (*PetscHelpPrintf)(amspub.comm,",%g",value[i]);
629:     }
630:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
631:   }
632:   return(0);
633: }


638: /*@C
639:    PetscOptionsIntArray - Gets an array of integers for a particular
640:    option in the database. The values must be separated with commas with 
641:    no intervening spaces. 

643:    Collective on the communicator passed in PetscOptionsBegin()

645:    Input Parameters:
646: +  opt - the option one is seeking
647: .  text - short string describing option
648: .  man - manual page for option
649: -  nmax - maximum number of values

651:    Output Parameter:
652: +  value - location to copy values
653: .  nmax - actual number of values found
654: -  set - PETSC_TRUE if found, else PETSC_FALSE

656:    Level: beginner

658:    Notes: 
659:    The user should pass in an array of integers

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

663:    Concepts: options database^array of strings

665: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
666:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
667:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
668:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
669:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
670:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
671: @*/
672: PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
673: {
675:   PetscInt       i;

678:   PetscOptionsGetIntArray(amspub.prefix,opt,value,n,set);
679:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
680:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
681:     for (i=1; i<*n; i++) {
682:       (*PetscHelpPrintf)(amspub.comm,",%d",value[i]);
683:     }
684:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)\n",text,man);
685:   }
686:   return(0);
687: }

691: /*@C
692:    PetscOptionsStringArray - Gets an array of string values for a particular
693:    option in the database. The values must be separated with commas with 
694:    no intervening spaces. 

696:    Collective on the communicator passed in PetscOptionsBegin()

698:    Input Parameters:
699: +  opt - the option one is seeking
700: .  text - short string describing option
701: .  man - manual page for option
702: -  nmax - maximum number of strings

704:    Output Parameter:
705: +  value - location to copy strings
706: .  nmax - actual number of strings found
707: -  set - PETSC_TRUE if found, else PETSC_FALSE

709:    Level: beginner

711:    Notes: 
712:    The user should pass in an array of pointers to char, to hold all the
713:    strings returned by this function.

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

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

720:    Concepts: options database^array of strings

722: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
723:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
724:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
725:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
726:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
727:           PetscOptionsList(), PetscOptionsEList()
728: @*/
729: PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
730: {

734:   PetscOptionsGetStringArray(amspub.prefix,opt,value,nmax,set);
735:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
736:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
737:   }
738:   return(0);
739: }


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

748:    Collective on the communicator passed in PetscOptionsBegin()

750:    Input Parameter:
751: .   head - the heading text

753:    
754:    Level: intermediate

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

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

760:    Concepts: options database^subheading

762: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
763:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
764:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
765:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
766:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
767:           PetscOptionsList(), PetscOptionsEList()
768: @*/
769: PetscErrorCode PetscOptionsHead(const char head[])
770: {

774:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
775:     (*PetscHelpPrintf)(amspub.comm,"  %s\n",head);
776:   }
777:   return(0);
778: }