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: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD} OptionType;
 23: typedef struct _p_Options* PetscOptions;
 24: struct _p_Options {
 25:   char         *option;
 26:   char         *text;
 27:   void         *data;
 28:   void         *edata;
 29:   char         *man;
 30:   int          arraylength;
 31:   PetscTruth   set;
 32:   OptionType   type;
 33:   PetscOptions next;
 34: };

 36: static struct {
 37:   PetscOptions    next;
 38:   char            *prefix,*mprefix;
 39:   char            *title;
 40:   MPI_Comm        comm;
 41:   PetscTruth      printhelp,changedmethod;
 42: }                                   PetscOptionsObject;
 43: PetscInt                            PetscOptionsPublishCount = 0;

 47: /*
 48:     Handles setting up the data structure in a call to PetscOptionsBegin()
 49: */
 50: PetscErrorCode PetscOptionsBegin_Private(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
 51: {

 55:   PetscOptionsObject.next          = 0;
 56:   PetscOptionsObject.comm          = comm;
 57:   PetscOptionsObject.changedmethod = PETSC_FALSE;
 58:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
 59:   PetscStrallocpy(title,&PetscOptionsObject.title);

 61:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
 62:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
 63:     (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
 64:   }
 65:   return(0);
 66: }

 68: /*
 69:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 70: */
 73: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],OptionType t,PetscOptions *amsopt)
 74: {
 75:   int          ierr;
 76:   PetscOptions next;

 79:   PetscNew(struct _p_Options,amsopt);
 80:   (*amsopt)->next  = 0;
 81:   (*amsopt)->set   = PETSC_FALSE;
 82:   (*amsopt)->type  = t;
 83:   (*amsopt)->data  = 0;
 84:   (*amsopt)->edata = 0;
 85:   PetscStrallocpy(text,&(*amsopt)->text);
 86:   PetscStrallocpy(opt,&(*amsopt)->option);
 87:   PetscStrallocpy(man,&(*amsopt)->man);

 89:   if (!PetscOptionsObject.next) {
 90:     PetscOptionsObject.next = *amsopt;
 91:   } else {
 92:     next = PetscOptionsObject.next;
 93:     while (next->next) next = next->next;
 94:     next->next = *amsopt;
 95:   }
 96:   return(0);
 97: }

101: PetscErrorCode PetscOptionsGetFromGUI()
102: {
104:   PetscOptions   next = PetscOptionsObject.next;
105:   char           str[512];

107:   (*PetscPrintf)(PetscOptionsObject.comm,"%s -------------------------------------------------\n",PetscOptionsObject.title);
108:   while (next) {
109:     switch (next->type) {
110:       case OPTION_HEAD:
111:         break;
112:       case OPTION_INT:
113:         PetscPrintf(PetscOptionsObject.comm,"-%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option,*(int*)next->data,next->text,next->man);
114:         scanf("%s\n",str);
115:         if (str[0] != '\n') {
116:           printf("changing value\n");
117:         }
118:         break;
119:     default:
120:       break;
121:     }
122:     next = next->next;
123:   }
124:   return(0);
125: }

129: PetscErrorCode PetscOptionsEnd_Private(void)
130: {
132:   PetscOptions   last;
133:   char           option[256],value[1024],tmp[32];
134:   PetscInt       j;


138:   /*  if (PetscOptionsObject.next) { 
139:     PetscOptionsGetFromGUI();
140:     }*/

142:   PetscStrfree(PetscOptionsObject.title); PetscOptionsObject.title  = 0;
143:   PetscStrfree(PetscOptionsObject.prefix); PetscOptionsObject.prefix = 0;

145:   /* reset counter to -2; this updates the screen with the new options for the selected method */
146:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;

148:   while (PetscOptionsObject.next) {
149:     if (PetscOptionsObject.next->set) {
150:       if (PetscOptionsObject.prefix) {
151:         PetscStrcpy(option,"-");
152:         PetscStrcat(option,PetscOptionsObject.prefix);
153:         PetscStrcat(option,PetscOptionsObject.next->option+1);
154:       } else {
155:         PetscStrcpy(option,PetscOptionsObject.next->option);
156:       }

158:       switch (PetscOptionsObject.next->type) {
159:         case OPTION_HEAD:
160:           break;
161:         case OPTION_INT:
162:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
163:           break;
164:         case OPTION_REAL:
165:           sprintf(value,"%g",*(PetscReal*)PetscOptionsObject.next->data);
166:           break;
167:         case OPTION_REAL_ARRAY:
168:           sprintf(value,"%g",((PetscReal*)PetscOptionsObject.next->data)[0]);
169:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
170:             sprintf(tmp,"%g",((PetscReal*)PetscOptionsObject.next->data)[j]);
171:             PetscStrcat(value,",");
172:             PetscStrcat(value,tmp);
173:           }
174:           break;
175:         case OPTION_LOGICAL:
176:           sprintf(value,"%d",*(PetscInt*)PetscOptionsObject.next->data);
177:           break;
178:         case OPTION_LIST:
179:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
180:           break;
181:         case OPTION_STRING: /* also handles string arrays */
182:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
183:           break;
184:       }
185:       PetscOptionsSetValue(option,value);
186:     }
187:     PetscStrfree(PetscOptionsObject.next->text);
188:     PetscStrfree(PetscOptionsObject.next->option);
189:     PetscFree(PetscOptionsObject.next->man);
190:     PetscFree(PetscOptionsObject.next->data);
191:     PetscFree(PetscOptionsObject.next->edata);
192:     last                    = PetscOptionsObject.next;
193:     PetscOptionsObject.next = PetscOptionsObject.next->next;
194:     PetscFree(last);
195:   }
196:   PetscOptionsObject.next = 0;
197:   return(0);
198: }

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

