Actual source code: aoptions.c
petsc-3.10.5 2019-03-28
Report Typos and Errors

      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: {

     30:   if (!PetscOptionsObject->alreadyprinted) {
     31:     if (!PetscOptionsHelpPrintedSingleton) {
     32:       PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
     33:     }
     34:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
     35:   }
     36:   PetscOptionsObject->next          = 0;
     37:   PetscOptionsObject->comm          = comm;
     38:   PetscOptionsObject->changedmethod = PETSC_FALSE;

     40:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
     41:   PetscStrallocpy(title,&PetscOptionsObject->title);

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

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

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

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

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

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

     89:   PetscNew(amsopt);
     90:   (*amsopt)->next = 0;
     91:   (*amsopt)->set  = PETSC_FALSE;
     92:   (*amsopt)->type = t;
     93:   (*amsopt)->data = 0;

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

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

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

    111:     Collective on MPI_Comm

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

    118:     Bugs:
    119: .   Assumes process 0 of the given communicator has access to stdin

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    362: #if defined(PETSC_HAVE_SAWS)
    363:  #include <petscviewersaws.h>

    365: static int count = 0;

    367: PetscErrorCode PetscOptionsSAWsDestroy(void)
    368: {
    370:   return(0);
    371: }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    512:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
    513:   return(0);
    514: }
    515: #endif

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

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

    535:   PetscFree(PetscOptionsObject->title);

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

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

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

    626:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
    627:       free(PetscOptionsObject->next->data);
    628:     } else {
    629:       PetscFree(PetscOptionsObject->next->data);
    630:     }

    632:     last                    = PetscOptionsObject->next;
    633:     PetscOptionsObject->next = PetscOptionsObject->next->next;
    634:     PetscFree(last);
    635:   }
    636:   PetscFree(PetscOptionsObject->prefix);
    637:   PetscOptionsObject->next = 0;
    638:   return(0);
    639: }

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

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

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

    657:    Output Parameter:
    658: +  value - the  value to return
    659: -  set - PETSC_TRUE if found, else PETSC_FALSE

    661:    Level: beginner

    663:    Concepts: options database

    665:    Notes:
    666:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

    675: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    676:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    677:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    678:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    679:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    680:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    681:           PetscOptionsFList(), PetscOptionsEList()
    682: @*/
    683: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
    684: {
    686:   PetscInt       ntext = 0;
    687:   PetscInt       tval;
    688:   PetscBool      tflg;

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

    703: /*@C
    704:    PetscOptionsEnumArray - Gets an array of enum values for a particular
    705:    option in the database.

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

    709:    Input Parameters:
    710: +  opt - the option one is seeking
    711: .  text - short string describing option
    712: .  man - manual page for option
    713: -  n - maximum number of values

    715:    Output Parameter:
    716: +  value - location to copy values
    717: .  n - actual number of values found
    718: -  set - PETSC_TRUE if found, else PETSC_FALSE

    720:    Level: beginner

    722:    Notes:
    723:    The array must be passed as a comma separated list.

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

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

    729:    Concepts: options database^array of enums

    731: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    732:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    733:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    734:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    735:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    736:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    737: @*/
    738: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
    739: {
    740:   PetscInt        i,nlist = 0;
    741:   PetscOptionItem amsopt;
    742:   PetscErrorCode  ierr;

    745:   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");
    746:   if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    747:   nlist -= 3; /* drop enum name, prefix, and null termination */
    748:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
    749:     PetscEnum *vals;
    750:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
    751:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
    752:     amsopt->nlist = nlist;
    753:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
    754:     amsopt->arraylength = *n;
    755:     vals = (PetscEnum*)amsopt->data;
    756:     for (i=0; i<*n; i++) vals[i] = value[i];
    757:   }
    758:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
    759:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    760:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
    761:     for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
    762:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
    763:     for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
    764:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
    765:   }
    766:   return(0);
    767: }

    769: /* -------------------------------------------------------------------------------------------------------------*/
    770: /*@C
    771:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

    775:    Input Parameters:
    776: +  opt - option name
    777: .  text - short string that describes the option
    778: .  man - manual page with additional information on option
    779: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    780: $                 PetscOptionsInt(..., obj->value,&object->value,...) or
    781: $                 value = defaultvalue
    782: $                 PetscOptionsInt(..., value,&value,&flg);
    783: $                 if (flg) {

    785:    Output Parameter:
    786: +  value - the integer value to return
    787: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

    795:    Level: beginner

    797:    Concepts: options database^has int

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

    802: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    803:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    804:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    805:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    806:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    807:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    808:           PetscOptionsFList(), PetscOptionsEList()
    809: @*/
    810: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set)
    811: {
    812:   PetscErrorCode  ierr;
    813:   PetscOptionItem amsopt;
    814:   PetscBool       wasset;

    817:   if (!PetscOptionsObject->count) {
    818:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
    819:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
    820:     *(PetscInt*)amsopt->data = currentvalue;

    822:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
    823:     if (wasset) {
    824:       *(PetscInt*)amsopt->data = currentvalue;
    825:     }
    826:   }
    827:   PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
    828:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    829:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
    830:   }
    831:   return(0);
    832: }

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

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

    839:    Input Parameters:
    840: +  opt - option name
    841: .  text - short string that describes the option
    842: .  man - manual page with additional information on option
    843: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
    844: -  len - length of the result string including null terminator

    846:    Output Parameter:
    847: +  value - the value to return
    848: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    850:    Level: beginner

    852:    Concepts: options database^has int

    854:    Notes:
    855:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

    865: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    866:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    867:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
    868:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    869:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    870:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    871:           PetscOptionsFList(), PetscOptionsEList()
    872: @*/
    873: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
    874: {
    875:   PetscErrorCode  ierr;
    876:   PetscOptionItem amsopt;

    879:   if (!PetscOptionsObject->count) {
    880:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
    881:     /* must use system malloc since SAWs may free this */
    882:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    883:   }
    884:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
    885:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    886:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
    887:   }
    888:   return(0);
    889: }

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

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

    896:    Input Parameters:
    897: +  opt - option name
    898: .  text - short string that describes the option
    899: .  man - manual page with additional information on option
    900: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    901: $                 PetscOptionsReal(..., obj->value,&object->value,...) or
    902: $                 value = defaultvalue
    903: $                 PetscOptionsReal(..., value,&value,&flg);
    904: $                 if (flg) {

    906:    Output Parameter:
    907: +  value - the value to return
    908: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

    916:    Level: beginner

    918:    Concepts: options database^has int

    920:    Notes:
    921:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    923: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    924:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    925:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    926:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    927:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    928:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    929:           PetscOptionsFList(), PetscOptionsEList()
    930: @*/
    931: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
    932: {
    933:   PetscErrorCode  ierr;
    934:   PetscOptionItem amsopt;

    937:   if (!PetscOptionsObject->count) {
    938:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
    939:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

    941:     *(PetscReal*)amsopt->data = currentvalue;
    942:   }
    943:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
    944:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    945:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
    946:   }
    947:   return(0);
    948: }

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

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

    955:    Input Parameters:
    956: +  opt - option name
    957: .  text - short string that describes the option
    958: .  man - manual page with additional information on option
    959: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    960: $                 PetscOptionsScalar(..., obj->value,&object->value,...) or
    961: $                 value = defaultvalue
    962: $                 PetscOptionsScalar(..., value,&value,&flg);
    963: $                 if (flg) {

    966:    Output Parameter:
    967: +  value - the value to return
    968: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

    976:    Level: beginner

    978:    Concepts: options database^has int

    980:    Notes:
    981:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    983: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    984:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    985:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    986:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    987:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    988:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    989:           PetscOptionsFList(), PetscOptionsEList()
    990: @*/
    991: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
    992: {

    996: #if !defined(PETSC_USE_COMPLEX)
    997:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
    998: #else
    999:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
    1000: #endif
    1001:   return(0);
    1002: }

    1004: /*@C
    1005:    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
    1006:                       its value is set to false.

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

    1010:    Input Parameters:
    1011: +  opt - option name
    1012: .  text - short string that describes the option
    1013: -  man - manual page with additional information on option

    1015:    Output Parameter:
    1016: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1018:    Level: beginner

    1020:    Concepts: options database^has int

    1022:    Notes:
    1023:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1025: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1026:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1027:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1028:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1029:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1030:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1031:           PetscOptionsFList(), PetscOptionsEList()
    1032: @*/
    1033: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1034: {
    1035:   PetscErrorCode  ierr;
    1036:   PetscOptionItem amsopt;

    1039:   if (!PetscOptionsObject->count) {
    1040:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1041:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1043:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1044:   }
    1045:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
    1046:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1047:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1048:   }
    1049:   return(0);
    1050: }

    1052: /*@C
    1053:      PetscOptionsFList - Puts a list of option values that a single one may be selected from

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

    1057:    Input Parameters:
    1058: +  opt - option name
    1059: .  text - short string that describes the option
    1060: .  man - manual page with additional information on option
    1061: .  list - the possible choices
    1062: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1063: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
    1064: $                 if (flg) {
    1065: -  len - the length of the character array value

    1067:    Output Parameter:
    1068: +  value - the value to return
    1069: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1071:    Level: intermediate

    1073:    Notes:
    1074:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

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

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

    1088:    Concepts: options database^list

    1090: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1091:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1092:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1093:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1094:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1095:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
    1096: @*/
    1097: 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)
    1098: {
    1099:   PetscErrorCode  ierr;
    1100:   PetscOptionItem amsopt;

    1103:   if (!PetscOptionsObject->count) {
    1104:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
    1105:     /* must use system malloc since SAWs may free this */
    1106:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1107:     amsopt->flist = list;
    1108:   }
    1109:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
    1110:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1111:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
    1112:   }
    1113:   return(0);
    1114: }

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

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

    1121:    Input Parameters:
    1122: +  opt - option name
    1123: .  ltext - short string that describes the option
    1124: .  man - manual page with additional information on option
    1125: .  list - the possible choices (one of these must be selected, anything else is invalid)
    1126: .  ntext - number of choices
    1127: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1128: $                 PetscOptionsElist(..., obj->value,&value,&flg);
    1129: $                 if (flg) {

    1132:    Output Parameter:
    1133: +  value - the index of the value to return
    1134: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1136:    Level: intermediate

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

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

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

    1146:    Concepts: options database^list

    1148: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1149:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1150:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1151:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1152:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1153:           PetscOptionsFList(), PetscOptionsEnum()
    1154: @*/
    1155: 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)
    1156: {
    1157:   PetscErrorCode  ierr;
    1158:   PetscInt        i;
    1159:   PetscOptionItem amsopt;

    1162:   if (!PetscOptionsObject->count) {
    1163:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
    1164:     /* must use system malloc since SAWs may free this */
    1165:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1166:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
    1167:     amsopt->nlist = ntext;
    1168:   }
    1169:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
    1170:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1171:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
    1172:     for (i=0; i<ntext; i++) {
    1173:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
    1174:     }
    1175:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
    1176:   }
    1177:   return(0);
    1178: }

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

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

    1186:    Input Parameters:
    1187: +  opt - option name
    1188: .  text - short string that describes the option
    1189: -  man - manual page with additional information on option

    1191:    Output Parameter:
    1192: .  flg - whether that option was set or not

    1194:    Level: intermediate

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

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

    1201:     Concepts: options database^logical group

    1203: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1204:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1205:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1206:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1207:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1208:           PetscOptionsFList(), PetscOptionsEList()
    1209: @*/
    1210: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1211: {
    1212:   PetscErrorCode  ierr;
    1213:   PetscOptionItem amsopt;

    1216:   if (!PetscOptionsObject->count) {
    1217:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1218:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1220:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1221:   }
    1222:   *flg = PETSC_FALSE;
    1223:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1224:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1225:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
    1226:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1227:   }
    1228:   return(0);
    1229: }

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

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

    1237:    Input Parameters:
    1238: +  opt - option name
    1239: .  text - short string that describes the option
    1240: -  man - manual page with additional information on option

    1242:    Output Parameter:
    1243: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1245:    Level: intermediate

    1247:    Notes:
    1248:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    1252:     Concepts: options database^logical group

    1254: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1255:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1256:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1257:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1258:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1259:           PetscOptionsFList(), PetscOptionsEList()
    1260: @*/
    1261: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1262: {
    1263:   PetscErrorCode  ierr;
    1264:   PetscOptionItem amsopt;

    1267:   if (!PetscOptionsObject->count) {
    1268:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1269:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1271:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1272:   }
    1273:   *flg = PETSC_FALSE;
    1274:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1275:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1276:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1277:   }
    1278:   return(0);
    1279: }

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

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

    1287:    Input Parameters:
    1288: +  opt - option name
    1289: .  text - short string that describes the option
    1290: -  man - manual page with additional information on option

    1292:    Output Parameter:
    1293: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1295:    Level: intermediate

    1297:    Notes:
    1298:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1300:    Must follow a PetscOptionsBoolGroupBegin()

    1302:     Concepts: options database^logical group

    1304: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1305:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1306:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1307:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1308:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1309:           PetscOptionsFList(), PetscOptionsEList()
    1310: @*/
    1311: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1312: {
    1313:   PetscErrorCode  ierr;
    1314:   PetscOptionItem amsopt;

    1317:   if (!PetscOptionsObject->count) {
    1318:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1319:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1321:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1322:   }
    1323:   *flg = PETSC_FALSE;
    1324:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1325:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1326:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1327:   }
    1328:   return(0);
    1329: }

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

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

    1336:    Input Parameters:
    1337: +  opt - option name
    1338: .  text - short string that describes the option
    1339: .  man - manual page with additional information on option
    1340: -  currentvalue - the current value

    1342:    Output Parameter:
    1343: .  flg - PETSC_TRUE or PETSC_FALSE
    1344: .  set - PETSC_TRUE if found, else PETSC_FALSE

    1346:    Notes:
    1347:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1348:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1350:       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
    1351:      is equivalent to -requested_bool true

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

    1356:    Level: beginner

    1358:    Concepts: options database^logical

    1360:    Notes:
    1361:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

    1363: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1364:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1365:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1366:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1367:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1368:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1369:           PetscOptionsFList(), PetscOptionsEList()
    1370: @*/
    1371: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
    1372: {
    1373:   PetscErrorCode  ierr;
    1374:   PetscBool       iset;
    1375:   PetscOptionItem amsopt;

    1378:   if (!PetscOptionsObject->count) {
    1379:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1380:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1382:     *(PetscBool*)amsopt->data = currentvalue;
    1383:   }
    1384:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
    1385:   if (set) *set = iset;
    1386:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1387:     const char *v = PetscBools[currentvalue];
    1388:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
    1389:   }
    1390:   return(0);
    1391: }

    1393: /*@C
    1394:    PetscOptionsRealArray - Gets an array of double values for a particular
    1395:    option in the database. The values must be separated with commas with
    1396:    no intervening spaces.

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

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

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

    1411:    Level: beginner

    1413:    Notes:
    1414:    The user should pass in an array of doubles

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

    1418:    Concepts: options database^array of strings

    1420: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1421:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1422:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1423:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1424:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1425:           PetscOptionsFList(), PetscOptionsEList()
    1426: @*/
    1427: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
    1428: {
    1429:   PetscErrorCode  ierr;
    1430:   PetscInt        i;
    1431:   PetscOptionItem amsopt;

    1434:   if (!PetscOptionsObject->count) {
    1435:     PetscReal *vals;

    1437:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
    1438:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
    1439:     vals = (PetscReal*)amsopt->data;
    1440:     for (i=0; i<*n; i++) vals[i] = value[i];
    1441:     amsopt->arraylength = *n;
    1442:   }
    1443:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1444:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1445:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
    1446:     for (i=1; i<*n; i++) {
    1447:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
    1448:     }
    1449:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1450:   }
    1451:   return(0);
    1452: }

    1454: /*@C
    1455:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
    1456:    option in the database. The values must be separated with commas with
    1457:    no intervening spaces.

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

    1461:    Input Parameters:
    1462: +  opt - the option one is seeking
    1463: .  text - short string describing option
    1464: .  man - manual page for option
    1465: -  nmax - maximum number of values

    1467:    Output Parameter:
    1468: +  value - location to copy values
    1469: .  nmax - actual number of values found
    1470: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1472:    Level: beginner

    1474:    Notes:
    1475:    The user should pass in an array of doubles

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

    1479:    Concepts: options database^array of strings

    1481: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1482:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1483:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1484:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1485:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1486:           PetscOptionsFList(), PetscOptionsEList()
    1487: @*/
    1488: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
    1489: {
    1490:   PetscErrorCode  ierr;
    1491:   PetscInt        i;
    1492:   PetscOptionItem amsopt;

    1495:   if (!PetscOptionsObject->count) {
    1496:     PetscScalar *vals;

    1498:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
    1499:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
    1500:     vals = (PetscScalar*)amsopt->data;
    1501:     for (i=0; i<*n; i++) vals[i] = value[i];
    1502:     amsopt->arraylength = *n;
    1503:   }
    1504:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1505:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1506:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
    1507:     for (i=1; i<*n; i++) {
    1508:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
    1509:     }
    1510:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1511:   }
    1512:   return(0);
    1513: }

    1515: /*@C
    1516:    PetscOptionsIntArray - Gets an array of integers for a particular
    1517:    option in the database.

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

    1521:    Input Parameters:
    1522: +  opt - the option one is seeking
    1523: .  text - short string describing option
    1524: .  man - manual page for option
    1525: -  n - maximum number of values

    1527:    Output Parameter:
    1528: +  value - location to copy values
    1529: .  n - actual number of values found
    1530: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1532:    Level: beginner

    1534:    Notes:
    1535:    The array can be passed as
    1536:    a comma separated list:                                 0,1,2,3,4,5,6,7
    1537:    a range (start-end+1):                                  0-8
    1538:    a range with given increment (start-end+1:inc):         0-7:2
    1539:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

    1545:    Concepts: options database^array of ints

    1547: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1548:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1549:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1550:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1551:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1552:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    1553: @*/
    1554: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
    1555: {
    1557:   PetscInt        i;
    1558:   PetscOptionItem amsopt;

    1561:   if (!PetscOptionsObject->count) {
    1562:     PetscInt *vals;

    1564:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
    1565:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
    1566:     vals = (PetscInt*)amsopt->data;
    1567:     for (i=0; i<*n; i++) vals[i] = value[i];
    1568:     amsopt->arraylength = *n;
    1569:   }
    1570:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1571:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1572:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1573:     for (i=1; i<*n; i++) {
    1574:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1575:     }
    1576:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1577:   }
    1578:   return(0);
    1579: }

    1581: /*@C
    1582:    PetscOptionsStringArray - Gets an array of string values for a particular
    1583:    option in the database. The values must be separated with commas with
    1584:    no intervening spaces.

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

    1588:    Input Parameters:
    1589: +  opt - the option one is seeking
    1590: .  text - short string describing option
    1591: .  man - manual page for option
    1592: -  nmax - maximum number of strings

    1594:    Output Parameter:
    1595: +  value - location to copy strings
    1596: .  nmax - actual number of strings found
    1597: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1599:    Level: beginner

    1601:    Notes:
    1602:    The user should pass in an array of pointers to char, to hold all the
    1603:    strings returned by this function.

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

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

    1610:    Concepts: options database^array of strings

    1612: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1613:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1614:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1615:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1616:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1617:           PetscOptionsFList(), PetscOptionsEList()
    1618: @*/
    1619: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
    1620: {
    1621:   PetscErrorCode  ierr;
    1622:   PetscOptionItem amsopt;

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

    1629:     amsopt->arraylength = *nmax;
    1630:   }
    1631:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
    1632:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1633:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1634:   }
    1635:   return(0);
    1636: }

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

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

    1645:    Input Parameters:
    1646: +  opt - the option one is seeking
    1647: .  text - short string describing option
    1648: .  man - manual page for option
    1649: -  nmax - maximum number of values

    1651:    Output Parameter:
    1652: +  value - location to copy values
    1653: .  nmax - actual number of values found
    1654: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1656:    Level: beginner

    1658:    Notes:
    1659:    The user should pass in an array of doubles

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

    1663:    Concepts: options database^array of strings

    1665: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1666:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1667:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1668:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1669:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1670:           PetscOptionsFList(), PetscOptionsEList()
    1671: @*/
    1672: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
    1673: {
    1674:   PetscErrorCode   ierr;
    1675:   PetscInt         i;
    1676:   PetscOptionItem  amsopt;

    1679:   if (!PetscOptionsObject->count) {
    1680:     PetscBool *vals;

    1682:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
    1683:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
    1684:     vals = (PetscBool*)amsopt->data;
    1685:     for (i=0; i<*n; i++) vals[i] = value[i];
    1686:     amsopt->arraylength = *n;
    1687:   }
    1688:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
    1689:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1690:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1691:     for (i=1; i<*n; i++) {
    1692:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1693:     }
    1694:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1695:   }
    1696:   return(0);
    1697: }

    1699: /*@C
    1700:    PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user

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

    1704:    Input Parameters:
    1705: +  opt - option name
    1706: .  text - short string that describes the option
    1707: -  man - manual page with additional information on option

    1709:    Output Parameter:
    1710: +  viewer - the viewer
    1711: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1713:    Level: beginner

    1715:    Concepts: options database^has int

    1717:    Notes:
    1718:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    1722: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1723:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1724:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1725:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1726:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1727:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1728:           PetscOptionsFList(), PetscOptionsEList()
    1729: @*/
    1730: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
    1731: {
    1732:   PetscErrorCode  ierr;
    1733:   PetscOptionItem amsopt;

    1736:   if (!PetscOptionsObject->count) {
    1737:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
    1738:     /* must use system malloc since SAWs may free this */
    1739:     PetscStrdup("",(char**)&amsopt->data);
    1740:   }
    1741:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
    1742:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1743:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
    1744:   }
    1745:   return(0);
    1746: }

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

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

    1755:    Input Parameter:
    1756: .   head - the heading text

    1759:    Level: intermediate

    1761:    Notes:
    1762:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

    1766:    Concepts: options database^subheading

    1768: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1769:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1770:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1771:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1772:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1773:           PetscOptionsFList(), PetscOptionsEList()
    1774: @*/
    1775: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
    1776: {

    1780:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1781:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
    1782:   }
    1783:   return(0);
    1784: }