Actual source code: aoptions.c

  1: /*
  2:    Implements the higher-level options database querying methods. These are self-documenting and can attach at runtime to
  3:    GUI code to display the options and get values from the users.

  5: */

  7: #include <petsc/private/petscimpl.h>
  8: #include <petscviewer.h>

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

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

 16:     Eventually we'll attach this beast to a MPI_Comm
 17: */

 19: /*
 20:     Handles setting up the data structure in a call to PetscOptionsBegin()
 21: */
 22: PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
 23: {
 27:   if (!PetscOptionsObject->alreadyprinted) {
 28:     if (!PetscOptionsHelpPrintedSingleton) PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
 29:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
 30:   }
 31:   PetscOptionsObject->next          = NULL;
 32:   PetscOptionsObject->comm          = comm;
 33:   PetscOptionsObject->changedmethod = PETSC_FALSE;

 35:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
 36:   PetscStrallocpy(title,&PetscOptionsObject->title);

 38:   PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
 39:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
 40:     if (!PetscOptionsObject->alreadyprinted) {
 41:       (*PetscHelpPrintf)(comm,"----------------------------------------\n%s:\n",title);
 42:     }
 43:   }
 44:   return 0;
 45: }

 47: /*
 48:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 49: */
 50: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
 51: {
 52:   char      title[256];
 53:   PetscBool flg;

 57:   PetscOptionsObject->object         = obj;
 58:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

 60:   PetscStrcmp(obj->description,obj->class_name,&flg);
 61:   if (flg) PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
 62:   else     PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
 63:   PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
 64:   return 0;
 65: }

 67: /*
 68:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 69: */
 70: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
 71: {
 72:   PetscOptionItem next;
 73:   PetscBool       valid;

 75:   PetscOptionsValidKey(opt,&valid);

 78:   PetscNew(amsopt);
 79:   (*amsopt)->next = NULL;
 80:   (*amsopt)->set  = PETSC_FALSE;
 81:   (*amsopt)->type = t;
 82:   (*amsopt)->data = NULL;

 84:   PetscStrallocpy(text,&(*amsopt)->text);
 85:   PetscStrallocpy(opt,&(*amsopt)->option);
 86:   PetscStrallocpy(man,&(*amsopt)->man);

 88:   if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
 89:   else {
 90:     next = PetscOptionsObject->next;
 91:     while (next->next) next = next->next;
 92:     next->next = *amsopt;
 93:   }
 94:   return 0;
 95: }

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

100:     Collective

102:    Input Parameters:
103: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
104: .     n - length of the string, must be the same on all processes
105: -     str - location to store input

107:     Bugs:
108: .   Assumes process 0 of the given communicator has access to stdin

110: */
111: static PetscErrorCode PetscScanString(MPI_Comm comm, size_t n, char str[])
112: {
113:   PetscMPIInt rank,nm;

115:   MPI_Comm_rank(comm,&rank);
116:   if (rank == 0) {
117:     char   c = (char)getchar();
118:     size_t i = 0;

120:     while (c != '\n' && i < n-1) {
121:       str[i++] = c;
122:       c = (char)getchar();
123:     }
124:     str[i] = 0;
125:   }
126:   PetscMPIIntCast(n,&nm);
127:   MPI_Bcast(str,nm,MPI_CHAR,0,comm);
128:   return 0;
129: }

131: /*
132:     This is needed because certain strings may be freed by SAWs, hence we cannot use PetscStrallocpy()
133: */
134: static PetscErrorCode PetscStrdup(const char s[], char *t[])
135: {
136:   char *tmp = NULL;

138:   if (s) {
139:     size_t len;

141:     PetscStrlen(s,&len);
142:     tmp = (char*) malloc((len+1)*sizeof(*tmp));
144:     PetscStrcpy(tmp,s);
145:   }
146:   *t = tmp;
147:   return 0;
148: }

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

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

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

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

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

