Actual source code: aoptions.c

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

  6: */

  8: #include <petscsys.h>        /*I  "petscsys.h"   I*/
  9: #if defined(PETSC_HAVE_STDLIB_H)
 10: #include <stdlib.h>
 11: #endif

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

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

 19:     Eventually we'll attach this beast to a MPI_Comm
 20: */
 21: PetscOptionsObjectType PetscOptionsObject;
 22: PetscInt               PetscOptionsPublishCount = 0;

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

 34:   PetscOptionsObject.next          = 0;
 35:   PetscOptionsObject.comm          = comm;
 36:   PetscOptionsObject.changedmethod = PETSC_FALSE;
 37:   PetscFree(PetscOptionsObject.prefix);
 38:   PetscStrallocpy(prefix,&PetscOptionsObject.prefix);
 39:   PetscFree(PetscOptionsObject.title);
 40:   PetscStrallocpy(title,&PetscOptionsObject.title);

 42:   PetscOptionsHasName(PETSC_NULL,"-help",&PetscOptionsObject.printhelp);
 43:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1) {
 44:     if (!PetscOptionsObject.alreadyprinted) {
 45:       (*PetscHelpPrintf)(comm,"%s -------------------------------------------------\n",title);
 46:     }
 47:   }
 48:   return(0);
 49: }

 53: /*
 54:     Handles setting up the data structure in a call to PetscObjectOptionsBegin()
 55: */
 56: PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject obj)
 57: {
 59:   char title[256];
 60:   PetscBool flg;

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

 76: /*
 77:      Handles adding another option to the list of options within this particular PetscOptionsBegin() PetscOptionsEnd()
 78: */
 81: static int PetscOptionsCreate_Private(const char opt[],const char text[],const char man[],PetscOptionType t,PetscOptions *amsopt)
 82: {
 83:   int          ierr;
 84:   PetscOptions next;
 85:   PetscBool    valid;

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

 91:   PetscNew(struct _n_PetscOptions,amsopt);
 92:   (*amsopt)->next  = 0;
 93:   (*amsopt)->set   = PETSC_FALSE;
 94:   (*amsopt)->type  = t;
 95:   (*amsopt)->data  = 0;

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

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

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

116:     Collective on MPI_Comm

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

123:     Bugs: 
124: .   Assumes process 0 of the given communicator has access to stdin

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

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

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

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

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

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

165: */
166: PetscErrorCode PetscOptionsGetFromTextInput()
167: {
169:   PetscOptions   next = PetscOptionsObject.next;
170:   char           str[512];
171:   PetscInt       id;
172:   PetscReal      ir,*valr;
173:   PetscInt       *vald;
174:   size_t         i;
175: 
176:   (*PetscPrintf)(PETSC_COMM_WORLD,"%s -------------------------------------------------\n",PetscOptionsObject.title);
177:   while (next) {
178:     switch (next->type) {
179:       case OPTION_HEAD:
180:         break;
181:       case OPTION_INT_ARRAY:
182:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
183:         vald = (PetscInt*) next->data;
184:         for (i=0; i<next->arraylength; i++) {
185:           PetscPrintf(PETSC_COMM_WORLD,"%d",vald[i]);
186:           if (i < next->arraylength-1) {
187:             PetscPrintf(PETSC_COMM_WORLD,",");
188:           }
189:         }
190:         PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
191:         PetscScanString(PETSC_COMM_WORLD,512,str);
192:         if (str[0]) {
193:           PetscToken token;
194:           PetscInt   n=0,nmax = next->arraylength,*dvalue = (PetscInt*)next->data,start,end;
195:           size_t     len;
196:           char*      value;
197:           PetscBool  foundrange;

199:           next->set = PETSC_TRUE;
200:           value = str;
201:           PetscTokenCreate(value,',',&token);
202:           PetscTokenFind(token,&value);
203:           while (n < nmax) {
204:             if (!value) break;
205: 
206:             /* look for form  d-D where d and D are integers */
207:             foundrange = PETSC_FALSE;
208:             PetscStrlen(value,&len);
209:             if (value[0] == '-') i=2;
210:             else i=1;
211:             for (;i<len; i++) {
212:               if (value[i] == '-') {
213:                 if (i == len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
214:                 value[i] = 0;
215:                 PetscOptionsStringToInt(value,&start);
216:                 PetscOptionsStringToInt(value+i+1,&end);
217:                 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);
218:                 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);
219:                 for (;start<end; start++) {
220:                   *dvalue = start; dvalue++;n++;
221:                 }
222:                 foundrange = PETSC_TRUE;
223:                 break;
224:               }
225:             }
226:             if (!foundrange) {
227:               PetscOptionsStringToInt(value,dvalue);
228:               dvalue++;
229:               n++;
230:             }
231:             PetscTokenFind(token,&value);
232:           }
233:           PetscTokenDestroy(token);
234:         }
235:         break;
236:       case OPTION_REAL_ARRAY:
237:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1);
238:         valr = (PetscReal*) next->data;
239:         for (i=0; i<next->arraylength; i++) {
240:           PetscPrintf(PETSC_COMM_WORLD,"%g",valr[i]);
241:           if (i < next->arraylength-1) {
242:             PetscPrintf(PETSC_COMM_WORLD,",");
243:           }
244:         }
245:         PetscPrintf(PETSC_COMM_WORLD,">: %s (%s)",next->text,next->man);
246:         PetscScanString(PETSC_COMM_WORLD,512,str);
247:         if (str[0]) {
248:           PetscToken token;
249:           PetscInt   n=0,nmax = next->arraylength;
250:           PetscReal   *dvalue = (PetscReal*)next->data;
251:           char*      value;

253:           next->set = PETSC_TRUE;
254:           value = str;
255:           PetscTokenCreate(value,',',&token);
256:           PetscTokenFind(token,&value);
257:           while (n < nmax) {
258:             if (!value) break;
259:             PetscOptionsStringToReal(value,dvalue);
260:             dvalue++;
261:             n++;
262:             PetscTokenFind(token,&value);
263:           }
264:           PetscTokenDestroy(token);
265:         }
266:         break;
267:       case OPTION_INT:
268:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%d>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(int*)next->data,next->text,next->man);
269:         PetscScanString(PETSC_COMM_WORLD,512,str);
270:         if (str[0]) {
271: #if defined(PETSC_USE_64BIT_INDICES)
272:           sscanf(str,"%lld",&id);
273: #else
274:           sscanf(str,"%d",&id);
275: #endif
276:           next->set = PETSC_TRUE;
277:           *((PetscInt*)next->data) = id;
278:         }
279:         break;
280:       case OPTION_REAL:
281:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%g>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,*(double*)next->data,next->text,next->man);
282:         PetscScanString(PETSC_COMM_WORLD,512,str);
283:         if (str[0]) {
284: #if defined(PETSC_USE_REAL_SINGLE)
285:           sscanf(str,"%e",&ir);
286: #elif defined(PETSC_USE_REAL_DOUBLE)
287:           sscanf(str,"%le",&ir);
288: #elif defined(PETSC_USE_REAL_LONG_DOUBLE)
289:           sscanf(str,"%Le",&ir);
290: #elif defined(PETSC_USE_REAL___FLOAT128)
291:           ir = strtoflt128(str,0);
292: #else
293:           SETERRQ(PETSC_COMM_SELF,PETSC_ERR_LIB,"Unknown scalar type");
294: #endif
295:           next->set = PETSC_TRUE;
296:           *((PetscReal*)next->data) = ir;
297:         }
298:         break;
299:       case OPTION_LOGICAL:
300:       case OPTION_STRING:
301:         PetscPrintf(PETSC_COMM_WORLD,"-%s%s <%s>: %s (%s)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",next->option+1,(char*)next->data,next->text,next->man);
302:         PetscScanString(PETSC_COMM_WORLD,512,str);
303:         if (str[0]) {
304:           next->set = PETSC_TRUE;
305:           PetscStrcpy((char*)next->data,str);
306:         }
307:         break;
308:       case OPTION_LIST:
309:         PetscFListPrintTypes(PETSC_COMM_WORLD,stdout,PetscOptionsObject.prefix,next->option,next->text,next->man,next->flist,(char*)next->data);
310:         PetscScanString(PETSC_COMM_WORLD,512,str);
311:         if (str[0]) {
312:           PetscOptionsObject.changedmethod = PETSC_TRUE;
313:           next->set = PETSC_TRUE;
314:           PetscStrcpy((char*)next->data,str);
315:         }
316:         break;
317:     default:
318:       break;
319:     }
320:     next = next->next;
321:   }
322:   return(0);
323: }

