Actual source code: aoptions.c

  1: /*$Id: aoptions.c,v 1.34 2001/08/31 16:19:18 bsmith Exp $*/
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

 10:  #include petsc.h
 11:  #include petscsys.h
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif

 16: #if defined(PETSC_HAVE_AMS)
 17: /*
 18:     We keep a linked list of options that have been posted and we are waiting for 
 19:    user selection

 21:     Eventually we'll attach this beast to a MPI_Comm
 22: */
 23: typedef enum {OPTION_INT,OPTION_LOGICAL,OPTION_REAL,OPTION_LIST,OPTION_STRING,OPTION_REAL_ARRAY,OPTION_HEAD} OptionType;
 24: typedef struct _p_OptionsAMS* PetscOptionsAMS;
 25: struct _p_OptionsAMS {
 26:   char            *option;
 27:   char            *text;
 28:   void            *data;
 29:   void            *edata;
 30:   int             arraylength;
 31:   PetscTruth      set;
 32:   OptionType      type;
 33:   PetscOptionsAMS next;
 34:   char            *man;
 35: };
 36: #endif

 38: typedef struct {
 39: #if defined(PETSC_HAVE_AMS)
 40:   AMS_Memory      amem;
 41:   PetscOptionsAMS next;
 42: #endif
 43:   char            *prefix,*mprefix;  /* publish mprefix, not prefix cause the AMS will change it BUT we need to free it*/
 44:   char            *title;
 45:   MPI_Comm        comm;
 46:   PetscTruth      printhelp;
 47:   PetscTruth      changedmethod;
 48: } PetscOptionsPublishObject;
 49: static PetscOptionsPublishObject amspub;
 50: int PetscOptionsPublishCount;

 52: /*MC
 53:     PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
 54:      displayed on the same window of a GUI that allows the user to set the options interactively.

 56:    Synopsis: int PetscOptionsBegin(MPI_Comm comm,char *prefix,char *title,char *mansec)

 58:     Collective on MPI_Comm

 60:   Input Parameters:
 61: +   comm - communicator that shares GUI
 62: .   prefix - options prefix for all options displayed on window
 63: .   title - short descriptive text, for example "Krylov Solver Options"
 64: -   mansec - section of manual pages for options, for example KSP

 66:   Level: intermediate

 68:   Notes: Needs to be ended by a call the PetscOptionsEnd()

 70:          Can add subheadings with PetscOptionsHead()

 72: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
 73:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
 74:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
 75:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
 76:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
 77:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
 78:           PetscOptionsList(), PetscOptionsEList()

 80: M*/
 81: int PetscOptionsBegin_Private(MPI_Comm comm,char *prefix,char *title,char *mansec)
 82: {
 83:   int        ierr;

 86:   PetscStrallocpy(prefix,&amspub.prefix);
 87:   PetscStrallocpy(title,&amspub.title);
 88:   amspub.comm   = comm;
 89:   PetscOptionsHasName(PETSC_NULL,"-help",&amspub.printhelp);
 90:   if (amspub.printhelp && PetscOptionsPublishCount) {
 91:     (*PetscHelpPrintf)(comm,"%s -------------------------------------------------n",title);
 92:   }
 93: 
 94: #if defined(PETSC_HAVE_AMS)
 95:   if (!PetscOptionsPublishCount) {
 96:     AMS_Comm   acomm;
 97:     static int count = 0;
 98:     char       options[16];
 99:     /* the next line is a bug, this will only work if all processors are here, the comm passed in is ignored!!! */
100:     PetscViewerAMSGetAMSComm(PETSC_VIEWER_AMS_(PETSC_COMM_WORLD),&acomm);
101:     sprintf(options,"Options_%d",count++);
102:     AMS_Memory_create(acomm,options,&amspub.amem);
103:     AMS_Memory_take_access(amspub.amem);
104:     amspub.mprefix = amspub.prefix;
105:     AMS_Memory_add_field(amspub.amem,title,&amspub.mprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
106:     AMS_Memory_add_field(amspub.amem,mansec,&amspub.mprefix,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);
107:     amspub.changedmethod = PETSC_FALSE;
108:     AMS_Memory_add_field(amspub.amem,"ChangedMethod",&amspub.changedmethod,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
109:   }
110: #endif
111:   return(0);
112: }

114: /*MC
115:     PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
116:      displayed on the same window of a GUI that allows the user to set the options interactively.

118:     Collective on the MPI_Comm used in PetscOptionsBegin()

120:    Synopsis: int PetscOptionsEnd(void)

122:   Level: intermediate

124:   Notes: Needs to be preceded by a call to PetscOptionsBegin()

126: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
127:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
128:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
129:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
130:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
131:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
132:           PetscOptionsList(), PetscOptionsEList()

134: M*/
135: int PetscOptionsEnd_Private(void)
136: {

140: #if defined(PETSC_HAVE_AMS)
141:   if (!PetscOptionsPublishCount) {
142:     PetscOptionsAMS last;
143:     char       option[256],value[1024],tmp[32];
144:     int        j;

146:     if (amspub.amem < 0) SETERRQ(1,"Called without a call to PetscOptionsBegin()");
147:     AMS_Memory_publish(amspub.amem);
148:     AMS_Memory_grant_access(amspub.amem);
149:     /* wait until accessor has unlocked the memory */
150:     AMS_Memory_lock(amspub.amem,0);
151:     AMS_Memory_take_access(amspub.amem);

153:     /* reset counter to -2; this updates the screen with the new options for the selected method */
154:     if (amspub.changedmethod) PetscOptionsPublishCount = -2;

156:     /*
157:         Free all the PetscOptions in the linked list and add any changed ones to the database
158:     */
159:     while (amspub.next) {
160:       if (amspub.next->set) {
161:         if (amspub.prefix) {
162:           PetscStrcpy(option,"-");
163:           PetscStrcat(option,amspub.prefix);
164:           PetscStrcat(option,amspub.next->option+1);
165:         } else {
166:           PetscStrcpy(option,amspub.next->option);
167:         }

169:         switch (amspub.next->type) {
170:           case OPTION_HEAD:
171:             break;
172:           case OPTION_INT:
173:             sprintf(value,"%d",*(int*)amspub.next->data);
174:             break;
175:           case OPTION_REAL:
176:             sprintf(value,"%g",*(double*)amspub.next->data);
177:             break;
178:           case OPTION_REAL_ARRAY:
179:             sprintf(value,"%g",((PetscReal*)amspub.next->data)[0]);
180:             for (j=1; j<amspub.next->arraylength; j++) {
181:               sprintf(tmp,"%g",((PetscReal*)amspub.next->data)[j]);
182:               PetscStrcat(value,",");
183:               PetscStrcat(value,tmp);
184:             }
185:             break;
186:           case OPTION_LOGICAL:
187:             sprintf(value,"%d",*(int*)amspub.next->data);
188:             break;
189:           case OPTION_LIST:
190:             PetscStrcpy(value,*(char**)amspub.next->data);
191:             break;
192:           case OPTION_STRING: /* also handles string arrays */
193:             PetscStrcpy(value,*(char**)amspub.next->data);
194:             break;
195:         }
196:         PetscOptionsSetValue(option,value);
197:       }
198:       ierr   = PetscStrfree(amspub.next->text);
199:       ierr   = PetscStrfree(amspub.next->option);
200:       ierr   = PetscFree(amspub.next->man);
201:       if (amspub.next->data)  {PetscFree(amspub.next->data);}
202:       if (amspub.next->edata) {PetscFree(amspub.next->edata);}
203:       last        = amspub.next;
204:       amspub.next = amspub.next->next;
205:       ierr        = PetscFree(last);
206:     }
207:     AMS_Memory_grant_access(amspub.amem);
208:     AMS_Memory_destroy(amspub.amem);
209:   }
210: #endif
211:   PetscStrfree(amspub.title); amspub.title  = 0;
212:   PetscStrfree(amspub.prefix); amspub.prefix = 0;
213:   return(0);
214: }

216: #if defined(PETSC_HAVE_AMS)
217: /*
218:      Publishes the "lock" for an option; with a name that is the command line
219:    option name. This is the first item that is always published for an option
220: */
221: static int PetscOptionsCreate_Private(char *opt,char *text,char *man,PetscOptionsAMS *amsopt)
222: {
223:   int             ierr;
224:   static int      mancount = 0;
225:   PetscOptionsAMS next;
226:   char            manname[16];

229:   ierr             = PetscNew(struct _p_OptionsAMS,amsopt);
230:   (*amsopt)->next  = 0;
231:   (*amsopt)->set   = PETSC_FALSE;
232:   (*amsopt)->data  = 0;
233:   (*amsopt)->edata = 0;
234:   ierr             = PetscStrallocpy(text,&(*amsopt)->text);
235:   ierr             = PetscStrallocpy(opt,&(*amsopt)->option);
236:   AMS_Memory_add_field(amspub.amem,opt,&(*amsopt)->set,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
237:   sprintf(manname,"man_%d",mancount++);
238:   ierr                     = PetscMalloc(sizeof(char*),&(*amsopt)->man);
239:   *(char **)(*amsopt)->man = man;
240:   AMS_Memory_add_field(amspub.amem,manname,(*amsopt)->man,1,AMS_STRING,AMS_READ,AMS_COMMON,AMS_REDUCT_UNDEF);

242:   if (!amspub.next) {
243:     amspub.next = *amsopt;
244:   } else {
245:     next = amspub.next;
246:     while (next->next) next = next->next;
247:     next->next = *amsopt;
248:   }
249:   return(0);
250: }
251: #endif

253: /* -------------------------------------------------------------------------------------------------------------*/
254: /*
255:      Publishes an AMS int field (with the default value in it) and with a name
256:    given by the text string
257: */
258: /*@C
259:    PetscOptionsInt - Gets the integer value for a particular option in the database.

261:    Collective on the communicator passed in PetscOptionsBegin()

263:    Input Parameters:
264: +  opt - option name
265: .  text - short string that describes the option
266: .  man - manual page with additional information on option
267: -  defaultv - the default (current) value

269:    Output Parameter:
270: +  value - the integer value to return
271: -  flg - PETSC_TRUE if found, else PETSC_FALSE

273:    Level: beginner

275:    Concepts: options database^has int

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

279: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
280:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
281:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
282:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
283:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
284:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
285:           PetscOptionsList(), PetscOptionsEList()
286: @*/
287: int PetscOptionsInt(char *opt,char *text,char *man,int defaultv,int *value,PetscTruth *set)
288: {
289:   int             ierr;

292: #if defined(PETSC_HAVE_AMS)
293:   if (!PetscOptionsPublishCount) {
294:     PetscOptionsAMS amsopt;
295:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
296:     amsopt->type        = OPTION_INT;
297:     PetscMalloc(sizeof(int),&amsopt->data);
298:     *(int*)amsopt->data = defaultv;
299:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
300:     if (set) *set = PETSC_FALSE;
301:     return(0);
302:   }
303: #endif
304:   PetscOptionsGetInt(amspub.prefix,opt,value,set);
305:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
306:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d>: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
307:   }
308:   return(0);
309: }

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

314:    Collective on the communicator passed in PetscOptionsBegin()

316:    Input Parameters:
317: +  opt - option name
318: .  text - short string that describes the option
319: .  man - manual page with additional information on option
320: -  defaultv - the default (current) value

322:    Output Parameter:
323: +  value - the value to return
324: -  flg - PETSC_TRUE if found, else PETSC_FALSE

326:    Level: beginner

328:    Concepts: options database^has int

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

332: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
333:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
334:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
335:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
336:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
337:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
338:           PetscOptionsList(), PetscOptionsEList()
339: @*/
340: int PetscOptionsString(char *opt,char *text,char *man,char *defaultv,char *value,int len,PetscTruth *set)
341: {
342:   int             ierr;

345: #if defined(PETSC_HAVE_AMS)
346:   if (!PetscOptionsPublishCount) {
347:     PetscOptionsAMS amsopt;
348:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
349:     amsopt->type          = OPTION_STRING;
350:     PetscMalloc(sizeof(char*),&amsopt->data);
351:     *(char**)amsopt->data = defaultv;
352:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
353:     if (set) *set = PETSC_FALSE;
354:     return(0);
355:   }
356: #endif
357:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
358:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
359:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s>: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
360:   }
361:   return(0);
362: }

364: /*
365:      Publishes an AMS double field (with the default value in it) and with a name
366:    given by the text string
367: */
368: /*@C
369:    PetscOptionsReal - Gets the PetscReal value for a particular option in the database.

371:    Collective on the communicator passed in PetscOptionsBegin()

373:    Input Parameters:
374: +  opt - option name
375: .  text - short string that describes the option
376: .  man - manual page with additional information on option
377: -  defaultv - the default (current) value

379:    Output Parameter:
380: +  value - the value to return
381: -  flg - PETSC_TRUE if found, else PETSC_FALSE

383:    Level: beginner

385:    Concepts: options database^has int

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

389: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
390:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
391:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
392:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
393:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
394:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
395:           PetscOptionsList(), PetscOptionsEList()
396: @*/
397: int PetscOptionsReal(char *opt,char *text,char *man,PetscReal defaultv,PetscReal *value,PetscTruth *set)
398: {
399:   int             ierr;

402: #if defined(PETSC_HAVE_AMS)
403:   if (!PetscOptionsPublishCount) {
404:     PetscOptionsAMS amsopt;
405:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
406:     amsopt->type           = OPTION_REAL;
407:     PetscMalloc(sizeof(PetscReal),&amsopt->data);
408:     *(PetscReal*)amsopt->data = defaultv;
409:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
410:     if (set) *set = PETSC_FALSE;
411:     return(0);
412:   }
413: #endif
414:   PetscOptionsGetReal(amspub.prefix,opt,value,set);
415:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
416:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%g>: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,defaultv,text,man);
417:   }
418:   return(0);
419: }

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

