Actual source code: aoptions.c

petsc-dev 2014-08-27
Report Typos and Errors
  2: /*
  3:    Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
  4:    GUI code to display the options and get values from the users.

  6: */

  8: #include <petsc-private/petscimpl.h>        /*I  "petscsys.h"   I*/
  9: #include <petscviewer.h>

 11: #define ManSection(str) ((str) ? (str) : "None")

 13: /*
 14:     Keep a linked list of options that have been posted and we are waiting for
 15:    user selection. See the manual page for PetscOptionsBegin()

 17:     Eventually we'll attach this beast to a MPI_Comm
 18: */
 19: PetscOptionsObjectType PetscOptionsObject;
 20: PetscInt               PetscOptionsPublishCount = 0;

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

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

 36:   PetscFree(PetscOptionsObject.prefix);
 37:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
 38:   PetscFree(PetscOptionsObject.title);
 39:   PetscStrallocpy(title,&PetscOptionsObject.title);

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

 52: /*
 53:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 54: */
 55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
 56: {
 58:   char           title[256];
 59:   PetscBool      flg;

 63:   PetscOptionsObject.object         = obj;
 64:   PetscOptionsObject.alreadyprinted = obj->optionsprinted;

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

 76: /*
 77:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 78: */
 81: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
 82: {
 83:   int          ierr;
 84:   PetscOptions next;
 85:   PetscBool    valid;

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

 91:   PetscNew(amsopt);
 92:   (*amsopt)->next = 0;
 93:   (*amsopt)->set  = PETSC_FALSE;
 94:   (*amsopt)->type = t;
 95:   (*amsopt)->data = 0;

 97:   PetscStrallocpy(text,&(*amsopt)->text);
 98:   PetscStrallocpy(opt,&(*amsopt)->option);
 99:   PetscStrallocpy(man,&(*amsopt)->man);

101:   if (!PetscOptionsObject.next) PetscOptionsObject.next = *amsopt;
102:   else {
103:     next = PetscOptionsObject.next;
104:     while (next->next) next = next->next;
105:     next->next = *amsopt;
106:   }
107:   return(0);
108: }

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

115:     Collective on MPI_Comm

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

122:     Bugs:
123: .   Assumes process 0 of the given communicator has access to stdin

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

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

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

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


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

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

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

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

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

190: */
191: PetscErrorCode PetscOptionsGetFromTextInput()
192: {
194:   PetscOptions   next = PetscOptionsObject.next;
195:   char           str[512];
196:   PetscBool      bid;
197:   PetscReal      ir,*valr;
198:   PetscInt       *vald;
199:   size_t         i;

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

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

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

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

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

363: #if defined(PETSC_HAVE_SAWS)
364: #include <petscviewersaws.h>

366: static int count = 0;

370: PetscErrorCode PetscOptionsSAWsDestroy(void)
371: {
373:   return(0);
374: }

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

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


387: */
388: PetscErrorCode PetscOptionsSAWsInput()
389: {
391:   PetscOptions   next     = PetscOptionsObject.next;
392:   static int     mancount = 0;
393:   char           options[16];
394:   PetscBool      changedmethod = PETSC_FALSE;
395:   char           manname[16],textname[16];
396:   char           dir[1024];

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

401:   PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* SAWs will change this, so cannot pass prefix directly */

403:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
404:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.title,1,SAWs_READ,SAWs_STRING));
405:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
406:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject.pprefix,1,SAWs_READ,SAWs_STRING));
407:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));

409:   while (next) {
410:     sprintf(manname,"_man_%d",mancount);
411:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
412:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
413:     sprintf(textname,"_text_%d",mancount++);
414:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
415:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

417:     switch (next->type) {
418:     case OPTION_HEAD:
419:       break;
420:     case OPTION_INT_ARRAY:
421:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
422:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_INT));
423:       break;
424:     case OPTION_REAL_ARRAY:
425:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
426:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_DOUBLE));
427:       break;
428:     case OPTION_INT:
429:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
430:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_INT));
431:       break;
432:     case OPTION_REAL:
433:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
434:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_DOUBLE));
435:       break;
436:     case OPTION_BOOL:
437:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
438:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,1,SAWs_WRITE,SAWs_BOOLEAN));
439:       break;
440:     case OPTION_BOOL_ARRAY:
441:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
442:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_BOOLEAN));
443:       break;
444:     case OPTION_STRING:
445:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
446:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
447:       break;
448:     case OPTION_STRING_ARRAY:
449:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
450:       PetscStackCallSAWs(SAWs_Register,(dir,next->data,next->arraylength,SAWs_WRITE,SAWs_STRING));
451:       break;
452:     case OPTION_FLIST:
453:       {
454:       PetscInt ntext;
455:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
456:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
457:       PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
458:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
459:       }
460:       break;
461:     case OPTION_ELIST:
462:       {
463:       PetscInt ntext = next->nlist;
464:       PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
465:       PetscStackCallSAWs(SAWs_Register,(dir,&next->data,1,SAWs_WRITE,SAWs_STRING));
466:       PetscMalloc((ntext+1)*sizeof(char),&next->edata);
467:       PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
468:       PetscStackCallSAWs(SAWs_Set_Legal_Variable_Values,(dir,ntext,next->edata));
469:       }
470:       break;
471:     default:
472:       break;
473:     }
474:     next = next->next;
475:   }