325: #if defined(PETSC_HAVE_AMS)
326: #define CHKERRAMS(err)  if (err) {char *msg; AMS_Explain_error((err), &(msg)); SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"AMS Error: %s",msg);}
327: #define CHKERRAMSFieldName(err,fn)  if (err) {char *msg; AMS_Explain_error((err), &(msg)); SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_LIB,"Fieldname %s, AMS Error: %s",fn,msg);}

329: static int  count = 0;

333: PetscErrorCode PetscOptionsAMSDestroy(void)
334: {
336:   AMS_Comm       acomm = -1;
337:   AMS_Memory     amem = -1;
338:   char           options[16];
339:   const char     *string = "Exit";

341:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
342:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
343:   sprintf(options,"Options_%d",count++);
344:   AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
345:   AMS_Memory_add_field(amem,"Exit",&string,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"Exit");

347:   AMS_Memory_take_access(amem);CHKERRAMS(ierr);
348:   AMS_Memory_publish(amem);CHKERRAMS(ierr);
349:   AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
350:   /* wait until accessor has unlocked the memory */
351:   AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
352:   AMS_Memory_take_access(amem);CHKERRAMS(ierr);
353:   AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
354:   AMS_Memory_destroy(amem);CHKERRAMS(ierr);
355:   return(0);
356: }

