1: /*
  2:    3/99 Modified by Stephen Barnard to support SPAI version 3.0
  3: */

  5: /*
  6:       Provides an interface to the SPAI Sparse Approximate Inverse Preconditioner
  7:    Code written by Stephen Barnard.

  9:       Note: there is some BAD memory bleeding below!

 11:       This code needs work

 13:    1) get rid of all memory bleeding
 14:    2) fix PETSc/interface so that it gets if the matrix is symmetric from the matrix
 15:       rather than having the sp flag for PC_SPAI
 16:    3) fix to set the block size based on the matrix block size

 18: */
 19: #include <petsc/private/petscimpl.h>
 20: #include <petscpc.h>

 22: /*@
 23:   PCSPAISetEpsilon -- Set the tolerance for the `PCSPAI` preconditioner

 25:   Input Parameters:
 26: + pc       - the preconditioner
 27: - epsilon1 - the tolerance (default .4)

 29:   Level: intermediate

 31:   Note:
 32:   `espilon1` must be between 0 and 1. It controls the
 33:   quality of the approximation of M to the inverse of
 34:   A. Higher values of `epsilon1` lead to more work, more
 35:   fill, and usually better preconditioners. In many
 36:   cases the best choice of `epsilon1` is the one that
 37:   divides the total solution time equally between the
 38:   preconditioner and the solver.

 40: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
 41:   @*/
 42: PetscErrorCode PCSPAISetEpsilon(PC pc, PetscReal epsilon1)
 43: {
 44:   PetscFunctionBegin;
 45:   PetscTryMethod(pc, "PCSPAISetEpsilon_C", (PC, PetscReal), (pc, epsilon1));
 46:   PetscFunctionReturn(PETSC_SUCCESS);
 47: }

 49: /*@
 50:   PCSPAISetNBSteps - set maximum number of improvement steps per row in
 51:   the `PCSPAI` preconditioner

 53:   Input Parameters:
 54: + pc       - the preconditioner
 55: - nbsteps1 - number of steps (default 5)

 57:   Note:
 58:   `PCSPAI` constructs to approximation to every column of
 59:   the exact inverse of A in a series of improvement
 60:   steps. The quality of the approximation is determined
 61:   by epsilon. If an approximation achieving an accuracy
 62:   of epsilon is not obtained after `nbsteps1` steps, `PCSPAI` simply
 63:   uses the best approximation constructed so far.

 65:   Level: intermediate

 67: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`, `PCSPAISetMaxNew()`
 68: @*/
 69: PetscErrorCode PCSPAISetNBSteps(PC pc, PetscInt nbsteps1)
 70: {
 71:   PetscFunctionBegin;
 72:   PetscTryMethod(pc, "PCSPAISetNBSteps_C", (PC, PetscInt), (pc, nbsteps1));
 73:   PetscFunctionReturn(PETSC_SUCCESS);
 74: }

 76: /* added 1/7/99 g.h. */
 77: /*@
 78:   PCSPAISetMax - set the size of various working buffers in the `PCSPAI` preconditioner

 80:   Input Parameters:
 81: + pc   - the preconditioner
 82: - max1 - size (default is 5000)

 84:   Level: intermediate

 86: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
 87: @*/
 88: PetscErrorCode PCSPAISetMax(PC pc, PetscInt max1)
 89: {
 90:   PetscFunctionBegin;
 91:   PetscTryMethod(pc, "PCSPAISetMax_C", (PC, PetscInt), (pc, max1));
 92:   PetscFunctionReturn(PETSC_SUCCESS);
 93: }

 95: /*@
 96:   PCSPAISetMaxNew - set maximum number of new nonzero candidates per step in the `PCSPAI` preconditioner

 98:   Input Parameters:
 99: + pc      - the preconditioner
100: - maxnew1 - maximum number (default 5)

102:   Level: intermediate

104: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`, `PCSPAISetNBSteps()`
105: @*/
106: PetscErrorCode PCSPAISetMaxNew(PC pc, PetscInt maxnew1)
107: {
108:   PetscFunctionBegin;
109:   PetscTryMethod(pc, "PCSPAISetMaxNew_C", (PC, PetscInt), (pc, maxnew1));
110:   PetscFunctionReturn(PETSC_SUCCESS);
111: }

