Actual source code: aoptions.c

  1: #define PETSC_DLL
  2: /*
  3:    Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to 
  4:    GUI code to display the options and get values from the users.

  6: */

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

 13: /*
 14:     Keep a linked list of options that have been posted and we are waiting for 
 15:    user selection. See the manual page for PetscOptionsBegin()

 17:     Eventually we'll attach this beast to a MPI_Comm
 18: */
 19: PetscOptionsObjectType PetscOptionsObject;
 20: PetscInt               PetscOptionsPublishCount = 0;

 24: /*
 25:     Handles setting up the data structure in a call to PetscOptionsBegin()
 26: */
 27: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
 28: {

 32:   PetscOptionsObject.next          = 0;
 33:   PetscOptionsObject.comm          = comm;
 34:   PetscOptionsObject.changedmethod = PETSC_FALSE;
 35:   if (PetscOptionsObject.prefix) {
 36:     PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
 37:   }
 38:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
 39:   if (PetscOptionsObject.title) {
 40:     PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
 41:   }
 42:   PetscStrallocpy(title,&PetscOptionsObject.title);

 44:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
 45:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
 46:     if (!PetscOptionsObject.alreadyprinted) {
 47:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
 48:     }
 49:   }
 50:   return(0);
 51: }

 53: /*
 54:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 55: */
 58: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
 59: {
 60:   int          ierr;
 61:   PetscOptions next;

 64:   PetscNew(struct _p_PetscOptions,amsopt);
 65:   (*amsopt)->next  = 0;
 66:   (*amsopt)->set   = PETSC_FALSE;
 67:   (*amsopt)->type  = t;
 68:   (*amsopt)->data  = 0;

 70:   PetscStrallocpy(text,&(*amsopt)->text);
 71:   PetscStrallocpy(opt,&(*amsopt)->option);
 72:   PetscStrallocpy(man,&(*amsopt)->man);

 74:   if (!PetscOptionsObject.next) {
 75:     PetscOptionsObject.next = *amsopt;
 76:   } else {
 77:     next = PetscOptionsObject.next;
 78:     while (next->next) next = next->next;
 79:     next->next = *amsopt;
 80:   }
 81:   return(0);
 82: }

 86: /*
 87:     PetscScanString -  Gets user input via stdin from process and broadcasts to all processes

 89:     Collective on MPI_Comm

 91:    Input Parameters:
 92: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
 93: .     n - length of the string, must be the same on all processes 
 94: -     str - location to store input

 96:     Bugs: 
 97: .   Assumes process 0 of the given communicator has access to stdin

 99: */
100: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
101: {
102:   size_t         i;
103:   char           c;
104:   PetscMPIInt    rank,nm;

108:   MPI_Comm_rank(comm,&rank);
109:   if (!rank) {
110:     c = (char) getchar();
111:     i = 0;
112:     while ( c != '\n' && i < n-1) {
113:       str[i++] = c;
114:       c = (char) getchar();
115:     }
116:     str[i] = 0;
117:   }
118:   nm   = PetscMPIIntCast(n);
119:   MPI_Bcast(str,nm,MPI_CHAR,0,comm);
120:   return(0);
121: }

