Actual source code: aoptions.c

petsc-master 2016-09-28
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: */


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

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

 42:   PetscStrallocpy(prefix,&PetscOptionsObject->prefix);
 43:   PetscStrallocpy(title,&PetscOptionsObject->title);

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

 56: /*
 57:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 58: */
 59: PetscErrorCode PetscObjectOptionsBegin_Private(PetscOptionItems *PetscOptionsObject,PetscObject obj)
 60: {
 62:   char           title[256];
 63:   PetscBool      flg;

 67:   PetscOptionsObject->object         = obj;
 68:   PetscOptionsObject->alreadyprinted = obj->optionsprinted;

 70:   PetscStrcmp(obj->description,obj->class_name,&flg);
 71:   if (flg) {
 72:     PetscSNPrintf(title,sizeof(title),"%s options",obj->class_name);
 73:   } else {
 74:     PetscSNPrintf(title,sizeof(title),"%s (%s) options",obj->description,obj->class_name);
 75:   }
 76:   PetscOptionsBegin_Private(PetscOptionsObject,obj->comm,obj->prefix,title,obj->mansec);
 77:   return(0);
 78: }

 80: /*
 81:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 82: */
 85: static int PetscOptionItemCreate_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptionItem *amsopt)
 86: {
 87:   int             ierr;
 88:   PetscOptionItem next;
 89:   PetscBool       valid;

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

 95:   PetscNew(amsopt);
 96:   (*amsopt)->next = 0;
 97:   (*amsopt)->set  = PETSC_FALSE;
 98:   (*amsopt)->type = t;
 99:   (*amsopt)->data = 0;

101:   PetscStrallocpy(text,&(*amsopt)->text);
102:   PetscStrallocpy(opt,&(*amsopt)->option);
103:   PetscStrallocpy(man,&(*amsopt)->man);

105:   if (!PetscOptionsObject->next) PetscOptionsObject->next = *amsopt;
106:   else {
107:     next = PetscOptionsObject->next;
108:     while (next->next) next = next->next;
109:     next->next = *amsopt;
110:   }
111:   return(0);
112: }

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

119:     Collective on MPI_Comm

121:    Input Parameters:
122: +     commm - communicator for the broadcast, must be PETSC_COMM_WORLD
123: .     n - length of the string, must be the same on all processes
124: -     str - location to store input

126:     Bugs:
127: .   Assumes process 0 of the given communicator has access to stdin

129: */
130: static PetscErrorCode PetscScanString(MPI_Comm comm,size_t n,char str[])
131: {
132:   size_t         i;
133:   char           c;
134:   PetscMPIInt    rank,nm;

138:   MPI_Comm_rank(comm,&rank);
139:   if (!rank) {
140:     c = (char) getchar();
141:     i = 0;
142:     while (c != '\n' && i < n-1) {
143:       str[i++] = c;
144:       c = (char)getchar();
145:     }
146:     str[i] = 0;
147:   }
148:   PetscMPIIntCast(n,&nm);
149:   MPI_Bcast(str,nm,MPI_CHAR,0,comm);
150:   return(0);
151: }

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

165:   if (s) {
166:     PetscStrlen(s,&len);
167:     tmp = (char*) malloc((len+1)*sizeof(char));
168:     if (!tmp) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_MEM,"No memory to duplicate string");
169:     PetscStrcpy(tmp,s);
170:   }
171:   *t = tmp;
172:   return(0);
173: }


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

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

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

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

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

