Actual source code: aoptions.c

petsc-master 2020-02-22
Report Typos and Errors


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

  7: */

  9:  #include <petsc/private/petscimpl.h>
 10:  #include <petscviewer.h>

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

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

 18:     Eventually we'll attach this beast to a MPI_Comm
 19: */


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

 30:   if (!PetscOptionsObject->alreadyprinted) {
 31:     if (!PetscOptionsHelpPrintedSingleton) {
 32:       PetscOptionsHelpPrintedCreate(&PetscOptionsHelpPrintedSingleton);
 33:     }
 34:     PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrintedSingleton,prefix,title,&PetscOptionsObject->alreadyprinted);
 35:   }
 36:   PetscOptionsObject->next          = NULL;
 37:   PetscOptionsObject->comm          = comm;
 38:   PetscOptionsObject->changedmethod = PETSC_FALSE;

 40:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
 41:   PetscStrallocpy(title,&PetscOptionsObject->title);

 43:   PetscOptionsHasHelp(PetscOptionsObject->options,&PetscOptionsObject->printhelp);
 44:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1) {
 45:     if (!PetscOptionsObject->alreadyprinted) {
 46:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
 47:     }
 48:   }
 49:   return(0);
 50: }

 52: /*
 53:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 54: */
 55: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,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(PetscOptionsObject,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: */
 79: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
 80: {
 81:   int             ierr;
 82:   PetscOptionItem next;
 83:   PetscBool       valid;

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

 89:   PetscNew(amsopt);
 90:   (*amsopt)->next = NULL;
 91:   (*amsopt)->set  = PETSC_FALSE;
 92:   (*amsopt)->type = t;
 93:   (*amsopt)->data = NULL;

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

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

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

111:     Collective

113:    Input Parameters:
114: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
115: .     n - length of the string, must be the same on all processes
116: -     str - location to store input

118:     Bugs:
119: .   Assumes process 0 of the given communicator has access to stdin

121: */
122: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
123: {
124:   size_t         i;
125:   char           c;
126:   PetscMPIInt    rank,nm;

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

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

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


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

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

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

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

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

184: */
185: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
186: {
187:   PetscErrorCode  ierr;
188:   PetscOptionItem next = PetscOptionsObject->next;
189:   char            str[512];
190:   PetscBool       bid;
191:   PetscReal       ir,*valr;
192:   PetscInt        *vald;
193:   size_t          i;

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

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

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

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

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

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

365: static int count = 0;

367: PetscErrorCode PetscOptionsSAWsDestroy(void)
368: {
370:   return(0);
371: }

373: static const char *OptionsHeader = "<head>\n"
374:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/jquery-1.9.1.js\"></script>\n"
375:                                    "<script type=\"text/javascript\" src=\"https://www.mcs.anl.gov/research/projects/saws/js/SAWs.js\"></script>\n"
376:                                    "<script type=\"text/javascript\" src=\"js/PETSc.js\"></script>\n"
377:                                    "<script>\n"
378:                                       "jQuery(document).ready(function() {\n"
379:                                          "PETSc.getAndDisplayDirectory(null,\"#variablesInfo\")\n"
380:                                       "})\n"
381:                                   "</script>\n"
382:                                   "</head>\n";

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

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

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


396: */
397: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
398: {
399:   PetscErrorCode  ierr;
400:   PetscOptionItem next     = PetscOptionsObject->next;
401:   static int      mancount = 0;
402:   char            options[16];
403:   PetscBool       changedmethod = PETSC_FALSE;
404:   PetscBool       stopasking    = PETSC_FALSE;
405:   char            manname[16],textname[16];
406:   char            dir[1024];

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

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

414:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
415:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
416:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
417:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
418:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
419:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

421:   while (next) {
422:     sprintf(manname,"_man_%d",mancount);
423:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
424:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
425:     sprintf(textname,"_text_%d",mancount++);
426:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
427:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

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

489:   /* wait until accessor has unlocked the memory */
490:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
491:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
492:   PetscSAWsBlock();
493:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
494:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

496:   /* determine if any values have been set in GUI */
497:   next = PetscOptionsObject->next;
498:   while (next) {
499:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
500:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
501:     next = next->next;
502:   }

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

507:   if (stopasking) {
508:     PetscOptionsPublish      = PETSC_FALSE;
509:     PetscOptionsObject->count = 0;//do not ask for same thing again
510:   }

512:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
513:   return(0);
514: }
515: #endif

517: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
518: {
519:   PetscErrorCode  ierr;
520:   PetscOptionItem last;
521:   char            option[256],value[1024],tmp[32];
522:   size_t          j;

525:   if (PetscOptionsObject->next) {
526:     if (!PetscOptionsObject->count) {
527: #if defined(PETSC_HAVE_SAWS)
528:       PetscOptionsSAWsInput(PetscOptionsObject);
529: #else
530:       PetscOptionsGetFromTextInput(PetscOptionsObject);
531: #endif
532:     }
533:   }

535:   PetscFree(PetscOptionsObject->title);

537:   /* reset counter to -2; this updates the screen with the new options for the selected method */
538:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
539:   /* reset alreadyprinted flag */
540:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
541:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
542:   PetscOptionsObject->object = NULL;

544:   while (PetscOptionsObject->next) {
545:     if (PetscOptionsObject->next->set) {
546:       if (PetscOptionsObject->prefix) {
547:         PetscStrcpy(option,"-");
548:         PetscStrcat(option,PetscOptionsObject->prefix);
549:         PetscStrcat(option,PetscOptionsObject->next->option+1);
550:       } else {
551:         PetscStrcpy(option,PetscOptionsObject->next->option);
552:       }

554:       switch (PetscOptionsObject->next->type) {
555:       case OPTION_HEAD:
556:         break;
557:       case OPTION_INT_ARRAY:
558:         sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[0]);
559:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
560:           sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject->next->data)[j]);
561:           PetscStrcat(value,",");
562:           PetscStrcat(value,tmp);
563:         }
564:         break;
565:       case OPTION_INT:
566:         sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject->next->data);
567:         break;
568:       case OPTION_REAL:
569:         sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject->next->data);
570:         break;
571:       case OPTION_REAL_ARRAY:
572:         sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[0]);
573:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
574:           sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject->next->data)[j]);
575:           PetscStrcat(value,",");
576:           PetscStrcat(value,tmp);
577:         }
578:         break;
579:       case OPTION_SCALAR_ARRAY:
580:         sprintf(value,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[0]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[0]));
581:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
582:           sprintf(tmp,"%g+%gi",(double)PetscRealPart(((PetscScalar*)PetscOptionsObject->next->data)[j]),(double)PetscImaginaryPart(((PetscScalar*)PetscOptionsObject->next->data)[j]));
583:           PetscStrcat(value,",");
584:           PetscStrcat(value,tmp);
585:         }
586:         break;
587:       case OPTION_BOOL:
588:         sprintf(value,"%d",*(int*)PetscOptionsObject->next->data);
589:         break;
590:       case OPTION_BOOL_ARRAY:
591:         sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[0]);
592:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
593:           sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject->next->data)[j]);
594:           PetscStrcat(value,",");
595:           PetscStrcat(value,tmp);
596:         }
597:         break;
598:       case OPTION_FLIST:
599:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
600:         break;
601:       case OPTION_ELIST:
602:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
603:         break;
604:       case OPTION_STRING:
605:         PetscStrcpy(value,(char*)PetscOptionsObject->next->data);
606:         break;
607:       case OPTION_STRING_ARRAY:
608:         sprintf(value,"%s",((char**)PetscOptionsObject->next->data)[0]);
609:         for (j=1; j<PetscOptionsObject->next->arraylength; j++) {
610:           sprintf(tmp,"%s",((char**)PetscOptionsObject->next->data)[j]);
611:           PetscStrcat(value,",");
612:           PetscStrcat(value,tmp);
613:         }
614:         break;
615:       }
616:       PetscOptionsSetValue(PetscOptionsObject->options,option,value);
617:     }
618:     if (PetscOptionsObject->next->type == OPTION_ELIST) {
619:       PetscStrNArrayDestroy(PetscOptionsObject->next->nlist,(char ***)&PetscOptionsObject->next->list);
620:     }
621:     PetscFree(PetscOptionsObject->next->text);
622:     PetscFree(PetscOptionsObject->next->option);
623:     PetscFree(PetscOptionsObject->next->man);
624:     PetscFree(PetscOptionsObject->next->edata);

626:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
627:       free(PetscOptionsObject->next->data);
628:     } else {
629:       PetscFree(PetscOptionsObject->next->data);
630:     }

632:     last                    = PetscOptionsObject->next;
633:     PetscOptionsObject->next = PetscOptionsObject->next->next;
634:     PetscFree(last);
635:   }
636:   PetscFree(PetscOptionsObject->prefix);
637:   PetscOptionsObject->next = NULL;
638:   return(0);
639: }

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

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

646:    Synopsis:
647:    #include "petscsys.h"
648:    PetscErrorCode  PetscOptionsEnum(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)

650:    Input Parameters:
651: +  opt - option name
652: .  text - short string that describes the option
653: .  man - manual page with additional information on option
654: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
655: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
656: $                 PetscOptionsEnum(..., obj->value,&object->value,...) or
657: $                 value = defaultvalue
658: $                 PetscOptionsEnum(..., value,&value,&flg);
659: $                 if (flg) {

661:    Output Parameter:
662: +  value - the  value to return
663: -  set - PETSC_TRUE if found, else PETSC_FALSE

665:    Level: beginner

667:    Notes:
668:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

677: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
678:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
679:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
680:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
681:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
682:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
683:           PetscOptionsFList(), PetscOptionsEList()
684: M*/

686: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
687: {
689:   PetscInt       ntext = 0;
690:   PetscInt       tval;
691:   PetscBool      tflg;

694:   while (list[ntext++]) {
695:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
696:   }
697:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
698:   ntext -= 3;
699:   PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
700:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
701:   if (tflg) *value = (PetscEnum)tval;
702:   if (set)  *set   = tflg;
703:   return(0);
704: }

706: /*MC
707:    PetscOptionsEnumArray - Gets an array of enum values for a particular
708:    option in the database.

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

712:    Synopsis:
713:    #include "petscsys.h"
714:    PetscErrorCode  PetscOptionsEnumArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)

716:    Input Parameters:
717: +  opt - the option one is seeking
718: .  text - short string describing option
719: .  man - manual page for option
720: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
721: -  n - maximum number of values

723:    Output Parameter:
724: +  value - location to copy values
725: .  n - actual number of values found
726: -  set - PETSC_TRUE if found, else PETSC_FALSE

728:    Level: beginner

730:    Notes:
731:    The array must be passed as a comma separated list.

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

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

737: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
738:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
739:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
740:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
741:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
742:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
743: M*/

745: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
746: {
747:   PetscInt        i,nlist = 0;
748:   PetscOptionItem amsopt;
749:   PetscErrorCode  ierr;

752:   while (list[nlist++]) if (nlist > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
753:   if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
754:   nlist -= 3; /* drop enum name, prefix, and null termination */
755:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
756:     PetscEnum *vals;
757:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
758:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
759:     amsopt->nlist = nlist;
760:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
761:     amsopt->arraylength = *n;
762:     vals = (PetscEnum*)amsopt->data;
763:     for (i=0; i<*n; i++) vals[i] = value[i];
764:   }
765:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
766:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
767:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
768:     for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
769:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
770:     for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
771:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
772:   }
773:   return(0);
774: }

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

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

