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: /*
 17:     Keep a linked list of options that have been posted and we are waiting for 
 18:    user selection

 20:     Eventually we'll attach this beast to a MPI_Comm
 21: */
 22: PetscOptionsObjectType PetscOptionsObject;
 23: PetscInt               PetscOptionsPublishCount = 0;


 28: PetscErrorCode PetscOptionsHelpAddList(const char prefix[],const char title[],const char mansec[])
 29: {
 30:   int               ierr;
 31:   PetscOptionsHelp  newhelp;
 33:   PetscNew(struct _p_PetscOptionsHelp,&newhelp);
 34:   PetscStrallocpy(prefix,&newhelp->prefix);
 35:   PetscStrallocpy(title,&newhelp->title);
 36:   PetscStrallocpy(mansec,&newhelp->mansec);
 37:   newhelp->next = 0;

 39:   if (!PetscOptionsObject.help) {
 40:     PetscOptionsObject.help = newhelp;
 41:   } else {
 42:     newhelp->next = PetscOptionsObject.help;
 43:     PetscOptionsObject.help = newhelp;
 44:   }
 45:   return(0);
 46: }

 50: PetscErrorCode PetscOptionsHelpDestroyList(void)
 51: {
 52:   PetscErrorCode   ierr;
 53:   PetscOptionsHelp help = PetscOptionsObject.help, next;

 56:   while (help) {
 57:     next = help->next;
 58:     PetscStrfree(help->prefix);
 59:     PetscStrfree(help->title);
 60:     PetscStrfree(help->mansec);
 61:     PetscFree(help);
 62:     help = next;
 63:   }
 64:   return(0);
 65: }
 66: 

 70: PetscErrorCode PetscOptionsHelpFindList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
 71: {
 72:   PetscErrorCode   ierr;
 73:   PetscTruth       flg1,flg2,flg3;
 74:   PetscOptionsHelp help = PetscOptionsObject.help;
 76:   while (help) {
 77:     PetscStrcmp(help->prefix,prefix,&flg1);
 78:     PetscStrcmp(help->title,title,&flg2);
 79:     PetscStrcmp(help->mansec,mansec,&flg3);
 80:     if (flg1 && flg2 && flg3) {
 81:       *flg = PETSC_TRUE;
 82:       break;
 83:     }
 84:     help = help->next;
 85:   }
 86:   return(0);

 88: }

 92: PetscErrorCode PetscOptionsHelpCheckAddList(const char prefix[],const char title[],const char mansec[],PetscTruth *flg)
 93: {
 95:   PetscOptionsHelpFindList(prefix,title,mansec,flg);
 96:   if (!(*flg)) PetscOptionsHelpAddList(prefix,title,mansec);
 97:   return(0);
 98: }

102: /*
103:     Handles setting up the data structure in a call to PetscOptionsBegin()
104: */
105: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
106: {

110:   PetscOptionsObject.next          = 0;
111:   PetscOptionsObject.comm          = comm;
112:   PetscOptionsObject.changedmethod = PETSC_FALSE;
113:   if (PetscOptionsObject.prefix) {
114:     PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;
115:   }
116:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
117:   if (PetscOptionsObject.title) {
118:     PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
119:   }
120:   PetscStrallocpy(title,&PetscOptionsObject.title);

122:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
123:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
124:     PetscOptionsHelpCheckAddList(prefix,title,mansec,&PetscOptionsObject.alreadyprinted);
125:     if (!PetscOptionsObject.alreadyprinted) {
126:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
127:     }
128:   }
129:   return(0);
130: }

132: /*
133:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
134: */
137: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
138: {
139:   int          ierr;
140:   PetscOptions next;

143:   PetscNew(struct _p_PetscOptions,amsopt);
144:   (*amsopt)->next  = 0;
145:   (*amsopt)->set   = PETSC_FALSE;
146:   (*amsopt)->type  = t;
147:   (*amsopt)->data  = 0;
148:   (*amsopt)->edata = 0;

150:   PetscStrallocpy(text,&(*amsopt)->text);
151:   PetscStrallocpy(opt,&(*amsopt)->option);
152:   PetscStrallocpy(man,&(*amsopt)->man);

154:   if (!PetscOptionsObject.next) {
155:     PetscOptionsObject.next = *amsopt;
156:   } else {
157:     next = PetscOptionsObject.next;
158:     while (next->next) next = next->next;
159:     next->next = *amsopt;
160:   }
161:   return(0);
162: }

