Actual source code: options.c

      1: #define PETSC_DLL
      2: /*
      3:    These routines simplify the use of command line, file options, etc.,
      4:    and are used to manipulate the options database.

      6:   This file uses regular malloc and free because it cannot know
      7:   what malloc is being used until it has already processed the input.
      8: */

     10:  #include petsc.h
     11:  #include petscsys.h
     12: #if defined(PETSC_HAVE_STDLIB_H)
     13: #include <stdlib.h>
     14: #endif
     15: #if defined(PETSC_HAVE_MALLOC_H)
     16: #include <malloc.h>
     17: #endif
     18: #if defined(PETSC_HAVE_SYS_PARAM_H)
     19: #include "sys/param.h"
     20: #endif
     21: #include "petscfix.h"

     23: /*
     24:     For simplicity, we use a static size database
     25: */
     26: #define MAXOPTIONS 512
     27: #define MAXALIASES 25

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

     38: static PetscOptionsTable *options = 0;

     42: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtoi(const char name[],PetscInt *a)
     43: {
     45:   size_t         i,len;
     46:   PetscTruth     decide,tdefault,mouse;

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

     52:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
     53:   if (!tdefault) {
     54:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
     55:   }
     56:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
     57:   if (!decide) {
     58:     PetscStrcasecmp(name,"DECIDE",&decide);
     59:   }
     60:   PetscStrcasecmp(name,"mouse",&mouse);

     62:   if (tdefault) {
     63:     *a = PETSC_DEFAULT;
     64:   } else if (decide) {
     65:     *a = PETSC_DECIDE;
     66:   } else if (mouse) {
     67:     *a = -1;
     68:   } else {
     69:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
     70:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
     71:     }
     72:     for (i=1; i<len; i++) {
     73:       if (name[i] < '0' || name[i] > '9') {
     74:         SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
     75:       }
     76:     }
     77:     *a  = atoi(name);
     78:   }
     79:   return(0);
     80: }

     84: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAtod(const char name[],PetscReal *a)
     85: {
     87:   size_t     len;
     88:   PetscTruth decide,tdefault;

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

     94:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
     95:   if (!tdefault) {
     96:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
     97:   }
     98:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
     99:   if (!decide) {
    100:     PetscStrcasecmp(name,"DECIDE",&decide);
    101:   }

    103:   if (tdefault) {
    104:     *a = PETSC_DEFAULT;
    105:   } else if (decide) {
    106:     *a = PETSC_DECIDE;
    107:   } else {
    108:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
    109:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
    110:     }
    111:     *a  = atof(name);
    112:   }
    113:   return(0);
    114: }

    118: /*@C
    119:     PetscGetProgramName - Gets the name of the running program.

    121:     Not Collective

    123:     Input Parameter:
    124: .   len - length of the string name

    126:     Output Parameter:
    127: .   name - the name of the running program

    129:    Level: advanced

    131:     Notes:
    132:     The name of the program is copied into the user-provided character
    133:     array of length len.  On some machines the program name includes
    134:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
    135: @*/
    136: PetscErrorCode PETSC_DLLEXPORT PetscGetProgramName(char name[],size_t len)
    137: {

    141:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
    142:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
    143:   PetscStrncpy(name,options->programname,len);
    144:   return(0);
    145: }

    149: PetscErrorCode PETSC_DLLEXPORT PetscSetProgramName(const char name[])
    150: {

    154:   options->namegiven = PETSC_TRUE;
    155:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
    156:   return(0);
    157: }

    161: /*@C
    162:      PetscOptionsInsertString - Inserts options into the database from a string

    164:      Not collective: but only processes that call this routine will set the options
    165:                      included in the file

    167:   Input Parameter:
    168: .   in_str - string that contains options seperated by blanks

    171:   Level: intermediate

    173:   Contributed by Boyana Norris

    175: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
    176:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
    177:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    178:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    179:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    180:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

    182: @*/
    183: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertString(const char in_str[])
    184: {
    185:   char           *str,*first,*second,*third,*final;
    186:   size_t         len;
    188:   PetscToken     *token;

    191:   PetscStrallocpy(in_str, &str);
    192:   PetscTokenCreate(str,' ',&token);
    193:   PetscTokenFind(token,&first);
    194:   PetscTokenFind(token,&second);
    195:   if (first && first[0] == '-') {
    196:     if (second) {final = second;} else {final = first;}
    197:     PetscStrlen(final,&len);
    198:     while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
    199:       len--; final[len] = 0;
    200:     }
    201:     PetscOptionsSetValue(first,second);
    202:   } else if (first) {
    203:     PetscTruth match;
    204:
    205:     PetscStrcasecmp(first,"alias",&match);
    206:     if (match) {
    207:       PetscTokenFind(token,&third);
    208:       if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
    209:       PetscStrlen(third,&len);
    210:       if (third[len-1] == 'n') third[len-1] = 0;
    211:       PetscOptionsSetAlias(second,third);
    212:     }
    213:   }
    214:   PetscTokenDestroy(token);
    215:   PetscFree(str);
    216:
    217:   return(0);
    218: }

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

    225:      Not collective: but only processes that call this routine will set the options
    226:                      included in the file

    228:   Input Parameter:
    229: .   file - name of file

    232:   Level: intermediate

    234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
    235:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
    236:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    237:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    238:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    239:           PetscOptionsList(), PetscOptionsEList()

    241: @*/
    242: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsertFile(const char file[])
    243: {
    244:   char           string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
    246:   size_t         i,len,startIndex;
    247:   FILE           *fd;
    248:   PetscToken     *token;

    251:   PetscFixFilename(file,fname);
    252:   fd   = fopen(fname,"r");
    253:   if (fd) {
    254:     while (fgets(string,128,fd)) {
    255:       /* Comments are indicated by #, ! or % in the first column */
    256:       if (string[0] == '#') continue;
    257:       if (string[0] == '!') continue;
    258:       if (string[0] == '%') continue;

    260:       PetscStrlen(string,&len);

    262:       /* replace tabs, ^M with " " */
    263:       for (i=0; i<len; i++) {
    264:         if (string[i] == '\t' || string[i] == '\r') {
    265:           string[i] = ' ';
    266:         }
    267:       }
    268:       for(startIndex = 0; startIndex < len-1; startIndex++) {
    269:         if (string[startIndex] != ' ') break;
    270:       }
    271:       PetscTokenCreate(&string[startIndex],' ',&token);
    272:       PetscTokenFind(token,&first);
    273:       PetscTokenFind(token,&second);
    274:       if (first && first[0] == '-') {
    275:         if (second) {final = second;} else {final = first;}
    276:         PetscStrlen(final,&len);
    277:         while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
    278:           len--; final[len] = 0;
    279:         }
    280:         PetscOptionsSetValue(first,second);
    281:       } else if (first) {
    282:         PetscTruth match;

    284:         PetscStrcasecmp(first,"alias",&match);
    285:         if (match) {
    286:           PetscTokenFind(token,&third);
    287:           if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
    288:           PetscStrlen(third,&len);
    289:           if (third[len-1] == '\n') third[len-1] = 0;
    290:           PetscOptionsSetAlias(second,third);
    291:         }
    292:       }
    293:       PetscTokenDestroy(token);
    294:     }
    295:     fclose(fd);
    296:   } else {
    297:     SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
    298:   }
    299:   return(0);
    300: }

    304: /*@C
    305:    PetscOptionsInsert - Inserts into the options database from the command line,
    306:                    the environmental variable and a file.

    308:    Input Parameters:
    309: +  argc - count of number of command line arguments
    310: .  args - the command line arguments
    311: -  file - optional filename, defaults to ~username/.petscrc

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

    318:    Level: advanced

    320:    Concepts: options database^adding

    322: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
    323: @*/
    324: PetscErrorCode PETSC_DLLEXPORT PetscOptionsInsert(int *argc,char ***args,const char file[])
    325: {
    327:   PetscMPIInt    rank;
    328:   char           pfile[PETSC_MAX_PATH_LEN];
    329:   PetscToken     *token;

    332:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

    334:   options->argc     = (argc) ? *argc : 0;
    335:   options->args     = (args) ? *args : 0;

    337:   if (file) {
    338:     PetscOptionsInsertFile(file);
    339:   } else {
    340:     PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
    341:     if (pfile[0]) {
    342:       PetscTruth flag;
    343:       PetscStrcat(pfile,"/.petscrc");
    344:       PetscTestFile(pfile,'r',&flag);
    345:       if (flag) {
    346:         PetscOptionsInsertFile(pfile);
    347:       }
    348:     } else {
    349:       PetscLogInfo((0,"PetscOptionsInsert:Unable to determine home directory; skipping loading ~/.petscrc\n"));
    350:     }
    351:   }

    353:   /* insert environmental options */
    354:   {
    355:     char   *eoptions = 0,*second,*first;
    356:     size_t len = 0;
    357:     if (!rank) {
    358:       eoptions = (char*)getenv("PETSC_OPTIONS");
    359:       PetscStrlen(eoptions,&len);
    360:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
    361:     } else {
    362:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
    363:       if (len) {
    364:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
    365:       }
    366:     }
    367:     if (len) {
    368:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
    369:       eoptions[len] = 0;
    370:        PetscTokenCreate(eoptions,' ',&token);
    371:        PetscTokenFind(token,&first);
    372:       while (first) {
    373:         if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
    374:         PetscTokenFind(token,&second);
    375:         if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
    376:           PetscOptionsSetValue(first,(char *)0);
    377:           first = second;
    378:         } else {
    379:           PetscOptionsSetValue(first,second);
    380:           PetscTokenFind(token,&first);
    381:         }
    382:       }
    383:        PetscTokenDestroy(token);
    384:       if (rank) {PetscFree(eoptions);}
    385:     }
    386:   }

    388:   /* insert command line options */
    389:   if (argc && args && *argc) {
    390:     int        left    = *argc - 1;
    391:     char       **eargs = *args + 1;
    392:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

    394:     while (left) {
    395:       PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
    396:       PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
    397:       PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
    398:       PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
    399:       PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
    400:       isp4 = (PetscTruth) (isp4 || tisp4);
    401:       PetscStrcasecmp(eargs[0],"-np",&tisp4);
    402:       isp4 = (PetscTruth) (isp4 || tisp4);
    403:       PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);

    405:       if (eargs[0][0] != '-') {
    406:         eargs++; left--;
    407:       } else if (isoptions_file) {
    408:         if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
    409:         if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
    410:         PetscOptionsInsertFile(eargs[1]);
    411:         eargs += 2; left -= 2;

    413:       /*
    414:          These are "bad" options that MPICH, etc put on the command line
    415:          we strip them out here.
    416:       */
    417:       } else if (tisp4 || isp4rmrank) {
    418:         eargs += 1; left -= 1;
    419:       } else if (isp4 || isp4yourname) {
    420:         eargs += 2; left -= 2;
    421:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
    422:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
    423:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
    424:         eargs++; left--;
    425:       } else {
    426:         PetscOptionsSetValue(eargs[0],eargs[1]);
    427:         eargs += 2; left -= 2;
    428:       }
    429:     }
    430:   }
    431:   return(0);
    432: }

    436: /*@C
    437:    PetscOptionsPrint - Prints the options that have been loaded. This is
    438:    useful for debugging purposes.

    440:    Collective on PETSC_COMM_WORLD

    442:    Input Parameter:
    443: .  FILE fd - location to print options (usually stdout or stderr)

    445:    Options Database Key:
    446: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

    448:    Level: advanced

    450:    Concepts: options database^printing

    452: .seealso: PetscOptionsAllUsed()
    453: @*/
    454: PetscErrorCode PETSC_DLLEXPORT PetscOptionsPrint(FILE *fd)
    455: {
    457:   int i;

    460:   if (!fd) fd = stdout;
    461:   if (!options) {PetscOptionsInsert(0,0,0);}
    462:   for (i=0; i<options->N; i++) {
    463:     if (options->values[i]) {
    464:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
    465:     } else {
    466:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
    467:     }
    468:   }
    469:   return(0);
    470: }

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

    477:    Not Collective

    479:    Output Parameter:
    480: .  copts - pointer where string pointer is stored

    482:    Level: advanced

    484:    Concepts: options database^listing

    486: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
    487: @*/
    488: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetAll(char *copts[])
    489: {
    491:   int    i;
    492:   size_t len = 1,lent;
    493:   char   *coptions;

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

    498:   /* count the length of the required string */
    499:   for (i=0; i<options->N; i++) {
    500:     PetscStrlen(options->names[i],&lent);
    501:     len += 2 + lent;
    502:     if (options->values[i]) {
    503:       PetscStrlen(options->values[i],&lent);
    504:       len += 1 + lent;
    505:     }
    506:   }
    507:   PetscMalloc(len*sizeof(char),&coptions);
    508:   coptions[0] = 0;
    509:   for (i=0; i<options->N; i++) {
    510:     PetscStrcat(coptions,"-");
    511:     PetscStrcat(coptions,options->names[i]);
    512:     PetscStrcat(coptions," ");
    513:     if (options->values[i]) {
    514:       PetscStrcat(coptions,options->values[i]);
    515:       PetscStrcat(coptions," ");
    516:     }
    517:   }
    518:   *copts = coptions;
    519:   return(0);
    520: }

    524: /*@C
    525:     PetscOptionsDestroy - Destroys the option database.

    527:     Note:
    528:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user
    529:     typically does not need to call this routine.

    531:    Level: developer

    533: .seealso: PetscOptionsInsert()
    534: @*/
    535: PetscErrorCode PETSC_DLLEXPORT PetscOptionsDestroy(void)
    536: {
    537:   int i;

    540:   if (!options) return(0);
    541:   for (i=0; i<options->N; i++) {
    542:     if (options->names[i]) free(options->names[i]);
    543:     if (options->values[i]) free(options->values[i]);
    544:   }
    545:   for (i=0; i<options->Naliases; i++) {
    546:     free(options->aliases1[i]);
    547:     free(options->aliases2[i]);
    548:   }
    549:   free(options);
    550:   options = 0;
    551:   return(0);
    552: }

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

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

    563:    Input Parameters:
    564: +  name - name of option, this SHOULD have the - prepended
    565: -  value - the option value (not used for all options)

    567:    Level: intermediate

    569:    Note:
    570:    Only some options have values associated with them, such as
    571:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

    573:   Concepts: options database^adding option

    575: .seealso: PetscOptionsInsert()
    576: @*/
    577: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetValue(const char iname[],const char value[])
    578: {
    579:   size_t     len;
    581:   int        N,n,i;
    582:   char       **names;
    583:   const char *name = (char*)iname;
    584:   PetscTruth gt,match;

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

    589:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
    590:   PetscStrcasecmp(name,"-h",&match);
    591:   if (match) name = "-help";

    593:   name++;
    594:   /* first check against aliases */
    595:   N = options->Naliases;
    596:   for (i=0; i<N; i++) {
    597:     PetscStrcasecmp(options->aliases1[i],name,&match);
    598:     if (match) {
    599:       name = options->aliases2[i];
    600:       break;
    601:     }
    602:   }

    604:   N     = options->N;
    605:   n     = N;
    606:   names = options->names;
    607:
    608:   for (i=0; i<N; i++) {
    609:     PetscStrcasecmp(names[i],name,&match);
    610:     PetscStrgrt(names[i],name,&gt);
    611:     if (match) {
    612:       if (options->values[i]) free(options->values[i]);
    613:       PetscStrlen(value,&len);
    614:       if (len) {
    615:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
    616:         PetscStrcpy(options->values[i],value);
    617:       } else { options->values[i] = 0;}
    618:       return(0);
    619:     } else if (gt) {
    620:       n = i;
    621:       break;
    622:     }
    623:   }
    624:   if (N >= MAXOPTIONS) {
    625:     SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
    626:   }
    627:   /* shift remaining values down 1 */
    628:   for (i=N; i>n; i--) {
    629:     names[i]           = names[i-1];
    630:     options->values[i] = options->values[i-1];
    631:     options->used[i]   = options->used[i-1];
    632:   }
    633:   /* insert new name and value */
    634:   PetscStrlen(name,&len);
    635:   names[n] = (char*)malloc((len+1)*sizeof(char));
    636:   PetscStrcpy(names[n],name);
    637:   if (value) {
    638:     PetscStrlen(value,&len);
    639:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
    640:     PetscStrcpy(options->values[n],value);
    641:   } else {options->values[n] = 0;}
    642:   options->used[n] = PETSC_FALSE;
    643:   options->N++;
    644:   return(0);
    645: }

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

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

    656:    Input Parameter:
    657: .  name - name of option, this SHOULD have the - prepended

    659:    Level: intermediate

    661:    Concepts: options database^removing option
    662: .seealso: PetscOptionsInsert()
    663: @*/
    664: PetscErrorCode PETSC_DLLEXPORT PetscOptionsClearValue(const char iname[])
    665: {
    667:   int        N,n,i;
    668:   char       **names,*name=(char*)iname;
    669:   PetscTruth gt,match;

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

    675:   name++;

    677:   N     = options->N; n = 0;
    678:   names = options->names;
    679:
    680:   for (i=0; i<N; i++) {
    681:     PetscStrcasecmp(names[i],name,&match);
    682:     PetscStrgrt(names[i],name,&gt);
    683:     if (match) {
    684:       if (options->values[i]) free(options->values[i]);
    685:       break;
    686:     } else if (gt) {
    687:       return(0); /* it was not listed */
    688:     }
    689:     n++;
    690:   }
    691:   if (n == N) return(0); /* it was not listed */

    693:   /* shift remaining values down 1 */
    694:   for (i=n; i<N-1; i++) {
    695:     names[i]           = names[i+1];
    696:     options->values[i] = options->values[i+1];
    697:     options->used[i]   = options->used[i+1];
    698:   }
    699:   options->N--;
    700:   return(0);
    701: }

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

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

    711:    Input Parameters:
    712: +  name - the option one is seeking
    713: -  mess - error message (may be PETSC_NULL)

    715:    Level: advanced

    717:    Concepts: options database^rejecting option

    719: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    720:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
    721:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    722:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    723:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    724:           PetscOptionsList(), PetscOptionsEList()
    725: @*/
    726: PetscErrorCode PETSC_DLLEXPORT PetscOptionsSetAlias(const char inewname[],const char ioldname[])
    727: {
    729:   int    n = options->Naliases;
    730:   size_t len;
    731:   char   *newname = (char *)inewname,*oldname = (char*)ioldname;

    734:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
    735:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
    736:   if (n >= MAXALIASES) {
    737:     SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n  src/sys/src/objects/options.c with larger value for MAXALIASES",MAXALIASES);
    738:   }

    740:   newname++; oldname++;
    741:   PetscStrlen(newname,&len);
    742:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
    743:   PetscStrcpy(options->aliases1[n],newname);
    744:   PetscStrlen(oldname,&len);
    745:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
    746:   PetscStrcpy(options->aliases2[n],oldname);
    747:   options->Naliases++;
    748:   return(0);
    749: }

    753: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
    754: {
    756:   PetscInt       i,N;
    757:   size_t         len;
    758:   char           **names,tmp[256];
    759:   PetscTruth     match;

    762:   if (!options) {PetscOptionsInsert(0,0,0);}
    763:   N = options->N;
    764:   names = options->names;

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

    768:   /* append prefix to name */
    769:   if (pre) {
    770:     if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
    771:     PetscStrncpy(tmp,pre,256);
    772:     PetscStrlen(tmp,&len);
    773:     PetscStrncat(tmp,name+1,256-len-1);
    774:   } else {
    775:     PetscStrncpy(tmp,name+1,256);
    776:   }

    778:   /* slow search */
    779:   *flg = PETSC_FALSE;
    780:   for (i=0; i<N; i++) {
    781:     PetscStrcasecmp(names[i],tmp,&match);
    782:     if (match) {
    783:        *value           = options->values[i];
    784:        options->used[i] = PETSC_TRUE;
    785:        *flg             = PETSC_TRUE;
    786:        break;
    787:      }
    788:   }
    789:   if (!*flg) {
    790:     PetscInt j,cnt = 0,locs[16],loce[16];
    791:     size_t   n;
    792:     PetscStrlen(tmp,&n);
    793:     /* determine the location and number of all _%d_ in the key */
    794:     for (i=0; i< (PetscInt)n; i++) {
    795:       if (tmp[i] == '_') {
    796:         for (j=i+1; j< (PetscInt)n; j++) {
    797:           if (tmp[j] >= '0' && tmp[j] <= '9') continue;
    798:           if (tmp[j] == '_' && j > i+1) { /* found a number */
    799:             locs[cnt]   = i+1;
    800:             loce[cnt++] = j+1;
    801:           }
    802:           break;
    803:         }
    804:       }
    805:     }
    806:     if (cnt) {
    807:       char tmp2[256];
    808:       for (i=0; i<cnt; i++) {
    809:         PetscStrcpy(tmp2,"-");
    810:         PetscStrncat(tmp2,tmp,locs[i]);
    811:         PetscStrcat(tmp2,tmp+loce[i]);
    812:         PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
    813:         if (*flg) break;
    814:       }
    815:     }
    816:   }
    817:   return(0);
    818: }

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

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

    828:    Input Parameters:
    829: +  name - the option one is seeking
    830: -  mess - error message (may be PETSC_NULL)

    832:    Level: advanced

    834:    Concepts: options database^rejecting option

    836: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
    837:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    838:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    839:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    840:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    841:           PetscOptionsList(), PetscOptionsEList()
    842: @*/
    843: PetscErrorCode PETSC_DLLEXPORT PetscOptionsReject(const char name[],const char mess[])
    844: {
    846:   PetscTruth flag;

    849:   PetscOptionsHasName(PETSC_NULL,name,&flag);
    850:   if (flag) {
    851:     if (mess) {
    852:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
    853:     } else {
    854:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
    855:     }
    856:   }
    857:   return(0);
    858: }

    862: /*@C
    863:    PetscOptionsHasName - Determines whether a certain option is given in the database.

    865:    Not Collective

    867:    Input Parameters:
    868: +  name - the option one is seeking
    869: -  pre - string to prepend to the name or PETSC_NULL

    871:    Output Parameters:
    872: .  flg - PETSC_TRUE if found else PETSC_FALSE.

    874:    Level: beginner

    876:    Concepts: options database^has option name

    878: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    879:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    880:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    881:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    882:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    883:           PetscOptionsList(), PetscOptionsEList()
    884: @*/
    885: PetscErrorCode PETSC_DLLEXPORT PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
    886: {
    887:   char       *value;
    889:   PetscTruth isfalse,flag;

    892:   PetscOptionsFindPair_Private(pre,name,&value,&flag);

    894:   /* remove if turned off */
    895:   if (flag) {
    896:     PetscStrcasecmp(value,"FALSE",&isfalse);
    897:     if (isfalse) flag = PETSC_FALSE;
    898:     PetscStrcasecmp(value,"NO",&isfalse);
    899:     if (isfalse) flag = PETSC_FALSE;
    900:     PetscStrcasecmp(value,"0",&isfalse);
    901:     if (isfalse) flag = PETSC_FALSE;
    902:   }
    903:   if (flg) *flg = flag;
    904:   return(0);
    905: }

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

    912:    Not Collective

    914:    Input Parameters:
    915: +  pre - the string to prepend to the name or PETSC_NULL
    916: -  name - the option one is seeking

    918:    Output Parameter:
    919: +  ivalue - the integer value to return
    920: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    922:    Level: beginner

    924:    Concepts: options database^has int

    926: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    927:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
    928:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
    929:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    930:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    931:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    932:           PetscOptionsList(), PetscOptionsEList()
    933: @*/
    934: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
    935: {
    936:   char       *value;
    938:   PetscTruth flag;

    943:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    944:   if (flag) {
    945:     if (!value) {if (flg) *flg = PETSC_FALSE;}
    946:     else {
    947:       if (flg) *flg = PETSC_TRUE;
    948:       PetscOptionsAtoi(value,ivalue);
    949:     }
    950:   } else {
    951:     if (flg) *flg = PETSC_FALSE;
    952:   }
    953:   return(0);
    954: }

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

    961:    Not Collective

    963:    Input Parameters:
    964: +  pre - the string to prepend to the name or PETSC_NULL
    965: .  opt - option name
    966: .  list - the possible choices
    967: .  ntext - number of choices

    969:    Output Parameter:
    970: +  value - the index of the value to return
    971: -  set - PETSC_TRUE if found, else PETSC_FALSE
    972:
    973:    Level: intermediate

    975:    See PetscOptionsList() for when the choices are given in a PetscFList()

    977:    Concepts: options database^list

    979: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    980:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    981:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    982:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    983:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    984:           PetscOptionsList(), PetscOptionsEList()
    985: @*/
    986: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
    987: {
    989:   size_t         alen,len = 0;
    990:   char           *svalue;
    991:   PetscTruth     aset,flg = PETSC_FALSE;
    992:   PetscInt       i;

    995:   for ( i=0; i<ntext; i++) {
    996:     PetscStrlen(list[i],&alen);
    997:     if (alen > len) len = alen;
    998:   }
    999:   len += 5; /* a little extra space for user mistypes */
    1000:   PetscMalloc(len*sizeof(char),&svalue);
    1001:   PetscOptionsGetString(pre,opt,svalue,len,&aset);
    1002:   if (aset) {
    1003:     if (set) *set = PETSC_TRUE;
    1004:     for (i=0; i<ntext; i++) {
    1005:       PetscStrcasecmp(svalue,list[i],&flg);
    1006:       if (flg) {
    1007:         *value = i;
    1008:         break;
    1009:       }
    1010:     }
    1011:     if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
    1012:   } else if (set) {
    1013:     *set = PETSC_FALSE;
    1014:   }
    1015:   PetscFree(svalue);
    1016:   return(0);
    1017: }

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

    1024:    Not Collective

    1026:    Input Parameters:
    1027: +  pre - option prefix or PETSC_NULL
    1028: .  opt - option name
    1029: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    1030: -  defaultv - the default (current) value

    1032:    Output Parameter:
    1033: +  value - the  value to return
    1034: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1036:    Level: beginner

    1038:    Concepts: options database

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

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

    1044: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
    1045:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
    1046:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
    1047:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1048:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1049:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1050:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
    1051: @*/
    1052: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
    1053: {
    1055:   PetscInt       ntext = 0;

    1058:   while (list[ntext++]) {
    1059:     if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
    1060:   }
    1061:   if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
    1062:   ntext -= 3;
    1063:   PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
    1064:   return(0);
    1065: }

    1069: /*@C
    1070:    PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
    1071:             option in the database.

    1073:    Not Collective

    1075:    Input Parameters:
    1076: +  pre - the string to prepend to the name or PETSC_NULL
    1077: -  name - the option one is seeking

    1079:    Output Parameter:
    1080: +  ivalue - the logical value to return
    1081: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

    1083:    Level: beginner

    1085:    Notes:
    1086:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
    1087:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

    1089:    Concepts: options database^has logical

    1091: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
    1092:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
    1093:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1094:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1095:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1096:           PetscOptionsList(), PetscOptionsEList()
    1097: @*/
    1098: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
    1099: {
    1100:   char           *value;
    1101:   PetscTruth     flag,istrue,isfalse;

    1107:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1108:   if (flag) {
    1109:     if (flg) *flg = PETSC_TRUE;
    1110:     if (!value) {
    1111:       *ivalue = PETSC_TRUE;
    1112:     } else {
    1113:       *ivalue = PETSC_TRUE;
    1114:       PetscStrcasecmp(value,"TRUE",&istrue);
    1115:       if (istrue) return(0);
    1116:       PetscStrcasecmp(value,"YES",&istrue);
    1117:       if (istrue) return(0);
    1118:       PetscStrcasecmp(value,"1",&istrue);
    1119:       if (istrue) return(0);
    1120:       PetscStrcasecmp(value,"on",&istrue);
    1121:       if (istrue) return(0);

    1123:       *ivalue = PETSC_FALSE;
    1124:       PetscStrcasecmp(value,"FALSE",&isfalse);
    1125:       if (isfalse) return(0);
    1126:       PetscStrcasecmp(value,"NO",&isfalse);
    1127:       if (isfalse) return(0);
    1128:       PetscStrcasecmp(value,"0",&isfalse);
    1129:       if (isfalse) return(0);
    1130:       PetscStrcasecmp(value,"off",&isfalse);
    1131:       if (isfalse) return(0);

    1133:       SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
    1134:     }
    1135:   } else {
    1136:     if (flg) *flg = PETSC_FALSE;
    1137:   }
    1138:   return(0);
    1139: }

    1143: /*@C
    1144:    PetscOptionsGetReal - Gets the double precision value for a particular
    1145:    option in the database.

    1147:    Not Collective

    1149:    Input Parameters:
    1150: +  pre - string to prepend to each name or PETSC_NULL
    1151: -  name - the option one is seeking

    1153:    Output Parameter:
    1154: +  dvalue - the double value to return
    1155: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

    1157:    Level: beginner

    1159:    Concepts: options database^has double

    1161: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1162:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
    1163:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1164:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1165:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1166:           PetscOptionsList(), PetscOptionsEList()
    1167: @*/
    1168: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
    1169: {
    1170:   char           *value;
    1172:   PetscTruth     flag;

    1177:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1178:   if (flag) {
    1179:     if (!value) {if (flg) *flg = PETSC_FALSE;}
    1180:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
    1181:   } else {
    1182:     if (flg) *flg = PETSC_FALSE;
    1183:   }
    1184:   return(0);
    1185: }

    1189: /*@C
    1190:    PetscOptionsGetScalar - Gets the scalar value for a particular
    1191:    option in the database.

    1193:    Not Collective

    1195:    Input Parameters:
    1196: +  pre - string to prepend to each name or PETSC_NULL
    1197: -  name - the option one is seeking

    1199:    Output Parameter:
    1200: +  dvalue - the double value to return
    1201: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1203:    Level: beginner

    1205:    Usage:
    1206:    A complex number 2+3i can be specified as 2,3 at the command line.
    1207:    or a number 2.0e-10 - 3.3e-20 i  can be specified as 2.0e-10,3.3e-20

    1209:    Concepts: options database^has scalar

    1211: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1212:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    1213:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1214:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1215:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1216:           PetscOptionsList(), PetscOptionsEList()
    1217: @*/
    1218: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
    1219: {
    1220:   char           *value;
    1221:   PetscTruth     flag;

    1227:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1228:   if (flag) {
    1229:     if (!value) {
    1230:       if (flg) *flg = PETSC_FALSE;
    1231:     } else {
    1232: #if !defined(PETSC_USE_COMPLEX)
    1233:       PetscOptionsAtod(value,dvalue);
    1234: #else
    1235:       PetscReal  re=0.0,im=0.0;
    1236:       PetscToken *token;
    1237:       char       *tvalue = 0;

    1239:       PetscTokenCreate(value,',',&token);
    1240:       PetscTokenFind(token,&tvalue);
    1241:       if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
    1242:       PetscOptionsAtod(tvalue,&re);
    1243:       PetscTokenFind(token,&tvalue);
    1244:       if (!tvalue) { /* Unknown separator used. using only real value */
    1245:         *dvalue = re;
    1246:       } else {
    1247:         PetscOptionsAtod(tvalue,&im);
    1248:         *dvalue = re + PETSC_i*im;
    1249:       }
    1250:       PetscTokenDestroy(token);
    1251: #endif
    1252:       if (flg) *flg    = PETSC_TRUE;
    1253:     }
    1254:   } else { /* flag */
    1255:     if (flg) *flg = PETSC_FALSE;
    1256:   }
    1257:   return(0);
    1258: }

    1262: /*@C
    1263:    PetscOptionsGetRealArray - Gets an array of double precision values for a
    1264:    particular option in the database.  The values must be separated with
    1265:    commas with no intervening spaces.

    1267:    Not Collective

    1269:    Input Parameters:
    1270: +  pre - string to prepend to each name or PETSC_NULL
    1271: .  name - the option one is seeking
    1272: -  nmax - maximum number of values to retrieve

    1274:    Output Parameters:
    1275: +  dvalue - the double value to return
    1276: .  nmax - actual number of values retreived
    1277: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1279:    Level: beginner

    1281:    Concepts: options database^array of doubles

    1283: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1284:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
    1285:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1286:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1287:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1288:           PetscOptionsList(), PetscOptionsEList()
    1289: @*/
    1290: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
    1291: {
    1292:   char           *value;
    1294:   PetscInt       n = 0;
    1295:   PetscTruth     flag;
    1296:   PetscToken     *token;

    1301:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1302:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
    1303:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

    1305:   if (flg) *flg = PETSC_TRUE;

    1307:   PetscTokenCreate(value,',',&token);
    1308:   PetscTokenFind(token,&value);
    1309:   while (n < *nmax) {
    1310:     if (!value) break;
    1311:     PetscOptionsAtod(value,dvalue++);
    1312:     PetscTokenFind(token,&value);
    1313:     n++;
    1314:   }
    1315:   PetscTokenDestroy(token);
    1316:   *nmax = n;
    1317:   return(0);
    1318: }

    1322: /*@C
    1323:    PetscOptionsGetIntArray - Gets an array of integer values for a particular
    1324:    option in the database.  The values must be separated with commas with
    1325:    no intervening spaces.

    1327:    Not Collective

    1329:    Input Parameters:
    1330: +  pre - string to prepend to each name or PETSC_NULL
    1331: .  name - the option one is seeking
    1332: -  nmax - maximum number of values to retrieve

    1334:    Output Parameter:
    1335: +  dvalue - the integer values to return
    1336: .  nmax - actual number of values retreived
    1337: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1339:    Level: beginner

    1341:    Concepts: options database^array of ints

    1343: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
    1344:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    1345:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1346:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1347:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1348:           PetscOptionsList(), PetscOptionsEList()
    1349: @*/
    1350: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
    1351: {
    1352:   char           *value;
    1354:   PetscInt       n = 0;
    1355:   PetscTruth     flag;
    1356:   PetscToken     *token;

    1361:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1362:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
    1363:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

    1365:   if (flg) *flg = PETSC_TRUE;

    1367:   PetscTokenCreate(value,',',&token);
    1368:   PetscTokenFind(token,&value);
    1369:   while (n < *nmax) {
    1370:     if (!value) break;
    1371:     PetscOptionsAtoi(value,dvalue);
    1372:     dvalue++;
    1373:     PetscTokenFind(token,&value);
    1374:     n++;
    1375:   }
    1376:   PetscTokenDestroy(token);
    1377:   *nmax = n;
    1378:   return(0);
    1379: }

    1383: /*@C
    1384:    PetscOptionsGetString - Gets the string value for a particular option in
    1385:    the database.

    1387:    Not Collective

    1389:    Input Parameters:
    1390: +  pre - string to prepend to name or PETSC_NULL
    1391: .  name - the option one is seeking
    1392: -  len - maximum string length

    1394:    Output Parameters:
    1395: +  string - location to copy string
    1396: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1398:    Level: beginner

    1400:    Fortran Note:
    1401:    The Fortran interface is slightly different from the C/C++
    1402:    interface (len is not used).  Sample usage in Fortran follows
    1403: .vb
    1404:       character *20 string
    1405:       integer   flg, ierr
    1406:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
    1407: .ve

    1409:    Concepts: options database^string

    1411: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1412:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    1413:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1414:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1415:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1416:           PetscOptionsList(), PetscOptionsEList()
    1417: @*/
    1418: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
    1419: {
    1420:   char           *value;
    1422:   PetscTruth     flag;

    1427:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1428:   if (!flag) {
    1429:     if (flg) *flg = PETSC_FALSE;
    1430:   } else {
    1431:     if (flg) *flg = PETSC_TRUE;
    1432:     if (value) {
    1433:       PetscStrncpy(string,value,len);
    1434:     } else {
    1435:       PetscMemzero(string,len);
    1436:     }
    1437:   }
    1438:   return(0);
    1439: }

    1443: /*@C
    1444:    PetscOptionsGetStringArray - Gets an array of string values for a particular
    1445:    option in the database. The values must be separated with commas with
    1446:    no intervening spaces.

    1448:    Not Collective

    1450:    Input Parameters:
    1451: +  pre - string to prepend to name or PETSC_NULL
    1452: .  name - the option one is seeking
    1453: -  nmax - maximum number of strings

    1455:    Output Parameter:
    1456: +  strings - location to copy strings
    1457: -  flg - PETSC_TRUE if found, else PETSC_FALSE

    1459:    Level: beginner

    1461:    Notes:
    1462:    The user should pass in an array of pointers to char, to hold all the
    1463:    strings returned by this function.

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

    1468:    Contributed by Matthew Knepley.

    1470:    Concepts: options database^array of strings

    1472: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
    1473:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
    1474:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
    1475:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
    1476:           PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
    1477:           PetscOptionsList(), PetscOptionsEList()
    1478: @*/
    1479: PetscErrorCode PETSC_DLLEXPORT PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
    1480: {
    1481:   char           *value;
    1483:   PetscInt       n;
    1484:   PetscTruth     flag;
    1485:   PetscToken     *token;
    1486:
    1490:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
    1491:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
    1492:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
    1493:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
    1494:   if (flg) *flg = PETSC_TRUE;

    1496:   PetscTokenCreate(value,',',&token);
    1497:   PetscTokenFind(token,&value);
    1498:   n = 0;
    1499:   while (n < *nmax) {
    1500:     if (!value) break;
    1501:     PetscStrallocpy(value,&strings[n]);
    1502:     PetscTokenFind(token,&value);
    1503:     n++;
    1504:   }
    1505:   PetscTokenDestroy(token);
    1506:   *nmax = n;
    1507:   return(0);
    1508: }

    1512: /*@C
    1513:    PetscOptionsAllUsed - Returns a count of the number of options in the
    1514:    database that have never been selected.

    1516:    Not Collective

    1518:    Output Parameter:
    1519: .   N - count of options not used

    1521:    Level: advanced

    1523: .seealso: PetscOptionsPrint()
    1524: @*/
    1525: PetscErrorCode PETSC_DLLEXPORT PetscOptionsAllUsed(int *N)
    1526: {
    1527:   PetscInt i,n = 0;

    1530:   for (i=0; i<options->N; i++) {
    1531:     if (!options->used[i]) { n++; }
    1532:   }
    1533:   *N = n;
    1534:   return(0);
    1535: }

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

    1542:   Not collective

    1544:    Options Database Key:
    1545: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

    1547:   Level: advanced

    1549: .seealso: PetscOptionsAllUsed()
    1550: @*/
    1551: PetscErrorCode PETSC_DLLEXPORT PetscOptionsLeft(void)
    1552: {
    1554:   PetscInt       i;

    1557:   for (i=0; i<options->N; i++) {
    1558:     if (!options->used[i]) {
    1559:       if (options->values[i]) {
    1560:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
    1561:       } else {
    1562:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
    1563:       }
    1564:     }
    1565:   }
    1566:   return(0);
    1567: }

    1569: /*
    1570:     PetscOptionsCreate - Creates the empty options database.

    1572: */
    1575: PetscErrorCode PETSC_DLLEXPORT PetscOptionsCreate(void)
    1576: {

    1580:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
    1581:   PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
    1582:   options->namegiven = PETSC_FALSE;
    1583:   options->N         = 0;
    1584:   options->Naliases  = 0;
    1585:   return(0);
    1586: }