360: /*
361:     PetscOptionsAMSInput - Presents all the PETSc Options processed by the program so the user may change them at runtime using the AMS

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


369: */
370: PetscErrorCode PetscOptionsAMSInput()
371: {
373:   PetscOptions   next = PetscOptionsObject.next;
374:   static int     mancount = 0;
375:   char           options[16];
376:   AMS_Comm       acomm = -1;
377:   AMS_Memory     amem = -1;
378:   PetscBool      changedmethod = PETSC_FALSE;
379:   char           manname[16];

381:   /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
382:   PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
383:   sprintf(options,"Options_%d",count++);
384:   AMS_Memory_create(acomm,options,&amem);CHKERRAMS(ierr);
385:   AMS_Memory_take_access(amem);CHKERRAMS(ierr);
386:   PetscOptionsObject.pprefix = PetscOptionsObject.prefix; /* AMS will change this, so cannot pass prefix directly */

388:   AMS_Memory_add_field(amem,PetscOptionsObject.title,&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,PetscOptionsObject.title);
389:   /* AMS_Memory_add_field(amem,"mansec",&PetscOptionsObject.pprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMS(ierr); */
390:   AMS_Memory_add_field(amem,"ChangedMethod",&changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,"ChangedMethod");

392:   while (next) {
393:     AMS_Memory_add_field(amem,next->option,&next->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->option);
394:      PetscMalloc(sizeof(char*),&next->pman);
395:     *(char **)next->pman = next->man;
396:     sprintf(manname,"man_%d",mancount++);
397:     AMS_Memory_add_field(amem,manname,next->pman,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,manname);

399:     switch (next->type) {
400:       case OPTION_HEAD:
401:         break;
402:       case OPTION_INT_ARRAY:
403:         AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
404:         break;
405:       case OPTION_REAL_ARRAY:
406:         AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
407:         break;
408:       case OPTION_INT:
409:         AMS_Memory_add_field(amem,next->text,next->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
410:         break;
411:       case OPTION_REAL:
412:         AMS_Memory_add_field(amem,next->text,next->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
413:         break;
414:       case OPTION_LOGICAL:
415:         AMS_Memory_add_field(amem,next->text,next->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
416:         break;
417:       case OPTION_LOGICAL_ARRAY:
418:         AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
419:         break;
420:       case OPTION_STRING:
421:         AMS_Memory_add_field(amem,next->text,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
422:         break;
423:       case OPTION_STRING_ARRAY:
424:         AMS_Memory_add_field(amem,next->text,next->data,next->arraylength,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
425:         break;
426:       case OPTION_LIST:
427:         {PetscInt  ntext;
428:         char       ldefault[128];
429:         PetscStrcpy(ldefault,"DEFAULT:");
430:         PetscStrcat(ldefault,next->text);
431:         AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
432:         PetscFListGet(next->flist,(char***)&next->edata,&ntext);
433:         AMS_Memory_add_field(amem,next->text,next->edata,ntext-1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
434:         break;}
435:       case OPTION_ELIST:
436:         {PetscInt  ntext = next->nlist;
437:         char       ldefault[128];
438:         PetscStrcpy(ldefault,"DEFAULT:");
439:         PetscStrcat(ldefault,next->text);
440:         AMS_Memory_add_field(amem,ldefault,next->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,ldefault);
441:         PetscMalloc((ntext+1)*sizeof(char**),&next->edata);
442:         PetscMemcpy(next->edata,next->list,ntext*sizeof(char*));
443:         AMS_Memory_add_field(amem,next->text,next->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRAMSFieldName(ierr,next->text);
444:         break;}
445:     default:
446:       break;
447:     }
448:     next = next->next;
449:   }

451:   AMS_Memory_publish(amem);CHKERRAMS(ierr);
452:   AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
453:   /* wait until accessor has unlocked the memory */
454:   AMS_Memory_lock(amem,0);CHKERRAMS(ierr);
455:   AMS_Memory_take_access(amem);CHKERRAMS(ierr);
456: 
457:   /* reset counter to -2; this updates the screen with the new options for the selected method */
458:   if (changedmethod) PetscOptionsPublishCount = -2;

460:   AMS_Memory_grant_access(amem);CHKERRAMS(ierr);
461:   AMS_Memory_destroy(amem);CHKERRAMS(ierr);
462:   return(0);
463: }
464: #endif

468: PetscErrorCode PetscOptionsEnd_Private(void)
469: {
471:   PetscOptions   last;
472:   char           option[256],value[1024],tmp[32];
473:   size_t         j;


477:   CHKMEMQ;
478:   if (PetscOptionsObject.next) {
479:     if (!PetscOptionsPublishCount) {
480: #if defined(PETSC_HAVE_AMS)
481:       PetscOptionsAMSInput();
482: #else
483:       PetscOptionsGetFromTextInput();
484: #endif
485:     }
486:   }

488:   PetscFree(PetscOptionsObject.title);
489:   PetscFree(PetscOptionsObject.prefix);

491:   /* reset counter to -2; this updates the screen with the new options for the selected method */
492:   if (PetscOptionsObject.changedmethod) PetscOptionsPublishCount = -2;
493:   /* reset alreadyprinted flag */
494:   PetscOptionsObject.alreadyprinted = PETSC_FALSE;
495:   if (PetscOptionsObject.object) PetscOptionsObject.object->optionsprinted = PETSC_TRUE;
496:   PetscOptionsObject.object = PETSC_NULL;

498:   while (PetscOptionsObject.next) {
499:     if (PetscOptionsObject.next->set) {
500:       if (PetscOptionsObject.prefix) {
501:         PetscStrcpy(option,"-");
502:         PetscStrcat(option,PetscOptionsObject.prefix);
503:         PetscStrcat(option,PetscOptionsObject.next->option+1);
504:       } else {
505:         PetscStrcpy(option,PetscOptionsObject.next->option);
506:       }

508:       switch (PetscOptionsObject.next->type) {
509:         case OPTION_HEAD:
510:           break;
511:         case OPTION_INT_ARRAY:
512:           sprintf(value,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[0]);
513:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
514:             sprintf(tmp,"%d",(int)((PetscInt*)PetscOptionsObject.next->data)[j]);
515:             PetscStrcat(value,",");
516:             PetscStrcat(value,tmp);
517:           }
518:           break;
519:         case OPTION_INT:
520:           sprintf(value,"%d",(int) *(PetscInt*)PetscOptionsObject.next->data);
521:           break;
522:         case OPTION_REAL:
523:           sprintf(value,"%g",(double) *(PetscReal*)PetscOptionsObject.next->data);
524:           break;
525:         case OPTION_REAL_ARRAY:
526:           sprintf(value,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[0]);
527:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
528:             sprintf(tmp,"%g",(double)((PetscReal*)PetscOptionsObject.next->data)[j]);
529:             PetscStrcat(value,",");
530:             PetscStrcat(value,tmp);
531:           }
532:           break;
533:         case OPTION_LOGICAL:
534:           sprintf(value,"%d",*(int*)PetscOptionsObject.next->data);
535:           break;
536:       case OPTION_LOGICAL_ARRAY:
537:           sprintf(value,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[0]);
538:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
539:             sprintf(tmp,"%d",(int)((PetscBool*)PetscOptionsObject.next->data)[j]);
540:             PetscStrcat(value,",");
541:             PetscStrcat(value,tmp);
542:           }
543:           break;
544:         case OPTION_LIST:
545:         case OPTION_ELIST:
546:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
547:           break;
548:         case OPTION_STRING:
549:           PetscStrcpy(value,*(char**)PetscOptionsObject.next->data);
550:         case OPTION_STRING_ARRAY:
551:           sprintf(value,"%s",((char**)PetscOptionsObject.next->data)[0]);
552:           for (j=1; j<PetscOptionsObject.next->arraylength; j++) {
553:             sprintf(tmp,"%s",((char**)PetscOptionsObject.next->data)[j]);
554:             PetscStrcat(value,",");
555:             PetscStrcat(value,tmp);
556:           }
557:           break;
558:       }
559:       PetscOptionsSetValue(option,value);
560:     }
561:     PetscFree(PetscOptionsObject.next->text);
562:     PetscFree(PetscOptionsObject.next->option);
563:     PetscFree(PetscOptionsObject.next->man);
564:     PetscFree(PetscOptionsObject.next->data);
565:     PetscFree(PetscOptionsObject.next->edata);
566:     last                    = PetscOptionsObject.next;
567:     PetscOptionsObject.next = PetscOptionsObject.next->next;
568:     PetscFree(last);
569:     CHKMEMQ;
570:   }
571:   CHKMEMQ;
572:   PetscOptionsObject.next = 0;
573:   return(0);
574: }

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

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

583:    Input Parameters:
584: +  opt - option name
585: .  text - short string that describes the option
586: .  man - manual page with additional information on option
587: .  list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
588: -  defaultv - the default (current) value

590:    Output Parameter:
591: +  value - the  value to return
592: -  flg - PETSC_TRUE if found, else PETSC_FALSE

594:    Level: beginner

596:    Concepts: options database

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

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

602: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
603:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
604:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
605:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
606:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
607:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
608:           PetscOptionsList(), PetscOptionsEList()
609: @*/
610: PetscErrorCode  PetscOptionsEnum(const char opt[],const char text[],const char man[],const char *const*list,PetscEnum defaultv,PetscEnum *value,PetscBool  *set)
611: {
613:   PetscInt       ntext = 0;
614:   PetscInt       tval;
615:   PetscBool      tflg;

618:   while (list[ntext++]) {
619:     if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
620:   }
621:   if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
622:   ntext -= 3;
623:   PetscOptionsEList(opt,text,man,list,ntext,list[defaultv],&tval,&tflg);
624:   /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
625:   if (tflg) *value = (PetscEnum)tval;
626:   if (set)  *set   = tflg;
627:   return(0);
628: }

630: /* -------------------------------------------------------------------------------------------------------------*/
633: /*@C
634:    PetscOptionsInt - Gets the integer value for a particular option in the database.

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

638:    Input Parameters:
639: +  opt - option name
640: .  text - short string that describes the option
641: .  man - manual page with additional information on option
642: -  defaultv - the default (current) value

644:    Output Parameter:
645: +  value - the integer value to return
646: -  flg - PETSC_TRUE if found, else PETSC_FALSE

648:    Level: beginner

650:    Concepts: options database^has int

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

654: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
655:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
656:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
657:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
658:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
659:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
660:           PetscOptionsList(), PetscOptionsEList()
661: @*/
662: PetscErrorCode  PetscOptionsInt(const char opt[],const char text[],const char man[],PetscInt defaultv,PetscInt *value,PetscBool  *set)
663: {
665:   PetscOptions   amsopt;

668:   if (!PetscOptionsPublishCount) {
669:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT,&amsopt);
670:     PetscMalloc(sizeof(PetscInt),&amsopt->data);
671:     *(PetscInt*)amsopt->data = defaultv;
672:   }
673:   PetscOptionsGetInt(PetscOptionsObject.prefix,opt,value,set);
674:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
675:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
676:   }
677:   return(0);
678: }

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

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

687:    Input Parameters:
688: +  opt - option name
689: .  text - short string that describes the option
690: .  man - manual page with additional information on option
691: .  defaultv - the default (current) value
692: -  len - length of the result string including null terminator

694:    Output Parameter:
695: +  value - the value to return
696: -  flg - PETSC_TRUE if found, else PETSC_FALSE

698:    Level: beginner

700:    Concepts: options database^has int

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

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

706: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
707:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
708:           PetscOptionsInt(), PetscOptionsReal(), PetscOptionsBool(),
709:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
710:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
711:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
712:           PetscOptionsList(), PetscOptionsEList()
713: @*/
714: PetscErrorCode  PetscOptionsString(const char opt[],const char text[],const char man[],const char defaultv[],char value[],size_t len,PetscBool  *set)
715: {
717:   PetscOptions   amsopt;

720:   if (!PetscOptionsPublishCount) {
721:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING,&amsopt);
722:     PetscMalloc(sizeof(char*),&amsopt->data);
723:     *(const char**)amsopt->data = defaultv;
724:   }
725:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
726:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
727:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
728:   }
729:   return(0);
730: }

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

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