125: /*
126:     PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime

128:     Notes: this isn't really practical, it is just to demonstrate the principle

130:     Bugs: 
131: +    All processes must traverse through the exact same set of option queries do to the call to PetscScanString()
132: .    Internal strings have arbitrary length and string copies are not checked that they fit into string space 
133: -    Only works for PetscInt == int, PetscReal == double etc   

135:     Developer Notes: Normally the GUI that presents the options the user and retrieves the values would be running in a different 
136:      address space and communicating with the PETSc program

138: */
139: PetscErrorCode PetscOptionsGetFromTextInput()
140: {
142:   PetscOptions   next = PetscOptionsObject.next;
143:   char           str[512];
144:   PetscInt       id;
145:   PetscReal      ir,*valr;
146:   PetscInt       *vald;
147:   size_t         i;
148: 
149:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
150:   while (next) {
151:     switch (next->type) {
152:       case OPTION_HEAD:
153:         break;
154:       case OPTION_INT_ARRAY:
155:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
156:         vald = (PetscInt*) next->data;
157:         for (i=0; i<next->arraylength; i++) {
158:           PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
159:           if (i < next->arraylength-1) {
160:             PetscPrintf(PETSC_COMM_WORLD,",");
161:           }
162:         }
163:         PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
164:         PetscScanString(PETSC_COMM_WORLD,512,str);
165:         if (str[0]) {
166:           PetscToken token;
167:           PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
168:           size_t     len;
169:           char*      value;
170:           PetscTruth foundrange;

172:           next->set = PETSC_TRUE;
173:           value = str;
174:           PetscTokenCreate(value,',',&token);
175:           PetscTokenFind(token,&value);
176:           while (n < nmax) {
177:             if (!value) break;
178: 
179:             /* look for form  d-D where d and D are integers */
180:             foundrange = PETSC_FALSE;
181:             PetscStrlen(value,&len);
182:             if (value[0] == '-') i=2;
183:             else i=1;
184:             for (;i<len; i++) {
185:               if (value[i] == '-') {
186:                 if (i == len-1) SETERRQ2(PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
187:                 value[i] = 0;
188:                 PetscOptionsAtoi(value,&start);
189:                 PetscOptionsAtoi(value+i+1,&end);
190:                 if (end <= start) SETERRQ3(PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
191:                 if (n + end - start - 1 >= nmax) SETERRQ4(PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,nmax-n,start,end);
192:                 for (;start<end; start++) {
193:                   *dvalue = start; dvalue++;n++;
194:                 }
195:                 foundrange = PETSC_TRUE;
196:                 break;
197:               }
198:             }
199:             if (!foundrange) {
200:               PetscOptionsAtoi(value,dvalue);
201:               dvalue++;
202:               n++;
203:             }
204:             PetscTokenFind(token,&value);
205:           }
206:           PetscTokenDestroy(token);
207:         }
208:         break;
209:       case OPTION_REAL_ARRAY:
210:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
211:         valr = (PetscReal*) next->data;
212:         for (i=0; i<next->arraylength; i++) {
213:           PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
214:           if (i < next->arraylength-1) {
215:             PetscPrintf(PETSC_COMM_WORLD,",");
216:           }
217:         }
218:         PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
219:         PetscScanString(PETSC_COMM_WORLD,512,str);
220:         if (str[0]) {
221:           PetscToken token;
222:           PetscInt   n=0,nmax = next->arraylength;
223:           PetscReal   *dvalue = (PetscReal*)next->data;
224:           char*      value;

226:           next->set = PETSC_TRUE;
227:           value = str;
228:           PetscTokenCreate(value,',',&token);
229:           PetscTokenFind(token,&value);
230:           while (n < nmax) {
231:             if (!value) break;
232:             PetscOptionsAtod(value,dvalue);
233:             dvalue++;
234:             n++;
235:             PetscTokenFind(token,&value);
236:           }
237:           PetscTokenDestroy(token);
238:         }
239:         break;
240:       case OPTION_INT:
241:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(int*)next->data,next->text,next->man);
242:         PetscScanString(PETSC_COMM_WORLD,512,str);
243:         if (str[0]) {
244: #if defined(PETSC_USE_64BIT_INDICES)
245:           sscanf(str,"%lld",&id);
246: #else
247:           sscanf(str,"%d",&id);
248: #endif
249:           next->set = PETSC_TRUE;
250:           *((PetscInt*)next->data) = id;
251:         }
252:         break;
253:       case OPTION_REAL:
254:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(double*)next->data,next->text,next->man);
255:         PetscScanString(PETSC_COMM_WORLD,512,str);
256:         if (str[0]) {
257: #if defined(PETSC_USE_SCALAR_SINGLE)
258:           sscanf(str,"%e",&ir);
259: #else
260:           sscanf(str,"%le",&ir);
261: #endif
262:           next->set = PETSC_TRUE;
263:           *((PetscReal*)next->data) = ir;
264:         }
265:         break;
266:       case OPTION_LOGICAL:
267:       case OPTION_STRING:
268:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,(char*)next->data,next->text,next->man);
269:         PetscScanString(PETSC_COMM_WORLD,512,str);
270:         if (str[0]) {
271:           next->set = PETSC_TRUE;
272:           PetscStrcpy((char*)next->data,str);
273:         }
274:         break;
275:       case OPTION_LIST:
276:         PetscFListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
277:         PetscScanString(PETSC_COMM_WORLD,512,str);
278:         if (str[0]) {
279:           PetscOptionsObject.changedmethod = PETSC_TRUE;
280:           next->set = PETSC_TRUE;
281:           PetscStrcpy((char*)next->data,str);
282:         }
283:         break;
284:     default:
285:       break;
286:     }
287:     next = next->next;
288:   }
289:   return(0);
290: }