424:    Collective on the communicator passed in PetscOptionsBegin()

426:    Input Parameters:
427: +  opt - option name
428: .  text - short string that describes the option
429: .  man - manual page with additional information on option
430: -  defaultv - the default (current) value

432:    Output Parameter:
433: +  value - the value to return
434: -  flg - PETSC_TRUE if found, else PETSC_FALSE

436:    Level: beginner

438:    Concepts: options database^has int

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

442: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
443:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
444:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
445:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
446:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
447:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
448:           PetscOptionsList(), PetscOptionsEList()
449: @*/
450: int PetscOptionsScalar(char *opt,char *text,char *man,PetscScalar defaultv,PetscScalar *value,PetscTruth *set)
451: {

455: #if !defined(PETSC_USE_COMPLEX)
456:   PetscOptionsReal(opt,text,man,defaultv,value,set);
457: #else
458:   PetscOptionsGetScalar(amspub.prefix,opt,value,set);
459: #endif
460:   return(0);
461: }

463: /*
464:      Publishes an AMS logical field (with the default value in it) and with a name
465:    given by the text string
466: */
467: /*@C
468:    PetscOptionsName - Determines if a particular option is in the database

470:    Collective on the communicator passed in PetscOptionsBegin()

472:    Input Parameters:
473: +  opt - option name
474: .  text - short string that describes the option
475: -  man - manual page with additional information on option

477:    Output Parameter:
478: .  flg - PETSC_TRUE if found, else PETSC_FALSE

480:    Level: beginner

482:    Concepts: options database^has int

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

486: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
487:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
488:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
489:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
490:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
491:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
492:           PetscOptionsList(), PetscOptionsEList()
493: @*/
494: int PetscOptionsName(char *opt,char *text,char *man,PetscTruth *flg)
495: {
496:   int             ierr;

499: #if defined(PETSC_HAVE_AMS)
500:   if (!PetscOptionsPublishCount) {
501:     PetscOptionsAMS amsopt;
502:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
503:     amsopt->type        = OPTION_LOGICAL;
504:     PetscMalloc(sizeof(int),&amsopt->data);
505:     *(int*)amsopt->data = 0;
506:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
507:     if (flg) *flg = PETSC_FALSE;
508:     return(0);
509:   }
510: #endif
511:   PetscOptionsHasName(amspub.prefix,opt,flg);
512:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
513:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
514:   }

