Actual source code: aoptions.c

petsc-master 2017-02-23
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          = 0;
 37:   PetscOptionsObject->comm          = comm;
 38:   PetscOptionsObject->changedmethod = PETSC_FALSE;

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

 43:   PetscOptionsHasName(PetscOptionsObject->options,NULL,"-help",&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 = 0;
 91:   (*amsopt)->set  = PETSC_FALSE;
 92:   (*amsopt)->type = t;
 93:   (*amsopt)->data = 0;

 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 on MPI_Comm

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 = 0;

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: this isn't really practical, it is just to demonstrate the principle

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

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

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

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

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

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

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

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

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

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

363: static int count = 0;

365: PetscErrorCode PetscOptionsSAWsDestroy(void)
366: {
368:   return(0);
369: }

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

533:   PetscFree(PetscOptionsObject->title);

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

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

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

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

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

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

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

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

655:    Output Parameter:
656: +  value - the  value to return
657: -  set - PETSC_TRUE if found, else PETSC_FALSE

659:    Level: beginner

661:    Concepts: options database

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

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

667: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
668:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
669:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
670:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
671:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
672:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
673:           PetscOptionsFList(), PetscOptionsEList()
674: @*/
675: PetscErrorCode  PetscOptionsEnum_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum currentvalue,PetscEnum *value,PetscBool  *set)
676: {
678:   PetscInt       ntext = 0;
679:   PetscInt       tval;
680:   PetscBool      tflg;

683:   while (list[ntext++]) {
684:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
685:   }
686:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
687:   ntext -= 3;
688:   PetscOptionsEList_Private(PetscOptionsObject,opt,text,man,list,ntext,list[currentvalue],&tval,&tflg);
689:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
690:   if (tflg) *value = (PetscEnum)tval;
691:   if (set)  *set   = tflg;
692:   return(0);
693: }

695: /*@C
696:    PetscOptionsEnumArray - Gets an array of enum values for a particular
697:    option in the database.

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

701:    Input Parameters:
702: +  opt - the option one is seeking
703: .  text - short string describing option
704: .  man - manual page for option
705: -  n - maximum number of values

707:    Output Parameter:
708: +  value - location to copy values
709: .  n - actual number of values found
710: -  set - PETSC_TRUE if found, else PETSC_FALSE

712:    Level: beginner

714:    Notes:
715:    The array must be passed as a comma separated list.

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

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

721:    Concepts: options database^array of enums

723: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
724:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
725:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
726:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
727:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
728:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
729: @*/
730: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
731: {
732:   PetscInt        i,nlist = 0;
733:   PetscOptionItem amsopt;
734:   PetscErrorCode  ierr;

737:   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");
738:   if (nlist < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
739:   nlist -= 3; /* drop enum name, prefix, and null termination */
740:   if (0 && !PetscOptionsObject->count) { /* XXX Requires additional support */
741:     PetscEnum *vals;
742:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY/*XXX OPTION_ENUM_ARRAY*/,&amsopt);
743:     PetscStrNArrayallocpy(nlist,list,(char***)&amsopt->list);
744:     amsopt->nlist = nlist;
745:     PetscMalloc1(*n,(PetscEnum**)&amsopt->data);
746:     amsopt->arraylength = *n;
747:     vals = (PetscEnum*)amsopt->data;
748:     for (i=0; i<*n; i++) vals[i] = value[i];
749:   }
750:   PetscOptionsGetEnumArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,value,n,set);
751:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
752:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,list[value[0]]);
753:     for (i=1; i<*n; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm,",%s",list[value[i]]);}
754:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (choose from)",text);
755:     for (i=0; i<nlist; i++) {(*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);}
756:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
757:   }
758:   return(0);
759: }