194: */
195: PetscErrorCode PetscOptionsGetFromTextInput(PetscOptionItems *PetscOptionsObject)
196: {
197:   PetscErrorCode  ierr;
198:   PetscOptionItem next = PetscOptionsObject->next;
199:   char            str[512];
200:   PetscBool       bid;
201:   PetscReal       ir,*valr;
202:   PetscInt        *vald;
203:   size_t          i;

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

229:         next->set = PETSC_TRUE;
230:         value     = str;
231:         PetscTokenCreate(value,',',&token);
232:         PetscTokenFind(token,&value);
233:         while (n < nmax) {
234:           if (!value) break;

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

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

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

368: #if defined(PETSC_HAVE_SAWS)
369:  #include <petscviewersaws.h>

371: static int count = 0;

375: PetscErrorCode PetscOptionsSAWsDestroy(void)
376: {
378:   return(0);
379: }

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

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

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

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


406: */
407: PetscErrorCode PetscOptionsSAWsInput(PetscOptionItems *PetscOptionsObject)
408: {
409:   PetscErrorCode  ierr;
410:   PetscOptionItem next     = PetscOptionsObject->next;
411:   static int      mancount = 0;
412:   char            options[16];
413:   PetscBool       changedmethod = PETSC_FALSE;
414:   PetscBool       stopasking    = PETSC_FALSE;
415:   char            manname[16],textname[16];
416:   char            dir[1024];

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

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

424:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","_title");
425:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->title,1,SAWs_READ,SAWs_STRING));
426:   PetscSNPrintf(dir,1024,"/PETSc/Options/%s","prefix");
427:   PetscStackCallSAWs(SAWs_Register,(dir,&PetscOptionsObject->pprefix,1,SAWs_READ,SAWs_STRING));
428:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/ChangedMethod",&changedmethod,1,SAWs_WRITE,SAWs_BOOLEAN));
429:   PetscStackCallSAWs(SAWs_Register,("/PETSc/Options/StopAsking",&stopasking,1,SAWs_WRITE,SAWs_BOOLEAN));

431:   while (next) {
432:     sprintf(manname,"_man_%d",mancount);
433:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",manname);
434:     PetscStackCallSAWs(SAWs_Register,(dir,&next->man,1,SAWs_READ,SAWs_STRING));
435:     sprintf(textname,"_text_%d",mancount++);
436:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",textname);
437:     PetscStackCallSAWs(SAWs_Register,(dir,&next->text,1,SAWs_READ,SAWs_STRING));

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

499:   /* wait until accessor has unlocked the memory */
500:   PetscStackCallSAWs(SAWs_Push_Header,("index.html",OptionsHeader));
501:   PetscStackCallSAWs(SAWs_Push_Body,("index.html",2,OptionsBodyBottom));
502:   PetscSAWsBlock();
503:   PetscStackCallSAWs(SAWs_Pop_Header,("index.html"));
504:   PetscStackCallSAWs(SAWs_Pop_Body,("index.html",2));

506:   /* determine if any values have been set in GUI */
507:   next = PetscOptionsObject->next;
508:   while (next) {
509:     PetscSNPrintf(dir,1024,"/PETSc/Options/%s",next->option);
510:     PetscStackCallSAWs(SAWs_Selected,(dir,(int*)&next->set));
511:     next = next->next;
512:   }

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

517:   if (stopasking) {
518:     PetscOptionsPublish      = PETSC_FALSE;
519:     PetscOptionsObject->count = 0;//do not ask for same thing again
520:   }

522:   PetscStackCallSAWs(SAWs_Delete,("/PETSc/Options"));
523:   return(0);
524: }
525: #endif

529: PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *PetscOptionsObject)
530: {
531:   PetscErrorCode  ierr;
532:   PetscOptionItem last;
533:   char            option[256],value[1024],tmp[32];
534:   size_t          j;

537:   if (PetscOptionsObject->next) {
538:     if (!PetscOptionsObject->count) {
539: #if defined(PETSC_HAVE_SAWS)
540:       PetscOptionsSAWsInput(PetscOptionsObject);
541: #else
542:       PetscOptionsGetFromTextInput(PetscOptionsObject);
543: #endif
544:     }
545:   }

547:   PetscFree(PetscOptionsObject->title);

549:   /* reset counter to -2; this updates the screen with the new options for the selected method */
550:   if (PetscOptionsObject->changedmethod) PetscOptionsObject->count = -2;
551:   /* reset alreadyprinted flag */
552:   PetscOptionsObject->alreadyprinted = PETSC_FALSE;
553:   if (PetscOptionsObject->object) PetscOptionsObject->object->optionsprinted = PETSC_TRUE;
554:   PetscOptionsObject->object = NULL;

556:   while (PetscOptionsObject->next) {
557:     if (PetscOptionsObject->next->set) {
558:       if (PetscOptionsObject->prefix) {
559:         PetscStrcpy(option,"-");
560:         PetscStrcat(option,PetscOptionsObject->prefix);
561:         PetscStrcat(option,PetscOptionsObject->next->option+1);
562:       } else {
563:         PetscStrcpy(option,PetscOptionsObject->next->option);
564:       }

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

638:     if ((PetscOptionsObject->next->type == OPTION_STRING) || (PetscOptionsObject->next->type == OPTION_FLIST) || (PetscOptionsObject->next->type == OPTION_ELIST)){
639:       free(PetscOptionsObject->next->data);
640:     } else {
641:       PetscFree(PetscOptionsObject->next->data);
642:     }

644:     last                    = PetscOptionsObject->next;
645:     PetscOptionsObject->next = PetscOptionsObject->next->next;
646:     PetscFree(last);
647:   }
648:   PetscFree(PetscOptionsObject->prefix);
649:   PetscOptionsObject->next = 0;
650:   return(0);
651: }

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

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

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

671:    Output Parameter:
672: +  value - the  value to return
673: -  set - PETSC_TRUE if found, else PETSC_FALSE

675:    Level: beginner

677:    Concepts: options database

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

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

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

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

713: /*@C
714:    PetscOptionsEnumArray - Gets an array of enum values for a particular
715:    option in the database.

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

719:    Input Parameters:
720: +  opt - the option one is seeking
721: .  text - short string describing option
722: .  man - manual page for option
723: -  n - maximum number of values

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

730:    Level: beginner

732:    Notes:
733:    The array must be passed as a comma separated list.

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

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

739:    Concepts: options database^array of enums

741: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
742:           PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
743:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
744:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
745:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
746:           PetscOptionsFList(), PetscOptionsEList(), PetscOptionsRealArray()
747: @*/
748: PetscErrorCode  PetscOptionsEnumArray_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],const char *const *list,PetscEnum value[],PetscInt *n,PetscBool  *set)
749: {
750:   PetscInt        i,nlist = 0;
751:   PetscOptionItem amsopt;
752:   PetscErrorCode  ierr;

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

779: /* -------------------------------------------------------------------------------------------------------------*/
782: /*@C
783:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

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

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

801:    Level: beginner

803:    Concepts: options database^has int

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

807: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
808:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
809:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
810:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
811:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
812:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
813:           PetscOptionsFList(), PetscOptionsEList()
814: @*/
815: PetscErrorCode  PetscOptionsInt_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscInt currentvalue,PetscInt *value,PetscBool  *set)
816: {
817:   PetscErrorCode  ierr;
818:   PetscOptionItem amsopt;
819:   PetscBool       wasset;

822:   if (!PetscOptionsObject->count) {
823:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_INT,&amsopt);
824:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
825:     *(PetscInt*)amsopt->data = currentvalue;

827:     PetscOptionsGetInt(PetscOptionsObject->options,PetscOptionsObject->prefix,opt,&currentvalue,&wasset);
828:     if (wasset) {
829:       *(PetscInt*)amsopt->data = currentvalue;
830:     }
831:   }
832:   PetscOptionsGetInt(NULL,PetscOptionsObject->prefix,opt,value,set);
833:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
834:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject->prefix ? PetscOptionsObject->prefix : "",opt+1,currentvalue,text,ManSection(man));
835:   }
836:   return(0);
837: }

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

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

