Commits

BarryFSmith committed f7b8a5e Merge

Merge branch 'barry/update-some-manualpages'

Comments (0)

Files changed (13)

include/petsc-private/petscimpl.h

   }
 
 /*MC
-   PetscObjectStateIncrease - Increases the state of any PetscObject,
-   regardless of the type.
+   PetscObjectStateIncrease - Increases the state of any PetscObject
 
    Synopsis:
    #include "petsc-private/petscimpl.h"
          PetscObjectStateIncrease((PetscObject)mat);
 
    Notes: object state is an integer which gets increased every time
-   the object is changed. By saving and later querying the object state
+   the object is changed internally. By saving and later querying the object state
    one can determine whether information about the object is still current.
    Currently, state is maintained for Vec and Mat objects.
 
 -  data - the data to  be attached
 
    Notes
-   The data identifier can best be determined through a call to
-   PetscObjectComposedDataRegister()
+   The data identifier can best be created through a call to  PetscObjectComposedDataRegister()
 
    Level: developer
 M*/

include/petscdmda.h

 
      Level: beginner
 
+     Determines what ghost point values are brought over to each process; in this case the "corner" values are not
+     brought over and hence should not be accessed locally
+
 .seealso: DMDA_STENCIL_BOX, DMDAStencilType, DMDASetStencilType()
 M*/
 
       DM       cda;
 
       DMGetCoordinates(da,&vcoors);
-      DMDAGetCoordinateDA(da,&cda);
+      DMGetCoordinateDM(da,&cda);
       DMDAVecGetArray(cda,vcoors,&coors);
       DMDAGetCorners(cda,&mstart,&nstart,0,&m,&n,0)
       for (i=mstart; i<mstart+m; i++) {
       }
       DMDAVecRestoreArray(dac,vcoors,&coors);
 
-.seealso: DMDACoor3d, DMDAForEachPointBegin(), DMDAGetCoordinateDA(), DMGetCoordinates(), DMDAGetGhostCoordinates()
+.seealso: DMDACoor3d, DMGetCoordinateDM(), DMGetCoordinates(), DMDAGetGhostCoordinates()
 M*/
 typedef struct {PetscScalar x,y;} DMDACoor2d;
 
       DM       cda;
 
       DMGetCoordinates(da,&vcoors);
-      DMDAGetCoordinateDA(da,&cda);
+      DMGetCoordinateDM(da,&cda);
       DMDAVecGetArray(cda,vcoors,&coors);
       DMDAGetCorners(cda,&mstart,&nstart,&pstart,&m,&n,&p)
       for (i=mstart; i<mstart+m; i++) {
       }
       DMDAVecRestoreArray(dac,vcoors,&coors);
 
-.seealso: DMDACoor2d, DMDAForEachPointBegin(), DMDAGetCoordinateDA(), DMGetCoordinates(), DMDAGetGhostCoordinates()
+.seealso: DMDACoor2d, DMGetCoordinateDM(), DMGetCoordinates(), DMDAGetGhostCoordinates()
 M*/
 typedef struct {PetscScalar x,y,z;} DMDACoor3d;
 

include/petscerror.h

 #if defined(PETSC_USE_ERRORCHECKING)
 
 /*MC
-   SETERRQ - Macro that is called when an error has been detected,
+   SETERRQ - Macro to be called when an error has been detected,
 
    Synopsis:
    #include <petscsys.h>
   Level: beginner
 
    Notes:
+    We highly recommend using valgrind http://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind for finding memory problems. This is useful
+    on systems that do not have valgrind, but much much less useful.
+
     Must run with the option -malloc_debug to enable this option
 
     Once the error handler is called the calling function is then returned from with the given error code.
 .   format - the usual printf() format string
 
    Options Database Keys:
-+    -error_output_stdout - cause error messages to be printed to stdout instead of the
-         (default) stderr
--    -error_output_none to turn off all printing of error messages (does not change the way the
-          error is handled.)
++    -error_output_stdout - cause error messages to be printed to stdout instead of the  (default) stderr
+-    -error_output_none to turn off all printing of error messages (does not change the way the error is handled.)
 
    Notes: Use
 $     PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
 $                        error is handled.) and
-$     PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on
-$        of you can use your own function
+$     PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function
 
           Use
      PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
   } while (0)
 
 /*MC
-   PetscFunctionBegin - First executable line of each PETSc function
-        used for error handling.
+   PetscFunctionBegin - First executable line of each PETSc function,  used for error handling. Final
+      line of PETSc functions should be PetscFunctionReturn(0);
 
    Synopsis:
    #include <petscsys.h>
 .ve
 
    Notes:
+     Use PetscFunctionBeginUser for application codes.
+
      Not available in Fortran
 
    Level: developer
 
-.seealso: PetscFunctionReturn()
+.seealso: PetscFunctionReturn(), PetscFunctionBeginHot(), PetscFunctionBeginUser()
 
 .keywords: traceback, error handling
 M*/
 .ve
 
    Notes:
