Actual source code: petscprom.c

  1: /*  $Id: petsc_prom.c,v 1.7 2005/04/07 17:43:33 adams Exp $ */
  2: /*  Author:             Mark F. Adams    */
  3: /*  Copyright (c) 2004 by Mark F. Adams  */
  4: /*  Filename:           petsc_prom.c     */
  5: 
  6: /*  -------------------------------------------------------------------- 
  7:     
  8:      This file implements a Prometheus preconditioner for matrices that use
  9:      the Mat interface (various matrix formats).  This wraps the Prometheus
 10:      class - this is a C intercace to a C++ code.

 12:      Prometheus assumes that 'PetscScalar' is 'double'.  Prometheus does 
 13:      have a complex-valued solver, but this is runtime parameter, not a 
 14:      compile time parameter.

 16:      The following basic routines are required for each preconditioner.
 17:           PCCreate_XXX()          - Creates a preconditioner context
 18:           PCSetFromOptions_XXX()  - Sets runtime options
 19:           PCApply_XXX()           - Applies the preconditioner
 20:           PCDestroy_XXX()         - Destroys the preconditioner context
 21:      where the suffix "_XXX" denotes a particular implementation, in
 22:      this case we use _Prometheus (e.g., PCCreate_Prometheus, PCApply_Prometheus).
 23:      These routines are actually called via the common user interface
 24:      routines PCCreate(), PCSetFromOptions(), PCApply(), and PCDestroy(), 
 25:      so the application code interface remains identical for all 
 26:      preconditioners.  
 27:  
 28:      Another key routine is:
 29:           PCSetUp_XXX()           - Prepares for the use of a preconditioner
 30:      by setting data structures and options.   The interface routine PCSetUp()
 31:      is not usually called directly by the user, but instead is called by
 32:      PCApply() if necessary.
 33:  
 34:      Additional basic routines are:
 35:           PCView_XXX()            - Prints details of runtime options that
 36:           have actually been used.
 37:           These are called by application codes via the interface routines
 38:           PCView().
 39:  
 40:      The various types of solvers (preconditioners, Krylov subspace methods,
 41:      nonlinear solvers, timesteppers) are all organized similarly, so the
 42:      above description applies to these categories also.  One exception is
 43:      that the analogues of PCApply() for these components are KSPSolve(), 
 44:      SNESSolve(), and TSSolve().

 46:      Additional optional functionality unique to preconditioners is left and
 47:      right symmetric preconditioner application via PCApplySymmetricLeft() 
 48:      and PCApplySymmetricRight().  The Prometheus implementation is 
 49:      PCApplySymmetricLeftOrRight_Prometheus().

 51:     -------------------------------------------------------------------- */

 53:  #include src/ksp/pc/pcimpl.h

 55: EXTERN PetscErrorCode PCCreate_Prometheus_private( PC pc );
 56: EXTERN PetscErrorCode PCSetUp_Prometheus( PC pc );
 57: EXTERN PetscErrorCode PCSetCoordinates_Prometheus( PC pc, PetscReal *coords );
 58: EXTERN PetscErrorCode PCSetFromOptions_Prometheus(PC pc);
 59: EXTERN PetscErrorCode PCSetUp_Prometheus_Symmetric(PC pc);
 60: EXTERN PetscErrorCode PCSetUp_Prometheus_NonSymmetric(PC pc);
 61: EXTERN PetscErrorCode PCApply_Prometheus( PC pc, Vec x, Vec y );
 62: EXTERN PetscErrorCode PCApplySymmetricLeftOrRight_Prometheus(PC pc,Vec ,Vec );
 63: EXTERN PetscErrorCode PCDestroy_Prometheus(PC pc);
 64: EXTERN PetscErrorCode PCView_Prometheus( PC pc, PetscViewer viewer);

 66: /* -------------------------------------------------------------------------- */
 67: /*
 68:    PCCreate_Prometheus - Creates a Prometheus preconditioner context, Prometheus, 
 69:    and sets this as the private data within the generic preconditioning 
 70:    context, PC, that was created within PCCreate().

 72:    Input Parameter:
 73: .  pc - the preconditioner context

 75:    Application Interface Routine: PCCreate()
 76: */

 78: /*MC
 79:      PCPrometheus - Prometheus (i.e. diagonal scaling preconditioning)

 81:    Options Database Key:
 82: .    -pc_prometheus_rowmax - use the maximum absolute value in each row as the scaling factor,
 83:                         rather than the diagonal

 85:    Level: beginner

 87:   Concepts: Prometheus, diagonal scaling, preconditioners

 89:   Notes: By using KSPSetPreconditionerSide(ksp,PC_SYMMETRIC) or -ksp_symmetric_pc you 
 90:          can scale each side of the matrix by the squareroot of the diagonal entries.

 92:          Zero entries along the diagonal are replaced with the value 1.0

 94: .seealso:  PCCreate(), PCSetType(), PCType (for list of available types), PC
 95: M*/


101: PetscErrorCode PCCreate_Prometheus(PC pc)
102: {
104: 

107:   PCCreate_Prometheus_private( pc );
108: 
109:   /*
110:     Set the pointers for the functions that are provided above.
111:     Now when the user-level routines (such as PCApply(), PCDestroy(), etc.)
112:     are called, they will automatically call these functions.  Note we
113:     choose not to provide a couple of these functions since they are
114:     not needed.
115:   */
116:   pc->ops->apply               = PCApply_Prometheus;
117:   pc->ops->applytranspose      = PCApply_Prometheus;
118:   pc->ops->setup               = PCSetUp_Prometheus;
119:   pc->ops->destroy             = PCDestroy_Prometheus;
120:   pc->ops->setfromoptions      = PCSetFromOptions_Prometheus;
121:   pc->ops->view                = PCView_Prometheus;
122:   pc->ops->applyrichardson     = 0;
123:   pc->ops->applysymmetricleft  = 0;/* PCApplySymmetricLeftOrRight_Prometheus; */
124:   pc->ops->applysymmetricright = 0;/* PCApplySymmetricLeftOrRight_Prometheus; */
125:   PetscObjectComposeFunctionDynamic( (PetscObject)pc,
126:                                             "PCSetCoordinates_Prometheus_C",
127:                                             "PCSetCoordinates_Prometheus",
128:                                             PCSetCoordinates_Prometheus);
129: 

131:   return(0);
132: }