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 private/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_C",
127: "PCSetCoordinates_Prometheus",
128: PCSetCoordinates_Prometheus);
129:
130: return(0);
131: }
136: /*@
137: PCSetCoordinates - sets the coordinates of all the nodes on the local process
139: Collective on PC
141: Input Parameters:
142: + pc - the solver context
143: - coords - the coordinates
145: Level: intermediate
147: Notes: coords is an array of the 3D coordinates for the nodes on
148: the local processor. So if there are 108 equation on a processor
149: for a displacement finite element discretization of elasticity (so
150: that there are 36 = 108/3 nodes) then the array must have 108
151: double precision values (ie, 3 * 36). These x y z coordinates
152: should be ordered for nodes 0 to N-1 like so: [ 0.x, 0.y, 0.z, 1.x,
153: ... , N-1.z ].
155: .seealso: PCPROMETHEUS
156: @*/
157: PetscErrorCode PETSCKSP_DLLEXPORT PCSetCoordinates(PC pc,PetscReal *coords)
158: {
162: PetscTryMethod(pc,PCSetCoordinates_C,(PC,PetscReal*),(pc,coords));
163: return(0);
164: }