Actual source code: aoptions.c

petsc-3.6.1 2015-08-06
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>        /*I  "petscsys.h"   I*/
 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: */


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

 32:   PetscOptionsObject->next          = 0;
 33:   PetscOptionsObject->comm          = comm;
 34:   PetscOptionsObject->changedmethod = PETSC_FALSE;

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

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

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

 61:   PetscOptionsObject->object         = obj;
 62:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

 64:   PetscStrcmp(obj->description,obj->class_name,&flg);
 65:   if (flg) {
 66:     PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
 67:   } else {
 68:     PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
 69:   }
 70:   PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
 71:   return(0);
 72: }

 74: /*
 75:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 76: */
 79: static int PetscOptionsCreate_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOption *amsopt)
 80: {
 81:   int          ierr;
 82:   PetscOption 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: }

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

113:     Collective on MPI_Comm

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

120:     Bugs:
121: .   Assumes process 0 of the given communicator has access to stdin

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

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

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

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


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

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

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

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

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

188: */
189: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptions *PetscOptionsObject)
190: {
192:   PetscOption   next = PetscOptionsObject->next;
193:   char           str[512];
194:   PetscBool      bid;
195:   PetscReal      ir,*valr;
196:   PetscInt       *vald;
197:   size_t         i;

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

223:         next->set = PETSC_TRUE;
224:         value     = str;
225:         PetscTokenCreate(value,',',&token);
226:         PetscTokenFind(token,&value);
227:         while (n < nmax) {
228:           if (!value) break;

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

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

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

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

365: static int count = 0;

369: PetscErrorCode PetscOptionsSAWsDestroy(void)
370: {
372:   return(0);
373: }

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

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

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

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


400: */
401: PetscErrorCode PetscOptionsSAWsInput(PetscOptions *PetscOptionsObject)
402: {
404:   PetscOption    next     = PetscOptionsObject->next;
405:   static int     mancount = 0;
406:   char           options[16];
407:   PetscBool      changedmethod = PETSC_FALSE;
408:   PetscBool      stopasking    = PETSC_FALSE;
409:   char           manname[16],textname[16];
410:   char           dir[1024];

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

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

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

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

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

493:   /* wait until accessor has unlocked the memory */
494:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
495:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
496:   PetscSAWsBlock();
497:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
498:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

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

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

511:   if (stopasking) {
512:     PetscOptionsPublish      = PETSC_FALSE;
513:     PetscOptionsObject->count = 0;//do not ask for same thing again
514:   }

516:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
517:   return(0);
518: }
519: #endif

523: PetscErrorCode PetscOptionsEnd_Private(PetscOptions *PetscOptionsObject)
524: {
526:   PetscOption   last;
527:   char           option[256],value[1024],tmp[32];
528:   size_t         j;

531:   if (PetscOptionsObject->next) {
532:     if (!PetscOptionsObject->count) {
533: #if defined(PETSC_HAVE_SAWS)
534:       PetscOptionsSAWsInput(PetscOptionsObject);
535: #else
536:       PetscOptionsGetFromTextInput(PetscOptionsObject);
537: #endif
538:     }
539:   }

541:   PetscFree(PetscOptionsObject->title);

543:   /* reset counter to -2; this updates the screen with the new options for the selected method */
544:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
545:   /* reset alreadyprinted flag */
546:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
547:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
548:   PetscOptionsObject->object = NULL;

550:   while (PetscOptionsObject->next) {
551:     if (PetscOptionsObject->next->set) {
552:       if (PetscOptionsObject->prefix) {
553:         PetscStrcpy(option,"-");
554:         PetscStrcat(option,PetscOptionsObject->prefix);
555:         PetscStrcat(option,PetscOptionsObject->next->option+1);
556:       } else {
557:         PetscStrcpy(option,PetscOptionsObject->next->option);
558:       }

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

632:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
633:       free(PetscOptionsObject->next->data);
634:     } else {
635:       PetscFree(PetscOptionsObject->next->data);
636:     }

638:     last                    = PetscOptionsObject->next;
639:     PetscOptionsObject->next = PetscOptionsObject->next->next;
640:     PetscFree(last);
641:   }
642:   PetscFree(PetscOptionsObject->prefix);
643:   PetscOptionsObject->next = 0;
644:   return(0);
645: }

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

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

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

665:    Output Parameter:
666: +  value - the  value to return
667: -  set - PETSC_TRUE if found, else PETSC_FALSE

669:    Level: beginner

671:    Concepts: options database

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

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

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

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

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

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

713:    Input Parameters:
714: +  opt - the option one is seeking
715: .  text - short string describing option
716: .  man - manual page for option
717: -  n - maximum number of values

719:    Output Parameter:
720: +  value - location to copy values
721: .  n - actual number of values found
722: -  set - PETSC_TRUE if found, else PETSC_FALSE

724:    Level: beginner

726:    Notes:
727:    The array must be passed as a comma separated list.

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

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

733:    Concepts: options database^array of enums

735: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
736:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
737:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
738:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
739:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
740:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
741: @*/
742: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
743: {
744:   PetscInt       i,nlist = 0;
745:   PetscOption    amsopt;

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

773: /* -------------------------------------------------------------------------------------------------------------*/
776: /*@C
777:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

781:    Input Parameters:
782: +  opt - option name
783: .  text - short string that describes the option
784: .  man - manual page with additional information on option
785: -  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
786: $                 PetscOptionsInt(..., obj->value,&object->value,...) or
787: $                 value = defaultvalue
788: $                 PetscOptionsInt(..., value,&value,&flg);
789: $                 if (flg) {

791:    Output Parameter:
792: +  value - the integer value to return
793: -  flg - PETSC_TRUE if found, else PETSC_FALSE

795:    Level: beginner

797:    Concepts: options database^has int

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

801: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
802:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
803:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
804:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
805:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
806:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
807:           PetscOptionsFList(), PetscOptionsEList()
808: @*/
809: PetscErrorCode  PetscOptionsInt_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set)
810: {
812:   PetscOption    amsopt;
813:   PetscBool      wasset;
814: 
816:   if (!PetscOptionsObject->count) {
817:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
818:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
819:     *(PetscInt*)amsopt->data = currentvalue;

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

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

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

840:    Input Parameters:
841: +  opt - option name
842: .  text - short string that describes the option
843: .  man - manual page with additional information on option
844: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
845: -  len - length of the result string including null terminator

847:    Output Parameter:
848: +  value - the value to return
849: -  flg - PETSC_TRUE if found, else PETSC_FALSE

851:    Level: beginner

853:    Concepts: options database^has int

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

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

859: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
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(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],const char currentvalue[],char value[],size_t len,PetscBool  *set)
868: {
870:   PetscOption   amsopt;

873:   if (!PetscOptionsObject->count) {
874:     PetscOptionsCreate_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->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: }

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

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

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

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

906:    Level: beginner

908:    Concepts: options database^has int

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

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

926:   if (!PetscOptionsObject->count) {
927:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
928:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

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

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

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

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


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

961:    Level: beginner

963:    Concepts: options database^has int

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

967: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
968:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
969:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
970:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
971:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
972:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
973:           PetscOptionsFList(), PetscOptionsEList()
974: @*/
975: PetscErrorCode  PetscOptionsScalar_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar currentvalue,PetscScalar *value,PetscBool  *set)
976: {

980: #if !defined(PETSC_USE_COMPLEX)
981:   PetscOptionsReal(opt,text,man,currentvalue,value,set);
982: #else
983:   PetscOptionsGetScalar(PetscOptionsObject->prefix,opt,value,set);
984: #endif
985:   return(0);
986: }

990: /*@C
991:    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
992:                       its value is set to false.

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

996:    Input Parameters:
997: +  opt - option name
998: .  text - short string that describes the option
999: -  man - manual page with additional information on option

1001:    Output Parameter:
1002: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1004:    Level: beginner

1006:    Concepts: options database^has int

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

1010: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1011:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1012:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1013:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1014:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1015:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1016:           PetscOptionsFList(), PetscOptionsEList()
1017: @*/
1018: PetscErrorCode  PetscOptionsName_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1019: {
1021:   PetscOption   amsopt;

1024:   if (!PetscOptionsObject->count) {
1025:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1026:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

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

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

1058:    Level: intermediate

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

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

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

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

1069:    Concepts: options database^list

1071: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1072:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1073:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1074:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1075:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1076:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsEnum()
1077: @*/
1078: PetscErrorCode  PetscOptionsFList_Private(PetscOptions *PetscOptionsObject,const char opt[],const char ltext[],const char man[],PetscFunctionList list,const char currentvalue[],char value[],size_t len,PetscBool  *set)
1079: {
1081:   PetscOption   amsopt;

1084:   if (!PetscOptionsObject->count) {
1085:     PetscOptionsCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_FLIST,&amsopt);
1086:     /* must use system malloc since SAWs may free this */
1087:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1088:     amsopt->flist = list;
1089:   }
1090:   PetscOptionsGetString(PetscOptionsObject->prefix,opt,value,len,set);
1091:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1092:     PetscFunctionListPrintTypes(PetscOptionsObject->comm,stdout,PetscOptionsObject->prefix,opt,ltext,man,list,currentvalue);
1093:   }
1094:   return(0);
1095: }

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

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

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


1115:    Output Parameter:
1116: +  value - the index of the value to return
1117: -  set - PETSC_TRUE if found, else PETSC_FALSE

1119:    Level: intermediate

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

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

1125:    Concepts: options database^list

1127: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1128:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1129:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1130:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1131:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1132:           PetscOptionsFList(), PetscOptionsEnum()
1133: @*/
1134: PetscErrorCode  PetscOptionsEList_Private(PetscOptions *PetscOptionsObject,const char opt[],const char ltext[],const char man[],const char *const *list,PetscInt ntext,const char currentvalue[],PetscInt *value,PetscBool  *set)
1135: {
1137:   PetscInt       i;
1138:   PetscOption   amsopt;

1141:   if (!PetscOptionsObject->count) {
1142:     PetscOptionsCreate_Private(PetscOptionsObject,opt,ltext,man,OPTION_ELIST,&amsopt);
1143:     /* must use system malloc since SAWs may free this */
1144:     PetscStrdup(currentvalue ? currentvalue : "",(char**)&amsopt->data);
1145:     PetscStrNArrayallocpy(ntext,list,(char***)&amsopt->list);
1146:     amsopt->nlist = ntext;
1147:   }
1148:   PetscOptionsGetEList(PetscOptionsObject->prefix,opt,list,ntext,value,set);
1149:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1150:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,currentvalue);
1151:     for (i=0; i<ntext; i++) {
1152:       (*PetscHelpPrintf)(PetscOptionsObject->comm," %s",list[i]);
1153:     }
1154:     (*PetscHelpPrintf)(PetscOptionsObject->comm," (%s)\n",ManSection(man));
1155:   }
1156:   return(0);
1157: }

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

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

1167:    Input Parameters:
1168: +  opt - option name
1169: .  text - short string that describes the option
1170: -  man - manual page with additional information on option

1172:    Output Parameter:
1173: .  flg - whether that option was set or not

1175:    Level: intermediate

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

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

1181:     Concepts: options database^logical group

1183: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1184:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1185:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1186:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1187:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1188:           PetscOptionsFList(), PetscOptionsEList()
1189: @*/
1190: PetscErrorCode  PetscOptionsBoolGroupBegin_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1191: {
1193:   PetscOption   amsopt;

1196:   if (!PetscOptionsObject->count) {
1197:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1198:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1200:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1201:   }
1202:   *flg = PETSC_FALSE;
1203:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,NULL);
1204:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1205:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  Pick at most one of -------------\n");
1206:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"    -%s%s: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,text,ManSection(man));
1207:   }
1208:   return(0);
1209: }

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

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