516:   return(0);
517: }

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

522:    Collective on the communicator passed in PetscOptionsBegin()

524:    Input Parameters:
525: +  opt - option name
526: .  text - short string that describes the option
527: .  man - manual page with additional information on option
528: .  list - the possible choices
529: -  defaultv - the default (current) value

531:    Output Parameter:
532: +  value - the value to return
533: -  set - PETSC_TRUE if found, else PETSC_FALSE

535:    Level: intermediate
536:    
537:    Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()

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

541:    Concepts: options database^list

543: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
544:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
545:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
546:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
547:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
548:           PetscOptionsList(), PetscOptionsEList()
549: @*/
550: int PetscOptionsList(char *opt,char *ltext,char *man,PetscFList list,char *defaultv,char *value,int len,PetscTruth *set)
551: {
552:   int        ierr;

555: #if defined(PETSC_HAVE_AMS)
556:   if (!PetscOptionsPublishCount) {
557:     PetscOptionsAMS amsopt;
558:     int        ntext;
559:     char       ldefault[128];

561:     PetscOptionsCreate_Private(opt,ltext,man,&amsopt);
562:     amsopt->type             = OPTION_LIST;
563:     PetscMalloc(sizeof(char*),&amsopt->data);
564:     *(char **)(amsopt->data) = defaultv;
565:     PetscStrcpy(ldefault,"DEFAULT:");
566:     PetscStrcat(ldefault,ltext);
567:     AMS_Memory_add_field(amspub.amem,ldefault,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);

569:     PetscFListGet(list,(char***)&amsopt->edata,&ntext);
570:     AMS_Memory_add_field(amspub.amem,ltext,amsopt->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
571:     if (set) *set = PETSC_FALSE;
572:     return(0);
573:   }
574: #endif
575:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
576:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
577:     PetscFListPrintTypes(amspub.comm,stdout,amspub.prefix,opt,ltext,man,list);
578:   }

580:   return(0);
581: }

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