477:   /* wait until accessor has unlocked the memory */
478:   PetscSAWsBlock();

480:   /* determine if any values have been set in GUI */
481:   next = PetscOptionsObject.next;
482:   while (next) {
483:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
484:     PetscStackCallSAWs(SAWs_Selected,(dir,&next->set));
485:     next = next->next;
486:   }

488:   /* reset counter to -2; this updates the screen with the new options for the selected method */
489:   if (changedmethod) PetscOptionsPublishCount = -2;

491:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
492:   return(0);
493: }
494: #endif

498: PetscErrorCode PetscOptionsEnd_Private(void)
499: {
501:   PetscOptions   last;
502:   char           option[256],value[1024],tmp[32];
503:   size_t         j;

506:   if (PetscOptionsObject.next) {
507:     if (!PetscOptionsPublishCount) {
508: #if defined(PETSC_HAVE_SAWS)
509:       PetscOptionsSAWsInput();
510: #else
511:       PetscOptionsGetFromTextInput();
512: #endif
513:     }
514:   }

516:   PetscFree(PetscOptionsObject.title);
517:   PetscFree(PetscOptionsObject.prefix);

519:   /* reset counter to -2; this updates the screen with the new options for the selected method */
520:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
521:   /* reset alreadyprinted flag */
522:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;
523:   if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
524:   PetscOptionsObject.object = NULL;

526:   while (PetscOptionsObject.next) {
527:     if (PetscOptionsObject.next->set) {
528:       if (PetscOptionsObject.prefix) {
529:         PetscStrcpy(option,"-");
530:         PetscStrcat(option,PetscOptionsObject.prefix);
531:         PetscStrcat(option,PetscOptionsObject.next->option+1);
532:       } else {
533:         PetscStrcpy(option,PetscOptionsObject.next->option);
534:       }

536:       switch (PetscOptionsObject.next->type) {
537:       case OPTION_HEAD:
538:         break;
539:       case OPTION_INT_ARRAY:
540:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
541:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
542:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
543:           PetscStrcat(value,",");
544:           PetscStrcat(value,tmp);
545:         }
546:         break;
547:       case OPTION_INT:
548:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
549:         break;
550:       case OPTION_REAL:
551:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
552:         break;
553:       case OPTION_REAL_ARRAY:
554:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
555:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
556:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
557:           PetscStrcat(value,",");
558:           PetscStrcat(value,tmp);
559:         }
560:         break;
561:       case OPTION_BOOL:
562:         sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
563:         break;
564:       case OPTION_BOOL_ARRAY:
565:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
566:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
567:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
568:           PetscStrcat(value,",");
569:           PetscStrcat(value,tmp);
570:         }
571:         break;
572:       case OPTION_FLIST:
573:       case OPTION_ELIST:
574:         PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
575:         break;
576:       case OPTION_STRING:
577:         PetscStrcpy(value,(char*)PetscOptionsObject.next->data);
578:         break;
579:       case OPTION_STRING_ARRAY:
580:         sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
581:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
582:           sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
583:           PetscStrcat(value,",");
584:           PetscStrcat(value,tmp);
585:         }
586:         break;
587:       }
588:       PetscOptionsSetValue(option,value);
589:     }
590:     PetscFree(PetscOptionsObject.next->text);
591:     PetscFree(PetscOptionsObject.next->option);
592:     PetscFree(PetscOptionsObject.next->man);
593:     PetscFree(PetscOptionsObject.next->edata);