1219:    Input Parameters:
1220: +  opt - option name
1221: .  text - short string that describes the option
1222: -  man - manual page with additional information on option

1224:    Output Parameter:
1225: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1227:    Level: intermediate

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

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

1233:     Concepts: options database^logical group

1235: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1236:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1237:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1238:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1239:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1240:           PetscOptionsFList(), PetscOptionsEList()
1241: @*/
1242: PetscErrorCode  PetscOptionsBoolGroup_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool  *flg)
1243: {
1245:   PetscOption   amsopt;

1248:   if (!PetscOptionsObject->count) {
1249:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1250:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

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

1275:    Output Parameter:
1276: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1278:    Level: intermediate

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

1282:    Must follow a PetscOptionsBoolGroupBegin()

1284:     Concepts: options database^logical group

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

1299:   if (!PetscOptionsObject->count) {
1300:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1301:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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:    Level: beginner

1332:    Concepts: options database^logical

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

1336: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1337:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1338:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1339:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1340:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1341:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1342:           PetscOptionsFList(), PetscOptionsEList()
1343: @*/
1344: PetscErrorCode  PetscOptionsBool_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool currentvalue,PetscBool  *flg,PetscBool  *set)
1345: {
1347:   PetscBool      iset;
1348:   PetscOption   amsopt;

1351:   if (!PetscOptionsObject->count) {
1352:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1353:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

1355:     *(PetscBool*)amsopt->data = currentvalue;
1356:   }
1357:   PetscOptionsGetBool(PetscOptionsObject->prefix,opt,flg,&iset);
1358:   if (set) *set = iset;
1359:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1360:     const char *v = PetscBools[currentvalue];
1361:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,v,text,ManSection(man));
1362:   }
1363:   return(0);
1364: }