781:    Synopsis:
782:    #include "petscsys.h"
783:    PetscErrorCode  PetscOptionsBoundInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt bound)

785:    Input Parameters:
786: +  opt - option name
787: .  text - short string that describes the option
788: .  man - manual page with additional information on option
789: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
790: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
791: $                 value = defaultvalue
792: $                 PetscOptionsInt(..., value,&value,&flg);
793: $                 if (flg) {
794: -  bound - the requested value should be greater than or equal this bound or an error is generated

796:    Output Parameter:
797: +  value - the integer value to return
798: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

808:    Level: beginner

810: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
811:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
812:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
813:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
814:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
815:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
816:           PetscOptionsFList(), PetscOptionsEList()
817: M*/

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

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

824:    Synopsis:
825:    #include "petscsys.h"
826: PetscErrorCode  PetscOptionsRangeInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg,PetscInt lb,PetscInt ub)

828:    Input Parameters:
829: +  opt - option name
830: .  text - short string that describes the option
831: .  man - manual page with additional information on option
832: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
833: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
834: $                 value = defaultvalue
835: $                 PetscOptionsInt(..., value,&value,&flg);
836: $                 if (flg) {
837: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
838: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

840:    Output Parameter:
841: +  value - the integer value to return
842: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

852:    Level: beginner

854: .seealso: PetscOptionsInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
855:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsBoundedInt()
856:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
857:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
858:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
859:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
860:           PetscOptionsFList(), PetscOptionsEList()
861: M*/

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

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

868:    Synopsis:
869:    #include "petscsys.h"
870: PetscErrorCode  PetscOptionsInt(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool *flg))


