Actual source code: aoptions.c

petsc-master 2017-12-14
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:           If the user does not supply the option at all value is NOT changed. Thus
668:           you should ALWAYS initialize value if you access it without first checking if the set flag is true.

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

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

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

700: /*@C
701:    PetscOptionsEnumArray - Gets an array of enum values for a particular
702:    option in the database.

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

706:    Input Parameters:
707: +  opt - the option one is seeking
708: .  text - short string describing option
709: .  man - manual page for option
710: -  n - maximum number of values

712:    Output Parameter:
713: +  value - location to copy values
714: .  n - actual number of values found
715: -  set - PETSC_TRUE if found, else PETSC_FALSE

717:    Level: beginner

719:    Notes:
720:    The array must be passed as a comma separated list.

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

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

726:    Concepts: options database^array of enums

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

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

766: /* -------------------------------------------------------------------------------------------------------------*/
767: /*@C
768:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

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

782:    Output Parameter:
783: +  value - the integer value to return
784: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

791:    Level: beginner

793:    Concepts: options database^has int

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

797: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
798:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
799:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
800:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
801:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
802:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
803:           PetscOptionsFList(), PetscOptionsEList()
804: @*/
805: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set)
806: {
807:   PetscErrorCode  ierr;
808:   PetscOptionItem amsopt;
809:   PetscBool       wasset;

812:   if (!PetscOptionsObject->count) {
813:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
814:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
815:     *(PetscInt*)amsopt->data = currentvalue;

817:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
818:     if (wasset) {
819:       *(PetscInt*)amsopt->data = currentvalue;
820:     }
821:   }
822:   PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
823:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
824:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
825:   }
826:   return(0);
827: }

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

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

834:    Input Parameters:
835: +  opt - option name
836: .  text - short string that describes the option
837: .  man - manual page with additional information on option
838: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
839: -  len - length of the result string including null terminator

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

845:    Level: beginner

847:    Concepts: options database^has int

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

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

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

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


859: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
860:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
861:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
862:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
863:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
864:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
865:           PetscOptionsFList(), PetscOptionsEList()
866: @*/
867: PetscErrorCode  PetscOptionsString_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
868: {
869:   PetscErrorCode  ierr;
870:   PetscOptionItem amsopt;

873:   if (!PetscOptionsObject->count) {
874:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
875:     /* must use system malloc since SAWs may free this */
876:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
877:   }
878:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
879:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
880:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
881:   }
882:   return(0);
883: }

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

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

890:    Input Parameters:
891: +  opt - option name
892: .  text - short string that describes the option
893: .  man - manual page with additional information on option
894: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
895: $                 PetscOptionsReal(..., obj->value,&object->value,...) or
896: $                 value = defaultvalue
897: $                 PetscOptionsReal(..., value,&value,&flg);
898: $                 if (flg) {

900:    Output Parameter:
901: +  value - the value to return
902: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

909:    Level: beginner

911:    Concepts: options database^has int

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

915: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
916:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
917:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
918:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
919:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
920:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
921:           PetscOptionsFList(), PetscOptionsEList()
922: @*/
923: PetscErrorCode  PetscOptionsReal_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal currentvalue,PetscReal *value,PetscBool  *set)
924: {
925:   PetscErrorCode  ierr;
926:   PetscOptionItem amsopt;

929:   if (!PetscOptionsObject->count) {
930:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
931:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

933:     *(PetscReal*)amsopt->data = currentvalue;
934:   }
935:   PetscOptionsGetReal(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
936:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
937:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,(double)currentvalue,text,ManSection(man));
938:   }
939:   return(0);
940: }

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

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