205:    Collective on the communicator passed in PetscOptionsBegin()

207:    Input Parameters:
208: +  opt - option name
209: .  text - short string that describes the option
210: .  man - manual page with additional information on option
211: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
212: -  defaultv - the default (current) value

214:    Output Parameter:
215: +  value - the  value to return
216: -  flg - PETSC_TRUE if found, else PETSC_FALSE

218:    Level: beginner

220:    Concepts: options database

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

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

226: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
227:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
228:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
229:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
230:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
231:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
232:           PetscOptionsList(), PetscOptionsEList()
233: @*/
234: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char **list,PetscEnum defaultv,PetscEnum *value,PetscTruth *set)
235: {
237:   PetscInt       ntext = 0;

240:   while (list[ntext++]) {
241:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
242:   }
243:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
244:   ntext -= 3;
245:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],(PetscInt*)value,set);
246:   return(0);
247: }

249: /* -------------------------------------------------------------------------------------------------------------*/
252: /*@C
253:    PetscOptionsInt - Gets the integer value for a particular option in the database.

255:    Collective on the communicator passed in PetscOptionsBegin()

257:    Input Parameters:
258: +  opt - option name
259: .  text - short string that describes the option
260: .  man - manual page with additional information on option
261: -  defaultv - the default (current) value

263:    Output Parameter:
264: +  value - the integer value to return
265: -  flg - PETSC_TRUE if found, else PETSC_FALSE

267:    Level: beginner

269:    Concepts: options database^has int

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

273: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
274:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
275:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
276:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
277:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
278:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
279:           PetscOptionsList(), PetscOptionsEList()
280: @*/
281: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscTruth *set)
282: {
284:   PetscOptions   amsopt;

287:   if (PetscOptionsPublishCount == 1) {
288:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
289:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
290:     *(PetscInt*)amsopt->data = defaultv;
291:   }
292:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
293:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
294:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
295:   }
296:   return(0);
297: }

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

304:    Collective on the communicator passed in PetscOptionsBegin()

306:    Input Parameters:
307: +  opt - option name
308: .  text - short string that describes the option
309: .  man - manual page with additional information on option
310: -  defaultv - the default (current) value

312:    Output Parameter:
313: +  value - the value to return
314: -  flg - PETSC_TRUE if found, else PETSC_FALSE

316:    Level: beginner

318:    Concepts: options database^has int

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

322: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
323:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
324:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
325:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
326:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
327:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
328:           PetscOptionsList(), PetscOptionsEList()
329: @*/
330: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscTruth *set)
331: {

335:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
336:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
337:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
338:   }
339:   return(0);
340: }

342: /*
343:      Publishes an AMS double field (with the default value in it) and with a name
344:    given by the text string
345: */
348: /*@C
349:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

351:    Collective on the communicator passed in PetscOptionsBegin()

353:    Input Parameters:
354: +  opt - option name
355: .  text - short string that describes the option
356: .  man - manual page with additional information on option
357: -  defaultv - the default (current) value

359:    Output Parameter:
360: +  value - the value to return
361: -  flg - PETSC_TRUE if found, else PETSC_FALSE

363:    Level: beginner

365:    Concepts: options database^has int

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

369: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
370:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
371:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
372:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
373:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
374:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
375:           PetscOptionsList(), PetscOptionsEList()
376: @*/
377: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscTruth *set)
378: {

382:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
383:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
384:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,man);
385:   }
386:   return(0);
387: }

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