586:    Collective on the communicator passed in PetscOptionsBegin()

588:    Input Parameters:
589: +  opt - option name
590: .  text - short string that describes the option
591: .  man - manual page with additional information on option
592: .  list - the possible choices
593: .  ntext - number of choices
594: .  defaultv - the default (current) value
595: -  len - the size of the output value array

597:    Output Parameter:
598: +  value - the value to return
599: -  set - PETSC_TRUE if found, else PETSC_FALSE
600:    
601:    Level: intermediate

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

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

607:    Concepts: options database^list

609: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
610:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
611:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
612:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
613:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
614:           PetscOptionsList(), PetscOptionsEList()
615: @*/
616: int PetscOptionsEList(char *opt,char *ltext,char *man,char **list,int ntext,char *defaultv,char *value,int len,PetscTruth *set)
617: {
618:   int i,ierr;

621: #if defined(PETSC_HAVE_AMS)
622:   if (!PetscOptionsPublishCount) {
623:     PetscOptionsAMS amsopt;
624:     char       ldefault[128];

626:     PetscOptionsCreate_Private(opt,ltext,man,&amsopt);
627:     amsopt->type             = OPTION_LIST;
628:     PetscMalloc(sizeof(char*),&amsopt->data);
629:     *(char **)(amsopt->data) = defaultv;
630:     PetscStrcpy(ldefault,"DEFAULT:");
631:     PetscStrcat(ldefault,ltext);
632:     AMS_Memory_add_field(amspub.amem,ldefault,amsopt->data,1,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);

634:     PetscMalloc((ntext+1)*sizeof(char**),&amsopt->edata);
635:     PetscMemcpy(amsopt->edata,list,ntext*sizeof(char*));
636:     AMS_Memory_add_field(amspub.amem,ltext,amsopt->edata,ntext,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
637:     if (set) *set = PETSC_FALSE;
638:     return(0);
639:   }
640: #endif
641:   PetscOptionsGetString(amspub.prefix,opt,value,len,set);
642:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
643:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%s> (one of)",amspub.prefix?amspub.prefix:"",opt+1,defaultv);
644:     for (i=0; i<ntext; i++){
645:       (*PetscHelpPrintf)(amspub.comm," %s",list[i]);
646:     }
647:     (*PetscHelpPrintf)(amspub.comm,"n");
648:   }

650:   return(0);
651: }