873:    Input Parameters:
874: +  opt - option name
875: .  text - short string that describes the option
876: .  man - manual page with additional information on option
877: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
878: $                 PetscOptionsInt(..., obj->value,&obj->value,...) or
879: $                 value = defaultvalue
880: $                 PetscOptionsInt(..., value,&value,&flg);
881: $                 if (flg) {

883:    Output Parameter:
884: +  value - the integer value to return
885: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

895:    Level: beginner

897: .seealso: PetscOptionsBoundedInt(), PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
898:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), PetscOptionsRangeInt()
899:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
900:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
901:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
902:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
903:           PetscOptionsFList(), PetscOptionsEList()
904: M*/

906: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set,PetscInt lb,PetscInt ub)
907: {
908:   PetscErrorCode  ierr;
909:   PetscOptionItem amsopt;
910:   PetscBool       wasset;

913:   if (currentvalue < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D less than allowed bound %D",currentvalue,lb);
914:   if (currentvalue > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Current value %D greater than allowed bound %D",currentvalue,ub);
915:      if (!PetscOptionsObject->count) {
916:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
917:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
918:     *(PetscInt*)amsopt->data = currentvalue;

920:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
921:     if (wasset) {
922:       *(PetscInt*)amsopt->data = currentvalue;
923:     }
924:   }
925:   PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&wasset);
926:   if (wasset && *value < lb) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D less than allowed bound %D",*value,lb);
927:   if (wasset && *value > ub) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Newly set value %D greater than allowed bound %D",*value,ub);
928:   if (set) *set = wasset;
929:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
930:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <now %D : formerly %D>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,wasset && value ? *value : currentvalue,currentvalue,text,ManSection(man));
931:   }
932:   return(0);
933: }

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

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

940:    Synopsis:
941:    #include "petscsys.h"
942:    PetscErrorCode  PetscOptionsString(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)

944:    Input Parameters:
945: +  opt - option name
946: .  text - short string that describes the option
947: .  man - manual page with additional information on option
948: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
949: -  len - length of the result string including null terminator

951:    Output Parameter:
952: +  value - the value to return
953: -  flg - PETSC_TRUE if found, else PETSC_FALSE

955:    Level: beginner

957:    Notes:
958:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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


968: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
969:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
970:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
971:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
972:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
973:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
974:           PetscOptionsFList(), PetscOptionsEList()
975: M*/

977: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
978: {
979:   PetscErrorCode  ierr;
980:   PetscOptionItem amsopt;
981:   PetscBool       lset;

984:   if (!PetscOptionsObject->count) {
985:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
986:     /* must use system malloc since SAWs may free this */
987:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
988:   }
989:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
990:   if (set) *set = lset;
991:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
992:     (*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));
993:   }
994:   return(0);
995: }

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

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

1002:    Synopsis:
1003:    #include "petscsys.h"
1004:    PetscErrorCode  PetscOptionsReal(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)

