Actual source code: aoptions.c

petsc-3.4.4 2014-03-13
  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(struct _n_PetscOptions,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:     PetscOptionsGetFromTextInput - Presents all the PETSc Options processed by the program so the user may change them at runtime

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

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

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

164: */
165: PetscErrorCode PetscOptionsGetFromTextInput()
166: {
168:   PetscOptions   next = PetscOptionsObject.next;
169:   char           str[512];
170:   PetscInt       id;
171:   PetscReal      ir,*valr;
172:   PetscInt       *vald;
173:   size_t         i;

175:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
176:   while (next) {
177:     switch (next->type) {
178:     case OPTION_HEAD:
179:       break;
180:     case OPTION_INT_ARRAY:
181:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
182:       vald = (PetscInt*) next->data;
183:       for (i=0; i<next->arraylength; i++) {
184:         PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
185:         if (i < next->arraylength-1) {
186:           PetscPrintf(PETSC_COMM_WORLD,",");
187:         }
188:       }
189:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
190:       PetscScanString(PETSC_COMM_WORLD,512,str);
191:       if (str[0]) {
192:         PetscToken token;
193:         PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
194:         size_t     len;
195:         char       *value;
196:         PetscBool  foundrange;

198:         next->set = PETSC_TRUE;
199:         value     = str;
200:         PetscTokenCreate(value,',',&token);
201:         PetscTokenFind(token,&value);
202:         while (n < nmax) {
203:           if (!value) break;

205:           /* look for form  d-D where d and D are integers */
206:           foundrange = PETSC_FALSE;
207:           PetscStrlen(value,&len);
208:           if (value[0] == '-') i=2;
209:           else i=1;
210:           for (;i<len; i++) {
211:             if (value[i] == '-') {
212:               if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
213:               value[i] = 0;
214:               PetscOptionsStringToInt(value,&start);
215:               PetscOptionsStringToInt(value+i+1,&end);
216:               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);
217:               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);
218:               for (; start<end; start++) {
219:                 *dvalue = start; dvalue++;n++;
220:               }
221:               foundrange = PETSC_TRUE;
222:               break;
223:             }
224:           }
225:           if (!foundrange) {
226:             PetscOptionsStringToInt(value,dvalue);
227:             dvalue++;
228:             n++;
229:           }
230:           PetscTokenFind(token,&value);
231:         }
232:         PetscTokenDestroy(&token);
233:       }
234:       break;
235:     case OPTION_REAL_ARRAY:
236:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1);
237:       valr = (PetscReal*) next->data;
238:       for (i=0; i<next->arraylength; i++) {
239:         PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
240:         if (i < next->arraylength-1) {
241:           PetscPrintf(PETSC_COMM_WORLD,",");
242:         }
243:       }
244:       PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
245:       PetscScanString(PETSC_COMM_WORLD,512,str);
246:       if (str[0]) {
247:         PetscToken token;
248:         PetscInt   n = 0,nmax = next->arraylength;
249:         PetscReal  *dvalue = (PetscReal*)next->data;
250:         char       *value;

252:         next->set = PETSC_TRUE;
253:         value     = str;
254:         PetscTokenCreate(value,',',&token);
255:         PetscTokenFind(token,&value);
256:         while (n < nmax) {
257:           if (!value) break;
258:           PetscOptionsStringToReal(value,dvalue);
259:           dvalue++;
260:           n++;
261:           PetscTokenFind(token,&value);
262:         }
263:         PetscTokenDestroy(&token);
264:       }
265:       break;
266:     case OPTION_INT:
267:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(int*)next->data,next->text,next->man);
268:       PetscScanString(PETSC_COMM_WORLD,512,str);
269:       if (str[0]) {
270: #if defined(PETSC_USE_64BIT_INDICES)
271:         sscanf(str,"%lld",&id);
272: #else
273:         sscanf(str,"%d",&id);
274: #endif
275:         next->set = PETSC_TRUE;

277:         *((PetscInt*)next->data) = id;
278:       }
279:       break;
280:     case OPTION_REAL:
281:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
282:       PetscScanString(PETSC_COMM_WORLD,512,str);
283:       if (str[0]) {
284: #if defined(PETSC_USE_REAL_SINGLE)
285:         sscanf(str,"%e",&ir);
286: #elif defined(PETSC_USE_REAL_DOUBLE)
287:         sscanf(str,"%le",&ir);
288: #elif defined(PETSC_USE_REAL___FLOAT128)
289:         ir = strtoflt128(str,0);
290: #else
291:         SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
292: #endif
293:         next->set                 = PETSC_TRUE;
294:         *((PetscReal*)next->data) = ir;
295:       }
296:       break;
297:     case OPTION_LOGICAL:
298:     case OPTION_STRING:
299:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",next->option+1,(char*)next->data,next->text,next->man);
300:       PetscScanString(PETSC_COMM_WORLD,512,str);
301:       if (str[0]) {
302:         next->set = PETSC_TRUE;

304:         PetscStrcpy((char*)next->data,str);
305:       }
306:       break;
307:     case OPTION_LIST:
308:       PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
309:       PetscScanString(PETSC_COMM_WORLD,512,str);
310:       if (str[0]) {
311:         PetscOptionsObject.changedmethod = PETSC_TRUE;
312:         next->set = PETSC_TRUE;
313:         PetscStrcpy((char*)next->data,str);
314:       }
315:       break;
316:     default:
317:       break;
318:     }
319:     next = next->next;
320:   }
321:   return(0);
322: }