1368: /*@C
1369:    PetscOptionsRealArray - Gets an array of double values for a particular
1370:    option in the database. The values must be separated with commas with
1371:    no intervening spaces.

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

1375:    Input Parameters:
1376: +  opt - the option one is seeking
1377: .  text - short string describing option
1378: .  man - manual page for option
1379: -  nmax - maximum number of values

1381:    Output Parameter:
1382: +  value - location to copy values
1383: .  nmax - actual number of values found
1384: -  set - PETSC_TRUE if found, else PETSC_FALSE

1386:    Level: beginner

1388:    Notes:
1389:    The user should pass in an array of doubles

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

1393:    Concepts: options database^array of strings

1395: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1396:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1397:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1398:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1399:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1400:           PetscOptionsFList(), PetscOptionsEList()
1401: @*/
1402: PetscErrorCode PetscOptionsRealArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1403: {
1405:   PetscInt       i;
1406:   PetscOption   amsopt;

1409:   if (!PetscOptionsObject->count) {
1410:     PetscReal *vals;

1412:     PetscOptionsCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1413:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1414:     vals = (PetscReal*)amsopt->data;
1415:     for (i=0; i<*n; i++) vals[i] = value[i];
1416:     amsopt->arraylength = *n;
1417:   }
1418:   PetscOptionsGetRealArray(PetscOptionsObject->prefix,opt,value,n,set);
1419:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1420:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%g",PetscOptionsObject->prefix?PetscOptionsObject->prefix:"",opt+1,(double)value[0]);
1421:     for (i=1; i<*n; i++) {
1422:       (*PetscHelpPrintf)(PetscOptionsObject->comm,",%g",(double)value[i]);
1423:     }
1424:     (*PetscHelpPrintf)(PetscOptionsObject->comm,">: %s (%s)\n",text,ManSection(man));
1425:   }
1426:   return(0);
1427: }