166: PetscErrorCode PetscOptionsGetFromGUI()
167: {
169:   PetscOptions   next = PetscOptionsObject.next;
170:   char           str[512];

172:   (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
173:   while (next) {
174:     switch (next->type) {
175:       case OPTION_HEAD:
176:         break;
177:       case OPTION_INT:
178:         PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
179:         scanf("%s\n",str);
180:         if (str[0] != '\n') {
181:           printf("changing value\n");
182:         }
183:         break;
184:     default:
185:       break;
186:     }
187:     next = next->next;
188:   }
189:   return(0);
190: }

194: PetscErrorCode PetscOptionsEnd_Private(void)
195: {
197:   PetscOptions   last;
198:   char           option[256],value[1024],tmp[32];
199:   PetscInt       j;


203:   /*  if (PetscOptionsObject.next) { 
204:     PetscOptionsGetFromGUI();
205:     }*/

207:   PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
208:   PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;

210:   /* reset counter to -2; this updates the screen with the new options for the selected method */
211:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
212:   /* reset alreadyprinted flag */
213:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;

215:   while (PetscOptionsObject.next) {
216:     if (PetscOptionsObject.next->set) {
217:       if (PetscOptionsObject.prefix) {
218:         PetscStrcpy(option,"-");
219:         PetscStrcat(option,PetscOptionsObject.prefix);
220:         PetscStrcat(option,PetscOptionsObject.next->option+1);
221:       } else {
222:         PetscStrcpy(option,PetscOptionsObject.next->option);
223:       }

225:       switch (PetscOptionsObject.next->type) {
226:         case OPTION_HEAD:
227:           break;
228:         case OPTION_INT:
229:           sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
230:           break;
231:         case OPTION_REAL:
232:           sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
233:           break;
234:         case OPTION_REAL_ARRAY:
235:           sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
236:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
237:             sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
238:             PetscStrcat(value,",");
239:             PetscStrcat(value,tmp);
240:           }
241:           break;
242:         case OPTION_LOGICAL:
243:           sprintf(value,"%d",(int)*(PetscInt*)PetscOptionsObject.next->data);
244:           break;
245:         case OPTION_LIST:
246:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
247:           break;
248:         case OPTION_STRING: /* also handles string arrays */
249:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
250:           break;
251:       }
252:       PetscOptionsSetValue(option,value);
253:     }
254:     PetscStrfree(PetscOptionsObject.next->text);
255:     PetscStrfree(PetscOptionsObject.next->option);
256:     PetscFree(PetscOptionsObject.next->man);
257:     PetscFree(PetscOptionsObject.next->data);
258:     PetscFree(PetscOptionsObject.next->edata);
259:     last                    = PetscOptionsObject.next;
260:     PetscOptionsObject.next = PetscOptionsObject.next->next;
261:     PetscFree(last);
262:   }
263:   PetscOptionsObject.next = 0;
264:   return(0);
265: }

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

272:    Collective on the communicator passed in PetscOptionsBegin()

274:    Input Parameters:
275: +  opt - option name
276: .  text - short string that describes the option
277: .  man - manual page with additional information on option
278: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
279: -  defaultv - the default (current) value

281:    Output Parameter:
282: +  value - the  value to return
283: -  flg - PETSC_TRUE if found, else PETSC_FALSE

285:    Level: beginner

287:    Concepts: options database

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

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

293: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
294:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
295:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
296:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
297:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
298:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
299:           PetscOptionsList(), PetscOptionsEList()
300: @*/
301: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
302: {
304:   PetscInt       ntext = 0;
305:   PetscInt       tval;
306:   PetscTruth     tflg;

309:   while (list[ntext++]) {
310:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
311:   }
312:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
313:   ntext -= 3;
314:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
315:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
316:   if (tflg) *value = (PetscEnum)tval;
317:   if (set)  *set   = tflg;
318:   return(0);
319: }