168: */
169: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
170: {
171:   PetscOptionItem next = PetscOptionsObject->next;
172:   char            str[512];
173:   PetscBool       bid;
174:   PetscReal       ir,*valr;
175:   PetscInt        *vald;
176:   size_t          i;

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

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

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

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

283:         next->set = PETSC_TRUE;
284:         *((PetscInt*)next->data) = (PetscInt)lid;
285:       }
286:       break;
287:     case OPTION_REAL:
288:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,*(double*)next->data,next->text,next->man);
289:       PetscScanString(PETSC_COMM_WORLD,512,str);
290:       if (str[0]) {
291: #if defined(PETSC_USE_REAL_SINGLE)
292:         sscanf(str,"%e",&ir);
293: #elif defined(PETSC_USE_REAL___FP16)
294:         float irtemp;
295:         sscanf(str,"%e",&irtemp);
296:         ir = irtemp;
297: #elif defined(PETSC_USE_REAL_DOUBLE)
298:         sscanf(str,"%le",&ir);
299: #elif defined(PETSC_USE_REAL___FLOAT128)
300:         ir = strtoflt128(str,0);
301: #else
302:         SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
303: #endif
304:         next->set                 = PETSC_TRUE;
305:         *((PetscReal*)next->data) = ir;
306:       }
307:       break;
308:     case OPTION_BOOL:
309:       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);
310:       PetscScanString(PETSC_COMM_WORLD,512,str);
311:       if (str[0]) {
312:         PetscOptionsStringToBool(str,&bid);
313:         next->set = PETSC_TRUE;
314:         *((PetscBool*)next->data) = bid;
315:       }
316:       break;
317:     case OPTION_STRING:
318:       PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s) ",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",next->option+1,(char*)next->data,next->text,next->man);
319:       PetscScanString(PETSC_COMM_WORLD,512,str);
320:       if (str[0]) {
321:         next->set = PETSC_TRUE;
322:         /* must use system malloc since SAWs may free this */
323:         PetscStrdup(str,(char**)&next->data);
324:       }
325:       break;
326:     case OPTION_FLIST:
327:       PetscFunctionListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject->prefix,next->option,next->text,next->man,next->flist,(char*)next->data,(char*)next->data);
328:       PetscScanString(PETSC_COMM_WORLD,512,str);
329:       if (str[0]) {
330:         PetscOptionsObject->changedmethod = PETSC_TRUE;
331:         next->set = PETSC_TRUE;
332:         /* must use system malloc since SAWs may free this */
333:         PetscStrdup(str,(char**)&next->data);
334:       }
335:       break;
336:     default:
337:       break;
338:     }
339:     next = next->next;
340:   }
341:   return 0;
342: }

344: #if defined(PETSC_HAVE_SAWS)
345: #include <petscviewersaws.h>

347: static int count = 0;

349: PetscErrorCode PetscOptionsSAWsDestroy(void)
350: {
351:   return 0;
352: }

354: static const char *OptionsHeader = "<head>\n"
355:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
356:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
357:                                    "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
358:                                    "<script>\n"
359:                                       "jQuery(document).ready(function() {\n"
360:                                          "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
361:                                       "})\n"
362:                                   "</script>\n"
363:                                   "</head>\n";

365: /*  Determines the size and style of the scroll region where PETSc options selectable from users are displayed */
366: static const char *OptionsBodyBottom = "<div id=\"variablesInfo\" style=\"background-color:lightblue;height:auto;max-height:500px;overflow:scroll;\"></div>\n<br>\n</body>";

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

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