294: PetscErrorCode PetscOptionsEnd_Private(void)
295: {
297:   PetscOptions   last;
298:   char           option[256],value[1024],tmp[32];
299:   size_t         j;


303:   if (PetscOptionsObject.next) {
304:     if (PetscOptionsPublishCount == 0) {
305:       PetscOptionsGetFromTextInput();
306:     }
307:   }

309:   PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
310:   PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;

312:   /* reset counter to -2; this updates the screen with the new options for the selected method */
313:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
314:   /* reset alreadyprinted flag */
315:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;

317:   while (PetscOptionsObject.next) {
318:     if (PetscOptionsObject.next->set) {
319:       if (PetscOptionsObject.prefix) {
320:         PetscStrcpy(option,"-");
321:         PetscStrcat(option,PetscOptionsObject.prefix);
322:         PetscStrcat(option,PetscOptionsObject.next->option+1);
323:       } else {
324:         PetscStrcpy(option,PetscOptionsObject.next->option);
325:       }

327:       switch (PetscOptionsObject.next->type) {
328:         case OPTION_HEAD:
329:           break;
330:         case OPTION_INT_ARRAY:
331:           sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
332:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
333:             sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
334:             PetscStrcat(value,",");
335:             PetscStrcat(value,tmp);
336:           }
337:           break;
338:         case OPTION_INT:
339:           sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
340:           break;
341:         case OPTION_REAL:
342:           sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
343:           break;
344:         case OPTION_REAL_ARRAY:
345:           sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
346:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
347:             sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
348:             PetscStrcat(value,",");
349:             PetscStrcat(value,tmp);
350:           }
351:           break;
352:         case OPTION_LOGICAL:
353:           PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
354:           break;
355:         case OPTION_LIST:
356:           PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
357:           break;
358:         case OPTION_STRING: /* also handles string arrays */
359:           PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
360:           break;
361:       }
362:       PetscOptionsSetValue(option,value);
363:     }
364:     PetscStrfree(PetscOptionsObject.next->text);
365:     PetscStrfree(PetscOptionsObject.next->option);
366:     PetscFree(PetscOptionsObject.next->man);
367:     PetscFree(PetscOptionsObject.next->data);
368:     last                    = PetscOptionsObject.next;
369:     PetscOptionsObject.next = PetscOptionsObject.next->next;
370:     PetscFree(last);
371:   }
372:   PetscOptionsObject.next = 0;
373:   return(0);
374: }

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

381:    Collective on the communicator passed in PetscOptionsBegin()

383:    Input Parameters:
384: +  opt - option name
385: .  text - short string that describes the option
386: .  man - manual page with additional information on option
387: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
388: -  defaultv - the default (current) value

390:    Output Parameter:
391: +  value - the  value to return
392: -  flg - PETSC_TRUE if found, else PETSC_FALSE

394:    Level: beginner

396:    Concepts: options database

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

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