394:    Collective on the communicator passed in PetscOptionsBegin()

396:    Input Parameters:
397: +  opt - option name
398: .  text - short string that describes the option
399: .  man - manual page with additional information on option
400: -  defaultv - the default (current) value

402:    Output Parameter:
403: +  value - the value to return
404: -  flg - PETSC_TRUE if found, else PETSC_FALSE

406:    Level: beginner

408:    Concepts: options database^has int

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

412: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
413:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
414:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
415:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
416:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
417:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
418:           PetscOptionsList(), PetscOptionsEList()
419: @*/
420: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
421: {

425: #if !defined(PETSC_USE_COMPLEX)
426:   PetscOptionsReal(opt,text,man,defaultv,value,set);
427: #else
428:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
429: #endif
430:   return(0);
431: }

433: /*
434:      Publishes an AMS logical field (with the default value in it) and with a name
435:    given by the text string
436: */
439: /*@C
440:    PetscOptionsName - Determines if a particular option is in the database

442:    Collective on the communicator passed in PetscOptionsBegin()

444:    Input Parameters:
445: +  opt - option name
446: .  text - short string that describes the option
447: -  man - manual page with additional information on option

449:    Output Parameter:
450: .  flg - PETSC_TRUE if found, else PETSC_FALSE

452:    Level: beginner

454:    Concepts: options database^has int

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

458: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
459:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
460:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
461:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
462:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
463:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
464:           PetscOptionsList(), PetscOptionsEList()
465: @*/
466: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscTruth *flg)
467: {

471:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
472:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
473:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
474:   }
475:   return(0);
476: }

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

483:    Collective on the communicator passed in PetscOptionsBegin()

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

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

496:    Level: intermediate
497:    
498:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

505:    Concepts: options database^list

507: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
508:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
509:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
510:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
511:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
512:           PetscOptionsList(), PetscOptionsEList()
513: @*/
514: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],PetscInt len,PetscTruth *set)
515: {

519:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
520:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
521:     PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list);
522:   }
523:   return(0);
524: }

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

531:    Collective on the communicator passed in PetscOptionsBegin()

533:    Input Parameters:
534: +  opt - option name
535: .  ltext - short string that describes the option
536: .  man - manual page with additional information on option
537: .  list - the possible choices
538: .  ntext - number of choices
539: -  defaultv - the default (current) value

541:    Output Parameter:
542: +  value - the index of the value to return
543: -  set - PETSC_TRUE if found, else PETSC_FALSE
544:    
545:    Level: intermediate

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

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

551:    Concepts: options database^list

553: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
554:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
555:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
556:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
557:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
558:           PetscOptionsList(), PetscOptionsEList()
559: @*/
560: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char **list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscTruth *set)
561: {
563:   PetscInt       i;

566:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
567:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
568:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
569:     for (i=0; i<ntext; i++){
570:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
571:     }
572:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"\n");
573:   }
574:   return(0);
575: }

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

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

590:    Output Parameter:
591: .  flg - whether that option was set or not
592:    
593:    Level: intermediate

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

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

599:     Concepts: options database^logical group

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

613:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
614:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
615:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
616:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
617:   }
618:   return(0);
619: }

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

627:    Collective on the communicator passed in PetscOptionsBegin()

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

634:    Output Parameter:
635: .  flg - PETSC_TRUE if found, else PETSC_FALSE
636:    
637:    Level: intermediate

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

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

643:     Concepts: options database^logical group

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

657:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
658:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
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:      PetscOptionsTruthGroupEnd - Last in a series of logical queries on the options database for
668:        which only a single value can be true.

670:    Collective on the communicator passed in PetscOptionsBegin()

672:    Input Parameters:
673: +  opt - option name
674: .  text - short string that describes the option
675: -  man - manual page with additional information on option

677:    Output Parameter:
678: .  flg - PETSC_TRUE if found, else PETSC_FALSE
679:    
680:    Level: intermediate

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

684:    Must follow a PetscOptionsTruthGroupBegin()

686:     Concepts: options database^logical group

688: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
689:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
690:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
691:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
692:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
693:           PetscOptionsList(), PetscOptionsEList()
694: @*/
695: PetscErrorCode  PetscOptionsTruthGroupEnd(const char opt[],const char text[],const char man[],PetscTruth *flg)
696: {

700:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
701:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
702:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
703:   }
704:   return(0);
705: }

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