324: #if defined(PETSC_HAVE_AMS)
325: #include <petscviewerams.h>

327: static int count = 0;

331: PetscErrorCode PetscOptionsAMSDestroy(void)
332: {
334:   AMS_Comm       acomm = -1;
335:   AMS_Memory     amem  = -1;
336:   char           options[16];
337:   const char     *string = "Exit";

339:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
340:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
341:   sprintf(options,"Options_%d",count++);
342:   PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
343:   PetscStackCallAMS(AMS_Memory_add_field,(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));

345:   PetscStackCallAMS(AMS_Memory_take_access,(amem));
346:   PetscStackCallAMS(AMS_Memory_publish,(amem));
347:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
348:   /* wait until accessor has unlocked the memory */
349:   PetscStackCallAMS(AMS_Memory_lock,(amem,0));
350:   PetscStackCallAMS(AMS_Memory_take_access,(amem));
351:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
352:   PetscStackCallAMS(AMS_Memory_destroy,(amem));
353:   return(0);
354: }

358: /*
359:     PetscOptionsAMSInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the AMS

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


367: */
368: PetscErrorCode PetscOptionsAMSInput()
369: {
371:   PetscOptions   next     = PetscOptionsObject.next;
372:   static int     mancount = 0;
373:   char           options[16];
374:   AMS_Comm       acomm         = -1;
375:   AMS_Memory     amem          = -1;
376:   PetscBool      changedmethod = PETSC_FALSE;
377:   char           manname[16];

379:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
380:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
381:   sprintf(options,"Options_%d",count++);
382:   PetscStackCallAMS(AMS_Memory_create,(acomm,options,&amem));
383:   PetscStackCallAMS(AMS_Memory_take_access,(amem));

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

387:   PetscStackCallAMS(AMS_Memory_add_field,(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));
388:   /* PetscStackCallAMS(AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF)); */
389:   PetscStackCallAMS(AMS_Memory_add_field,(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));

391:   while (next) {
392:     PetscStackCallAMS(AMS_Memory_add_field,(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
393:      PetscMalloc(sizeof(char*),&next->pman);

395:     *(char**)next->pman = next->man;
396:     sprintf(manname,"man_%d",mancount++);
397:     PetscStackCallAMS(AMS_Memory_add_field,(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF));

399:     switch (next->type) {
400:     case OPTION_HEAD:
401:       break;
402:     case OPTION_INT_ARRAY:
403:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
404:       break;
405:     case OPTION_REAL_ARRAY:
406:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
407:       break;
408:     case OPTION_INT:
409:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
410:       break;
411:     case OPTION_REAL:
412:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
413:       break;
414:     case OPTION_LOGICAL:
415:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
416:       break;
417:     case OPTION_LOGICAL_ARRAY:
418:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
419:       break;
420:     case OPTION_STRING:
421:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
422:       break;
423:     case OPTION_STRING_ARRAY:
424:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
425:       break;
426:     case OPTION_LIST:
427:       {PetscInt ntext;
428:       char      ldefault[128];
429:       PetscStrcpy(ldefault,"DEFAULT:");
430:       PetscStrcat(ldefault,next->text);
431:       PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
432:       PetscFunctionListGet(next->flist,(const char***)&next->edata,&ntext);
433:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
434:       break;}
435:     case OPTION_ELIST:
436:       {PetscInt ntext = next->nlist;
437:       char      ldefault[128];
438:       PetscStrcpy(ldefault,"DEFAULT:");
439:       PetscStrcat(ldefault,next->text);
440:       PetscStackCallAMS(AMS_Memory_add_field,(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
441:       PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
442:       PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
443:       PetscStackCallAMS(AMS_Memory_add_field,(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF));
444:       break;}
445:     default:
446:       break;
447:     }
448:     next = next->next;
449:   }

451:   PetscStackCallAMS(AMS_Memory_publish,(amem));
452:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
453:   /* wait until accessor has unlocked the memory */
454:   PetscStackCallAMS(AMS_Memory_lock,(amem,0));
455:   PetscStackCallAMS(AMS_Memory_take_access,(amem));

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

460:   PetscStackCallAMS(AMS_Memory_grant_access,(amem));
461:   PetscStackCallAMS(AMS_Memory_destroy,(amem));
462:   return(0);
463: }
464: #endif

468: PetscErrorCode PetscOptionsEnd_Private(void)
469: {
471:   PetscOptions   last;
472:   char           option[256],value[1024],tmp[32];
473:   size_t         j;

476:   if (PetscOptionsObject.next) {
477:     if (!PetscOptionsPublishCount) {
478: #if defined(PETSC_HAVE_AMS)
479:       PetscOptionsAMSInput();
480: #else
481:       PetscOptionsGetFromTextInput();
482: #endif
483:     }
484:   }

486:   PetscFree(PetscOptionsObject.title);
487:   PetscFree(PetscOptionsObject.prefix);

489:   /* reset counter to -2; this updates the screen with the new options for the selected method */
490:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
491:   /* reset alreadyprinted flag */
492:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;
493:   if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
494:   PetscOptionsObject.object = NULL;

496:   while (PetscOptionsObject.next) {
497:     if (PetscOptionsObject.next->set) {
498:       if (PetscOptionsObject.prefix) {
499:         PetscStrcpy(option,"-");
500:         PetscStrcat(option,PetscOptionsObject.prefix);
501:         PetscStrcat(option,PetscOptionsObject.next->option+1);
502:       } else {
503:         PetscStrcpy(option,PetscOptionsObject.next->option);
504:       }

506:       switch (PetscOptionsObject.next->type) {
507:       case OPTION_HEAD:
508:         break;
509:       case OPTION_INT_ARRAY:
510:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
511:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
512:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
513:           PetscStrcat(value,",");
514:           PetscStrcat(value,tmp);
515:         }
516:         break;
517:       case OPTION_INT:
518:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
519:         break;
520:       case OPTION_REAL:
521:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
522:         break;
523:       case OPTION_REAL_ARRAY:
524:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
525:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
526:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
527:           PetscStrcat(value,",");
528:           PetscStrcat(value,tmp);
529:         }
530:         break;
531:       case OPTION_LOGICAL:
532:         sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
533:         break;
534:       case OPTION_LOGICAL_ARRAY:
535:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
536:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
537:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
538:           PetscStrcat(value,",");
539:           PetscStrcat(value,tmp);
540:         }
541:         break;
542:       case OPTION_LIST:
543:       case OPTION_ELIST:
544:         PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
545:         break;
546:       case OPTION_STRING:
547:         PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
548:       case OPTION_STRING_ARRAY:
549:         sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
550:         for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
551:           sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
552:           PetscStrcat(value,",");
553:           PetscStrcat(value,tmp);
554:         }
555:         break;
556:       }
557:       PetscOptionsSetValue(option,value);
558:     }
559:     PetscFree(PetscOptionsObject.next->text);
560:     PetscFree(PetscOptionsObject.next->option);
561:     PetscFree(PetscOptionsObject.next->man);
562:     PetscFree(PetscOptionsObject.next->data);
563:     PetscFree(PetscOptionsObject.next->edata);

565:     last                    = PetscOptionsObject.next;
566:     PetscOptionsObject.next = PetscOptionsObject.next->next;
567:     PetscFree(last);
568:   }
569:   PetscOptionsObject.next = 0;
570:   return(0);
571: }

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

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