761: /* -------------------------------------------------------------------------------------------------------------*/
762: /*@C
763:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

767:    Input Parameters:
768: +  opt - option name
769: .  text - short string that describes the option
770: .  man - manual page with additional information on option
771: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
772: $                 PetscOptionsInt(..., obj->value,&object->value,...) or
773: $                 value = defaultvalue
774: $                 PetscOptionsInt(..., value,&value,&flg);
775: $                 if (flg) {

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

781:    Level: beginner

783:    Concepts: options database^has int

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

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

802:   if (!PetscOptionsObject->count) {
803:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
804:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
805:     *(PetscInt*)amsopt->data = currentvalue;

807:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
808:     if (wasset) {
809:       *(PetscInt*)amsopt->data = currentvalue;
810:     }
811:   }
812:   PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
813:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
814:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
815:   }
816:   return(0);
817: }

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

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

824:    Input Parameters:
825: +  opt - option name
826: .  text - short string that describes the option
827: .  man - manual page with additional information on option
828: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
829: -  len - length of the result string including null terminator

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

835:    Level: beginner

837:    Concepts: options database^has int

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

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

843: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
844:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
845:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
846:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
847:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
848:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
849:           PetscOptionsFList(), PetscOptionsEList()
850: @*/
851: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
852: {
853:   PetscErrorCode  ierr;
854:   PetscOptionItem amsopt;

857:   if (!PetscOptionsObject->count) {
858:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
859:     /* must use system malloc since SAWs may free this */
860:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
861:   }
862:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
863:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
864:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
865:   }
866:   return(0);
867: }

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

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

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

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

888:    Level: beginner

890:    Concepts: options database^has int

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

894: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
895:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
896:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
897:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
898:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
899:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
900:           PetscOptionsFList(), PetscOptionsEList()
901: @*/
902: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
903: {
904:   PetscErrorCode  ierr;
905:   PetscOptionItem amsopt;

908:   if (!PetscOptionsObject->count) {
909:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
910:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

912:     *(PetscReal*)amsopt->data = currentvalue;
913:   }
914:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
915:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
916:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
917:   }
918:   return(0);
919: }

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

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

926:    Input Parameters:
927: +  opt - option name
928: .  text - short string that describes the option
929: .  man - manual page with additional information on option
930: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
931: $                 PetscOptionsScalar(..., obj->value,&object->value,...) or
932: $                 value = defaultvalue
933: $                 PetscOptionsScalar(..., value,&value,&flg);
934: $                 if (flg) {


937:    Output Parameter:
938: +  value - the value to return
939: -  flg - PETSC_TRUE if found, else PETSC_FALSE

941:    Level: beginner

943:    Concepts: options database^has int

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

947: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
948:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
949:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
950:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
951:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
952:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
953:           PetscOptionsFList(), PetscOptionsEList()
954: @*/
955: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
956: {

960: #if !defined(PETSC_USE_COMPLEX)
961:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
962: #else
963:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
964: #endif
965:   return(0);
966: }

968: /*@C
969:    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
970:                       its value is set to false.

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

974:    Input Parameters:
975: +  opt - option name
976: .  text - short string that describes the option
977: -  man - manual page with additional information on option

979:    Output Parameter:
980: .  flg - PETSC_TRUE if found, else PETSC_FALSE

982:    Level: beginner

984:    Concepts: options database^has int

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

988: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
989:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
990:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
991:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
992:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
993:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
994:           PetscOptionsFList(), PetscOptionsEList()
995: @*/
996: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
997: {
998:   PetscErrorCode  ierr;
999:   PetscOptionItem amsopt;

1002:   if (!PetscOptionsObject->count) {
1003:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1004:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1006:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1007:   }
1008:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1009:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1010:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1011:   }
1012:   return(0);
1013: }

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

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

1020:    Input Parameters:
1021: +  opt - option name
1022: .  text - short string that describes the option
1023: .  man - manual page with additional information on option
1024: .  list - the possible choices
1025: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1026: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
1027: $                 if (flg) {
1028: -  len - the length of the character array value

1030:    Output Parameter:
1031: +  value - the value to return
1032: -  set - PETSC_TRUE if found, else PETSC_FALSE

1034:    Level: intermediate

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

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

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

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

1045:    Concepts: options database^list

1047: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1048:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1049:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1050:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1051:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1052:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1053: @*/
1054: 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)
1055: {
1056:   PetscErrorCode  ierr;
1057:   PetscOptionItem amsopt;

1060:   if (!PetscOptionsObject->count) {
1061:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1062:     /* must use system malloc since SAWs may free this */
1063:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1064:     amsopt->flist = list;
1065:   }
1066:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1067:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1068:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1069:   }
1070:   return(0);
1071: }

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

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