-     Not available in Fortran
+      Final line of PETSc functions should be PetscFunctionReturn(0) except for main().
+
+      Not available in Fortran
 
    Level: intermediate
 

include/petscksp.h

 typedef enum {KSP_GMRES_CGS_REFINE_NEVER, KSP_GMRES_CGS_REFINE_IFNEEDED, KSP_GMRES_CGS_REFINE_ALWAYS} KSPGMRESCGSRefinementType;
 PETSC_EXTERN const char *const KSPGMRESCGSRefinementTypes[];
 /*MC
-    KSP_GMRES_CGS_REFINE_NEVER - Just do the classical (unmodified) Gram-Schmidt process
+    KSP_GMRES_CGS_REFINE_NEVER - Do the classical (unmodified) Gram-Schmidt process
 
    Level: advanced
 
 
    Level: advanced
 
-    Note: Some Krylov methods need to compute a residual norm and then this option is ignored
+    Note: Some Krylov methods need to compute a residual norm (such as GMRES) and then this option is ignored
 
 .seealso: KSPNormType, KSPSetNormType(), KSP_NORM_PRECONDITIONED, KSP_NORM_UNPRECONDITIONED, KSP_NORM_NATURAL
 M*/
 
 /*MC
-    KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual and pass that to the
+    KSP_NORM_PRECONDITIONED - Compute the norm of the preconditioned residual B*(b - A*x), if left preconditioning, and pass that to the
        convergence test routine.
 
    Level: advanced
 PETSC_EXTERN PetscErrorCode KSPSetLagNorm(KSP,PetscBool);
 
 /*E
-    KSPConvergedReason - reason a Krylov method was said to
-         have converged or diverged
+    KSPConvergedReason - reason a Krylov method was said to have converged or diverged
 
    Level: beginner
 
            the preconditioner is applied. Also used when the KSPConvergedSkip() convergence
            test routine is set in KSP.
 
-
    Level: beginner
 
-
 .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
 
 M*/
      KSP_DIVERGED_BREAKDOWN_BICG - A breakdown in the KSPBICG method was detected so the
           method could not continue to enlarge the Krylov space.
 
-
    Level: beginner
 
-
 .seealso:  KSPSolve(), KSPGetConvergedReason(), KSPConvergedReason, KSPSetTolerances()
 
 M*/

include/petscmat.h

 +  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 .  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 .  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 +  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 .  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 .  dnz - the array that will be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 +  dnz - the array that was be passed to the matrix preallocation routines
 -  ozn - the other array passed to the matrix preallocation routines
 
-
    Level: intermediate
 
    Notes:
 M*/
 #define MatPreallocateFinalize(dnz,onz) 0;_4_ierr = PetscFree2(dnz,onz);CHKERRQ(_4_ierr);}
 
-
-
 /* Routines unique to particular data structures */
 PETSC_EXTERN PetscErrorCode MatShellGetContext(Mat,void *);
 

include/petscmath.h

 +  v1 - first value to find minimum of
 -  v2 - second value to find minimum of
 
-
    Notes: type can be integer or floating point value
 
    Level: beginner
 
-
 .seealso: PetscMin(), PetscClipInterval(), PetscAbsInt(), PetscAbsReal(), PetscSqr()
 
 M*/

include/petscoptions.h

 
 /*MC
     PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
-     displayed on the same window of a GUI that allows the user to set the options interactively.
+     displayed on the same window of a GUI that allows the user to set the options interactively. Often one should 
+     use PetscObjectOptionsBegin() rather than this call.
 
    Synopsis:
     #include <petscoptions.h>
 
   Level: intermediate
 
-  Notes: Needs to be preceded by a call to PetscOptionsBegin()
+  Notes: Needs to be preceded by a call to PetscOptionsBegin() or PetscObjectOptionsBegin()
 
 .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
 
   Level: intermediate
 
-   Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
+   Notes: Must be between a PetscOptionsBegin()/PetscObjectOptionsBegin() and a PetscOptionsEnd()
 
           Must be preceded by a call to PetscOptionsHead() in the same function.
 

include/petscsnes.h

               SNES_NORM_FINAL_ONLY         =  3,
               SNES_NORM_INITIAL_FINAL_ONLY =  4} SNESNormSchedule;
 PETSC_EXTERN const char *const*const SNESNormSchedules;
+
 /*MC
     SNES_NORM_NONE - Don't compute function and its L2 norm.
 
 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_SNES_NORM_INITIAL_ONLY, SNES_NORM_FINAL_ONLY
 M*/
 