580:    Input Parameters:
581: +  opt - option name
582: .  text - short string that describes the option
583: .  man - manual page with additional information on option
584: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
585: -  defaultv - the default (current) value

587:    Output Parameter:
588: +  value - the  value to return
589: -  set - PETSC_TRUE if found, else PETSC_FALSE

591:    Level: beginner

593:    Concepts: options database

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

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

599: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
600:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
601:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
602:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
603:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
604:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
605:           PetscOptionsList(), PetscOptionsEList()
606: @*/
607: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum defaultv,PetscEnum *value,PetscBool  *set)
608: {
610:   PetscInt       ntext = 0;
611:   PetscInt       tval;
612:   PetscBool      tflg;

615:   while (list[ntext++]) {
616:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
617:   }
618:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
619:   ntext -= 3;
620:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
621:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
622:   if (tflg) *value = (PetscEnum)tval;
623:   if (set)  *set   = tflg;
624:   return(0);
625: }

627: /* -------------------------------------------------------------------------------------------------------------*/
630: /*@C
631:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

635:    Input Parameters:
636: +  opt - option name
637: .  text - short string that describes the option
638: .  man - manual page with additional information on option
639: -  defaultv - the default (current) value

641:    Output Parameter:
642: +  value - the integer value to return
643: -  flg - PETSC_TRUE if found, else PETSC_FALSE

645:    Level: beginner

647:    Concepts: options database^has int

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

651: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
652:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
653:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
654:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
655:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
656:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
657:           PetscOptionsList(), PetscOptionsEList()
658: @*/
659: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool  *set)
660: {
662:   PetscOptions   amsopt;

665:   if (!PetscOptionsPublishCount) {
666:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
667:     PetscMalloc(sizeof(PetscInt),&amsopt->data);

669:     *(PetscInt*)amsopt->data = defaultv;
670:   }
671:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
672:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
673:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
674:   }
675:   return(0);
676: }

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

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