1006:    Input Parameters:
1007: +  opt - option name
1008: .  text - short string that describes the option
1009: .  man - manual page with additional information on option
1010: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1011: $                 PetscOptionsReal(..., obj->value,&obj->value,...) or
1012: $                 value = defaultvalue
1013: $                 PetscOptionsReal(..., value,&value,&flg);
1014: $                 if (flg) {

1016:    Output Parameter:
1017: +  value - the value to return
1018: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

1028:    Level: beginner

1030: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1031:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1032:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1033:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1034:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1035:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1036:           PetscOptionsFList(), PetscOptionsEList()
1037: M*/

1039: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
1040: {
1041:   PetscErrorCode  ierr;
1042:   PetscOptionItem amsopt;
1043:   PetscBool       lset;

1046:   if (!PetscOptionsObject->count) {
1047:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
1048:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

1050:     *(PetscReal*)amsopt->data = currentvalue;
1051:   }
1052:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,&lset);
1053:   if (set) *set = lset;
1054:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1055:     (*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));
1056:   }
1057:   return(0);
1058: }

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

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

1065:    Synopsis:
1066:    #include "petscsys.h"
1067:    PetscErrorCode PetscOptionsScalar(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)

1069:    Input Parameters:
1070: +  opt - option name
1071: .  text - short string that describes the option
1072: .  man - manual page with additional information on option
1073: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
1074: $                 PetscOptionsScalar(..., obj->value,&obj->value,...) or
1075: $                 value = defaultvalue
1076: $                 PetscOptionsScalar(..., value,&value,&flg);
1077: $                 if (flg) {


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

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

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

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

1092:    Level: beginner

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

1103: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
1104: {

1108: #if !defined(PETSC_USE_COMPLEX)
1109:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
1110: #else
1111:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
1112: #endif
1113:   return(0);
1114: }

1116: /*MC
1117:    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
1118:                       its value is set to false.

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

1122:    Synopsis:
1123:    #include "petscsys.h"
1124:    PetscErrorCode PetscOptionsName(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)

1126:    Input Parameters:
1127: +  opt - option name
1128: .  text - short string that describes the option
1129: -  man - manual page with additional information on option

1131:    Output Parameter:
1132: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1134:    Level: beginner

1136:    Notes:
1137:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1139: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1140:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1141:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1142:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1143:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1144:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1145:           PetscOptionsFList(), PetscOptionsEList()
1146: M*/

1148: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1149: {
1150:   PetscErrorCode  ierr;
1151:   PetscOptionItem amsopt;

1154:   if (!PetscOptionsObject->count) {
1155:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1156:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1158:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1159:   }
1160:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1161:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1162:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1163:   }
1164:   return(0);
1165: }

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

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

1172:    Synopsis:
1173:    #include "petscsys.h"
1174:    PetscErrorCode  PetscOptionsFList(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)

1176:    Input Parameters:
1177: +  opt - option name
1178: .  text - short string that describes the option
1179: .  man - manual page with additional information on option
1180: .  list - the possible choices
1181: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1182: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
1183: $                 if (flg) {
1184: -  len - the length of the character array value

1186:    Output Parameter:
1187: +  value - the value to return
1188: -  set - PETSC_TRUE if found, else PETSC_FALSE

1190:    Level: intermediate

1192:    Notes:
1193:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

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

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

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

1207: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1208:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1209:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1210:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1211:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1212:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1213: M*/

1215: 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)
1216: {
1217:   PetscErrorCode  ierr;
1218:   PetscOptionItem amsopt;
1219:   PetscBool       lset;

1222:   if (!PetscOptionsObject->count) {
1223:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1224:     /* must use system malloc since SAWs may free this */
1225:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1226:     amsopt->flist = list;
1227:   }
1228:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,&lset);
1229:   if (set) *set = lset;
1230:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1231:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue,lset && value ? value : currentvalue);
1232:   }
1233:   return(0);
1234: }

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

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

1241:    Synopsis:
1242:    #include "petscsys.h"
1243:    PetscErrorCode  PetscOptionsEList(PetscOptionItems *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)