376: */
377: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
378: {
379:   PetscOptionItem next     = PetscOptionsObject->next;
380:   static int      mancount = 0;
381:   char            options[16];
382:   PetscBool       changedmethod = PETSC_FALSE;
383:   PetscBool       stopasking    = PETSC_FALSE;
384:   char            manname[16],textname[16];
385:   char            dir[1024];

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

390:   PetscOptionsObject->pprefix = PetscOptionsObject->prefix; /* SAWs will change this, so cannot pass prefix directly */

392:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
393:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
394:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
395:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
396:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
397:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

399:   while (next) {
400:     sprintf(manname,"_man_%d",mancount);
401:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
402:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
403:     sprintf(textname,"_text_%d",mancount++);
404:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
405:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

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

467:   /* wait until accessor has unlocked the memory */
468:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
469:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
470:   PetscSAWsBlock();
471:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
472:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

474:   /* determine if any values have been set in GUI */
475:   next = PetscOptionsObject->next;
476:   while (next) {
477:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
478:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
479:     next = next->next;
480:   }

482:   /* reset counter to -2; this updates the screen with the new options for the selected method */
483:   if (changedmethod) PetscOptionsObject->count = -2;

485:   if (stopasking) {
486:     PetscOptionsPublish      = PETSC_FALSE;
487:     PetscOptionsObject->count = 0;//do not ask for same thing again
488:   }

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

495: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
496: {
497:   PetscOptionItem last;
498:   char            option[256],value[1024],tmp[32];
499:   size_t          j;

501:   if (PetscOptionsObject->next) {
502:     if (!PetscOptionsObject->count) {
503: #if defined(PETSC_HAVE_SAWS)
504:       PetscOptionsSAWsInput(PetscOptionsObject);
505: #else
506:       PetscOptionsGetFromTextInput(PetscOptionsObject);
507: #endif
508:     }
509:   }

511:   PetscFree(PetscOptionsObject->title);

513:   /* reset counter to -2; this updates the screen with the new options for the selected method */
514:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
515:   /* reset alreadyprinted flag */
516:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
517:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
518:   PetscOptionsObject->object = NULL;

520:   while (PetscOptionsObject->next) {
521:     if (PetscOptionsObject->next->set) {
522:       if (PetscOptionsObject->prefix) {
523:         PetscStrcpy(option,"-");
524:         PetscStrcat(option,PetscOptionsObject->prefix);
525:         PetscStrcat(option,PetscOptionsObject->next->option+1);
526:       } else PetscStrcpy(option,PetscOptionsObject->next->option);

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

600:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)) {
601:       free(PetscOptionsObject->next->data);
602:     } else {
603:       PetscFree(PetscOptionsObject->next->data);
604:     }

606:     last                     = PetscOptionsObject->next;
607:     PetscOptionsObject->next = PetscOptionsObject->next->next;
608:     PetscFree(last);
609:   }
610:   PetscFree(PetscOptionsObject->prefix);
611:   PetscOptionsObject->next = NULL;
612:   return 0;
613: }

615: /*MC
616:    PetscOptionsEnum - Gets the enum value for a particular option in the database.

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

620:    Synopsis:
621:    #include "petscsys.h"
622:    PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)

624:    Input Parameters:
625: +  opt - option name
626: .  text - short string that describes the option
627: .  man - manual page with additional information on option
628: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
629: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
630: $                 PetscOptionsEnum(..., obj->value,&object->value,...) or
631: $                 value = defaultvalue
632: $                 PetscOptionsEnum(..., value,&value,&flg);
633: $                 if (flg) {

635:    Output Parameters:
636: +  value - the  value to return
637: -  set - PETSC_TRUE if found, else PETSC_FALSE

639:    Level: beginner

641:    Notes:
642:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

646:           If the user does not supply the option at all value is NOT changed. Thus
647:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

649:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

651: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
652:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
653:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
654:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
655:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
656:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
657:           PetscOptionsFList(), PetscOptionsEList()
658: M*/

660: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
661: {
662:   PetscInt       ntext = 0;
663:   PetscInt       tval;
664:   PetscBool      tflg;

666:   while (list[ntext++]) {
668:   }
670:   ntext -= 3;
671:   PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
672:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
673:   if (tflg) *value = (PetscEnum)tval;
674:   if (set)  *set   = tflg;
675:   return 0;
676: }

678: /*MC
679:    PetscOptionsEnumArray - Gets an array of enum values for a particular
680:    option in the database.

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

684:    Synopsis:
685:    #include "petscsys.h"
686:    PetscErrorCode  PetscOptionsEnumArray(const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)

688:    Input Parameters:
689: +  opt - the option one is seeking
690: .  text - short string describing option
691: .  man - manual page for option
692: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
693: -  n - maximum number of values allowed in the value array

695:    Output Parameters:
696: +  value - location to copy values
697: .  n - actual number of values found
698: -  set - PETSC_TRUE if found, else PETSC_FALSE

700:    Level: beginner

702:    Notes:
703:    The array must be passed as a comma separated list.

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

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

709: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
710:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
711:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
712:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
713:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
714:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
715: M*/

717: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
718: {
719:   PetscInt        i,nlist = 0;
720:   PetscOptionItem amsopt;

724:   nlist -= 3; /* drop enum name, prefix, and null termination */
725:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
726:     PetscEnum *vals;
727:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
728:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
729:     amsopt->nlist = nlist;
730:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
731:     amsopt->arraylength = *n;
732:     vals = (PetscEnum*)amsopt->data;
733:     for (i=0; i<*n; i++) vals[i] = value[i];
734:   }
735:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
736:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
737:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
738:     for (i=1; i<*n; i++) (*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);
739:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
740:     for (i=0; i<nlist; i++) (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
741:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
742:   }
743:   return 0;
744: }

746: /*MC
747:    PetscOptionsBoundedInt - Gets an integer value greater than or equal a given bound for a particular option in the database.

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

751:    Synopsis:
752:    #include "petscsys.h"
753:    PetscErrorCode  PetscOptionsBoundInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)

755:    Input Parameters:
756: +  opt - option name
757: .  text - short string that describes the option
758: .  man - manual page with additional information on option
759: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
760: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
761: $                 value = defaultvalue
762: $                 PetscOptionsInt(..., value,&value,&flg);
763: $                 if (flg) {
764: -  bound - the requested value should be greater than or equal this bound or an error is generated

766:    Output Parameters:
767: +  value - the integer value to return
768: -  flg - PETSC_TRUE if found, else PETSC_FALSE

770:    Notes:
771:     If the user does not supply the option at all value is NOT changed. Thus
772:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

774:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

778:    Level: beginner

780: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
781:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
782:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
783:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
784:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
785:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
786:           PetscOptionsFList(), PetscOptionsEList()
787: M*/