1078:    Input Parameters:
1079: +  opt - option name
1080: .  ltext - short string that describes the option
1081: .  man - manual page with additional information on option
1082: .  list - the possible choices (one of these must be selected, anything else is invalid)
1083: .  ntext - number of choices
1084: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1085: $                 PetscOptionsElist(..., obj->value,&value,&flg);
1086: $                 if (flg) {


1089:    Output Parameter:
1090: +  value - the index of the value to return
1091: -  set - PETSC_TRUE if found, else PETSC_FALSE

1093:    Level: intermediate

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

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

1099:    Concepts: options database^list

1101: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1102:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1103:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1104:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1105:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1106:           PetscOptionsFList(), PetscOptionsEnum()
1107: @*/
1108: 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)
1109: {
1110:   PetscErrorCode  ierr;
1111:   PetscInt        i;
1112:   PetscOptionItem amsopt;

1115:   if (!PetscOptionsObject->count) {
1116:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1117:     /* must use system malloc since SAWs may free this */
1118:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1119:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1120:     amsopt->nlist = ntext;
1121:   }
1122:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1123:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1124:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1125:     for (i=0; i<ntext; i++) {
1126:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1127:     }
1128:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1129:   }
1130:   return(0);
1131: }

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

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

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

1144:    Output Parameter:
1145: .  flg - whether that option was set or not

1147:    Level: intermediate

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

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

1153:     Concepts: options database^logical group

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

1168:   if (!PetscOptionsObject->count) {
1169:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1170:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

1189:    Input Parameters:
1190: +  opt - option name
1191: .  text - short string that describes the option
1192: -  man - manual page with additional information on option

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

1197:    Level: intermediate

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

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

1203:     Concepts: options database^logical group

1205: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1206:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1207:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1208:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1209:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1210:           PetscOptionsFList(), PetscOptionsEList()
1211: @*/
1212: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1213: {
1214:   PetscErrorCode  ierr;
1215:   PetscOptionItem amsopt;

1218:   if (!PetscOptionsObject->count) {
1219:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1220:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1222:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1223:   }
1224:   *flg = PETSC_FALSE;
1225:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1226:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1227:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1228:   }
1229:   return(0);
1230: }

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

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

1238:    Input Parameters:
1239: +  opt - option name
1240: .  text - short string that describes the option
1241: -  man - manual page with additional information on option

1243:    Output Parameter:
1244: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1246:    Level: intermediate

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

1250:    Must follow a PetscOptionsBoolGroupBegin()

1252:     Concepts: options database^logical group

1254: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1255:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1256:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1257:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1258:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1259:           PetscOptionsFList(), PetscOptionsEList()
1260: @*/
1261: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1262: {
1263:   PetscErrorCode  ierr;
1264:   PetscOptionItem amsopt;

1267:   if (!PetscOptionsObject->count) {
1268:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1269:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1271:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1272:   }
1273:   *flg = PETSC_FALSE;
1274:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1275:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1276:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1277:   }
1278:   return(0);
1279: }

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

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

1286:    Input Parameters:
1287: +  opt - option name
1288: .  text - short string that describes the option
1289: .  man - manual page with additional information on option
1290: -  currentvalue - the current value

1292:    Output Parameter:
1293: .  flg - PETSC_TRUE or PETSC_FALSE
1294: .  set - PETSC_TRUE if found, else PETSC_FALSE

1296:    Level: beginner

1298:    Concepts: options database^logical

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