1245:    Input Parameters:
1246: +  opt - option name
1247: .  ltext - short string that describes the option
1248: .  man - manual page with additional information on option
1249: .  list - the possible choices (one of these must be selected, anything else is invalid)
1250: .  ntext - number of choices
1251: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1252: $                 PetscOptionsElist(..., obj->value,&value,&flg);
1253: $                 if (flg) {


1256:    Output Parameter:
1257: +  value - the index of the value to return
1258: -  set - PETSC_TRUE if found, else PETSC_FALSE

1260:    Level: intermediate

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

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

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

1270: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1271:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1272:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1273:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1274:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1275:           PetscOptionsFList(), PetscOptionsEnum()
1276: M*/

1278: 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)
1279: {
1280:   PetscErrorCode  ierr;
1281:   PetscInt        i;
1282:   PetscOptionItem amsopt;
1283:   PetscBool       lset;

1286:   if (!PetscOptionsObject->count) {
1287:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1288:     /* must use system malloc since SAWs may free this */
1289:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1290:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1291:     amsopt->nlist = ntext;
1292:   }
1293:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,&lset);
1294:   if (set) *set = lset;
1295:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1296:     (*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);
1297:     for (i=0; i<ntext; i++) {
1298:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1299:     }
1300:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1301:   }
1302:   return(0);
1303: }

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

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

1311:    Synopsis:
1312:    #include "petscsys.h"
1313:    PetscErrorCode PetscOptionsBoolGroupBegin(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)

1315:    Input Parameters:
1316: +  opt - option name
1317: .  text - short string that describes the option
1318: -  man - manual page with additional information on option

1320:    Output Parameter:
1321: .  flg - whether that option was set or not

1323:    Level: intermediate

1325:    Notes:
1326:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

1338: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1339: {
1340:   PetscErrorCode  ierr;
1341:   PetscOptionItem amsopt;

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

1348:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1349:   }
1350:   *flg = PETSC_FALSE;
1351:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1352:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1353:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
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:      PetscOptionsBoolGroup - One 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 PetscOptionsBoolGroup(PetscOptionItems *PetscOptionsObject,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() and preceded a PetscOptionsBoolGroupEnd()

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  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1393: {
1394:   PetscErrorCode  ierr;
1395:   PetscOptionItem amsopt;

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

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

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

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

1418:    Synopsis:
1419:    #include "petscsys.h"
1420:    PetscErrorCode PetscOptionsBoolGroupEnd(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)

1422:    Input Parameters:
1423: +  opt - option name
1424: .  text - short string that describes the option
1425: -  man - manual page with additional information on option

1427:    Output Parameter:
1428: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1430:    Level: intermediate

1432:    Notes:
1433:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

1435:    Must follow a PetscOptionsBoolGroupBegin()

1437: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1438:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1439:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1440:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1441:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1442:           PetscOptionsFList(), PetscOptionsEList()
1443: M*/

1445: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1446: {
1447:   PetscErrorCode  ierr;
1448:   PetscOptionItem amsopt;

1451:   if (!PetscOptionsObject->count) {
1452:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1453:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1455:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1456:   }
1457:   *flg = PETSC_FALSE;
1458:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1459:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1460:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1461:   }
1462:   return(0);
1463: }

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

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

1470:    Synopsis:
1471:    #include "petscsys.h"
1472:    PetscErrorCode PetscOptionsBool(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)

1474:    Input Parameters:
1475: +  opt - option name
1476: .  text - short string that describes the option
1477: .  man - manual page with additional information on option
1478: -  currentvalue - the current value

1480:    Output Parameter:
1481: +  flg - PETSC_TRUE or PETSC_FALSE
1482: -  set - PETSC_TRUE if found, else PETSC_FALSE

1484:    Notes:
1485:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1486:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1488:       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
1489:      is equivalent to -requested_bool true

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

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

1496:    Level: beginner

1498: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1499:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1500:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1501:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1502:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1503:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1504:           PetscOptionsFList(), PetscOptionsEList()
1505: M*/

1507: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1508: {
1509:   PetscErrorCode  ierr;
1510:   PetscBool       iset;
1511:   PetscOptionItem amsopt;

1514:   if (!PetscOptionsObject->count) {
1515:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1516:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1518:     *(PetscBool*)amsopt->data = currentvalue;
1519:   }
1520:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1521:   if (set) *set = iset;
1522:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1523:     const char *v = PetscBools[currentvalue], *vn = PetscBools[iset && flg ? *flg : currentvalue];
1524:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s : %s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,vn,text,ManSection(man));
1525:   }
1526:   return(0);
1527: }