846:    Input Parameters:
847: +  opt - option name
848: .  text - short string that describes the option
849: .  man - manual page with additional information on option
850: .  currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
851: -  len - length of the result string including null terminator

853:    Output Parameter:
854: +  value - the value to return
855: -  flg - PETSC_TRUE if found, else PETSC_FALSE

857:    Level: beginner

859:    Concepts: options database^has int

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

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

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

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

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

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

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

908:    Output Parameter:
909: +  value - the value to return
910: -  flg - PETSC_TRUE if found, else PETSC_FALSE

912:    Level: beginner

914:    Concepts: options database^has int

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

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

932:   if (!PetscOptionsObject->count) {
933:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_REAL,&amsopt);
934:     PetscMalloc(sizeof(PetscReal),&amsopt->data);

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

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

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

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


963:    Output Parameter:
964: +  value - the value to return
965: -  flg - PETSC_TRUE if found, else PETSC_FALSE

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

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

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

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

1007:    Output Parameter:
1008: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1010:    Level: beginner

1012:    Concepts: options database^has int

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

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

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

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

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

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

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

1060:    Output Parameter:
1061: +  value - the value to return
1062: -  set - PETSC_TRUE if found, else PETSC_FALSE

1064:    Level: intermediate

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

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

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

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

1075:    Concepts: options database^list

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

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

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

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

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


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

1125:    Level: intermediate

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

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

1131:    Concepts: options database^list

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

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

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

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

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

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

1230:    Output Parameter:
1231: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1233:    Level: intermediate

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

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

1239:     Concepts: options database^logical group

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

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

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

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

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

1276:    Input Parameters:
1277: +  opt - option name
1278: .  text - short string that describes the option
1279: -  man - manual page with additional information on option