685:    Input Parameters:
686: +  opt - option name
687: .  text - short string that describes the option
688: .  man - manual page with additional information on option
689: .  defaultv - the default (current) value
690: -  len - length of the result string including null terminator

692:    Output Parameter:
693: +  value - the value to return
694: -  flg - PETSC_TRUE if found, else PETSC_FALSE

696:    Level: beginner

698:    Concepts: options database^has int

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

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

704: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
705:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
706:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
707:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
708:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
709:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
710:           PetscOptionsList(), PetscOptionsEList()
711: @*/
712: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool  *set)
713: {
715:   PetscOptions   amsopt;

718:   if (!PetscOptionsPublishCount) {
719:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
720:     PetscMalloc(sizeof(char*),&amsopt->data);

722:     *(const char**)amsopt->data = defaultv;
723:   }
724:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
725:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
726:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
727:   }
728:   return(0);
729: }

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

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

738:    Input Parameters:
739: +  opt - option name
740: .  text - short string that describes the option
741: .  man - manual page with additional information on option
742: -  defaultv - the default (current) value

744:    Output Parameter:
745: +  value - the value to return
746: -  flg - PETSC_TRUE if found, else PETSC_FALSE

748:    Level: beginner

750:    Concepts: options database^has int

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

754: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
755:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
756:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
757:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
758:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
759:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
760:           PetscOptionsList(), PetscOptionsEList()
761: @*/
762: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool  *set)
763: {
765:   PetscOptions   amsopt;

768:   if (!PetscOptionsPublishCount) {
769:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
770:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

772:     *(PetscReal*)amsopt->data = defaultv;
773:   }
774:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
775:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
776:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,defaultv,text,ManSection(man));
777:   }
778:   return(0);
779: }

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

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