1529: /*MC
1530:    PetscOptionsRealArray - Gets an array of double values for a particular
1531:    option in the database. The values must be separated with commas with
1532:    no intervening spaces.

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

1536:    Synopsis:
1537:    #include "petscsys.h"
1538:    PetscErrorCode PetscOptionsRealArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)

1540:    Input Parameters:
1541: +  opt - the option one is seeking
1542: .  text - short string describing option
1543: .  man - manual page for option
1544: -  nmax - maximum number of values

1546:    Output Parameter:
1547: +  value - location to copy values
1548: .  nmax - actual number of values found
1549: -  set - PETSC_TRUE if found, else PETSC_FALSE

1551:    Level: beginner

1553:    Notes:
1554:    The user should pass in an array of doubles

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

1558: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1559:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1560:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1561:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1562:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1563:           PetscOptionsFList(), PetscOptionsEList()
1564: M*/

1566: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1567: {
1568:   PetscErrorCode  ierr;
1569:   PetscInt        i;
1570:   PetscOptionItem amsopt;

1573:   if (!PetscOptionsObject->count) {
1574:     PetscReal *vals;

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

1593: /*MC
1594:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1595:    option in the database. The values must be separated with commas with
1596:    no intervening spaces.

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

1600:    Synopsis:
1601:    #include "petscsys.h"
1602:    PetscErrorCode PetscOptionsScalarArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)

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

1610:    Output Parameter:
1611: +  value - location to copy values
1612: .  nmax - actual number of values found
1613: -  set - PETSC_TRUE if found, else PETSC_FALSE

1615:    Level: beginner

1617:    Notes:
1618:    The user should pass in an array of doubles

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

1622: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1623:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1624:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1625:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1626:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1627:           PetscOptionsFList(), PetscOptionsEList()
1628: M*/

1630: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1631: {
1632:   PetscErrorCode  ierr;
1633:   PetscInt        i;
1634:   PetscOptionItem amsopt;

1637:   if (!PetscOptionsObject->count) {
1638:     PetscScalar *vals;

1640:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1641:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1642:     vals = (PetscScalar*)amsopt->data;
1643:     for (i=0; i<*n; i++) vals[i] = value[i];
1644:     amsopt->arraylength = *n;
1645:   }
1646:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1647:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1648:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1649:     for (i=1; i<*n; i++) {
1650:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1651:     }
1652:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1653:   }
1654:   return(0);
1655: }

1657: /*MC
1658:    PetscOptionsIntArray - Gets an array of integers for a particular
1659:    option in the database.

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

1663:    Synopsis:
1664:    #include "petscsys.h"
1665:    PetscErrorCode PetscOptionsIntArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)

1667:    Input Parameters:
1668: +  opt - the option one is seeking
1669: .  text - short string describing option
1670: .  man - manual page for option
1671: -  n - maximum number of values

1673:    Output Parameter:
1674: +  value - location to copy values
1675: .  n - actual number of values found
1676: -  set - PETSC_TRUE if found, else PETSC_FALSE

1678:    Level: beginner

1680:    Notes:
1681:    The array can be passed as
1682:    a comma separated list:                                 0,1,2,3,4,5,6,7
1683:    a range (start-end+1):                                  0-8
1684:    a range with given increment (start-end+1:inc):         0-7:2
1685:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

1691: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1692:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1693:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1694:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1695:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1696:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1697: M*/

1699: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1700: {
1702:   PetscInt        i;
1703:   PetscOptionItem amsopt;

1706:   if (!PetscOptionsObject->count) {
1707:     PetscInt *vals;

1709:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1710:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1711:     vals = (PetscInt*)amsopt->data;
1712:     for (i=0; i<*n; i++) vals[i] = value[i];
1713:     amsopt->arraylength = *n;
1714:   }
1715:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1716:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1717:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1718:     for (i=1; i<*n; i++) {
1719:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1720:     }
1721:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1722:   }
1723:   return(0);
1724: }

