Date: 2013-07-02T14:39:01+00:00

Actual source code: aoptions.c
petsc-3.4.2 2013-07-02

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

      6: */

      8: #include <petsc-private/petscimpl.h>        /*I  "petscsys.h"   I*/
      9: #include <petscviewer.h>

     11: #define ManSection(str) ((str) ? (str) : "None")

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

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

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

     32:   PetscOptionsObject.next          = 0;
     33:   PetscOptionsObject.comm          = comm;
     34:   PetscOptionsObject.changedmethod = PETSC_FALSE;

     36:   PetscFree(PetscOptionsObject.prefix);
     37:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
     38:   PetscFree(PetscOptionsObject.title);
     39:   PetscStrallocpy(title,&PetscOptionsObject.title);

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

     52: /*
     53:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
     54: */
     55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
     56: {
     58:   char           title[256];
     59:   PetscBool      flg;

     63:   PetscOptionsObject.object         = obj;
     64:   PetscOptionsObject.alreadyprinted = obj->optionsprinted;

     66:   PetscStrcmp(obj->description,obj->class_name,&flg);
     67:   if (flg) {
     68:     PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
     69:   } else {
     70:     PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
     71:   }
     72:   PetscOptionsBegin_Private(obj->comm,obj->prefix,title,obj->mansec);
     73:   return(0);
     74: }

     76: /*
     77:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
     78: */
     81: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
     82: {
     83:   int          ierr;
     84:   PetscOptions next;
     85:   PetscBool    valid;

     88:   PetscOptionsValidKey(opt,&valid);
     89:   if (!valid) SETERRQ1(PETSC_COMM_WORLD,PETSC_ERR_ARG_INCOMP,"The option '%s' is not a valid key",opt);

     91:   PetscNew(struct _n_PetscOptions,amsopt);
     92:   (*amsopt)->next = 0;
     93:   (*amsopt)->set  = PETSC_FALSE;
     94:   (*amsopt)->type = t;
     95:   (*amsopt)->data = 0;

     97:   PetscStrallocpy(text,&(*amsopt)->text);
     98:   PetscStrallocpy(opt,&(*amsopt)->option);
     99:   PetscStrallocpy(man,&(*amsopt)->man);

    101:   if (!PetscOptionsObject.next) PetscOptionsObject.next = *amsopt;
    102:   else {
    103:     next = PetscOptionsObject.next;
    104:     while (next->next) next = next->next;
    105:     next->next = *amsopt;
    106:   }
    107:   return(0);
    108: }

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

    115:     Collective on MPI_Comm

    117:    Input Parameters:
    118: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
    119: .     n - length of the string, must be the same on all processes
    120: -     str - location to store input

    122:     Bugs:
    123: .   Assumes process 0 of the given communicator has access to stdin

    125: */
    126: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
    127: {
    128:   size_t         i;
    129:   char           c;
    130:   PetscMPIInt    rank,nm;

    134:   MPI_Comm_rank(comm,&rank);
    135:   if (!rank) {
    136:     c = (char) getchar();
    137:     i = 0;
    138:     while (c != '\n' && i < n-1) {
    139:       str[i++] = c;
    140:       c = (char)getchar();
    141:     }
    142:     str[i] = 0;
    143:   }
    144:   PetscMPIIntCast(n,&nm);
    145:   MPI_Bcast(str,nm,MPI_CHAR,0,comm);
    146:   return(0);
    147: }

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

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

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

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

    164: */
    165: PetscErrorCode PetscOptionsGetFromTextInput()
    166: {
    168:   PetscOptions   next = PetscOptionsObject.next;
    169:   char           str[512];
    170:   PetscInt       id;
    171:   PetscReal      ir,*valr;
    172:   PetscInt       *vald;
    173:   size_t         i;

    175:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
    176:   while (next) {
    177:     switch (next->type) {
    178:     case OPTION_HEAD:
    179:       break;
    180:     case OPTION_INT_ARRAY:
    181:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
    182:       vald = (PetscInt*) next->data;
    183:       for (i=0; i<next->arraylength; i++) {
    184:         PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
    185:         if (i < next->arraylength-1) {
    186:           PetscPrintf(PETSC_COMM_WORLD,",");
    187:         }
    188:       }
    189:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
    190:       PetscScanString(PETSC_COMM_WORLD,512,str);
    191:       if (str[0]) {
    192:         PetscToken token;
    193:         PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
    194:         size_t     len;
    195:         char       *value;
    196:         PetscBool  foundrange;

    198:         next->set = PETSC_TRUE;
    199:         value     = str;
    200:         PetscTokenCreate(value,',',&token);
    201:         PetscTokenFind(token,&value);
    202:         while (n < nmax) {
    203:           if (!value) break;

    205:           /* look for form  d-D where d and D are integers */
    206:           foundrange = PETSC_FALSE;
    207:           PetscStrlen(value,&len);
    208:           if (value[0] == '-') i=2;
    209:           else i=1;
    210:           for (;i<len; i++) {
    211:             if (value[i] == '-') {
    212:               if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
    213:               value[i] = 0;
    214:               PetscOptionsStringToInt(value,&start);
    215:               PetscOptionsStringToInt(value+i+1,&end);
    216:               if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1);
    217:               if (n + end - start - 1 >= nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,nmax-n,start,end);
    218:               for (; start<end; start++) {
    219:                 *dvalue = start; dvalue++;n++;
    220:               }
    221:               foundrange = PETSC_TRUE;
    222:               break;
    223:             }
    224:           }
    225:           if (!foundrange) {
    226:             PetscOptionsStringToInt(value,dvalue);
    227:             dvalue++;
    228:             n++;
    229:           }
    230:           PetscTokenFind(token,&value);
    231:         }
    232:         PetscTokenDestroy(&token);
    233:       }
    234:       break;
    235:     case OPTION_REAL_ARRAY:
    236:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
    237:       valr = (PetscReal*) next->data;
    238:       for (i=0; i<next->arraylength; i++) {
    239:         PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
    240:         if (i < next->arraylength-1) {
    241:           PetscPrintf(PETSC_COMM_WORLD,",");
    242:         }
    243:       }
    244:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
    245:       PetscScanString(PETSC_COMM_WORLD,512,str);
    246:       if (str[0]) {
    247:         PetscToken token;
    248:         PetscInt   n = 0,nmax = next->arraylength;
    249:         PetscReal  *dvalue = (PetscReal*)next->data;
    250:         char       *value;

    252:         next->set = PETSC_TRUE;
    253:         value     = str;
    254:         PetscTokenCreate(value,',',&token);
    255:         PetscTokenFind(token,&value);
    256:         while (n < nmax) {
    257:           if (!value) break;
    258:           PetscOptionsStringToReal(value,dvalue);
    259:           dvalue++;
    260:           n++;
    261:           PetscTokenFind(token,&value);
    262:         }
    263:         PetscTokenDestroy(&token);
    264:       }
    265:       break;
    266:     case OPTION_INT:
    267:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
    268:       PetscScanString(PETSC_COMM_WORLD,512,str);
    269:       if (str[0]) {
    270: #if defined(PETSC_USE_64BIT_INDICES)
    271:         sscanf(str,"%lld",&id);
    272: #else
    273:         sscanf(str,"%d",&id);
    274: #endif
    275:         next->set = PETSC_TRUE;

    277:         *((PetscInt*)next->data) = id;
    278:       }
    279:       break;
    280:     case OPTION_REAL:
    281:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
    282:       PetscScanString(PETSC_COMM_WORLD,512,str);
    283:       if (str[0]) {
    284: #if defined(PETSC_USE_REAL_SINGLE)
    285:         sscanf(str,"%e",&ir);
    286: #elif defined(PETSC_USE_REAL_DOUBLE)
    287:         sscanf(str,"%le",&ir);
    288: #elif defined(PETSC_USE_REAL___FLOAT128)
    289:         ir = strtoflt128(str,0);
    290: #else
    291:         SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
    292: #endif
    293:         next->set                 = PETSC_TRUE;
    294:         *((PetscReal*)next->data) = ir;
    295:       }
    296:       break;
    297:     case OPTION_LOGICAL:
    298:     case OPTION_STRING:
    299:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,(char*)next->data,next->text,next->man);
    300:       PetscScanString(PETSC_COMM_WORLD,512,str);
    301:       if (str[0]) {
    302:         next->set = PETSC_TRUE;

    304:         PetscStrcpy((char*)next->data,str);
    305:       }
    306:       break;
    307:     case OPTION_LIST:
    308:       PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
    309:       PetscScanString(PETSC_COMM_WORLD,512,str);
    310:       if (str[0]) {
    311:         PetscOptionsObject.changedmethod = PETSC_TRUE;
    312:         next->set = PETSC_TRUE;
    313:         PetscStrcpy((char*)next->data,str);
    314:       }
    315:       break;
    316:     default:
    317:       break;
    318:     }
    319:     next = next->next;
    320:   }
    321:   return(0);
    322: }

    324: #if defined(PETSC_HAVE_AMS)
    325: #include <petscviewerams.h>

    327: static int count = 0;

    331: PetscErrorCode PetscOptionsAMSDestroy(void)
    332: {
    334:   AMS_Comm       acomm = -1;
    335:   AMS_Memory     amem  = -1;
    336:   char           options[16];
    337:   const char     *string = "Exit";

    339:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
    340:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
    341:   sprintf(options,"Options_%d",count++);
    342:   PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
    343:   PetscStackCallAMS(AMS_Memory_add_field,(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));

    345:   PetscStackCallAMS(AMS_Memory_take_access,(amem));
    346:   PetscStackCallAMS(AMS_Memory_publish,(amem));
    347:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
    348:   /* wait until accessor has unlocked the memory */
    349:   PetscStackCallAMS(AMS_Memory_lock,(amem,0));
    350:   PetscStackCallAMS(AMS_Memory_take_access,(amem));
    351:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
    352:   PetscStackCallAMS(AMS_Memory_destroy,(amem));
    353:   return(0);
    354: }

    358: /*
    359:     PetscOptionsAMSInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the AMS

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

    367: */
    368: PetscErrorCode PetscOptionsAMSInput()
    369: {
    371:   PetscOptions   next     = PetscOptionsObject.next;
    372:   static int     mancount = 0;
    373:   char           options[16];
    374:   AMS_Comm       acomm         = -1;
    375:   AMS_Memory     amem          = -1;
    376:   PetscBool      changedmethod = PETSC_FALSE;
    377:   char           manname[16];

    379:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
    380:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
    381:   sprintf(options,"Options_%d",count++);
    382:   PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
    383:   PetscStackCallAMS(AMS_Memory_take_access,(amem));

    385:   PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* AMS will change this, so cannot pass prefix directly */

    387:   PetscStackCallAMS(AMS_Memory_add_field,(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));
    388:   /* PetscStackCallAMS(AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF)); */
    389:   PetscStackCallAMS(AMS_Memory_add_field,(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));

    391:   while (next) {
    392:     PetscStackCallAMS(AMS_Memory_add_field,(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    393:      PetscMalloc(sizeof(char*),&next->pman);

    395:     *(char**)next->pman = next->man;
    396:     sprintf(manname,"man_%d",mancount++);
    397:     PetscStackCallAMS(AMS_Memory_add_field,(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));

    399:     switch (next->type) {
    400:     case OPTION_HEAD:
    401:       break;
    402:     case OPTION_INT_ARRAY:
    403:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    404:       break;
    405:     case OPTION_REAL_ARRAY:
    406:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    407:       break;
    408:     case OPTION_INT:
    409:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    410:       break;
    411:     case OPTION_REAL:
    412:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    413:       break;
    414:     case OPTION_LOGICAL:
    415:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    416:       break;
    417:     case OPTION_LOGICAL_ARRAY:
    418:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    419:       break;
    420:     case OPTION_STRING:
    421:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    422:       break;
    423:     case OPTION_STRING_ARRAY:
    424:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    425:       break;
    426:     case OPTION_LIST:
    427:       {PetscInt ntext;
    428:       char      ldefault[128];
    429:       PetscStrcpy(ldefault,"DEFAULT:");
    430:       PetscStrcat(ldefault,next->text);
    431:       PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    432:       PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
    433:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    434:       break;}
    435:     case OPTION_ELIST:
    436:       {PetscInt ntext = next->nlist;
    437:       char      ldefault[128];
    438:       PetscStrcpy(ldefault,"DEFAULT:");
    439:       PetscStrcat(ldefault,next->text);
    440:       PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    441:       PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
    442:       PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
    443:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
    444:       break;}
    445:     default:
    446:       break;
    447:     }
    448:     next = next->next;
    449:   }

    451:   PetscStackCallAMS(AMS_Memory_publish,(amem));
    452:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
    453:   /* wait until accessor has unlocked the memory */
    454:   PetscStackCallAMS(AMS_Memory_lock,(amem,0));
    455:   PetscStackCallAMS(AMS_Memory_take_access,(amem));

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

    460:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
    461:   PetscStackCallAMS(AMS_Memory_destroy,(amem));
    462:   return(0);
    463: }
    464: #endif

    468: PetscErrorCode PetscOptionsEnd_Private(void)
    469: {
    471:   PetscOptions   last;
    472:   char           option[256],value[1024],tmp[32];
    473:   size_t         j;

    476:   if (PetscOptionsObject.next) {
    477:     if (!PetscOptionsPublishCount) {
    478: #if defined(PETSC_HAVE_AMS)
    479:       PetscOptionsAMSInput();
    480: #else
    481:       PetscOptionsGetFromTextInput();
    482: #endif
    483:     }
    484:   }

    486:   PetscFree(PetscOptionsObject.title);
    487:   PetscFree(PetscOptionsObject.prefix);

    489:   /* reset counter to -2; this updates the screen with the new options for the selected method */
    490:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
    491:   /* reset alreadyprinted flag */
    492:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;
    493:   if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
    494:   PetscOptionsObject.object = NULL;

    496:   while (PetscOptionsObject.next) {
    497:     if (PetscOptionsObject.next->set) {
    498:       if (PetscOptionsObject.prefix) {
    499:         PetscStrcpy(option,"-");
    500:         PetscStrcat(option,PetscOptionsObject.prefix);
    501:         PetscStrcat(option,PetscOptionsObject.next->option+1);
    502:       } else {
    503:         PetscStrcpy(option,PetscOptionsObject.next->option);
    504:       }

    506:       switch (PetscOptionsObject.next->type) {
    507:       case OPTION_HEAD:
    508:         break;
    509:       case OPTION_INT_ARRAY:
    510:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
    511:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
    512:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
    513:           PetscStrcat(value,",");
    514:           PetscStrcat(value,tmp);
    515:         }
    516:         break;
    517:       case OPTION_INT:
    518:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
    519:         break;
    520:       case OPTION_REAL:
    521:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
    522:         break;
    523:       case OPTION_REAL_ARRAY:
    524:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
    525:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
    526:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
    527:           PetscStrcat(value,",");
    528:           PetscStrcat(value,tmp);
    529:         }
    530:         break;
    531:       case OPTION_LOGICAL:
    532:         sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
    533:         break;
    534:       case OPTION_LOGICAL_ARRAY:
    535:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
    536:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
    537:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
    538:           PetscStrcat(value,",");
    539:           PetscStrcat(value,tmp);
    540:         }
    541:         break;
    542:       case OPTION_LIST:
    543:       case OPTION_ELIST:
    544:         PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
    545:         break;
    546:       case OPTION_STRING:
    547:         PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
    548:       case OPTION_STRING_ARRAY:
    549:         sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
    550:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
    551:           sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
    552:           PetscStrcat(value,",");
    553:           PetscStrcat(value,tmp);
    554:         }
    555:         break;
    556:       }
    557:       PetscOptionsSetValue(option,value);
    558:     }
    559:     PetscFree(PetscOptionsObject.next->text);
    560:     PetscFree(PetscOptionsObject.next->option);
    561:     PetscFree(PetscOptionsObject.next->man);
    562:     PetscFree(PetscOptionsObject.next->data);
    563:     PetscFree(PetscOptionsObject.next->edata);

    565:     last                    = PetscOptionsObject.next;
    566:     PetscOptionsObject.next = PetscOptionsObject.next->next;
    567:     PetscFree(last);
    568:   }
    569:   PetscOptionsObject.next = 0;
    570:   return(0);
    571: }

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

    578:    Logically Collective on the communicator passed in PetscOptionsBegin()

    580:    Input Parameters:
    581: +  opt - option name
    582: .  text - short string that describes the option
    583: .  man - manual page with additional information on option
    584: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    585: -  defaultv - the default (current) value

    587:    Output Parameter:
    588: +  value - the  value to return
    589: -  set - PETSC_TRUE if found, else PETSC_FALSE

    591:    Level: beginner

    593:    Concepts: options database

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

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

    599: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    600:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    601:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    602:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    603:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    604:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    605:           PetscOptionsList(), PetscOptionsEList()
    606: @*/
    607: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool  *set)
    608: {
    610:   PetscInt       ntext = 0;
    611:   PetscInt       tval;
    612:   PetscBool      tflg;

    615:   while (list[ntext++]) {
    616:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    617:   }
    618:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    619:   ntext -= 3;
    620:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
    621:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
    622:   if (tflg) *value = (PetscEnum)tval;
    623:   if (set)  *set   = tflg;
    624:   return(0);
    625: }

    627: /* -------------------------------------------------------------------------------------------------------------*/
    630: /*@C
    631:    PetscOptionsInt - Gets the integer value for a particular option in the database.

    633:    Logically Collective on the communicator passed in PetscOptionsBegin()

    635:    Input Parameters:
    636: +  opt - option name
    637: .  text - short string that describes the option
    638: .  man - manual page with additional information on option
    639: -  defaultv - the default (current) value

    641:    Output Parameter:
    642: +  value - the integer value to return
    643: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    645:    Level: beginner

    647:    Concepts: options database^has int

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

    651: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    652:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    653:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    654:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    655:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    656:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    657:           PetscOptionsList(), PetscOptionsEList()
    658: @*/
    659: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool  *set)
    660: {
    662:   PetscOptions   amsopt;

    665:   if (!PetscOptionsPublishCount) {
    666:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
    667:     PetscMalloc(sizeof(PetscInt),&amsopt->data);

    669:     *(PetscInt*)amsopt->data = defaultv;
    670:   }
    671:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
    672:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    673:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
    674:   }
    675:   return(0);
    676: }

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

    683:    Logically Collective on the communicator passed in PetscOptionsBegin()

    685:    Input Parameters:
    686: +  opt - option name
    687: .  text - short string that describes the option
    688: .  man - manual page with additional information on option
    689: .  defaultv - the default (current) value
    690: -  len - length of the result string including null terminator

    692:    Output Parameter:
    693: +  value - the value to return
    694: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    696:    Level: beginner

    698:    Concepts: options database^has int

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

    702:    Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls).

    704: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    705:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    706:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
    707:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    708:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    709:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    710:           PetscOptionsList(), PetscOptionsEList()
    711: @*/
    712: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool  *set)
    713: {
    715:   PetscOptions   amsopt;

    718:   if (!PetscOptionsPublishCount) {
    719:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
    720:     PetscMalloc(sizeof(char*),&amsopt->data);

    722:     *(const char**)amsopt->data = defaultv;
    723:   }
    724:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
    725:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    726:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
    727:   }
    728:   return(0);
    729: }

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

    736:    Logically Collective on the communicator passed in PetscOptionsBegin()

    738:    Input Parameters:
    739: +  opt - option name
    740: .  text - short string that describes the option
    741: .  man - manual page with additional information on option
    742: -  defaultv - the default (current) value

    744:    Output Parameter:
    745: +  value - the value to return
    746: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    748:    Level: beginner

    750:    Concepts: options database^has int

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

    754: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    755:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    756:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    757:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    758:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    759:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    760:           PetscOptionsList(), PetscOptionsEList()
    761: @*/
    762: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool  *set)
    763: {
    765:   PetscOptions   amsopt;

    768:   if (!PetscOptionsPublishCount) {
    769:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
    770:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

    772:     *(PetscReal*)amsopt->data = defaultv;
    773:   }
    774:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
    775:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    776:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
    777:   }
    778:   return(0);
    779: }

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

    786:    Logically Collective on the communicator passed in PetscOptionsBegin()

    788:    Input Parameters:
    789: +  opt - option name
    790: .  text - short string that describes the option
    791: .  man - manual page with additional information on option
    792: -  defaultv - the default (current) value

    794:    Output Parameter:
    795: +  value - the value to return
    796: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    798:    Level: beginner

    800:    Concepts: options database^has int

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

    804: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    805:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    806:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    807:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    808:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    809:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    810:           PetscOptionsList(), PetscOptionsEList()
    811: @*/
    812: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool  *set)
    813: {

    817: #if !defined(PETSC_USE_COMPLEX)
    818:   PetscOptionsReal(opt,text,man,defaultv,value,set);
    819: #else
    820:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
    821: #endif
    822:   return(0);
    823: }

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

    831:    Logically Collective on the communicator passed in PetscOptionsBegin()

    833:    Input Parameters:
    834: +  opt - option name
    835: .  text - short string that describes the option
    836: -  man - manual page with additional information on option

    838:    Output Parameter:
    839: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    841:    Level: beginner

    843:    Concepts: options database^has int

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

    847: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    848:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    849:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    850:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    851:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    852:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    853:           PetscOptionsList(), PetscOptionsEList()
    854: @*/
    855: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)
    856: {
    858:   PetscOptions   amsopt;

    861:   if (!PetscOptionsPublishCount) {
    862:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
    863:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    865:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    866:   }
    867:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
    868:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    869:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
    870:   }
    871:   return(0);
    872: }

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

    879:    Logically Collective on the communicator passed in PetscOptionsBegin()

    881:    Input Parameters:
    882: +  opt - option name
    883: .  text - short string that describes the option
    884: .  man - manual page with additional information on option
    885: .  list - the possible choices
    886: .  defaultv - the default (current) value
    887: -  len - the length of the character array value

    889:    Output Parameter:
    890: +  value - the value to return
    891: -  set - PETSC_TRUE if found, else PETSC_FALSE

    893:    Level: intermediate

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

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

    899:    To get a listing of all currently specified options,
    900:     see PetscOptionsView() or PetscOptionsGetAll()

    902:    Concepts: options database^list

    904: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    905:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    906:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    907:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    908:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    909:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsEnum()
    910: @*/
    911: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool  *set)
    912: {
    914:   PetscOptions   amsopt;

    917:   if (!PetscOptionsPublishCount) {
    918:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
    919:     PetscMalloc(sizeof(char*),&amsopt->data);

    921:     *(const char**)amsopt->data = defaultv;

    923:     amsopt->flist = list;
    924:   }
    925:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
    926:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    927:     PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
    928:   }
    929:   return(0);
    930: }

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

    937:    Logically Collective on the communicator passed in PetscOptionsBegin()

    939:    Input Parameters:
    940: +  opt - option name
    941: .  ltext - short string that describes the option
    942: .  man - manual page with additional information on option
    943: .  list - the possible choices
    944: .  ntext - number of choices
    945: -  defaultv - the default (current) value

    947:    Output Parameter:
    948: +  value - the index of the value to return
    949: -  set - PETSC_TRUE if found, else PETSC_FALSE

    951:    Level: intermediate

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

    955:    See PetscOptionsList() for when the choices are given in a PetscFunctionList()

    957:    Concepts: options database^list

    959: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    960:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    961:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    962:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    963:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    964:           PetscOptionsList(), PetscOptionsEnum()
    965: @*/
    966: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool  *set)
    967: {
    969:   PetscInt       i;
    970:   PetscOptions   amsopt;

    973:   if (!PetscOptionsPublishCount) {
    974:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
    975:     PetscMalloc(sizeof(char*),&amsopt->data);

    977:     *(const char**)amsopt->data = defaultv;

    979:     amsopt->list  = list;
    980:     amsopt->nlist = ntext;
    981:   }
    982:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
    983:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    984:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
    985:     for (i=0; i<ntext; i++) {
    986:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
    987:     }
    988:     (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
    989:   }
    990:   return(0);
    991: }

    995: /*@C
    996:      PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
    997:        which at most a single value can be true.

    999:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1001:    Input Parameters:
    1002: +  opt - option name
    1003: .  text - short string that describes the option
    1004: -  man - manual page with additional information on option

    1006:    Output Parameter:
    1007: .  flg - whether that option was set or not

    1009:    Level: intermediate

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

    1013:    Must be followed by 0 or more PetscOptionsBoolGroup()s and PetscOptionsBoolGroupEnd()

    1015:     Concepts: options database^logical group

    1017: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1018:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1019:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1020:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1021:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1022:           PetscOptionsList(), PetscOptionsEList()
    1023: @*/
    1024: PetscErrorCode  PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)
    1025: {
    1027:   PetscOptions   amsopt;

    1030:   if (!PetscOptionsPublishCount) {
    1031:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
    1032:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1034:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1035:   }
    1036:   *flg = PETSC_FALSE;
    1037:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
    1038:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1039:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
    1040:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
    1041:   }
    1042:   return(0);
    1043: }

    1047: /*@C
    1048:      PetscOptionsBoolGroup - One in a series of logical queries on the options database for
    1049:        which at most a single value can be true.

    1051:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1053:    Input Parameters:
    1054: +  opt - option name
    1055: .  text - short string that describes the option
    1056: -  man - manual page with additional information on option

    1058:    Output Parameter:
    1059: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1061:    Level: intermediate

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

    1065:    Must follow a PetscOptionsBoolGroupBegin() and preceded a PetscOptionsBoolGroupEnd()

    1067:     Concepts: options database^logical group

    1069: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1070:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1071:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1072:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1073:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1074:           PetscOptionsList(), PetscOptionsEList()
    1075: @*/
    1076: PetscErrorCode  PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)
    1077: {
    1079:   PetscOptions   amsopt;

    1082:   if (!PetscOptionsPublishCount) {
    1083:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
    1084:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1086:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1087:   }
    1088:   *flg = PETSC_FALSE;
    1089:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
    1090:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1091:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
    1092:   }
    1093:   return(0);
    1094: }

    1098: /*@C
    1099:      PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
    1100:        which at most a single value can be true.

    1102:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1104:    Input Parameters:
    1105: +  opt - option name
    1106: .  text - short string that describes the option
    1107: -  man - manual page with additional information on option

    1109:    Output Parameter:
    1110: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1112:    Level: intermediate

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

    1116:    Must follow a PetscOptionsBoolGroupBegin()

    1118:     Concepts: options database^logical group

    1120: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1121:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1122:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1123:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1124:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1125:           PetscOptionsList(), PetscOptionsEList()
    1126: @*/
    1127: PetscErrorCode  PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)
    1128: {
    1130:   PetscOptions   amsopt;

    1133:   if (!PetscOptionsPublishCount) {
    1134:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
    1135:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1137:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1138:   }
    1139:   *flg = PETSC_FALSE;
    1140:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
    1141:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1142:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
    1143:   }
    1144:   return(0);
    1145: }

    1149: /*@C
    1150:    PetscOptionsBool - Determines if a particular option is in the database with a true or false

    1152:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1154:    Input Parameters:
    1155: +  opt - option name
    1156: .  text - short string that describes the option
    1157: -  man - manual page with additional information on option

    1159:    Output Parameter:
    1160: .  flg - PETSC_TRUE or PETSC_FALSE
    1161: .  set - PETSC_TRUE if found, else PETSC_FALSE

    1163:    Level: beginner

    1165:    Concepts: options database^logical

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

    1169: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1170:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1171:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1172:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1173:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1174:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1175:           PetscOptionsList(), PetscOptionsEList()
    1176: @*/
    1177: PetscErrorCode  PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool  *flg,PetscBool  *set)
    1178: {
    1180:   PetscBool      iset;
    1181:   PetscOptions   amsopt;

    1184:   if (!PetscOptionsPublishCount) {
    1185:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
    1186:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1188:     *(PetscBool*)amsopt->data = deflt;
    1189:   }
    1190:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
    1191:   if (!iset) {
    1192:     if (flg) *flg = deflt;
    1193:   }
    1194:   if (set) *set = iset;
    1195:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1196:     const char *v = PetscBools[deflt];
    1197:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
    1198:   }
    1199:   return(0);
    1200: }

    1204: /*@C
    1205:    PetscOptionsRealArray - Gets an array of double values for a particular
    1206:    option in the database. The values must be separated with commas with
    1207:    no intervening spaces.

    1209:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1211:    Input Parameters:
    1212: +  opt - the option one is seeking
    1213: .  text - short string describing option
    1214: .  man - manual page for option
    1215: -  nmax - maximum number of values

    1217:    Output Parameter:
    1218: +  value - location to copy values
    1219: .  nmax - actual number of values found
    1220: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1222:    Level: beginner

    1224:    Notes:
    1225:    The user should pass in an array of doubles

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

    1229:    Concepts: options database^array of strings

    1231: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1232:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1233:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1234:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1235:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1236:           PetscOptionsList(), PetscOptionsEList()
    1237: @*/
    1238: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
    1239: {
    1241:   PetscInt       i;
    1242:   PetscOptions   amsopt;

    1245:   if (!PetscOptionsPublishCount) {
    1246:     PetscReal *vals;

    1248:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
    1249:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
    1250:     vals = (PetscReal*)amsopt->data;
    1251:     for (i=0; i<*n; i++) vals[i] = value[i];
    1252:     amsopt->arraylength = *n;
    1253:   }
    1254:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
    1255:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1256:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
    1257:     for (i=1; i<*n; i++) {
    1258:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
    1259:     }
    1260:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
    1261:   }
    1262:   return(0);
    1263: }

    1268: /*@C
    1269:    PetscOptionsIntArray - Gets an array of integers for a particular
    1270:    option in the database.

    1272:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1274:    Input Parameters:
    1275: +  opt - the option one is seeking
    1276: .  text - short string describing option
    1277: .  man - manual page for option
    1278: -  n - maximum number of values

    1280:    Output Parameter:
    1281: +  value - location to copy values
    1282: .  n - actual number of values found
    1283: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1285:    Level: beginner

    1287:    Notes:
    1288:    The array can be passed as
    1289:    a comma seperated list:                                 0,1,2,3,4,5,6,7
    1290:    a range (start-end+1):                                  0-8
    1291:    a range with given increment (start-end+1:inc):         0-7:2
    1292:    a combination of values and ranges seperated by commas: 0,1-8,8-15:2

    1294:    There must be no intervening spaces between the values.

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

    1298:    Concepts: options database^array of ints

    1300: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1301:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1302:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1303:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1304:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1305:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
    1306: @*/
    1307: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
    1308: {
    1310:   PetscInt       i;
    1311:   PetscOptions   amsopt;

    1314:   if (!PetscOptionsPublishCount) {
    1315:     PetscInt *vals;

    1317:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
    1318:     PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
    1319:     vals = (PetscInt*)amsopt->data;
    1320:     for (i=0; i<*n; i++) vals[i] = value[i];
    1321:     amsopt->arraylength = *n;
    1322:   }
    1323:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
    1324:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1325:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
    1326:     for (i=1; i<*n; i++) {
    1327:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
    1328:     }
    1329:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
    1330:   }
    1331:   return(0);
    1332: }

    1336: /*@C
    1337:    PetscOptionsStringArray - Gets an array of string values for a particular
    1338:    option in the database. The values must be separated with commas with
    1339:    no intervening spaces.

    1341:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1343:    Input Parameters:
    1344: +  opt - the option one is seeking
    1345: .  text - short string describing option
    1346: .  man - manual page for option
    1347: -  nmax - maximum number of strings

    1349:    Output Parameter:
    1350: +  value - location to copy strings
    1351: .  nmax - actual number of strings found
    1352: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1354:    Level: beginner

    1356:    Notes:
    1357:    The user should pass in an array of pointers to char, to hold all the
    1358:    strings returned by this function.

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

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

    1365:    Concepts: options database^array of strings

    1367: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1368:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1369:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1370:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1371:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1372:           PetscOptionsList(), PetscOptionsEList()
    1373: @*/
    1374: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
    1375: {
    1377:   PetscOptions   amsopt;

    1380:   if (!PetscOptionsPublishCount) {
    1381:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
    1382:     PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);

    1384:     amsopt->arraylength = *nmax;
    1385:   }
    1386:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
    1387:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1388:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
    1389:   }
    1390:   return(0);
    1391: }

    1395: /*@C
    1396:    PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
    1397:    option in the database. The values must be separated with commas with
    1398:    no intervening spaces.

    1400:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1402:    Input Parameters:
    1403: +  opt - the option one is seeking
    1404: .  text - short string describing option
    1405: .  man - manual page for option
    1406: -  nmax - maximum number of values

    1408:    Output Parameter:
    1409: +  value - location to copy values
    1410: .  nmax - actual number of values found
    1411: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1413:    Level: beginner

    1415:    Notes:
    1416:    The user should pass in an array of doubles

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

    1420:    Concepts: options database^array of strings

    1422: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1423:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1424:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1425:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1426:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1427:           PetscOptionsList(), PetscOptionsEList()
    1428: @*/
    1429: PetscErrorCode  PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
    1430: {
    1432:   PetscInt       i;
    1433:   PetscOptions   amsopt;

    1436:   if (!PetscOptionsPublishCount) {
    1437:     PetscBool *vals;

    1439:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
    1440:     PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
    1441:     vals = (PetscBool*)amsopt->data;
    1442:     for (i=0; i<*n; i++) vals[i] = value[i];
    1443:     amsopt->arraylength = *n;
    1444:   }
    1445:   PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
    1446:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1447:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
    1448:     for (i=1; i<*n; i++) {
    1449:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
    1450:     }
    1451:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
    1452:   }
    1453:   return(0);
    1454: }

    1458: /*@C
    1459:    PetscOptionsInt - Gets a viewer appropriate for the type indicated by the user

    1461:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1463:    Input Parameters:
    1464: +  opt - option name
    1465: .  text - short string that describes the option
    1466: -  man - manual page with additional information on option

    1468:    Output Parameter:
    1469: +  viewer - the viewer
    1470: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1472:    Level: beginner

    1474:    Concepts: options database^has int

    1476:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
    1477: If no value is provided ascii:stdout is used
    1478: $       ascii[:[filename][:format]]   defaults to stdout - format can be one of info, info_detailed, or matlab, for example ascii::info prints just the info
    1479: $                                     about the object to standard out
    1480: $       binary[:filename]   defaults to binaryoutput
    1481: $       draw
    1482: $       socket[:port]    defaults to the standard output port

    1484:    Use PetscRestoreViewerDestroy() after using the viewer, otherwise a memory leak will occur

    1486: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1487:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1488:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1489:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1490:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1491:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1492:           PetscOptionsList(), PetscOptionsEList()
    1493: @*/
    1494: PetscErrorCode  PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
    1495: {
    1497:   PetscOptions   amsopt;

    1500:   if (!PetscOptionsPublishCount) {
    1501:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
    1502:     PetscMalloc(sizeof(PetscInt),&amsopt->data);

    1504:     *(const char**)amsopt->data = "";
    1505:   }
    1506:   PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
    1507:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1508:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
    1509:   }
    1510:   return(0);
    1511: }

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

    1520:    Logically Collective on the communicator passed in PetscOptionsBegin()

    1522:    Input Parameter:
    1523: .   head - the heading text

    1526:    Level: intermediate

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

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

    1532:    Concepts: options database^subheading

    1534: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1535:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1536:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1537:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1538:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1539:           PetscOptionsList(), PetscOptionsEList()
    1540: @*/
    1541: PetscErrorCode  PetscOptionsHead(const char head[])
    1542: {

    1546:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
    1547:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
    1548:   }
    1549:   return(0);
    1550: }