788:    Input Parameters:
789: +  opt - option name
790: .  text - short string that describes the option
791: .  man - manual page with additional information on option
792: -  defaultv - the default (current) value

794:    Output Parameter:
795: +  value - the value to return
796: -  flg - PETSC_TRUE if found, else PETSC_FALSE

798:    Level: beginner

800:    Concepts: options database^has int

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

804: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
805:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
806:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
807:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
808:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
809:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
810:           PetscOptionsList(), PetscOptionsEList()
811: @*/
812: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool  *set)
813: {

817: #if !defined(PETSC_USE_COMPLEX)
818:   PetscOptionsReal(opt,text,man,defaultv,value,set);
819: #else
820:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
821: #endif
822:   return(0);
823: }

827: /*@C
828:    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
829:                       its value is set to false.

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

833:    Input Parameters:
834: +  opt - option name
835: .  text - short string that describes the option
836: -  man - manual page with additional information on option

838:    Output Parameter:
839: .  flg - PETSC_TRUE if found, else PETSC_FALSE

841:    Level: beginner

843:    Concepts: options database^has int

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

847: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
848:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
849:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
850:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
851:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
852:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
853:           PetscOptionsList(), PetscOptionsEList()
854: @*/
855: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)
856: {
858:   PetscOptions   amsopt;

861:   if (!PetscOptionsPublishCount) {
862:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
863:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

865:     *(PetscBool*)amsopt->data = PETSC_FALSE;
866:   }
867:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
868:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
869:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
870:   }
871:   return(0);
872: }

876: /*@C
877:      PetscOptionsList - Puts a list of option values that a single one may be selected from

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

881:    Input Parameters:
882: +  opt - option name
883: .  text - short string that describes the option
884: .  man - manual page with additional information on option
885: .  list - the possible choices
886: .  defaultv - the default (current) value
887: -  len - the length of the character array value

889:    Output Parameter:
890: +  value - the value to return
891: -  set - PETSC_TRUE if found, else PETSC_FALSE

893:    Level: intermediate

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

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

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

902:    Concepts: options database^list

904: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
905:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
906:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
907:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
908:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
909:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsEnum()
910: @*/
911: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char defaultv[],char value[],size_t len,PetscBool  *set)
912: {
914:   PetscOptions   amsopt;

917:   if (!PetscOptionsPublishCount) {
918:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
919:     PetscMalloc(sizeof(char*),&amsopt->data);

921:     *(const char**)amsopt->data = defaultv;

923:     amsopt->flist = list;
924:   }
925:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
926:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
927:     PetscFunctionListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
928:   }
929:   return(0);
930: }

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

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

939:    Input Parameters:
940: +  opt - option name
941: .  ltext - short string that describes the option
942: .  man - manual page with additional information on option
943: .  list - the possible choices
944: .  ntext - number of choices
945: -  defaultv - the default (current) value

947:    Output Parameter:
948: +  value - the index of the value to return
949: -  set - PETSC_TRUE if found, else PETSC_FALSE