947:    Input Parameters:
948: +  opt - option name
949: .  text - short string that describes the option
950: .  man - manual page with additional information on option
951: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
952: $                 PetscOptionsScalar(..., obj->value,&object->value,...) or
953: $                 value = defaultvalue
954: $                 PetscOptionsScalar(..., value,&value,&flg);
955: $                 if (flg) {


958:    Output Parameter:
959: +  value - the value to return
960: -  flg - PETSC_TRUE if found, else PETSC_FALSE

962:    Notes: 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.

967:    Level: beginner

969:    Concepts: options database^has int

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

973: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
974:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
975:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
976:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
977:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
978:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
979:           PetscOptionsFList(), PetscOptionsEList()
980: @*/
981: PetscErrorCode  PetscOptionsScalar_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
982: {

986: #if !defined(PETSC_USE_COMPLEX)
987:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
988: #else
989:   PetscOptionsGetScalar(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,set);
990: #endif
991:   return(0);
992: }

994: /*@C
995:    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
996:                       its value is set to false.

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

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

1005:    Output Parameter:
1006: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1008:    Level: beginner

1010:    Concepts: options database^has int

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

1014: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1015:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1016:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1017:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1018:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1019:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1020:           PetscOptionsFList(), PetscOptionsEList()
1021: @*/
1022: PetscErrorCode  PetscOptionsName_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1023: {
1024:   PetscErrorCode  ierr;
1025:   PetscOptionItem amsopt;

1028:   if (!PetscOptionsObject->count) {
1029:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1030:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1032:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1033:   }
1034:   PetscOptionsHasName(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg);
1035:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1036:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1037:   }
1038:   return(0);
1039: }

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

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

1046:    Input Parameters:
1047: +  opt - option name
1048: .  text - short string that describes the option
1049: .  man - manual page with additional information on option
1050: .  list - the possible choices
1051: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1052: $                 PetscOptionsFlist(..., obj->value,value,len,&flg);
1053: $                 if (flg) {
1054: -  len - the length of the character array value

1056:    Output Parameter:
1057: +  value - the value to return
1058: -  set - PETSC_TRUE if found, else PETSC_FALSE

1060:    Level: intermediate

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

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

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

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

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

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

1076:    Concepts: options database^list

1078: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1079:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1080:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1081:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1082:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1083:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1084: @*/
1085: 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)
1086: {
1087:   PetscErrorCode  ierr;
1088:   PetscOptionItem amsopt;

1091:   if (!PetscOptionsObject->count) {
1092:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1093:     /* must use system malloc since SAWs may free this */
1094:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1095:     amsopt->flist = list;
1096:   }
1097:   PetscOptionsGetString(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,len,set);
1098:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1099:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1100:   }
1101:   return(0);
1102: }

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

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

1109:    Input Parameters:
1110: +  opt - option name
1111: .  ltext - short string that describes the option
1112: .  man - manual page with additional information on option
1113: .  list - the possible choices (one of these must be selected, anything else is invalid)
1114: .  ntext - number of choices
1115: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1116: $                 PetscOptionsElist(..., obj->value,&value,&flg);
1117: $                 if (flg) {


1120:    Output Parameter:
1121: +  value - the index of the value to return
1122: -  set - PETSC_TRUE if found, else PETSC_FALSE

1124:    Level: intermediate

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

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

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

1133:    Concepts: options database^list

1135: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1136:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1137:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1138:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1139:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1140:           PetscOptionsFList(), PetscOptionsEnum()
1141: @*/
1142: 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)
1143: {
1144:   PetscErrorCode  ierr;
1145:   PetscInt        i;
1146:   PetscOptionItem amsopt;

1149:   if (!PetscOptionsObject->count) {
1150:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1151:     /* must use system malloc since SAWs may free this */
1152:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1153:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1154:     amsopt->nlist = ntext;
1155:   }
1156:   PetscOptionsGetEList(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,list,ntext,value,set);
1157:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1158:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s> %s (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue,ltext);
1159:     for (i=0; i<ntext; i++) {
1160:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1161:     }
1162:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1163:   }
1164:   return(0);
1165: }

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

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

1173:    Input Parameters:
1174: +  opt - option name
1175: .  text - short string that describes the option
1176: -  man - manual page with additional information on option

1178:    Output Parameter:
1179: .  flg - whether that option was set or not

1181:    Level: intermediate

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

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

1187:     Concepts: options database^logical group