739:    Input Parameters:
740: +  opt - option name
741: .  text - short string that describes the option
742: .  man - manual page with additional information on option
743: -  defaultv - the default (current) value

745:    Output Parameter:
746: +  value - the value to return
747: -  flg - PETSC_TRUE if found, else PETSC_FALSE

749:    Level: beginner

751:    Concepts: options database^has int

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

755: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
756:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
757:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
758:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
759:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
760:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
761:           PetscOptionsList(), PetscOptionsEList()
762: @*/
763: PetscErrorCode  PetscOptionsReal(const char opt[],const char text[],const char man[],PetscReal defaultv,PetscReal *value,PetscBool  *set)
764: {
766:   PetscOptions   amsopt;

769:   if (!PetscOptionsPublishCount) {
770:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL,&amsopt);
771:     PetscMalloc(sizeof(PetscReal),&amsopt->data);
772:     *(PetscReal*)amsopt->data = defaultv;
773:   }
774:   PetscOptionsGetReal(PetscOptionsObject.prefix,opt,value,set);
775:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
776:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv,text,ManSection(man));
777:   }
778:   return(0);
779: }

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

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

788:    Input Parameters:
789: +  opt - option name
790: .  text - short string that describes the option
791: .  man - manual page with additional information on option
792: -  defaultv - the default (current) value

