Actual source code: aoptions.c

petsc-dev 2014-02-02
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: }

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

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


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

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

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

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

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

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

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

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

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

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

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

361: #if defined(PETSC_HAVE_SAWS)
362: #include <petscviewersaws.h>

364: static int count = 0;

368: PetscErrorCode PetscOptionsSAWsDestroy(void)
369: {
371:   return(0);
372: }

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

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


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

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

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

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

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

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

475:   /* wait until accessor has unlocked the memory */
476:   PetscSAWsBlock();

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

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

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

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

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

514:   PetscFree(PetscOptionsObject.title);
515:   PetscFree(PetscOptionsObject.prefix);

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

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

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

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

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

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

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

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

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

626:    Level: beginner

628:    Concepts: options database

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

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

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

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

662: /* -------------------------------------------------------------------------------------------------------------*/
665: /*@C
666:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

670:    Input Parameters:
671: +  opt - option name
672: .  text - short string that describes the option
673: .  man - manual page with additional information on option
674: -  defaultv - the default (current) value

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

680:    Level: beginner

682:    Concepts: options database^has int

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

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

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

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

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

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

720:    Input Parameters:
721: +  opt - option name
722: .  text - short string that describes the option
723: .  man - manual page with additional information on option
724: .  defaultv - the default (current) value
725: -  len - length of the result string including null terminator

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

731:    Level: beginner

733:    Concepts: options database^has int

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

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

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

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

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

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

772:    Input Parameters:
773: +  opt - option name
774: .  text - short string that describes the option
775: .  man - manual page with additional information on option
776: -  defaultv - the default (current) value

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

782:    Level: beginner

784:    Concepts: options database^has int

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

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

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

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

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

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

822:    Input Parameters:
823: +  opt - option name
824: .  text - short string that describes the option
825: .  man - manual page with additional information on option
826: -  defaultv - the default (current) value

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

832:    Level: beginner

834:    Concepts: options database^has int

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

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

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

861: /*@C
862:    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
863:                       its value is set to false.

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

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

872:    Output Parameter:
873: .  flg - PETSC_TRUE if found, else PETSC_FALSE

875:    Level: beginner

877:    Concepts: options database^has int

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

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

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

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

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

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

915:    Input Parameters:
916: +  opt - option name
917: .  text - short string that describes the option
918: .  man - manual page with additional information on option
919: .  list - the possible choices
920: .  defaultv - the default (current) value
921: -  len - the length of the character array value

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

927:    Level: intermediate

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

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

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

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

938:    Concepts: options database^list

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

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

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

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

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

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

985:    Level: intermediate

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

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

991:    Concepts: options database^list

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

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

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

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

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

1038:    Output Parameter:
1039: .  flg - whether that option was set or not

1041:    Level: intermediate

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

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

1047:     Concepts: options database^logical group

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

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

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

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

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

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

1090:    Output Parameter:
1091: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1093:    Level: intermediate

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

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

1099:     Concepts: options database^logical group

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

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

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

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

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

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

1141:    Output Parameter:
1142: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1144:    Level: intermediate

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

1148:    Must follow a PetscOptionsBoolGroupBegin()

1150:     Concepts: options database^logical group

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

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

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

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

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

1186:    Input Parameters:
1187: +  opt - option name
1188: .  text - short string that describes the option
1189: -  man - manual page with additional information on option

1191:    Output Parameter:
1192: .  flg - PETSC_TRUE or PETSC_FALSE
1193: .  set - PETSC_TRUE if found, else PETSC_FALSE

1195:    Level: beginner

1197:    Concepts: options database^logical

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

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

1216:   if (!PetscOptionsPublishCount) {
1217:     PetscOptionsCreate_Private(opt,text,man,OPTION_BOOL,&amsopt);
1218:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

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

1249:    Output Parameter:
1250: +  value - location to copy values
1251: .  nmax - actual number of values found
1252: -  set - PETSC_TRUE if found, else PETSC_FALSE

1254:    Level: beginner

1256:    Notes:
1257:    The user should pass in an array of doubles

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

1261:    Concepts: options database^array of strings

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

1277:   if (!PetscOptionsPublishCount) {
1278:     PetscReal *vals;

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


1300: /*@C
1301:    PetscOptionsIntArray - Gets an array of integers for a particular
1302:    option in the database.

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

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

1312:    Output Parameter:
1313: +  value - location to copy values
1314: .  n - actual number of values found
1315: -  set - PETSC_TRUE if found, else PETSC_FALSE

1317:    Level: beginner

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

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

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

1330:    Concepts: options database^array of ints

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

1346:   if (!PetscOptionsPublishCount) {
1347:     PetscInt *vals;

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

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

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

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

1381:    Output Parameter:
1382: +  value - location to copy strings
1383: .  nmax - actual number of strings found
1384: -  set - PETSC_TRUE if found, else PETSC_FALSE

1386:    Level: beginner

1388:    Notes:
1389:    The user should pass in an array of pointers to char, to hold all the
1390:    strings returned by this function.

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

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

1397:    Concepts: options database^array of strings

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

1412:   if (!PetscOptionsPublishCount) {
1413:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1414:     PetscMalloc1((*nmax),(char**)&amsopt->data);

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

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

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

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

1440:    Output Parameter:
1441: +  value - location to copy values
1442: .  nmax - actual number of values found
1443: -  set - PETSC_TRUE if found, else PETSC_FALSE

1445:    Level: beginner

1447:    Notes:
1448:    The user should pass in an array of doubles

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

1452:    Concepts: options database^array of strings

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

1468:   if (!PetscOptionsPublishCount) {
1469:     PetscBool *vals;

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

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

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

1495:    Input Parameters:
1496: +  opt - option name
1497: .  text - short string that describes the option
1498: -  man - manual page with additional information on option

1500:    Output Parameter:
1501: +  viewer - the viewer
1502: -  set - PETSC_TRUE if found, else PETSC_FALSE

1504:    Level: beginner

1506:    Concepts: options database^has int

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

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

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

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


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

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

1547:    Input Parameter:
1548: .   head - the heading text


1551:    Level: intermediate

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

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

1557:    Concepts: options database^subheading

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

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