Actual source code: aoptions.c

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

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

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

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

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

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

     45: PetscErrorCode PetscOptionsEnd_Private(void)
     46: {

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

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

     60:    Collective on the communicator passed in PetscOptionsBegin()

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

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

     73:    Level: beginner

     75:    Concepts: options database

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

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

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

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

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

    110:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    122:    Level: beginner

    124:    Concepts: options database^has int

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

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

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

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

    153:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    165:    Level: beginner

    167:    Concepts: options database^has int

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

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

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

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

    200:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    212:    Level: beginner

    214:    Concepts: options database^has int

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

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

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

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

    243:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    255:    Level: beginner

    257:    Concepts: options database^has int

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

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

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

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

    291:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    301:    Level: beginner

    303:    Concepts: options database^has int

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

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

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

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

    332:    Collective on the communicator passed in PetscOptionsBegin()

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

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

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

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

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

    354:    Concepts: options database^list

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

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

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

    380:    Collective on the communicator passed in PetscOptionsBegin()

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

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

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

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

    400:    Concepts: options database^list

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

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

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

    432:    Collective on the communicator passed in PetscOptionsBegin()

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

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

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

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

    448:     Concepts: options database^logical group

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

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

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

    476:    Collective on the communicator passed in PetscOptionsBegin()

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

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

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

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

    492:     Concepts: options database^logical group

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

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

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

    519:    Collective on the communicator passed in PetscOptionsBegin()

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

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

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

    533:    Must follow a PetscOptionsTruthGroupBegin()

    535:     Concepts: options database^logical group

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

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

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

    561:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    572:    Level: beginner

    574:    Concepts: options database^logical

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

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

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

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

    611:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    624:    Level: beginner

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

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

    631:    Concepts: options database^array of strings

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

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

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

    665:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    678:    Level: beginner

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

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

    685:    Concepts: options database^array of strings

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

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

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

    718:    Collective on the communicator passed in PetscOptionsBegin()

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

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

    731:    Level: beginner

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

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

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

    742:    Concepts: options database^array of strings

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

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

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

    770:    Collective on the communicator passed in PetscOptionsBegin()

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

    775:
    776:    Level: intermediate

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

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

    782:    Concepts: options database^subheading

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

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