321: /* -------------------------------------------------------------------------------------------------------------*/
324: /*@C
325:    PetscOptionsInt - Gets the integer value for a particular option in the database.

327:    Collective on the communicator passed in PetscOptionsBegin()

329:    Input Parameters:
330: +  opt - option name
331: .  text - short string that describes the option
332: .  man - manual page with additional information on option
333: -  defaultv - the default (current) value

335:    Output Parameter:
336: +  value - the integer value to return
337: -  flg - PETSC_TRUE if found, else PETSC_FALSE

339:    Level: beginner

341:    Concepts: options database^has int

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

345: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
346:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
347:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
348:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
349:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
350:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
351:           PetscOptionsList(), PetscOptionsEList()
352: @*/
353: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
354: {
356:   PetscOptions   amsopt;

359:   if (PetscOptionsPublishCount == 1) {
360:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
361:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
362:     *(PetscInt*)amsopt->data = defaultv;
363:   }
364:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
365:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
366:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
367:   }
368:   return(0);
369: }

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

376:    Collective on the communicator passed in PetscOptionsBegin()

378:    Input Parameters:
379: +  opt - option name
380: .  text - short string that describes the option
381: .  man - manual page with additional information on option
382: -  defaultv - the default (current) value

384:    Output Parameter:
385: +  value - the value to return
386: -  flg - PETSC_TRUE if found, else PETSC_FALSE

388:    Level: beginner

390:    Concepts: options database^has int

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

394: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
395:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
396:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
397:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
398:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
399:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
400:           PetscOptionsList(), PetscOptionsEList()
401: @*/
402: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
403: {

407:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
408:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
409:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
410:   }
411:   return(0);
412: }

414: /*
415:      Publishes an AMS double field (with the default value in it) and with a name
416:    given by the text string
417: */
420: /*@C
421:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

423:    Collective on the communicator passed in PetscOptionsBegin()

425:    Input Parameters:
426: +  opt - option name
427: .  text - short string that describes the option
428: .  man - manual page with additional information on option
429: -  defaultv - the default (current) value

431:    Output Parameter:
432: +  value - the value to return
433: -  flg - PETSC_TRUE if found, else PETSC_FALSE

435:    Level: beginner

437:    Concepts: options database^has int

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

441: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
442:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
443:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
444:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
445:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
446:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
447:           PetscOptionsList(), PetscOptionsEList()
448: @*/
449: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
450: {

454:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
455:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
456:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
457:   }
458:   return(0);
459: }

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

466:    Collective on the communicator passed in PetscOptionsBegin()

468:    Input Parameters:
469: +  opt - option name
470: .  text - short string that describes the option
471: .  man - manual page with additional information on option
472: -  defaultv - the default (current) value

474:    Output Parameter:
475: +  value - the value to return
476: -  flg - PETSC_TRUE if found, else PETSC_FALSE

478:    Level: beginner

480:    Concepts: options database^has int

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

484: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
485:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
486:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
487:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
488:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
489:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
490:           PetscOptionsList(), PetscOptionsEList()
491: @*/
492: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
493: {

497: #if !defined(PETSC_USE_COMPLEX)
498:   PetscOptionsReal(opt,text,man,defaultv,value,set);
499: #else
500:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
501: #endif
502:   return(0);
503: }

505: /*
506:      Publishes an AMS logical field (with the default value in it) and with a name
507:    given by the text string
508: */
511: /*@C
512:    PetscOptionsName - Determines if a particular option is in the database

514:    Collective on the communicator passed in PetscOptionsBegin()

516:    Input Parameters:
517: +  opt - option name
518: .  text - short string that describes the option
519: -  man - manual page with additional information on option

521:    Output Parameter:
522: .  flg - PETSC_TRUE if found, else PETSC_FALSE

524:    Level: beginner

526:    Concepts: options database^has int

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

530: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
531:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
532:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
533:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
534:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
535:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
536:           PetscOptionsList(), PetscOptionsEList()
537: @*/
538: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
539: {

543:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
544:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
545:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
546:   }
547:   return(0);
548: }

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

555:    Collective on the communicator passed in PetscOptionsBegin()

557:    Input Parameters:
558: +  opt - option name
559: .  text - short string that describes the option
560: .  man - manual page with additional information on option
561: .  list - the possible choices
562: -  defaultv - the default (current) value

564:    Output Parameter:
565: +  value - the value to return
566: -  set - PETSC_TRUE if found, else PETSC_FALSE

568:    Level: intermediate
569:    
570:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

577:    Concepts: options database^list

579: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
580:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
581:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
582:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
583:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
584:           PetscOptionsList(), PetscOptionsEList()
585: @*/
586: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
587: {

591:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
592:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
593:     PetscFListPrintTypes(list,PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man);
594:   }
595:   return(0);
596: }

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