951:    Level: intermediate

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

955:    See PetscOptionsList() for when the choices are given in a PetscFunctionList()

957:    Concepts: options database^list

959: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
960:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
961:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
962:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
963:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
964:           PetscOptionsList(), PetscOptionsEnum()
965: @*/
966: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool  *set)
967: {
969:   PetscInt       i;
970:   PetscOptions   amsopt;

973:   if (!PetscOptionsPublishCount) {
974:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
975:     PetscMalloc(sizeof(char*),&amsopt->data);

977:     *(const char**)amsopt->data = defaultv;

979:     amsopt->list  = list;
980:     amsopt->nlist = ntext;
981:   }
982:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
983:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
984:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
985:     for (i=0; i<ntext; i++) {
986:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
987:     }
988:     (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
989:   }
990:   return(0);
991: }

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

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

1001:    Input Parameters:
1002: +  opt - option name
1003: .  text - short string that describes the option
1004: -  man - manual page with additional information on option

1006:    Output Parameter:
1007: .  flg - whether that option was set or not

1009:    Level: intermediate

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

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

1015:     Concepts: options database^logical group

1017: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1018:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1019:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1020:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1021:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1022:           PetscOptionsList(), PetscOptionsEList()
1023: @*/
1024: PetscErrorCode  PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)
1025: {
1027:   PetscOptions   amsopt;

1030:   if (!PetscOptionsPublishCount) {
1031:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1032:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1034:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1035:   }
1036:   *flg = PETSC_FALSE;
1037:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1038:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1039:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
1040:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1041:   }
1042:   return(0);
1043: }

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

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

1053:    Input Parameters:
1054: +  opt - option name
1055: .  text - short string that describes the option
1056: -  man - manual page with additional information on option

1058:    Output Parameter:
1059: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1061:    Level: intermediate

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

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

1067:     Concepts: options database^logical group

1069: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1070:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1071:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1072:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1073:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1074:           PetscOptionsList(), PetscOptionsEList()
1075: @*/
1076: PetscErrorCode  PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)
1077: {
1079:   PetscOptions   amsopt;

1082:   if (!PetscOptionsPublishCount) {
1083:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1084:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1086:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1087:   }
1088:   *flg = PETSC_FALSE;
1089:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1090:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1091:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1092:   }
1093:   return(0);
1094: }

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

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

1104:    Input Parameters:
1105: +  opt - option name
1106: .  text - short string that describes the option
1107: -  man - manual page with additional information on option

1109:    Output Parameter:
1110: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1112:    Level: intermediate

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

1116:    Must follow a PetscOptionsBoolGroupBegin()

1118:     Concepts: options database^logical group

1120: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1121:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1122:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1123:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1124:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1125:           PetscOptionsList(), PetscOptionsEList()
1126: @*/
1127: PetscErrorCode  PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)
1128: {
1130:   PetscOptions   amsopt;

1133:   if (!PetscOptionsPublishCount) {
1134:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1135:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1137:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1138:   }
1139:   *flg = PETSC_FALSE;
1140:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,NULL);
1141:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1142:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1143:   }
1144:   return(0);
1145: }

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

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

1154:    Input Parameters:
1155: +  opt - option name
1156: .  text - short string that describes the option
1157: -  man - manual page with additional information on option

1159:    Output Parameter:
1160: .  flg - PETSC_TRUE or PETSC_FALSE
1161: .  set - PETSC_TRUE if found, else PETSC_FALSE

1163:    Level: beginner

1165:    Concepts: options database^logical

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

1169: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1170:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1171:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1172:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1173:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1174:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1175:           PetscOptionsList(), PetscOptionsEList()
1176: @*/
1177: PetscErrorCode  PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool deflt,PetscBool  *flg,PetscBool  *set)
1178: {
1180:   PetscBool      iset;
1181:   PetscOptions   amsopt;

1184:   if (!PetscOptionsPublishCount) {
1185:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1186:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1188:     *(PetscBool*)amsopt->data = deflt;
1189:   }
1190:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1191:   if (!iset) {
1192:     if (flg) *flg = deflt;
1193:   }
1194:   if (set) *set = iset;
1195:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1196:     const char *v = PetscBools[deflt];
1197:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1198:   }
1199:   return(0);
1200: }

