Actual source code: cgtype.c


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

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

  9:     Logically Collective

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

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

 23:     Level: intermediate

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

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

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

 41:     Logically Collective

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

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

 50:     Level: intermediate

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

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

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

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

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

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

 77:     Logically Collective

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

 83:     Level: advanced

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

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

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

102:     Logically Collective

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

108:     Level: advanced

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

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

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

129:     Collective

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

135:     Level: advanced

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

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

150:     Collective

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

156:     Level: advanced

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