595:     if ((PetscOptionsObject.next->type == OPTION_STRING) || (PetscOptionsObject.next->type == OPTION_FLIST) || (PetscOptionsObject.next->type == OPTION_ELIST)){
596:       /* must use system free since SAWs may have allocated it */
597:       free(PetscOptionsObject.next->data);
598:     } else {
599:       PetscFree(PetscOptionsObject.next->data);
600:     }

602:     last                    = PetscOptionsObject.next;
603:     PetscOptionsObject.next = PetscOptionsObject.next->next;
604:     PetscFree(last);
605:   }
606:   PetscOptionsObject.next = 0;
607:   return(0);
608: }

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

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

617:    Input Parameters:
618: +  opt - option name
619: .  text - short string that describes the option
620: .  man - manual page with additional information on option
621: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
622: -  defaultv - the default (current) value

624:    Output Parameter:
625: +  value - the  value to return
626: -  set - PETSC_TRUE if found, else PETSC_FALSE

628:    Level: beginner

630:    Concepts: options database

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

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

636: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
637:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
638:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
639:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
640:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
641:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
642:           PetscOptionsFList(), PetscOptionsEList()
643: @*/
644: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool  *set)
645: {
647:   PetscInt       ntext = 0;
648:   PetscInt       tval;
649:   PetscBool      tflg;

652:   while (list[ntext++]) {
653:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
654:   }
655:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
656:   ntext -= 3;
657:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
658:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
659:   if (tflg) *value = (PetscEnum)tval;
660:   if (set)  *set   = tflg;
661:   return(0);
662: }

664: /* -------------------------------------------------------------------------------------------------------------*/
667: /*@C
668:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

672:    Input Parameters:
673: +  opt - option name
674: .  text - short string that describes the option
675: .  man - manual page with additional information on option
676: -  defaultv - the default (current) value, if the user does not provide a value this is returned in value

678:    Output Parameter:
679: +  value - the integer value to return
680: -  flg - PETSC_TRUE if found, else PETSC_FALSE

682:    Level: beginner

684:    Concepts: options database^has int

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

688: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
689:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
690:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
691:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
692:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
693:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
694:           PetscOptionsFList(), PetscOptionsEList()
695: @*/
696: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool  *set)
697: {
699:   PetscOptions   amsopt;

702:   if (!PetscOptionsPublishCount) {
703:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
704:     PetscMalloc(sizeof(PetscInt),&amsopt->data);

706:     *(PetscInt*)amsopt->data = defaultv;
707:   }
708:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
709:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
710:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
711:   }
712:   return(0);
713: }

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

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

722:    Input Parameters:
723: +  opt - option name
724: .  text - short string that describes the option
725: .  man - manual page with additional information on option
726: .  defaultv - the default (current) value, if the user does not provide a value this is returned in value
727: -  len - length of the result string including null terminator

729:    Output Parameter:
730: +  value - the value to return
731: -  flg - PETSC_TRUE if found, else PETSC_FALSE

733:    Level: beginner

735:    Concepts: options database^has int

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

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

741: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
742:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
743:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
744:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
745:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
746:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
747:           PetscOptionsFList(), PetscOptionsEList()
748: @*/
749: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool  *set)
750: {
752:   PetscOptions   amsopt;

755:   if (!PetscOptionsPublishCount) {
756:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
757:     /* must use system malloc since SAWs may free this */
758:     PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
759:   }
760:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
761:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
762:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
763:   }
764:   return(0);
765: }

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

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

774:    Input Parameters:
775: +  opt - option name
776: .  text - short string that describes the option
777: .  man - manual page with additional information on option
778: -  defaultv - the default (current) value, if the user does not provide a value this is returned in value

780:    Output Parameter:
781: +  value - the value to return
782: -  flg - PETSC_TRUE if found, else PETSC_FALSE

784:    Level: beginner

786:    Concepts: options database^has int

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

790: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
791:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
792:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
793:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
794:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
795:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
796:           PetscOptionsFList(), PetscOptionsEList()
797: @*/
798: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool  *set)
799: {
801:   PetscOptions   amsopt;

804:   if (!PetscOptionsPublishCount) {
805:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
806:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

808:     *(PetscReal*)amsopt->data = defaultv;
809:   }
810:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
811:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
812:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%g>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,(double)defaultv,text,ManSection(man));
813:   }
814:   return(0);
815: }

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

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

824:    Input Parameters:
825: +  opt - option name
826: .  text - short string that describes the option
827: .  man - manual page with additional information on option
828: -  defaultv - the default (current) value, if the user does not provide a value this is returned in value

