Actual source code: aoptions.c

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

      7: */

      9: #include <petsc/private/petscimpl.h>
     10: #include <petscviewer.h>

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

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

     18:     Eventually we'll attach this beast to a MPI_Comm
     19: */

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

     33:   if (!PetscOptionsObject->alreadyprinted) {
     34:     if (!PetscOptionsHelpPrintedSingleton) {
     35:       PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
     36:     }
     37:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
     38:   }
     39:   PetscOptionsObject->next          = NULL;
     40:   PetscOptionsObject->comm          = comm;
     41:   PetscOptionsObject->changedmethod = PETSC_FALSE;

     43:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
     44:   PetscStrallocpy(title,&PetscOptionsObject->title);

     46:   PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
     47:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
     48:     if (!PetscOptionsObject->alreadyprinted) {
     49:       (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
     50:     }
     51:   }
     52:   return(0);
     53: }

     55: /*
     56:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
     57: */
     58: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
     59: {
     61:   char           title[256];
     62:   PetscBool      flg;

     66:   PetscOptionsObject->object         = obj;
     67:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

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

     79: /*
     80:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
     81: */
     82: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
     83: {
     84:   int             ierr;
     85:   PetscOptionItem next;
     86:   PetscBool       valid;

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

     92:   PetscNew(amsopt);
     93:   (*amsopt)->next = NULL;
     94:   (*amsopt)->set  = PETSC_FALSE;
     95:   (*amsopt)->type = t;
     96:   (*amsopt)->data = NULL;

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

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

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

    114:     Collective

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

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

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

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

    148: /*
    149:     This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
    150: */
    151: static PetscErrorCode  PetscStrdup(const char s[],char *t[])
    152: {
    154:   size_t         len;
    155:   char           *tmp = NULL;

    158:   if (s) {
    159:     PetscStrlen(s,&len);
    160:     tmp = (char*) malloc((len+1)*sizeof(char));
    161:     if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
    162:     PetscStrcpy(tmp,s);
    163:   }
    164:   *t = tmp;
    165:   return(0);
    166: }

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

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

    175:     A carriage return indicates no change from the default; but this like -ksp_monitor <stdout>  the default is actually not stdout the default
    176:     is to do nothing so to get it to use stdout you need to type stdout. This is kind of bug?

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

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

    187: */
    188: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
    189: {
    190:   PetscErrorCode  ierr;
    191:   PetscOptionItem next = PetscOptionsObject->next;
    192:   char            str[512];
    193:   PetscBool       bid;
    194:   PetscReal       ir,*valr;
    195:   PetscInt        *vald;
    196:   size_t          i;

    199:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s --------------------\n",PetscOptionsObject->title);
    200:   while (next) {
    201:     switch (next->type) {
    202:     case OPTION_HEAD:
    203:       break;
    204:     case OPTION_INT_ARRAY:
    205:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
    206:       vald = (PetscInt*) next->data;
    207:       for (i=0; i<next->arraylength; i++) {
    208:         PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
    209:         if (i < next->arraylength-1) {
    210:           PetscPrintf(PETSC_COMM_WORLD,",");
    211:         }
    212:       }
    213:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
    214:       PetscScanString(PETSC_COMM_WORLD,512,str);
    215:       if (str[0]) {
    216:         PetscToken token;
    217:         PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
    218:         size_t     len;
    219:         char       *value;
    220:         PetscBool  foundrange;

    222:         next->set = PETSC_TRUE;
    223:         value     = str;
    224:         PetscTokenCreate(value,',',&token);
    225:         PetscTokenFind(token,&value);
    226:         while (n < nmax) {
    227:           if (!value) break;

    229:           /* look for form  d-D where d and D are integers */
    230:           foundrange = PETSC_FALSE;
    231:           PetscStrlen(value,&len);
    232:           if (value[0] == '-') i=2;
    233:           else i=1;
    234:           for (;i<len; i++) {
    235:             if (value[i] == '-') {
    236:               if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
    237:               value[i] = 0;
    238:               PetscOptionsStringToInt(value,&start);
    239:               PetscOptionsStringToInt(value+i+1,&end);
    240:               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);
    241:               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);
    242:               for (; start<end; start++) {
    243:                 *dvalue = start; dvalue++;n++;
    244:               }
    245:               foundrange = PETSC_TRUE;
    246:               break;
    247:             }
    248:           }
    249:           if (!foundrange) {
    250:             PetscOptionsStringToInt(value,dvalue);
    251:             dvalue++;
    252:             n++;
    253:           }
    254:           PetscTokenFind(token,&value);
    255:         }
    256:         PetscTokenDestroy(&token);
    257:       }
    258:       break;
    259:     case OPTION_REAL_ARRAY:
    260:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1);
    261:       valr = (PetscReal*) next->data;
    262:       for (i=0; i<next->arraylength; i++) {
    263:         PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
    264:         if (i < next->arraylength-1) {
    265:           PetscPrintf(PETSC_COMM_WORLD,",");
    266:         }
    267:       }
    268:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s) ",next->text,next->man);
    269:       PetscScanString(PETSC_COMM_WORLD,512,str);
    270:       if (str[0]) {
    271:         PetscToken token;
    272:         PetscInt   n = 0,nmax = next->arraylength;
    273:         PetscReal  *dvalue = (PetscReal*)next->data;
    274:         char       *value;

    276:         next->set = PETSC_TRUE;
    277:         value     = str;
    278:         PetscTokenCreate(value,',',&token);
    279:         PetscTokenFind(token,&value);
    280:         while (n < nmax) {
    281:           if (!value) break;
    282:           PetscOptionsStringToReal(value,dvalue);
    283:           dvalue++;
    284:           n++;
    285:           PetscTokenFind(token,&value);
    286:         }
    287:         PetscTokenDestroy(&token);
    288:       }
    289:       break;
    290:     case OPTION_INT:
    291:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
    292:       PetscScanString(PETSC_COMM_WORLD,512,str);
    293:       if (str[0]) {
    294: #if defined(PETSC_SIZEOF_LONG_LONG)
    295:         long long lid;
    296:         sscanf(str,"%lld",&lid);
    297:         if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %lld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
    298: #else
    299:         long  lid;
    300:         sscanf(str,"%ld",&lid);
    301:         if (lid > PETSC_MAX_INT || lid < PETSC_MIN_INT) SETERRQ3(PETSC_COMM_WORLD,PETSC_ERR_ARG_OUTOFRANGE,"Argument: -%s%s %ld",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,lid);
    302: #endif

    304:         next->set = PETSC_TRUE;
    305:         *((PetscInt*)next->data) = (PetscInt)lid;
    306:       }
    307:       break;
    308:     case OPTION_REAL:
    309:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
    310:       PetscScanString(PETSC_COMM_WORLD,512,str);
    311:       if (str[0]) {
    312: #if defined(PETSC_USE_REAL_SINGLE)
    313:         sscanf(str,"%e",&ir);
    314: #elif defined(PETSC_USE_REAL___FP16)
    315:         float irtemp;
    316:         sscanf(str,"%e",&irtemp);
    317:         ir = irtemp;
    318: #elif defined(PETSC_USE_REAL_DOUBLE)
    319:         sscanf(str,"%le",&ir);
    320: #elif defined(PETSC_USE_REAL___FLOAT128)
    321:         ir = strtoflt128(str,0);
    322: #else
    323:         SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
    324: #endif
    325:         next->set                 = PETSC_TRUE;
    326:         *((PetscReal*)next->data) = ir;
    327:       }
    328:       break;
    329:     case OPTION_BOOL:
    330:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(PetscBool*)next->data ? "true": "false",next->text,next->man);
    331:       PetscScanString(PETSC_COMM_WORLD,512,str);
    332:       if (str[0]) {
    333:         PetscOptionsStringToBool(str,&bid);
    334:         next->set = PETSC_TRUE;
    335:         *((PetscBool*)next->data) = bid;
    336:       }
    337:       break;
    338:     case OPTION_STRING:
    339:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
    340:       PetscScanString(PETSC_COMM_WORLD,512,str);
    341:       if (str[0]) {
    342:         next->set = PETSC_TRUE;
    343:         /* must use system malloc since SAWs may free this */
    344:         PetscStrdup(str,(char**)&next->data);
    345:       }
    346:       break;
    347:     case OPTION_FLIST:
    348:       PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
    349:       PetscScanString(PETSC_COMM_WORLD,512,str);
    350:       if (str[0]) {
    351:         PetscOptionsObject->changedmethod = PETSC_TRUE;
    352:         next->set = PETSC_TRUE;
    353:         /* must use system malloc since SAWs may free this */
    354:         PetscStrdup(str,(char**)&next->data);
    355:       }
    356:       break;
    357:     default:
    358:       break;
    359:     }
    360:     next = next->next;
    361:   }
    362:   return(0);
    363: }

    365: #if defined(PETSC_HAVE_SAWS)
    366: #include <petscviewersaws.h>

    368: static int count = 0;

    370: PetscErrorCode PetscOptionsSAWsDestroy(void)
    371: {
    373:   return(0);
    374: }

    376: static const char *OptionsHeader = "<head>\n"
    377:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
    378:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
    379:                                    "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
    380:                                    "<script>\n"
    381:                                       "jQuery(document).ready(function() {\n"
    382:                                          "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
    383:                                       "})\n"
    384:                                   "</script>\n"
    385:                                   "</head>\n";

    387: /*  Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
    388: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";

    390: /*
    391:     PetscOptionsSAWsInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the SAWs

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

    399: */
    400: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
    401: {
    402:   PetscErrorCode  ierr;
    403:   PetscOptionItem next     = PetscOptionsObject->next;
    404:   static int      mancount = 0;
    405:   char            options[16];
    406:   PetscBool       changedmethod = PETSC_FALSE;
    407:   PetscBool       stopasking    = PETSC_FALSE;
    408:   char            manname[16],textname[16];
    409:   char            dir[1024];

    412:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
    413:   sprintf(options,"Options_%d",count++);

    415:   PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */

    417:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
    418:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
    419:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
    420:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
    421:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
    422:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

    424:   while (next) {
    425:     sprintf(manname,"_man_%d",mancount);
    426:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
    427:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
    428:     sprintf(textname,"_text_%d",mancount++);
    429:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
    430:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

    432:     switch (next->type) {
    433:     case OPTION_HEAD:
    434:       break;
    435:     case OPTION_INT_ARRAY:
    436:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    437:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
    438:       break;
    439:     case OPTION_REAL_ARRAY:
    440:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    441:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
    442:       break;
    443:     case OPTION_INT:
    444:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    445:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
    446:       break;
    447:     case OPTION_REAL:
    448:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    449:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
    450:       break;
    451:     case OPTION_BOOL:
    452:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    453:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
    454:       break;
    455:     case OPTION_BOOL_ARRAY:
    456:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    457:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
    458:       break;
    459:     case OPTION_STRING:
    460:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    461:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
    462:       break;
    463:     case OPTION_STRING_ARRAY:
    464:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    465:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
    466:       break;
    467:     case OPTION_FLIST:
    468:       {
    469:       PetscInt ntext;
    470:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    471:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
    472:       PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
    473:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
    474:       }
    475:       break;
    476:     case OPTION_ELIST:
    477:       {
    478:       PetscInt ntext = next->nlist;
    479:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    480:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
    481:       PetscMalloc1((ntext+1),(char***)&next->edata);
    482:       PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
    483:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
    484:       }
    485:       break;
    486:     default:
    487:       break;
    488:     }
    489:     next = next->next;
    490:   }

    492:   /* wait until accessor has unlocked the memory */
    493:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
    494:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
    495:   PetscSAWsBlock();
    496:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
    497:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

    499:   /* determine if any values have been set in GUI */
    500:   next = PetscOptionsObject->next;
    501:   while (next) {
    502:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    503:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
    504:     next = next->next;
    505:   }

    507:   /* reset counter to -2; this updates the screen with the new options for the selected method */
    508:   if (changedmethod) PetscOptionsObject->count = -2;

    510:   if (stopasking) {
    511:     PetscOptionsPublish      = PETSC_FALSE;
    512:     PetscOptionsObject->count = 0;//do not ask for same thing again
    513:   }

    515:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
    516:   return(0);
    517: }
    518: #endif

    520: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
    521: {
    522:   PetscErrorCode  ierr;
    523:   PetscOptionItem last;
    524:   char            option[256],value[1024],tmp[32];
    525:   size_t          j;

    528:   if (PetscOptionsObject->next) {
    529:     if (!PetscOptionsObject->count) {
    530: #if defined(PETSC_HAVE_SAWS)
    531:       PetscOptionsSAWsInput(PetscOptionsObject);
    532: #else
    533:       PetscOptionsGetFromTextInput(PetscOptionsObject);
    534: #endif
    535:     }
    536:   }

    538:   PetscFree(PetscOptionsObject->title);

    540:   /* reset counter to -2; this updates the screen with the new options for the selected method */
    541:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
    542:   /* reset alreadyprinted flag */
    543:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
    544:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
    545:   PetscOptionsObject->object = NULL;

    547:   while (PetscOptionsObject->next) {
    548:     if (PetscOptionsObject->next->set) {
    549:       if (PetscOptionsObject->prefix) {
    550:         PetscStrcpy(option,"-");
    551:         PetscStrcat(option,PetscOptionsObject->prefix);
    552:         PetscStrcat(option,PetscOptionsObject->next->option+1);
    553:       } else {
    554:         PetscStrcpy(option,PetscOptionsObject->next->option);
    555:       }

    557:       switch (PetscOptionsObject->next->type) {
    558:       case OPTION_HEAD:
    559:         break;
    560:       case OPTION_INT_ARRAY:
    561:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
    562:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
    563:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
    564:           PetscStrcat(value,",");
    565:           PetscStrcat(value,tmp);
    566:         }
    567:         break;
    568:       case OPTION_INT:
    569:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
    570:         break;
    571:       case OPTION_REAL:
    572:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
    573:         break;
    574:       case OPTION_REAL_ARRAY:
    575:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
    576:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
    577:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
    578:           PetscStrcat(value,",");
    579:           PetscStrcat(value,tmp);
    580:         }
    581:         break;
    582:       case OPTION_SCALAR_ARRAY:
    583:         sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
    584:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
    585:           sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
    586:           PetscStrcat(value,",");
    587:           PetscStrcat(value,tmp);
    588:         }
    589:         break;
    590:       case OPTION_BOOL:
    591:         sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
    592:         break;
    593:       case OPTION_BOOL_ARRAY:
    594:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
    595:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
    596:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
    597:           PetscStrcat(value,",");
    598:           PetscStrcat(value,tmp);
    599:         }
    600:         break;
    601:       case OPTION_FLIST:
    602:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
    603:         break;
    604:       case OPTION_ELIST:
    605:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
    606:         break;
    607:       case OPTION_STRING:
    608:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
    609:         break;
    610:       case OPTION_STRING_ARRAY:
    611:         sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
    612:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
    613:           sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
    614:           PetscStrcat(value,",");
    615:           PetscStrcat(value,tmp);
    616:         }
    617:         break;
    618:       }
    619:       PetscOptionsSetValue(PetscOptionsObject->options,option,value);
    620:     }
    621:     if (PetscOptionsObject->next->type == OPTION_ELIST) {
    622:       PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
    623:     }
    624:     PetscFree(PetscOptionsObject->next->text);
    625:     PetscFree(PetscOptionsObject->next->option);
    626:     PetscFree(PetscOptionsObject->next->man);
    627:     PetscFree(PetscOptionsObject->next->edata);

    629:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
    630:       free(PetscOptionsObject->next->data);
    631:     } else {
    632:       PetscFree(PetscOptionsObject->next->data);
    633:     }

    635:     last                    = PetscOptionsObject->next;
    636:     PetscOptionsObject->next = PetscOptionsObject->next->next;
    637:     PetscFree(last);
    638:   }
    639:   PetscFree(PetscOptionsObject->prefix);
    640:   PetscOptionsObject->next = NULL;
    641:   return(0);
    642: }

    644: /*MC
    645:    PetscOptionsEnum - Gets the enum value for a particular option in the database.

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

    649:    Synopsis:
    650:    #include "petscsys.h"
    651:    PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)

    653:    Input Parameters:
    654: +  opt - option name
    655: .  text - short string that describes the option
    656: .  man - manual page with additional information on option
    657: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    658: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    659: $                 PetscOptionsEnum(..., obj->value,&object->value,...) or
    660: $                 value = defaultvalue
    661: $                 PetscOptionsEnum(..., value,&value,&flg);
    662: $                 if (flg) {

    664:    Output Parameter:
    665: +  value - the  value to return
    666: -  set - PETSC_TRUE if found, else PETSC_FALSE

    668:    Level: beginner

    670:    Notes:
    671:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    675:           If the user does not supply the option at all value is NOT changed. Thus
    676:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    678:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

    680: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    681:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    682:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    683:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    684:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    685:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    686:           PetscOptionsFList(), PetscOptionsEList()
    687: M*/

    689: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
    690: {
    692:   PetscInt       ntext = 0;
    693:   PetscInt       tval;
    694:   PetscBool      tflg;

    697:   while (list[ntext++]) {
    698:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    699:   }
    700:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    701:   ntext -= 3;
    702:   PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
    703:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
    704:   if (tflg) *value = (PetscEnum)tval;
    705:   if (set)  *set   = tflg;
    706:   return(0);
    707: }

    709: /*MC
    710:    PetscOptionsEnumArray - Gets an array of enum values for a particular
    711:    option in the database.

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

    715:    Synopsis:
    716:    #include "petscsys.h"
    717:    PetscErrorCode  PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)

    719:    Input Parameters:
    720: +  opt - the option one is seeking
    721: .  text - short string describing option
    722: .  man - manual page for option
    723: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    724: -  n - maximum number of values

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

    731:    Level: beginner

    733:    Notes:
    734:    The array must be passed as a comma separated list.

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

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

    740: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    741:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    742:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    743:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    744:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    745:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    746: M*/

    748: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
    749: {
    750:   PetscInt        i,nlist = 0;
    751:   PetscOptionItem amsopt;
    752:   PetscErrorCode  ierr;

    755:   while (list[nlist++]) if (nlist > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    756:   if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    757:   nlist -= 3; /* drop enum name, prefix, and null termination */
    758:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
    759:     PetscEnum *vals;
    760:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
    761:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
    762:     amsopt->nlist = nlist;
    763:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
    764:     amsopt->arraylength = *n;
    765:     vals = (PetscEnum*)amsopt->data;
    766:     for (i=0; i<*n; i++) vals[i] = value[i];
    767:   }
    768:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
    769:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    770:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
    771:     for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
    772:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
    773:     for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
    774:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
    775:   }
    776:   return(0);
    777: }

    779: /*MC
    780:    PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.

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

    784:    Synopsis:
    785:    #include "petscsys.h"
    786:    PetscErrorCode  PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)

    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: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    793: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
    794: $                 value = defaultvalue
    795: $                 PetscOptionsInt(..., value,&value,&flg);
    796: $                 if (flg) {
    797: -  bound - the requested value should be greater than or equal this bound or an error is generated

    799:    Output Parameter:
    800: +  value - the integer value to return
    801: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    803:    Notes:
    804:     If the user does not supply the option at all value is NOT changed. Thus
    805:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    807:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

    811:    Level: beginner

    813: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    814:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
    815:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    816:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    817:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    818:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    819:           PetscOptionsFList(), PetscOptionsEList()
    820: M*/

    822: /*MC
    823:    PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.

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

    827:    Synopsis:
    828:    #include "petscsys.h"
    829: PetscErrorCode  PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)

    831:    Input Parameters:
    832: +  opt - option name
    833: .  text - short string that describes the option
    834: .  man - manual page with additional information on option
    835: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    836: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
    837: $                 value = defaultvalue
    838: $                 PetscOptionsInt(..., value,&value,&flg);
    839: $                 if (flg) {
    840: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
    841: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

    843:    Output Parameter:
    844: +  value - the integer value to return
    845: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    847:    Notes:
    848:     If the user does not supply the option at all value is NOT changed. Thus
    849:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    851:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

    855:    Level: beginner

    857: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    858:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsBoundedInt()
    859:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    860:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    861:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    862:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    863:           PetscOptionsFList(), PetscOptionsEList()
    864: M*/

    866: /*MC
    867:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

    871:    Synopsis:
    872:    #include "petscsys.h"
    873: PetscErrorCode  PetscOptionsInt(const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))

    876:    Input Parameters:
    877: +  opt - option name
    878: .  text - short string that describes the option
    879: .  man - manual page with additional information on option
    880: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    881: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
    882: $                 value = defaultvalue
    883: $                 PetscOptionsInt(..., value,&value,&flg);
    884: $                 if (flg) {

    886:    Output Parameter:
    887: +  value - the integer value to return
    888: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    890:    Notes:
    891:     If the user does not supply the option at all value is NOT changed. Thus
    892:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    894:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

    898:    Level: beginner

    900: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    901:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
    902:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    903:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    904:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    905:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    906:           PetscOptionsFList(), PetscOptionsEList()
    907: M*/

    909: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set,PetscInt lb,PetscInt ub)
    910: {
    911:   PetscErrorCode  ierr;
    912:   PetscOptionItem amsopt;
    913:   PetscBool       wasset;

    916:   if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
    917:   if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
    918:      if (!PetscOptionsObject->count) {
    919:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
    920:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
    921:     *(PetscInt*)amsopt->data = currentvalue;

    923:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
    924:     if (wasset) {
    925:       *(PetscInt*)amsopt->data = currentvalue;
    926:     }
    927:   }
    928:   PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
    929:   if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
    930:   if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
    931:   if (set) *set = wasset;
    932:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    933:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %D : formerly %D>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
    934:   }
    935:   return(0);
    936: }

    938: /*MC
    939:    PetscOptionsString - Gets the string value for a particular option in the database.

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

    943:    Synopsis:
    944:    #include "petscsys.h"
    945:    PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)

    947:    Input Parameters:
    948: +  opt - option name
    949: .  text - short string that describes the option
    950: .  man - manual page with additional information on option
    951: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
    952: -  len - length of the result string including null terminator

    954:    Output Parameter:
    955: +  value - the value to return
    956: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    958:    Level: beginner

    960:    Notes:
    961:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    963:    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).

    965:           If the user does not supply the option at all value is NOT changed. Thus
    966:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    968:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

    971: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    972:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    973:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
    974:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    975:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    976:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    977:           PetscOptionsFList(), PetscOptionsEList()
    978: M*/

    980: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
    981: {
    982:   PetscErrorCode  ierr;
    983:   PetscOptionItem amsopt;
    984:   PetscBool       lset;

    987:   if (!PetscOptionsObject->count) {
    988:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
    989:     /* must use system malloc since SAWs may free this */
    990:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    991:   }
    992:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
    993:   if (set) *set = lset;
    994:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    995:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? value : currentvalue,currentvalue,text,ManSection(man));
    996:   }
    997:   return(0);
    998: }

    1000: /*MC
    1001:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

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

    1005:    Synopsis:
    1006:    #include "petscsys.h"
    1007:    PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)

    1009:    Input Parameters:
    1010: +  opt - option name
    1011: .  text - short string that describes the option
    1012: .  man - manual page with additional information on option
    1013: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    1014: $                 PetscOptionsReal(..., obj->value,&obj->value,...) or
    1015: $                 value = defaultvalue
    1016: $                 PetscOptionsReal(..., value,&value,&flg);
    1017: $                 if (flg) {

    1019:    Output Parameter:
    1020: +  value - the value to return
    1021: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1023:    Notes:
    1024:     If the user does not supply the option at all value is NOT changed. Thus
    1025:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    1027:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

    1031:    Level: beginner

    1033: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1034:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    1035:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1036:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1037:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1038:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1039:           PetscOptionsFList(), PetscOptionsEList()
    1040: M*/

    1042: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
    1043: {
    1044:   PetscErrorCode  ierr;
    1045:   PetscOptionItem amsopt;
    1046:   PetscBool       lset;

    1049:   if (!PetscOptionsObject->count) {
    1050:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
    1051:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

    1053:     *(PetscReal*)amsopt->data = currentvalue;
    1054:   }
    1055:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
    1056:   if (set) *set = lset;
    1057:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1058:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g : %g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? (double)*value : (double) currentvalue,(double)currentvalue,text,ManSection(man));
    1059:   }
    1060:   return(0);
    1061: }

    1063: /*MC
    1064:    PetscOptionsScalar - Gets the scalar value for a particular option in the database.

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

    1068:    Synopsis:
    1069:    #include "petscsys.h"
    1070:    PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)

    1072:    Input Parameters:
    1073: +  opt - option name
    1074: .  text - short string that describes the option
    1075: .  man - manual page with additional information on option
    1076: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    1077: $                 PetscOptionsScalar(..., obj->value,&obj->value,...) or
    1078: $                 value = defaultvalue
    1079: $                 PetscOptionsScalar(..., value,&value,&flg);
    1080: $                 if (flg) {

    1083:    Output Parameter:
    1084: +  value - the value to return
    1085: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1087:    Notes:
    1088:     If the user does not supply the option at all value is NOT changed. Thus
    1089:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    1091:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

    1095:    Level: beginner

    1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1098:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    1099:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1100:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1101:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1102:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1103:           PetscOptionsFList(), PetscOptionsEList()
    1104: M*/

    1106: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
    1107: {

    1111: #if !defined(PETSC_USE_COMPLEX)
    1112:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
    1113: #else
    1114:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
    1115: #endif
    1116:   return(0);
    1117: }

    1119: /*MC
    1120:    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
    1121:                       its value is set to false.

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

    1125:    Synopsis:
    1126:    #include "petscsys.h"
    1127:    PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)

    1129:    Input Parameters:
    1130: +  opt - option name
    1131: .  text - short string that describes the option
    1132: -  man - manual page with additional information on option

    1134:    Output Parameter:
    1135: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1137:    Level: beginner

    1139:    Notes:
    1140:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1142: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1143:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    1144:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1145:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1146:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1147:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1148:           PetscOptionsFList(), PetscOptionsEList()
    1149: M*/

    1151: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1152: {
    1153:   PetscErrorCode  ierr;
    1154:   PetscOptionItem amsopt;

    1157:   if (!PetscOptionsObject->count) {
    1158:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1159:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1161:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1162:   }
    1163:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
    1164:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1165:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1166:   }
    1167:   return(0);
    1168: }

    1170: /*MC
    1171:      PetscOptionsFList - Puts a list of option values that a single one may be selected from

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

    1175:    Synopsis:
    1176:    #include "petscsys.h"
    1177:    PetscErrorCode  PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)

    1179:    Input Parameters:
    1180: +  opt - option name
    1181: .  text - short string that describes the option
    1182: .  man - manual page with additional information on option
    1183: .  list - the possible choices
    1184: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1185: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
    1186: $                 if (flg) {
    1187: -  len - the length of the character array value

    1189:    Output Parameter:
    1190: +  value - the value to return
    1191: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1193:    Level: intermediate

    1195:    Notes:
    1196:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1198:           If the user does not supply the option at all value is NOT changed. Thus
    1199:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    1201:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

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

    1208:    Developer Note: This cannot check for invalid selection because of things like MATAIJ that are not included in the list

    1210: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1211:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1212:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1213:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1214:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1215:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
    1216: M*/

    1218: PetscErrorCode  PetscOptionsFList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)
    1219: {
    1220:   PetscErrorCode  ierr;
    1221:   PetscOptionItem amsopt;
    1222:   PetscBool       lset;

    1225:   if (!PetscOptionsObject->count) {
    1226:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
    1227:     /* must use system malloc since SAWs may free this */
    1228:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1229:     amsopt->flist = list;
    1230:   }
    1231:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
    1232:   if (set) *set = lset;
    1233:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1234:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
    1235:   }
    1236:   return(0);
    1237: }

    1239: /*MC
    1240:      PetscOptionsEList - Puts a list of option values that a single one may be selected from

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

    1244:    Synopsis:
    1245:    #include "petscsys.h"
    1246:    PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)

    1248:    Input Parameters:
    1249: +  opt - option name
    1250: .  ltext - short string that describes the option
    1251: .  man - manual page with additional information on option
    1252: .  list - the possible choices (one of these must be selected, anything else is invalid)
    1253: .  ntext - number of choices
    1254: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1255: $                 PetscOptionsElist(..., obj->value,&value,&flg);
    1256: $                 if (flg) {

    1259:    Output Parameter:
    1260: +  value - the index of the value to return
    1261: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1263:    Level: intermediate

    1265:    Notes:
    1266:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1268:          If the user does not supply the option at all value is NOT changed. Thus
    1269:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

    1271:    See PetscOptionsFList() for when the choices are given in a PetscFunctionList()

    1273: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1274:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1275:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1276:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1277:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1278:           PetscOptionsFList(), PetscOptionsEnum()
    1279: M*/

    1281: PetscErrorCode  PetscOptionsEList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)
    1282: {
    1283:   PetscErrorCode  ierr;
    1284:   PetscInt        i;
    1285:   PetscOptionItem amsopt;
    1286:   PetscBool       lset;

    1289:   if (!PetscOptionsObject->count) {
    1290:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
    1291:     /* must use system malloc since SAWs may free this */
    1292:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1293:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
    1294:     amsopt->nlist = ntext;
    1295:   }
    1296:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
    1297:   if (set) *set = lset;
    1298:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1299:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,lset && value ? list[*value] : currentvalue,currentvalue,ltext);
    1300:     for (i=0; i<ntext; i++) {
    1301:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
    1302:     }
    1303:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
    1304:   }
    1305:   return(0);
    1306: }

    1308: /*MC
    1309:      PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
    1310:        which at most a single value can be true.

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

    1314:    Synopsis:
    1315:    #include "petscsys.h"
    1316:    PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)

    1318:    Input Parameters:
    1319: +  opt - option name
    1320: .  text - short string that describes the option
    1321: -  man - manual page with additional information on option

    1323:    Output Parameter:
    1324: .  flg - whether that option was set or not

    1326:    Level: intermediate

    1328:    Notes:
    1329:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    1333: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1334:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1335:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1336:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1337:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1338:           PetscOptionsFList(), PetscOptionsEList()
    1339: M*/

    1341: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1342: {
    1343:   PetscErrorCode  ierr;
    1344:   PetscOptionItem amsopt;

    1347:   if (!PetscOptionsObject->count) {
    1348:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1349:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1351:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1352:   }
    1353:   *flg = PETSC_FALSE;
    1354:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1355:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1356:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
    1357:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1358:   }
    1359:   return(0);
    1360: }

    1362: /*MC
    1363:      PetscOptionsBoolGroup - One in a series of logical queries on the options database for
    1364:        which at most a single value can be true.

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

    1368:    Synopsis:
    1369:    #include "petscsys.h"
    1370:    PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)

    1372:    Input Parameters:
    1373: +  opt - option name
    1374: .  text - short string that describes the option
    1375: -  man - manual page with additional information on option

    1377:    Output Parameter:
    1378: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1380:    Level: intermediate

    1382:    Notes:
    1383:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    1387: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1388:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1389:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1390:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1391:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1392:           PetscOptionsFList(), PetscOptionsEList()
    1393: M*/

    1395: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1396: {
    1397:   PetscErrorCode  ierr;
    1398:   PetscOptionItem amsopt;

    1401:   if (!PetscOptionsObject->count) {
    1402:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1403:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1405:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1406:   }
    1407:   *flg = PETSC_FALSE;
    1408:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1409:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1410:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1411:   }
    1412:   return(0);
    1413: }

    1415: /*MC
    1416:      PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
    1417:        which at most a single value can be true.

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

    1421:    Synopsis:
    1422:    #include "petscsys.h"
    1423:    PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)

    1425:    Input Parameters:
    1426: +  opt - option name
    1427: .  text - short string that describes the option
    1428: -  man - manual page with additional information on option

    1430:    Output Parameter:
    1431: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1433:    Level: intermediate

    1435:    Notes:
    1436:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1438:    Must follow a PetscOptionsBoolGroupBegin()

    1440: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1441:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1442:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1443:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1444:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1445:           PetscOptionsFList(), PetscOptionsEList()
    1446: M*/

    1448: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1449: {
    1450:   PetscErrorCode  ierr;
    1451:   PetscOptionItem amsopt;

    1454:   if (!PetscOptionsObject->count) {
    1455:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1456:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1458:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1459:   }
    1460:   *flg = PETSC_FALSE;
    1461:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1462:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1463:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1464:   }
    1465:   return(0);
    1466: }

    1468: /*MC
    1469:    PetscOptionsBool - Determines if a particular option is in the database with a true or false

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

    1473:    Synopsis:
    1474:    #include "petscsys.h"
    1475:    PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)

    1477:    Input Parameters:
    1478: +  opt - option name
    1479: .  text - short string that describes the option
    1480: .  man - manual page with additional information on option
    1481: -  currentvalue - the current value

    1483:    Output Parameter:
    1484: +  flg - PETSC_TRUE or PETSC_FALSE
    1485: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1487:    Notes:
    1488:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1489:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1491:       If the option is given, but no value is provided, then flg and set are both given the value PETSC_TRUE. That is -requested_bool
    1492:      is equivalent to -requested_bool true

    1494:        If the user does not supply the option at all flg is NOT changed. Thus
    1495:      you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.

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

    1499:    Level: beginner

    1501: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1502:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
    1503:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
    1504:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1505:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1506:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1507:           PetscOptionsFList(), PetscOptionsEList()
    1508: M*/

    1510: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
    1511: {
    1512:   PetscErrorCode  ierr;
    1513:   PetscBool       iset;
    1514:   PetscOptionItem amsopt;

    1517:   if (!PetscOptionsObject->count) {
    1518:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1519:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1521:     *(PetscBool*)amsopt->data = currentvalue;
    1522:   }
    1523:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
    1524:   if (set) *set = iset;
    1525:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1526:     const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
    1527:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
    1528:   }
    1529:   return(0);
    1530: }

    1532: /*MC
    1533:    PetscOptionsRealArray - Gets an array of double values for a particular
    1534:    option in the database. The values must be separated with commas with
    1535:    no intervening spaces.

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

    1539:    Synopsis:
    1540:    #include "petscsys.h"
    1541:    PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)

    1543:    Input Parameters:
    1544: +  opt - the option one is seeking
    1545: .  text - short string describing option
    1546: .  man - manual page for option
    1547: -  nmax - maximum number of values

    1549:    Output Parameter:
    1550: +  value - location to copy values
    1551: .  nmax - actual number of values found
    1552: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1554:    Level: beginner

    1556:    Notes:
    1557:    The user should pass in an array of doubles

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

    1561: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1562:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1563:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1564:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1565:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1566:           PetscOptionsFList(), PetscOptionsEList()
    1567: M*/

    1569: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
    1570: {
    1571:   PetscErrorCode  ierr;
    1572:   PetscInt        i;
    1573:   PetscOptionItem amsopt;

    1576:   if (!PetscOptionsObject->count) {
    1577:     PetscReal *vals;

    1579:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
    1580:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
    1581:     vals = (PetscReal*)amsopt->data;
    1582:     for (i=0; i<*n; i++) vals[i] = value[i];
    1583:     amsopt->arraylength = *n;
    1584:   }
    1585:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1586:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1587:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
    1588:     for (i=1; i<*n; i++) {
    1589:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
    1590:     }
    1591:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1592:   }
    1593:   return(0);
    1594: }

    1596: /*MC
    1597:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
    1598:    option in the database. The values must be separated with commas with
    1599:    no intervening spaces.

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

    1603:    Synopsis:
    1604:    #include "petscsys.h"
    1605:    PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)

    1607:    Input Parameters:
    1608: +  opt - the option one is seeking
    1609: .  text - short string describing option
    1610: .  man - manual page for option
    1611: -  nmax - maximum number of values

    1613:    Output Parameter:
    1614: +  value - location to copy values
    1615: .  nmax - actual number of values found
    1616: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1618:    Level: beginner

    1620:    Notes:
    1621:    The user should pass in an array of doubles

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

    1625: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1626:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1627:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1628:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1629:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1630:           PetscOptionsFList(), PetscOptionsEList()
    1631: M*/

    1633: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
    1634: {
    1635:   PetscErrorCode  ierr;
    1636:   PetscInt        i;
    1637:   PetscOptionItem amsopt;

    1640:   if (!PetscOptionsObject->count) {
    1641:     PetscScalar *vals;

    1643:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
    1644:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
    1645:     vals = (PetscScalar*)amsopt->data;
    1646:     for (i=0; i<*n; i++) vals[i] = value[i];
    1647:     amsopt->arraylength = *n;
    1648:   }
    1649:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1650:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1651:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
    1652:     for (i=1; i<*n; i++) {
    1653:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
    1654:     }
    1655:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1656:   }
    1657:   return(0);
    1658: }

    1660: /*MC
    1661:    PetscOptionsIntArray - Gets an array of integers for a particular
    1662:    option in the database.

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

    1666:    Synopsis:
    1667:    #include "petscsys.h"
    1668:    PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)

    1670:    Input Parameters:
    1671: +  opt - the option one is seeking
    1672: .  text - short string describing option
    1673: .  man - manual page for option
    1674: -  n - maximum number of values

    1676:    Output Parameter:
    1677: +  value - location to copy values
    1678: .  n - actual number of values found
    1679: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1681:    Level: beginner

    1683:    Notes:
    1684:    The array can be passed as
    1685:    a comma separated list:                                 0,1,2,3,4,5,6,7
    1686:    a range (start-end+1):                                  0-8
    1687:    a range with given increment (start-end+1:inc):         0-7:2
    1688:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

    1694: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1695:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1696:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1697:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1698:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1699:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    1700: M*/

    1702: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
    1703: {
    1705:   PetscInt        i;
    1706:   PetscOptionItem amsopt;

    1709:   if (!PetscOptionsObject->count) {
    1710:     PetscInt *vals;

    1712:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
    1713:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
    1714:     vals = (PetscInt*)amsopt->data;
    1715:     for (i=0; i<*n; i++) vals[i] = value[i];
    1716:     amsopt->arraylength = *n;
    1717:   }
    1718:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1719:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1720:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1721:     for (i=1; i<*n; i++) {
    1722:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1723:     }
    1724:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1725:   }
    1726:   return(0);
    1727: }

    1729: /*MC
    1730:    PetscOptionsStringArray - Gets an array of string values for a particular
    1731:    option in the database. The values must be separated with commas with
    1732:    no intervening spaces.

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

    1736:    Synopsis:
    1737:    #include "petscsys.h"
    1738:    PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)

    1740:    Input Parameters:
    1741: +  opt - the option one is seeking
    1742: .  text - short string describing option
    1743: .  man - manual page for option
    1744: -  nmax - maximum number of strings

    1746:    Output Parameter:
    1747: +  value - location to copy strings
    1748: .  nmax - actual number of strings found
    1749: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1751:    Level: beginner

    1753:    Notes:
    1754:    The user should pass in an array of pointers to char, to hold all the
    1755:    strings returned by this function.

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

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

    1762: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1763:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1764:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1765:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1766:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1767:           PetscOptionsFList(), PetscOptionsEList()
    1768: M*/

    1770: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
    1771: {
    1772:   PetscErrorCode  ierr;
    1773:   PetscOptionItem amsopt;

    1776:   if (!PetscOptionsObject->count) {
    1777:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
    1778:     PetscMalloc1(*nmax,(char**)&amsopt->data);

    1780:     amsopt->arraylength = *nmax;
    1781:   }
    1782:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
    1783:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1784:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1785:   }
    1786:   return(0);
    1787: }

    1789: /*MC
    1790:    PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
    1791:    option in the database. The values must be separated with commas with
    1792:    no intervening spaces.

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

    1796:    Synopsis:
    1797:    #include "petscsys.h"
    1798:    PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)

    1800:    Input Parameters:
    1801: +  opt - the option one is seeking
    1802: .  text - short string describing option
    1803: .  man - manual page for option
    1804: -  nmax - maximum number of values

    1806:    Output Parameter:
    1807: +  value - location to copy values
    1808: .  nmax - actual number of values found
    1809: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1811:    Level: beginner

    1813:    Notes:
    1814:    The user should pass in an array of doubles

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

    1818: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1819:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1820:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1821:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1822:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1823:           PetscOptionsFList(), PetscOptionsEList()
    1824: M*/

    1826: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
    1827: {
    1828:   PetscErrorCode   ierr;
    1829:   PetscInt         i;
    1830:   PetscOptionItem  amsopt;

    1833:   if (!PetscOptionsObject->count) {
    1834:     PetscBool *vals;

    1836:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
    1837:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
    1838:     vals = (PetscBool*)amsopt->data;
    1839:     for (i=0; i<*n; i++) vals[i] = value[i];
    1840:     amsopt->arraylength = *n;
    1841:   }
    1842:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1843:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1844:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1845:     for (i=1; i<*n; i++) {
    1846:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1847:     }
    1848:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1849:   }
    1850:   return(0);
    1851: }

    1853: /*MC
    1854:    PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user

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

    1858:    Synopsis:
    1859:    #include "petscsys.h"
    1860:    PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)

    1862:    Input Parameters:
    1863: +  opt - option name
    1864: .  text - short string that describes the option
    1865: -  man - manual page with additional information on option

    1867:    Output Parameter:
    1868: +  viewer - the viewer
    1869: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1871:    Level: beginner

    1873:    Notes:
    1874:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1876:    See PetscOptionsGetViewer() for the format of the supplied viewer and its options

    1878: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1879:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1880:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1881:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1882:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1883:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1884:           PetscOptionsFList(), PetscOptionsEList()
    1885: M*/

    1887: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
    1888: {
    1889:   PetscErrorCode  ierr;
    1890:   PetscOptionItem amsopt;

    1893:   if (!PetscOptionsObject->count) {
    1894:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
    1895:     /* must use system malloc since SAWs may free this */
    1896:     PetscStrdup("",(char**)&amsopt->data);
    1897:   }
    1898:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
    1899:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1900:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
    1901:   }
    1902:   return(0);
    1903: }

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

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

    1911:    Input Parameter:
    1912: .   head - the heading text

    1915:    Level: intermediate

    1917:    Notes:
    1918:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument

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

    1922: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1923:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1924:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1925:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1926:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1927:           PetscOptionsFList(), PetscOptionsEList()
    1928: @*/
    1929: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
    1930: {

    1934:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1935:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
    1936:   }
    1937:   return(0);
    1938: }