1302: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1303:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1304:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1305:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1306:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1307:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1308:           PetscOptionsFList(), PetscOptionsEList()
1309: @*/
1310: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1311: {
1312:   PetscErrorCode  ierr;
1313:   PetscBool       iset;
1314:   PetscOptionItem amsopt;

1317:   if (!PetscOptionsObject->count) {
1318:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1319:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1321:     *(PetscBool*)amsopt->data = currentvalue;
1322:   }
1323:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1324:   if (set) *set = iset;
1325:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1326:     const char *v = PetscBools[currentvalue];
1327:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1328:   }
1329:   return(0);
1330: }

1332: /*@C
1333:    PetscOptionsRealArray - Gets an array of double values for a particular
1334:    option in the database. The values must be separated with commas with
1335:    no intervening spaces.

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

1339:    Input Parameters:
1340: +  opt - the option one is seeking
1341: .  text - short string describing option
1342: .  man - manual page for option
1343: -  nmax - maximum number of values

1345:    Output Parameter:
1346: +  value - location to copy values
1347: .  nmax - actual number of values found
1348: -  set - PETSC_TRUE if found, else PETSC_FALSE

1350:    Level: beginner

1352:    Notes:
1353:    The user should pass in an array of doubles

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

1357:    Concepts: options database^array of strings

1359: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1360:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1361:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1362:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1363:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1364:           PetscOptionsFList(), PetscOptionsEList()
1365: @*/
1366: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1367: {
1368:   PetscErrorCode  ierr;
1369:   PetscInt        i;
1370:   PetscOptionItem amsopt;

1373:   if (!PetscOptionsObject->count) {
1374:     PetscReal *vals;

1376:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1377:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1378:     vals = (PetscReal*)amsopt->data;
1379:     for (i=0; i<*n; i++) vals[i] = value[i];
1380:     amsopt->arraylength = *n;
1381:   }
1382:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1383:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1384:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1385:     for (i=1; i<*n; i++) {
1386:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1387:     }
1388:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1389:   }
1390:   return(0);
1391: }

1393: /*@C
1394:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1395:    option in the database. The values must be separated with commas with
1396:    no intervening spaces.

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

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

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

1411:    Level: beginner

1413:    Notes:
1414:    The user should pass in an array of doubles

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

1418:    Concepts: options database^array of strings

1420: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1421:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1422:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1423:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1424:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1425:           PetscOptionsFList(), PetscOptionsEList()
1426: @*/
1427: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1428: {
1429:   PetscErrorCode  ierr;
1430:   PetscInt        i;
1431:   PetscOptionItem amsopt;

1434:   if (!PetscOptionsObject->count) {
1435:     PetscScalar *vals;

1437:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1438:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1439:     vals = (PetscScalar*)amsopt->data;
1440:     for (i=0; i<*n; i++) vals[i] = value[i];
1441:     amsopt->arraylength = *n;
1442:   }
1443:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1444:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1445:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1446:     for (i=1; i<*n; i++) {
1447:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1448:     }
1449:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1450:   }
1451:   return(0);
1452: }

1454: /*@C
1455:    PetscOptionsIntArray - Gets an array of integers for a particular
1456:    option in the database.

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

1460:    Input Parameters:
1461: +  opt - the option one is seeking
1462: .  text - short string describing option
1463: .  man - manual page for option
1464: -  n - maximum number of values

1466:    Output Parameter:
1467: +  value - location to copy values
1468: .  n - actual number of values found
1469: -  set - PETSC_TRUE if found, else PETSC_FALSE

1471:    Level: beginner

1473:    Notes:
1474:    The array can be passed as
1475:    a comma separated list:                                 0,1,2,3,4,5,6,7
1476:    a range (start-end+1):                                  0-8
1477:    a range with given increment (start-end+1:inc):         0-7:2
1478:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

1484:    Concepts: options database^array of ints

1486: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1487:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1488:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1489:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1490:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1491:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1492: @*/
1493: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1494: {
1496:   PetscInt        i;
1497:   PetscOptionItem amsopt;

1500:   if (!PetscOptionsObject->count) {
1501:     PetscInt *vals;

1503:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1504:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1505:     vals = (PetscInt*)amsopt->data;
1506:     for (i=0; i<*n; i++) vals[i] = value[i];
1507:     amsopt->arraylength = *n;
1508:   }
1509:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1510:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1511:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1512:     for (i=1; i<*n; i++) {
1513:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1514:     }
1515:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1516:   }
1517:   return(0);
1518: }