794:    Output Parameter:
795: +  value - the value to return
796: -  flg - PETSC_TRUE if found, else PETSC_FALSE

798:    Level: beginner

800:    Concepts: options database^has int

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

804: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
805:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
806:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
807:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
808:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
809:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
810:           PetscOptionsList(), PetscOptionsEList()
811: @*/
812: PetscErrorCode  PetscOptionsScalar(const char opt[],const char text[],const char man[],PetscScalar defaultv,PetscScalar *value,PetscBool  *set)
813: {

817: #if !defined(PETSC_USE_COMPLEX)
818:   PetscOptionsReal(opt,text,man,defaultv,value,set);
819: #else
820:   PetscOptionsGetScalar(PetscOptionsObject.prefix,opt,value,set);
821: #endif
822:   return(0);
823: }

827: /*@C
828:    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 
829:                       its value is set to false.

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

833:    Input Parameters:
834: +  opt - option name
835: .  text - short string that describes the option
836: -  man - manual page with additional information on option

838:    Output Parameter:
839: .  flg - PETSC_TRUE if found, else PETSC_FALSE

841:    Level: beginner

843:    Concepts: options database^has int

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

847: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
848:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
849:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
850:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
851:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
852:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
853:           PetscOptionsList(), PetscOptionsEList()
854: @*/
855: PetscErrorCode  PetscOptionsName(const char opt[],const char text[],const char man[],PetscBool  *flg)
856: {
858:   PetscOptions   amsopt;

861:   if (!PetscOptionsPublishCount) {
862:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
863:     PetscMalloc(sizeof(PetscBool),&amsopt->data);
864:     *(PetscBool*)amsopt->data = PETSC_FALSE;
865:   }
866:   PetscOptionsHasName(PetscOptionsObject.prefix,opt,flg);
867:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
868:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
869:   }
870:   return(0);
871: }

