Actual source code: aoptions.c
petsc-3.7.1 2016-05-15
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(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
     28: {

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

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

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

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

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

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

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

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

     95:   PetscNew(amsopt);
     96:   (*amsopt)->next = 0;
     97:   (*amsopt)->set  = PETSC_FALSE;
     98:   (*amsopt)->type = t;
     99:   (*amsopt)->data = 0;

    101:   PetscStrallocpy(text,&(*amsopt)->text);
    102:   PetscStrallocpy(opt,&(*amsopt)->option);
    103:   PetscStrallocpy(man,&(*amsopt)->man);

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

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

    119:     Collective on MPI_Comm

    121:    Input Parameters:
    122: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
    123: .     n - length of the string, must be the same on all processes
    124: -     str - location to store input

    126:     Bugs:
    127: .   Assumes process 0 of the given communicator has access to stdin

    129: */
    130: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
    131: {
    132:   size_t         i;
    133:   char           c;
    134:   PetscMPIInt    rank,nm;

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

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

    165:   if (s) {
    166:     PetscStrlen(s,&len);
    167:     tmp = (char*) malloc((len+1)*sizeof(char));
    168:     if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
    169:     PetscStrcpy(tmp,s);
    170:   }
    171:   *t = tmp;
    172:   return(0);
    173: }

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

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

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

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

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

    194: */
    195: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
    196: {
    197:   PetscErrorCode  ierr;
    198:   PetscOptionItem next = PetscOptionsObject->next;
    199:   char            str[512];
    200:   PetscBool       bid;
    201:   PetscReal       ir,*valr;
    202:   PetscInt        *vald;
    203:   size_t          i;

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

    229:         next->set = PETSC_TRUE;
    230:         value     = str;
    231:         PetscTokenCreate(value,',',&token);
    232:         PetscTokenFind(token,&value);
    233:         while (n < nmax) {
    234:           if (!value) break;

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

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

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

    368: #if defined(PETSC_HAVE_SAWS)
    369: #include <petscviewersaws.h>

    371: static int count = 0;

    375: PetscErrorCode PetscOptionsSAWsDestroy(void)
    376: {
    378:   return(0);
    379: }

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

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

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

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

    406: */
    407: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
    408: {
    409:   PetscErrorCode  ierr;
    410:   PetscOptionItem next     = PetscOptionsObject->next;
    411:   static int      mancount = 0;
    412:   char            options[16];
    413:   PetscBool       changedmethod = PETSC_FALSE;
    414:   PetscBool       stopasking    = PETSC_FALSE;
    415:   char            manname[16],textname[16];
    416:   char            dir[1024];

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

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

    424:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
    425:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
    426:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
    427:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
    428:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
    429:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

    431:   while (next) {
    432:     sprintf(manname,"_man_%d",mancount);
    433:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
    434:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
    435:     sprintf(textname,"_text_%d",mancount++);
    436:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
    437:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

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

    499:   /* wait until accessor has unlocked the memory */
    500:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
    501:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
    502:   PetscSAWsBlock();
    503:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
    504:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

    506:   /* determine if any values have been set in GUI */
    507:   next = PetscOptionsObject->next;
    508:   while (next) {
    509:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
    510:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
    511:     next = next->next;
    512:   }

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

    517:   if (stopasking) {
    518:     PetscOptionsPublish      = PETSC_FALSE;
    519:     PetscOptionsObject->count = 0;//do not ask for same thing again
    520:   }

    522:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
    523:   return(0);
    524: }
    525: #endif

    529: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
    530: {
    531:   PetscErrorCode  ierr;
    532:   PetscOptionItem last;
    533:   char            option[256],value[1024],tmp[32];
    534:   size_t          j;

    537:   if (PetscOptionsObject->next) {
    538:     if (!PetscOptionsObject->count) {
    539: #if defined(PETSC_HAVE_SAWS)
    540:       PetscOptionsSAWsInput(PetscOptionsObject);
    541: #else
    542:       PetscOptionsGetFromTextInput(PetscOptionsObject);
    543: #endif
    544:     }
    545:   }

    547:   PetscFree(PetscOptionsObject->title);

    549:   /* reset counter to -2; this updates the screen with the new options for the selected method */
    550:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
    551:   /* reset alreadyprinted flag */
    552:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
    553:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
    554:   PetscOptionsObject->object = NULL;

    556:   while (PetscOptionsObject->next) {
    557:     if (PetscOptionsObject->next->set) {
    558:       if (PetscOptionsObject->prefix) {
    559:         PetscStrcpy(option,"-");
    560:         PetscStrcat(option,PetscOptionsObject->prefix);
    561:         PetscStrcat(option,PetscOptionsObject->next->option+1);
    562:       } else {
    563:         PetscStrcpy(option,PetscOptionsObject->next->option);
    564:       }

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

    638:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
    639:       free(PetscOptionsObject->next->data);
    640:     } else {
    641:       PetscFree(PetscOptionsObject->next->data);
    642:     }

    644:     last                    = PetscOptionsObject->next;
    645:     PetscOptionsObject->next = PetscOptionsObject->next->next;
    646:     PetscFree(last);
    647:   }
    648:   PetscFree(PetscOptionsObject->prefix);
    649:   PetscOptionsObject->next = 0;
    650:   return(0);
    651: }

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

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

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

    671:    Output Parameter:
    672: +  value - the  value to return
    673: -  set - PETSC_TRUE if found, else PETSC_FALSE

    675:    Level: beginner

    677:    Concepts: options database

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

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

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

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

    713: /*@C
    714:    PetscOptionsEnumArray - Gets an array of enum values for a particular
    715:    option in the database.

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

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

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

    730:    Level: beginner

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

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

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

    739:    Concepts: options database^array of enums

    741: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    742:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    743:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    744:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    745:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    746:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    747: @*/
    748: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
    749: {
    750:   PetscInt        i,nlist = 0;
    751:   PetscOptionItem amsopt;
    752:   PetscErrorCode  ierr;

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

    779: /* -------------------------------------------------------------------------------------------------------------*/
    782: /*@C
    783:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

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

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

    801:    Level: beginner

    803:    Concepts: options database^has int

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

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

    822:   if (!PetscOptionsObject->count) {
    823:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
    824:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
    825:     *(PetscInt*)amsopt->data = currentvalue;

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

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

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

    846:    Input Parameters:
    847: +  opt - option name
    848: .  text - short string that describes the option
    849: .  man - manual page with additional information on option
    850: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
    851: -  len - length of the result string including null terminator

    853:    Output Parameter:
    854: +  value - the value to return
    855: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    857:    Level: beginner

    859:    Concepts: options database^has int

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

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

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

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

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

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

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

    912:    Level: beginner

    914:    Concepts: options database^has int

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

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

    932:   if (!PetscOptionsObject->count) {
    933:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
    934:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

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

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

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

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

    963:    Output Parameter:
    964: +  value - the value to return
    965: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    967:    Level: beginner

    969:    Concepts: options database^has int

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

    973: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    974:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    975:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    976:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    977:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    978:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    979:           PetscOptionsFList(), PetscOptionsEList()
    980: @*/
    981: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
    982: {

    986: #if !defined(PETSC_USE_COMPLEX)
    987:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
    988: #else
    989:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
    990: #endif
    991:   return(0);
    992: }

    996: /*@C
    997:    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
    998:                       its value is set to false.

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

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

    1007:    Output Parameter:
    1008: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1010:    Level: beginner

    1012:    Concepts: options database^has int

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

    1016: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1017:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1018:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1019:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1020:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1021:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1022:           PetscOptionsFList(), PetscOptionsEList()
    1023: @*/
    1024: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1025: {
    1026:   PetscErrorCode  ierr;
    1027:   PetscOptionItem amsopt;

    1030:   if (!PetscOptionsObject->count) {
    1031:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1032:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1034:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1035:   }
    1036:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
    1037:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1038:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1039:   }
    1040:   return(0);
    1041: }

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

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

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

    1060:    Output Parameter:
    1061: +  value - the value to return
    1062: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1064:    Level: intermediate

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

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

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

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

    1075:    Concepts: options database^list

    1077: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1078:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1079:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1080:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1081:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1082:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
    1083: @*/
    1084: 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)
    1085: {
    1086:   PetscErrorCode  ierr;
    1087:   PetscOptionItem amsopt;

    1090:   if (!PetscOptionsObject->count) {
    1091:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
    1092:     /* must use system malloc since SAWs may free this */
    1093:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
    1094:     amsopt->flist = list;
    1095:   }
    1096:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
    1097:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1098:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
    1099:   }
    1100:   return(0);
    1101: }

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

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

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

    1121:    Output Parameter:
    1122: +  value - the index of the value to return
    1123: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1125:    Level: intermediate

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

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

    1131:    Concepts: options database^list

    1133: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1134:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1135:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1136:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1137:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1138:           PetscOptionsFList(), PetscOptionsEnum()
    1139: @*/
    1140: 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)
    1141: {
    1142:   PetscErrorCode  ierr;
    1143:   PetscInt        i;
    1144:   PetscOptionItem amsopt;

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

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

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

    1173:    Input Parameters:
    1174: +  opt - option name
    1175: .  text - short string that describes the option
    1176: -  man - manual page with additional information on option

    1178:    Output Parameter:
    1179: .  flg - whether that option was set or not

    1181:    Level: intermediate

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

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

    1187:     Concepts: options database^logical group

    1189: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1190:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1191:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1192:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1193:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1194:           PetscOptionsFList(), PetscOptionsEList()
    1195: @*/
    1196: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1197: {
    1198:   PetscErrorCode  ierr;
    1199:   PetscOptionItem amsopt;

    1202:   if (!PetscOptionsObject->count) {
    1203:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1204:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1206:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1207:   }
    1208:   *flg = PETSC_FALSE;
    1209:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1210:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1211:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
    1212:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1213:   }
    1214:   return(0);
    1215: }

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

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

    1225:    Input Parameters:
    1226: +  opt - option name
    1227: .  text - short string that describes the option
    1228: -  man - manual page with additional information on option

    1230:    Output Parameter:
    1231: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1233:    Level: intermediate

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

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

    1239:     Concepts: options database^logical group

    1241: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1242:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1243:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1244:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1245:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1246:           PetscOptionsFList(), PetscOptionsEList()
    1247: @*/
    1248: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1249: {
    1250:   PetscErrorCode  ierr;
    1251:   PetscOptionItem amsopt;

    1254:   if (!PetscOptionsObject->count) {
    1255:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1256:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1258:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1259:   }
    1260:   *flg = PETSC_FALSE;
    1261:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1262:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1263:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1264:   }
    1265:   return(0);
    1266: }

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

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

    1276:    Input Parameters:
    1277: +  opt - option name
    1278: .  text - short string that describes the option
    1279: -  man - manual page with additional information on option

    1281:    Output Parameter:
    1282: .  flg - PETSC_TRUE if found, else PETSC_FALSE

    1284:    Level: intermediate

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

    1288:    Must follow a PetscOptionsBoolGroupBegin()

    1290:     Concepts: options database^logical group

    1292: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1293:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1294:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1295:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1296:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1297:           PetscOptionsFList(), PetscOptionsEList()
    1298: @*/
    1299: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
    1300: {
    1301:   PetscErrorCode  ierr;
    1302:   PetscOptionItem amsopt;

    1305:   if (!PetscOptionsObject->count) {
    1306:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1307:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

    1309:     *(PetscBool*)amsopt->data = PETSC_FALSE;
    1310:   }
    1311:   *flg = PETSC_FALSE;
    1312:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
    1313:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1314:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1315:   }
    1316:   return(0);
    1317: }

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

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

    1326:    Input Parameters:
    1327: +  opt - option name
    1328: .  text - short string that describes the option
    1329: .  man - manual page with additional information on option
    1330: -  currentvalue - the current value

    1332:    Output Parameter:
    1333: .  flg - PETSC_TRUE or PETSC_FALSE
    1334: .  set - PETSC_TRUE if found, else PETSC_FALSE

    1336:    Level: beginner

    1338:    Concepts: options database^logical

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

    1342: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1343:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1344:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1345:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1346:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1347:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1348:           PetscOptionsFList(), PetscOptionsEList()
    1349: @*/
    1350: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
    1351: {
    1352:   PetscErrorCode  ierr;
    1353:   PetscBool       iset;
    1354:   PetscOptionItem amsopt;

    1357:   if (!PetscOptionsObject->count) {
    1358:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
    1359:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

    1374: /*@C
    1375:    PetscOptionsRealArray - Gets an array of double values for a particular
    1376:    option in the database. The values must be separated with commas with
    1377:    no intervening spaces.

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

    1381:    Input Parameters:
    1382: +  opt - the option one is seeking
    1383: .  text - short string describing option
    1384: .  man - manual page for option
    1385: -  nmax - maximum number of values

    1387:    Output Parameter:
    1388: +  value - location to copy values
    1389: .  nmax - actual number of values found
    1390: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1392:    Level: beginner

    1394:    Notes:
    1395:    The user should pass in an array of doubles

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

    1399:    Concepts: options database^array of strings

    1401: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1402:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1403:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1404:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1405:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1406:           PetscOptionsFList(), PetscOptionsEList()
    1407: @*/
    1408: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
    1409: {
    1410:   PetscErrorCode  ierr;
    1411:   PetscInt        i;
    1412:   PetscOptionItem amsopt;

    1415:   if (!PetscOptionsObject->count) {
    1416:     PetscReal *vals;

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

    1437: /*@C
    1438:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
    1439:    option in the database. The values must be separated with commas with
    1440:    no intervening spaces.

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

    1444:    Input Parameters:
    1445: +  opt - the option one is seeking
    1446: .  text - short string describing option
    1447: .  man - manual page for option
    1448: -  nmax - maximum number of values

    1450:    Output Parameter:
    1451: +  value - location to copy values
    1452: .  nmax - actual number of values found
    1453: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1455:    Level: beginner

    1457:    Notes:
    1458:    The user should pass in an array of doubles

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

    1462:    Concepts: options database^array of strings

    1464: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1465:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1466:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1467:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1468:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1469:           PetscOptionsFList(), PetscOptionsEList()
    1470: @*/
    1471: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
    1472: {
    1473:   PetscErrorCode  ierr;
    1474:   PetscInt        i;
    1475:   PetscOptionItem amsopt;

    1478:   if (!PetscOptionsObject->count) {
    1479:     PetscScalar *vals;

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

    1500: /*@C
    1501:    PetscOptionsIntArray - Gets an array of integers for a particular
    1502:    option in the database.

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

    1506:    Input Parameters:
    1507: +  opt - the option one is seeking
    1508: .  text - short string describing option
    1509: .  man - manual page for option
    1510: -  n - maximum number of values

    1512:    Output Parameter:
    1513: +  value - location to copy values
    1514: .  n - actual number of values found
    1515: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1517:    Level: beginner

    1519:    Notes:
    1520:    The array can be passed as
    1521:    a comma separated list:                                 0,1,2,3,4,5,6,7
    1522:    a range (start-end+1):                                  0-8
    1523:    a range with given increment (start-end+1:inc):         0-7:2
    1524:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

    1530:    Concepts: options database^array of ints

    1532: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1533:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1534:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1535:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1536:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1537:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
    1538: @*/
    1539: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
    1540: {
    1542:   PetscInt        i;
    1543:   PetscOptionItem amsopt;

    1546:   if (!PetscOptionsObject->count) {
    1547:     PetscInt *vals;

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

    1568: /*@C
    1569:    PetscOptionsStringArray - Gets an array of string values for a particular
    1570:    option in the database. The values must be separated with commas with
    1571:    no intervening spaces.

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

    1575:    Input Parameters:
    1576: +  opt - the option one is seeking
    1577: .  text - short string describing option
    1578: .  man - manual page for option
    1579: -  nmax - maximum number of strings

    1581:    Output Parameter:
    1582: +  value - location to copy strings
    1583: .  nmax - actual number of strings found
    1584: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1586:    Level: beginner

    1588:    Notes:
    1589:    The user should pass in an array of pointers to char, to hold all the
    1590:    strings returned by this function.

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

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

    1597:    Concepts: options database^array of strings

    1599: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1600:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1601:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1602:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1603:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1604:           PetscOptionsFList(), PetscOptionsEList()
    1605: @*/
    1606: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
    1607: {
    1608:   PetscErrorCode  ierr;
    1609:   PetscOptionItem amsopt;

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

    1616:     amsopt->arraylength = *nmax;
    1617:   }
    1618:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
    1619:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1620:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
    1621:   }
    1622:   return(0);
    1623: }

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

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

    1634:    Input Parameters:
    1635: +  opt - the option one is seeking
    1636: .  text - short string describing option
    1637: .  man - manual page for option
    1638: -  nmax - maximum number of values

    1640:    Output Parameter:
    1641: +  value - location to copy values
    1642: .  nmax - actual number of values found
    1643: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1645:    Level: beginner

    1647:    Notes:
    1648:    The user should pass in an array of doubles

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

    1652:    Concepts: options database^array of strings

    1654: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1655:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1656:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1657:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1658:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1659:           PetscOptionsFList(), PetscOptionsEList()
    1660: @*/
    1661: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
    1662: {
    1663:   PetscErrorCode   ierr;
    1664:   PetscInt         i;
    1665:   PetscOptionItem  amsopt;

    1668:   if (!PetscOptionsObject->count) {
    1669:     PetscBool *vals;

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

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

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

    1695:    Input Parameters:
    1696: +  opt - option name
    1697: .  text - short string that describes the option
    1698: -  man - manual page with additional information on option

    1700:    Output Parameter:
    1701: +  viewer - the viewer
    1702: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1704:    Level: beginner

    1706:    Concepts: options database^has int

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

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

    1712: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
    1713:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1714:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1715:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1716:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1717:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1718:           PetscOptionsFList(), PetscOptionsEList()
    1719: @*/
    1720: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
    1721: {
    1722:   PetscErrorCode  ierr;
    1723:   PetscOptionItem amsopt;

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

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

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

    1747:    Input Parameter:
    1748: .   head - the heading text

    1751:    Level: intermediate

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

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

    1757:    Concepts: options database^subheading

    1759: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
    1760:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1761:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1762:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1763:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1764:           PetscOptionsFList(), PetscOptionsEList()
    1765: @*/
    1766: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
    1767: {

    1771:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
    1772:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
    1773:   }
    1774:   return(0);
    1775: }