402: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
403:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
404:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
405:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
406:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
407:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
408:           PetscOptionsList(), PetscOptionsEList()
409: @*/
410: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const*list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
411: {
413:   PetscInt       ntext = 0;
414:   PetscInt       tval;
415:   PetscTruth     tflg;

418:   while (list[ntext++]) {
419:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
420:   }
421:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
422:   ntext -= 3;
423:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
424:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
425:   if (tflg) *value = (PetscEnum)tval;
426:   if (set)  *set   = tflg;
427:   return(0);
428: }

430: /* -------------------------------------------------------------------------------------------------------------*/
433: /*@C
434:    PetscOptionsInt - Gets the integer value for a particular option 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
442: -  defaultv - the default (current) value

444:    Output Parameter:
445: +  value - the integer value to return
446: -  flg - PETSC_TRUE if found, else PETSC_FALSE

448:    Level: beginner

450:    Concepts: options database^has int

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

454: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
455:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
456:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
457:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
458:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
459:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
460:           PetscOptionsList(), PetscOptionsEList()
461: @*/
462: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
463: {
465:   PetscOptions   amsopt;

468:   if (PetscOptionsPublishCount == 0) {
469:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
470:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
471:     *(PetscInt*)amsopt->data = defaultv;
472:   }
473:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
474:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
475:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
476:   }
477:   return(0);
478: }

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

485:    Collective on the communicator passed in PetscOptionsBegin()

487:    Input Parameters:
488: +  opt - option name
489: .  text - short string that describes the option
490: .  man - manual page with additional information on option
491: -  defaultv - the default (current) value

493:    Output Parameter:
494: +  value - the value to return
495: -  flg - PETSC_TRUE if found, else PETSC_FALSE

497:    Level: beginner

499:    Concepts: options database^has int

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

503: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
504:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
505:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
506:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
507:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
508:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
509:           PetscOptionsList(), PetscOptionsEList()
510: @*/
511: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
512: {
514:   PetscOptions   amsopt;

517:   if (PetscOptionsPublishCount == 0) {
518:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
519:     PetscMalloc(len*sizeof(char),&amsopt->data);
520:     PetscStrcpy((char*)amsopt->data,defaultv);
521:   }
522:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
523:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
524:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
525:   }
526:   return(0);
527: }

531: /*@C
532:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

534:    Collective on the communicator passed in PetscOptionsBegin()

536:    Input Parameters:
537: +  opt - option name
538: .  text - short string that describes the option
539: .  man - manual page with additional information on option
540: -  defaultv - the default (current) value

542:    Output Parameter:
543: +  value - the value to return
544: -  flg - PETSC_TRUE if found, else PETSC_FALSE

546:    Level: beginner

548:    Concepts: options database^has int

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

552: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
553:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
554:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
555:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
556:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
557:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
558:           PetscOptionsList(), PetscOptionsEList()
559: @*/
560: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
561: {
563:   PetscOptions   amsopt;

566:   if (PetscOptionsPublishCount == 0) {
567:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
568:     PetscMalloc(sizeof(PetscReal),&amsopt->data);
569:     *(PetscReal*)amsopt->data = defaultv;
570:   }
571:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
572:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
573:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
574:   }
575:   return(0);
576: }

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

583:    Collective on the communicator passed in PetscOptionsBegin()

585:    Input Parameters:
586: +  opt - option name
587: .  text - short string that describes the option
588: .  man - manual page with additional information on option
589: -  defaultv - the default (current) value

591:    Output Parameter:
592: +  value - the value to return
593: -  flg - PETSC_TRUE if found, else PETSC_FALSE

595:    Level: beginner

597:    Concepts: options database^has int

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

601: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
602:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
603:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
604:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
605:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
606:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
607:           PetscOptionsList(), PetscOptionsEList()
608: @*/
609: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
610: {

614: #if !defined(PETSC_USE_COMPLEX)
615:   PetscOptionsReal(opt,text,man,defaultv,value,set);
616: #else
617:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
618: #endif
619:   return(0);
620: }

