Actual source code: cgtype.c

  1: #include <../src/ksp/ksp/impls/cg/cgimpl.h>

  3: /*@
  4:   KSPCGSetType - Sets the variant of the conjugate gradient method to
  5:   use for solving a linear system with a complex coefficient matrix.
  6:   This option is irrelevant when solving a real system.

  8:   Logically Collective

 10:   Input Parameters:
 11: + ksp  - the iterative context
 12: - type - the variant of CG to use, one of
 13: .vb
 14:       KSP_CG_HERMITIAN - complex, Hermitian matrix (default)
 15:       KSP_CG_SYMMETRIC - complex, symmetric matrix
 16: .ve

 18:   Options Database Keys:
 19: + -ksp_cg_type hermitian - Indicates Hermitian matrix
 20: - -ksp_cg_type symmetric - Indicates symmetric matrix

 22:   Level: intermediate

 24:   Note:
 25:   By default, the matrix is assumed to be complex, Hermitian.

 27: .seealso: [](ch_ksp), `KSP`, `KSPCG`
 28: @*/
 29: PetscErrorCode KSPCGSetType(KSP ksp, KSPCGType type)
 30: {
 31:   PetscFunctionBegin;
 33:   PetscTryMethod(ksp, "KSPCGSetType_C", (KSP, KSPCGType), (ksp, type));
 34:   PetscFunctionReturn(PETSC_SUCCESS);
 35: }

 37: /*@
 38:   KSPCGUseSingleReduction - Merge the two inner products needed in `KSPCG` into a single `MPI_Allreduce()` call.

 40:   Logically Collective

 42:   Input Parameters:
 43: + ksp - the iterative context
 44: - flg - turn on or off the single reduction

 46:   Options Database Key:
 47: . -ksp_cg_single_reduction <bool> - Merge inner products into single `MPI_Allreduce()`

 49:   Level: intermediate

 51:   Notes:
 52:   The algorithm used in this case is described as Method 1 in [1]. V. Eijkhout credits the algorithm initially to Chronopoulos and Gear.

 54:   It requires two extra work vectors than the conventional implementation in PETSc.

 56:   See also `KSPPIPECG`, `KSPPIPECR`, and `KSPGROPPCG` that use non-blocking reductions. [](sec_pipelineksp),

 58:   References:
 59: .   [1] - Lapack Working Note 56, "Conjugate Gradient Algorithms with Reduced Synchronization Overhead
 60:   Distributed Memory Multiprocessors", by E. F. D'Azevedo, V. L. Eijkhout, and C. H. Romine, December 3, 1999.

 62: .seealso: [](ch_ksp), [](sec_pipelineksp), `KSP`, `KSPCG`, `KSPGMRES`, `KSPPIPECG`, `KSPPIPECR`, `and KSPGROPPCG`
 63: @*/
 64: PetscErrorCode KSPCGUseSingleReduction(KSP ksp, PetscBool flg)
 65: {
 66:   PetscFunctionBegin;
 69:   PetscTryMethod(ksp, "KSPCGUseSingleReduction_C", (KSP, PetscBool), (ksp, flg));
 70:   PetscFunctionReturn(PETSC_SUCCESS);
 71: }

 73: /*@
 74:   KSPCGSetRadius - Sets the radius of the trust region

 76:   Logically Collective

 78:   Input Parameters:
 79: + ksp    - the iterative context
 80: - radius - the trust region radius (0 is the default that disable the use of the radius)

 82:   Level: advanced

 84:   Note:
 85:   When radius is greater then 0, the Steihaugh-Toint trick is used

 87: .seealso: [](ch_ksp), `KSP`, `KSPCG`, `KSPNASH`, `KSPSTCG`, `KSPGLTR`
 88: @*/
 89: PetscErrorCode KSPCGSetRadius(KSP ksp, PetscReal radius)
 90: {
 91:   PetscFunctionBegin;
 94:   PetscTryMethod(ksp, "KSPCGSetRadius_C", (KSP, PetscReal), (ksp, radius));
 95:   PetscFunctionReturn(PETSC_SUCCESS);
 96: }

 98: /*@
 99:   KSPCGSetObjectiveTarget - Sets the target value for the quadratic model reduction

101:   Logically Collective

103:   Input Parameters:
104: + ksp - the iterative context
105: - obj - the objective value (0 is the default)

107:   Level: advanced

109:   Note:
110:   The CG process will stop when the current objective function
111:   1/2 x_k * A * x_k - b * x_k is smaller than obj if obj is negative.
112:   Otherwise the test is ignored.

114: .seealso: [](ch_ksp), `KSP`, `KSPCG`, `KSPNASH`, `KSPSTCG`, `KSPGLTR`
115: @*/
116: PetscErrorCode KSPCGSetObjectiveTarget(KSP ksp, PetscReal obj)
117: {
118:   PetscFunctionBegin;
121:   PetscTryMethod(ksp, "KSPCGSetObjectiveTarget_C", (KSP, PetscReal), (ksp, obj));
122:   PetscFunctionReturn(PETSC_SUCCESS);
123: }

125: /*@
126:   KSPCGGetNormD - Got norm of the direction when the solver is used inside `SNESNEWTONTR`

128:   Collective

130:   Input Parameters:
131: + ksp    - the iterative context
132: - norm_d - the norm of the direction

134:   Level: advanced

136: .seealso: [](ch_ksp), `KSP`, `KSPCG`, `KSPNASH`, `KSPSTCG`, `KSPGLTR`
137: @*/
138: PetscErrorCode KSPCGGetNormD(KSP ksp, PetscReal *norm_d)
139: {
140:   PetscFunctionBegin;
142:   PetscUseMethod(ksp, "KSPCGGetNormD_C", (KSP, PetscReal *), (ksp, norm_d));
143:   PetscFunctionReturn(PETSC_SUCCESS);
144: }

146: /*@
147:   KSPCGGetObjFcn - Get objective function value when the solver is used inside `SNESNEWTONTR`

149:   Collective

151:   Input Parameters:
152: + ksp   - the iterative context
153: - o_fcn - the objective function value

155:   Level: advanced

157: .seealso: [](ch_ksp), `KSP`, `KSPCG`, `KSPNASH`, `KSPSTCG`, `KSPGLTR`
158: @*/
159: PetscErrorCode KSPCGGetObjFcn(KSP ksp, PetscReal *o_fcn)
160: {
161:   PetscFunctionBegin;
163:   PetscUseMethod(ksp, "KSPCGGetObjFcn_C", (KSP, PetscReal *), (ksp, o_fcn));
164:   PetscFunctionReturn(PETSC_SUCCESS);
165: }