789: /*MC
790:    PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.

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

794:    Synopsis:
795:    #include "petscsys.h"
796: PetscErrorCode  PetscOptionsRangeInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)

798:    Input Parameters:
799: +  opt - option name
800: .  text - short string that describes the option
801: .  man - manual page with additional information on option
802: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
803: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
804: $                 value = defaultvalue
805: $                 PetscOptionsInt(..., value,&value,&flg);
806: $                 if (flg) {
807: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
808: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

810:    Output Parameters:
811: +  value - the integer value to return
812: -  flg - PETSC_TRUE if found, else PETSC_FALSE

814:    Notes:
815:     If the user does not supply the option at all value is NOT changed. Thus
816:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

818:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

822:    Level: beginner

824: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
825:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsBoundedInt()
826:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
827:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
828:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
829:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
830:           PetscOptionsFList(), PetscOptionsEList()
831: M*/

833: /*MC
834:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

838:    Synopsis:
839:    #include "petscsys.h"
840: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))

842:    Input Parameters:
843: +  opt - option name
844: .  text - short string that describes the option
845: .  man - manual page with additional information on option
846: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
847: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
848: $                 value = defaultvalue
849: $                 PetscOptionsInt(..., value,&value,&flg);
850: $                 if (flg) {

852:    Output Parameters:
853: +  value - the integer value to return
854: -  flg - PETSC_TRUE if found, else PETSC_FALSE

856:    Notes:
857:     If the user does not supply the option at all value is NOT changed. Thus
858:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

860:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

864:    Level: beginner

866: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
867:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(), PetscOptionsRangeInt()
868:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
869:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
870:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
871:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
872:           PetscOptionsFList(), PetscOptionsEList()
873: M*/

875: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set,PetscInt lb,PetscInt ub)
876: {
877:   PetscOptionItem amsopt;
878:   PetscBool       wasset;

882:      if (!PetscOptionsObject->count) {
883:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
884:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
885:     *(PetscInt*)amsopt->data = currentvalue;

887:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
888:     if (wasset) {
889:       *(PetscInt*)amsopt->data = currentvalue;
890:     }
891:   }
892:   PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
895:   if (set) *set = wasset;
896:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
897:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %" PetscInt_FMT " : formerly %" PetscInt_FMT ">: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
898:   }
899:   return 0;
900: }

902: /*MC
903:    PetscOptionsString - Gets the string value for a particular option in the database.

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

907:    Synopsis:
908:    #include "petscsys.h"
909:    PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)

911:    Input Parameters:
912: +  opt - option name
913: .  text - short string that describes the option
914: .  man - manual page with additional information on option
915: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
916: -  len - length of the result string including null terminator

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

922:    Level: beginner

924:    Notes:
925:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

929:           If the user does not supply the option at all value is NOT changed. Thus
930:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

932:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

934: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
935:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
936:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
937:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
938:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
939:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
940:           PetscOptionsFList(), PetscOptionsEList()
941: M*/

943: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
944: {
945:   PetscOptionItem amsopt;
946:   PetscBool       lset;

948:   if (!PetscOptionsObject->count) {
949:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
950:     /* must use system malloc since SAWs may free this */
951:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
952:   }
953:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
954:   if (set) *set = lset;
955:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
956:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? value : currentvalue,currentvalue,text,ManSection(man));
957:   }
958:   return 0;
959: }

961: /*MC
962:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

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

966:    Synopsis:
967:    #include "petscsys.h"
968:    PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)

970:    Input Parameters:
971: +  opt - option name
972: .  text - short string that describes the option
973: .  man - manual page with additional information on option
974: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
975: $                 PetscOptionsReal(..., obj->value,&obj->value,...) or
976: $                 value = defaultvalue
977: $                 PetscOptionsReal(..., value,&value,&flg);
978: $                 if (flg) {

980:    Output Parameters:
981: +  value - the value to return
982: -  flg - PETSC_TRUE if found, else PETSC_FALSE

984:    Notes:
985:     If the user does not supply the option at all value is NOT changed. Thus
986:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

988:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

992:    Level: beginner

994: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
995:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
996:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
997:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
998:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
999:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1000:           PetscOptionsFList(), PetscOptionsEList()
1001: M*/