603:    Collective on the communicator passed in PetscOptionsBegin()

605:    Input Parameters:
606: +  opt - option name
607: .  ltext - short string that describes the option
608: .  man - manual page with additional information on option
609: .  list - the possible choices
610: .  ntext - number of choices
611: -  defaultv - the default (current) value

613:    Output Parameter:
614: +  value - the index of the value to return
615: -  set - PETSC_TRUE if found, else PETSC_FALSE
616:    
617:    Level: intermediate

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

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

623:    Concepts: options database^list

625: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
626:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
627:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
628:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
629:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
630:           PetscOptionsList(), PetscOptionsEList()
631: @*/
632: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
633: {
635:   PetscInt       i;

638:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
639:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
640:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
641:     for (i=0; i<ntext; i++){
642:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
643:     }
644:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
645:   }
646:   return(0);
647: }

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

655:    Collective on the communicator passed in PetscOptionsBegin()

657:    Input Parameters:
658: +  opt - option name
659: .  text - short string that describes the option
660: -  man - manual page with additional information on option

662:    Output Parameter:
663: .  flg - whether that option was set or not
664:    
665:    Level: intermediate

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

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

671:     Concepts: options database^logical group

673: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
674:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
675:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
676:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
677:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
678:           PetscOptionsList(), PetscOptionsEList()
679: @*/
680: PetscErrorCode  PetscOptionsTruthGroupBegin(const char opt[],const char text[],const char man[],PetscTruth *flg)
681: {

685:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
686:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
687:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
688:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
689:   }
690:   return(0);
691: }

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

699:    Collective on the communicator passed in PetscOptionsBegin()

701:    Input Parameters:
702: +  opt - option name
703: .  text - short string that describes the option
704: -  man - manual page with additional information on option

706:    Output Parameter:
707: .  flg - PETSC_TRUE if found, else PETSC_FALSE
708:    
709:    Level: intermediate

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

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

715:     Concepts: options database^logical group

717: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
718:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
719:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
720:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
721:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
722:           PetscOptionsList(), PetscOptionsEList()
723: @*/
724: PetscErrorCode  PetscOptionsTruthGroup(const char opt[],const char text[],const char man[],PetscTruth *flg)
725: {

729:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
730:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
731:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
732:   }
733:   return(0);
734: }

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

742:    Collective on the communicator passed in PetscOptionsBegin()

744:    Input Parameters:
745: +  opt - option name
746: .  text - short string that describes the option
747: -  man - manual page with additional information on option

749:    Output Parameter:
750: .  flg - PETSC_TRUE if found, else PETSC_FALSE
751:    
752:    Level: intermediate

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

756:    Must follow a PetscOptionsTruthGroupBegin()

758:     Concepts: options database^logical group

760: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
761:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
762:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
763:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
764:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
765:           PetscOptionsList(), PetscOptionsEList()
766: @*/
767: PetscErrorCode  PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
768: {

772:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
773:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
774:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
775:   }
776:   return(0);
777: }

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

784:    Collective on the communicator passed in PetscOptionsBegin()

786:    Input Parameters:
787: +  opt - option name
788: .  text - short string that describes the option
789: -  man - manual page with additional information on option

791:    Output Parameter:
792: .  flg - PETSC_TRUE or PETSC_FALSE
793: .  set - PETSC_TRUE if found, else PETSC_FALSE

795:    Level: beginner

797:    Concepts: options database^logical

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

801: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
802:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
803:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
804:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
805:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
806:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
807:           PetscOptionsList(), PetscOptionsEList()
808: @*/
809: PetscErrorCode  PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
810: {
812:   PetscTruth     iset;

815:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
816:   if (!iset) {
817:     if (flg) *flg = deflt;
818:   }
819:   if (set) *set = iset;
820:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
821:     const char *v = PetscTruths[deflt];
822:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
823:   }
824:   return(0);
825: }