653: /*@C
654:      PetscOptionsLogicalGroupBegin - First in a series of logical queries on the options database for
655:        which only a single value can be true.

657:    Collective on the communicator passed in PetscOptionsBegin()

659:    Input Parameters:
660: +  opt - option name
661: .  text - short string that describes the option
662: -  man - manual page with additional information on option

664:    Output Parameter:
665: .  flg - whether that option was set or not
666:    
667:    Level: intermediate

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

671:    Must be followed by 0 or more PetscOptionsLogicalGroup()s and PetscOptionsLogicalGroupEnd()

673:     Concepts: options database^logical group

675: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
676:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
677:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
678:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
679:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
680:           PetscOptionsList(), PetscOptionsEList()
681: @*/
682: int PetscOptionsLogicalGroupBegin(char *opt,char *text,char *man,PetscTruth *flg)
683: {
684:   int             ierr;

687: #if defined(PETSC_HAVE_AMS)
688:   if (!PetscOptionsPublishCount) {
689:     PetscOptionsAMS amsopt;
690:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
691:     amsopt->type        = OPTION_LOGICAL;
692:     PetscMalloc(sizeof(int),&amsopt->data);
693:     *(int*)amsopt->data = 1; /* the first one listed is always the default */
694:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
695:     if (flg) *flg = PETSC_FALSE;
696:     return(0);
697:   }
698: #endif
699:   PetscOptionsHasName(amspub.prefix,opt,flg);
700:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
701:     (*PetscHelpPrintf)(amspub.comm,"  Pick at most one of -------------n");
702:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
703:   }

