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

Actual source code: options.c
petsc-3.6.2 2015-10-02
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_YAML)
     20: #include <yaml.h>
     21: #endif

     23: /*
     24:     This table holds all the options set by the user. For simplicity, we use a static size database
     25: */
     26: #define MAXOPTIONS 512
     27: #define MAXALIASES 25
     28: #define MAXOPTIONSMONITORS 5
     29: #define MAXPREFIXES 25

     31: typedef struct {
     32:   int            N,argc,Naliases;
     33:   char           **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
     34:   char           *aliases1[MAXALIASES],*aliases2[MAXALIASES];
     35:   PetscBool      used[MAXOPTIONS];
     36:   PetscBool      namegiven;
     37:   char           programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */

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

     45:   /* Prefixes */
     46:   PetscInt prefixind,prefixstack[MAXPREFIXES];
     47:   char     prefix[2048];
     48: } PetscOptionsTable;

     51: static PetscOptionsTable      *options = 0;

     53: /*
     54:     Options events monitor
     55: */
     56: #define PetscOptionsMonitor(name,value)                              \
     57:   { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
     58:     for (_i=0; _i<_im; _i++) { \
     59:       _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
     60:     } \
     61:   }

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

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

     78:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
     79:   if (!tdefault) {
     80:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
     81:   }
     82:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
     83:   if (!decide) {
     84:     PetscStrcasecmp(name,"DECIDE",&decide);
     85:   }
     86:   PetscStrcasecmp(name,"mouse",&mouse);

     88:   if (tdefault)    *a = PETSC_DEFAULT;
     89:   else if (decide) *a = PETSC_DECIDE;
     90:   else if (mouse)  *a = -1;
     91:   else {
     92:     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);

     94:     for (i=1; i<len; i++) {
     95:       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);
     96:     }

     98: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
     99:     *a = atoll(name);
    100: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
    101:     *a = _atoi64(name);
    102: #else
    103:     *a = (PetscInt)atoi(name);
    104: #endif
    105:   }
    106:   return(0);
    107: }

    111: /*
    112:    Converts a string to PetscReal value. Handles special cases like "default" and "decide"
    113: */
    114: PetscErrorCode  PetscOptionsStringToReal(const char name[],PetscReal *a)
    115: {
    117:   size_t         len;
    118:   PetscBool      decide,tdefault;

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

    124:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
    125:   if (!tdefault) {
    126:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
    127:   }
    128:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
    129:   if (!decide) {
    130:     PetscStrcasecmp(name,"DECIDE",&decide);
    131:   }

    133:   if (tdefault)    *a = PETSC_DEFAULT;
    134:   else if (decide) *a = PETSC_DECIDE;
    135:   else {
    136:     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);
    137:     *a = atof(name);
    138:   }
    139:   return(0);
    140: }

    144: /*
    145:    Converts a string to PetscScalar value. Handles
    146:       [-][2].0
    147:       [-][2].0i
    148:       [-][2].0+/-2.0i

    150: */
    151: PetscErrorCode  PetscOptionsStringToScalar(const char name[],PetscScalar *a)
    152: {
    154:   size_t         len;

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

    160:   if (name[0] == '+') name++;
    161:   if (name[0] == 'i') {
    162: #if defined(PETSC_USE_COMPLEX)
    163:     *a = PETSC_i;
    164: #else
    165:     SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
    166: #endif
    167:   } else {
    168:     PetscToken token;
    169:     char       *tvalue1,*tvalue2;
    170:     PetscBool  neg = PETSC_FALSE, negim = PETSC_FALSE;
    171:     PetscReal  re = 0.0,im = 0.0;

    173:     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);
    174:     if (name[0] == '-') {
    175:       neg = PETSC_TRUE;
    176:       name++;
    177:     }
    178:     if (name[0] == 'i') {
    179: #if defined(PETSC_USE_COMPLEX)
    180:       *a = -PETSC_i;
    181: #else
    182:      SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
    183: #endif
    184:       return(0);
    185:     }

    187:     PetscTokenCreate(name,'+',&token);
    188:     PetscTokenFind(token,&tvalue1);
    189:     PetscTokenFind(token,&tvalue2);
    190:     if (!tvalue2) {
    191:       negim = PETSC_TRUE;
    192:       PetscTokenDestroy(&token);
    193:       PetscTokenCreate(name,'-',&token);
    194:       PetscTokenFind(token,&tvalue1);
    195:       PetscTokenFind(token,&tvalue2);
    196:     }
    197:     if (!tvalue2) {
    198:       PetscBool isim;
    199:       PetscStrendswith(tvalue1,"i",&isim);
    200:       if (isim) {
    201:         tvalue2 = tvalue1;
    202:         tvalue1 = NULL;
    203:         negim   = neg;
    204:       }
    205:     } else {
    206:       PetscBool isim;
    207:       PetscStrendswith(tvalue2,"i",&isim);
    208:       if (!isim) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
    209:     }
    210:     if (tvalue1) {
    211:       PetscOptionsStringToReal(tvalue1,&re);
    212:       if (neg) re = -re;
    213:     }
    214:     if (tvalue2) {
    215:       PetscStrlen(tvalue2,&len);
    216:       tvalue2[len-1] = 0;
    217:       PetscOptionsStringToReal(tvalue2,&im);
    218:       if (negim) im = -im;
    219:     }
    220:     PetscTokenDestroy(&token);
    221: #if defined(PETSC_USE_COMPLEX)
    222:     *a = re + im*PETSC_i;
    223: #else
    224:     if (im != 0.0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is complex but complex not supported ",name);
    225:     *a = re;
    226: #endif
    227:   }
    228:   return(0);
    229: }

    233: /*
    234:    PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
    235: */
    236: PetscErrorCode  PetscOptionsStringToBool(const char value[], PetscBool  *a)
    237: {
    238:   PetscBool      istrue, isfalse;
    239:   size_t         len;

    243:   PetscStrlen(value, &len);
    244:   if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
    245:   PetscStrcasecmp(value,"TRUE",&istrue);
    246:   if (istrue) {*a = PETSC_TRUE; return(0);}
    247:   PetscStrcasecmp(value,"YES",&istrue);
    248:   if (istrue) {*a = PETSC_TRUE; return(0);}
    249:   PetscStrcasecmp(value,"1",&istrue);
    250:   if (istrue) {*a = PETSC_TRUE; return(0);}
    251:   PetscStrcasecmp(value,"on",&istrue);
    252:   if (istrue) {*a = PETSC_TRUE; return(0);}
    253:   PetscStrcasecmp(value,"FALSE",&isfalse);
    254:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    255:   PetscStrcasecmp(value,"NO",&isfalse);
    256:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    257:   PetscStrcasecmp(value,"0",&isfalse);
    258:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    259:   PetscStrcasecmp(value,"off",&isfalse);
    260:   if (isfalse) {*a = PETSC_FALSE; return(0);}
    261:   SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
    262: }

    266: /*@C
    267:     PetscGetProgramName - Gets the name of the running program.

    269:     Not Collective

    271:     Input Parameter:
    272: .   len - length of the string name

    274:     Output Parameter:
    275: .   name - the name of the running program

    277:    Level: advanced

    279:     Notes:
    280:     The name of the program is copied into the user-provided character
    281:     array of length len.  On some machines the program name includes
    282:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
    283: @*/
    284: PetscErrorCode  PetscGetProgramName(char name[],size_t len)
    285: {

    289:   if (!options) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
    290:   if (!options->namegiven) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Unable to determine program name");
    291:   PetscStrncpy(name,options->programname,len);
    292:   return(0);
    293: }

    297: PetscErrorCode  PetscSetProgramName(const char name[])
    298: {

    302:   options->namegiven = PETSC_TRUE;

    304:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
    305:   return(0);
    306: }

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

    313:    Input Parameter:
    314: .    in_str - string to check if valid

    316:    Output Parameter:
    317: .    key - PETSC_TRUE if a valid key

    319:   Level: intermediate

    321: @*/
    322: PetscErrorCode  PetscOptionsValidKey(const char in_str[],PetscBool  *key)
    323: {
    324:   PetscBool      inf,INF;

    328:   *key = PETSC_FALSE;
    329:   if (!in_str) return(0);
    330:   if (in_str[0] != '-') return(0);
    331:   if (in_str[1] == '-') in_str++;
    332:   if (!isalpha((int)(in_str[1]))) return(0);
    333:   PetscStrncmp(in_str+1,"inf",3,&inf);
    334:   PetscStrncmp(in_str+1,"INF",3,&INF);
    335:   if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
    336:   *key = PETSC_TRUE;
    337:   return(0);
    338: }

    342: /*@C
    343:      PetscOptionsInsertString - Inserts options into the database from a string

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

    348:   Input Parameter:
    349: .   in_str - string that contains options separated by blanks

    352:   Level: intermediate

    354:   Contributed by Boyana Norris

    356: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
    357:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    358:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    359:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    360:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    361:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()

    363: @*/
    364: PetscErrorCode  PetscOptionsInsertString(const char in_str[])
    365: {
    366:   char           *first,*second;
    368:   PetscToken     token;
    369:   PetscBool      key,ispush,ispop;

    372:   PetscTokenCreate(in_str,' ',&token);
    373:   PetscTokenFind(token,&first);
    374:   while (first) {
    375:     PetscStrcasecmp(first,"-prefix_push",&ispush);
    376:     PetscStrcasecmp(first,"-prefix_pop",&ispop);
    377:     PetscOptionsValidKey(first,&key);
    378:     if (ispush) {
    379:       PetscTokenFind(token,&second);
    380:       PetscOptionsPrefixPush(second);
    381:       PetscTokenFind(token,&first);
    382:     } else if (ispop) {
    383:       PetscOptionsPrefixPop();
    384:       PetscTokenFind(token,&first);
    385:     } else if (key) {
    386:       PetscTokenFind(token,&second);
    387:       PetscOptionsValidKey(second,&key);
    388:       if (!key) {
    389:         PetscOptionsSetValue(first,second);
    390:         PetscTokenFind(token,&first);
    391:       } else {
    392:         PetscOptionsSetValue(first,NULL);
    393:         first = second;
    394:       }
    395:     } else {
    396:       PetscTokenFind(token,&first);
    397:     }
    398:   }
    399:   PetscTokenDestroy(&token);
    400:   return(0);
    401: }

    403: /*
    404:     Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
    405: */
    406: static char *Petscgetline(FILE * f)
    407: {
    408:   size_t size  = 0;
    409:   size_t len   = 0;
    410:   size_t last  = 0;
    411:   char   *buf  = NULL;

    413:   if (feof(f)) return 0;
    414:   do {
    415:     size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
    416:     buf   = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
    417:     /* Actually do the read. Note that fgets puts a terminal '\0' on the
    418:     end of the string, so we make sure we overwrite this */
    419:     if (!fgets(buf+len,size,f)) buf[len]=0;
    420:     PetscStrlen(buf,&len);
    421:     last = len - 1;
    422:   } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
    423:   if (len) return buf;
    424:   free(buf);
    425:   return 0;
    426: }

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

    434:      Collective on MPI_Comm

    436:   Input Parameter:
    437: +   comm - the processes that will share the options (usually PETSC_COMM_WORLD)
    438: .   file - name of file
    439: -   require - if PETSC_TRUE will generate an error if the file does not exist

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

    444:    Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
    445:    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
    446:    calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().

    448:   Level: developer

    450: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
    451:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    452:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    453:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    454:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    455:           PetscOptionsFList(), PetscOptionsEList()

    457: @*/
    458: PetscErrorCode  PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
    459: {
    460:   char           *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
    462:   size_t         i,len,bytes;
    463:   FILE           *fd;
    464:   PetscToken     token;
    465:   int            err;
    466:   char           cmt[1]={'#'},*cmatch;
    467:   PetscMPIInt    rank,cnt=0,acnt=0,counts[2];

    470:   MPI_Comm_rank(comm,&rank);
    471:   if (!rank) {
    472:     cnt        = 0;
    473:     acnt       = 0;

    475:     PetscFixFilename(file,fname);
    476:     fd   = fopen(fname,"r");
    477:     if (fd) {
    478:       PetscSegBuffer vseg,aseg;
    479:       PetscSegBufferCreate(1,4000,&vseg);
    480:       PetscSegBufferCreate(1,2000,&aseg);

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

    485:       while ((string = Petscgetline(fd))) {
    486:         /* eliminate comments from each line */
    487:         for (i=0; i<1; i++) {
    488:           PetscStrchr(string,cmt[i],&cmatch);
    489:           if (cmatch) *cmatch = 0;
    490:         }
    491:         PetscStrlen(string,&len);
    492:         /* replace tabs, ^M, \n with " " */
    493:         for (i=0; i<len; i++) {
    494:           if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
    495:             string[i] = ' ';
    496:           }
    497:         }
    498:         PetscTokenCreate(string,' ',&token);
    499:         PetscTokenFind(token,&first);
    500:         if (!first) {
    501:           goto destroy;
    502:         } else if (!first[0]) { /* if first token is empty spaces, redo first token */
    503:           PetscTokenFind(token,&first);
    504:         }
    505:         PetscTokenFind(token,&second);
    506:         if (!first) {
    507:           goto destroy;
    508:         } else if (first[0] == '-') {
    509:           PetscStrlen(first,&len);
    510:           PetscSegBufferGet(vseg,len+1,&vstring);
    511:           PetscMemcpy(vstring,first,len);
    512:           vstring[len] = ' ';
    513:           if (second) {
    514:             PetscStrlen(second,&len);
    515:             PetscSegBufferGet(vseg,len+3,&vstring);
    516:             vstring[0] = '"';
    517:             PetscMemcpy(vstring+1,second,len);
    518:             vstring[len+1] = '"';
    519:             vstring[len+2] = ' ';
    520:           }
    521:         } else {
    522:           PetscBool match;

    524:           PetscStrcasecmp(first,"alias",&match);
    525:           if (match) {
    526:             PetscTokenFind(token,&third);
    527:             if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
    528:             PetscStrlen(second,&len);
    529:             PetscSegBufferGet(aseg,len+1,&astring);
    530:             PetscMemcpy(astring,second,len);
    531:             astring[len] = ' ';

    533:             PetscStrlen(third,&len);
    534:             PetscSegBufferGet(aseg,len+1,&astring);
    535:             PetscMemcpy(astring,third,len);
    536:             astring[len] = ' ';
    537:           } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
    538:         }
    539: destroy:
    540:         free(string);
    541:         PetscTokenDestroy(&token);
    542:       }
    543:       err = fclose(fd);
    544:       if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
    545:       PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
    546:       PetscMPIIntCast(bytes,&acnt);
    547:       PetscSegBufferGet(aseg,1,&astring);
    548:       astring[0] = 0;
    549:       PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
    550:       PetscMPIIntCast(bytes,&cnt);
    551:       PetscSegBufferGet(vseg,1,&vstring);
    552:       vstring[0] = 0;
    553:       PetscMalloc1(2+acnt+cnt,&packed);
    554:       PetscSegBufferExtractTo(aseg,packed);
    555:       PetscSegBufferExtractTo(vseg,packed+acnt+1);
    556:       PetscSegBufferDestroy(&aseg);
    557:       PetscSegBufferDestroy(&vseg);
    558:     } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
    559:   }

    561:   counts[0] = acnt;
    562:   counts[1] = cnt;
    563:   MPI_Bcast(counts,2,MPI_INT,0,comm);
    564:   acnt = counts[0];
    565:   cnt = counts[1];
    566:   if (rank) {
    567:     PetscMalloc1(2+acnt+cnt,&packed);
    568:   }
    569:   if (acnt || cnt) {
    570:     MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
    571:     astring = packed;
    572:     vstring = packed + acnt + 1;
    573:   }

    575:   if (acnt) {
    576:     PetscToken token;
    577:     char       *first,*second;

    579:     PetscTokenCreate(astring,' ',&token);
    580:     PetscTokenFind(token,&first);
    581:     while (first) {
    582:       PetscTokenFind(token,&second);
    583:       PetscOptionsSetAlias(first,second);
    584:       PetscTokenFind(token,&first);
    585:     }
    586:     PetscTokenDestroy(&token);
    587:   }

    589:   if (cnt) {
    590:     PetscOptionsInsertString(vstring);
    591:   }
    592:   PetscFree(packed);
    593:   return(0);
    594: }

    598: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
    599: {
    601:   int            left    = argc - 1;
    602:   char           **eargs = args + 1;

    605:   while (left) {
    606:     PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
    607:     PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
    608:     PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
    609:     PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
    610:     PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
    611:     PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
    612:     PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
    613:     PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
    614:     isp4 = (PetscBool) (isp4 || tisp4);
    615:     PetscStrcasecmp(eargs[0],"-np",&tisp4);
    616:     isp4 = (PetscBool) (isp4 || tisp4);
    617:     PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
    618:     PetscOptionsValidKey(eargs[0],&key);

    620:     if (!key) {
    621:       eargs++; left--;
    622:     } else if (isoptions_file) {
    623:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
    624:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
    625:       PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
    626:       eargs += 2; left -= 2;
    627:     } else if (isprefixpush) {
    628:       if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
    629:       if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
    630:       PetscOptionsPrefixPush(eargs[1]);
    631:       eargs += 2; left -= 2;
    632:     } else if (isprefixpop) {
    633:       PetscOptionsPrefixPop();
    634:       eargs++; left--;

    636:       /*
    637:        These are "bad" options that MPICH, etc put on the command line
    638:        we strip them out here.
    639:        */
    640:     } else if (tisp4 || isp4rmrank) {
    641:       eargs += 1; left -= 1;
    642:     } else if (isp4 || isp4yourname) {
    643:       eargs += 2; left -= 2;
    644:     } else {
    645:       PetscBool nextiskey = PETSC_FALSE;
    646:       if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
    647:       if (left < 2 || nextiskey) {
    648:         PetscOptionsSetValue(eargs[0],NULL);
    649:         eargs++; left--;
    650:       } else {
    651:         PetscOptionsSetValue(eargs[0],eargs[1]);
    652:         eargs += 2; left -= 2;
    653:       }
    654:     }
    655:   }
    656:   return(0);
    657: }

    662: /*@C
    663:    PetscOptionsInsert - Inserts into the options database from the command line,
    664:                    the environmental variable and a file.

    666:    Input Parameters:
    667: +  argc - count of number of command line arguments
    668: .  args - the command line arguments
    669: -  file - optional filename, defaults to ~username/.petscrc

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

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

    680:    Level: advanced

    682:    Concepts: options database^adding

    684: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
    685:           PetscInitialize()
    686: @*/
    687: PetscErrorCode  PetscOptionsInsert(int *argc,char ***args,const char file[])
    688: {
    690:   PetscMPIInt    rank;
    691:   char           pfile[PETSC_MAX_PATH_LEN];
    692:   PetscBool      flag = PETSC_FALSE;

    695:   if (!options) {
    696:     fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
    697:     MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
    698:   }
    699:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

    701:   options->argc = (argc) ? *argc : 0;
    702:   options->args = (args) ? *args : NULL;

    704:   if (file && file[0]) {
    705:     char fullpath[PETSC_MAX_PATH_LEN];

    707:     PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
    708:     PetscOptionsInsertFile(PETSC_COMM_WORLD,fullpath,PETSC_TRUE);
    709:   }
    710:   /*
    711:      We want to be able to give -skip_petscrc on the command line, but need to parse it first.  Since the command line
    712:      should take precedence, we insert it twice.  It would be sufficient to just scan for -skip_petscrc.
    713:   */
    714:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
    715:   PetscOptionsGetBool(NULL,"-skip_petscrc",&flag,NULL);
    716:   if (!flag) {
    717:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
    718:     /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
    719:     if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
    720:     PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
    721:     PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
    722:     PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
    723:   }

    725:   /* insert environmental options */
    726:   {
    727:     char   *eoptions = 0;
    728:     size_t len       = 0;
    729:     if (!rank) {
    730:       eoptions = (char*)getenv("PETSC_OPTIONS");
    731:       PetscStrlen(eoptions,&len);
    732:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
    733:     } else {
    734:       MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
    735:       if (len) {
    736:         PetscMalloc1(len+1,&eoptions);
    737:       }
    738:     }
    739:     if (len) {
    740:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
    741:       if (rank) eoptions[len] = 0;
    742:       PetscOptionsInsertString(eoptions);
    743:       if (rank) {PetscFree(eoptions);}
    744:     }
    745:   }

    747: #if defined(PETSC_HAVE_YAML)
    748:   char      yaml_file[PETSC_MAX_PATH_LEN];
    749:   PetscBool yaml_flg = PETSC_FALSE;
    750:   PetscOptionsGetString(NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
    751:   if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
    752: #endif

    754:   /* insert command line options again because they take precedence over arguments in petscrc/environment */
    755:   if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
    756:   return(0);
    757: }

    761: /*@C
    762:    PetscOptionsView - Prints the options that have been loaded. This is
    763:    useful for debugging purposes.

    765:    Logically Collective on PetscViewer

    767:    Input Parameter:
    768: .  viewer - must be an PETSCVIEWERASCII viewer

    770:    Options Database Key:
    771: .  -options_table - Activates PetscOptionsView() within PetscFinalize()

    773:    Level: advanced

    775:    Concepts: options database^printing

    777: .seealso: PetscOptionsAllUsed()
    778: @*/
    779: PetscErrorCode  PetscOptionsView(PetscViewer viewer)
    780: {
    782:   PetscInt       i;
    783:   PetscBool      isascii;

    786:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
    787:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
    788:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");

    790:   if (!options) {PetscOptionsInsert(0,0,0);}
    791:   if (options->N) {
    792:     PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
    793:   } else {
    794:     PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
    795:   }
    796:   for (i=0; i<options->N; i++) {
    797:     if (options->values[i]) {
    798:       PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
    799:     } else {
    800:       PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
    801:     }
    802:   }
    803:   if (options->N) {
    804:     PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
    805:   }
    806:   return(0);
    807: }

    811: /*
    812:    Called by error handlers to print options used in run
    813: */
    814: PetscErrorCode  PetscOptionsViewError(void)
    815: {
    816:   PetscInt       i;

    819:   if (options->N) {
    820:     (*PetscErrorPrintf)("PETSc Option Table entries:\n");
    821:   } else {
    822:     (*PetscErrorPrintf)("No PETSc Option Table entries\n");
    823:   }
    824:   for (i=0; i<options->N; i++) {
    825:     if (options->values[i]) {
    826:       (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
    827:     } else {
    828:       (*PetscErrorPrintf)("-%s\n",options->names[i]);
    829:     }
    830:   }
    831:   return(0);
    832: }

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

    839:    Not Collective

    841:    Output Parameter:
    842: .  copts - pointer where string pointer is stored

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

    846:    Level: advanced

    848:    Concepts: options database^listing

    850: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
    851: @*/
    852: PetscErrorCode  PetscOptionsGetAll(char *copts[])
    853: {
    855:   PetscInt       i;
    856:   size_t         len       = 1,lent = 0;
    857:   char           *coptions = NULL;

    860:   if (!options) {PetscOptionsInsert(0,0,0);}

    862:   /* count the length of the required string */
    863:   for (i=0; i<options->N; i++) {
    864:     PetscStrlen(options->names[i],&lent);
    865:     len += 2 + lent;
    866:     if (options->values[i]) {
    867:       PetscStrlen(options->values[i],&lent);
    868:       len += 1 + lent;
    869:     }
    870:   }
    871:   PetscMalloc1(len,&coptions);
    872:   coptions[0] = 0;
    873:   for (i=0; i<options->N; i++) {
    874:     PetscStrcat(coptions,"-");
    875:     PetscStrcat(coptions,options->names[i]);
    876:     PetscStrcat(coptions," ");
    877:     if (options->values[i]) {
    878:       PetscStrcat(coptions,options->values[i]);
    879:       PetscStrcat(coptions," ");
    880:     }
    881:   }
    882:   *copts = coptions;
    883:   return(0);
    884: }

    888: /*@
    889:    PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.

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

    893:    Input Parameter:
    894: .  prefix - The string to append to the existing prefix

    896:    Options Database Keys:
    897:  +   -prefix_push <some_prefix_> - push the given prefix
    898:  -   -prefix_pop - pop the last prefix

    900:    Notes:
    901:    It is common to use this in conjunction with -options_file as in

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

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

    907: Level: advanced

    909: .seealso: PetscOptionsPrefixPop()
    910: @*/
    911: PetscErrorCode  PetscOptionsPrefixPush(const char prefix[])
    912: {
    914:   size_t         n;
    915:   PetscInt       start;
    916:   char           buf[2048];
    917:   PetscBool      key;

    921:   /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
    922:   buf[0] = '-';
    923:   PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
    924:   buf[sizeof(buf) - 1] = 0;
    925:   PetscOptionsValidKey(buf,&key);
    926:   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);

    928:   if (!options) {PetscOptionsInsert(0,0,0);}
    929:   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);
    930:   start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
    931:   PetscStrlen(prefix,&n);
    932:   if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
    933:   PetscMemcpy(options->prefix+start,prefix,n+1);
    934:   options->prefixstack[options->prefixind++] = start+n;
    935:   return(0);
    936: }

    940: /*@
    941:    PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details

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

    945:    Level: advanced

    947: .seealso: PetscOptionsPrefixPush()
    948: @*/
    949: PetscErrorCode  PetscOptionsPrefixPop(void)
    950: {
    951:   PetscInt offset;

    954:   if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
    955:   options->prefixind--;
    956:   offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
    957:   options->prefix[offset] = 0;
    958:   return(0);
    959: }

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

    966:    Level: developer

    968: .seealso: PetscOptionsInsert()
    969: @*/
    970: PetscErrorCode  PetscOptionsClear(void)
    971: {
    972:   PetscInt i;

    975:   if (!options) return(0);
    976:   for (i=0; i<options->N; i++) {
    977:     if (options->names[i])  free(options->names[i]);
    978:     if (options->values[i]) free(options->values[i]);
    979:   }
    980:   for (i=0; i<options->Naliases; i++) {
    981:     free(options->aliases1[i]);
    982:     free(options->aliases2[i]);
    983:   }
    984:   options->prefix[0] = 0;
    985:   options->prefixind = 0;
    986:   options->N         = 0;
    987:   options->Naliases  = 0;
    988:   return(0);
    989: }

    993: /*@C
    994:     PetscOptionsDestroy - Destroys the option database.

    996:     Note:
    997:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user
    998:     typically does not need to call this routine.

    1000:    Level: developer

    1002: .seealso: PetscOptionsInsert()
    1003: @*/
    1004: PetscErrorCode  PetscOptionsDestroy(void)
    1005: {

    1009:   if (!options) return(0);
    1010:   PetscOptionsClear();
    1011:   free(options);
    1012:   options = 0;
    1013:   return(0);
    1014: }

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

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

    1025:    Input Parameters:
    1026: +  name - name of option, this SHOULD have the - prepended
    1027: -  value - the option value (not used for all options)

    1029:    Level: intermediate

    1031:    Note:
    1032:    Only some options have values associated with them, such as
    1033:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

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

    1037:   Concepts: options database^adding option

    1039: .seealso: PetscOptionsInsert()
    1040: @*/
    1041: PetscErrorCode  PetscOptionsSetValue(const char iname[],const char value[])
    1042: {
    1043:   size_t         len;
    1045:   PetscInt       N,n,i;
    1046:   char           **names;
    1047:   char           fullname[2048];
    1048:   const char     *name = iname;
    1049:   PetscBool      gt,match;

    1052:   if (!options) {PetscOptionsInsert(0,0,0);}

    1054:   /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
    1055:   PetscStrcasecmp(name,"-h",&match);
    1056:   if (match) name = "-help";

    1058:   name++; /* skip starting hyphen */
    1059:   if (options->prefixind > 0) {
    1060:     PetscStrncpy(fullname,options->prefix,sizeof(fullname));
    1061:     PetscStrncat(fullname,name,sizeof(fullname));
    1062:     name = fullname;
    1063:   }

    1065:   /* check against aliases */
    1066:   N = options->Naliases;
    1067:   for (i=0; i<N; i++) {
    1068:     PetscStrcasecmp(options->aliases1[i],name,&match);
    1069:     if (match) {
    1070:       name = options->aliases2[i];
    1071:       break;
    1072:     }
    1073:   }

    1075:   N     = options->N;
    1076:   n     = N;
    1077:   names = options->names;

    1079:   for (i=0; i<N; i++) {
    1080:     PetscStrcasecmp(names[i],name,&match);
    1081:     PetscStrgrt(names[i],name,&gt);
    1082:     if (match) {
    1083:       if (options->values[i]) free(options->values[i]);
    1084:       PetscStrlen(value,&len);
    1085:       if (len) {
    1086:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
    1087:         PetscStrcpy(options->values[i],value);
    1088:       } else options->values[i] = 0;
    1089:       PetscOptionsMonitor(name,value);
    1090:       return(0);
    1091:     } else if (gt) {
    1092:       n = i;
    1093:       break;
    1094:     }
    1095:   }
    1096:   if (N >= MAXOPTIONS) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);

    1098:   /* shift remaining values down 1 */
    1099:   for (i=N; i>n; i--) {
    1100:     options->names[i]  = options->names[i-1];
    1101:     options->values[i] = options->values[i-1];
    1102:     options->used[i]   = options->used[i-1];
    1103:   }
    1104:   /* insert new name and value */
    1105:   PetscStrlen(name,&len);
    1106:   options->names[n] = (char*)malloc((len+1)*sizeof(char));
    1107:   PetscStrcpy(options->names[n],name);
    1108:   PetscStrlen(value,&len);
    1109:   if (len) {
    1110:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
    1111:     PetscStrcpy(options->values[n],value);
    1112:   } else options->values[n] = 0;
    1113:   options->used[n] = PETSC_FALSE;
    1114:   options->N++;
    1115:   PetscOptionsMonitor(name,value);
    1116:   return(0);
    1117: }

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

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

    1128:    Input Parameter:
    1129: .  name - name of option, this SHOULD have the - prepended

    1131:    Level: intermediate

    1133:    Concepts: options database^removing option
    1134: .seealso: PetscOptionsInsert()
    1135: @*/
    1136: PetscErrorCode  PetscOptionsClearValue(const char iname[])
    1137: {
    1139:   PetscInt       N,n,i;
    1140:   char           **names,*name=(char*)iname;
    1141:   PetscBool      gt,match;

    1144:   if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
    1145:   if (!options) {PetscOptionsInsert(0,0,0);}

    1147:   name++;

    1149:   N     = options->N; n = 0;
    1150:   names = options->names;

    1152:   for (i=0; i<N; i++) {
    1153:     PetscStrcasecmp(names[i],name,&match);
    1154:     PetscStrgrt(names[i],name,&gt);
    1155:     if (match) {
    1156:       if (options->names[i])  free(options->names[i]);
    1157:       if (options->values[i]) free(options->values[i]);
    1158:       PetscOptionsMonitor(name,"");
    1159:       break;
    1160:     } else if (gt) return(0); /* it was not listed */

    1162:     n++;
    1163:   }
    1164:   if (n == N) return(0); /* it was not listed */

    1166:   /* shift remaining values down 1 */
    1167:   for (i=n; i<N-1; i++) {
    1168:     options->names[i]  = options->names[i+1];
    1169:     options->values[i] = options->values[i+1];
    1170:     options->used[i]   = options->used[i+1];
    1171:   }
    1172:   options->N--;
    1173:   return(0);
    1174: }

    1178: /*@C
    1179:    PetscOptionsSetAlias - Makes a key and alias for another key

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

    1184:    Input Parameters:
    1185: +  inewname - the alias
    1186: -  ioldname - the name that alias will refer to

    1188:    Level: advanced

    1190: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    1191:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
    1192:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1193:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1194:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1195:           PetscOptionsFList(), PetscOptionsEList()
    1196: @*/
    1197: PetscErrorCode  PetscOptionsSetAlias(const char inewname[],const char ioldname[])
    1198: {
    1200:   PetscInt       n = options->Naliases;
    1201:   size_t         len;
    1202:   char           *newname = (char*)inewname,*oldname = (char*)ioldname;

    1205:   if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
    1206:   if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
    1207:   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);

    1209:   newname++; oldname++;
    1210:   PetscStrlen(newname,&len);
    1211:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
    1212:   PetscStrcpy(options->aliases1[n],newname);
    1213:   PetscStrlen(oldname,&len);
    1214:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
    1215:   PetscStrcpy(options->aliases2[n],oldname);
    1216:   options->Naliases++;
    1217:   return(0);
    1218: }

    1222: PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool  *flg)
    1223: {
    1225:   PetscInt       i,N;
    1226:   size_t         len;
    1227:   char           **names,tmp[256];
    1228:   PetscBool      match;

    1231:   if (!options) {PetscOptionsInsert(0,0,0);}
    1232:   N     = options->N;
    1233:   names = options->names;

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

    1237:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
    1238:   if (pre) {
    1239:     char       *ptr   = tmp;
    1240:     const char *namep = name;
    1241:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
    1242:     if (name[1] == '-') {
    1243:       *ptr++ = '-';
    1244:       namep++;
    1245:     }
    1246:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
    1247:     tmp[sizeof(tmp)-1] = 0;
    1248:     PetscStrlen(tmp,&len);
    1249:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
    1250:   } else {
    1251:     PetscStrncpy(tmp,name+1,sizeof(tmp));
    1252:     tmp[sizeof(tmp)-1] = 0;
    1253:   }
    1254: #if defined(PETSC_USE_DEBUG)
    1255:   {
    1256:     PetscBool valid;
    1257:     char      key[sizeof(tmp)+1] = "-";

    1259:     PetscMemcpy(key+1,tmp,sizeof(tmp));
    1260:     PetscOptionsValidKey(key,&valid);
    1261:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
    1262:   }
    1263: #endif

    1265:   /* slow search */
    1266:   *flg = PETSC_FALSE;
    1267:   for (i=0; i<N; i++) {
    1268:     PetscStrcasecmp(names[i],tmp,&match);
    1269:     if (match) {
    1270:       *value           = options->values[i];
    1271:       options->used[i] = PETSC_TRUE;
    1272:       *flg             = PETSC_TRUE;
    1273:       break;
    1274:     }
    1275:   }
    1276:   if (!*flg) {
    1277:     PetscInt j,cnt = 0,locs[16],loce[16];
    1278:     size_t   n;
    1279:     PetscStrlen(tmp,&n);
    1280:     /* determine the location and number of all _%d_ in the key */
    1281:     for (i=0; i< (PetscInt)n; i++) {
    1282:       if (tmp[i] == '_') {
    1283:         for (j=i+1; j< (PetscInt)n; j++) {
    1284:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
    1285:           if (tmp[j] == '_' && j > i+1) { /* found a number */
    1286:             locs[cnt]   = i+1;
    1287:             loce[cnt++] = j+1;
    1288:           }
    1289:           break;
    1290:         }
    1291:       }
    1292:     }
    1293:     if (cnt) {
    1294:       char tmp2[256];
    1295:       for (i=0; i<cnt; i++) {
    1296:         PetscStrcpy(tmp2,"-");
    1297:         PetscStrncat(tmp2,tmp,locs[i]);
    1298:         PetscStrcat(tmp2,tmp+loce[i]);
    1299:         PetscOptionsFindPair_Private(NULL,tmp2,value,flg);
    1300:         if (*flg) break;
    1301:       }
    1302:     }
    1303:   }
    1304:   return(0);
    1305: }

    1309: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(const char pre[], const char name[], char *value[], PetscBool *flg)
    1310: {
    1312:   PetscInt       i,N;
    1313:   size_t         len;
    1314:   char           **names,tmp[256];
    1315:   PetscBool      match;

    1318:   if (!options) {PetscOptionsInsert(0,0,0);}
    1319:   N     = options->N;
    1320:   names = options->names;

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

    1324:   /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
    1325:   if (pre) {
    1326:     char       *ptr   = tmp;
    1327:     const char *namep = name;
    1328:     if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
    1329:     if (name[1] == '-') {
    1330:       *ptr++ = '-';
    1331:       namep++;
    1332:     }
    1333:     PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
    1334:     tmp[sizeof(tmp)-1] = 0;
    1335:     PetscStrlen(tmp,&len);
    1336:     PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
    1337:   } else {
    1338:     PetscStrncpy(tmp,name+1,sizeof(tmp));
    1339:     tmp[sizeof(tmp)-1] = 0;
    1340:   }
    1341: #if defined(PETSC_USE_DEBUG)
    1342:   {
    1343:     PetscBool valid;
    1344:     char      key[sizeof(tmp)+1] = "-";

    1346:     PetscMemcpy(key+1,tmp,sizeof(tmp));
    1347:     PetscOptionsValidKey(key,&valid);
    1348:     if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
    1349:   }
    1350: #endif

    1352:   /* slow search */
    1353:   *flg = PETSC_FALSE;
    1354:   PetscStrlen(tmp,&len);
    1355:   for (i = 0; i < N; ++i) {
    1356:     PetscStrncmp(names[i], tmp, len, &match);
    1357:     if (match) {
    1358:       if (value) *value = options->values[i];
    1359:       options->used[i]  = PETSC_TRUE;
    1360:       if (flg)   *flg   = PETSC_TRUE;
    1361:       break;
    1362:     }
    1363:   }
    1364:   return(0);
    1365: }

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

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

    1375:    Input Parameters:
    1376: +  name - the option one is seeking
    1377: -  mess - error message (may be NULL)

    1379:    Level: advanced

    1381:    Concepts: options database^rejecting option

    1383: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    1384:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1385:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1386:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1387:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1388:           PetscOptionsFList(), PetscOptionsEList()
    1389: @*/
    1390: PetscErrorCode  PetscOptionsReject(const char name[],const char mess[])
    1391: {
    1393:   PetscBool      flag = PETSC_FALSE;

    1396:   PetscOptionsHasName(NULL,name,&flag);
    1397:   if (flag) {
    1398:     if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
    1399:     else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
    1400:   }
    1401:   return(0);
    1402: }

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

    1410:    Not Collective

    1412:    Input Parameters:
    1413: +  name - the option one is seeking
    1414: -  pre - string to prepend to the name or NULL

    1416:    Output Parameters:
    1417: .  set - PETSC_TRUE if found else PETSC_FALSE.

    1419:    Level: beginner

    1421:    Concepts: options database^has option name

    1423:    Notes: Name cannot be simply -h

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

    1427: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1428:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1429:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1430:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1431:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1432:           PetscOptionsFList(), PetscOptionsEList()
    1433: @*/
    1434: PetscErrorCode  PetscOptionsHasName(const char pre[],const char name[],PetscBool  *set)
    1435: {
    1436:   char           *value;
    1438:   PetscBool      flag;

    1441:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1442:   if (set) *set = flag;
    1443:   return(0);
    1444: }

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

    1451:    Not Collective

    1453:    Input Parameters:
    1454: +  pre - the string to prepend to the name or NULL
    1455: -  name - the option one is seeking

    1457:    Output Parameter:
    1458: +  ivalue - the integer value to return
    1459: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1461:    Level: beginner

    1463:    Concepts: options database^has int

    1465: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    1466:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1467:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1468:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1469:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1470:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1471:           PetscOptionsFList(), PetscOptionsEList()
    1472: @*/
    1473: PetscErrorCode  PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool  *set)
    1474: {
    1475:   char           *value;
    1477:   PetscBool      flag;

    1482:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1483:   if (flag) {
    1484:     if (!value) {
    1485:       if (set) *set = PETSC_FALSE;
    1486:     } else {
    1487:       if (set) *set = PETSC_TRUE;
    1488:       PetscOptionsStringToInt(value,ivalue);
    1489:     }
    1490:   } else {
    1491:     if (set) *set = PETSC_FALSE;
    1492:   }
    1493:   return(0);
    1494: }

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

    1501:    Not Collective

    1503:    Input Parameters:
    1504: +  pre - the string to prepend to the name or NULL
    1505: .  opt - option name
    1506: .  list - the possible choices (one of these must be selected, anything else is invalid)
    1507: .  ntext - number of choices

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

    1513:    Level: intermediate

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

    1517:    Concepts: options database^list

    1519: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1520:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1521:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1522:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1523:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1524:           PetscOptionsFList(), PetscOptionsEList()
    1525: @*/
    1526: PetscErrorCode  PetscOptionsGetEList(const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool  *set)
    1527: {
    1529:   size_t         alen,len = 0;
    1530:   char           *svalue;
    1531:   PetscBool      aset,flg = PETSC_FALSE;
    1532:   PetscInt       i;

    1535:   for (i=0; i<ntext; i++) {
    1536:     PetscStrlen(list[i],&alen);
    1537:     if (alen > len) len = alen;
    1538:   }
    1539:   len += 5; /* a little extra space for user mistypes */
    1540:   PetscMalloc1(len,&svalue);
    1541:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
    1542:   if (aset) {
    1543:     PetscEListFind(ntext,list,svalue,value,&flg);
    1544:     if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
    1545:     if (set) *set = PETSC_TRUE;
    1546:   } else if (set) *set = PETSC_FALSE;
    1547:   PetscFree(svalue);
    1548:   return(0);
    1549: }

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

    1556:    Not Collective

    1558:    Input Parameters:
    1559: +  pre - option prefix or NULL
    1560: .  opt - option name
    1561: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    1562: -  defaultv - the default (current) value

    1564:    Output Parameter:
    1565: +  value - the  value to return
    1566: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1568:    Level: beginner

    1570:    Concepts: options database

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

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

    1576: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1577:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    1578:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
    1579:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1580:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1581:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1582:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
    1583: @*/
    1584: PetscErrorCode  PetscOptionsGetEnum(const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool  *set)
    1585: {
    1587:   PetscInt       ntext = 0,tval;
    1588:   PetscBool      fset;

    1591:   while (list[ntext++]) {
    1592:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    1593:   }
    1594:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    1595:   ntext -= 3;
    1596:   PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
    1597:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
    1598:   if (fset) *value = (PetscEnum)tval;
    1599:   if (set) *set = fset;
    1600:   return(0);
    1601: }

    1605: /*@C
    1606:    PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
    1607:             option in the database.

    1609:    Not Collective

    1611:    Input Parameters:
    1612: +  pre - the string to prepend to the name or NULL
    1613: -  name - the option one is seeking

    1615:    Output Parameter:
    1616: +  ivalue - the logical value to return
    1617: -  set - PETSC_TRUE  if found, else PETSC_FALSE

    1619:    Level: beginner

    1621:    Notes:
    1622:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1623:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

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

    1628:    Concepts: options database^has logical

    1630: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    1631:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
    1632:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1633:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1634:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1635:           PetscOptionsFList(), PetscOptionsEList()
    1636: @*/
    1637: PetscErrorCode  PetscOptionsGetBool(const char pre[],const char name[],PetscBool  *ivalue,PetscBool  *set)
    1638: {
    1639:   char           *value;
    1640:   PetscBool      flag;

    1646:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1647:   if (flag) {
    1648:     if (set) *set = PETSC_TRUE;
    1649:     if (!value) *ivalue = PETSC_TRUE;
    1650:     else {
    1651:       PetscOptionsStringToBool(value, ivalue);
    1652:     }
    1653:   } else {
    1654:     if (set) *set = PETSC_FALSE;
    1655:   }
    1656:   return(0);
    1657: }

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

    1666:    Not Collective

    1668:    Input Parameters:
    1669: +  pre - string to prepend to each name or NULL
    1670: .  name - the option one is seeking
    1671: -  nmax - maximum number of values to retrieve

    1673:    Output Parameter:
    1674: +  dvalue - the integer values to return
    1675: .  nmax - actual number of values retreived
    1676: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1678:    Level: beginner

    1680:    Concepts: options database^array of ints

    1682:    Notes:
    1683:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1684:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1686: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1687:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1688:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1689:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1690:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1691:           PetscOptionsFList(), PetscOptionsEList()
    1692: @*/
    1693: PetscErrorCode  PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool  *set)
    1694: {
    1695:   char           *value;
    1697:   PetscInt       n = 0;
    1698:   PetscBool      flag;
    1699:   PetscToken     token;

    1704:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1705:   if (!flag)  {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
    1706:   if (!value) {if (set) *set = PETSC_TRUE;  *nmax = 0; return(0);}

    1708:   if (set) *set = PETSC_TRUE;

    1710:   PetscTokenCreate(value,',',&token);
    1711:   PetscTokenFind(token,&value);
    1712:   while (n < *nmax) {
    1713:     if (!value) break;
    1714:     PetscOptionsStringToBool(value,dvalue);
    1715:     PetscTokenFind(token,&value);
    1716:     dvalue++;
    1717:     n++;
    1718:   }
    1719:   PetscTokenDestroy(&token);
    1720:   *nmax = n;
    1721:   return(0);
    1722: }

    1726: /*@C
    1727:    PetscOptionsGetReal - Gets the double precision value for a particular
    1728:    option in the database.

    1730:    Not Collective

    1732:    Input Parameters:
    1733: +  pre - string to prepend to each name or NULL
    1734: -  name - the option one is seeking

    1736:    Output Parameter:
    1737: +  dvalue - the double value to return
    1738: -  set - PETSC_TRUE if found, PETSC_FALSE if not found

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

    1742:    Level: beginner

    1744:    Concepts: options database^has double

    1746: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1747:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
    1748:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1749:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1750:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1751:           PetscOptionsFList(), PetscOptionsEList()
    1752: @*/
    1753: PetscErrorCode  PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool  *set)
    1754: {
    1755:   char           *value;
    1757:   PetscBool      flag;

    1762:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1763:   if (flag) {
    1764:     if (!value) {
    1765:       if (set) *set = PETSC_FALSE;
    1766:     } else {
    1767:       if (set) *set = PETSC_TRUE;
    1768:       PetscOptionsStringToReal(value,dvalue);
    1769:     }
    1770:   } else {
    1771:     if (set) *set = PETSC_FALSE;
    1772:   }
    1773:   return(0);
    1774: }

    1778: /*@C
    1779:    PetscOptionsGetScalar - Gets the scalar value for a particular
    1780:    option in the database.

    1782:    Not Collective

    1784:    Input Parameters:
    1785: +  pre - string to prepend to each name or NULL
    1786: -  name - the option one is seeking

    1788:    Output Parameter:
    1789: +  dvalue - the double value to return
    1790: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1792:    Level: beginner

    1794:    Usage:
    1795:    A complex number 2+3i must be specified with NO spaces

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

    1799:    Concepts: options database^has scalar

    1801: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1802:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    1803:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1804:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1805:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1806:           PetscOptionsFList(), PetscOptionsEList()
    1807: @*/
    1808: PetscErrorCode  PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool  *set)
    1809: {
    1810:   char           *value;
    1811:   PetscBool      flag;

    1817:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1818:   if (flag) {
    1819:     if (!value) {
    1820:       if (set) *set = PETSC_FALSE;
    1821:     } else {
    1822: #if !defined(PETSC_USE_COMPLEX)
    1823:       PetscOptionsStringToReal(value,dvalue);
    1824: #else
    1825:       PetscOptionsStringToScalar(value,dvalue);
    1826: #endif
    1827:       if (set) *set = PETSC_TRUE;
    1828:     }
    1829:   } else { /* flag */
    1830:     if (set) *set = PETSC_FALSE;
    1831:   }
    1832:   return(0);
    1833: }

    1837: /*@C
    1838:    PetscOptionsGetRealArray - Gets an array of double precision values for a
    1839:    particular option in the database.  The values must be separated with
    1840:    commas with no intervening spaces.

    1842:    Not Collective

    1844:    Input Parameters:
    1845: +  pre - string to prepend to each name or NULL
    1846: .  name - the option one is seeking
    1847: -  nmax - maximum number of values to retrieve

    1849:    Output Parameters:
    1850: +  dvalue - the double values to return
    1851: .  nmax - actual number of values retreived
    1852: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1854:    Level: beginner

    1856:    Concepts: options database^array of doubles

    1858: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1859:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    1860:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1861:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1862:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1863:           PetscOptionsFList(), PetscOptionsEList()
    1864: @*/
    1865: PetscErrorCode  PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool  *set)
    1866: {
    1867:   char           *value;
    1869:   PetscInt       n = 0;
    1870:   PetscBool      flag;
    1871:   PetscToken     token;

    1876:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1877:   if (!flag) {
    1878:     if (set) *set = PETSC_FALSE;
    1879:     *nmax = 0;
    1880:     return(0);
    1881:   }
    1882:   if (!value) {
    1883:     if (set) *set = PETSC_TRUE;
    1884:     *nmax = 0;
    1885:     return(0);
    1886:   }

    1888:   if (set) *set = PETSC_TRUE;

    1890:   PetscTokenCreate(value,',',&token);
    1891:   PetscTokenFind(token,&value);
    1892:   while (n < *nmax) {
    1893:     if (!value) break;
    1894:     PetscOptionsStringToReal(value,dvalue++);
    1895:     PetscTokenFind(token,&value);
    1896:     n++;
    1897:   }
    1898:   PetscTokenDestroy(&token);
    1899:   *nmax = n;
    1900:   return(0);
    1901: }

    1905: /*@C
    1906:    PetscOptionsGetScalarArray - Gets an array of scalars for a
    1907:    particular option in the database.  The values must be separated with
    1908:    commas with no intervening spaces.

    1910:    Not Collective

    1912:    Input Parameters:
    1913: +  pre - string to prepend to each name or NULL
    1914: .  name - the option one is seeking
    1915: -  nmax - maximum number of values to retrieve

    1917:    Output Parameters:
    1918: +  dvalue - the scalar values to return
    1919: .  nmax - actual number of values retreived
    1920: -  set - PETSC_TRUE if found, else PETSC_FALSE

    1922:    Level: beginner

    1924:    Concepts: options database^array of doubles

    1926: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1927:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
    1928:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1929:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1930:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    1931:           PetscOptionsFList(), PetscOptionsEList()
    1932: @*/
    1933: PetscErrorCode  PetscOptionsGetScalarArray(const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool  *set)
    1934: {
    1935:   char           *value;
    1937:   PetscInt       n = 0;
    1938:   PetscBool      flag;
    1939:   PetscToken     token;

    1944:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1945:   if (!flag) {
    1946:     if (set) *set = PETSC_FALSE;
    1947:     *nmax = 0;
    1948:     return(0);
    1949:   }
    1950:   if (!value) {
    1951:     if (set) *set = PETSC_TRUE;
    1952:     *nmax = 0;
    1953:     return(0);
    1954:   }

    1956:   if (set) *set = PETSC_TRUE;

    1958:   PetscTokenCreate(value,',',&token);
    1959:   PetscTokenFind(token,&value);
    1960:   while (n < *nmax) {
    1961:     if (!value) break;
    1962:     PetscOptionsStringToScalar(value,dvalue++);
    1963:     PetscTokenFind(token,&value);
    1964:     n++;
    1965:   }
    1966:   PetscTokenDestroy(&token);
    1967:   *nmax = n;
    1968:   return(0);
    1969: }

    1973: /*@C
    1974:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
    1975:    option in the database.

    1977:    Not Collective

    1979:    Input Parameters:
    1980: +  pre - string to prepend to each name or NULL
    1981: .  name - the option one is seeking
    1982: -  nmax - maximum number of values to retrieve

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

    1989:    Level: beginner

    1991:    Notes:
    1992:    The array can be passed as
    1993:    a comma separated list:                                 0,1,2,3,4,5,6,7
    1994:    a range (start-end+1):                                  0-8
    1995:    a range with given increment (start-end+1:inc):         0-7:2
    1996:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

    2000:    Concepts: options database^array of ints

    2002: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    2003:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2004:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2005:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2006:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2007:           PetscOptionsFList(), PetscOptionsEList()
    2008: @*/
    2009: PetscErrorCode  PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool  *set)
    2010: {
    2011:   char           *value;
    2013:   PetscInt       n = 0,i,j,start,end,inc,nvalues;
    2014:   size_t         len;
    2015:   PetscBool      flag,foundrange;
    2016:   PetscToken     token;

    2021:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    2022:   if (!flag) {
    2023:     if (set) *set = PETSC_FALSE;
    2024:     *nmax = 0;
    2025:     return(0);
    2026:   }
    2027:   if (!value) {
    2028:     if (set) *set = PETSC_TRUE;
    2029:     *nmax = 0;
    2030:     return(0);
    2031:   }

    2033:   if (set) *set = PETSC_TRUE;

    2035:   PetscTokenCreate(value,',',&token);
    2036:   PetscTokenFind(token,&value);
    2037:   while (n < *nmax) {
    2038:     if (!value) break;

    2040:     /* look for form  d-D where d and D are integers */
    2041:     foundrange = PETSC_FALSE;
    2042:     PetscStrlen(value,&len);
    2043:     if (value[0] == '-') i=2;
    2044:     else i=1;
    2045:     for (;i<(int)len; i++) {
    2046:       if (value[i] == '-') {
    2047:         if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
    2048:         value[i] = 0;

    2050:         PetscOptionsStringToInt(value,&start);
    2051:         inc  = 1;
    2052:         j    = i+1;
    2053:         for (;j<(int)len; j++) {
    2054:           if (value[j] == ':') {
    2055:             value[j] = 0;

    2057:             PetscOptionsStringToInt(value+j+1,&inc);
    2058:             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);
    2059:             break;
    2060:           }
    2061:         }
    2062:         PetscOptionsStringToInt(value+i+1,&end);
    2063:         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);
    2064:         nvalues = (end-start)/inc + (end-start)%inc;
    2065:         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);
    2066:         for (;start<end; start+=inc) {
    2067:           *dvalue = start; dvalue++;n++;
    2068:         }
    2069:         foundrange = PETSC_TRUE;
    2070:         break;
    2071:       }
    2072:     }
    2073:     if (!foundrange) {
    2074:       PetscOptionsStringToInt(value,dvalue);
    2075:       dvalue++;
    2076:       n++;
    2077:     }
    2078:     PetscTokenFind(token,&value);
    2079:   }
    2080:   PetscTokenDestroy(&token);
    2081:   *nmax = n;
    2082:   return(0);
    2083: }

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

    2090:    Not Collective

    2092:    Input Parameters:
    2093: +  pre - option prefix or NULL
    2094: .  name - option name
    2095: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    2096: -  nmax - maximum number of values to retrieve

    2098:    Output Parameters:
    2099: +  dvalue - the  enum values to return
    2100: .  nmax - actual number of values retreived
    2101: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2103:    Level: beginner

    2105:    Concepts: options database

    2107:    Notes:
    2108:    The array must be passed as a comma separated list.

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

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

    2114: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    2115:           PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
    2116:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
    2117:           PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
    2118:           PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2119:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
    2120: @*/
    2121: PetscErrorCode PetscOptionsGetEnumArray(const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
    2122: {
    2123:   char           *svalue;
    2124:   PetscInt       n = 0;
    2125:   PetscEnum      evalue;
    2126:   PetscBool      flag;
    2127:   PetscToken     token;

    2136:   PetscOptionsFindPair_Private(pre,name,&svalue,&flag);
    2137:   if (!flag) {
    2138:     if (set) *set = PETSC_FALSE;
    2139:     *nmax = 0;
    2140:     return(0);
    2141:   }
    2142:   if (!svalue) {
    2143:     if (set) *set = PETSC_TRUE;
    2144:     *nmax = 0;
    2145:     return(0);
    2146:   }
    2147:   if (set) *set = PETSC_TRUE;

    2149:   PetscTokenCreate(svalue,',',&token);
    2150:   PetscTokenFind(token,&svalue);
    2151:   while (svalue && n < *nmax) {
    2152:     PetscEnumFind(list,svalue,&evalue,&flag);
    2153:     if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
    2154:     dvalue[n++] = evalue;
    2155:     PetscTokenFind(token,&svalue);
    2156:   }
    2157:   *nmax = n;
    2158:   PetscTokenDestroy(&token);
    2159:   return(0);
    2160: }

    2164: /*@C
    2165:    PetscOptionsGetString - Gets the string value for a particular option in
    2166:    the database.

    2168:    Not Collective

    2170:    Input Parameters:
    2171: +  pre - string to prepend to name or NULL
    2172: .  name - the option one is seeking
    2173: -  len - maximum length of the string including null termination

    2175:    Output Parameters:
    2176: +  string - location to copy string
    2177: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2179:    Level: beginner

    2181:    Fortran Note:
    2182:    The Fortran interface is slightly different from the C/C++
    2183:    interface (len is not used).  Sample usage in Fortran follows
    2184: .vb
    2185:       character *20 string
    2186:       integer   flg, ierr
    2187:       call PetscOptionsGetString(NULL_CHARACTER,'-s',string,flg,ierr)
    2188: .ve

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

    2192:    Concepts: options database^string

    2194:     Note:
    2195:       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).

    2197: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    2198:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2199:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2200:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2201:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2202:           PetscOptionsFList(), PetscOptionsEList()
    2203: @*/
    2204: PetscErrorCode  PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool  *set)
    2205: {
    2206:   char           *value;
    2208:   PetscBool      flag;

    2213:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    2214:   if (!flag) {
    2215:     if (set) *set = PETSC_FALSE;
    2216:   } else {
    2217:     if (set) *set = PETSC_TRUE;
    2218:     if (value) {
    2219:       PetscStrncpy(string,value,len);
    2220:       string[len-1] = 0;        /* Ensure that the string is NULL terminated */
    2221:     } else {
    2222:       PetscMemzero(string,len);
    2223:     }
    2224:   }
    2225:   return(0);
    2226: }

    2230: char *PetscOptionsGetStringMatlab(const char pre[],const char name[])
    2231: {
    2232:   char           *value;
    2234:   PetscBool      flag;

    2237:   PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
    2238:   if (flag) PetscFunctionReturn(value);
    2239:   else return(0);
    2240: }

    2245: /*@C
    2246:    PetscOptionsGetStringArray - Gets an array of string values for a particular
    2247:    option in the database. The values must be separated with commas with
    2248:    no intervening spaces.

    2250:    Not Collective

    2252:    Input Parameters:
    2253: +  pre - string to prepend to name or NULL
    2254: .  name - the option one is seeking
    2255: -  nmax - maximum number of strings

    2257:    Output Parameter:
    2258: +  strings - location to copy strings
    2259: -  set - PETSC_TRUE if found, else PETSC_FALSE

    2261:    Level: beginner

    2263:    Notes:
    2264:    The user should pass in an array of pointers to char, to hold all the
    2265:    strings returned by this function.

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

    2270:    Contributed by Matthew Knepley.

    2272:    Concepts: options database^array of strings

    2274: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    2275:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
    2276:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    2277:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    2278:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
    2279:           PetscOptionsFList(), PetscOptionsEList()
    2280: @*/
    2281: PetscErrorCode  PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool  *set)
    2282: {
    2283:   char           *value;
    2285:   PetscInt       n;
    2286:   PetscBool      flag;
    2287:   PetscToken     token;

    2292:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    2293:   if (!flag) {
    2294:     *nmax = 0;
    2295:     if (set) *set = PETSC_FALSE;
    2296:     return(0);
    2297:   }
    2298:   if (!value) {
    2299:     *nmax = 0;
    2300:     if (set) *set = PETSC_FALSE;
    2301:     return(0);
    2302:   }
    2303:   if (!*nmax) {
    2304:     if (set) *set = PETSC_FALSE;
    2305:     return(0);
    2306:   }
    2307:   if (set) *set = PETSC_TRUE;

    2309:   PetscTokenCreate(value,',',&token);
    2310:   PetscTokenFind(token,&value);
    2311:   n    = 0;
    2312:   while (n < *nmax) {
    2313:     if (!value) break;
    2314:     PetscStrallocpy(value,&strings[n]);
    2315:     PetscTokenFind(token,&value);
    2316:     n++;
    2317:   }
    2318:   PetscTokenDestroy(&token);
    2319:   *nmax = n;
    2320:   return(0);
    2321: }

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

    2328:    Not Collective

    2330:    Input Parameter:
    2331: .    option - string name of option

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

    2336:    Level: advanced

    2338: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
    2339: @*/
    2340: PetscErrorCode  PetscOptionsUsed(const char *option,PetscBool *used)
    2341: {
    2342:   PetscInt       i;

    2346:   *used = PETSC_FALSE;
    2347:   for (i=0; i<options->N; i++) {
    2348:     PetscStrcmp(options->names[i],option,used);
    2349:     if (*used) {
    2350:       *used = options->used[i];
    2351:       break;
    2352:     }
    2353:   }
    2354:   return(0);
    2355: }

    2359: /*@C
    2360:    PetscOptionsAllUsed - Returns a count of the number of options in the
    2361:    database that have never been selected.

    2363:    Not Collective

    2365:    Output Parameter:
    2366: .   N - count of options not used

    2368:    Level: advanced

    2370: .seealso: PetscOptionsView()
    2371: @*/
    2372: PetscErrorCode  PetscOptionsAllUsed(PetscInt *N)
    2373: {
    2374:   PetscInt i,n = 0;

    2377:   for (i=0; i<options->N; i++) {
    2378:     if (!options->used[i]) n++;
    2379:   }
    2380:   *N = n;
    2381:   return(0);
    2382: }

    2386: /*@
    2387:     PetscOptionsLeft - Prints to screen any options that were set and never used.

    2389:   Not collective

    2391:    Options Database Key:
    2392: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

    2394:   Level: advanced

    2396: .seealso: PetscOptionsAllUsed()
    2397: @*/
    2398: PetscErrorCode  PetscOptionsLeft(void)
    2399: {
    2401:   PetscInt       i;

    2404:   for (i=0; i<options->N; i++) {
    2405:     if (!options->used[i]) {
    2406:       if (options->values[i]) {
    2407:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
    2408:       } else {
    2409:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
    2410:       }
    2411:     }
    2412:   }
    2413:   return(0);
    2414: }

    2419: /*
    2420:     PetscOptionsCreate - Creates the empty options database.

    2422: */
    2423: PetscErrorCode  PetscOptionsCreate(void)
    2424: {

    2428:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
    2429:   PetscMemzero(options,sizeof(PetscOptionsTable));

    2431:   options->namegiven      = PETSC_FALSE;
    2432:   options->N              = 0;
    2433:   options->Naliases       = 0;
    2434:   options->numbermonitors = 0;

    2436:   return(0);
    2437: }

    2441: /*@
    2442:    PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc

    2444:    Collective on PETSC_COMM_WORLD

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

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

    2456:    Level: intermediate

    2458: .keywords: set, options, database
    2459: @*/
    2460: PetscErrorCode  PetscOptionsSetFromOptions(void)
    2461: {
    2462:   PetscBool      flgc = PETSC_FALSE,flgm;
    2464:   char           monfilename[PETSC_MAX_PATH_LEN];
    2465:   PetscViewer    monviewer;

    2468:   PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
    2469:   PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
    2470:   PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
    2471:   PetscOptionsEnd();
    2472:   if (flgm) {
    2473:     PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
    2474:     PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    2475:   }
    2476:   if (flgc) { PetscOptionsMonitorCancel(); }
    2477:   return(0);
    2478: }

    2483: /*@C
    2484:    PetscOptionsMonitorDefault - Print all options set value events.

    2486:    Logically Collective on PETSC_COMM_WORLD

    2488:    Input Parameters:
    2489: +  name  - option name string
    2490: .  value - option value string
    2491: -  dummy - unused monitor context

    2493:    Level: intermediate

    2495: .keywords: PetscOptions, default, monitor

    2497: .seealso: PetscOptionsMonitorSet()
    2498: @*/
    2499: PetscErrorCode  PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
    2500: {
    2502:   PetscViewer    viewer = (PetscViewer) dummy;

    2505:   if (!viewer) {
    2506:     PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
    2507:   }
    2508:   PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
    2509:   return(0);
    2510: }

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

    2518:    Not collective

    2520:    Input Parameters:
    2521: +  monitor - pointer to function (if this is NULL, it turns off monitoring
    2522: .  mctx    - [optional] context for private data for the
    2523:              monitor routine (use NULL if no context is desired)
    2524: -  monitordestroy - [optional] routine that frees monitor context
    2525:           (may be NULL)

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

    2530: +  name - option name string
    2531: .  value - option value string
    2532: -  mctx  - optional monitoring context, as set by PetscOptionsMonitorSet()

    2534:    Options Database Keys:
    2535: +    -options_monitor    - sets PetscOptionsMonitorDefault()
    2536: -    -options_monitor_cancel - cancels all monitors that have
    2537:                           been hardwired into a code by
    2538:                           calls to PetscOptionsMonitorSet(), but
    2539:                           does not cancel those set via
    2540:                           the options database.

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

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

    2551:    Level: beginner

    2553: .keywords: PetscOptions, set, monitor

    2555: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
    2556: @*/
    2557: PetscErrorCode  PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
    2558: {
    2560:   if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
    2561:   options->monitor[options->numbermonitors]          = monitor;
    2562:   options->monitordestroy[options->numbermonitors]   = monitordestroy;
    2563:   options->monitorcontext[options->numbermonitors++] = (void*)mctx;
    2564:   return(0);
    2565: }

    2569: /*@
    2570:    PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.

    2572:    Not collective

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

    2579:    Level: intermediate

    2581: .keywords: PetscOptions, set, monitor

    2583: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
    2584: @*/
    2585: PetscErrorCode  PetscOptionsMonitorCancel(void)
    2586: {
    2588:   PetscInt       i;

    2591:   for (i=0; i<options->numbermonitors; i++) {
    2592:     if (options->monitordestroy[i]) {
    2593:       (*options->monitordestroy[i])(&options->monitorcontext[i]);
    2594:     }
    2595:   }
    2596:   options->numbermonitors = 0;
    2597:   return(0);
    2598: }

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

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

    2607:   Collective on PetscObject

    2609:   Input Parameters:
    2610: + obj   - the object
    2611: . bobj  - optional other object that provides prefix (if NULL then the prefix in obj is used)
    2612: - optionname - option to activate viewing

    2614:   Level: intermediate

    2616: @*/
    2617: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
    2618: {
    2619:   PetscErrorCode    ierr;
    2620:   PetscViewer       viewer;
    2621:   PetscBool         flg;
    2622:   static PetscBool  incall = PETSC_FALSE;
    2623:   PetscViewerFormat format;
    2624:   char              *prefix;

    2627:   if (incall) return(0);
    2628:   incall = PETSC_TRUE;
    2629:   prefix = bobj ? bobj->prefix : obj->prefix;
    2630:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
    2631:   if (flg) {
    2632:     PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
    2633:     PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
    2634:     PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
    2635:     PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
    2636:   }
    2637:   incall = PETSC_FALSE;
    2638:   return(0);
    2639: }