875: /*@C
876:      PetscOptionsList - Puts a list of option values that a single one may be selected from

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

880:    Input Parameters:
881: +  opt - option name
882: .  text - short string that describes the option
883: .  man - manual page with additional information on option
884: .  list - the possible choices
885: .  defaultv - the default (current) value
886: -  len - the length of the character array value

888:    Output Parameter:
889: +  value - the value to return
890: -  set - PETSC_TRUE if found, else PETSC_FALSE

892:    Level: intermediate
893:    
894:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

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

901:    Concepts: options database^list

903: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
904:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
905:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
906:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
907:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
908:           PetscOptionsList(), PetscOptionsEList()
909: @*/
910: PetscErrorCode  PetscOptionsList(const char opt[],const char ltext[],const char man[],PetscFList list,const char defaultv[],char value[],size_t len,PetscBool  *set)
911: {
913:   PetscOptions   amsopt;

916:   if (!PetscOptionsPublishCount) {
917:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_LIST,&amsopt);
918:     PetscMalloc(sizeof(char*),&amsopt->data);
919:     *(const char**)amsopt->data = defaultv;
920:     amsopt->flist = list;
921:   }
922:   PetscOptionsGetString(PetscOptionsObject.prefix,opt,value,len,set);
923:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
924:     PetscFListPrintTypes(PetscOptionsObject.comm,stdout,PetscOptionsObject.prefix,opt,ltext,man,list,defaultv);
925:   }
926:   return(0);
927: }

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

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

936:    Input Parameters:
937: +  opt - option name
938: .  ltext - short string that describes the option
939: .  man - manual page with additional information on option
940: .  list - the possible choices
941: .  ntext - number of choices
942: -  defaultv - the default (current) value

944:    Output Parameter:
945: +  value - the index of the value to return
946: -  set - PETSC_TRUE if found, else PETSC_FALSE
947:    
948:    Level: intermediate

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

952:    See PetscOptionsList() for when the choices are given in a PetscFList()

954:    Concepts: options database^list

956: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
957:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
958:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
959:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
960:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
961:           PetscOptionsList(), PetscOptionsEList()
962: @*/
963: PetscErrorCode  PetscOptionsEList(const char opt[],const char ltext[],const char man[],const char *const*list,PetscInt ntext,const char defaultv[],PetscInt *value,PetscBool  *set)
964: {
966:   PetscInt       i;
967:   PetscOptions   amsopt;

970:   if (!PetscOptionsPublishCount) {
971:     PetscOptionsCreate_Private(opt,ltext,man,OPTION_ELIST,&amsopt);
972:     PetscMalloc(sizeof(char*),&amsopt->data);
973:     *(const char**)amsopt->data = defaultv;
974:     amsopt->list  = list;
975:     amsopt->nlist = ntext;
976:   }
977:   PetscOptionsGetEList(PetscOptionsObject.prefix,opt,list,ntext,value,set);
978:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
979:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%s> (choose one of)",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,defaultv);
980:     for (i=0; i<ntext; i++){
981:       (*PetscHelpPrintf)(PetscOptionsObject.comm," %s",list[i]);
982:     }
983:     (*PetscHelpPrintf)(PetscOptionsObject.comm," (%s)\n",ManSection(man));
984:   }
985:   return(0);
986: }

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

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 - whether that option was set or not
1003:    
1004:    Level: intermediate

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

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

1010:     Concepts: options database^logical group

1012: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1013:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1014:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1015:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1016:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1017:           PetscOptionsList(), PetscOptionsEList()
1018: @*/
1019: PetscErrorCode  PetscOptionsBoolGroupBegin(const char opt[],const char text[],const char man[],PetscBool  *flg)
1020: {
1022:   PetscOptions   amsopt;

1025:   if (!PetscOptionsPublishCount) {
1026:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1027:     PetscMalloc(sizeof(PetscBool),&amsopt->data);
1028:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1029:   }
1030:   *flg = PETSC_FALSE;
1031:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1032:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1033:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  Pick at most one of -------------\n");
1034:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1035:   }
1036:   return(0);
1037: }

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

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

1047:    Input Parameters:
1048: +  opt - option name
1049: .  text - short string that describes the option
1050: -  man - manual page with additional information on option

1052:    Output Parameter:
1053: .  flg - PETSC_TRUE if found, else PETSC_FALSE
1054:    
1055:    Level: intermediate

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

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

1061:     Concepts: options database^logical group

1063: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1064:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1065:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1066:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1067:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1068:           PetscOptionsList(), PetscOptionsEList()
1069: @*/
1070: PetscErrorCode  PetscOptionsBoolGroup(const char opt[],const char text[],const char man[],PetscBool  *flg)
1071: {
1073:   PetscOptions   amsopt;

1076:   if (!PetscOptionsPublishCount) {
1077:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1078:     PetscMalloc(sizeof(PetscBool),&amsopt->data);
1079:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1080:   }
1081:   *flg = PETSC_FALSE;
1082:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1083:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1084:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1085:   }
1086:   return(0);
1087: }

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

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

1097:    Input Parameters:
1098: +  opt - option name
1099: .  text - short string that describes the option
1100: -  man - manual page with additional information on option

