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:
    130:   return(0);
    131: }

    136: /*@
    137:    PCPrometheusSetCoordinates - sets the coordinates of all the nodes

    139:    Collective on PC

    141:    Input Parameters:
    142: +  pc - the solver context
    143: -  coords - the coordinates

    145:    Level: intermediate

    147: .seealso: PCPROMETHEUS
    148: @*/
    149: PetscErrorCode PETSCKSP_DLLEXPORT PCPrometheusSetCoordinates(PC pc,PetscReal *coords)
    150: {

    154:   PetscTryMethod(pc,PCSetCoordinates_Prometheus_C,(PC,PetscReal*),(pc,coords));
    155:   return(0);
    156: }