1003: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
1004: {
1005:   PetscOptionItem amsopt;
1006:   PetscBool       lset;

1008:   if (!PetscOptionsObject->count) {
1009:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1010:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

1012:     *(PetscReal*)amsopt->data = currentvalue;
1013:   }
1014:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1015:   if (set) *set = lset;
1016:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1017:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g : %g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,lset && value ? (double)*value : (double) currentvalue,(double)currentvalue,text,ManSection(man));
1018:   }
1019:   return 0;
1020: }

1022: /*MC
1023:    PetscOptionsScalar - Gets the scalar value for a particular option in the database.

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

1027:    Synopsis:
1028:    #include "petscsys.h"
1029:    PetscErrorCode PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)

1031:    Input Parameters:
1032: +  opt - option name
1033: .  text - short string that describes the option
1034: .  man - manual page with additional information on option
1035: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1036: $                 PetscOptionsScalar(..., obj->value,&obj->value,...) or
1037: $                 value = defaultvalue
1038: $                 PetscOptionsScalar(..., value,&value,&flg);
1039: $                 if (flg) {

1041:    Output Parameters:
1042: +  value - the value to return
1043: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1045:    Notes:
1046:     If the user does not supply the option at all value is NOT changed. Thus
1047:     you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1049:     The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

1053:    Level: beginner

1055: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1056:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1057:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1058:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1059:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1060:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1061:           PetscOptionsFList(), PetscOptionsEList()
1062: M*/

1064: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
1065: {
1066: #if !defined(PETSC_USE_COMPLEX)
1067:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
1068: #else
1069:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1070: #endif
1071:   return 0;
1072: }

1074: /*MC
1075:    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
1076:                       its value is set to false.

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

1080:    Synopsis:
1081:    #include "petscsys.h"
1082:    PetscErrorCode PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)

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

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

1092:    Level: beginner

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

1097: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1098:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1099:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1100:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1101:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1102:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1103:           PetscOptionsFList(), PetscOptionsEList()
1104: M*/

1106: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1107: {
1108:   PetscOptionItem amsopt;

1110:   if (!PetscOptionsObject->count) {
1111:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1112:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1114:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1115:   }
1116:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1117:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1118:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1119:   }
1120:   return 0;
1121: }

1123: /*MC
1124:      PetscOptionsFList - Puts a list of option values that a single one may be selected from

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

1128:    Synopsis:
1129:    #include "petscsys.h"
1130:    PetscErrorCode  PetscOptionsFList(const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)

1132:    Input Parameters:
1133: +  opt - option name
1134: .  text - short string that describes the option
1135: .  man - manual page with additional information on option
1136: .  list - the possible choices
1137: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1138: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
1139: $                 if (flg) {
1140: -  len - the length of the character array value

1142:    Output Parameters:
1143: +  value - the value to return
1144: -  set - PETSC_TRUE if found, else PETSC_FALSE

1146:    Level: intermediate

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

1151:           If the user does not supply the option at all value is NOT changed. Thus
1152:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

1154:           The default/currentvalue passed into this routine does not get transferred to the output value variable automatically.

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

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

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

1163: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1164:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1165:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1166:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1167:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1168:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1169: M*/

1171: PetscErrorCode  PetscOptionsFList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)
1172: {
1173:   PetscOptionItem amsopt;
1174:   PetscBool       lset;

1176:   if (!PetscOptionsObject->count) {
1177:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1178:     /* must use system malloc since SAWs may free this */
1179:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1180:     amsopt->flist = list;
1181:   }
1182:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1183:   if (set) *set = lset;
1184:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1185:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1186:   }
1187:   return 0;
1188: }

1190: /*MC
1191:      PetscOptionsEList - Puts a list of option values that a single one may be selected from

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

1195:    Synopsis:
1196:    #include "petscsys.h"
1197:    PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)

1199:    Input Parameters:
1200: +  opt - option name
1201: .  ltext - short string that describes the option
1202: .  man - manual page with additional information on option
1203: .  list - the possible choices (one of these must be selected, anything else is invalid)
1204: .  ntext - number of choices
1205: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1206: $                 PetscOptionsElist(..., obj->value,&value,&flg);
1207: $                 if (flg) {

1209:    Output Parameters:
1210: +  value - the index of the value to return
1211: -  set - PETSC_TRUE if found, else PETSC_FALSE

1213:    Level: intermediate

1215:    Notes:
1216:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1218:          If the user does not supply the option at all value is NOT changed. Thus
1219:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

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

1223: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1224:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1225:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1226:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1227:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1228:           PetscOptionsFList(), PetscOptionsEnum()
1229: M*/