1189: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1190:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1191:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1192:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1193:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1194:           PetscOptionsFList(), PetscOptionsEList()
1195: @*/
1196: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1197: {
1198:   PetscErrorCode  ierr;
1199:   PetscOptionItem amsopt;

1202:   if (!PetscOptionsObject->count) {
1203:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1204:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1206:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1207:   }
1208:   *flg = PETSC_FALSE;
1209:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1210:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1211:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
1212:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1213:   }
1214:   return(0);
1215: }

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

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

1223:    Input Parameters:
1224: +  opt - option name
1225: .  text - short string that describes the option
1226: -  man - manual page with additional information on option

1228:    Output Parameter:
1229: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1231:    Level: intermediate

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

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

1237:     Concepts: options database^logical group

1239: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1240:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1241:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1242:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1243:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1244:           PetscOptionsFList(), PetscOptionsEList()
1245: @*/
1246: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1247: {
1248:   PetscErrorCode  ierr;
1249:   PetscOptionItem amsopt;

1252:   if (!PetscOptionsObject->count) {
1253:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1254:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1256:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1257:   }
1258:   *flg = PETSC_FALSE;
1259:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1260:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1261:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1262:   }
1263:   return(0);
1264: }

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

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

1272:    Input Parameters:
1273: +  opt - option name
1274: .  text - short string that describes the option
1275: -  man - manual page with additional information on option

1277:    Output Parameter:
1278: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1280:    Level: intermediate

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

1284:    Must follow a PetscOptionsBoolGroupBegin()

1286:     Concepts: options database^logical group

1288: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1289:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1290:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1291:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1292:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1293:           PetscOptionsFList(), PetscOptionsEList()
1294: @*/
1295: PetscErrorCode  PetscOptionsBoolGroupEnd_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1296: {
1297:   PetscErrorCode  ierr;
1298:   PetscOptionItem amsopt;

1301:   if (!PetscOptionsObject->count) {
1302:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1303:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1305:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1306:   }
1307:   *flg = PETSC_FALSE;
1308:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,NULL);
1309:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1310:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1311:   }
1312:   return(0);
1313: }

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

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

1320:    Input Parameters:
1321: +  opt - option name
1322: .  text - short string that describes the option
1323: .  man - manual page with additional information on option
1324: -  currentvalue - the current value

1326:    Output Parameter:
1327: .  flg - PETSC_TRUE or PETSC_FALSE
1328: .  set - PETSC_TRUE if found, else PETSC_FALSE

1330:    Notes:
1331:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1332:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

1334:       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
1335:      is equivalent to -requested_bool true

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

1340:    Level: beginner

1342:    Concepts: options database^logical

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

1346: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1347:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1348:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1349:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1350:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1351:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1352:           PetscOptionsFList(), PetscOptionsEList()
1353: @*/
1354: PetscErrorCode  PetscOptionsBool_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1355: {
1356:   PetscErrorCode  ierr;
1357:   PetscBool       iset;
1358:   PetscOptionItem amsopt;

1361:   if (!PetscOptionsObject->count) {
1362:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1363:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1365:     *(PetscBool*)amsopt->data = currentvalue;
1366:   }
1367:   PetscOptionsGetBool(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,flg,&iset);
1368:   if (set) *set = iset;
1369:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1370:     const char *v = PetscBools[currentvalue];
1371:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1372:   }
1373:   return(0);
1374: }

1376: /*@C
1377:    PetscOptionsRealArray - Gets an array of double values for a particular
1378:    option in the database. The values must be separated with commas with
1379:    no intervening spaces.

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

1383:    Input Parameters:
1384: +  opt - the option one is seeking
1385: .  text - short string describing option
1386: .  man - manual page for option
1387: -  nmax - maximum number of values

1389:    Output Parameter:
1390: +  value - location to copy values
1391: .  nmax - actual number of values found
1392: -  set - PETSC_TRUE if found, else PETSC_FALSE

1394:    Level: beginner

1396:    Notes:
1397:    The user should pass in an array of doubles

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

1401:    Concepts: options database^array of strings

1403: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1404:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1405:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1406:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1407:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1408:           PetscOptionsFList(), PetscOptionsEList()
1409: @*/
1410: PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1411: {
1412:   PetscErrorCode  ierr;
1413:   PetscInt        i;
1414:   PetscOptionItem amsopt;

1417:   if (!PetscOptionsObject->count) {
1418:     PetscReal *vals;

1420:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1421:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1422:     vals = (PetscReal*)amsopt->data;
1423:     for (i=0; i<*n; i++) vals[i] = value[i];
1424:     amsopt->arraylength = *n;
1425:   }
1426:   PetscOptionsGetRealArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1427:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1428:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1429:     for (i=1; i<*n; i++) {
1430:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1431:     }
1432:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1433:   }
1434:   return(0);
1435: }