1726: /*MC
1727:    PetscOptionsStringArray - Gets an array of string values for a particular
1728:    option in the database. The values must be separated with commas with
1729:    no intervening spaces.

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

1733:    Synopsis:
1734:    #include "petscsys.h"
1735:    PetscErrorCode PetscOptionsStringArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)

1737:    Input Parameters:
1738: +  opt - the option one is seeking
1739: .  text - short string describing option
1740: .  man - manual page for option
1741: -  nmax - maximum number of strings

1743:    Output Parameter:
1744: +  value - location to copy strings
1745: .  nmax - actual number of strings found
1746: -  set - PETSC_TRUE if found, else PETSC_FALSE

1748:    Level: beginner

1750:    Notes:
1751:    The user should pass in an array of pointers to char, to hold all the
1752:    strings returned by this function.

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

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

1759: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1760:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1761:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1762:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1763:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1764:           PetscOptionsFList(), PetscOptionsEList()
1765: M*/

1767: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1768: {
1769:   PetscErrorCode  ierr;
1770:   PetscOptionItem amsopt;

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

1777:     amsopt->arraylength = *nmax;
1778:   }
1779:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1780:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1781:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1782:   }
1783:   return(0);
1784: }

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

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

1793:    Synopsis:
1794:    #include "petscsys.h"
1795:    PetscErrorCode PetscOptionsBoolArray(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)

1797:    Input Parameters:
1798: +  opt - the option one is seeking
1799: .  text - short string describing option
1800: .  man - manual page for option
1801: -  nmax - maximum number of values

1803:    Output Parameter:
1804: +  value - location to copy values
1805: .  nmax - actual number of values found
1806: -  set - PETSC_TRUE if found, else PETSC_FALSE

1808:    Level: beginner

1810:    Notes:
1811:    The user should pass in an array of doubles

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

1815: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1816:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1817:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1818:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1819:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1820:           PetscOptionsFList(), PetscOptionsEList()
1821: M*/

1823: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1824: {
1825:   PetscErrorCode   ierr;
1826:   PetscInt         i;
1827:   PetscOptionItem  amsopt;

1830:   if (!PetscOptionsObject->count) {
1831:     PetscBool *vals;

1833:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1834:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1835:     vals = (PetscBool*)amsopt->data;
1836:     for (i=0; i<*n; i++) vals[i] = value[i];
1837:     amsopt->arraylength = *n;
1838:   }
1839:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1840:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1841:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1842:     for (i=1; i<*n; i++) {
1843:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1844:     }
1845:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1846:   }
1847:   return(0);
1848: }

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

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

1855:    Synopsis:
1856:    #include "petscsys.h"
1857:    PetscErrorCode PetscOptionsViewer(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)

1859:    Input Parameters:
1860: +  opt - option name
1861: .  text - short string that describes the option
1862: -  man - manual page with additional information on option

1864:    Output Parameter:
1865: +  viewer - the viewer
1866: -  set - PETSC_TRUE if found, else PETSC_FALSE

1868:    Level: beginner

1870:    Notes:
1871:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1875: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1876:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1877:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1878:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1879:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1880:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1881:           PetscOptionsFList(), PetscOptionsEList()
1882: M*/

1884: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1885: {
1886:   PetscErrorCode  ierr;
1887:   PetscOptionItem amsopt;

1890:   if (!PetscOptionsObject->count) {
1891:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1892:     /* must use system malloc since SAWs may free this */
1893:     PetscStrdup("",(char**)&amsopt->data);
1894:   }
1895:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->options,PetscOptionsObject->prefix,opt,viewer,format,set);
1896:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1897:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1898:   }
1899:   return(0);
1900: }

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

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

1908:    Input Parameter:
1909: .   head - the heading text


1912:    Level: intermediate

1914:    Notes:
1915:     Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

1919: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1920:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1921:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1922:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1923:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1924:           PetscOptionsFList(), PetscOptionsEList()
1925: @*/
1926: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1927: {

1931:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1932:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1933:   }
1934:   return(0);
1935: }