829: /*@C
830:    PetscOptionsRealArray - Gets an array of double values for a particular
831:    option in the database. The values must be separated with commas with 
832:    no intervening spaces. 

834:    Collective on the communicator passed in PetscOptionsBegin()

836:    Input Parameters:
837: +  opt - the option one is seeking
838: .  text - short string describing option
839: .  man - manual page for option
840: -  nmax - maximum number of values

842:    Output Parameter:
843: +  value - location to copy values
844: .  nmax - actual number of values found
845: -  set - PETSC_TRUE if found, else PETSC_FALSE

847:    Level: beginner

849:    Notes: 
850:    The user should pass in an array of doubles

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

854:    Concepts: options database^array of strings

856: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
857:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
858:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
859:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
860:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
861:           PetscOptionsList(), PetscOptionsEList()
862: @*/
863: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
864: {
866:   PetscInt       i;

869:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
870:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
871:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
872:     for (i=1; i<*n; i++) {
873:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
874:     }
875:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
876:   }
877:   return(0);
878: }


883: /*@C
884:    PetscOptionsIntArray - Gets an array of integers for a particular
885:    option in the database. The values must be separated with commas with 
886:    no intervening spaces. 

888:    Collective on the communicator passed in PetscOptionsBegin()

890:    Input Parameters:
891: +  opt - the option one is seeking
892: .  text - short string describing option
893: .  man - manual page for option
894: -  n - maximum number of values

896:    Output Parameter:
897: +  value - location to copy values
898: .  n - actual number of values found
899: -  set - PETSC_TRUE if found, else PETSC_FALSE

901:    Level: beginner

903:    Notes: 
904:    The user should pass in an array of integers

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

908:    Concepts: options database^array of strings

910: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
911:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
912:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
913:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
914:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
915:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
916: @*/
917: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscTruth *set)
918: {
920:   PetscInt       i;

923:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
924:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
925:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
926:     for (i=1; i<*n; i++) {
927:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
928:     }
929:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
930:   }
931:   return(0);
932: }

936: /*@C
937:    PetscOptionsStringArray - Gets an array of string values for a particular
938:    option in the database. The values must be separated with commas with 
939:    no intervening spaces. 

941:    Collective on the communicator passed in PetscOptionsBegin()

943:    Input Parameters:
944: +  opt - the option one is seeking
945: .  text - short string describing option
946: .  man - manual page for option
947: -  nmax - maximum number of strings

949:    Output Parameter:
950: +  value - location to copy strings
951: .  nmax - actual number of strings found
952: -  set - PETSC_TRUE if found, else PETSC_FALSE

954:    Level: beginner

956:    Notes: 
957:    The user should pass in an array of pointers to char, to hold all the
958:    strings returned by this function.

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

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

965:    Concepts: options database^array of strings

967: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
968:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
969:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
970:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
971:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
972:           PetscOptionsList(), PetscOptionsEList()
973: @*/
974: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
975: {

979:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
980:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
981:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
982:   }
983:   return(0);
984: }

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

993:    Collective on the communicator passed in PetscOptionsBegin()

995:    Input Parameters:
996: +  opt - the option one is seeking
997: .  text - short string describing option
998: .  man - manual page for option
999: -  nmax - maximum number of values

1001:    Output Parameter:
1002: +  value - location to copy values
1003: .  nmax - actual number of values found
1004: -  set - PETSC_TRUE if found, else PETSC_FALSE

1006:    Level: beginner

1008:    Notes: 
1009:    The user should pass in an array of doubles

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

1013:    Concepts: options database^array of strings

1015: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1016:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1017:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1018:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1019:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1020:           PetscOptionsList(), PetscOptionsEList()
1021: @*/
1022: PetscErrorCode  PetscOptionsTruthArray(const char opt[],const char text[],const char man[],PetscTruth value[],PetscInt *n,PetscTruth *set)
1023: {
1025:   PetscInt       i;

1028:   PetscOptionsGetTruthArray(PetscOptionsObject.prefix,opt,value,n,set);
1029:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1030:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1031:     for (i=1; i<*n; i++) {
1032:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1033:     }
1034:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
1035:   }
1036:   return(0);
1037: }


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

1046:    Collective on the communicator passed in PetscOptionsBegin()

1048:    Input Parameter:
1049: .   head - the heading text

1051:    
1052:    Level: intermediate

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

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

1058:    Concepts: options database^subheading

1060: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1061:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1062:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1063:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1064:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1065:           PetscOptionsList(), PetscOptionsEList()
1066: @*/
1067: PetscErrorCode  PetscOptionsHead(const char head[])
1068: {

1072:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1073:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1074:   }
1075:   return(0);
1076: }