830:    Output Parameter:
831: +  value - the value to return
832: -  flg - PETSC_TRUE if found, else PETSC_FALSE

834:    Level: beginner

836:    Concepts: options database^has int

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

840: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
841:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
842:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
843:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
844:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
845:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
846:           PetscOptionsFList(), PetscOptionsEList()
847: @*/
848: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool  *set)
849: {

853: #if !defined(PETSC_USE_COMPLEX)
854:   PetscOptionsReal(opt,text,man,defaultv,value,set);
855: #else
856:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
857: #endif
858:   return(0);
859: }

863: /*@C
864:    PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
865:                       its value is set to false.

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

869:    Input Parameters:
870: +  opt - option name
871: .  text - short string that describes the option
872: -  man - manual page with additional information on option

874:    Output Parameter:
875: .  flg - PETSC_TRUE if found, else PETSC_FALSE

877:    Level: beginner

879:    Concepts: options database^has int

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

883: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
884:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
885:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
886:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
887:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
888:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
889:           PetscOptionsFList(), PetscOptionsEList()
890: @*/
891: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)
892: {
894:   PetscOptions   amsopt;

897:   if (!PetscOptionsPublishCount) {
898:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
899:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

901:     *(PetscBool*)amsopt->data = PETSC_FALSE;
902:   }
903:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
904:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
905:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
906:   }
907:   return(0);
908: }

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

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

917:    Input Parameters:
918: +  opt - option name
919: .  text - short string that describes the option
920: .  man - manual page with additional information on option
921: .  list - the possible choices
922: .  defaultv - the default (current) value, if the user does not provide a value this is returned in value
923: -  len - the length of the character array value

925:    Output Parameter:
926: +  value - the value to return
927: -  set - PETSC_TRUE if found, else PETSC_FALSE

929:    Level: intermediate

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

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

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

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

940:    Concepts: options database^list

942: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
943:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
944:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
945:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
946:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
947:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
948: @*/
949: PetscErrorCode  PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool  *set)
950: {
952:   PetscOptions   amsopt;

955:   if (!PetscOptionsPublishCount) {
956:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_FLIST,&amsopt);
957:     /* must use system malloc since SAWs may free this */
958:     PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
959:     amsopt->flist = list;
960:   }
961:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
962:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
963:     PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
964:   }
965:   return(0);
966: }

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

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

975:    Input Parameters:
976: +  opt - option name
977: .  ltext - short string that describes the option
978: .  man - manual page with additional information on option
979: .  list - the possible choices (one of these must be selected, anything else is invalid)
980: .  ntext - number of choices
981: -  defaultv - the default (current) value, if the user does not provide a value the index of defaultv is returned

983:    Output Parameter:
984: +  value - the index of the value to return
985: -  set - PETSC_TRUE if found, else PETSC_FALSE

987:    Level: intermediate

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

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

993:    Concepts: options database^list

995: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
996:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
997:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
998:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
999:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1000:           PetscOptionsFList(), PetscOptionsEnum()
1001: @*/
1002: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool  *set)
1003: {
1005:   PetscInt       i;
1006:   PetscOptions   amsopt;

1009:   if (!PetscOptionsPublishCount) {
1010:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
1011:     /* must use system malloc since SAWs may free this */
1012:     PetscStrdup(defaultv ? defaultv : "",(char**)&amsopt->data);
1013:     amsopt->list  = list;
1014:     amsopt->nlist = ntext;
1015:   }
1016:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
1017:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1018:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
1019:     for (i=0; i<ntext; i++) {
1020:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
1021:     }
1022:     (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
1023:   }
1024:   return(0);
1025: }

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

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

1035:    Input Parameters:
1036: +  opt - option name
1037: .  text - short string that describes the option
1038: -  man - manual page with additional information on option

1040:    Output Parameter:
1041: .  flg - whether that option was set or not

1043:    Level: intermediate

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

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

1049:     Concepts: options database^logical group

1051: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1052:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1053:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1054:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1055:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1056:           PetscOptionsFList(), PetscOptionsEList()
1057: @*/
1058: PetscErrorCode  PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)
1059: {
1061:   PetscOptions   amsopt;

1064:   if (!PetscOptionsPublishCount) {
1065:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1066:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1068:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1069:   }
1070:   *flg = PETSC_FALSE;
1071:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1072:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1073:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
1074:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1075:   }
1076:   return(0);
1077: }

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

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