705:   return(0);
706: }

708: /*@C
709:      PetscOptionsLogicalGroup - One in a series of logical queries on the options database for
710:        which only a single value can be true.

712:    Collective on the communicator passed in PetscOptionsBegin()

714:    Input Parameters:
715: +  opt - option name
716: .  text - short string that describes the option
717: -  man - manual page with additional information on option

719:    Output Parameter:
720: .  flg - PETSC_TRUE if found, else PETSC_FALSE
721:    
722:    Level: intermediate

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

726:    Must follow a PetscOptionsLogicalGroupBegin() and preceded a PetscOptionsLogicalGroupEnd()

728:     Concepts: options database^logical group

730: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
731:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
732:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
733:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
734:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
735:           PetscOptionsList(), PetscOptionsEList()
736: @*/
737: int PetscOptionsLogicalGroup(char *opt,char *text,char *man,PetscTruth *flg)
738: {
739:   int             ierr;

742: #if defined(PETSC_HAVE_AMS)
743:   if (!PetscOptionsPublishCount) {
744:     PetscOptionsAMS amsopt;
745:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
746:     amsopt->type        = OPTION_LOGICAL;
747:     PetscMalloc(sizeof(int),&amsopt->data);
748:     *(int*)amsopt->data = 0;
749:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
750:     if (flg) *flg = PETSC_FALSE;
751:     return(0);
752:   }
753: #endif
754:   PetscOptionsHasName(amspub.prefix,opt,flg);
755:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
756:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
757:   }

759:   return(0);
760: }

762: /*@C
763:      PetscOptionsLogicalGroupEnd - Last in a series of logical queries on the options database for
764:        which only a single value can be true.

766:    Collective on the communicator passed in PetscOptionsBegin()

768:    Input Parameters:
769: +  opt - option name
770: .  text - short string that describes the option
771: -  man - manual page with additional information on option

773:    Output Parameter:
774: .  flg - PETSC_TRUE if found, else PETSC_FALSE
775:    
776:    Level: intermediate

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

780:    Must follow a PetscOptionsLogicalGroupBegin()

782:     Concepts: options database^logical group

784: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
785:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
786:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
787:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
788:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
789:           PetscOptionsList(), PetscOptionsEList()
790: @*/
791: int PetscOptionsLogicalGroupEnd(char *opt,char *text,char *man,PetscTruth *flg)
792: {
793:   int             ierr;

796: #if defined(PETSC_HAVE_AMS)
797:   if (!PetscOptionsPublishCount) {
798:     PetscOptionsAMS amsopt;
799:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
800:     amsopt->type        = OPTION_LOGICAL;
801:     PetscMalloc(sizeof(int),&amsopt->data);
802:     *(int*)amsopt->data = 0;
803:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
804:     if (flg) *flg = PETSC_FALSE;
805:     return(0);
806:   }
807: #endif
808:   PetscOptionsHasName(amspub.prefix,opt,flg);
809:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
810:     (*PetscHelpPrintf)(amspub.comm,"    -%s%s: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
811:   }

813:   return(0);
814: }

816: /*@C
817:    PetscOptionsLogical - Determines if a particular option is in the database with a true or false

819:    Collective on the communicator passed in PetscOptionsBegin()

821:    Input Parameters:
822: +  opt - option name
823: .  text - short string that describes the option
824: -  man - manual page with additional information on option

826:    Output Parameter:
827: .  flg - PETSC_TRUE or PETSC_FALSE
828: .  set - PETSC_TRUE if found, else PETSC_FALSE

830:    Level: beginner

832:    Concepts: options database^logical

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

836: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
837:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
838:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
839:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
840:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
841:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
842:           PetscOptionsList(), PetscOptionsEList()
843: @*/
844: int PetscOptionsLogical(char *opt,char *text,char *man,PetscTruth deflt,PetscTruth *flg,PetscTruth *set)
845: {
846:   int        ierr;
847:   PetscTruth iset;

850: #if defined(PETSC_HAVE_AMS)
851:   if (!PetscOptionsPublishCount) {
852:     PetscOptionsAMS amsopt;
853:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
854:     amsopt->type        = OPTION_LOGICAL;
855:     PetscMalloc(sizeof(int),&amsopt->data);
856:     *(int*)amsopt->data = (int)deflt;
857:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
858:     if (flg) *flg = PETSC_FALSE;
859:     return(0);
860:   }
861: #endif
862:   PetscOptionsGetLogical(amspub.prefix,opt,flg,&iset);
863:   if (iset == PETSC_FALSE) {
864:     if (flg != PETSC_NULL) *flg = deflt;
865:   }
866:   if (set != PETSC_NULL) *set = iset;
867:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
868:     const char *v = (deflt ? "true" : "false");
869:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s: <%s> %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,v,text,man);
870:   }