1102:    Output Parameter:
1103: .  flg - PETSC_TRUE if found, else PETSC_FALSE
1104:    
1105:    Level: intermediate

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

1109:    Must follow a PetscOptionsBoolGroupBegin()

1111:     Concepts: options database^logical group

1113: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1114:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1115:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1116:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1117:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1118:           PetscOptionsList(), PetscOptionsEList()
1119: @*/
1120: PetscErrorCode  PetscOptionsBoolGroupEnd(const char opt[],const char text[],const char man[],PetscBool  *flg)
1121: {
1123:   PetscOptions   amsopt;

1126:   if (!PetscOptionsPublishCount) {
1127:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1128:     PetscMalloc(sizeof(PetscBool),&amsopt->data);
1129:     *(PetscBool*)amsopt->data = PETSC_FALSE;
1130:   }
1131:   *flg = PETSC_FALSE;
1132:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,PETSC_NULL);
1133:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1134:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"    -%s%s: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1135:   }
1136:   return(0);
1137: }

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

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

1146:    Input Parameters:
1147: +  opt - option name
1148: .  text - short string that describes the option
1149: -  man - manual page with additional information on option

1151:    Output Parameter:
1152: .  flg - PETSC_TRUE or PETSC_FALSE
1153: .  set - PETSC_TRUE if found, else PETSC_FALSE

1155:    Level: beginner

1157:    Concepts: options database^logical

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

1161: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1162:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1163:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1164:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1165:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1166:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1167:           PetscOptionsList(), PetscOptionsEList()
1168: @*/
1169: PetscErrorCode  PetscOptionsBool(const char opt[],const char text[],const char man[],PetscBool  deflt,PetscBool  *flg,PetscBool  *set)
1170: {
1172:   PetscBool      iset;
1173:   PetscOptions   amsopt;

1176:   if (!PetscOptionsPublishCount) {
1177:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL,&amsopt);
1178:     PetscMalloc(sizeof(PetscBool),&amsopt->data);
1179:     *(PetscBool*)amsopt->data = deflt;
1180:   }
1181:   PetscOptionsGetBool(PetscOptionsObject.prefix,opt,flg,&iset);
1182:   if (!iset) {
1183:     if (flg) *flg = deflt;
1184:   }
1185:   if (set) *set = iset;
1186:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1187:     const char *v = PetscBools[deflt];
1188:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s: <%s> %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,v,text,ManSection(man));
1189:   }
1190:   return(0);
1191: }

1195: /*@C
1196:    PetscOptionsRealArray - Gets an array of double values for a particular
1197:    option in the database. The values must be separated with commas with 
1198:    no intervening spaces. 

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

1202:    Input Parameters:
1203: +  opt - the option one is seeking
1204: .  text - short string describing option
1205: .  man - manual page for option
1206: -  nmax - maximum number of values

1208:    Output Parameter:
1209: +  value - location to copy values
1210: .  nmax - actual number of values found
1211: -  set - PETSC_TRUE if found, else PETSC_FALSE

1213:    Level: beginner

1215:    Notes: 
1216:    The user should pass in an array of doubles

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

1220:    Concepts: options database^array of strings

1222: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1223:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1224:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1225:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1226:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1227:           PetscOptionsList(), PetscOptionsEList()
1228: @*/
1229: PetscErrorCode  PetscOptionsRealArray(const char opt[],const char text[],const char man[],PetscReal value[],PetscInt *n,PetscBool  *set)
1230: {
1232:   PetscInt       i;
1233:   PetscOptions   amsopt;

1236:   if (!PetscOptionsPublishCount) {
1237:     PetscReal *vals;

1239:     PetscOptionsCreate_Private(opt,text,man,OPTION_REAL_ARRAY,&amsopt);
1240:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
1241:     vals = (PetscReal*)amsopt->data;
1242:     for (i=0; i<*n; i++) vals[i] = value[i];
1243:     amsopt->arraylength = *n;
1244:   }
1245:   PetscOptionsGetRealArray(PetscOptionsObject.prefix,opt,value,n,set);
1246:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1247:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%G",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1248:     for (i=1; i<*n; i++) {
1249:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%G",value[i]);
1250:     }
1251:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1252:   }
1253:   return(0);
1254: }


1259: /*@C
1260:    PetscOptionsIntArray - Gets an array of integers for a particular
1261:    option in the database. The values must be separated with commas with 
1262:    no intervening spaces. 

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

1266:    Input Parameters:
1267: +  opt - the option one is seeking
1268: .  text - short string describing option
1269: .  man - manual page for option
1270: -  n - maximum number of values

1272:    Output Parameter:
1273: +  value - location to copy values
1274: .  n - actual number of values found
1275: -  set - PETSC_TRUE if found, else PETSC_FALSE

1277:    Level: beginner

1279:    Notes: 
1280:    The user should pass in an array of integers

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

1284:    Concepts: options database^array of strings

1286: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1287:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1288:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1289:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1290:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1291:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
1292: @*/
1293: PetscErrorCode  PetscOptionsIntArray(const char opt[],const char text[],const char man[],PetscInt value[],PetscInt *n,PetscBool  *set)
1294: {
1296:   PetscInt       i;
1297:   PetscOptions   amsopt;

1300:   if (!PetscOptionsPublishCount) {
1301:     PetscInt *vals;

1303:     PetscOptionsCreate_Private(opt,text,man,OPTION_INT_ARRAY,&amsopt);
1304:     PetscMalloc((*n)*sizeof(PetscInt),&amsopt->data);
1305:     vals = (PetscInt*)amsopt->data;
1306:     for (i=0; i<*n; i++) vals[i] = value[i];
1307:     amsopt->arraylength = *n;
1308:   }
1309:   PetscOptionsGetIntArray(PetscOptionsObject.prefix,opt,value,n,set);
1310:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1311:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1312:     for (i=1; i<*n; i++) {
1313:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1314:     }
1315:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1316:   }
1317:   return(0);
1318: }