1087:    Input Parameters:
1088: +  opt - option name
1089: .  text - short string that describes the option
1090: -  man - manual page with additional information on option

1092:    Output Parameter:
1093: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1095:    Level: intermediate

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

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

1101:     Concepts: options database^logical group

1103: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1104:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1105:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1106:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1107:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1108:           PetscOptionsFList(), PetscOptionsEList()
1109: @*/
1110: PetscErrorCode  PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)
1111: {
1113:   PetscOptions   amsopt;

1116:   if (!PetscOptionsPublishCount) {
1117:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1118:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1120:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1121:   }
1122:   *flg = PETSC_FALSE;
1123:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1124:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1125:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1126:   }
1127:   return(0);
1128: }

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

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

1138:    Input Parameters:
1139: +  opt - option name
1140: .  text - short string that describes the option
1141: -  man - manual page with additional information on option

1143:    Output Parameter:
1144: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1146:    Level: intermediate

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

1150:    Must follow a PetscOptionsBoolGroupBegin()

1152:     Concepts: options database^logical group

1154: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1155:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1156:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1157:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1158:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1159:           PetscOptionsFList(), PetscOptionsEList()
1160: @*/
1161: PetscErrorCode  PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)
1162: {
1164:   PetscOptions   amsopt;

1167:   if (!PetscOptionsPublishCount) {
1168:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1169:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1171:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1172:   }
1173:   *flg = PETSC_FALSE;
1174:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1175:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1176:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1177:   }
1178:   return(0);
1179: }

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

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

1188:    Input Parameters:
1189: +  opt - option name
1190: .  text - short string that describes the option
1191: .  man - manual page with additional information on option
1192: -  deflt - the default value, if the user does not set a value then this value is returned in flg

1194:    Output Parameter:
1195: .  flg - PETSC_TRUE or PETSC_FALSE
1196: .  set - PETSC_TRUE if found, else PETSC_FALSE

1198:    Level: beginner

1200:    Concepts: options database^logical

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

1204: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1205:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1206:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1207:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1208:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1209:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1210:           PetscOptionsFList(), PetscOptionsEList()
1211: @*/
1212: PetscErrorCode  PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool  *flg,PetscBool  *set)
1213: {
1215:   PetscBool      iset;
1216:   PetscOptions   amsopt;

1219:   if (!PetscOptionsPublishCount) {
1220:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1221:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1223:     *(PetscBool*)amsopt->data = deflt;
1224:   }
1225:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1226:   if (!iset) {
1227:     if (flg) *flg = deflt;
1228:   }
1229:   if (set) *set = iset;
1230:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1231:     const char *v = PetscBools[deflt];
1232:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1233:   }
1234:   return(0);
1235: }

1239: /*@C
1240:    PetscOptionsRealArray - Gets an array of double values for a particular
1241:    option in the database. The values must be separated with commas with
1242:    no intervening spaces.

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

1246:    Input Parameters:
1247: +  opt - the option one is seeking
1248: .  text - short string describing option
1249: .  man - manual page for option
1250: -  nmax - maximum number of values

1252:    Output Parameter:
1253: +  value - location to copy values
1254: .  nmax - actual number of values found
1255: -  set - PETSC_TRUE if found, else PETSC_FALSE

1257:    Level: beginner

1259:    Notes:
1260:    The user should pass in an array of doubles

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

1264:    Concepts: options database^array of strings

1266: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1267:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1268:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1269:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1270:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1271:           PetscOptionsFList(), PetscOptionsEList()
1272: @*/
1273: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1274: {
1276:   PetscInt       i;
1277:   PetscOptions   amsopt;

1280:   if (!PetscOptionsPublishCount) {
1281:     PetscReal *vals;

1283:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1284:     PetscMalloc1((*n),(PetscReal**)&amsopt->data);
1285:     vals = (PetscReal*)amsopt->data;
1286:     for (i=0; i<*n; i++) vals[i] = value[i];
1287:     amsopt->arraylength = *n;
1288:   }
1289:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1290:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1291:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%g",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,(double)value[0]);
1292:     for (i=1; i<*n; i++) {
1293:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%g",(double)value[i]);
1294:     }
1295:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1296:   }
1297:   return(0);
1298: }