872:   return(0);
873: }

875: /*@C
876:    PetscOptionsRealArray - Gets an array of double values for a particular
877:    option in the database. The values must be separated with commas with 
878:    no intervening spaces. 

880:    Collective on the communicator passed in PetscOptionsBegin()

882:    Input Parameters:
883: +  opt - the option one is seeking
884: .  text - short string describing option
885: .  man - manual page for option
886: -  nmax - maximum number of values

888:    Output Parameter:
889: +  value - location to copy values
890: .  nmax - actual number of values found
891: -  set - PETSC_TRUE if found, else PETSC_FALSE

893:    Level: beginner

895:    Notes: 
896:    The user should pass in an array of doubles

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

900:    Concepts: options database^array of strings

902: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
903:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
904:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
905:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
906:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
907:           PetscOptionsList(), PetscOptionsEList()
908: @*/
909: int PetscOptionsRealArray(char *opt,char *text,char *man,PetscReal *value,int *n,PetscTruth *set)
910: {
911:   int             ierr,i;

914: #if defined(PETSC_HAVE_AMS)
915:   if (!PetscOptionsPublishCount) {
916:     PetscOptionsAMS amsopt;
917:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
918:     amsopt->type           = OPTION_REAL_ARRAY;
919:     amsopt->arraylength    = *n;
920:     PetscMalloc((*n)*sizeof(PetscReal),&amsopt->data);
921:     ierr                   = PetscMemcpy(amsopt->data,value,(*n)*sizeof(PetscReal));
922:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_DOUBLE,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
923:     if (set) *set = PETSC_FALSE;
924:     return(0);
925:   }
926: #endif
927:   PetscOptionsGetRealArray(amspub.prefix,opt,value,n,set);
928:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
929:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%g",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
930:     for (i=1; i<*n; i++) {
931:       (*PetscHelpPrintf)(amspub.comm,",%g",value[i]);
932:     }
933:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)n",text,man);
934:   }
935:   return(0);
936: }


939: /*@C
940:    PetscOptionsIntArray - Gets an array of integers for a particular
941:    option in the database. The values must be separated with commas with 
942:    no intervening spaces. 

944:    Collective on the communicator passed in PetscOptionsBegin()

946:    Input Parameters:
947: +  opt - the option one is seeking
948: .  text - short string describing option
949: .  man - manual page for option
950: -  nmax - maximum number of values

952:    Output Parameter:
953: +  value - location to copy values
954: .  nmax - actual number of values found
955: -  set - PETSC_TRUE if found, else PETSC_FALSE

957:    Level: beginner

959:    Notes: 
960:    The user should pass in an array of integers

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

964:    Concepts: options database^array of strings

966: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
967:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
968:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
969:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
970:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
971:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsRealArray()
972: @*/
973: int PetscOptionsIntArray(char *opt,char *text,char *man,int *value,int *n,PetscTruth *set)
974: {
975:   int             ierr,i;

978: #if defined(PETSC_HAVE_AMS)
979:   if (!PetscOptionsPublishCount) {
980:     PetscOptionsAMS amsopt;
981:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
982:     amsopt->type           = OPTION_REAL_ARRAY;
983:     amsopt->arraylength    = *n;
984:     PetscMalloc((*n)*sizeof(int),&amsopt->data);
985:     ierr                   = PetscMemcpy(amsopt->data,value,(*n)*sizeof(int));
986:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,*n,AMS_INT,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
987:     if (set) *set = PETSC_FALSE;
988:     return(0);
989:   }
990: #endif
991:   PetscOptionsGetIntArray(amspub.prefix,opt,value,n,set);
992:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
993:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <%d",amspub.prefix?amspub.prefix:"",opt+1,value[0]);
994:     for (i=1; i<*n; i++) {
995:       (*PetscHelpPrintf)(amspub.comm,",%d",value[i]);
996:     }
997:     (*PetscHelpPrintf)(amspub.comm,">: %s (%s)n",text,man);
998:   }
999:   return(0);
1000: }