113: /*@
114:   PCSPAISetBlockSize - set the block size for the `PCSPAI` preconditioner

116:   Input Parameters:
117: + pc          - the preconditioner
118: - block_size1 - block size (default 1)

120:   Level: intermediate

122:   Notes:
123:   A block
124:   size of 1 treats A as a matrix of scalar elements. A
125:   block size of s > 1 treats A as a matrix of sxs
126:   blocks. A block size of 0 treats A as a matrix with
127:   variable sized blocks, which are determined by
128:   searching for dense square diagonal blocks in A.
129:   This can be very effective for finite-element
130:   matrices.

132:   SPAI will convert A to block form, use a block
133:   version of the preconditioner algorithm, and then
134:   convert the result back to scalar form.

136:   In many cases the a block-size parameter other than 1
137:   can lead to very significant improvement in
138:   performance.

140:   Developer Note:
141:   This preconditioner could use the matrix block size as the default block size to use

143: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
144: @*/
145: PetscErrorCode PCSPAISetBlockSize(PC pc, PetscInt block_size1)
146: {
147:   PetscFunctionBegin;
148:   PetscTryMethod(pc, "PCSPAISetBlockSize_C", (PC, PetscInt), (pc, block_size1));
149:   PetscFunctionReturn(PETSC_SUCCESS);
150: }

152: /*@
153:   PCSPAISetCacheSize - specify cache size in the `PCSPAI` preconditioner

155:   Input Parameters:
156: + pc         - the preconditioner
157: - cache_size - cache size {0,1,2,3,4,5} (default 5)

159:   Level: intermediate

161:   Note:
162:   `PCSPAI` uses a hash table to cache messages and avoid
163:   redundant communication. If suggest always using
164:   5. This parameter is irrelevant in the serial
165:   version.

167: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
168: @*/
169: PetscErrorCode PCSPAISetCacheSize(PC pc, PetscInt cache_size)
170: {
171:   PetscFunctionBegin;
172:   PetscTryMethod(pc, "PCSPAISetCacheSize_C", (PC, PetscInt), (pc, cache_size));
173:   PetscFunctionReturn(PETSC_SUCCESS);
174: }

176: /*@
177:   PCSPAISetVerbose - verbosity level for the `PCSPAI` preconditioner

179:   Input Parameters:
180: + pc      - the preconditioner
181: - verbose - level (default 1)

183:   Level: intermediate

185:   Note:
186:   Prints parameters, timings and matrix statistics

188: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
189: @*/
190: PetscErrorCode PCSPAISetVerbose(PC pc, PetscInt verbose)
191: {
192:   PetscFunctionBegin;
193:   PetscTryMethod(pc, "PCSPAISetVerbose_C", (PC, PetscInt), (pc, verbose));
194:   PetscFunctionReturn(PETSC_SUCCESS);
195: }

197: /*@
198:   PCSPAISetSp - specify a symmetric matrix sparsity pattern in the `PCSPAI` preconditioner

200:   Input Parameters:
201: + pc - the preconditioner
202: - sp - 0 or 1

204:   Level: intermediate

206:   Note:
207:   If A has a symmetric nonzero pattern use `sp` 1 to
208:   improve performance by eliminating some communication
209:   in the parallel version. Even if A does not have a
210:   symmetric nonzero pattern `sp` 1 may well lead to good
211:   results, but the code will not follow the published
212:   SPAI algorithm exactly.

214: .seealso: [](ch_ksp), `PCSPAI`, `PCSetType()`
215: @*/
216: PetscErrorCode PCSPAISetSp(PC pc, PetscInt sp)
217: {
218:   PetscFunctionBegin;
219:   PetscTryMethod(pc, "PCSPAISetSp_C", (PC, PetscInt), (pc, sp));
220:   PetscFunctionReturn(PETSC_SUCCESS);
221: }