Actual source code: options.c
petsc-3.7.1 2016-05-15
Report Typos and Errors

      2: /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
      3: #define PETSC_DESIRE_FEATURE_TEST_MACROS

      5: /*
      6:    These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
      7:    This provides the low-level interface, the high level interface is in aoptions.c

      9:    Some routines use regular malloc and free because it cannot know  what malloc is requested with the
     10:    options database until it has already processed the input.
     11: */

     13: #include <petsc/private/petscimpl.h>        /*I  "petscsys.h"   I*/
     14: #include <petscviewer.h>
     15: #include <ctype.h>
     16: #if defined(PETSC_HAVE_MALLOC_H)
     17: #include <malloc.h>
     18: #endif
     19: #if defined(PETSC_HAVE_STRING_H)
     20: #include <string.h>             /* strstr */
     21: #endif
     22: #if defined(PETSC_HAVE_STRINGS_H)
     23: #  include <strings.h>          /* strcasecmp */
     24: #endif
     25: #if defined(PETSC_HAVE_YAML)
     26: #include <yaml.h>
     27: #endif

     29: /*
     30:     This table holds all the options set by the user. For simplicity, we use a static size database
     31: */
     32: #define MAXOPTIONS 512
     33: #define MAXALIASES 25
     34: #define MAXOPTIONSMONITORS 5
     35: #define MAXPREFIXES 25

     37: struct  _n_PetscOptions {
     38:   int            N,argc,Naliases;
     39:   char           **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
     40:   char           *aliases1[MAXALIASES],*aliases2[MAXALIASES];
     41:   PetscBool      used[MAXOPTIONS];
     42:   PetscBool      namegiven;
     43:   char           programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */

     45:   /* --------User (or default) routines (most return -1 on error) --------*/
     46:   PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
     47:   PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**);         /* */
     48:   void           *monitorcontext[MAXOPTIONSMONITORS];                  /* to pass arbitrary user data into monitor */
     49:   PetscInt       numbermonitors;                                       /* to, for instance, detect options being set */

     51:   /* Prefixes */
     52:   PetscInt prefixind,prefixstack[MAXPREFIXES];
     53:   char     prefix[2048];
     54: };

     57: static PetscOptions      defaultoptions = NULL;

     59: /*
     60:     Options events monitor
     61: */
     62: #define PetscOptionsMonitor(name,value)                              \
     63:   { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
     64:     for (_i=0; _i<_im; _i++) { \
     65:       _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
     66:     } \
     67:   }

     71: /*
     72:    PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
     73: */
     74: PetscErrorCode  PetscOptionsStringToInt(const char name[],PetscInt *a)
     75: {
     77:   size_t         i,len;
     78:   PetscBool      decide,tdefault,mouse;

     81:   PetscStrlen(name,&len);
     82:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

     84:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
     85:   if (!tdefault) {
     86:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
     87:   }
     88:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
     89:   if (!decide) {
     90:     PetscStrcasecmp(name,"DECIDE",&decide);
     91:   }
     92:   PetscStrcasecmp(name,"mouse",&mouse);

     94:   if (tdefault)    *a = PETSC_DEFAULT;
     95:   else if (decide) *a = PETSC_DECIDE;
     96:   else if (mouse)  *a = -1;
     97:   else {
     98:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);

    100:     for (i=1; i<len; i++) {
    101:       if (name[i] < '0' || name[i] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
    102:     }

    104: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
    105:     *a = atoll(name);
    106: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
    107:     *a = _atoi64(name);
    108: #else
    109:     *a = (PetscInt)atoi(name);
    110: #endif
    111:   }
    112:   return(0);
    113: }

    115: #if defined(PETSC_USE_REAL___FLOAT128)
    116: #include <quadmath.h>
    117: #endif

    121: /*
    122:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
    123: */
    124: PetscErrorCode  PetscOptionsStringToReal(const char name[],PetscReal *a)
    125: {
    127:   size_t         len;
    128:   PetscBool      decide,tdefault;

    131:   PetscStrlen(name,&len);
    132:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

    134:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
    135:   if (!tdefault) {
    136:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
    137:   }
    138:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
    139:   if (!decide) {
    140:     PetscStrcasecmp(name,"DECIDE",&decide);
    141:   }

    143:   if (tdefault)    *a = PETSC_DEFAULT;
    144:   else if (decide) *a = PETSC_DECIDE;
    145:   else {
    146:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
    147: #if defined(PETSC_USE_REAL___FLOAT128)
    148:     *a = strtoflt128(name,NULL);
    149: #else
    150:     *a = atof(name);
    151: #endif
    152:   }
    153:   return(0);
    154: }

    158: /*
    159:    Converts a string to PetscScalar value. Handles
    160:       [-][2].0
    161:       [-][2].0i
    162:       [-][2].0+/-2.0i

    164: */
    165: PetscErrorCode  PetscOptionsStringToScalar(const char name[],PetscScalar *a)
    166: {
    168:   size_t         len;

    171:   PetscStrlen(name,&len);
    172:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");

    174:   if (name[0] == '+') name++;
    175:   if (name[0] == 'i') {
    176: #if defined(PETSC_USE_COMPLEX)
    177:     *a = PETSC_i;
    178: #else
    179:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
    180: #endif
    181:   } else {
    182:     PetscToken token;
    183:     char       *tvalue1,*tvalue2;
    184:     PetscBool  neg = PETSC_FALSE, negim = PETSC_FALSE;
    185:     PetscReal  re = 0.0,im = 0.0;

    187:     if (name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
    188:     if (name[0] == '-') {
    189:       neg = PETSC_TRUE;
    190:       name++;
    191:     }
    192:     if (name[0] == 'i') {
    193: #if defined(PETSC_USE_COMPLEX)
    194:       *a = -PETSC_i;
    195: #else
    196:      SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
    197: #endif
    198:       return(0);
    199:     }

    201:     PetscTokenCreate(name,'+',&token);
    202:     PetscTokenFind(token,&tvalue1);
    203:     PetscTokenFind(token,&tvalue2);
    204:     if (!tvalue2) {
    205:       negim = PETSC_TRUE;
    206:       PetscTokenDestroy(&token);
    207:       PetscTokenCreate(name,'-',&token);
    208:       PetscTokenFind(token,&tvalue1);
    209:       PetscTokenFind(token,&tvalue2);
    210:     }
    211:     if (!tvalue2) {
    212:       PetscBool isim;
    213:       PetscStrendswith(tvalue1,"i",&isim);
    214:       if (isim) {
    215:         tvalue2 = tvalue1;
    216:         tvalue1 = NULL;
    217:         negim   = neg;
    218:       }
    219:     } else {
    220:       PetscBool isim;
    221:       PetscStrendswith(tvalue2,"i",&isim);
    222:       if (!isim) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
    223:     }
    224:     if (tvalue1) {
    225:       PetscOptionsStringToReal(tvalue1,&re);
    226:       if (neg) re = -re;
    227:     }
    228:     if (tvalue2) {
    229:       PetscStrlen(tvalue2,&len);
    230:       tvalue2[len-1] = 0;
    231:       PetscOptionsStringToReal(tvalue2,&im);
    232:       if (negim) im = -im;
    233:     }
    234:     PetscTokenDestroy(&token);
    235: #if defined(PETSC_USE_COMPLEX)
    236:     *a = re + im*PETSC_i;
    237: #else
    238:     if (im != 0.0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is complex but complex not supported ",name);
    239:     *a = re;
    240: #endif
    241:   }
    242:   return(0);
    243: }

    247: /*
    248:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
    249: */
    250: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
    251: {
    252:   PetscBool      istrue, isfalse;
    253:   size_t         len;

    257:   PetscStrlen(value, &len);
    258:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
    259:   PetscStrcasecmp(value,"TRUE",&istrue);
    260:   if (istrue) {*a = PETSC_TRUE; return(0);}
    261:   PetscStrcasecmp(value,"YES",&istrue);
    262:   if (istrue) {*a = PETSC_TRUE; return(0);}
    263:   PetscStrcasecmp(value,"1",&istrue);
    264:   if (istrue) {*a = PETSC_TRUE; return(0);}
    265:   PetscStrcasecmp(value,"on",&istrue);
    266:   if (istrue) {*a = PETSC_TRUE; return(0);}
    267:   PetscStrcasecmp(value,"FALSE",&isfalse);
    268:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    269:   PetscStrcasecmp(value,"NO",&isfalse);
    270:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    271:   PetscStrcasecmp(value,"0",&isfalse);
    272:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    273:   PetscStrcasecmp(value,"off",&isfalse);
    274:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    275:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
    276: }

    280: /*@C
    281:     PetscGetProgramName - Gets the name of the running program.

    283:     Not Collective

    285:     Input Parameter:
    286: .   len - length of the string name

    288:     Output Parameter:
    289: .   name - the name of the running program

    291:    Level: advanced

    293:     Notes:
    294:     The name of the program is copied into the user-provided character
    295:     array of length len.  On some machines the program name includes
    296:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
    297: @*/
    298: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
    299: {

    303:    PetscStrncpy(name,defaultoptions->programname,len);
    304:   return(0);
    305: }

    309: PetscErrorCode  PetscSetProgramName(const char name[])
    310: {

    314:   PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);
    315:   return(0);
    316: }

    320: /*@
    321:     PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter.

    323:    Input Parameter:
    324: .    in_str - string to check if valid

    326:    Output Parameter:
    327: .    key - PETSC_TRUE if a valid key

    329:   Level: intermediate

    331: @*/
    332: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
    333: {
    334:   PetscBool      inf,INF;

    338:   *key = PETSC_FALSE;
    339:   if (!in_str) return(0);
    340:   if (in_str[0] != '-') return(0);
    341:   if (in_str[1] == '-') in_str++;
    342:   if (!isalpha((int)(in_str[1]))) return(0);
    343:   PetscStrncmp(in_str+1,"inf",3,&inf);
    344:   PetscStrncmp(in_str+1,"INF",3,&INF);
    345:   if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
    346:   *key = PETSC_TRUE;
    347:   return(0);
    348: }

    352: /*@C
    353:      PetscOptionsInsertString - Inserts options into the database from a string

    355:      Not collective: but only processes that call this routine will set the options
    356:                      included in the string

    358:   Input Parameter:
    359: .   in_str - string that contains options separated by blanks

    362:   Level: intermediate

    364:   Contributed by Boyana Norris

    366: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
    367:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    368:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    369:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    370:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    371:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()

    373: @*/
    374: PetscErrorCode  PetscOptionsInsertString(PetscOptions options,const char in_str[])
    375: {
    376:   char           *first,*second;
    378:   PetscToken     token;
    379:   PetscBool      key,ispush,ispop;

    382:   options = options ? options : defaultoptions;
    383:   PetscTokenCreate(in_str,' ',&token);
    384:   PetscTokenFind(token,&first);
    385:   while (first) {
    386:     PetscStrcasecmp(first,"-prefix_push",&ispush);
    387:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
    388:     PetscOptionsValidKey(first,&key);
    389:     if (ispush) {
    390:       PetscTokenFind(token,&second);
    391:       PetscOptionsPrefixPush(options,second);
    392:       PetscTokenFind(token,&first);
    393:     } else if (ispop) {
    394:       PetscOptionsPrefixPop(options);
    395:       PetscTokenFind(token,&first);
    396:     } else if (key) {
    397:       PetscTokenFind(token,&second);
    398:       PetscOptionsValidKey(second,&key);
    399:       if (!key) {
    400:         PetscOptionsSetValue(options,first,second);
    401:         PetscTokenFind(token,&first);
    402:       } else {
    403:         PetscOptionsSetValue(options,first,NULL);
    404:         first = second;
    405:       }
    406:     } else {
    407:       PetscTokenFind(token,&first);
    408:     }
    409:   }
    410:   PetscTokenDestroy(&token);
    411:   return(0);
    412: }

    414: /*
    415:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
    416: */
    417: static char *Petscgetline(FILE * f)
    418: {
    419:   size_t size  = 0;
    420:   size_t len   = 0;
    421:   size_t last  = 0;
    422:   char   *buf  = NULL;

    424:   if (feof(f)) return 0;
    425:   do {
    426:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
    427:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
    428:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
    429:     end of the string, so we make sure we overwrite this */
    430:     if (!fgets(buf+len,size,f)) buf[len]=0;
    431:     PetscStrlen(buf,&len);
    432:     last = len - 1;
    433:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
    434:   if (len) return buf;
    435:   free(buf);
    436:   return 0;
    437: }

    442: /*@C
    443:      PetscOptionsInsertFile - Inserts options into the database from a file.

    445:      Collective on MPI_Comm

    447:   Input Parameter:
    448: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
    449: .   options - options database, use NULL for default global database
    450: .   file - name of file
    451: -   require - if PETSC_TRUE will generate an error if the file does not exist

    454:   Notes: Use  # for lines that are comments and which should be ignored.

    456:    Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
    457:    such as -log_summary or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later
    458:    calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().

    460:   Level: developer

    462: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
    463:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    464:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    465:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    466:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    467:           PetscOptionsFList(), PetscOptionsEList()

    469: @*/
    470: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
    471: {
    472:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
    474:   size_t         i,len,bytes;
    475:   FILE           *fd;
    476:   PetscToken     token;
    477:   int            err;
    478:   char           cmt[1]={'#'},*cmatch;
    479:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];

    482:   options = options ? options : defaultoptions;
    483:   MPI_Comm_rank(comm,&rank);
    484:   if (!rank) {
    485:     cnt        = 0;
    486:     acnt       = 0;

    488:     PetscFixFilename(file,fname);
    489:     fd   = fopen(fname,"r");
    490:     if (fd) {
    491:       PetscSegBuffer vseg,aseg;
    492:       PetscSegBufferCreate(1,4000,&vseg);
    493:       PetscSegBufferCreate(1,2000,&aseg);

    495:       /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
    496:       PetscInfo1(0,"Opened options file %s\n",file);

    498:       while ((string = Petscgetline(fd))) {
    499:         /* eliminate comments from each line */
    500:         for (i=0; i<1; i++) {
    501:           PetscStrchr(string,cmt[i],&cmatch);
    502:           if (cmatch) *cmatch = 0;
    503:         }
    504:         PetscStrlen(string,&len);
    505:         /* replace tabs, ^M, \n with " " */
    506:         for (i=0; i<len; i++) {
    507:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
    508:             string[i] = ' ';
    509:           }
    510:         }
    511:         PetscTokenCreate(string,' ',&token);
    512:         PetscTokenFind(token,&first);
    513:         if (!first) {
    514:           goto destroy;
    515:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
    516:           PetscTokenFind(token,&first);
    517:         }
    518:         PetscTokenFind(token,&second);
    519:         if (!first) {
    520:           goto destroy;
    521:         } else if (first[0] == '-') {
    522:           PetscStrlen(first,&len);
    523:           PetscSegBufferGet(vseg,len+1,&vstring);
    524:           PetscMemcpy(vstring,first,len);
    525:           vstring[len] = ' ';
    526:           if (second) {
    527:             PetscStrlen(second,&len);
    528:             PetscSegBufferGet(vseg,len+3,&vstring);
    529:             vstring[0] = '"';
    530:             PetscMemcpy(vstring+1,second,len);
    531:             vstring[len+1] = '"';
    532:             vstring[len+2] = ' ';
    533:           }
    534:         } else {
    535:           PetscBool match;

    537:           PetscStrcasecmp(first,"alias",&match);
    538:           if (match) {
    539:             PetscTokenFind(token,&third);
    540:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
    541:             PetscStrlen(second,&len);
    542:             PetscSegBufferGet(aseg,len+1,&astring);
    543:             PetscMemcpy(astring,second,len);
    544:             astring[len] = ' ';

    546:             PetscStrlen(third,&len);
    547:             PetscSegBufferGet(aseg,len+1,&astring);
    548:             PetscMemcpy(astring,third,len);
    549:             astring[len] = ' ';
    550:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
    551:         }
    552: destroy:
    553:         free(string);
    554:         PetscTokenDestroy(&token);
    555:       }
    556:       err = fclose(fd);
    557:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
    558:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
    559:       PetscMPIIntCast(bytes,&acnt);
    560:       PetscSegBufferGet(aseg,1,&astring);
    561:       astring[0] = 0;
    562:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
    563:       PetscMPIIntCast(bytes,&cnt);
    564:       PetscSegBufferGet(vseg,1,&vstring);
    565:       vstring[0] = 0;
    566:       PetscMalloc1(2+acnt+cnt,&packed);
    567:       PetscSegBufferExtractTo(aseg,packed);
    568:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
    569:       PetscSegBufferDestroy(&aseg);
    570:       PetscSegBufferDestroy(&vseg);
    571:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
    572:   }

    574:   counts[0] = acnt;
    575:   counts[1] = cnt;
    576:   MPI_Bcast(counts,2,MPI_INT,0,comm);
    577:   acnt = counts[0];
    578:   cnt = counts[1];
    579:   if (rank) {
    580:     PetscMalloc1(2+acnt+cnt,&packed);
    581:   }
    582:   if (acnt || cnt) {
    583:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
    584:     astring = packed;
    585:     vstring = packed + acnt + 1;
    586:   }

    588:   if (acnt) {
    589:     PetscToken token;
    590:     char       *first,*second;

    592:     PetscTokenCreate(astring,' ',&token);
    593:     PetscTokenFind(token,&first);
    594:     while (first) {
    595:       PetscTokenFind(token,&second);
    596:       PetscOptionsSetAlias(options,first,second);
    597:       PetscTokenFind(token,&first);
    598:     }
    599:     PetscTokenDestroy(&token);
    600:   }

    602:   if (cnt) {
    603:     PetscOptionsInsertString(options,vstring);
    604:   }
    605:   PetscFree(packed);
    606:   return(0);
    607: }

    611: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
    612: {
    614:   int            left    = argc - 1;
    615:   char           **eargs = args + 1;

    618:   options = options ? options : defaultoptions;
    619:   while (left) {
    620:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
    621:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
    622:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
    623:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
    624:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
    625:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
    626:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
    627:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
    628:     isp4 = (PetscBool) (isp4 || tisp4);
    629:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
    630:     isp4 = (PetscBool) (isp4 || tisp4);
    631:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
    632:     PetscOptionsValidKey(eargs[0],&key);

    634:     if (!key) {
    635:       eargs++; left--;
    636:     } else if (isoptions_file) {
    637:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
    638:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
    639:       PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
    640:       eargs += 2; left -= 2;
    641:     } else if (isprefixpush) {
    642:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
    643:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
    644:       PetscOptionsPrefixPush(options,eargs[1]);
    645:       eargs += 2; left -= 2;
    646:     } else if (isprefixpop) {
    647:       PetscOptionsPrefixPop(options);
    648:       eargs++; left--;

    650:       /*
    651:        These are "bad" options that MPICH, etc put on the command line
    652:        we strip them out here.
    653:        */
    654:     } else if (tisp4 || isp4rmrank) {
    655:       eargs += 1; left -= 1;
    656:     } else if (isp4 || isp4yourname) {
    657:       eargs += 2; left -= 2;
    658:     } else {
    659:       PetscBool nextiskey = PETSC_FALSE;
    660:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
    661:       if (left < 2 || nextiskey) {
    662:         PetscOptionsSetValue(options,eargs[0],NULL);
    663:         eargs++; left--;
    664:       } else {
    665:         PetscOptionsSetValue(options,eargs[0],eargs[1]);
    666:         eargs += 2; left -= 2;
    667:       }
    668:     }
    669:   }
    670:   return(0);
    671: }

    676: /*@C
    677:    PetscOptionsInsert - Inserts into the options database from the command line,
    678:                    the environmental variable and a file.

    680:    Input Parameters:
    681: +  options - options database or NULL for the default global database
    682: .  argc - count of number of command line arguments
    683: .  args - the command line arguments
    684: -  file - optional filename, defaults to ~username/.petscrc

    686:    Note:
    687:    Since PetscOptionsInsert() is automatically called by PetscInitialize(),
    688:    the user does not typically need to call this routine. PetscOptionsInsert()
    689:    can be called several times, adding additional entries into the database.

    691:    Options Database Keys:
    692: +   -options_monitor <optional filename> - print options names and values as they are set
    693: .   -options_file <filename> - read options from a file

    695:    Level: advanced

    697:    Concepts: options database^adding

    699: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
    700:           PetscInitialize()
    701: @*/
    702: PetscErrorCode  PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
    703: {
    705:   PetscMPIInt    rank;
    706:   char           pfile[PETSC_MAX_PATH_LEN];
    707:   PetscBool      flag = PETSC_FALSE;

    709:
    711:   if (!options) {
    712:     if (!defaultoptions) {
    713:       PetscOptionsCreateDefault();
    714:     }
    715:     options = defaultoptions;
    716:   }
    717:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

    719:   options->argc = (argc) ? *argc : 0;
    720:   options->args = (args) ? *args : NULL;

    722:   if (file && file[0]) {
    723:     char fullpath[PETSC_MAX_PATH_LEN];

    725:     PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
    726:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
    727:   }
    728:   /*
    729:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
    730:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
    731:   */
    732:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
    733:   PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
    734:   if (!flag) {
    735:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
    736:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
    737:     if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
    738:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
    739:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
    740:     PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
    741:   }

    743:   /* insert environmental options */
    744:   {
    745:     char   *eoptions = 0;
    746:     size_t len       = 0;
    747:     if (!rank) {
    748:       eoptions = (char*)getenv("PETSC_OPTIONS");
    749:       PetscStrlen(eoptions,&len);
    750:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
    751:     } else {
    752:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
    753:       if (len) {
    754:         PetscMalloc1(len+1,&eoptions);
    755:       }
    756:     }
    757:     if (len) {
    758:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
    759:       if (rank) eoptions[len] = 0;
    760:       PetscOptionsInsertString(options,eoptions);
    761:       if (rank) {PetscFree(eoptions);}
    762:     }
    763:   }

    765: #if defined(PETSC_HAVE_YAML)
    766:   char      yaml_file[PETSC_MAX_PATH_LEN];
    767:   PetscBool yaml_flg = PETSC_FALSE;
    768:   PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
    769:   if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
    770: #endif

    772:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
    773:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
    774:   return(0);
    775: }

    779: /*@C
    780:    PetscOptionsView - Prints the options that have been loaded. This is
    781:    useful for debugging purposes.

    783:    Logically Collective on PetscViewer

    785:    Input Parameter:
    786: .  viewer - must be an PETSCVIEWERASCII viewer

    788:    Options Database Key:
    789: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

    791:    Level: advanced

    793:    Concepts: options database^printing

    795: .seealso: PetscOptionsAllUsed()
    796: @*/
    797: PetscErrorCode  PetscOptionsView(PetscOptions options,PetscViewer viewer)
    798: {
    800:   PetscInt       i;
    801:   PetscBool      isascii;

    804:   options = options ? options : defaultoptions;
    805:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
    806:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
    807:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

    809:   if (options->N) {
    810:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
    811:   } else {
    812:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
    813:   }
    814:   for (i=0; i<options->N; i++) {
    815:     if (options->values[i]) {
    816:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
    817:     } else {
    818:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
    819:     }
    820:   }
    821:   if (options->N) {
    822:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
    823:   }
    824:   return(0);
    825: }

    829: /*
    830:    Called by error handlers to print options used in run
    831: */
    832: PetscErrorCode  PetscOptionsViewError(void)
    833: {
    834:   PetscInt       i;
    835:   PetscOptions   options = defaultoptions;

    838:   if (options->N) {
    839:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
    840:   } else {
    841:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
    842:   }
    843:   for (i=0; i<options->N; i++) {
    844:     if (options->values[i]) {
    845:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
    846:     } else {
    847:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
    848:     }
    849:   }
    850:   return(0);
    851: }

    855: /*@C
    856:    PetscOptionsGetAll - Lists all the options the program was run with in a single string.

    858:    Not Collective

    860:    Input Paramter:
    861: .  options - the options database, use NULL for the default global database

    863:    Output Parameter:
    864: .  copts - pointer where string pointer is stored

    866:    Notes: the array and each entry in the array should be freed with PetscFree()

    868:    Level: advanced

    870:    Concepts: options database^listing

    872: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
    873: @*/
    874: PetscErrorCode  PetscOptionsGetAll(PetscOptions options,char *copts[])
    875: {
    877:   PetscInt       i;
    878:   size_t         len       = 1,lent = 0;
    879:   char           *coptions = NULL;

    882:   options = options ? options : defaultoptions;

    884:   /* count the length of the required string */
    885:   for (i=0; i<options->N; i++) {
    886:     PetscStrlen(options->names[i],&lent);
    887:     len += 2 + lent;
    888:     if (options->values[i]) {
    889:       PetscStrlen(options->values[i],&lent);
    890:       len += 1 + lent;
    891:     }
    892:   }
    893:   PetscMalloc1(len,&coptions);
    894:   coptions[0] = 0;
    895:   for (i=0; i<options->N; i++) {
    896:     PetscStrcat(coptions,"-");
    897:     PetscStrcat(coptions,options->names[i]);
    898:     PetscStrcat(coptions," ");
    899:     if (options->values[i]) {
    900:       PetscStrcat(coptions,options->values[i]);
    901:       PetscStrcat(coptions," ");
    902:     }
    903:   }
    904:   *copts = coptions;
    905:   return(0);
    906: }

    910: /*@C
    911:    PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.

    913:    Not Collective, but prefix will only be applied on calling ranks

    915:    Input Parameter:
    916: +  options - options database, or NULL for the default global database
    917: -  prefix - The string to append to the existing prefix

    919:    Options Database Keys:
    920:  +   -prefix_push <some_prefix_> - push the given prefix
    921:  -   -prefix_pop - pop the last prefix

    923:    Notes:
    924:    It is common to use this in conjunction with -options_file as in

    926:  $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop

    928:    where the files no longer require all options to be prefixed with -system2_.

    930: Level: advanced

    932: .seealso: PetscOptionsPrefixPop()
    933: @*/
    934: PetscErrorCode  PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
    935: {
    937:   size_t         n;
    938:   PetscInt       start;
    939:   char           buf[2048];
    940:   PetscBool      key;

    944:   options = options ? options : defaultoptions;
    945:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
    946:   buf[0] = '-';
    947:   PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
    948:   buf[sizeof(buf) - 1] = 0;
    949:   PetscOptionsValidKey(buf,&key);
    950:   if (!key) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Given prefix \"%s\" not valid (the first character must be a letter, do not include leading '-')",prefix);

    952:   if (!options) {
    953:     PetscOptionsInsert(NULL,0,0,0);
    954:     options = defaultoptions;
    955:   }
    956:   if (options->prefixind >= MAXPREFIXES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum depth of prefix stack %d exceeded, recompile \n src/sys/objects/options.c with larger value for MAXPREFIXES",MAXPREFIXES);
    957:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
    958:   PetscStrlen(prefix,&n);
    959:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
    960:   PetscMemcpy(options->prefix+start,prefix,n+1);
    961:   options->prefixstack[options->prefixind++] = start+n;
    962:   return(0);
    963: }

    967: /*@C
    968:    PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details

    970:    Not  Collective, but prefix will only be popped on calling ranks

    972:   Input Parameters:
    973: .  options - options database, or NULL for the default global database

    975:    Level: advanced

    977: .seealso: PetscOptionsPrefixPush()
    978: @*/
    979: PetscErrorCode  PetscOptionsPrefixPop(PetscOptions options)
    980: {
    981:   PetscInt offset;

    984:   options = options ? options : defaultoptions;
    985:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
    986:   options->prefixind--;
    987:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
    988:   options->prefix[offset] = 0;
    989:   return(0);
    990: }

    994: /*@C
    995:     PetscOptionsClear - Removes all options form the database leaving it empty.

    997:   Input Parameters:
    998: .  options - options database, use NULL for the default global database

    1000:    Level: developer

    1002: .seealso: PetscOptionsInsert()
    1003: @*/
    1004: PetscErrorCode  PetscOptionsClear(PetscOptions options)
    1005: {
    1006:   PetscInt     i;

    1009:   options = options ? options : defaultoptions;
    1010:   for (i=0; i<options->N; i++) {
    1011:     if (options->names[i])  free(options->names[i]);
    1012:     if (options->values[i]) free(options->values[i]);
    1013:   }
    1014:   for (i=0; i<options->Naliases; i++) {
    1015:     free(options->aliases1[i]);
    1016:     free(options->aliases2[i]);
    1017:   }
    1018:   options->prefix[0] = 0;
    1019:   options->prefixind = 0;
    1020:   options->N         = 0;
    1021:   options->Naliases  = 0;
    1022:   return(0);
    1023: }

    1027: /*@
    1028:     PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options

    1030:   Input Parameters:
    1031: .  obj  - the PetscObject

    1033:    Level: developer

    1035:    Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
    1036:     PCBJACOBI from all printing the same help messages to the screen

    1038: .seealso: PetscOptionsInsert()
    1039: @*/
    1040: PetscErrorCode  PetscObjectSetPrintedOptions(PetscObject obj)
    1041: {
    1043:   obj->optionsprinted = PETSC_TRUE;
    1044:   return(0);
    1045: }

    1049: /*@
    1050:     PetscObjectInheritPrintedOptions - If the child object is not on the rank 0 process of the parent object and the child is sequential then the child gets it set.

    1052:   Input Parameters:
    1053: +  pobj - the parent object
    1054: -  obj  - the PetscObject

    1056:    Level: developer

    1058:    Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
    1059:     PCBJACOBI from all printing the same help messages to the screen

    1061:     This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap

    1063: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
    1064: @*/
    1065: PetscErrorCode  PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
    1066: {
    1068:   PetscMPIInt    prank,size;

    1071:   MPI_Comm_rank(pobj->comm,&prank);
    1072:   MPI_Comm_size(obj->comm,&size);
    1073:   if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
    1074:   return(0);
    1075: }

    1079: /*@
    1080:     PetscOptionsDestroy - Destroys an option database.

    1082:   Input Parameter:
    1083: .  options - the PetscOptions object

    1085:    Level: developer

    1087: .seealso: PetscOptionsInsert()
    1088: @*/
    1089: PetscErrorCode  PetscOptionsDestroy(PetscOptions *options)
    1090: {

    1094:   PetscOptionsClear(*options);
    1095:   free(*options);
    1096:   *options = NULL;
    1097:   return(0);
    1098: }

    1102: PetscErrorCode  PetscOptionsDestroyDefault(void)
    1103: {

    1106:   PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
    1107:   return 0;
    1108: }

    1113: /*@C
    1114:    PetscOptionsSetValue - Sets an option name-value pair in the options
    1115:    database, overriding whatever is already present.

    1117:    Not collective, but setting values on certain processors could cause problems
    1118:    for parallel objects looking for options.

    1120:    Input Parameters:
    1121: +  options - options database, use NULL for the default global database
    1122: .  name - name of option, this SHOULD have the - prepended
    1123: -  value - the option value (not used for all options)

    1125:    Level: intermediate

    1127:    Note:
    1128:    This function can be called BEFORE PetscInitialize()

    1130:    Only some options have values associated with them, such as
    1131:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

    1133:   Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized

    1135:   Concepts: options database^adding option

    1137: .seealso: PetscOptionsInsert()
    1138: @*/
    1139: PetscErrorCode  PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
    1140: {
    1141:   size_t         len;
    1143:   PetscInt       N,n,i;
    1144:   char           **names;
    1145:   char           fullname[2048];
    1146:   const char     *name = iname;
    1147:   int            gt,match;

    1149:   if (!options) {
    1150:     if (!defaultoptions) {
    1151:       PetscOptionsCreateDefault();
    1152:       if (ierr) return ierr;
    1153:     }
    1154:     options = defaultoptions;
    1155:   }

    1157:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
    1158:   match = strcmp(name,"-h");
    1159:   if (!match) name = "-help";

    1161:   name++; /* skip starting hyphen */
    1162:   if (options->prefixind > 0) {
    1163:     strncpy(fullname,options->prefix,sizeof(fullname));
    1164:     strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
    1165:     name = fullname;
    1166:   }

    1168:   /* check against aliases */
    1169:   N = options->Naliases;
    1170:   for (i=0; i<N; i++) {
    1171: #if defined(PETSC_HAVE_STRCASECMP)
    1172:     match = strcasecmp(options->aliases1[i],name);
    1173: #elif defined(PETSC_HAVE_STRICMP)
    1174:     match = stricmp(options->aliases1[i],name);
    1175: #else
    1176:     Error
    1177: #endif
    1178:     if (!match) {
    1179:       name = options->aliases2[i];
    1180:       break;
    1181:     }
    1182:   }

    1184:   N     = options->N;
    1185:   n     = N;
    1186:   names = options->names;

    1188:   for (i=0; i<N; i++) {
    1189: #if defined(PETSC_HAVE_STRCASECMP)
    1190:     gt = strcasecmp(names[i],name);
    1191: #elif defined(PETSC_HAVE_STRICMP)
    1192:     gt = stricmp(names[i],name);
    1193: #else
    1194:     Error
    1195: #endif
    1196:     if (!gt) {
    1197:       if (options->values[i]) free(options->values[i]);
    1198:       len = value ? strlen(value) : 0;
    1199:       if (len) {
    1200:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
    1201:         if (!options->values[i]) return PETSC_ERR_MEM;
    1202:         strcpy(options->values[i],value);
    1203:       } else options->values[i] = 0;
    1204:       return 0;
    1205:     } else if (gt > 0) {
    1206:       n = i;
    1207:       break;
    1208:     }
    1209:   }
    1210:   if (N >= MAXOPTIONS) abort();

    1212:   /* shift remaining values down 1 */
    1213:   for (i=N; i>n; i--) {
    1214:     options->names[i]  = options->names[i-1];
    1215:     options->values[i] = options->values[i-1];
    1216:     options->used[i]   = options->used[i-1];
    1217:   }
    1218:   /* insert new name and value */
    1219:   len = strlen(name);
    1220:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
    1221:   if (!options->names[n]) return PETSC_ERR_MEM;
    1222:   strcpy(options->names[n],name);
    1223:   len = value ? strlen(value) : 0;
    1224:   if (len) {
    1225:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
    1226:     if (!options->values[n]) return PETSC_ERR_MEM;
    1227:     strcpy(options->values[n],value);
    1228:   } else options->values[n] = NULL;
    1229:   options->used[n] = PETSC_FALSE;
    1230:   options->N++;
    1231:   return 0;
    1232: }

    1236: /*@C
    1237:    PetscOptionsClearValue - Clears an option name-value pair in the options
    1238:    database, overriding whatever is already present.

    1240:    Not Collective, but setting values on certain processors could cause problems
    1241:    for parallel objects looking for options.

    1243:    Input Parameter:
    1244: +  options - options database, use NULL for the default global database
    1245: .  name - name of option, this SHOULD have the - prepended

    1247:    Level: intermediate

    1249:    Concepts: options database^removing option
    1250: .seealso: PetscOptionsInsert()
    1251: @*/
    1252: PetscErrorCode  PetscOptionsClearValue(PetscOptions options,const char iname[])
    1253: {
    1255:   PetscInt       N,n,i;
    1256:   char           **names,*name=(char*)iname;
    1257:   PetscBool      gt,match;

    1260:   options = options ? options : defaultoptions;
    1261:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
    1262:   name++;

    1264:   N     = options->N; n = 0;
    1265:   names = options->names;

    1267:   for (i=0; i<N; i++) {
    1268:     PetscStrcasecmp(names[i],name,&match);
    1269:     PetscStrgrt(names[i],name,&gt);
    1270:     if (match) {
    1271:       if (options->names[i])  free(options->names[i]);
    1272:       if (options->values[i]) free(options->values[i]);
    1273:       PetscOptionsMonitor(name,"");
    1274:       break;
    1275:     } else if (gt) return(0); /* it was not listed */

    1277:     n++;
    1278:   }
    1279:   if (n == N) return(0); /* it was not listed */

    1281:   /* shift remaining values down 1 */
    1282:   for (i=n; i<N-1; i++) {
    1283:     options->names[i]  = options->names[i+1];
    1284:     options->values[i] = options->values[i+1];
    1285:     options->used[i]   = options->used[i+1];
    1286:   }
    1287:   options->N--;
    1288:   return(0);
    1289: }

    1293: /*@C
    1294:    PetscOptionsSetAlias - Makes a key and alias for another key

    1296:    Not Collective, but setting values on certain processors could cause problems
    1297:    for parallel objects looking for options.

    1299:    Input Parameters:
    1300: +  options - options database or NULL for default global database
    1301: .  inewname - the alias
    1302: -  ioldname - the name that alias will refer to

    1304:    Level: advanced

    1306: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    1307:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
    1308:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1309:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1310:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1311:           PetscOptionsFList(), PetscOptionsEList()
    1312: @*/
    1313: PetscErrorCode  PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
    1314: {
    1316:   PetscInt       n = options->Naliases;
    1317:   size_t         len;
    1318:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

    1321:   options = options ? options : defaultoptions;
    1322:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
    1323:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
    1324:   if (n >= MAXALIASES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n  src/sys/objects/options.c with larger value for MAXALIASES",MAXALIASES);

    1326:   newname++; oldname++;
    1327:   PetscStrlen(newname,&len);
    1328:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
    1329:   PetscStrcpy(options->aliases1[n],newname);
    1330:   PetscStrlen(oldname,&len);
    1331:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
    1332:   PetscStrcpy(options->aliases2[n],oldname);
    1333:   options->Naliases++;
    1334:   return(0);
    1335: }

    1339: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool  *flg)
    1340: {
    1342:   PetscInt       i,N;
    1343:   size_t         len;
    1344:   char           **names,tmp[256];
    1345:   PetscBool      match;

    1348:   options = options ? options : defaultoptions;
    1349:   N     = options->N;
    1350:   names = options->names;

    1352:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);

    1354:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
    1355:   if (pre) {
    1356:     char       *ptr   = tmp;
    1357:     const char *namep = name;
    1358:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
    1359:     if (name[1] == '-') {
    1360:       *ptr++ = '-';
    1361:       namep++;
    1362:     }
    1363:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
    1364:     tmp[sizeof(tmp)-1] = 0;
    1365:     PetscStrlen(tmp,&len);
    1366:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
    1367:   } else {
    1368:     PetscStrncpy(tmp,name+1,sizeof(tmp));
    1369:     tmp[sizeof(tmp)-1] = 0;
    1370:   }
    1371: #if defined(PETSC_USE_DEBUG)
    1372:   {
    1373:     PetscBool valid;
    1374:     char      key[sizeof(tmp)+1] = "-";

    1376:     PetscMemcpy(key+1,tmp,sizeof(tmp));
    1377:     PetscOptionsValidKey(key,&valid);
    1378:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
    1379:   }
    1380: #endif

    1382:   /* slow search */
    1383:   *flg = PETSC_FALSE;
    1384:   for (i=0; i<N; i++) {
    1385:     PetscStrcasecmp(names[i],tmp,&match);
    1386:     if (match) {
    1387:       *value           = options->values[i];
    1388:       options->used[i] = PETSC_TRUE;
    1389:       *flg             = PETSC_TRUE;
    1390:       break;
    1391:     }
    1392:   }
    1393:   if (!*flg) {
    1394:     PetscInt j,cnt = 0,locs[16],loce[16];
    1395:     size_t   n;
    1396:     PetscStrlen(tmp,&n);
    1397:     /* determine the location and number of all _%d_ in the key */
    1398:     for (i=0; i< (PetscInt)n; i++) {
    1399:       if (tmp[i] == '_') {
    1400:         for (j=i+1; j< (PetscInt)n; j++) {
    1401:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
    1402:           if (tmp[j] == '_' && j > i+1) { /* found a number */
    1403:             locs[cnt]   = i+1;
    1404:             loce[cnt++] = j+1;
    1405:           }
    1406:           break;
    1407:         }
    1408:       }
    1409:     }
    1410:     if (cnt) {
    1411:       char tmp2[256];
    1412:       for (i=0; i<cnt; i++) {
    1413:         PetscStrcpy(tmp2,"-");
    1414:         PetscStrncat(tmp2,tmp,locs[i]);
    1415:         PetscStrcat(tmp2,tmp+loce[i]);
    1416:         PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
    1417:         if (*flg) break;
    1418:       }
    1419:     }
    1420:   }
    1421:   return(0);
    1422: }

    1426: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
    1427: {
    1429:   PetscInt       i,N;
    1430:   size_t         len;
    1431:   char           **names,tmp[256];
    1432:   PetscBool      match;

    1435:   options = options ? options : defaultoptions;
    1436:   N     = options->N;
    1437:   names = options->names;

    1439:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);

    1441:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
    1442:   if (pre) {
    1443:     char       *ptr   = tmp;
    1444:     const char *namep = name;
    1445:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
    1446:     if (name[1] == '-') {
    1447:       *ptr++ = '-';
    1448:       namep++;
    1449:     }
    1450:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
    1451:     tmp[sizeof(tmp)-1] = 0;
    1452:     PetscStrlen(tmp,&len);
    1453:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
    1454:   } else {
    1455:     PetscStrncpy(tmp,name+1,sizeof(tmp));
    1456:     tmp[sizeof(tmp)-1] = 0;
    1457:   }
    1458: #if defined(PETSC_USE_DEBUG)
    1459:   {
    1460:     PetscBool valid;
    1461:     char      key[sizeof(tmp)+1] = "-";

    1463:     PetscMemcpy(key+1,tmp,sizeof(tmp));
    1464:     PetscOptionsValidKey(key,&valid);
    1465:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
    1466:   }
    1467: #endif

    1469:   /* slow search */
    1470:   *flg = PETSC_FALSE;
    1471:   PetscStrlen(tmp,&len);
    1472:   for (i = 0; i < N; ++i) {
    1473:     PetscStrncmp(names[i], tmp, len, &match);
    1474:     if (match) {
    1475:       if (value) *value = options->values[i];
    1476:       options->used[i]  = PETSC_TRUE;
    1477:       if (flg)   *flg   = PETSC_TRUE;
    1478:       break;
    1479:     }
    1480:   }
    1481:   return(0);
    1482: }

    1486: /*@C
    1487:    PetscOptionsReject - Generates an error if a certain option is given.

    1489:    Not Collective, but setting values on certain processors could cause problems
    1490:    for parallel objects looking for options.

    1492:    Input Parameters:
    1493: +  options - options database use NULL for default global database
    1494: .  name - the option one is seeking
    1495: -  mess - error message (may be NULL)

    1497:    Level: advanced

    1499:    Concepts: options database^rejecting option

    1501: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    1502:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1503:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1504:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1505:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1506:           PetscOptionsFList(), PetscOptionsEList()
    1507: @*/
    1508: PetscErrorCode  PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
    1509: {
    1511:   PetscBool      flag = PETSC_FALSE;

    1514:   options = options ? options : defaultoptions;
    1515:   PetscOptionsHasName(options,NULL,name,&flag);
    1516:   if (flag) {
    1517:     if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
    1518:     else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
    1519:   }
    1520:   return(0);
    1521: }

    1525: /*@C
    1526:    PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
    1527:                       its value is set to false.

    1529:    Not Collective

    1531:    Input Parameters:
    1532: +  options - options database use NULL for default global database
    1533: .  name - the option one is seeking
    1534: -  pre - string to prepend to the name or NULL

    1536:    Output Parameters:
    1537: .  set - PETSC_TRUE if found else PETSC_FALSE.

    1539:    Level: beginner

    1541:    Concepts: options database^has option name

    1543:    Notes: Name cannot be simply -h

    1545:           In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.

    1547: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1548:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1549:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1550:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1551:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1552:           PetscOptionsFList(), PetscOptionsEList()
    1553: @*/
    1554: PetscErrorCode  PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool  *set)
    1555: {
    1556:   char           *value;
    1558:   PetscBool      flag;

    1561:   options = options ? options : defaultoptions;
    1562:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1563:   if (set) *set = flag;
    1564:   return(0);
    1565: }

    1569: /*@C
    1570:    PetscOptionsGetInt - Gets the integer value for a particular option in the database.

    1572:    Not Collective

    1574:    Input Parameters:
    1575: +  options - options database use NULL for default global database
    1576: .  pre - the string to prepend to the name or NULL
    1577: -  name - the option one is seeking

    1579:    Output Parameter:
    1580: +  ivalue - the integer value to return
    1581: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1583:    Level: beginner

    1585:    Concepts: options database^has int

    1587: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    1588:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1589:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1590:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1591:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1592:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1593:           PetscOptionsFList(), PetscOptionsEList()
    1594: @*/
    1595: PetscErrorCode  PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool  *set)
    1596: {
    1597:   char           *value;
    1599:   PetscBool      flag;

    1604:   options = options ? options : defaultoptions;
    1605:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1606:   if (flag) {
    1607:     if (!value) {
    1608:       if (set) *set = PETSC_FALSE;
    1609:     } else {
    1610:       if (set) *set = PETSC_TRUE;
    1611:       PetscOptionsStringToInt(value,ivalue);
    1612:     }
    1613:   } else {
    1614:     if (set) *set = PETSC_FALSE;
    1615:   }
    1616:   return(0);
    1617: }

    1621: /*@C
    1622:      PetscOptionsGetEList - Puts a list of option values that a single one may be selected from

    1624:    Not Collective

    1626:    Input Parameters:
    1627: +  options - options database use NULL for default global database
    1628: .  pre - the string to prepend to the name or NULL
    1629: .  opt - option name
    1630: .  list - the possible choices (one of these must be selected, anything else is invalid)
    1631: .  ntext - number of choices

    1633:    Output Parameter:
    1634: +  value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
    1635: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1637:    Level: intermediate

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

    1641:    Concepts: options database^list

    1643: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1644:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1645:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1646:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1647:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1648:           PetscOptionsFList(), PetscOptionsEList()
    1649: @*/
    1650: PetscErrorCode  PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool  *set)
    1651: {
    1653:   size_t         alen,len = 0;
    1654:   char           *svalue;
    1655:   PetscBool      aset,flg = PETSC_FALSE;
    1656:   PetscInt       i;

    1659:   options = options ? options : defaultoptions;
    1660:   for (i=0; i<ntext; i++) {
    1661:     PetscStrlen(list[i],&alen);
    1662:     if (alen > len) len = alen;
    1663:   }
    1664:   len += 5; /* a little extra space for user mistypes */
    1665:   PetscMalloc1(len,&svalue);
    1666:   PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
    1667:   if (aset) {
    1668:     PetscEListFind(ntext,list,svalue,value,&flg);
    1669:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
    1670:     if (set) *set = PETSC_TRUE;
    1671:   } else if (set) *set = PETSC_FALSE;
    1672:   PetscFree(svalue);
    1673:   return(0);
    1674: }

    1678: /*@C
    1679:    PetscOptionsGetEnum - Gets the enum value for a particular option in the database.

    1681:    Not Collective

    1683:    Input Parameters:
    1684: +  options - options database use NULL for default global database
    1685: .  pre - option prefix or NULL
    1686: .  opt - option name
    1687: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    1688: -  defaultv - the default (current) value

    1690:    Output Parameter:
    1691: +  value - the  value to return
    1692: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1694:    Level: beginner

    1696:    Concepts: options database

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

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

    1702: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1703:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1704:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1705:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1706:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1707:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1708:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
    1709: @*/
    1710: PetscErrorCode  PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool  *set)
    1711: {
    1713:   PetscInt       ntext = 0,tval;
    1714:   PetscBool      fset;

    1717:   options = options ? options : defaultoptions;
    1718:   while (list[ntext++]) {
    1719:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    1720:   }
    1721:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    1722:   ntext -= 3;
    1723:   PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
    1724:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
    1725:   if (fset) *value = (PetscEnum)tval;
    1726:   if (set) *set = fset;
    1727:   return(0);
    1728: }

    1732: /*@C
    1733:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
    1734:             option in the database.

    1736:    Not Collective

    1738:    Input Parameters:
    1739: +  options - options database use NULL for default global database
    1740: .  pre - the string to prepend to the name or NULL
    1741: -  name - the option one is seeking

    1743:    Output Parameter:
    1744: +  ivalue - the logical value to return
    1745: -  set - PETSC_TRUE  if found, else PETSC_FALSE

    1747:    Level: beginner

    1749:    Notes:
    1750:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1751:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1753:        If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
    1754:      you NEED TO ALWAYS initialize the ivalue.

    1756:    Concepts: options database^has logical

    1758: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    1759:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
    1760:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1761:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1762:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1763:           PetscOptionsFList(), PetscOptionsEList()
    1764: @*/
    1765: PetscErrorCode  PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
    1766: {
    1767:   char           *value;
    1768:   PetscBool      flag;

    1774:   options = options ? options : defaultoptions;
    1775:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1776:   if (flag) {
    1777:     if (set) *set = PETSC_TRUE;
    1778:     if (!value) {
    1779:       if (ivalue) *ivalue = PETSC_TRUE;
    1780:     } else {
    1781:       PetscOptionsStringToBool(value, ivalue);
    1782:     }
    1783:   } else {
    1784:     if (set) *set = PETSC_FALSE;
    1785:   }
    1786:   return(0);
    1787: }

    1791: /*@C
    1792:    PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
    1793:    option in the database.  The values must be separated with commas with
    1794:    no intervening spaces.

    1796:    Not Collective

    1798:    Input Parameters:
    1799: +  options - options database use NULL for default global database
    1800: .  pre - string to prepend to each name or NULL
    1801: .  name - the option one is seeking
    1802: -  nmax - maximum number of values to retrieve

    1804:    Output Parameter:
    1805: +  dvalue - the integer values to return
    1806: .  nmax - actual number of values retreived
    1807: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1809:    Level: beginner

    1811:    Concepts: options database^array of ints

    1813:    Notes:
    1814:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1815:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1817: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1818:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1819:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1820:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1821:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1822:           PetscOptionsFList(), PetscOptionsEList()
    1823: @*/
    1824: PetscErrorCode  PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
    1825: {
    1826:   char           *value;
    1828:   PetscInt       n = 0;
    1829:   PetscBool      flag;
    1830:   PetscToken     token;

    1835:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1836:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
    1837:   if (!value) {if (set) *set = PETSC_TRUE;  *nmax = 0; return(0);}

    1839:   if (set) *set = PETSC_TRUE;

    1841:   PetscTokenCreate(value,',',&token);
    1842:   PetscTokenFind(token,&value);
    1843:   while (n < *nmax) {
    1844:     if (!value) break;
    1845:     PetscOptionsStringToBool(value,dvalue);
    1846:     PetscTokenFind(token,&value);
    1847:     dvalue++;
    1848:     n++;
    1849:   }
    1850:   PetscTokenDestroy(&token);
    1851:   *nmax = n;
    1852:   return(0);
    1853: }

    1857: /*@C
    1858:    PetscOptionsGetReal - Gets the double precision value for a particular
    1859:    option in the database.

    1861:    Not Collective

    1863:    Input Parameters:
    1864: +  options - options database use NULL for default global database
    1865: .  pre - string to prepend to each name or NULL
    1866: -  name - the option one is seeking

    1868:    Output Parameter:
    1869: +  dvalue - the double value to return
    1870: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

    1872:    Note: if the option is given but no value is provided then set is given the value PETSC_FALSE

    1874:    Level: beginner

    1876:    Concepts: options database^has double

    1878: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1879:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
    1880:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1881:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1882:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1883:           PetscOptionsFList(), PetscOptionsEList()
    1884: @*/
    1885: PetscErrorCode  PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
    1886: {
    1887:   char           *value;
    1889:   PetscBool      flag;

    1894:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1895:   if (flag) {
    1896:     if (!value) {
    1897:       if (set) *set = PETSC_FALSE;
    1898:     } else {
    1899:       if (set) *set = PETSC_TRUE;
    1900:       PetscOptionsStringToReal(value,dvalue);
    1901:     }
    1902:   } else {
    1903:     if (set) *set = PETSC_FALSE;
    1904:   }
    1905:   return(0);
    1906: }

    1910: /*@C
    1911:    PetscOptionsGetScalar - Gets the scalar value for a particular
    1912:    option in the database.

    1914:    Not Collective

    1916:    Input Parameters:
    1917: +  options - options database use NULL for default global database
    1918: .  pre - string to prepend to each name or NULL
    1919: -  name - the option one is seeking

    1921:    Output Parameter:
    1922: +  dvalue - the double value to return
    1923: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1925:    Level: beginner

    1927:    Usage:
    1928:    A complex number 2+3i must be specified with NO spaces

    1930:    Note: if the option is given but no value is provided then set is given the value PETSC_FALSE

    1932:    Concepts: options database^has scalar

    1934: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1935:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1936:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1937:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1938:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1939:           PetscOptionsFList(), PetscOptionsEList()
    1940: @*/
    1941: PetscErrorCode  PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
    1942: {
    1943:   char           *value;
    1944:   PetscBool      flag;

    1950:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    1951:   if (flag) {
    1952:     if (!value) {
    1953:       if (set) *set = PETSC_FALSE;
    1954:     } else {
    1955: #if !defined(PETSC_USE_COMPLEX)
    1956:       PetscOptionsStringToReal(value,dvalue);
    1957: #else
    1958:       PetscOptionsStringToScalar(value,dvalue);
    1959: #endif
    1960:       if (set) *set = PETSC_TRUE;
    1961:     }
    1962:   } else { /* flag */
    1963:     if (set) *set = PETSC_FALSE;
    1964:   }
    1965:   return(0);
    1966: }

    1970: /*@C
    1971:    PetscOptionsGetRealArray - Gets an array of double precision values for a
    1972:    particular option in the database.  The values must be separated with
    1973:    commas with no intervening spaces.

    1975:    Not Collective

    1977:    Input Parameters:
    1978: +  options - options database use NULL for default global database
    1979: .  pre - string to prepend to each name or NULL
    1980: .  name - the option one is seeking
    1981: -  nmax - maximum number of values to retrieve

    1983:    Output Parameters:
    1984: +  dvalue - the double values to return
    1985: .  nmax - actual number of values retreived
    1986: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1988:    Level: beginner

    1990:    Concepts: options database^array of doubles

    1992: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1993:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    1994:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1995:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1996:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1997:           PetscOptionsFList(), PetscOptionsEList()
    1998: @*/
    1999: PetscErrorCode  PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool  *set)
    2000: {
    2001:   char           *value;
    2003:   PetscInt       n = 0;
    2004:   PetscBool      flag;
    2005:   PetscToken     token;

    2010:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    2011:   if (!flag) {
    2012:     if (set) *set = PETSC_FALSE;
    2013:     *nmax = 0;
    2014:     return(0);
    2015:   }
    2016:   if (!value) {
    2017:     if (set) *set = PETSC_TRUE;
    2018:     *nmax = 0;
    2019:     return(0);
    2020:   }

    2022:   if (set) *set = PETSC_TRUE;

    2024:   PetscTokenCreate(value,',',&token);
    2025:   PetscTokenFind(token,&value);
    2026:   while (n < *nmax) {
    2027:     if (!value) break;
    2028:     PetscOptionsStringToReal(value,dvalue++);
    2029:     PetscTokenFind(token,&value);
    2030:     n++;
    2031:   }
    2032:   PetscTokenDestroy(&token);
    2033:   *nmax = n;
    2034:   return(0);
    2035: }

    2039: /*@C
    2040:    PetscOptionsGetScalarArray - Gets an array of scalars for a
    2041:    particular option in the database.  The values must be separated with
    2042:    commas with no intervening spaces.

    2044:    Not Collective

    2046:    Input Parameters:
    2047: +  options - options database use NULL for default global database
    2048: .  pre - string to prepend to each name or NULL
    2049: .  name - the option one is seeking
    2050: -  nmax - maximum number of values to retrieve

    2052:    Output Parameters:
    2053: +  dvalue - the scalar values to return
    2054: .  nmax - actual number of values retreived
    2055: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2057:    Level: beginner

    2059:    Concepts: options database^array of doubles

    2061: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    2062:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    2063:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2064:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2065:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2066:           PetscOptionsFList(), PetscOptionsEList()
    2067: @*/
    2068: PetscErrorCode  PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
    2069: {
    2070:   char           *value;
    2072:   PetscInt       n = 0;
    2073:   PetscBool      flag;
    2074:   PetscToken     token;

    2079:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    2080:   if (!flag) {
    2081:     if (set) *set = PETSC_FALSE;
    2082:     *nmax = 0;
    2083:     return(0);
    2084:   }
    2085:   if (!value) {
    2086:     if (set) *set = PETSC_TRUE;
    2087:     *nmax = 0;
    2088:     return(0);
    2089:   }

    2091:   if (set) *set = PETSC_TRUE;

    2093:   PetscTokenCreate(value,',',&token);
    2094:   PetscTokenFind(token,&value);
    2095:   while (n < *nmax) {
    2096:     if (!value) break;
    2097:     PetscOptionsStringToScalar(value,dvalue++);
    2098:     PetscTokenFind(token,&value);
    2099:     n++;
    2100:   }
    2101:   PetscTokenDestroy(&token);
    2102:   *nmax = n;
    2103:   return(0);
    2104: }

    2108: /*@C
    2109:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
    2110:    option in the database.

    2112:    Not Collective

    2114:    Input Parameters:
    2115: +  options - options database use NULL for default global database
    2116: .  pre - string to prepend to each name or NULL
    2117: .  name - the option one is seeking
    2118: -  nmax - maximum number of values to retrieve

    2120:    Output Parameter:
    2121: +  dvalue - the integer values to return
    2122: .  nmax - actual number of values retreived
    2123: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2125:    Level: beginner

    2127:    Notes:
    2128:    The array can be passed as
    2129:    a comma separated list:                                 0,1,2,3,4,5,6,7
    2130:    a range (start-end+1):                                  0-8
    2131:    a range with given increment (start-end+1:inc):         0-7:2
    2132:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

    2136:    Concepts: options database^array of ints

    2138: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    2139:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2140:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2141:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2142:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2143:           PetscOptionsFList(), PetscOptionsEList()
    2144: @*/
    2145: PetscErrorCode  PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
    2146: {
    2147:   char           *value;
    2149:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
    2150:   size_t         len;
    2151:   PetscBool      flag,foundrange;
    2152:   PetscToken     token;

    2157:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    2158:   if (!flag) {
    2159:     if (set) *set = PETSC_FALSE;
    2160:     *nmax = 0;
    2161:     return(0);
    2162:   }
    2163:   if (!value) {
    2164:     if (set) *set = PETSC_TRUE;
    2165:     *nmax = 0;
    2166:     return(0);
    2167:   }

    2169:   if (set) *set = PETSC_TRUE;

    2171:   PetscTokenCreate(value,',',&token);
    2172:   PetscTokenFind(token,&value);
    2173:   while (n < *nmax) {
    2174:     if (!value) break;

    2176:     /* look for form  d-D where d and D are integers */
    2177:     foundrange = PETSC_FALSE;
    2178:     PetscStrlen(value,&len);
    2179:     if (value[0] == '-') i=2;
    2180:     else i=1;
    2181:     for (;i<(int)len; i++) {
    2182:       if (value[i] == '-') {
    2183:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
    2184:         value[i] = 0;

    2186:         PetscOptionsStringToInt(value,&start);
    2187:         inc  = 1;
    2188:         j    = i+1;
    2189:         for (;j<(int)len; j++) {
    2190:           if (value[j] == ':') {
    2191:             value[j] = 0;

    2193:             PetscOptionsStringToInt(value+j+1,&inc);
    2194:             if (inc <= 0) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry,%s cannot have negative increment",n,value+j+1);
    2195:             break;
    2196:           }
    2197:         }
    2198:         PetscOptionsStringToInt(value+i+1,&end);
    2199:         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);
    2200:         nvalues = (end-start)/inc + (end-start)%inc;
    2201:         if (n + nvalues  > *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
    2202:         for (;start<end; start+=inc) {
    2203:           *dvalue = start; dvalue++;n++;
    2204:         }
    2205:         foundrange = PETSC_TRUE;
    2206:         break;
    2207:       }
    2208:     }
    2209:     if (!foundrange) {
    2210:       PetscOptionsStringToInt(value,dvalue);
    2211:       dvalue++;
    2212:       n++;
    2213:     }
    2214:     PetscTokenFind(token,&value);
    2215:   }
    2216:   PetscTokenDestroy(&token);
    2217:   *nmax = n;
    2218:   return(0);
    2219: }

    2223: /*@C
    2224:    PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.

    2226:    Not Collective

    2228:    Input Parameters:
    2229: +  options - options database use NULL for default global database
    2230: .  pre - option prefix or NULL
    2231: .  name - option name
    2232: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    2233: -  nmax - maximum number of values to retrieve

    2235:    Output Parameters:
    2236: +  dvalue - the  enum values to return
    2237: .  nmax - actual number of values retreived
    2238: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2240:    Level: beginner

    2242:    Concepts: options database

    2244:    Notes:
    2245:    The array must be passed as a comma separated list.

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

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

    2251: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    2252:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    2253:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
    2254:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
    2255:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2256:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
    2257: @*/
    2258: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
    2259: {
    2260:   char           *svalue;
    2261:   PetscInt       n = 0;
    2262:   PetscEnum      evalue;
    2263:   PetscBool      flag;
    2264:   PetscToken     token;

    2273:   PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
    2274:   if (!flag) {
    2275:     if (set) *set = PETSC_FALSE;
    2276:     *nmax = 0;
    2277:     return(0);
    2278:   }
    2279:   if (!svalue) {
    2280:     if (set) *set = PETSC_TRUE;
    2281:     *nmax = 0;
    2282:     return(0);
    2283:   }
    2284:   if (set) *set = PETSC_TRUE;

    2286:   PetscTokenCreate(svalue,',',&token);
    2287:   PetscTokenFind(token,&svalue);
    2288:   while (svalue && n < *nmax) {
    2289:     PetscEnumFind(list,svalue,&evalue,&flag);
    2290:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
    2291:     dvalue[n++] = evalue;
    2292:     PetscTokenFind(token,&svalue);
    2293:   }
    2294:   *nmax = n;
    2295:   PetscTokenDestroy(&token);
    2296:   return(0);
    2297: }

    2301: /*@C
    2302:    PetscOptionsGetString - Gets the string value for a particular option in
    2303:    the database.

    2305:    Not Collective

    2307:    Input Parameters:
    2308: +  options - options database use NULL for default global database
    2309: .  pre - string to prepend to name or NULL
    2310: .  name - the option one is seeking
    2311: -  len - maximum length of the string including null termination

    2313:    Output Parameters:
    2314: +  string - location to copy string
    2315: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2317:    Level: beginner

    2319:    Fortran Note:
    2320:    The Fortran interface is slightly different from the C/C++
    2321:    interface (len is not used).  Sample usage in Fortran follows
    2322: .vb
    2323:       character *20 string
    2324:       integer   flg, ierr
    2325:       call PetscOptionsGetString(PETSC_NULL_OBJECT,PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
    2326: .ve

    2328:    Notes: if the option is given but no string is provided then an empty string is returned and set is given the value of PETSC_TRUE

    2330:    Concepts: options database^string

    2332:     Note:
    2333:       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).

    2335: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    2336:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2337:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2338:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2339:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2340:           PetscOptionsFList(), PetscOptionsEList()
    2341: @*/
    2342: PetscErrorCode  PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
    2343: {
    2344:   char           *value;
    2346:   PetscBool      flag;

    2351:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    2352:   if (!flag) {
    2353:     if (set) *set = PETSC_FALSE;
    2354:   } else {
    2355:     if (set) *set = PETSC_TRUE;
    2356:     if (value) {
    2357:       PetscStrncpy(string,value,len);
    2358:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
    2359:     } else {
    2360:       PetscMemzero(string,len);
    2361:     }
    2362:   }
    2363:   return(0);
    2364: }

    2368: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
    2369: {
    2370:   char           *value;
    2372:   PetscBool      flag;

    2375:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
    2376:   if (flag) PetscFunctionReturn(value);
    2377:   else return(0);
    2378: }

    2383: /*@C
    2384:    PetscOptionsGetStringArray - Gets an array of string values for a particular
    2385:    option in the database. The values must be separated with commas with
    2386:    no intervening spaces.

    2388:    Not Collective

    2390:    Input Parameters:
    2391: +  options - options database use NULL for default global database
    2392: .  pre - string to prepend to name or NULL
    2393: .  name - the option one is seeking
    2394: -  nmax - maximum number of strings

    2396:    Output Parameter:
    2397: +  strings - location to copy strings
    2398: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2400:    Level: beginner

    2402:    Notes:
    2403:    The user should pass in an array of pointers to char, to hold all the
    2404:    strings returned by this function.

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

    2409:    Contributed by Matthew Knepley.

    2411:    Concepts: options database^array of strings

    2413: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    2414:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2415:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2416:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2417:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2418:           PetscOptionsFList(), PetscOptionsEList()
    2419: @*/
    2420: PetscErrorCode  PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
    2421: {
    2422:   char           *value;
    2424:   PetscInt       n;
    2425:   PetscBool      flag;
    2426:   PetscToken     token;

    2431:   PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
    2432:   if (!flag) {
    2433:     *nmax = 0;
    2434:     if (set) *set = PETSC_FALSE;
    2435:     return(0);
    2436:   }
    2437:   if (!value) {
    2438:     *nmax = 0;
    2439:     if (set) *set = PETSC_FALSE;
    2440:     return(0);
    2441:   }
    2442:   if (!*nmax) {
    2443:     if (set) *set = PETSC_FALSE;
    2444:     return(0);
    2445:   }
    2446:   if (set) *set = PETSC_TRUE;

    2448:   PetscTokenCreate(value,',',&token);
    2449:   PetscTokenFind(token,&value);
    2450:   n    = 0;
    2451:   while (n < *nmax) {
    2452:     if (!value) break;
    2453:     PetscStrallocpy(value,&strings[n]);
    2454:     PetscTokenFind(token,&value);
    2455:     n++;
    2456:   }
    2457:   PetscTokenDestroy(&token);
    2458:   *nmax = n;
    2459:   return(0);
    2460: }

    2464: /*@C
    2465:    PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database

    2467:    Not Collective

    2469:    Input Parameter:
    2470: +   options - options database use NULL for default global database
    2471: -   option - string name of option

    2473:    Output Parameter:
    2474: .   used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database

    2476:    Level: advanced

    2478: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
    2479: @*/
    2480: PetscErrorCode  PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
    2481: {
    2482:   PetscInt       i;

    2486:   options = options ? options : defaultoptions;
    2487:   *used = PETSC_FALSE;
    2488:   for (i=0; i<options->N; i++) {
    2489:     PetscStrcmp(options->names[i],option,used);
    2490:     if (*used) {
    2491:       *used = options->used[i];
    2492:       break;
    2493:     }
    2494:   }
    2495:   return(0);
    2496: }

    2500: /*@C
    2501:    PetscOptionsAllUsed - Returns a count of the number of options in the
    2502:    database that have never been selected.

    2504:    Not Collective

    2506:    Input Parameter:
    2507: .  options - options database use NULL for default global database

    2509:    Output Parameter:
    2510: .   N - count of options not used

    2512:    Level: advanced

    2514: .seealso: PetscOptionsView()
    2515: @*/
    2516: PetscErrorCode  PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
    2517: {
    2518:   PetscInt     i,n = 0;

    2521:   options = options ? options : defaultoptions;
    2522:   for (i=0; i<options->N; i++) {
    2523:     if (!options->used[i]) n++;
    2524:   }
    2525:   *N = n;
    2526:   return(0);
    2527: }

    2531: /*@C
    2532:     PetscOptionsLeft - Prints to screen any options that were set and never used.

    2534:   Not collective

    2536:    Input Parameter:
    2537: .  options - options database use NULL for default global database

    2539:    Options Database Key:
    2540: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

    2542:   Level: advanced

    2544: .seealso: PetscOptionsAllUsed()
    2545: @*/
    2546: PetscErrorCode  PetscOptionsLeft(PetscOptions options)
    2547: {
    2549:   PetscInt       i;

    2552:   options = options ? options : defaultoptions;
    2553:   for (i=0; i<options->N; i++) {
    2554:     if (!options->used[i]) {
    2555:       if (options->values[i]) {
    2556:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
    2557:       } else {
    2558:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
    2559:       }
    2560:     }
    2561:   }
    2562:   return(0);
    2563: }

    2567: /*@
    2568:     PetscOptionsCreate - Creates the empty options database.

    2570:   Output Parameter:
    2571: .   options - Options database object

    2573:   Level: advanced

    2575: @*/
    2576: PetscErrorCode  PetscOptionsCreate(PetscOptions *options)
    2577: {
    2578:   *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
    2579:   if (!options) return PETSC_ERR_MEM;
    2580:   (*options)->namegiven      = PETSC_FALSE;
    2581:   (*options)->N              = 0;
    2582:   (*options)->Naliases       = 0;
    2583:   (*options)->numbermonitors = 0;
    2584:   return 0;
    2585: }

    2589: /*
    2590:     PetscOptionsCreateDefault - Creates the default global options database

    2592: */
    2593: PetscErrorCode  PetscOptionsCreateDefault(void)
    2594: {

    2597:   if (!defaultoptions) {
    2598:     PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
    2599:   }
    2600:   return 0;
    2601: }

    2605: /*@C
    2606:    PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc

    2608:    Collective on PETSC_COMM_WORLD

    2610:    Input Parameter:
    2611: .  options - options database use NULL for default global database

    2613:    Options Database Keys:
    2614: +  -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
    2615:                 available for options set through a file, environment variable, or on
    2616:                 the command line. Only options set after PetscInitialize() completes will
    2617:                 be monitored.
    2618: .  -options_monitor_cancel - cancel all options database monitors

    2620:    Notes:
    2621:    To see all options, run your program with the -help option or consult Users-Manual: Introduction

    2623:    Level: intermediate

    2625: .keywords: set, options, database
    2626: @*/
    2627: PetscErrorCode  PetscOptionsSetFromOptions(PetscOptions options)
    2628: {
    2629:   PetscBool      flgc = PETSC_FALSE,flgm;
    2631:   char           monfilename[PETSC_MAX_PATH_LEN];
    2632:   PetscViewer    monviewer;

    2635:   /*
    2636:      The options argument is currently ignored since we currently maintain only a single options database

    2638:      options = options ? options : defaultoptions;
    2639:   */
    2640:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
    2641:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
    2642:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
    2643:   PetscOptionsEnd();
    2644:   if (flgm) {
    2645:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
    2646:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    2647:   }
    2648:   if (flgc) { PetscOptionsMonitorCancel(); }
    2649:   return(0);
    2650: }

    2655: /*@C
    2656:    PetscOptionsMonitorDefault - Print all options set value events.

    2658:    Logically Collective on PETSC_COMM_WORLD

    2660:    Input Parameters:
    2661: +  name  - option name string
    2662: .  value - option value string
    2663: -  dummy - an ASCII viewer

    2665:    Level: intermediate

    2667: .keywords: PetscOptions, default, monitor

    2669: .seealso: PetscOptionsMonitorSet()
    2670: @*/
    2671: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
    2672: {
    2674:   PetscViewer    viewer = (PetscViewer) dummy;

    2677:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
    2678:   return(0);
    2679: }

    2683: /*@C
    2684:    PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
    2685:    modified the PETSc options database.

    2687:    Not collective

    2689:    Input Parameters:
    2690: +  monitor - pointer to function (if this is NULL, it turns off monitoring
    2691: .  mctx    - [optional] context for private data for the
    2692:              monitor routine (use NULL if no context is desired)
    2693: -  monitordestroy - [optional] routine that frees monitor context
    2694:           (may be NULL)

    2696:    Calling Sequence of monitor:
    2697: $     monitor (const char name[], const char value[], void *mctx)

    2699: +  name - option name string
    2700: .  value - option value string
    2701: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

    2703:    Options Database Keys:
    2704: +    -options_monitor    - sets PetscOptionsMonitorDefault()
    2705: -    -options_monitor_cancel - cancels all monitors that have
    2706:                           been hardwired into a code by
    2707:                           calls to PetscOptionsMonitorSet(), but
    2708:                           does not cancel those set via
    2709:                           the options database.

    2711:    Notes:
    2712:    The default is to do nothing.  To print the name and value of options
    2713:    being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
    2714:    with a null monitoring context.

    2716:    Several different monitoring routines may be set by calling
    2717:    PetscOptionsMonitorSet() multiple times; all will be called in the
    2718:    order in which they were set.

    2720:    Level: beginner

    2722: .keywords: PetscOptions, set, monitor

    2724: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
    2725: @*/
    2726: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
    2727: {
    2728:   PetscOptions options = defaultoptions;

    2731:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
    2732:   options->monitor[options->numbermonitors]          = monitor;
    2733:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
    2734:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
    2735:   return(0);
    2736: }

    2740: /*@
    2741:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

    2743:    Not collective

    2745:    Options Database Key:
    2746: .  -options_monitor_cancel - Cancels all monitors that have
    2747:     been hardwired into a code by calls to PetscOptionsMonitorSet(),
    2748:     but does not cancel those set via the options database.

    2750:    Level: intermediate

    2752: .keywords: PetscOptions, set, monitor

    2754: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
    2755: @*/
    2756: PetscErrorCode  PetscOptionsMonitorCancel(void)
    2757: {
    2759:   PetscInt       i;
    2760:   PetscOptions   options = defaultoptions;

    2763:   for (i=0; i<options->numbermonitors; i++) {
    2764:     if (options->monitordestroy[i]) {
    2765:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
    2766:     }
    2767:   }
    2768:   options->numbermonitors = 0;
    2769:   return(0);
    2770: }

    2772: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }

    2776: /*@C
    2777:   PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed.

    2779:   Collective on PetscObject

    2781:   Input Parameters:
    2782: + obj   - the object
    2783: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
    2784: - optionname - option to activate viewing

    2786:   Level: intermediate

    2788: @*/
    2789: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
    2790: {
    2791:   PetscErrorCode    ierr;
    2792:   PetscViewer       viewer;
    2793:   PetscBool         flg;
    2794:   static PetscBool  incall = PETSC_FALSE;
    2795:   PetscViewerFormat format;
    2796:   char              *prefix;

    2799:   if (incall) return(0);
    2800:   incall = PETSC_TRUE;
    2801:   prefix = bobj ? bobj->prefix : obj->prefix;
    2802:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
    2803:   if (flg) {
    2804:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
    2805:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
    2806:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
    2807:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
    2808:   }
    2809:   incall = PETSC_FALSE;
    2810:   return(0);
    2811: }