-
 PETSC_EXTERN PetscErrorCode SNESSetNormSchedule(SNES,SNESNormSchedule);
 PETSC_EXTERN PetscErrorCode SNESGetNormSchedule(SNES,SNESNormSchedule*);
 

include/petscsys.h

 #endif
 
 /*MC
-    PetscErrorCode - datatype used for return error code from all PETSc functions
+    PetscErrorCode - datatype used for return error code from almost all PETSc functions
 
     Level: beginner
 
 /*MC
 
     PetscClassId - A unique id used to identify each PETSc class.
-         (internal integer in the data structure used for error
-         checking). These are all computed by an offset from the lowest
-         one, PETSC_SMALLEST_CLASSID.
-
-    Level: advanced
+
+    Notes: Use PetscClassIdRegister() to obtain a new value for a new class being created. Usually
+         XXXInitializePackage() calls it for each class it defines.
+
+    Developer Notes: Internal integer stored in the _p_PetscObject data structure.
+         These are all computed by an offset from the lowest one, PETSC_SMALLEST_CLASSID.
+
+    Level: developer
 
 .seealso: PetscClassIdRegister(), PetscLogEventRegister(), PetscHeaderCreate()
 M*/

include/petscts.h

   TS_DIVERGED_STEP_REJECTED   = -2
 } TSConvergedReason;
 PETSC_EXTERN const char *const*TSConvergedReasons;
+
 /*MC
    TS_CONVERGED_ITERATING - this only occurs if TSGetConvergedReason() is called during the TSSolve()
 
 M*/
 
 /*MC
-   TS_CONVERGED_ITS - the maximum number of iterations was reached prior to the final time
+   TS_CONVERGED_ITS - the maximum number of iterations (time-steps) was reached prior to the final time
 
    Level: beginner
 
 .seealso: TSSolve(), TSGetConvergedReason(), TSGetAdapt(), TSSetDuration()
 M*/
+
 /*MC
    TS_CONVERGED_USER - user requested termination
 
 
    Level: beginner
 
-.seealso: TSSolve(), TSGetConvergedReason(), TSGetAdapt(), TSGetSNES(), SNESGetConvergedReason()
+   Notes: See TSSetMaxSNESFailures() for how to allow more nonlinear solver failures.
+
+.seealso: TSSolve(), TSGetConvergedReason(), TSGetAdapt(), TSGetSNES(), SNESGetConvergedReason(), TSSetMaxSNESFailures()
 M*/
 
 /*MC
 
    Level: beginner
 
-.seealso: TSSolve(), TSGetConvergedReason(), TSGetAdapt()
+   Notes: See TSSetMaxStepRejections() for how to allow more step rejections.
+
+.seealso: TSSolve(), TSGetConvergedReason(), TSGetAdapt(), TSSetMaxStepRejections()
 M*/
 
 /*E

src/dm/impls/composite/pack.c

 /*MC
    DMCOMPOSITE = "composite" - A DM object that is used to manage data for a collection of DMs
 
-
-
   Level: intermediate
 
 .seealso: DMType, DMCOMPOSITE, DMDACreate(), DMCreate(), DMSetType(), DMCompositeCreate()

src/dm/impls/da/dacreate.c

          The vectors can be thought of as either cell centered or vertex centered on the mesh. But some variables cannot be cell centered and others
          vertex centered.
 
-
   Level: intermediate
 
 .seealso: DMType, DMCOMPOSITE, DMDACreate(), DMCreate(), DMSetType()

src/sys/objects/state.c

 #undef __FUNCT__
 #define __FUNCT__ "PetscObjectComposedDataRegister"
 /*@C
-   PetscObjectComposedDataRegister - Get an available id for
-   composed data
+   PetscObjectComposedDataRegister - Get an available id for composed data
 
    Not Collective
 
 
    Level: developer
 
+   Notes: You must keep this value (for example in a global variable) in order to attach the data to an object or 
+          access in an object.
+
    seealso: PetscObjectComposedDataSetInt()
 
 @*/