1303: /*@C
1304:    PetscOptionsIntArray - Gets an array of integers for a particular
1305:    option in the database.

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

1309:    Input Parameters:
1310: +  opt - the option one is seeking
1311: .  text - short string describing option
1312: .  man - manual page for option
1313: -  n - maximum number of values

1315:    Output Parameter:
1316: +  value - location to copy values
1317: .  n - actual number of values found
1318: -  set - PETSC_TRUE if found, else PETSC_FALSE

1320:    Level: beginner

1322:    Notes:
1323:    The array can be passed as
1324:    a comma seperated list:                                 0,1,2,3,4,5,6,7
1325:    a range (start-end+1):                                  0-8
1326:    a range with given increment (start-end+1:inc):         0-7:2
1327:    a combination of values and ranges seperated by commas: 0,1-8,8-15:2

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

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

1333:    Concepts: options database^array of ints

1335: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1336:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1337:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1338:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1339:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1340:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1341: @*/
1342: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1343: {
1345:   PetscInt       i;
1346:   PetscOptions   amsopt;

1349:   if (!PetscOptionsPublishCount) {
1350:     PetscInt *vals;

1352:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1353:     PetscMalloc1((*n),(PetscInt**)&amsopt->data);
1354:     vals = (PetscInt*)amsopt->data;
1355:     for (i=0; i<*n; i++) vals[i] = value[i];
1356:     amsopt->arraylength = *n;
1357:   }
1358:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1359:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1360:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1361:     for (i=1; i<*n; i++) {
1362:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1363:     }
1364:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1365:   }
1366:   return(0);
1367: }

1371: /*@C
1372:    PetscOptionsStringArray - Gets an array of string values for a particular
1373:    option in the database. The values must be separated with commas with
1374:    no intervening spaces.

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

1378:    Input Parameters:
1379: +  opt - the option one is seeking
1380: .  text - short string describing option
1381: .  man - manual page for option
1382: -  nmax - maximum number of strings

1384:    Output Parameter:
1385: +  value - location to copy strings
1386: .  nmax - actual number of strings found
1387: -  set - PETSC_TRUE if found, else PETSC_FALSE

1389:    Level: beginner

1391:    Notes:
1392:    The user should pass in an array of pointers to char, to hold all the
1393:    strings returned by this function.

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

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

1400:    Concepts: options database^array of strings

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

1415:   if (!PetscOptionsPublishCount) {
1416:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1417:     PetscMalloc1((*nmax),(char**)&amsopt->data);

1419:     amsopt->arraylength = *nmax;
1420:   }
1421:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1422:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1423:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1424:   }
1425:   return(0);
1426: }

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

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

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

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

1448:    Level: beginner

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

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

1455:    Concepts: options database^array of strings

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

1471:   if (!PetscOptionsPublishCount) {
1472:     PetscBool *vals;

1474:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1475:     PetscMalloc1((*n),(PetscBool**)&amsopt->data);
1476:     vals = (PetscBool*)amsopt->data;
1477:     for (i=0; i<*n; i++) vals[i] = value[i];
1478:     amsopt->arraylength = *n;
1479:   }
1480:   PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1481:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1482:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1483:     for (i=1; i<*n; i++) {
1484:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1485:     }
1486:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1487:   }
1488:   return(0);
1489: }

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

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

1498:    Input Parameters:
1499: +  opt - option name
1500: .  text - short string that describes the option
1501: -  man - manual page with additional information on option

1503:    Output Parameter:
1504: +  viewer - the viewer
1505: -  set - PETSC_TRUE if found, else PETSC_FALSE

1507:    Level: beginner

1509:    Concepts: options database^has int

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

1513:    See PetscOptionsGetVieweer() for the format of the supplied viewer and its options

1515: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1516:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1517:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1518:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1519:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1520:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1521:           PetscOptionsFList(), PetscOptionsEList()
1522: @*/
1523: PetscErrorCode  PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1524: {
1526:   PetscOptions   amsopt;

1529:   if (!PetscOptionsPublishCount) {
1530:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
1531:     /* must use system malloc since SAWs may free this */
1532:     PetscStrdup("",(char**)&amsopt->data);
1533:   }
1534:   PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
1535:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1536:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
1537:   }
1538:   return(0);
1539: }


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

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

1550:    Input Parameter:
1551: .   head - the heading text


1554:    Level: intermediate

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

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

1560:    Concepts: options database^subheading

1562: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1563:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1564:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1565:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1566:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1567:           PetscOptionsFList(), PetscOptionsEList()
1568: @*/
1569: PetscErrorCode  PetscOptionsHead(const char head[])
1570: {

1574:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1575:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1576:   }
1577:   return(0);
1578: }