1204: /*@C
1205:    PetscOptionsRealArray - Gets an array of double values for a particular
1206:    option in the database. The values must be separated with commas with
1207:    no intervening spaces.

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

1211:    Input Parameters:
1212: +  opt - the option one is seeking
1213: .  text - short string describing option
1214: .  man - manual page for option
1215: -  nmax - maximum number of values

1217:    Output Parameter:
1218: +  value - location to copy values
1219: .  nmax - actual number of values found
1220: -  set - PETSC_TRUE if found, else PETSC_FALSE

1222:    Level: beginner

1224:    Notes:
1225:    The user should pass in an array of doubles

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

1229:    Concepts: options database^array of strings

1231: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1232:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1233:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1234:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1235:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1236:           PetscOptionsList(), PetscOptionsEList()
1237: @*/
1238: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1239: {
1241:   PetscInt       i;
1242:   PetscOptions   amsopt;

1245:   if (!PetscOptionsPublishCount) {
1246:     PetscReal *vals;

1248:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1249:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1250:     vals = (PetscReal*)amsopt->data;
1251:     for (i=0; i<*n; i++) vals[i] = value[i];
1252:     amsopt->arraylength = *n;
1253:   }
1254:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1255:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1256:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1257:     for (i=1; i<*n; i++) {
1258:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1259:     }
1260:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1261:   }
1262:   return(0);
1263: }


1268: /*@C
1269:    PetscOptionsIntArray - Gets an array of integers for a particular
1270:    option in the database.

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

1274:    Input Parameters:
1275: +  opt - the option one is seeking
1276: .  text - short string describing option
1277: .  man - manual page for option
1278: -  n - maximum number of values

1280:    Output Parameter:
1281: +  value - location to copy values
1282: .  n - actual number of values found
1283: -  set - PETSC_TRUE if found, else PETSC_FALSE

1285:    Level: beginner

1287:    Notes:
1288:    The array can be passed as
1289:    a comma seperated list:                                 0,1,2,3,4,5,6,7
1290:    a range (start-end+1):                                  0-8
1291:    a range with given increment (start-end+1:inc):         0-7:2
1292:    a combination of values and ranges seperated by commas: 0,1-8,8-15:2

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

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

1298:    Concepts: options database^array of ints

1300: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1301:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1302:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1303:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1304:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1305:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1306: @*/
1307: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1308: {
1310:   PetscInt       i;
1311:   PetscOptions   amsopt;

1314:   if (!PetscOptionsPublishCount) {
1315:     PetscInt *vals;

1317:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1318:     PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1319:     vals = (PetscInt*)amsopt->data;
1320:     for (i=0; i<*n; i++) vals[i] = value[i];
1321:     amsopt->arraylength = *n;
1322:   }
1323:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1324:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1325:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1326:     for (i=1; i<*n; i++) {
1327:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1328:     }
1329:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1330:   }
1331:   return(0);
1332: }

1336: /*@C
1337:    PetscOptionsStringArray - Gets an array of string values for a particular
1338:    option in the database. The values must be separated with commas with
1339:    no intervening spaces.

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

1343:    Input Parameters:
1344: +  opt - the option one is seeking
1345: .  text - short string describing option
1346: .  man - manual page for option
1347: -  nmax - maximum number of strings

1349:    Output Parameter:
1350: +  value - location to copy strings
1351: .  nmax - actual number of strings found
1352: -  set - PETSC_TRUE if found, else PETSC_FALSE

1354:    Level: beginner

1356:    Notes:
1357:    The user should pass in an array of pointers to char, to hold all the
1358:    strings returned by this function.

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

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

1365:    Concepts: options database^array of strings

1367: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1368:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1369:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1370:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1371:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1372:           PetscOptionsList(), PetscOptionsEList()
1373: @*/
1374: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1375: {
1377:   PetscOptions   amsopt;

1380:   if (!PetscOptionsPublishCount) {
1381:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1382:     PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);

1384:     amsopt->arraylength = *nmax;
1385:   }
1386:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1387:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1388:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,text,ManSection(man));
1389:   }
1390:   return(0);
1391: }

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

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