1231: PetscErrorCode  PetscOptionsEList_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)
1232: {
1233:   PetscInt        i;
1234:   PetscOptionItem amsopt;
1235:   PetscBool       lset;

1237:   if (!PetscOptionsObject->count) {
1238:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1239:     /* must use system malloc since SAWs may free this */
1240:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1241:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1242:     amsopt->nlist = ntext;
1243:   }
1244:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1245:   if (set) *set = lset;
1246:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1247:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %s : formerly %s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,lset && value ? list[*value] : currentvalue,currentvalue,ltext);
1248:     for (i=0; i<ntext; i++) {
1249:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1250:     }
1251:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1252:   }
1253:   return 0;
1254: }

1256: /*MC
1257:      PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1258:        which at most a single value can be true.

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

1262:    Synopsis:
1263:    #include "petscsys.h"
1264:    PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)

1266:    Input Parameters:
1267: +  opt - option name
1268: .  text - short string that describes the option
1269: -  man - manual page with additional information on option

1271:    Output Parameter:
1272: .  flg - whether that option was set or not

1274:    Level: intermediate

1276:    Notes:
1277:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1281: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1282:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1283:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1284:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1285:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1286:           PetscOptionsFList(), PetscOptionsEList()
1287: M*/

1289: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1290: {
1291:   PetscOptionItem amsopt;

1293:   if (!PetscOptionsObject->count) {
1294:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1295:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1297:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1298:   }
1299:   *flg = PETSC_FALSE;
1300:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1301:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1302:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
1303:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1304:   }
1305:   return 0;
1306: }

1308: /*MC
1309:      PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1310:        which at most a single value can be true.

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

1314:    Synopsis:
1315:    #include "petscsys.h"
1316:    PetscErrorCode PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)

1318:    Input Parameters:
1319: +  opt - option name
1320: .  text - short string that describes the option
1321: -  man - manual page with additional information on option

1323:    Output Parameter:
1324: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1326:    Level: intermediate

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

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

1333: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1334:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1335:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1336:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1337:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1338:           PetscOptionsFList(), PetscOptionsEList()
1339: M*/

1341: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1342: {
1343:   PetscOptionItem amsopt;

1345:   if (!PetscOptionsObject->count) {
1346:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1347:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1349:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1350:   }
1351:   *flg = PETSC_FALSE;
1352:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1353:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1354:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1355:   }
1356:   return 0;
1357: }

1359: /*MC
1360:      PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1361:        which at most a single value can be true.

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

1365:    Synopsis:
1366:    #include "petscsys.h"
1367:    PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)

1369:    Input Parameters:
1370: +  opt - option name
1371: .  text - short string that describes the option
1372: -  man - manual page with additional information on option

1374:    Output Parameter:
1375: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1377:    Level: intermediate

1379:    Notes:
1380:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1382:    Must follow a PetscOptionsBoolGroupBegin()

1384: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1385:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1386:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1387:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1388:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1389:           PetscOptionsFList(), PetscOptionsEList()
1390: M*/

1392: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1393: {
1394:   PetscOptionItem amsopt;

1396:   if (!PetscOptionsObject->count) {
1397:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1398:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1400:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1401:   }
1402:   *flg = PETSC_FALSE;
1403:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1404:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1405:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1406:   }
1407:   return 0;
1408: }

1410: /*MC
1411:    PetscOptionsBool - Determines if a particular option is in the database with a true or false

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

1415:    Synopsis:
1416:    #include "petscsys.h"
1417:    PetscErrorCode PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)

1419:    Input Parameters:
1420: +  opt - option name
1421: .  text - short string that describes the option
1422: .  man - manual page with additional information on option
1423: -  currentvalue - the current value

1425:    Output Parameters:
1426: +  flg - PETSC_TRUE or PETSC_FALSE
1427: -  set - PETSC_TRUE if found, else PETSC_FALSE

1429:    Notes:
1430:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1431:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1433:       If the option is given, but no value is provided, then flg and set are both given the value PETSC_TRUE. That is -requested_bool
1434:      is equivalent to -requested_bool true

1436:        If the user does not supply the option at all flg is NOT changed. Thus
1437:      you should ALWAYS initialize the flg if you access it without first checking if the set flag is true.

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

1441:    Level: beginner

1443: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1444:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetBool(),
1445:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(),
1446:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1447:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1448:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1449:           PetscOptionsFList(), PetscOptionsEList()
1450: M*/