1520: /*@C
1521:    PetscOptionsStringArray - Gets an array of string values for a particular
1522:    option in the database. The values must be separated with commas with
1523:    no intervening spaces.

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

1527:    Input Parameters:
1528: +  opt - the option one is seeking
1529: .  text - short string describing option
1530: .  man - manual page for option
1531: -  nmax - maximum number of strings

1533:    Output Parameter:
1534: +  value - location to copy strings
1535: .  nmax - actual number of strings found
1536: -  set - PETSC_TRUE if found, else PETSC_FALSE

1538:    Level: beginner

1540:    Notes:
1541:    The user should pass in an array of pointers to char, to hold all the
1542:    strings returned by this function.

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

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

1549:    Concepts: options database^array of strings

1551: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1552:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1553:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1554:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1555:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1556:           PetscOptionsFList(), PetscOptionsEList()
1557: @*/
1558: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1559: {
1560:   PetscErrorCode  ierr;
1561:   PetscOptionItem amsopt;

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

1568:     amsopt->arraylength = *nmax;
1569:   }
1570:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1571:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1572:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1573:   }
1574:   return(0);
1575: }

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

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

1584:    Input Parameters:
1585: +  opt - the option one is seeking
1586: .  text - short string describing option
1587: .  man - manual page for option
1588: -  nmax - maximum number of values

1590:    Output Parameter:
1591: +  value - location to copy values
1592: .  nmax - actual number of values found
1593: -  set - PETSC_TRUE if found, else PETSC_FALSE

1595:    Level: beginner

1597:    Notes:
1598:    The user should pass in an array of doubles

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

1602:    Concepts: options database^array of strings

1604: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1605:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1606:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1607:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1608:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1609:           PetscOptionsFList(), PetscOptionsEList()
1610: @*/
1611: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1612: {
1613:   PetscErrorCode   ierr;
1614:   PetscInt         i;
1615:   PetscOptionItem  amsopt;

1618:   if (!PetscOptionsObject->count) {
1619:     PetscBool *vals;

1621:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1622:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1623:     vals = (PetscBool*)amsopt->data;
1624:     for (i=0; i<*n; i++) vals[i] = value[i];
1625:     amsopt->arraylength = *n;
1626:   }
1627:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1628:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1629:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1630:     for (i=1; i<*n; i++) {
1631:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1632:     }
1633:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1634:   }
1635:   return(0);
1636: }

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

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

1643:    Input Parameters:
1644: +  opt - option name
1645: .  text - short string that describes the option
1646: -  man - manual page with additional information on option

1648:    Output Parameter:
1649: +  viewer - the viewer
1650: -  set - PETSC_TRUE if found, else PETSC_FALSE

1652:    Level: beginner

1654:    Concepts: options database^has int

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

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

1660: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1661:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1662:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1663:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1664:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1665:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1666:           PetscOptionsFList(), PetscOptionsEList()
1667: @*/
1668: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1669: {
1670:   PetscErrorCode  ierr;
1671:   PetscOptionItem amsopt;

1674:   if (!PetscOptionsObject->count) {
1675:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1676:     /* must use system malloc since SAWs may free this */
1677:     PetscStrdup("",(char**)&amsopt->data);
1678:   }
1679:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
1680:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1681:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1682:   }
1683:   return(0);
1684: }


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

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

1693:    Input Parameter:
1694: .   head - the heading text


1697:    Level: intermediate

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

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

1703:    Concepts: options database^subheading

1705: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1706:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1707:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1708:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1709:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1710:           PetscOptionsFList(), PetscOptionsEList()
1711: @*/
1712: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1713: {

1717:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1718:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1719:   }
1720:   return(0);
1721: }