1322: /*@C
1323:    PetscOptionsStringArray - Gets an array of string values for a particular
1324:    option in the database. The values must be separated with commas with 
1325:    no intervening spaces. 

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

1329:    Input Parameters:
1330: +  opt - the option one is seeking
1331: .  text - short string describing option
1332: .  man - manual page for option
1333: -  nmax - maximum number of strings

1335:    Output Parameter:
1336: +  value - location to copy strings
1337: .  nmax - actual number of strings found
1338: -  set - PETSC_TRUE if found, else PETSC_FALSE

1340:    Level: beginner

1342:    Notes: 
1343:    The user should pass in an array of pointers to char, to hold all the
1344:    strings returned by this function.

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

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

1351:    Concepts: options database^array of strings

1353: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1354:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1355:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1356:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1357:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1358:           PetscOptionsList(), PetscOptionsEList()
1359: @*/
1360: PetscErrorCode  PetscOptionsStringArray(const char opt[],const char text[],const char man[],char *value[],PetscInt *nmax,PetscBool  *set)
1361: {
1363:   PetscOptions   amsopt;

1366:   if (!PetscOptionsPublishCount) {
1367:     PetscOptionsCreate_Private(opt,text,man,OPTION_STRING_ARRAY,&amsopt);
1368:     PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1369:     amsopt->arraylength = *nmax;
1370:   }
1371:   PetscOptionsGetStringArray(PetscOptionsObject.prefix,opt,value,nmax,set);
1372:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1373:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <string1,string2,...>: %s (%s)\n",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,text,ManSection(man));
1374:   }
1375:   return(0);
1376: }

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

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

1387:    Input Parameters:
1388: +  opt - the option one is seeking
1389: .  text - short string describing option
1390: .  man - manual page for option
1391: -  nmax - maximum number of values

1393:    Output Parameter:
1394: +  value - location to copy values
1395: .  nmax - actual number of values found
1396: -  set - PETSC_TRUE if found, else PETSC_FALSE

1398:    Level: beginner

1400:    Notes: 
1401:    The user should pass in an array of doubles

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

1405:    Concepts: options database^array of strings

1407: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1408:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1409:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1410:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1411:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1412:           PetscOptionsList(), PetscOptionsEList()
1413: @*/
1414: PetscErrorCode  PetscOptionsBoolArray(const char opt[],const char text[],const char man[],PetscBool  value[],PetscInt *n,PetscBool  *set)
1415: {
1417:   PetscInt       i;
1418:   PetscOptions   amsopt;

1421:   if (!PetscOptionsPublishCount) {
1422:     PetscBool  *vals;

1424:     PetscOptionsCreate_Private(opt,text,man,OPTION_LOGICAL_ARRAY,&amsopt);
1425:     PetscMalloc((*n)*sizeof(PetscBool),&amsopt->data);
1426:     vals = (PetscBool*)amsopt->data;
1427:     for (i=0; i<*n; i++) vals[i] = value[i];
1428:     amsopt->arraylength = *n;
1429:   }
1430:   PetscOptionsGetBoolArray(PetscOptionsObject.prefix,opt,value,n,set);
1431:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1432:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  -%s%s <%d",PetscOptionsObject.prefix?PetscOptionsObject.prefix:"",opt+1,value[0]);
1433:     for (i=1; i<*n; i++) {
1434:       (*PetscHelpPrintf)(PetscOptionsObject.comm,",%d",value[i]);
1435:     }
1436:     (*PetscHelpPrintf)(PetscOptionsObject.comm,">: %s (%s)\n",text,ManSection(man));
1437:   }
1438:   return(0);
1439: }


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

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

1450:    Input Parameter:
1451: .   head - the heading text

1453:    
1454:    Level: intermediate

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

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

1460:    Concepts: options database^subheading

1462: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1463:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1464:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1465:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1466:           PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1467:           PetscOptionsList(), PetscOptionsEList()
1468: @*/
1469: PetscErrorCode  PetscOptionsHead(const char head[])
1470: {

1474:   if (PetscOptionsObject.printhelp && PetscOptionsPublishCount == 1 && !PetscOptionsObject.alreadyprinted) {
1475:     (*PetscHelpPrintf)(PetscOptionsObject.comm,"  %s\n",head);
1476:   }
1477:   return(0);
1478: }