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 <petsc-private/pcimpl.h>     /*I "petscpc.h" I*/
 54: #include <petscpromproto.h>

 56: /* -------------------------------------------------------------------------- */
 57: /*
 58:    PCCreate_Prometheus - Creates a Prometheus preconditioner context, Prometheus, 
 59:    and sets this as the private data within the generic preconditioning 
 60:    context, PC, that was created within PCCreate().

 62:    Input Parameter:
 63: .  pc - the preconditioner context

 65:    Application Interface Routine: PCCreate()
 66: */

 68: /*MC
 69:      PCPROMETHEUS - Prometheus preconditioner

 71:    Level: intermediate

 73:   Concepts: Prometheus, preconditioners

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

 78: EXTERN_C_BEGIN

 82: PetscErrorCode PCCreate_Prometheus(PC pc)
 83: {
 85: 

 88:   PCCreate_Prometheus_private( pc );
 89: 
 90:   /*
 91:     Set the pointers for the functions that are provided above.
 92:     Now when the user-level routines (such as PCApply(), PCDestroy(), etc.)
 93:     are called, they will automatically call these functions.  Note we
 94:     choose not to provide a couple of these functions since they are
 95:     not needed.
 96:   */
 97:   pc->ops->apply               = PCApply_Prometheus;
 98:   pc->ops->applytranspose      = PCApply_Prometheus;
 99:   pc->ops->setup               = PCSetUp_Prometheus;
100:   pc->ops->destroy             = PCDestroy_Prometheus;
101:   pc->ops->setfromoptions      = PCSetFromOptions_Prometheus;
102:   pc->ops->view                = PCView_Prometheus;
103:   pc->ops->applyrichardson     = 0;
104:   pc->ops->applysymmetricleft  = 0;/* PCApplySymmetricLeftOrRight_Prometheus; */
105:   pc->ops->applysymmetricright = 0;/* PCApplySymmetricLeftOrRight_Prometheus; */
106:   PetscObjectComposeFunctionDynamic( (PetscObject)pc,
107:                                             "PCSetCoordinates_C",
108:                                             "PCSetCoordinates_Prometheus",
109:                                             PCSetCoordinates_Prometheus);
110:   PetscObjectComposeFunctionDynamic( (PetscObject)pc,
111:                                             "PCSASetVectors_C",
112:                                             "PCSASetVectors_Prometheus",
113:                                             PCSASetVectors_Prometheus);
114:   return(0);
115: }

117: EXTERN_C_END

121: /*@
122:    PCSASetVectors - sets the vectors of all the nodes on the local process

124:    Collective on PC

126:    Input Parameters:
127: +  pc - the solver context
128: .  nects - the number of vectors
129: -  vects - the vectors

131:    Level: intermediate

133:    Notes: 'vects' is a dense tall skinny matrix with 'nvects' columns and 
134:    the number of local equations rows.  'vects' is stored in row major order.

136: .seealso: PCPROMETHEUS
137: @*/
138: PetscErrorCode  PCSASetVectors(PC pc,PetscInt nvects,PetscReal *vects)
139: {

143:   PetscTryMethod(pc,"PCSASetVectors_C",(PC,PetscInt,PetscReal*),(pc,nvects,vects));
144:   return(0);
145: }