1452: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1453: {
1454:   PetscBool       iset;
1455:   PetscOptionItem amsopt;

1457:   if (!PetscOptionsObject->count) {
1458:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1459:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1461:     *(PetscBool*)amsopt->data = currentvalue;
1462:   }
1463:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1464:   if (set) *set = iset;
1465:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1466:     const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1467:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1468:   }
1469:   return 0;
1470: }

1472: /*MC
1473:    PetscOptionsRealArray - Gets an array of double values for a particular
1474:    option in the database. The values must be separated with commas with
1475:    no intervening spaces.

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

1479:    Synopsis:
1480:    #include "petscsys.h"
1481:    PetscErrorCode PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)

1483:    Input Parameters:
1484: +  opt - the option one is seeking
1485: .  text - short string describing option
1486: .  man - manual page for option
1487: -  n - maximum number of values that value has room for

1489:    Output Parameters:
1490: +  value - location to copy values
1491: .  n - actual number of values found
1492: -  set - PETSC_TRUE if found, else PETSC_FALSE

1494:    Level: beginner

1496:    Notes:
1497:    The user should pass in an array of doubles

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

1501: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1502:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1503:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1504:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1505:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1506:           PetscOptionsFList(), PetscOptionsEList()
1507: M*/

1509: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1510: {
1511:   PetscInt        i;
1512:   PetscOptionItem amsopt;

1514:   if (!PetscOptionsObject->count) {
1515:     PetscReal *vals;

1517:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1518:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1519:     vals = (PetscReal*)amsopt->data;
1520:     for (i=0; i<*n; i++) vals[i] = value[i];
1521:     amsopt->arraylength = *n;
1522:   }
1523:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1524:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1525:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1526:     for (i=1; i<*n; i++) {
1527:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1528:     }
1529:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1530:   }
1531:   return 0;
1532: }

1534: /*MC
1535:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1536:    option in the database. The values must be separated with commas with
1537:    no intervening spaces.

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

1541:    Synopsis:
1542:    #include "petscsys.h"
1543:    PetscErrorCode PetscOptionsScalarArray(const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)

1545:    Input Parameters:
1546: +  opt - the option one is seeking
1547: .  text - short string describing option
1548: .  man - manual page for option
1549: -  n - maximum number of values allowed in the value array

1551:    Output Parameters:
1552: +  value - location to copy values
1553: .  n - actual number of values found
1554: -  set - PETSC_TRUE if found, else PETSC_FALSE

1556:    Level: beginner

1558:    Notes:
1559:    The user should pass in an array of doubles

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

1563: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1564:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1565:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1566:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1567:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1568:           PetscOptionsFList(), PetscOptionsEList()
1569: M*/

1571: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1572: {
1573:   PetscInt        i;
1574:   PetscOptionItem amsopt;

1576:   if (!PetscOptionsObject->count) {
1577:     PetscScalar *vals;

1579:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1580:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1581:     vals = (PetscScalar*)amsopt->data;
1582:     for (i=0; i<*n; i++) vals[i] = value[i];
1583:     amsopt->arraylength = *n;
1584:   }
1585:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1586:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1587:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1588:     for (i=1; i<*n; i++) {
1589:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1590:     }
1591:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1592:   }
1593:   return 0;
1594: }

1596: /*MC
1597:    PetscOptionsIntArray - Gets an array of integers for a particular
1598:    option in the database.

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

1602:    Synopsis:
1603:    #include "petscsys.h"
1604:    PetscErrorCode PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)

1606:    Input Parameters:
1607: +  opt - the option one is seeking
1608: .  text - short string describing option
1609: .  man - manual page for option
1610: -  n - maximum number of values

1612:    Output Parameters:
1613: +  value - location to copy values
1614: .  n - actual number of values found
1615: -  set - PETSC_TRUE if found, else PETSC_FALSE

1617:    Level: beginner

1619:    Notes:
1620:    The array can be passed as
1621:    a comma separated list:                                 0,1,2,3,4,5,6,7
1622:    a range (start-end+1):                                  0-8
1623:    a range with given increment (start-end+1:inc):         0-7:2
1624:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

1630: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1631:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1632:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1633:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1634:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1635:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1636: M*/

1638: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1639: {
1640:   PetscInt        i;
1641:   PetscOptionItem amsopt;

1643:   if (!PetscOptionsObject->count) {
1644:     PetscInt *vals;

1646:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1647:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1648:     vals = (PetscInt*)amsopt->data;
1649:     for (i=0; i<*n; i++) vals[i] = value[i];
1650:     amsopt->arraylength = *n;
1651:   }
1652:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1653:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1654:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%" PetscInt_FMT,PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1655:     for (i=1; i<*n; i++) {
1656:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%" PetscInt_FMT,value[i]);
1657:     }
1658:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1659:   }
1660:   return 0;
1661: }