1002: /*@C
1003:    PetscOptionsStringArray - Gets an array of string values for a particular
1004:    option in the database. The values must be separated with commas with 
1005:    no intervening spaces. 

1007:    Collective on the communicator passed in PetscOptionsBegin()

1009:    Input Parameters:
1010: +  opt - the option one is seeking
1011: .  text - short string describing option
1012: .  man - manual page for option
1013: -  nmax - maximum number of strings

1015:    Output Parameter:
1016: +  value - location to copy strings
1017: .  nmax - actual number of strings found
1018: -  set - PETSC_TRUE if found, else PETSC_FALSE

1020:    Level: beginner

1022:    Notes: 
1023:    The user should pass in an array of pointers to char, to hold all the
1024:    strings returned by this function.

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

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

1031:    Concepts: options database^array of strings

1033: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1034:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1035:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1036:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1037:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1038:           PetscOptionsList(), PetscOptionsEList()
1039: @*/
1040: int PetscOptionsStringArray(char *opt,char *text,char *man,char **value,int *nmax,PetscTruth *set)
1041: {
1042:   int             ierr;

1045: #if defined(PETSC_HAVE_AMS)
1046:   if (!PetscOptionsPublishCount) {
1047:     PetscOptionsAMS amsopt;
1048:     PetscOptionsCreate_Private(opt,text,man,&amsopt);
1049:     amsopt->type          = OPTION_STRING;
1050:     PetscMalloc((*nmax)*sizeof(char*),&amsopt->data);
1051:     ierr                  = PetscMemzero(amsopt->data,(*nmax)*sizeof(char*));
1052:     AMS_Memory_add_field(amspub.amem,text,amsopt->data,*nmax,AMS_STRING,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1053:     if (set) *set = PETSC_FALSE;
1054:     return(0);
1055:   }
1056: #endif
1057:   PetscOptionsGetStringArray(amspub.prefix,opt,value,nmax,set);
1058:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1059:     (*PetscHelpPrintf)(amspub.comm,"  -%s%s <string1,string2,...>: %s (%s)n",amspub.prefix?amspub.prefix:"",opt+1,text,man);
1060:   }
1061:   return(0);
1062: }

1064: /*MC
1065:      PetscOptionsTail - Ends a section of options begun with PetscOptionsHead()
1066:             See, for example, KSPSetFromOptions_GMRES().

1068:    Collective on the communicator passed in PetscOptionsBegin()

1070:    Synopsis: int PetscOptionsTail(void)

1072:   Level: intermediate

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

1076:           Must be preceded by a call to PetscOptionsHead() in the same function.

1078:    Concepts: options database^subheading

1080: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1081:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1082:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1083:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1084:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1085:           PetscOptionsList(), PetscOptionsEList()
1086: M*/

1088: /*@C
1089:      PetscOptionsHead - Puts a heading before list any more published options. Used, for example,
1090:             in KSPSetFromOptions_GMRES().

1092:    Collective on the communicator passed in PetscOptionsBegin()

1094:    Input Parameter:
1095: .   head - the heading text

1097:    
1098:    Level: intermediate

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

1102:           Must be followed by a call to PetscOptionsTail() in the same function.

1104:    Concepts: options database^subheading

1106: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1107:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1108:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1109:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1110:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1111:           PetscOptionsList(), PetscOptionsEList()
1112: @*/
1113: int PetscOptionsHead(char *head)
1114: {
1115:   int             ierr;

1118: #if defined(PETSC_HAVE_AMS)
1119:   if (!PetscOptionsPublishCount) {
1120:     PetscOptionsAMS amsopt;
1121:     PetscOptionsCreate_Private("-amshead",head,"None",&amsopt);
1122:     amsopt->type = OPTION_HEAD;
1123:     PetscMalloc(sizeof(int),&amsopt->data);
1124:     *(int*)amsopt->data = 0;
1125:     AMS_Memory_add_field(amspub.amem,head,amsopt->data,1,AMS_BOOLEAN,AMS_WRITE,AMS_COMMON,AMS_REDUCT_UNDEF);
1126:   }
1127: #endif
1128:   if (amspub.printhelp && PetscOptionsPublishCount == 1) {
1129:     (*PetscHelpPrintf)(amspub.comm,"  %sn",head);
1130:   }

1132:   return(0);
1133: }