1281:    Output Parameter:
1282: .  flg - PETSC_TRUE if found, else PETSC_FALSE

1284:    Level: intermediate

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

1288:    Must follow a PetscOptionsBoolGroupBegin()

1290:     Concepts: options database^logical group

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

1305:   if (!PetscOptionsObject->count) {
1306:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1307:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

1326:    Input Parameters:
1327: +  opt - option name
1328: .  text - short string that describes the option
1329: .  man - manual page with additional information on option
1330: -  currentvalue - the current value

1332:    Output Parameter:
1333: .  flg - PETSC_TRUE or PETSC_FALSE
1334: .  set - PETSC_TRUE if found, else PETSC_FALSE

1336:    Level: beginner

1338:    Concepts: options database^logical

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

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

1357:   if (!PetscOptionsObject->count) {
1358:     PetscOptionItemCreate_Private(PetscOptionsObject,opt,text,man,OPTION_BOOL,&amsopt);
1359:     PetscMalloc(sizeof(PetscBool),&amsopt->data);

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

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

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

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

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

1392:    Level: beginner

1394:    Notes:
1395:    The user should pass in an array of doubles

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

1399:    Concepts: options database^array of strings

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

1415:   if (!PetscOptionsObject->count) {
1416:     PetscReal *vals;

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

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

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

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

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

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

1517:    Level: beginner

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

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

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

1530:    Concepts: options database^array of ints

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

1546:   if (!PetscOptionsObject->count) {
1547:     PetscInt *vals;

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

1568: /*@C
1569:    PetscOptionsStringArray - Gets an array of string values for a particular
1570:    option in the database. The values must be separated with commas with
1571:    no intervening spaces.

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

1575:    Input Parameters:
1576: +  opt - the option one is seeking
1577: .  text - short string describing option
1578: .  man - manual page for option
1579: -  nmax - maximum number of strings

1581:    Output Parameter:
1582: +  value - location to copy strings
1583: .  nmax - actual number of strings found
1584: -  set - PETSC_TRUE if found, else PETSC_FALSE

1586:    Level: beginner

1588:    Notes:
1589:    The user should pass in an array of pointers to char, to hold all the
1590:    strings returned by this function.

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

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

1597:    Concepts: options database^array of strings

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

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

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

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

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

1634:    Input Parameters:
1635: +  opt - the option one is seeking
1636: .  text - short string describing option
1637: .  man - manual page for option
1638: -  nmax - maximum number of values

1640:    Output Parameter:
1641: +  value - location to copy values
1642: .  nmax - actual number of values found
1643: -  set - PETSC_TRUE if found, else PETSC_FALSE

1645:    Level: beginner

1647:    Notes:
1648:    The user should pass in an array of doubles

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

1652:    Concepts: options database^array of strings

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

1668:   if (!PetscOptionsObject->count) {
1669:     PetscBool *vals;

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

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

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

1695:    Input Parameters:
1696: +  opt - option name
1697: .  text - short string that describes the option
1698: -  man - manual page with additional information on option

1700:    Output Parameter:
1701: +  viewer - the viewer
1702: -  set - PETSC_TRUE if found, else PETSC_FALSE

1704:    Level: beginner

1706:    Concepts: options database^has int

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

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

1712: .seealso: PetscOptionsGetViewer(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(NULL,),
1713:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1714:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1715:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1716:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1717:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1718:           PetscOptionsFList(), PetscOptionsEList()
1719: @*/
1720: PetscErrorCode  PetscOptionsViewer_Private(PetscOptionItems *PetscOptionsObject,const char opt[],const char text[],const char man[],PetscViewer *viewer,PetscViewerFormat *format,PetscBool  *set)
1721: {
1722:   PetscErrorCode  ierr;
1723:   PetscOptionItem amsopt;

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


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

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

1747:    Input Parameter:
1748: .   head - the heading text


1751:    Level: intermediate

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

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

1757:    Concepts: options database^subheading

1759: .seealso: PetscOptionsGetInt(NULL,), PetscOptionsGetReal(),
1760:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1761:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1762:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1763:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1764:           PetscOptionsFList(), PetscOptionsEList()
1765: @*/
1766: PetscErrorCode  PetscOptionsHead(PetscOptionItems *PetscOptionsObject,const char head[])
1767: {

1771:   if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) {
1772:     (*PetscHelpPrintf)(PetscOptionsObject->comm,"  %s\n",head);
1773:   }
1774:   return(0);
1775: }