1402:    Input Parameters:
1403: +  opt - the option one is seeking
1404: .  text - short string describing option
1405: .  man - manual page for option
1406: -  nmax - maximum number of values

1408:    Output Parameter:
1409: +  value - location to copy values
1410: .  nmax - actual number of values found
1411: -  set - PETSC_TRUE if found, else PETSC_FALSE

1413:    Level: beginner

1415:    Notes:
1416:    The user should pass in an array of doubles

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

1420:    Concepts: options database^array of strings

1422: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1423:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1424:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1425:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1426:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1427:           PetscOptionsList(), PetscOptionsEList()
1428: @*/
1429: PetscErrorCode  PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1430: {
1432:   PetscInt       i;
1433:   PetscOptions   amsopt;

1436:   if (!PetscOptionsPublishCount) {
1437:     PetscBool *vals;

1439:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
1440:     PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
1441:     vals = (PetscBool*)amsopt->data;
1442:     for (i=0; i<*n; i++) vals[i] = value[i];
1443:     amsopt->arraylength = *n;
1444:   }
1445:   PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1446:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1447:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,value[0]);
1448:     for (i=1; i<*n; i++) {
1449:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1450:     }
1451:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1452:   }
1453:   return(0);
1454: }

1458: /*@C
1459:    PetscOptionsInt - Gets a viewer appropriate for the type indicated by the user

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

1463:    Input Parameters:
1464: +  opt - option name
1465: .  text - short string that describes the option
1466: -  man - manual page with additional information on option

1468:    Output Parameter:
1469: +  viewer - the viewer
1470: -  set - PETSC_TRUE if found, else PETSC_FALSE

1472:    Level: beginner

1474:    Concepts: options database^has int

1476:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1477: If no value is provided ascii:stdout is used
1478: $       ascii[:[filename][:format]]   defaults to stdout - format can be one of info, info_detailed, or matlab, for example ascii::info prints just the info
1479: $                                     about the object to standard out
1480: $       binary[:filename]   defaults to binaryoutput
1481: $       draw
1482: $       socket[:port]    defaults to the standard output port

1484:    Use PetscRestoreViewerDestroy() after using the viewer, otherwise a memory leak will occur

1486: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1487:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1488:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1489:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1490:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1491:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1492:           PetscOptionsList(), PetscOptionsEList()
1493: @*/
1494: PetscErrorCode  PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1495: {
1497:   PetscOptions   amsopt;

1500:   if (!PetscOptionsPublishCount) {
1501:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
1502:     PetscMalloc(sizeof(PetscInt),&amsopt->data);

1504:     *(const char**)amsopt->data = "";
1505:   }
1506:   PetscOptionsGetViewer(PetscOptionsObject.comm,PetscOptionsObject.prefix,opt,viewer,format,set);
1507:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1508:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix ? PetscOptionsObject.prefix : "",opt+1,"",text,ManSection(man));
1509:   }
1510:   return(0);
1511: }


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

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

1522:    Input Parameter:
1523: .   head - the heading text


1526:    Level: intermediate

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

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

1532:    Concepts: options database^subheading

1534: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1535:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1536:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1537:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1538:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1539:           PetscOptionsList(), PetscOptionsEList()
1540: @*/
1541: PetscErrorCode  PetscOptionsHead(const char head[])
1542: {

1546:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1547:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1548:   }
1549:   return(0);
1550: }