1437: /*@C
1438:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1439:    option in the database. The values must be separated with commas with
1440:    no intervening spaces.

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

1444:    Input Parameters:
1445: +  opt - the option one is seeking
1446: .  text - short string describing option
1447: .  man - manual page for option
1448: -  nmax - maximum number of values

1450:    Output Parameter:
1451: +  value - location to copy values
1452: .  nmax - actual number of values found
1453: -  set - PETSC_TRUE if found, else PETSC_FALSE

1455:    Level: beginner

1457:    Notes:
1458:    The user should pass in an array of doubles

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

1462:    Concepts: options database^array of strings

1464: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1465:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1466:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1467:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1468:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1469:           PetscOptionsFList(), PetscOptionsEList()
1470: @*/
1471: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1472: {
1473:   PetscErrorCode  ierr;
1474:   PetscInt        i;
1475:   PetscOptionItem amsopt;

1478:   if (!PetscOptionsObject->count) {
1479:     PetscScalar *vals;

1481:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_SCALAR_ARRAY,&amsopt);
1482:     PetscMalloc((*n)*sizeof(PetscScalar),&amsopt->data);
1483:     vals = (PetscScalar*)amsopt->data;
1484:     for (i=0; i<*n; i++) vals[i] = value[i];
1485:     amsopt->arraylength = *n;
1486:   }
1487:   PetscOptionsGetScalarArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1488:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1489:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g+%gi",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)PetscRealPart(value[0]),(double)PetscImaginaryPart(value[0]));
1490:     for (i=1; i<*n; i++) {
1491:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g+%gi",(double)PetscRealPart(value[i]),(double)PetscImaginaryPart(value[i]));
1492:     }
1493:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1494:   }
1495:   return(0);
1496: }

1498: /*@C
1499:    PetscOptionsIntArray - Gets an array of integers for a particular
1500:    option in the database.

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

1504:    Input Parameters:
1505: +  opt - the option one is seeking
1506: .  text - short string describing option
1507: .  man - manual page for option
1508: -  n - maximum number of values

1510:    Output Parameter:
1511: +  value - location to copy values
1512: .  n - actual number of values found
1513: -  set - PETSC_TRUE if found, else PETSC_FALSE

1515:    Level: beginner

1517:    Notes:
1518:    The array can be passed as
1519:    a comma separated list:                                 0,1,2,3,4,5,6,7
1520:    a range (start-end+1):                                  0-8
1521:    a range with given increment (start-end+1:inc):         0-7:2
1522:    a combination of values and ranges separated by commas: 0,1-8,8-15:2

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

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

1528:    Concepts: options database^array of ints

1530: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1531:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1532:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1533:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1534:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1535:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
1536: @*/
1537: PetscErrorCode  PetscOptionsIntArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1538: {
1540:   PetscInt        i;
1541:   PetscOptionItem amsopt;

1544:   if (!PetscOptionsObject->count) {
1545:     PetscInt *vals;

1547:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT_ARRAY,&amsopt);
1548:     PetscMalloc1(*n,(PetscInt**)&amsopt->data);
1549:     vals = (PetscInt*)amsopt->data;
1550:     for (i=0; i<*n; i++) vals[i] = value[i];
1551:     amsopt->arraylength = *n;
1552:   }
1553:   PetscOptionsGetIntArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1554:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1555:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1556:     for (i=1; i<*n; i++) {
1557:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1558:     }
1559:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1560:   }
1561:   return(0);
1562: }