624: /*@C
625:    PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even 
626:                       its value is set to false.

628:    Collective on the communicator passed in PetscOptionsBegin()

630:    Input Parameters:
631: +  opt - option name
632: .  text - short string that describes the option
633: -  man - manual page with additional information on option

635:    Output Parameter:
636: .  flg - PETSC_TRUE if found, else PETSC_FALSE

638:    Level: beginner

640:    Concepts: options database^has int

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

644: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
645:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
646:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
647:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
648:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
649:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
650:           PetscOptionsList(), PetscOptionsEList()
651: @*/
652: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
653: {

657:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
658:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
659:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
660:   }
661:   return(0);
662: }

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

669:    Collective on the communicator passed in PetscOptionsBegin()

671:    Input Parameters:
672: +  opt - option name
673: .  text - short string that describes the option
674: .  man - manual page with additional information on option
675: .  list - the possible choices
676: .  defaultv - the default (current) value
677: -  len - the length of the character array value

679:    Output Parameter:
680: +  value - the value to return
681: -  set - PETSC_TRUE if found, else PETSC_FALSE

683:    Level: intermediate
684:    
685:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

692:    Concepts: options database^list

694: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
695:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
696:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
697:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
698:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
699:           PetscOptionsList(), PetscOptionsEList()
700: @*/
701: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],size_t len,PetscTruth *set)
702: {
704:   PetscOptions   amsopt;

707:   if (PetscOptionsPublishCount == 0) {
708:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
709:     PetscMalloc(1024*sizeof(char),&amsopt->data);
710:     PetscStrcpy((char*)amsopt->data,defaultv);
711:     amsopt->flist = list;
712:   }
713:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
714:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
715:     PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
716:   }
717:   return(0);
718: }

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

725:    Collective on the communicator passed in PetscOptionsBegin()

727:    Input Parameters:
728: +  opt - option name
729: .  ltext - short string that describes the option
730: .  man - manual page with additional information on option
731: .  list - the possible choices
732: .  ntext - number of choices
733: -  defaultv - the default (current) value

735:    Output Parameter:
736: +  value - the index of the value to return
737: -  set - PETSC_TRUE if found, else PETSC_FALSE
738:    
739:    Level: intermediate

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

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

745:    Concepts: options database^list

747: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
748:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
749:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
750:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
751:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
752:           PetscOptionsList(), PetscOptionsEList()
753: @*/
754: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const*list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
755: {
757:   PetscInt       i;

760:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
761:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
762:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
763:     for (i=0; i<ntext; i++){
764:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
765:     }
766:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
767:   }
768:   return(0);
769: }

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

777:    Collective on the communicator passed in PetscOptionsBegin()

779:    Input Parameters:
780: +  opt - option name
781: .  text - short string that describes the option
782: -  man - manual page with additional information on option

784:    Output Parameter:
785: .  flg - whether that option was set or not
786:    
787:    Level: intermediate

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

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

793:     Concepts: options database^logical group

795: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
796:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
797:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
798:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
799:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
800:           PetscOptionsList(), PetscOptionsEList()
801: @*/
802: PetscErrorCode  PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
803: {

807:   *flg = PETSC_FALSE;
808:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
809:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
810:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
811:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
812:   }
813:   return(0);
814: }

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

822:    Collective on the communicator passed in PetscOptionsBegin()

824:    Input Parameters:
825: +  opt - option name
826: .  text - short string that describes the option
827: -  man - manual page with additional information on option

829:    Output Parameter:
830: .  flg - PETSC_TRUE if found, else PETSC_FALSE
831:    
832:    Level: intermediate

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

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

838:     Concepts: options database^logical group

840: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
841:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
842:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
843:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
844:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
845:           PetscOptionsList(), PetscOptionsEList()
846: @*/
847: PetscErrorCode  PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
848: {

852:   *flg = PETSC_FALSE;
853:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
854:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
855:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
856:   }
857:   return(0);
858: }

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