1431: /*@C
1432:    PetscOptionsScalarArray - Gets an array of Scalar values for a particular
1433:    option in the database. The values must be separated with commas with
1434:    no intervening spaces.

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

1438:    Input Parameters:
1439: +  opt - the option one is seeking
1440: .  text - short string describing option
1441: .  man - manual page for option
1442: -  nmax - maximum number of values

1444:    Output Parameter:
1445: +  value - location to copy values
1446: .  nmax - actual number of values found
1447: -  set - PETSC_TRUE if found, else PETSC_FALSE

1449:    Level: beginner

1451:    Notes:
1452:    The user should pass in an array of doubles

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

1456:    Concepts: options database^array of strings

1458: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1459:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1460:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1461:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1462:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1463:           PetscOptionsFList(), PetscOptionsEList()
1464: @*/
1465: PetscErrorCode PetscOptionsScalarArray_Private(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscScalar value[],PetscInt *n,PetscBool  *set)
1466: {
1468:   PetscInt       i;
1469:   PetscOption   amsopt;

1472:   if (!PetscOptionsObject->count) {
1473:     PetscScalar *vals;

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

1494: /*@C
1495:    PetscOptionsIntArray - Gets an array of integers for a particular
1496:    option in the database.

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

1500:    Input Parameters:
1501: +  opt - the option one is seeking
1502: .  text - short string describing option
1503: .  man - manual page for option
1504: -  n - maximum number of values

1506:    Output Parameter:
1507: +  value - location to copy values
1508: .  n - actual number of values found
1509: -  set - PETSC_TRUE if found, else PETSC_FALSE

1511:    Level: beginner

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

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

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

1524:    Concepts: options database^array of ints

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

1540:   if (!PetscOptionsObject->count) {
1541:     PetscInt *vals;

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

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

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

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

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

1580:    Level: beginner

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

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

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

1591:    Concepts: options database^array of strings

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

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

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

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(), 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(PetscOptions *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscBool value[],PetscInt *n,PetscBool *set)
1656: {
1658:   PetscInt       i;
1659:   PetscOption    amsopt;

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

1665:     PetscOptionsCreate_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->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: }

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

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

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

1694:    Output Parameter:
1695: +  viewer - the viewer
1696: -  set - PETSC_TRUE if found, else PETSC_FALSE

1698:    Level: beginner

1700:    Concepts: options database^has int

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

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

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

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


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

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

1741:    Input Parameter:
1742: .   head - the heading text


1745:    Level: intermediate

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

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

1751:    Concepts: options database^subheading

1753: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1754:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1755:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1756:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1757:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1758:           PetscOptionsFList(), PetscOptionsEList()
1759: @*/
1760: PetscErrorCode  PetscOptionsHead(PetscOptions *PetscOptionsObject,const char head[])
1761: {

1765:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1766:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1767:   }
1768:   return(0);
1769: }