1564: /*@C
1565:    PetscOptionsStringArray - Gets an array of string values for a particular
1566:    option in the database. The values must be separated with commas with
1567:    no intervening spaces.

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

1571:    Input Parameters:
1572: +  opt - the option one is seeking
1573: .  text - short string describing option
1574: .  man - manual page for option
1575: -  nmax - maximum number of strings

1577:    Output Parameter:
1578: +  value - location to copy strings
1579: .  nmax - actual number of strings found
1580: -  set - PETSC_TRUE if found, else PETSC_FALSE

1582:    Level: beginner

1584:    Notes:
1585:    The user should pass in an array of pointers to char, to hold all the
1586:    strings returned by this function.

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

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

1593:    Concepts: options database^array of strings

1595: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1596:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1597:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1598:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1599:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1600:           PetscOptionsFList(), PetscOptionsEList()
1601: @*/
1602: PetscErrorCode  PetscOptionsStringArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1603: {
1604:   PetscErrorCode  ierr;
1605:   PetscOptionItem amsopt;

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

1612:     amsopt->arraylength = *nmax;
1613:   }
1614:   PetscOptionsGetStringArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,nmax,set);
1615:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1616:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1617:   }
1618:   return(0);
1619: }

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

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

1628:    Input Parameters:
1629: +  opt - the option one is seeking
1630: .  text - short string describing option
1631: .  man - manual page for option
1632: -  nmax - maximum number of values

1634:    Output Parameter:
1635: +  value - location to copy values
1636: .  nmax - actual number of values found
1637: -  set - PETSC_TRUE if found, else PETSC_FALSE

1639:    Level: beginner

1641:    Notes:
1642:    The user should pass in an array of doubles

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

1646:    Concepts: options database^array of strings

1648: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1649:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1650:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1651:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1652:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1653:           PetscOptionsFList(), PetscOptionsEList()
1654: @*/
1655: PetscErrorCode  PetscOptionsBoolArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1656: {
1657:   PetscErrorCode   ierr;
1658:   PetscInt         i;
1659:   PetscOptionItem  amsopt;

1662:   if (!PetscOptionsObject->count) {
1663:     PetscBool *vals;

1665:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL_ARRAY,&amsopt);
1666:     PetscMalloc1(*n,(PetscBool**)&amsopt->data);
1667:     vals = (PetscBool*)amsopt->data;
1668:     for (i=0; i<*n; i++) vals[i] = value[i];
1669:     amsopt->arraylength = *n;
1670:   }
1671:   PetscOptionsGetBoolArray(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,value,n,set);
1672:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1673:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,value[0]);
1674:     for (i=1; i<*n; i++) {
1675:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%d",value[i]);
1676:     }
1677:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1678:   }
1679:   return(0);
1680: }

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

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

1687:    Input Parameters:
1688: +  opt - option name
1689: .  text - short string that describes the option
1690: -  man - manual page with additional information on option

1692:    Output Parameter:
1693: +  viewer - the viewer
1694: -  set - PETSC_TRUE if found, else PETSC_FALSE

1696:    Level: beginner

1698:    Concepts: options database^has int

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

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

1704: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1705:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1706:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1707:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1708:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1709:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1710:           PetscOptionsFList(), PetscOptionsEList()
1711: @*/
1712: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1713: {
1714:   PetscErrorCode  ierr;
1715:   PetscOptionItem amsopt;

1718:   if (!PetscOptionsObject->count) {
1719:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_STRING,&amsopt);
1720:     /* must use system malloc since SAWs may free this */
1721:     PetscStrdup("",(char**)&amsopt->data);
1722:   }
1723:   PetscOptionsGetViewer(PetscOptionsObject->comm,PetscOptionsObject->prefix,opt,viewer,format,set);
1724:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1725:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,"",text,ManSection(man));
1726:   }
1727:   return(0);
1728: }


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

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

1737:    Input Parameter:
1738: .   head - the heading text


1741:    Level: intermediate

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

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

1747:    Concepts: options database^subheading

1749: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1750:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1751:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1752:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1753:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1754:           PetscOptionsFList(), PetscOptionsEList()
1755: @*/
1756: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1757: {

1761:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1762:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1763:   }
1764:   return(0);
1765: }