866:    Collective on the communicator passed in PetscOptionsBegin()

868:    Input Parameters:
869: +  opt - option name
870: .  text - short string that describes the option
871: -  man - manual page with additional information on option

873:    Output Parameter:
874: .  flg - PETSC_TRUE if found, else PETSC_FALSE
875:    
876:    Level: intermediate

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

880:    Must follow a PetscOptionsTruthGroupBegin()

882:     Concepts: options database^logical group

884: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
885:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
886:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
887:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
888:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
889:           PetscOptionsList(), PetscOptionsEList()
890: @*/
891: PetscErrorCode  PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
892: {

896:   *flg = PETSC_FALSE;
897:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
898:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
899:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
900:   }
901:   return(0);
902: }

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

909:    Collective on the communicator passed in PetscOptionsBegin()

911:    Input Parameters:
912: +  opt - option name
913: .  text - short string that describes the option
914: -  man - manual page with additional information on option

916:    Output Parameter:
917: .  flg - PETSC_TRUE or PETSC_FALSE
918: .  set - PETSC_TRUE if found, else PETSC_FALSE

920:    Level: beginner

922:    Concepts: options database^logical

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

926: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
927:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
928:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
929:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
930:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
931:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
932:           PetscOptionsList(), PetscOptionsEList()
933: @*/
934: PetscErrorCode  PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
935: {
937:   PetscTruth     iset;
938:   PetscOptions   amsopt;

941:   if (PetscOptionsPublishCount == 0) {
942:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
943:     PetscMalloc(16*sizeof(char),&amsopt->data);
944:     PetscStrcpy((char*)amsopt->data,deflt ? "true" : "false");
945:   }
946:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
947:   if (!iset) {
948:     if (flg) *flg = deflt;
949:   }
950:   if (set) *set = iset;
951:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
952:     const char *v = PetscTruths[deflt];
953:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
954:   }
955:   return(0);
956: }

960: /*@C
961:    PetscOptionsRealArray - Gets an array of double values for a particular
962:    option in the database. The values must be separated with commas with 
963:    no intervening spaces. 

965:    Collective on the communicator passed in PetscOptionsBegin()

967:    Input Parameters:
968: +  opt - the option one is seeking
969: .  text - short string describing option
970: .  man - manual page for option
971: -  nmax - maximum number of values

973:    Output Parameter:
974: +  value - location to copy values
975: .  nmax - actual number of values found
976: -  set - PETSC_TRUE if found, else PETSC_FALSE

978:    Level: beginner

980:    Notes: 
981:    The user should pass in an array of doubles

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

985:    Concepts: options database^array of strings

987: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
988:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
989:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
990:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
991:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
992:           PetscOptionsList(), PetscOptionsEList()
993: @*/
994: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
995: {
997:   PetscInt       i;
998:   PetscOptions   amsopt;

1001:   if (PetscOptionsPublishCount == 0) {
1002:     PetscReal *vals;

1004:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1005:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1006:     vals = (PetscReal*)amsopt->data;
1007:     for (i=0; i<*n; i++) vals[i] = value[i];
1008:     amsopt->arraylength = *n;
1009:   }
1010:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1011:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1012:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1013:     for (i=1; i<*n; i++) {
1014:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1015:     }
1016:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
1017:   }
1018:   return(0);
1019: }