712:    Collective on the communicator passed in PetscOptionsBegin()

714:    Input Parameters:
715: +  opt - option name
716: .  text - short string that describes the option
717: -  man - manual page with additional information on option

719:    Output Parameter:
720: .  flg - PETSC_TRUE or PETSC_FALSE
721: .  set - PETSC_TRUE if found, else PETSC_FALSE

723:    Level: beginner

725:    Concepts: options database^logical

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

729: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
730:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
731:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
732:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
733:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
734:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
735:           PetscOptionsList(), PetscOptionsEList()
736: @*/
737: PetscErrorCode  PetscOptionsTruth(const char opt[],const char text[],const char man[],PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
738: {
740:   PetscTruth     iset;

743:   PetscOptionsGetTruth(PetscOptionsObject.prefix,opt,flg,&iset);
744:   if (!iset) {
745:     if (flg) *flg = deflt;
746:   }
747:   if (set) *set = iset;
748:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
749:     const char *v = PetscTruths[deflt];
750:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,man);
751:   }
752:   return(0);
753: }

757: /*@C
758:    PetscOptionsRealArray - Gets an array of double values for a particular
759:    option in the database. The values must be separated with commas with 
760:    no intervening spaces. 

762:    Collective on the communicator passed in PetscOptionsBegin()

764:    Input Parameters:
765: +  opt - the option one is seeking
766: .  text - short string describing option
767: .  man - manual page for option
768: -  nmax - maximum number of values

770:    Output Parameter:
771: +  value - location to copy values
772: .  nmax - actual number of values found
773: -  set - PETSC_TRUE if found, else PETSC_FALSE

775:    Level: beginner

777:    Notes: 
778:    The user should pass in an array of doubles

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

782:    Concepts: options database^array of strings

784: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
785:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
786:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
787:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
788:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
789:           PetscOptionsList(), PetscOptionsEList()
790: @*/
791: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscTruth *set)
792: {
794:   PetscInt       i;

797:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
798:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
799:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
800:     for (i=1; i<*n; i++) {
801:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
802:     }
803:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
804:   }
805:   return(0);
806: }


811: /*@C
812:    PetscOptionsIntArray - Gets an array of integers for a particular
813:    option in the database. The values must be separated with commas with 
814:    no intervening spaces. 

816:    Collective on the communicator passed in PetscOptionsBegin()

818:    Input Parameters:
819: +  opt - the option one is seeking
820: .  text - short string describing option
821: .  man - manual page for option
822: -  nmax - maximum number of values

824:    Output Parameter:
825: +  value - location to copy values
826: .  nmax - actual number of values found
827: -  set - PETSC_TRUE if found, else PETSC_FALSE

829:    Level: beginner

831:    Notes: 
832:    The user should pass in an array of integers

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

836:    Concepts: options database^array of strings

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

851:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
852:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
853:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
854:     for (i=1; i<*n; i++) {
855:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
856:     }
857:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,man);
858:   }
859:   return(0);
860: }

864: /*@C
865:    PetscOptionsStringArray - Gets an array of string values for a particular
866:    option in the database. The values must be separated with commas with 
867:    no intervening spaces. 

869:    Collective on the communicator passed in PetscOptionsBegin()

871:    Input Parameters:
872: +  opt - the option one is seeking
873: .  text - short string describing option
874: .  man - manual page for option
875: -  nmax - maximum number of strings

877:    Output Parameter:
878: +  value - location to copy strings
879: .  nmax - actual number of strings found
880: -  set - PETSC_TRUE if found, else PETSC_FALSE

882:    Level: beginner

884:    Notes: 
885:    The user should pass in an array of pointers to char, to hold all the
886:    strings returned by this function.

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

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

893:    Concepts: options database^array of strings

895: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
896:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
897:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
898:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
899:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
900:           PetscOptionsList(), PetscOptionsEList()
901: @*/
902: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscTruth *set)
903: {

907:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
908:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
909:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,man);
910:   }
911:   return(0);
912: }


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

921:    Collective on the communicator passed in PetscOptionsBegin()

923:    Input Parameter:
924: .   head - the heading text

926:    
927:    Level: intermediate

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

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

933:    Concepts: options database^subheading

935: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
936:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
937:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
938:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
939:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
940:           PetscOptionsList(), PetscOptionsEList()
941: @*/
942: PetscErrorCode  PetscOptionsHead(const char head[])
943: {

947:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
948:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
949:   }
950:   return(0);
951: }