1663: /*MC
1664:    PetscOptionsStringArray - Gets an array of string values for a particular
1665:    option in the database. The values must be separated with commas with
1666:    no intervening spaces.

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

1670:    Synopsis:
1671:    #include "petscsys.h"
1672:    PetscErrorCode PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)

1674:    Input Parameters:
1675: +  opt - the option one is seeking
1676: .  text - short string describing option
1677: .  man - manual page for option
1678: -  nmax - maximum number of strings

1680:    Output Parameters:
1681: +  value - location to copy strings
1682: .  nmax - actual number of strings found
1683: -  set - PETSC_TRUE if found, else PETSC_FALSE

1685:    Level: beginner

1687:    Notes:
1688:    The user should pass in an array of pointers to char, to hold all the
1689:    strings returned by this function.

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

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

1696: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1697:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1698:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1699:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1700:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1701:           PetscOptionsFList(), PetscOptionsEList()
1702: M*/

1704: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1705: {
1706:   PetscOptionItem amsopt;

1708:   if (!PetscOptionsObject->count) {
1709:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1710:     PetscMalloc1(*nmax,(char**)&amsopt->data);

1712:     amsopt->arraylength = *nmax;
1713:   }
1714:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1715:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1716:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1717:   }
1718:   return 0;
1719: }

1721: /*MC
1722:    PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1723:    option in the database. The values must be separated with commas with
1724:    no intervening spaces.

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

1728:    Synopsis:
1729:    #include "petscsys.h"
1730:    PetscErrorCode PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)

1732:    Input Parameters:
1733: +  opt - the option one is seeking
1734: .  text - short string describing option
1735: .  man - manual page for option
1736: -  n - maximum number of values allowed in the value array

1738:    Output Parameters:
1739: +  value - location to copy values
1740: .  n - actual number of values found
1741: -  set - PETSC_TRUE if found, else PETSC_FALSE

1743:    Level: beginner

1745:    Notes:
1746:    The user should pass in an array of doubles

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

1750: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1751:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1752:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1753:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1754:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1755:           PetscOptionsFList(), PetscOptionsEList()
1756: M*/

1758: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1759: {
1760:   PetscInt         i;
1761:   PetscOptionItem  amsopt;

1763:   if (!PetscOptionsObject->count) {
1764:     PetscBool *vals;

1766:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1767:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1768:     vals = (PetscBool*)amsopt->data;
1769:     for (i=0; i<*n; i++) vals[i] = value[i];
1770:     amsopt->arraylength = *n;
1771:   }
1772:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1773:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1774:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1775:     for (i=1; i<*n; i++) {
1776:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1777:     }
1778:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1779:   }
1780:   return 0;
1781: }

1783: /*MC
1784:    PetscOptionsViewer - Gets a viewer appropriate for the type indicated by the user

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

1788:    Synopsis:
1789:    #include "petscsys.h"
1790:    PetscErrorCode PetscOptionsViewer(const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool *set)

1792:    Input Parameters:
1793: +  opt - option name
1794: .  text - short string that describes the option
1795: -  man - manual page with additional information on option

1797:    Output Parameters:
1798: +  viewer - the viewer
1799: .  format - the PetscViewerFormat requested by the user, pass NULL if not needed
1800: -  set - PETSC_TRUE if found, else PETSC_FALSE

1802:    Level: beginner

1804:    Notes:
1805:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1807:    See PetscOptionsGetViewer() for the format of the supplied viewer and its options

1809: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1810:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1811:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1812:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1813:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1814:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1815:           PetscOptionsFList(), PetscOptionsEList()
1816: M*/

1818: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1819: {
1820:   PetscOptionItem amsopt;

1822:   if (!PetscOptionsObject->count) {
1823:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1824:     /* must use system malloc since SAWs may free this */
1825:     PetscStrdup("",(char**)&amsopt->data);
1826:   }
1827:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1828:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1829:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1830:   }
1831:   return 0;
1832: }

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

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

1840:    Input Parameter:
1841: .   head - the heading text

1843:    Level: intermediate

1845:    Notes:
1846:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd(), and PetscOptionsObject created in PetscOptionsBegin() should be the first argument

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

1850: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1851:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1852:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1853:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1854:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1855:           PetscOptionsFList(), PetscOptionsEList()
1856: @*/
1857: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1858: {
1859:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1860:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1861:   }
1862:   return 0;
1863: }