1024: /*@C
1025:    PetscOptionsIntArray - Gets an array of integers for a particular
1026:    option in the database. The values must be separated with commas with 
1027:    no intervening spaces. 

1029:    Collective on the communicator passed in PetscOptionsBegin()

1031:    Input Parameters:
1032: +  opt - the option one is seeking
1033: .  text - short string describing option
1034: .  man - manual page for option
1035: -  n - maximum number of values

1037:    Output Parameter:
1038: +  value - location to copy values
1039: .  n - actual number of values found
1040: -  set - PETSC_TRUE if found, else PETSC_FALSE

1042:    Level: beginner

1044:    Notes: 
1045:    The user should pass in an array of integers

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

1049:    Concepts: options database^array of strings

1051: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1052:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1053:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1054:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1055:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1056:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1057: @*/
1058: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
1059: {
1061:   PetscInt       i;
1062:   PetscOptions   amsopt;

1065:   if (PetscOptionsPublishCount == 0) {
1066:     PetscInt *vals;

1068:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1069:     PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1070:     vals = (PetscInt*)amsopt->data;
1071:     for (i=0; i<*n; i++) vals[i] = value[i];
1072:     amsopt->arraylength = *n;
1073:   }
1074:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1075:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1076:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1077:     for (i=1; i<*n; i++) {
1078:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1079:     }
1080:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
1081:   }
1082:   return(0);
1083: }

1087: /*@C
1088:    PetscOptionsStringArray - Gets an array of string values for a particular
1089:    option in the database. The values must be separated with commas with 
1090:    no intervening spaces. 

1092:    Collective on the communicator passed in PetscOptionsBegin()

1094:    Input Parameters:
1095: +  opt - the option one is seeking
1096: .  text - short string describing option
1097: .  man - manual page for option
1098: -  nmax - maximum number of strings

1100:    Output Parameter:
1101: +  value - location to copy strings
1102: .  nmax - actual number of strings found
1103: -  set - PETSC_TRUE if found, else PETSC_FALSE

1105:    Level: beginner

1107:    Notes: 
1108:    The user should pass in an array of pointers to char, to hold all the
1109:    strings returned by this function.

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

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

1116:    Concepts: options database^array of strings

1118: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1119:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1120:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1121:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1122:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1123:           PetscOptionsList(), PetscOptionsEList()
1124: @*/
1125: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
1126: {

1130:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1131:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1132:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
1133:   }
1134:   return(0);
1135: }

1139: /*@C
1140:    PetscOptionsTruthArray - Gets an array of logical values (true or false) for a particular
1141:    option in the database. The values must be separated with commas with 
1142:    no intervening spaces. 

1144:    Collective on the communicator passed in PetscOptionsBegin()

1146:    Input Parameters:
1147: +  opt - the option one is seeking
1148: .  text - short string describing option
1149: .  man - manual page for option
1150: -  nmax - maximum number of values

1152:    Output Parameter:
1153: +  value - location to copy values
1154: .  nmax - actual number of values found
1155: -  set - PETSC_TRUE if found, else PETSC_FALSE

1157:    Level: beginner

1159:    Notes: 
1160:    The user should pass in an array of doubles

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

1164:    Concepts: options database^array of strings

1166: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1167:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1168:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1169:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1170:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1171:           PetscOptionsList(), PetscOptionsEList()
1172: @*/
1173: PetscErrorCode  PetscOptionsTruthArray(const char opt[],const char text[],const char man[],PetscTruth value[],PetscInt *n,PetscTruth *set)
1174: {
1176:   PetscInt       i;

1179:   PetscOptionsGetTruthArray(PetscOptionsObject.prefix,opt,value,n,set);
1180:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1181:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1182:     for (i=1; i<*n; i++) {
1183:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1184:     }
1185:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
1186:   }
1187:   return(0);
1188: }


1193: /*@C
1194:      PetscOptionsHead - Puts a heading before listing any more published options. Used, for example,
1195:             in KSPSetFromOptions_GMRES().

1197:    Collective on the communicator passed in PetscOptionsBegin()

1199:    Input Parameter:
1200: .   head - the heading text

1202:    
1203:    Level: intermediate

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

1207:           Can be followed by a call to PetscOptionsTail() in the same function.

1209:    Concepts: options database^subheading

1211: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1212:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1213:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1214:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1215:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1216:           PetscOptionsList(), PetscOptionsEList()
1217: @*/
1218: PetscErrorCode  PetscOptionsHead(const char head[])
1219: {

1223:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1224:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1225:   }
1226:   return(0);
1227: }