Date: 2015-10-02T22:00:27+00:00

Actual source code: aoptions.c
petsc-3.6.2 2015-10-02
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>        /*I  "petscsys.h"   I*/
     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: */

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

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

     36:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
     37:   PetscStrallocpy(title,&PetscOptionsObject->title);

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

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

     61:   PetscOptionsObject->object         = obj;
     62:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

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

     74: /*
     75:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
     76: */
     79: static int PetscOptionsCreate_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOption *amsopt)
     80: {
     81:   int          ierr;
     82:   PetscOption 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: }

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

    113:     Collective on MPI_Comm

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    305:         next->set = PETSC_TRUE;
    306:         *((PetscInt*)next->data) = (PetscInt)lid;
    307:       }
    308:       break;
    309:     case OPTION_REAL:
    310:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
    311:       PetscScanString(PETSC_COMM_WORLD,512,str);
    312:       if (str[0]) {
    313: #if defined(PETSC_USE_REAL_SINGLE)
    314:         sscanf(str,"%e",&ir);
    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;

    369: PetscErrorCode PetscOptionsSAWsDestroy(void)
    370: {
    372:   return(0);
    373: }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    523: PetscErrorCode PetscOptionsEnd_Private(PetscOptions *PetscOptionsObject)
    524: {
    526:   PetscOption   last;
    527:   char           option[256],value[1024],tmp[32];
    528:   size_t         j;

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

    541:   PetscFree(PetscOptionsObject->title);

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

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

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

    632:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
    633:       free(PetscOptionsObject->next->data);
    634:     } else {
    635:       PetscFree(PetscOptionsObject->next->data);
    636:     }

    638:     last                    = PetscOptionsObject->next;
    639:     PetscOptionsObject->next = PetscOptionsObject->next->next;
    640:     PetscFree(last);
    641:   }
    642:   PetscFree(PetscOptionsObject->prefix);
    643:   PetscOptionsObject->next = 0;
    644:   return(0);
    645: }

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

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

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

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

    669:    Level: beginner

    671:    Concepts: options database

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

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

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

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

    707: /*@C
    708:    PetscOptionsEnumArray - Gets an array of enum values for a particular
    709:    option in the database.

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

    713:    Input Parameters:
    714: +  opt - the option one is seeking
    715: .  text - short string describing option
    716: .  man - manual page for option
    717: -  n - maximum number of values

    719:    Output Parameter:
    720: +  value - location to copy values
    721: .  n - actual number of values found
    722: -  set - PETSC_TRUE if found, else PETSC_FALSE

    724:    Level: beginner

    726:    Notes:
    727:    The array must be passed as a comma separated list.

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

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

    733:    Concepts: options database^array of enums

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

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

    773: /* -------------------------------------------------------------------------------------------------------------*/
    776: /*@C
    777:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

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

    791:    Output Parameter:
    792: +  value - the integer value to return
    793: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    795:    Level: beginner

    797:    Concepts: options database^has int

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

    801: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    802:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    803:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    804:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    805:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    806:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    807:           PetscOptionsFList(), PetscOptionsEList()
    808: @*/
    809: PetscErrorCode  PetscOptionsInt_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set)
    810: {
    812:   PetscOption    amsopt;
    813:   PetscBool      wasset;
    814:
    816:   if (!PetscOptionsObject->count) {
    817:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
    818:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
    819:     *(PetscInt*)amsopt->data = currentvalue;

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

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

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

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

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

    851:    Level: beginner

    853:    Concepts: options database^has int

    855:    Notes: 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: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    860:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    861:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
    862:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    863:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    864:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    865:           PetscOptionsFList(), PetscOptionsEList()
    866: @*/
    867: PetscErrorCode  PetscOptionsString_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
    868: {
    870:   PetscOption   amsopt;

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

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

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

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

    902:    Output Parameter:
    903: +  value - the value to return
    904: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    906:    Level: beginner

    908:    Concepts: options database^has int

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

    912: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    913:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    914:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    915:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    916:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    917:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    918:           PetscOptionsFList(), PetscOptionsEList()
    919: @*/
    920: PetscErrorCode  PetscOptionsReal_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
    921: {
    923:   PetscOption   amsopt;

    926:   if (!PetscOptionsObject->count) {
    927:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
    928:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

    930:     *(PetscReal*)amsopt->data = currentvalue;
    931:   }
    932:   PetscOptionsGetReal(PetscOptionsObject->prefix,opt,value,set);
    933:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    934:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
    935:   }
    936:   return(0);
    937: }

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

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

    946:    Input Parameters:
    947: +  opt - option name
    948: .  text - short string that describes the option
    949: .  man - manual page with additional information on option
    950: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    951: $                 PetscOptionsScalar(..., obj->value,&object->value,...) or
    952: $                 value = defaultvalue
    953: $                 PetscOptionsScalar(..., value,&value,&flg);
    954: $                 if (flg) {

    957:    Output Parameter:
    958: +  value - the value to return
    959: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    961:    Level: beginner

    963:    Concepts: options database^has int

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

    967: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    968:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    969:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    970:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    971:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    972:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    973:           PetscOptionsFList(), PetscOptionsEList()
    974: @*/
    975: PetscErrorCode  PetscOptionsScalar_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
    976: {

    980: #if !defined(PETSC_USE_COMPLEX)
    981:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
    982: #else
    983:   PetscOptionsGetScalar(PetscOptionsObject->prefix,opt,value,set);
    984: #endif
    985:   return(0);
    986: }

    990: /*@C
    991:    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
    992:                       its value is set to false.

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

    996:    Input Parameters:
    997: +  opt - option name
    998: .  text - short string that describes the option
    999: -  man - manual page with additional information on option

    1001:    Output Parameter:
    1002: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1004:    Level: beginner

    1006:    Concepts: options database^has int

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

    1010: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1011:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1012:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1013:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1014:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1015:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1016:           PetscOptionsFList(), PetscOptionsEList()
    1017: @*/
    1018: PetscErrorCode  PetscOptionsName_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1019: {
    1021:   PetscOption   amsopt;

    1024:   if (!PetscOptionsObject->count) {
    1025:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1026:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1028:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1029:   }
    1030:   PetscOptionsHasName(PetscOptionsObject->prefix,opt,flg);
    1031:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1032:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1033:   }
    1034:   return(0);
    1035: }

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

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

    1044:    Input Parameters:
    1045: +  opt - option name
    1046: .  text - short string that describes the option
    1047: .  man - manual page with additional information on option
    1048: .  list - the possible choices
    1049: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1050: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
    1051: $                 if (flg) {
    1052: -  len - the length of the character array value

    1054:    Output Parameter:
    1055: +  value - the value to return
    1056: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1058:    Level: intermediate

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

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

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

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

    1069:    Concepts: options database^list

    1071: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1072:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1073:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1074:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1075:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1076:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
    1077: @*/
    1078: PetscErrorCode  PetscOptionsFList_Private(PetscOptions *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)
    1079: {
    1081:   PetscOption   amsopt;

    1084:   if (!PetscOptionsObject->count) {
    1085:     PetscOptionsCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
    1086:     /* must use system malloc since SAWs may free this */
    1087:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1088:     amsopt->flist = list;
    1089:   }
    1090:   PetscOptionsGetString(PetscOptionsObject->prefix,opt,value,len,set);
    1091:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1092:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
    1093:   }
    1094:   return(0);
    1095: }

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

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

    1104:    Input Parameters:
    1105: +  opt - option name
    1106: .  ltext - short string that describes the option
    1107: .  man - manual page with additional information on option
    1108: .  list - the possible choices (one of these must be selected, anything else is invalid)
    1109: .  ntext - number of choices
    1110: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1111: $                 PetscOptionsElist(..., obj->value,&value,&flg);
    1112: $                 if (flg) {

    1115:    Output Parameter:
    1116: +  value - the index of the value to return
    1117: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1119:    Level: intermediate

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

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

    1125:    Concepts: options database^list

    1127: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1128:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1129:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1130:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1131:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1132:           PetscOptionsFList(), PetscOptionsEnum()
    1133: @*/
    1134: PetscErrorCode  PetscOptionsEList_Private(PetscOptions *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)
    1135: {
    1137:   PetscInt       i;
    1138:   PetscOption   amsopt;

    1141:   if (!PetscOptionsObject->count) {
    1142:     PetscOptionsCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
    1143:     /* must use system malloc since SAWs may free this */
    1144:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1145:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
    1146:     amsopt->nlist = ntext;
    1147:   }
    1148:   PetscOptionsGetEList(PetscOptionsObject->prefix,opt,list,ntext,value,set);
    1149:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1150:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue);
    1151:     for (i=0; i<ntext; i++) {
    1152:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
    1153:     }
    1154:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
    1155:   }
    1156:   return(0);
    1157: }

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

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

    1167:    Input Parameters:
    1168: +  opt - option name
    1169: .  text - short string that describes the option
    1170: -  man - manual page with additional information on option

    1172:    Output Parameter:
    1173: .  flg - whether that option was set or not

    1175:    Level: intermediate

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

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

    1181:     Concepts: options database^logical group

    1183: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1184:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1185:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1186:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1187:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1188:           PetscOptionsFList(), PetscOptionsEList()
    1189: @*/
    1190: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1191: {
    1193:   PetscOption   amsopt;

    1196:   if (!PetscOptionsObject->count) {
    1197:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1198:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1200:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1201:   }
    1202:   *flg = PETSC_FALSE;
    1203:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,NULL);
    1204:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1205:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
    1206:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1207:   }
    1208:   return(0);
    1209: }

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

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

    1219:    Input Parameters:
    1220: +  opt - option name
    1221: .  text - short string that describes the option
    1222: -  man - manual page with additional information on option

    1224:    Output Parameter:
    1225: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1227:    Level: intermediate

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

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

    1233:     Concepts: options database^logical group

    1235: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1236:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1237:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1238:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1239:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1240:           PetscOptionsFList(), PetscOptionsEList()
    1241: @*/
    1242: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1243: {
    1245:   PetscOption   amsopt;

    1248:   if (!PetscOptionsObject->count) {
    1249:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1250:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1252:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1253:   }
    1254:   *flg = PETSC_FALSE;
    1255:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,NULL);
    1256:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1257:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1258:   }
    1259:   return(0);
    1260: }

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

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

    1270:    Input Parameters:
    1271: +  opt - option name
    1272: .  text - short string that describes the option
    1273: -  man - manual page with additional information on option

    1275:    Output Parameter:
    1276: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1278:    Level: intermediate

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

    1282:    Must follow a PetscOptionsBoolGroupBegin()

    1284:     Concepts: options database^logical group

    1286: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1287:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1288:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1289:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1290:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1291:           PetscOptionsFList(), PetscOptionsEList()
    1292: @*/
    1293: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1294: {
    1296:   PetscOption   amsopt;

    1299:   if (!PetscOptionsObject->count) {
    1300:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1301:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1303:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1304:   }
    1305:   *flg = PETSC_FALSE;
    1306:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,NULL);
    1307:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1308:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1309:   }
    1310:   return(0);
    1311: }

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

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

    1320:    Input Parameters:
    1321: +  opt - option name
    1322: .  text - short string that describes the option
    1323: .  man - manual page with additional information on option
    1324: -  currentvalue - the current value

    1326:    Output Parameter:
    1327: .  flg - PETSC_TRUE or PETSC_FALSE
    1328: .  set - PETSC_TRUE if found, else PETSC_FALSE

    1330:    Level: beginner

    1332:    Concepts: options database^logical

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

    1336: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1337:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1338:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1339:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1340:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1341:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1342:           PetscOptionsFList(), PetscOptionsEList()
    1343: @*/
    1344: PetscErrorCode  PetscOptionsBool_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
    1345: {
    1347:   PetscBool      iset;
    1348:   PetscOption   amsopt;

    1351:   if (!PetscOptionsObject->count) {
    1352:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1353:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1355:     *(PetscBool*)amsopt->data = currentvalue;
    1356:   }
    1357:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,&iset);
    1358:   if (set) *set = iset;
    1359:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1360:     const char *v = PetscBools[currentvalue];
    1361:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
    1362:   }
    1363:   return(0);
    1364: }

    1368: /*@C
    1369:    PetscOptionsRealArray - Gets an array of double values for a particular
    1370:    option in the database. The values must be separated with commas with
    1371:    no intervening spaces.

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

    1375:    Input Parameters:
    1376: +  opt - the option one is seeking
    1377: .  text - short string describing option
    1378: .  man - manual page for option
    1379: -  nmax - maximum number of values

    1381:    Output Parameter:
    1382: +  value - location to copy values
    1383: .  nmax - actual number of values found
    1384: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1386:    Level: beginner

    1388:    Notes:
    1389:    The user should pass in an array of doubles

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

    1393:    Concepts: options database^array of strings

    1395: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1396:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1397:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1398:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1399:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1400:           PetscOptionsFList(), PetscOptionsEList()
    1401: @*/
    1402: PetscErrorCode PetscOptionsRealArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
    1403: {
    1405:   PetscInt       i;
    1406:   PetscOption   amsopt;

    1409:   if (!PetscOptionsObject->count) {
    1410:     PetscReal *vals;

    1412:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
    1413:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
    1414:     vals = (PetscReal*)amsopt->data;
    1415:     for (i=0; i<*n; i++) vals[i] = value[i];
    1416:     amsopt->arraylength = *n;
    1417:   }
    1418:   PetscOptionsGetRealArray(PetscOptionsObject->prefix,opt,value,n,set);
    1419:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1420:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
    1421:     for (i=1; i<*n; i++) {
    1422:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
    1423:     }
    1424:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1425:   }
    1426:   return(0);
    1427: }

    1431: /*@C
    1432:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
    1433:    option in the database. The values must be separated with commas with
    1434:    no intervening spaces.

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

    1438:    Input Parameters:
    1439: +  opt - the option one is seeking
    1440: .  text - short string describing option
    1441: .  man - manual page for option
    1442: -  nmax - maximum number of values

    1444:    Output Parameter:
    1445: +  value - location to copy values
    1446: .  nmax - actual number of values found
    1447: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1449:    Level: beginner

    1451:    Notes:
    1452:    The user should pass in an array of doubles

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

    1456:    Concepts: options database^array of strings

    1458: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1459:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1460:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1461:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1462:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1463:           PetscOptionsFList(), PetscOptionsEList()
    1464: @*/
    1465: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
    1466: {
    1468:   PetscInt       i;
    1469:   PetscOption   amsopt;

    1472:   if (!PetscOptionsObject->count) {
    1473:     PetscScalar *vals;

    1475:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
    1476:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
    1477:     vals = (PetscScalar*)amsopt->data;
    1478:     for (i=0; i<*n; i++) vals[i] = value[i];
    1479:     amsopt->arraylength = *n;
    1480:   }
    1481:   PetscOptionsGetScalarArray(PetscOptionsObject->prefix,opt,value,n,set);
    1482:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1483:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
    1484:     for (i=1; i<*n; i++) {
    1485:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
    1486:     }
    1487:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1488:   }
    1489:   return(0);
    1490: }

    1494: /*@C
    1495:    PetscOptionsIntArray - Gets an array of integers for a particular
    1496:    option in the database.

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

    1500:    Input Parameters:
    1501: +  opt - the option one is seeking
    1502: .  text - short string describing option
    1503: .  man - manual page for option
    1504: -  n - maximum number of values

    1506:    Output Parameter:
    1507: +  value - location to copy values
    1508: .  n - actual number of values found
    1509: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1511:    Level: beginner

    1513:    Notes:
    1514:    The array can be passed as
    1515:    a comma separated list:                                 0,1,2,3,4,5,6,7
    1516:    a range (start-end+1):                                  0-8
    1517:    a range with given increment (start-end+1:inc):         0-7:2
    1518:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

    1524:    Concepts: options database^array of ints

    1526: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1527:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1528:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1529:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1530:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1531:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    1532: @*/
    1533: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
    1534: {
    1536:   PetscInt       i;
    1537:   PetscOption   amsopt;

    1540:   if (!PetscOptionsObject->count) {
    1541:     PetscInt *vals;

    1543:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
    1544:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
    1545:     vals = (PetscInt*)amsopt->data;
    1546:     for (i=0; i<*n; i++) vals[i] = value[i];
    1547:     amsopt->arraylength = *n;
    1548:   }
    1549:   PetscOptionsGetIntArray(PetscOptionsObject->prefix,opt,value,n,set);
    1550:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1551:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1552:     for (i=1; i<*n; i++) {
    1553:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1554:     }
    1555:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1556:   }
    1557:   return(0);
    1558: }

    1562: /*@C
    1563:    PetscOptionsStringArray - Gets an array of string values for a particular
    1564:    option in the database. The values must be separated with commas with
    1565:    no intervening spaces.

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

    1569:    Input Parameters:
    1570: +  opt - the option one is seeking
    1571: .  text - short string describing option
    1572: .  man - manual page for option
    1573: -  nmax - maximum number of strings

    1575:    Output Parameter:
    1576: +  value - location to copy strings
    1577: .  nmax - actual number of strings found
    1578: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1580:    Level: beginner

    1582:    Notes:
    1583:    The user should pass in an array of pointers to char, to hold all the
    1584:    strings returned by this function.

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

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

    1591:    Concepts: options database^array of strings

    1593: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1594:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1595:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1596:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1597:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1598:           PetscOptionsFList(), PetscOptionsEList()
    1599: @*/
    1600: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
    1601: {
    1603:   PetscOption   amsopt;

    1606:   if (!PetscOptionsObject->count) {
    1607:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
    1608:     PetscMalloc1(*nmax,(char**)&amsopt->data);

    1610:     amsopt->arraylength = *nmax;
    1611:   }
    1612:   PetscOptionsGetStringArray(PetscOptionsObject->prefix,opt,value,nmax,set);
    1613:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1614:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1615:   }
    1616:   return(0);
    1617: }

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

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

    1628:    Input Parameters:
    1629: +  opt - the option one is seeking
    1630: .  text - short string describing option
    1631: .  man - manual page for option
    1632: -  nmax - maximum number of values

    1634:    Output Parameter:
    1635: +  value - location to copy values
    1636: .  nmax - actual number of values found
    1637: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1639:    Level: beginner

    1641:    Notes:
    1642:    The user should pass in an array of doubles

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

    1646:    Concepts: options database^array of strings

    1648: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1649:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1650:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1651:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1652:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1653:           PetscOptionsFList(), PetscOptionsEList()
    1654: @*/
    1655: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
    1656: {
    1658:   PetscInt       i;
    1659:   PetscOption    amsopt;

    1662:   if (!PetscOptionsObject->count) {
    1663:     PetscBool *vals;

    1665:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
    1666:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
    1667:     vals = (PetscBool*)amsopt->data;
    1668:     for (i=0; i<*n; i++) vals[i] = value[i];
    1669:     amsopt->arraylength = *n;
    1670:   }
    1671:   PetscOptionsGetBoolArray(PetscOptionsObject->prefix,opt,value,n,set);
    1672:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1673:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
    1674:     for (i=1; i<*n; i++) {
    1675:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
    1676:     }
    1677:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
    1678:   }
    1679:   return(0);
    1680: }

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

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

    1689:    Input Parameters:
    1690: +  opt - option name
    1691: .  text - short string that describes the option
    1692: -  man - manual page with additional information on option

    1694:    Output Parameter:
    1695: +  viewer - the viewer
    1696: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1698:    Level: beginner

    1700:    Concepts: options database^has int

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

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

    1706: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1707:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1708:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1709:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1710:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1711:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1712:           PetscOptionsFList(), PetscOptionsEList()
    1713: @*/
    1714: PetscErrorCode  PetscOptionsViewer_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
    1715: {
    1717:   PetscOption    amsopt;

    1720:   if (!PetscOptionsObject->count) {
    1721:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
    1722:     /* must use system malloc since SAWs may free this */
    1723:     PetscStrdup("",(char**)&amsopt->data);
    1724:   }
    1725:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
    1726:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1727:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
    1728:   }
    1729:   return(0);
    1730: }

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

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

    1741:    Input Parameter:
    1742: .   head - the heading text

    1745:    Level: intermediate

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

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

    1751:    Concepts: options database^subheading

    1753: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1754:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1755:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1756:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1757:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1758:           PetscOptionsFList(), PetscOptionsEList()
    1759: @*/
    1760: PetscErrorCode  PetscOptionsHead(PetscOptions *PetscOptionsObject,const char head[])
    1761: {

    1765:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1766:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
    1767:   }
    1768:   return(0);
    1769: }