Actual source code: itfunc.c

      1: #define PETSCKSP_DLL

      3: /*
      4:       Interface KSP routines that the user calls.
      5: */

     7:  #include src/ksp/ksp/kspimpl.h

     11: /*@
     12:    KSPComputeExtremeSingularValues - Computes the extreme singular values
     13:    for the preconditioned operator. Called after or during KSPSolve().

     15:    Not Collective

     17:    Input Parameter:
     18: .  ksp - iterative context obtained from KSPCreate()

     20:    Output Parameters:
     21: .  emin, emax - extreme singular values

     23:    Notes:
     24:    One must call KSPSetComputeSingularValues() before calling KSPSetUp()
     25:    (or use the option -ksp_compute_eigenvalues) in order for this routine to work correctly.

     27:    Many users may just want to use the monitoring routine
     28:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
     29:    to print the extreme singular values at each iteration of the linear solve.

     31:    Level: advanced

     33: .keywords: KSP, compute, extreme, singular, values

     35: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeEigenvalues()
     36: @*/
     37: PetscErrorCode PETSCKSP_DLLEXPORT KSPComputeExtremeSingularValues(KSP ksp,PetscReal *emax,PetscReal *emin)
     38: {

     45:   if (!ksp->calc_sings) {
     46:     SETERRQ(4,"Singular values not requested before KSPSetUp()");
     47:   }

     49:   if (ksp->ops->computeextremesingularvalues) {
     50:     (*ksp->ops->computeextremesingularvalues)(ksp,emax,emin);
     51:   } else {
     52:     *emin = -1.0;
     53:     *emax = -1.0;
     54:   }
     55:   return(0);
     56: }

     60: /*@
     61:    KSPComputeEigenvalues - Computes the extreme eigenvalues for the
     62:    preconditioned operator. Called after or during KSPSolve().

     64:    Not Collective

     66:    Input Parameter:
     67: +  ksp - iterative context obtained from KSPCreate()
     68: -  n - size of arrays r and c. The number of eigenvalues computed (neig) will, in
     69:        general, be less than this.

     71:    Output Parameters:
     72: +  r - real part of computed eigenvalues
     73: .  c - complex part of computed eigenvalues
     74: -  neig - number of eigenvalues computed (will be less than or equal to n)

     76:    Options Database Keys:
     77: +  -ksp_compute_eigenvalues - Prints eigenvalues to stdout
     78: -  -ksp_plot_eigenvalues - Plots eigenvalues in an x-window display

     80:    Notes:
     81:    The number of eigenvalues estimated depends on the size of the Krylov space
     82:    generated during the KSPSolve() ; for example, with
     83:    CG it corresponds to the number of CG iterations, for GMRES it is the number
     84:    of GMRES iterations SINCE the last restart. Any extra space in r[] and c[]
     85:    will be ignored.

     87:    KSPComputeEigenvalues() does not usually provide accurate estimates; it is
     88:    intended only for assistance in understanding the convergence of iterative
     89:    methods, not for eigenanalysis.

     91:    One must call KSPSetComputeEigenvalues() before calling KSPSetUp()
     92:    in order for this routine to work correctly.

     94:    Many users may just want to use the monitoring routine
     95:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
     96:    to print the singular values at each iteration of the linear solve.

     98:    Level: advanced

    100: .keywords: KSP, compute, extreme, singular, values

    102: .seealso: KSPSetComputeSingularValues(), KSPSingularValueMonitor(), KSPComputeExtremeSingularValues()
    103: @*/
    104: PetscErrorCode PETSCKSP_DLLEXPORT KSPComputeEigenvalues(KSP ksp,PetscInt n,PetscReal *r,PetscReal *c,PetscInt *neig)
    105: {

    113:   if (!ksp->calc_sings) {
    114:     SETERRQ(4,"Eigenvalues not requested before KSPSetUp()");
    115:   }

    117:   if (ksp->ops->computeeigenvalues) {
    118:     (*ksp->ops->computeeigenvalues)(ksp,n,r,c,neig);
    119:   } else {
    120:     *neig = 0;
    121:   }
    122:   return(0);
    123: }

    127: /*@
    128:    KSPSetUpOnBlocks - Sets up the preconditioner for each block in
    129:    the block Jacobi, block Gauss-Seidel, and overlapping Schwarz
    130:    methods.

    132:    Collective on KSP

    134:    Input Parameter:
    135: .  ksp - the KSP context

    137:    Notes:
    138:    KSPSetUpOnBlocks() is a routine that the user can optinally call for
    139:    more precise profiling (via -log_summary) of the setup phase for these
    140:    block preconditioners.  If the user does not call KSPSetUpOnBlocks(),
    141:    it will automatically be called from within KSPSolve().
    142:
    143:    Calling KSPSetUpOnBlocks() is the same as calling PCSetUpOnBlocks()
    144:    on the PC context within the KSP context.

    146:    Level: advanced

    148: .keywords: KSP, setup, blocks

    150: .seealso: PCSetUpOnBlocks(), KSPSetUp(), PCSetUp()
    151: @*/
    152: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetUpOnBlocks(KSP ksp)
    153: {

    158:   PCSetUpOnBlocks(ksp->pc);
    159:   return(0);
    160: }

    164: /*@
    165:    KSPSetUp - Sets up the internal data structures for the
    166:    later use of an iterative solver.

    168:    Collective on KSP

    170:    Input Parameter:
    171: .  ksp   - iterative context obtained from KSPCreate()

    173:    Level: developer

    175: .keywords: KSP, setup

    177: .seealso: KSPCreate(), KSPSolve(), KSPDestroy()
    178: @*/
    179: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetUp(KSP ksp)
    180: {

    186:   /* reset the convergence flag from the previous solves */
    187:   ksp->reason = KSP_CONVERGED_ITERATING;

    189:   if (!ksp->type_name){
    190:     KSPSetType(ksp,KSPGMRES);
    191:   }

    193:   if (ksp->setupcalled == 2) return(0);

    195:   PetscLogEventBegin(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);

    197:   if (!ksp->setupcalled) {
    198:     (*ksp->ops->setup)(ksp);
    199:   }

    201:   /* scale the matrix if requested */
    202:   if (ksp->dscale) {
    203:     Mat mat,pmat;
    204:     PCGetOperators(ksp->pc,&mat,&pmat,PETSC_NULL);
    205:     if (mat == pmat) {
    206:       PetscScalar  *xx;
    207:       PetscInt          i,n;
    208:       PetscTruth   zeroflag = PETSC_FALSE;

    210:       if (!ksp->diagonal) { /* allocate vector to hold diagonal */
    211:         MatGetVecs(pmat,&ksp->diagonal,0);
    212:       }
    213:       MatGetDiagonal(mat,ksp->diagonal);
    214:       VecGetLocalSize(ksp->diagonal,&n);
    215:       VecGetArray(ksp->diagonal,&xx);
    216:       for (i=0; i<n; i++) {
    217:         if (xx[i] != 0.0) xx[i] = 1.0/sqrt(PetscAbsScalar(xx[i]));
    218:         else {
    219:           xx[i]     = 1.0;
    220:           zeroflag  = PETSC_TRUE;
    221:         }
    222:       }
    223:       VecRestoreArray(ksp->diagonal,&xx);
    224:       if (zeroflag) {
    225:         PetscLogInfo((ksp,"KSPSetUp:Zero detected in diagonal of matrix, using 1 at those locations\n"));
    226:       }
    227:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
    228:       ksp->dscalefix2 = PETSC_FALSE;
    229:     } else {
    230:       SETERRQ(PETSC_ERR_SUP,"No support for diagonal scaling of linear system if preconditioner matrix not actual matrix");
    231:     }
    232:   }
    233:   PetscLogEventEnd(KSP_SetUp,ksp,ksp->vec_rhs,ksp->vec_sol,0);
    234:   PCSetUp(ksp->pc);
    235:   if (ksp->nullsp) {
    236:     PetscTruth test;
    237:     PetscOptionsHasName(ksp->prefix,"-ksp_test_null_space",&test);
    238:     if (test) {
    239:       Mat mat;
    240:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
    241:       MatNullSpaceTest(ksp->nullsp,mat);
    242:     }
    243:   }
    244:   ksp->setupcalled = 2;
    245:   return(0);
    246: }

    250: /*@
    251:    KSPSolve - Solves linear system.

    253:    Collective on KSP

    255:    Parameter:
    256: +  ksp - iterative context obtained from KSPCreate()
    257: .  b - the right hand side vector
    258: -  x - the solution

    260:    Options Database Keys:
    261: +  -ksp_compute_eigenvalues - compute preconditioned operators eigenvalues
    262: .  -ksp_plot_eigenvalues - plot the computed eigenvalues in an X-window
    263: .  -ksp_compute_eigenvalues_explicitly - compute the eigenvalues by forming the dense operator and useing LAPACK
    264: .  -ksp_plot_eigenvalues_explicitly - plot the explicitly computing eigenvalues
    265: .  -ksp_view_binary - save matrix and right hand side that define linear system to the default binary viewer (can be
    266:                                 read later with src/ksp/examples/tutorials/ex10.c for testing solvers)
    267: .  -ksp_converged_reason - print reason for converged or diverged
    268: .  -ksp_final_residual - print 2-norm of true linear system residual at the end of the solution process
    269: -  -ksp_view - print the ksp data structure at the end of the system solution

    271:    Notes:

    273:    The operator is specified with PCSetOperators().

    275:    Call KSPGetConvergedReason() to determine if the solver converged or failed and
    276:    why. The number of iterations can be obtained from KSPGetIterationNumber().
    277:
    278:    If using a direct method (e.g., via the KSP solver
    279:    KSPPREONLY and a preconditioner such as PCLU/PCILU),
    280:    then its=1.  See KSPSetTolerances() and KSPDefaultConverged()
    281:    for more details.

    283:    Understanding Convergence:
    284:    The routines KSPSetMonitor(), KSPComputeEigenvalues(), and
    285:    KSPComputeEigenvaluesExplicitly() provide information on additional
    286:    options to monitor convergence and print eigenvalue information.

    288:    Level: beginner

    290: .keywords: KSP, solve, linear system

    292: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
    293:           KSPSolveTranspose(), KSPGetIterationNumber()
    294: @*/
    295: PetscErrorCode PETSCKSP_DLLEXPORT KSPSolve(KSP ksp,Vec b,Vec x)
    296: {
    298:   PetscMPIInt    rank;
    299:   PetscTruth     flag1,flag2,viewed=PETSC_FALSE,flg;
    300:   char           view[10];
    301:   PetscScalar    zero = 0.0;

    307:
    308:   ksp->vec_rhs = b;
    309:   ksp->vec_sol = x;
    310:   PetscOptionsHasName(ksp->prefix,"-ksp_view_binary",&flg);
    311:   if (flg) {
    312:     Mat mat;
    313:     PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
    314:     MatView(mat,PETSC_VIEWER_BINARY_(ksp->comm));
    315:     VecView(ksp->vec_rhs,PETSC_VIEWER_BINARY_(ksp->comm));
    316:   }

    318:   PetscLogEventBegin(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

    320:   /* reset the residual history list if requested */
    321:   if (ksp->res_hist_reset) ksp->res_hist_len = 0;

    323:   PetscOptionsGetString(ksp->prefix,"-ksp_view",view,10,&flg);
    324:   if (flg) {
    325:     PetscStrcmp(view,"before",&viewed);
    326:     if (viewed){
    327:       KSPView(ksp,PETSC_VIEWER_STDOUT_(ksp->comm));
    328:     }
    329:   }

    331:   /* KSPSetUp() scales the matrix if needed */
    332:   KSPSetUp(ksp);
    333:   KSPSetUpOnBlocks(ksp);

    335:   ksp->transpose_solve = PETSC_FALSE;

    337:   /* diagonal scale RHS if called for */
    338:   if (ksp->dscale) {
    339:     VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
    340:     /* second time in, but matrix was scaled back to original */
    341:     if (ksp->dscalefix && ksp->dscalefix2) {
    342:       Mat mat;

    344:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
    345:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
    346:     }

    348:     /*  scale initial guess */
    349:     if (!ksp->guess_zero) {
    350:       if (!ksp->truediagonal) {
    351:         VecDuplicate(ksp->diagonal,&ksp->truediagonal);
    352:         VecCopy(ksp->diagonal,ksp->truediagonal);
    353:         VecReciprocal(ksp->truediagonal);
    354:       }
    355:       VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->truediagonal);
    356:     }
    357:   }
    358:   PCPreSolve(ksp->pc,ksp);

    360:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,zero);}
    361:   if (ksp->guess_knoll) {
    362:     PCApply(ksp->pc,ksp->vec_rhs,ksp->vec_sol);
    363:     KSP_RemoveNullSpace(ksp,ksp->vec_sol);
    364:     ksp->guess_zero = PETSC_FALSE;
    365:   }
    366:   (*ksp->ops->solve)(ksp);
    367:   if (!ksp->reason) {
    368:     SETERRQ(PETSC_ERR_PLIB,"Internal error, solver returned without setting converged reason");
    369:   }
    370:   if (ksp->printreason) {
    371:     if (ksp->reason > 0) {
    372:       PetscPrintf(ksp->comm,"Linear solve converged due to %s\n",KSPConvergedReasons[ksp->reason]);
    373:     } else {
    374:       PetscPrintf(ksp->comm,"Linear solve did not converge due to %s\n",KSPConvergedReasons[ksp->reason]);
    375:     }
    376:   }

    378:   /* diagonal scale solution if called for */
    379:   PCPostSolve(ksp->pc,ksp);
    380:   if (ksp->dscale) {
    381:     VecPointwiseMult(ksp->vec_sol,ksp->vec_sol,ksp->diagonal);
    382:     /* unscale right hand side and matrix */
    383:     if (ksp->dscalefix) {
    384:       Mat mat;

    386:       VecReciprocal(ksp->diagonal);
    387:       VecPointwiseMult(ksp->vec_rhs,ksp->vec_rhs,ksp->diagonal);
    388:       PCGetOperators(ksp->pc,&mat,PETSC_NULL,PETSC_NULL);
    389:       MatDiagonalScale(mat,ksp->diagonal,ksp->diagonal);
    390:       VecReciprocal(ksp->diagonal);
    391:       ksp->dscalefix2 = PETSC_TRUE;
    392:     }
    393:   }
    394:   PetscLogEventEnd(KSP_Solve,ksp,ksp->vec_rhs,ksp->vec_sol,0);

    396:   MPI_Comm_rank(ksp->comm,&rank);

    398:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues",&flag1);
    399:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues",&flag2);
    400:   if (flag1 || flag2) {
    401:     PetscInt   nits,n,i,neig;
    402:     PetscReal *r,*c;
    403:
    404:     KSPGetIterationNumber(ksp,&nits);
    405:     n = nits+2;

    407:     if (!n) {
    408:       PetscPrintf(ksp->comm,"Zero iterations in solver, cannot approximate any eigenvalues\n");
    409:     } else {
    410:       PetscMalloc(2*n*sizeof(PetscReal),&r);
    411:       c = r + n;
    412:       KSPComputeEigenvalues(ksp,n,r,c,&neig);
    413:       if (flag1) {
    414:         PetscPrintf(ksp->comm,"Iteratively computed eigenvalues\n");
    415:         for (i=0; i<neig; i++) {
    416:           if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%g + %gi\n",r[i],c[i]);}
    417:           else             {PetscPrintf(ksp->comm,"%g - %gi\n",r[i],-c[i]);}
    418:         }
    419:       }
    420:       if (flag2 && !rank) {
    421:         PetscViewer viewer;
    422:         PetscDraw   draw;
    423:         PetscDrawSP drawsp;

    425:         PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Iteratively Computed Eigenvalues",
    426:                                PETSC_DECIDE,PETSC_DECIDE,300,300,&viewer);
    427:         PetscViewerDrawGetDraw(viewer,0,&draw);
    428:         PetscDrawSPCreate(draw,1,&drawsp);
    429:         for (i=0; i<neig; i++) {
    430:           PetscDrawSPAddPoint(drawsp,r+i,c+i);
    431:         }
    432:         PetscDrawSPDraw(drawsp);
    433:         PetscDrawSPDestroy(drawsp);
    434:         PetscViewerDestroy(viewer);
    435:       }
    436:       PetscFree(r);
    437:     }
    438:   }

    440:   PetscOptionsHasName(ksp->prefix,"-ksp_compute_eigenvalues_explicitly",&flag1);
    441:   PetscOptionsHasName(ksp->prefix,"-ksp_plot_eigenvalues_explicitly",&flag2);
    442:   if (flag1 || flag2) {
    443:     PetscInt       n,i;
    444:     PetscReal *r,*c;
    445:     VecGetSize(ksp->vec_sol,&n);
    446:     PetscMalloc(2*n*sizeof(PetscReal),&r);
    447:     c = r + n;
    448:     KSPComputeEigenvaluesExplicitly(ksp,n,r,c);
    449:     if (flag1) {
    450:       PetscPrintf(ksp->comm,"Explicitly computed eigenvalues\n");
    451:       for (i=0; i<n; i++) {
    452:         if (c[i] >= 0.0) {PetscPrintf(ksp->comm,"%g + %gi\n",r[i],c[i]);}
    453:         else             {PetscPrintf(ksp->comm,"%g - %gi\n",r[i],-c[i]);}
    454:       }
    455:     }
    456:     if (flag2 && !rank) {
    457:       PetscViewer viewer;
    458:       PetscDraw   draw;
    459:       PetscDrawSP drawsp;

    461:       PetscViewerDrawOpen(PETSC_COMM_SELF,0,"Explicitly Computed Eigenvalues",0,320,300,300,&viewer);
    462:       PetscViewerDrawGetDraw(viewer,0,&draw);
    463:       PetscDrawSPCreate(draw,1,&drawsp);
    464:       for (i=0; i<n; i++) {
    465:         PetscDrawSPAddPoint(drawsp,r+i,c+i);
    466:       }
    467:       PetscDrawSPDraw(drawsp);
    468:       PetscDrawSPDestroy(drawsp);
    469:       PetscViewerDestroy(viewer);
    470:     }
    471:     PetscFree(r);
    472:   }

    474:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator",&flag2);
    475:   if (flag2) {
    476:     Mat A,B;
    477:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
    478:     MatComputeExplicitOperator(A,&B);
    479:     PetscViewerPushFormat(PETSC_VIEWER_STDOUT_(ksp->comm),PETSC_VIEWER_ASCII_MATLAB);
    480:     MatView(B,PETSC_VIEWER_STDOUT_(ksp->comm));
    481:     PetscViewerPopFormat(PETSC_VIEWER_STDOUT_(ksp->comm));
    482:     MatDestroy(B);
    483:   }
    484:   PetscOptionsHasName(ksp->prefix,"-ksp_view_operator_binary",&flag2);
    485:   if (flag2) {
    486:     Mat A,B;
    487:     PCGetOperators(ksp->pc,&A,PETSC_NULL,PETSC_NULL);
    488:     MatComputeExplicitOperator(A,&B);
    489:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
    490:     MatDestroy(B);
    491:   }
    492:   PetscOptionsHasName(ksp->prefix,"-ksp_view_preconditioned_operator_binary",&flag2);
    493:   if (flag2) {
    494:     Mat B;
    495:     KSPComputeExplicitOperator(ksp,&B);
    496:     MatView(B,PETSC_VIEWER_BINARY_(ksp->comm));
    497:     MatDestroy(B);
    498:   }
    499:   if (!viewed) {
    500:     PetscOptionsHasName(ksp->prefix,"-ksp_view",&flg);
    501:     if (flg) {
    502:       KSPView(ksp,PETSC_VIEWER_STDOUT_(ksp->comm));
    503:     }
    504:   }
    505:   PetscOptionsHasName(ksp->prefix,"-ksp_final_residual",&flg);
    506:   if (flg) {
    507:     Mat         A;
    508:     Vec         t;
    509:     PetscScalar mone = -1.0;
    510:     PetscReal   norm;
    511:     if (ksp->dscale && !ksp->dscalefix) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Cannot compute final scale with -ksp_diagonal_scale except also with -ksp_diagonal_scale_fix");
    512:     PCGetOperators(ksp->pc,&A,0,0);
    513:     VecDuplicate(ksp->vec_sol,&t);
    514:     KSP_MatMult(ksp,A,ksp->vec_sol,t);
    515:     VecWAXPY(t,mone,t,ksp->vec_rhs);
    516:     VecNorm(t,NORM_2,&norm);
    517:     VecDestroy(t);
    518:     PetscPrintf(ksp->comm,"KSP final norm of residual %g\n",norm);
    519:   }
    520:   return(0);
    521: }

    525: /*@
    526:    KSPSolveTranspose - Solves the transpose of a linear system. Usually
    527:    accessed through KSPSolveTranspose().

    529:    Collective on KSP

    531:    Input Parameter:
    532: +  ksp - iterative context obtained from KSPCreate()
    533: .  b - right hand side vector
    534: -  x - solution vector

    536:    Note:
    537:    Currently only supported by KSPType of KSPPREONLY. This routine is usally
    538:    only used internally by the BiCG solver on the subblocks in BJacobi and ASM.

    540:    Level: developer

    542: .keywords: KSP, solve, linear system

    544: .seealso: KSPCreate(), KSPSetUp(), KSPDestroy(), KSPSetTolerances(), KSPDefaultConverged(),
    545:           KSPSolve()
    546: @*/
    547: PetscErrorCode PETSCKSP_DLLEXPORT KSPSolveTranspose(KSP ksp,Vec b,Vec x)
    548: {
    550:   PetscScalar    zero = 0.0;

    557:   ksp->vec_rhs = b;
    558:   ksp->vec_sol = x;
    559:   KSPSetUp(ksp);
    560:   if (ksp->guess_zero) { VecSet(ksp->vec_sol,zero);}
    561:   ksp->transpose_solve = PETSC_TRUE;
    562:   (*ksp->ops->solve)(ksp);
    563:   return(0);
    564: }

    568: /*@C
    569:    KSPDestroy - Destroys KSP context.

    571:    Collective on KSP

    573:    Input Parameter:
    574: .  ksp - iterative context obtained from KSPCreate()

    576:    Level: beginner

    578: .keywords: KSP, destroy

    580: .seealso: KSPCreate(), KSPSetUp(), KSPSolve()
    581: @*/
    582: PetscErrorCode PETSCKSP_DLLEXPORT KSPDestroy(KSP ksp)
    583: {

    588:   if (--ksp->refct > 0) return(0);

    590:   /* if memory was published with AMS then destroy it */
    591:   PetscObjectDepublish(ksp);

    593:   if (ksp->ops->destroy) {
    594:     (*ksp->ops->destroy)(ksp);
    595:   }
    596:   KSPClearMonitor(ksp);
    597:   PCDestroy(ksp->pc);
    598:   if (ksp->diagonal) {VecDestroy(ksp->diagonal);}
    599:   if (ksp->truediagonal) {VecDestroy(ksp->truediagonal);}
    600:   if (ksp->nullsp) {MatNullSpaceDestroy(ksp->nullsp);}
    601:   PetscHeaderDestroy(ksp);
    602:   return(0);
    603: }

    607: /*@
    608:     KSPSetPreconditionerSide - Sets the preconditioning side.

    610:     Collective on KSP

    612:     Input Parameter:
    613: .   ksp - iterative context obtained from KSPCreate()

    615:     Output Parameter:
    616: .   side - the preconditioning side, where side is one of
    617: .vb
    618:       PC_LEFT - left preconditioning (default)
    619:       PC_RIGHT - right preconditioning
    620:       PC_SYMMETRIC - symmetric preconditioning
    621: .ve

    623:     Options Database Keys:
    624: +   -ksp_left_pc - Sets left preconditioning
    625: .   -ksp_right_pc - Sets right preconditioning
    626: -   -ksp_symmetric_pc - Sets symmetric preconditioning

    628:     Notes:
    629:     Left preconditioning is used by default.  Symmetric preconditioning is
    630:     currently available only for the KSPQCG method. Note, however, that
    631:     symmetric preconditioning can be emulated by using either right or left
    632:     preconditioning and a pre or post processing step.

    634:     Level: intermediate

    636: .keywords: KSP, set, right, left, symmetric, side, preconditioner, flag

    638: .seealso: KSPGetPreconditionerSide()
    639: @*/
    640: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPreconditionerSide(KSP ksp,PCSide side)
    641: {
    644:   ksp->pc_side = side;
    645:   return(0);
    646: }

    650: /*@C
    651:     KSPGetPreconditionerSide - Gets the preconditioning side.

    653:     Not Collective

    655:     Input Parameter:
    656: .   ksp - iterative context obtained from KSPCreate()

    658:     Output Parameter:
    659: .   side - the preconditioning side, where side is one of
    660: .vb
    661:       PC_LEFT - left preconditioning (default)
    662:       PC_RIGHT - right preconditioning
    663:       PC_SYMMETRIC - symmetric preconditioning
    664: .ve

    666:     Level: intermediate

    668: .keywords: KSP, get, right, left, symmetric, side, preconditioner, flag

    670: .seealso: KSPSetPreconditionerSide()
    671: @*/
    672: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetPreconditionerSide(KSP ksp,PCSide *side)
    673: {
    677:   *side = ksp->pc_side;
    678:   return(0);
    679: }

    683: /*@
    684:    KSPGetTolerances - Gets the relative, absolute, divergence, and maximum
    685:    iteration tolerances used by the default KSP convergence tests.

    687:    Not Collective

    689:    Input Parameter:
    690: .  ksp - the Krylov subspace context
    691:
    692:    Output Parameters:
    693: +  rtol - the relative convergence tolerance
    694: .  abstol - the absolute convergence tolerance
    695: .  dtol - the divergence tolerance
    696: -  maxits - maximum number of iterations

    698:    Notes:
    699:    The user can specify PETSC_NULL for any parameter that is not needed.

    701:    Level: intermediate

    703: .keywords: KSP, get, tolerance, absolute, relative, divergence, convergence,
    704:            maximum, iterations

    706: .seealso: KSPSetTolerances()
    707: @*/
    708: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetTolerances(KSP ksp,PetscReal *rtol,PetscReal *abstol,PetscReal *dtol,PetscInt *maxits)
    709: {
    712:   if (abstol)   *abstol   = ksp->abstol;
    713:   if (rtol)   *rtol   = ksp->rtol;
    714:   if (dtol)   *dtol   = ksp->divtol;
    715:   if (maxits) *maxits = ksp->max_it;
    716:   return(0);
    717: }

    721: /*@
    722:    KSPSetTolerances - Sets the relative, absolute, divergence, and maximum
    723:    iteration tolerances used by the default KSP convergence testers.

    725:    Collective on KSP

    727:    Input Parameters:
    728: +  ksp - the Krylov subspace context
    729: .  rtol - the relative convergence tolerance
    730:    (relative decrease in the residual norm)
    731: .  abstol - the absolute convergence tolerance
    732:    (absolute size of the residual norm)
    733: .  dtol - the divergence tolerance
    734:    (amount residual can increase before KSPDefaultConverged()
    735:    concludes that the method is diverging)
    736: -  maxits - maximum number of iterations to use

    738:    Options Database Keys:
    739: +  -ksp_atol <abstol> - Sets abstol
    740: .  -ksp_rtol <rtol> - Sets rtol
    741: .  -ksp_divtol <dtol> - Sets dtol
    742: -  -ksp_max_it <maxits> - Sets maxits

    744:    Notes:
    745:    Use PETSC_DEFAULT to retain the default value of any of the tolerances.

    747:    See KSPDefaultConverged() for details on the use of these parameters
    748:    in the default convergence test.  See also KSPSetConvergenceTest()
    749:    for setting user-defined stopping criteria.

    751:    Level: intermediate

    753: .keywords: KSP, set, tolerance, absolute, relative, divergence,
    754:            convergence, maximum, iterations

    756: .seealso: KSPGetTolerances(), KSPDefaultConverged(), KSPSetConvergenceTest()
    757: @*/
    758: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetTolerances(KSP ksp,PetscReal rtol,PetscReal abstol,PetscReal dtol,PetscInt maxits)
    759: {
    762:   if (abstol != PETSC_DEFAULT)   ksp->abstol   = abstol;
    763:   if (rtol != PETSC_DEFAULT)   ksp->rtol   = rtol;
    764:   if (dtol != PETSC_DEFAULT)   ksp->divtol = dtol;
    765:   if (maxits != PETSC_DEFAULT) ksp->max_it = maxits;
    766:   return(0);
    767: }

    771: /*@
    772:    KSPSetInitialGuessNonzero - Tells the iterative solver that the
    773:    initial guess is nonzero; otherwise KSP assumes the initial guess
    774:    is to be zero (and thus zeros it out before solving).

    776:    Collective on KSP

    778:    Input Parameters:
    779: +  ksp - iterative context obtained from KSPCreate()
    780: -  flg - PETSC_TRUE indicates the guess is non-zero, PETSC_FALSE indicates the guess is zero

    782:    Level: beginner

    784:    Notes:
    785:     If this is not called the X vector is zeroed in the call to KSPSolve().

    787: .keywords: KSP, set, initial guess, nonzero

    789: .seealso: KSPGetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
    790: @*/
    791: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessNonzero(KSP ksp,PetscTruth flg)
    792: {
    794:   ksp->guess_zero   = (PetscTruth)!(int)flg;
    795:   return(0);
    796: }

    800: /*@
    801:    KSPGetInitialGuessNonzero - Determines whether the KSP solver is using
    802:    a zero initial guess.

    804:    Not Collective

    806:    Input Parameter:
    807: .  ksp - iterative context obtained from KSPCreate()

    809:    Output Parameter:
    810: .  flag - PETSC_TRUE if guess is nonzero, else PETSC_FALSE

    812:    Level: intermediate

    814: .keywords: KSP, set, initial guess, nonzero

    816: .seealso: KSPSetInitialGuessNonzero(), KSPSetInitialGuessKnoll(), KSPGetInitialGuessKnoll()
    817: @*/
    818: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessNonzero(KSP ksp,PetscTruth *flag)
    819: {
    821:   if (ksp->guess_zero) *flag = PETSC_FALSE;
    822:   else                 *flag = PETSC_TRUE;
    823:   return(0);
    824: }

    828: /*@
    829:    KSPSetInitialGuessKnoll - Tells the iterative solver to use PCApply(pc,b,..) to compute the initial guess (The Knoll trick)

    831:    Collective on KSP

    833:    Input Parameters:
    834: +  ksp - iterative context obtained from KSPCreate()
    835: -  flg - PETSC_TRUE or PETSC_FALSE

    837:    Level: advanced

    840: .keywords: KSP, set, initial guess, nonzero

    842: .seealso: KSPGetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
    843: @*/
    844: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetInitialGuessKnoll(KSP ksp,PetscTruth flg)
    845: {
    847:   ksp->guess_knoll   = flg;
    848:   return(0);
    849: }

    853: /*@
    854:    KSPGetInitialGuessKnoll - Determines whether the KSP solver is using the Knoll trick (using PCApply(pc,b,...) to compute
    855:      the initial guess

    857:    Not Collective

    859:    Input Parameter:
    860: .  ksp - iterative context obtained from KSPCreate()

    862:    Output Parameter:
    863: .  flag - PETSC_TRUE if using Knoll trick, else PETSC_FALSE

    865:    Level: advanced

    867: .keywords: KSP, set, initial guess, nonzero

    869: .seealso: KSPSetInitialGuessKnoll(), KSPSetInitialGuessNonzero(), KSPGetInitialGuessNonzero()
    870: @*/
    871: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetInitialGuessKnoll(KSP ksp,PetscTruth *flag)
    872: {
    874:   *flag = ksp->guess_knoll;
    875:   return(0);
    876: }

    880: /*@
    881:    KSPGetComputeSingularValues - Gets the flag indicating whether the extreme singular
    882:    values will be calculated via a Lanczos or Arnoldi process as the linear
    883:    system is solved.

    885:    Collective on KSP

    887:    Input Parameter:
    888: .  ksp - iterative context obtained from KSPCreate()

    890:    Output Parameter:
    891: .  flg - PETSC_TRUE or PETSC_FALSE

    893:    Options Database Key:
    894: .  -ksp_singmonitor - Activates KSPSetComputeSingularValues()

    896:    Notes:
    897:    Currently this option is not valid for all iterative methods.

    899:    Many users may just want to use the monitoring routine
    900:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
    901:    to print the singular values at each iteration of the linear solve.

    903:    Level: advanced

    905: .keywords: KSP, set, compute, singular values

    907: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
    908: @*/
    909: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeSingularValues(KSP ksp,PetscTruth *flg)
    910: {
    914:   *flg = ksp->calc_sings;
    915:   return(0);
    916: }

    920: /*@
    921:    KSPSetComputeSingularValues - Sets a flag so that the extreme singular
    922:    values will be calculated via a Lanczos or Arnoldi process as the linear
    923:    system is solved.

    925:    Collective on KSP

    927:    Input Parameters:
    928: +  ksp - iterative context obtained from KSPCreate()
    929: -  flg - PETSC_TRUE or PETSC_FALSE

    931:    Options Database Key:
    932: .  -ksp_singmonitor - Activates KSPSetComputeSingularValues()

    934:    Notes:
    935:    Currently this option is not valid for all iterative methods.

    937:    Many users may just want to use the monitoring routine
    938:    KSPSingularValueMonitor() (which can be set with option -ksp_singmonitor)
    939:    to print the singular values at each iteration of the linear solve.

    941:    Level: advanced

    943: .keywords: KSP, set, compute, singular values

    945: .seealso: KSPComputeExtremeSingularValues(), KSPSingularValueMonitor()
    946: @*/
    947: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeSingularValues(KSP ksp,PetscTruth flg)
    948: {
    951:   ksp->calc_sings  = flg;
    952:   return(0);
    953: }

    957: /*@
    958:    KSPGetComputeEigenvalues - Gets the flag indicating that the extreme eigenvalues
    959:    values will be calculated via a Lanczos or Arnoldi process as the linear
    960:    system is solved.

    962:    Collective on KSP

    964:    Input Parameter:
    965: .  ksp - iterative context obtained from KSPCreate()

    967:    Output Parameter:
    968: .  flg - PETSC_TRUE or PETSC_FALSE

    970:    Notes:
    971:    Currently this option is not valid for all iterative methods.

    973:    Level: advanced

    975: .keywords: KSP, set, compute, eigenvalues

    977: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
    978: @*/
    979: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetComputeEigenvalues(KSP ksp,PetscTruth *flg)
    980: {
    984:   *flg = ksp->calc_sings;
    985:   return(0);
    986: }

    990: /*@
    991:    KSPSetComputeEigenvalues - Sets a flag so that the extreme eigenvalues
    992:    values will be calculated via a Lanczos or Arnoldi process as the linear
    993:    system is solved.

    995:    Collective on KSP

    997:    Input Parameters:
    998: +  ksp - iterative context obtained from KSPCreate()
    999: -  flg - PETSC_TRUE or PETSC_FALSE

    1001:    Notes:
    1002:    Currently this option is not valid for all iterative methods.

    1004:    Level: advanced

    1006: .keywords: KSP, set, compute, eigenvalues

    1008: .seealso: KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly()
    1009: @*/
    1010: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetComputeEigenvalues(KSP ksp,PetscTruth flg)
    1011: {
    1014:   ksp->calc_sings  = flg;
    1015:   return(0);
    1016: }

    1020: /*@C
    1021:    KSPGetRhs - Gets the right-hand-side vector for the linear system to
    1022:    be solved.

    1024:    Not Collective

    1026:    Input Parameter:
    1027: .  ksp - iterative context obtained from KSPCreate()

    1029:    Output Parameter:
    1030: .  r - right-hand-side vector

    1032:    Level: developer

    1034: .keywords: KSP, get, right-hand-side, rhs

    1036: .seealso: KSPGetSolution(), KSPSolve()
    1037: @*/
    1038: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetRhs(KSP ksp,Vec *r)
    1039: {
    1042:   *r = ksp->vec_rhs;
    1043:   return(0);
    1044: }

    1048: /*@C
    1049:    KSPGetSolution - Gets the location of the solution for the
    1050:    linear system to be solved.  Note that this may not be where the solution
    1051:    is stored during the iterative process; see KSPBuildSolution().

    1053:    Not Collective

    1055:    Input Parameters:
    1056: .  ksp - iterative context obtained from KSPCreate()

    1058:    Output Parameters:
    1059: .  v - solution vector

    1061:    Level: developer

    1063: .keywords: KSP, get, solution

    1065: .seealso: KSPGetRhs(),  KSPBuildSolution(), KSPSolve()
    1066: @*/
    1067: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetSolution(KSP ksp,Vec *v)
    1068: {
    1072:   *v = ksp->vec_sol;
    1073:   return(0);
    1074: }

    1078: /*@
    1079:    KSPSetPC - Sets the preconditioner to be used to calculate the
    1080:    application of the preconditioner on a vector.

    1082:    Collective on KSP

    1084:    Input Parameters:
    1085: +  ksp - iterative context obtained from KSPCreate()
    1086: -  pc   - the preconditioner object

    1088:    Notes:
    1089:    Use KSPGetPC() to retrieve the preconditioner context (for example,
    1090:    to free it at the end of the computations).

    1092:    Level: developer

    1094: .keywords: KSP, set, precondition, Binv

    1096: .seealso: KSPGetPC()
    1097: @*/
    1098: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetPC(KSP ksp,PC pc)
    1099: {

    1106:   if (ksp->pc) {PCDestroy(ksp->pc);}
    1107:   ksp->pc = pc;
    1108:   PetscObjectReference((PetscObject)ksp->pc);
    1109:   return(0);
    1110: }

    1114: /*@C
    1115:    KSPGetPC - Returns a pointer to the preconditioner context
    1116:    set with KSPSetPC().

    1118:    Not Collective

    1120:    Input Parameters:
    1121: .  ksp - iterative context obtained from KSPCreate()

    1123:    Output Parameter:
    1124: .  pc - preconditioner context

    1126:    Level: developer

    1128: .keywords: KSP, get, preconditioner, Binv

    1130: .seealso: KSPSetPC()
    1131: @*/
    1132: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetPC(KSP ksp,PC *pc)
    1133: {
    1137:   *pc = ksp->pc;
    1138:   return(0);
    1139: }

    1143: /*@C
    1144:    KSPSetMonitor - Sets an ADDITIONAL function to be called at every iteration to monitor
    1145:    the residual/error etc.
    1146:
    1147:    Collective on KSP

    1149:    Input Parameters:
    1150: +  ksp - iterative context obtained from KSPCreate()
    1151: .  monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
    1152: .  mctx    - [optional] context for private data for the
    1153:              monitor routine (use PETSC_NULL if no context is desired)
    1154: -  monitordestroy - [optional] routine that frees monitor context
    1155:           (may be PETSC_NULL)

    1157:    Calling Sequence of monitor:
    1158: $     monitor (KSP ksp, int it, PetscReal rnorm, void *mctx)

    1160: +  ksp - iterative context obtained from KSPCreate()
    1161: .  it - iteration number
    1162: .  rnorm - (estimated) 2-norm of (preconditioned) residual
    1163: -  mctx  - optional monitoring context, as set by KSPSetMonitor()

    1165:    Options Database Keys:
    1166: +    -ksp_monitor        - sets KSPDefaultMonitor()
    1167: .    -ksp_truemonitor    - sets KSPTrueMonitor()
    1168: .    -ksp_xmonitor       - sets line graph monitor,
    1169:                            uses KSPLGMonitorCreate()
    1170: .    -ksp_xtruemonitor   - sets line graph monitor,
    1171:                            uses KSPLGMonitorCreate()
    1172: .    -ksp_singmonitor    - sets KSPSingularValueMonitor()
    1173: -    -ksp_cancelmonitors - cancels all monitors that have
    1174:                           been hardwired into a code by
    1175:                           calls to KSPSetMonitor(), but
    1176:                           does not cancel those set via
    1177:                           the options database.

    1179:    Notes:
    1180:    The default is to do nothing.  To print the residual, or preconditioned
    1181:    residual if KSPSetNormType(ksp,KSP_PRECONDITIONED_NORM) was called, use
    1182:    KSPDefaultMonitor() as the monitoring routine, with a null monitoring
    1183:    context.

    1185:    Several different monitoring routines may be set by calling
    1186:    KSPSetMonitor() multiple times; all will be called in the
    1187:    order in which they were set.

    1189:    Level: beginner

    1191: .keywords: KSP, set, monitor

    1193: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPClearMonitor()
    1194: @*/
    1195: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetMonitor(KSP ksp,PetscErrorCode (*monitor)(KSP,PetscInt,PetscReal,void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
    1196: {
    1199:   if (ksp->numbermonitors >= MAXKSPMONITORS) {
    1200:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many KSP monitors set");
    1201:   }
    1202:   ksp->monitor[ksp->numbermonitors]           = monitor;
    1203:   ksp->monitordestroy[ksp->numbermonitors]    = monitordestroy;
    1204:   ksp->monitorcontext[ksp->numbermonitors++]  = (void*)mctx;
    1205:   return(0);
    1206: }

    1210: /*@
    1211:    KSPClearMonitor - Clears all monitors for a KSP object.

    1213:    Collective on KSP

    1215:    Input Parameters:
    1216: .  ksp - iterative context obtained from KSPCreate()

    1218:    Options Database Key:
    1219: .  -ksp_cancelmonitors - Cancels all monitors that have
    1220:     been hardwired into a code by calls to KSPSetMonitor(),
    1221:     but does not cancel those set via the options database.

    1223:    Level: intermediate

    1225: .keywords: KSP, set, monitor

    1227: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate(), KSPSetMonitor()
    1228: @*/
    1229: PetscErrorCode PETSCKSP_DLLEXPORT KSPClearMonitor(KSP ksp)
    1230: {
    1232:   PetscInt       i;

    1236:   for (i=0; i<ksp->numbermonitors; i++) {
    1237:     if (ksp->monitordestroy[i]) {
    1238:       (*ksp->monitordestroy[i])(ksp->monitorcontext[i]);
    1239:     }
    1240:   }
    1241:   ksp->numbermonitors = 0;
    1242:   return(0);
    1243: }

    1247: /*@C
    1248:    KSPGetMonitorContext - Gets the monitoring context, as set by
    1249:    KSPSetMonitor() for the FIRST monitor only.

    1251:    Not Collective

    1253:    Input Parameter:
    1254: .  ksp - iterative context obtained from KSPCreate()

    1256:    Output Parameter:
    1257: .  ctx - monitoring context

    1259:    Level: intermediate

    1261: .keywords: KSP, get, monitor, context

    1263: .seealso: KSPDefaultMonitor(), KSPLGMonitorCreate()
    1264: @*/
    1265: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetMonitorContext(KSP ksp,void **ctx)
    1266: {
    1269:   *ctx =      (ksp->monitorcontext[0]);
    1270:   return(0);
    1271: }

    1275: /*@
    1276:    KSPSetResidualHistory - Sets the array used to hold the residual history.
    1277:    If set, this array will contain the residual norms computed at each
    1278:    iteration of the solver.

    1280:    Not Collective

    1282:    Input Parameters:
    1283: +  ksp - iterative context obtained from KSPCreate()
    1284: .  a   - array to hold history
    1285: .  na  - size of a
    1286: -  reset - PETSC_TRUE indicates the history counter is reset to zero
    1287:            for each new linear solve

    1289:    Level: advanced

    1291:    Notes: The array is NOT freed by PETSc so the user needs to keep track of
    1292:            it and destroy once the KSP object is destroyed.

    1294:    If 'na' is PETSC_DECIDE or 'a' is PETSC_NULL, then a default array of
    1295:    length 1000 is allocated.

    1297: .keywords: KSP, set, residual, history, norm

    1299: .seealso: KSPGetResidualHistory()

    1301: @*/
    1302: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetResidualHistory(KSP ksp,PetscReal a[],PetscInt na,PetscTruth reset)
    1303: {

    1308:   if (na != PETSC_DECIDE && a) {
    1309:     ksp->res_hist        = a;
    1310:     ksp->res_hist_max    = na;
    1311:   } else {
    1312:     ksp->res_hist_max    = 1000;
    1313:     PetscMalloc(ksp->res_hist_max*sizeof(PetscReal),&ksp->res_hist);
    1314:   }
    1315:   ksp->res_hist_len    = 0;
    1316:   ksp->res_hist_reset  = reset;

    1319:   return(0);
    1320: }

    1324: /*@C
    1325:    KSPGetResidualHistory - Gets the array used to hold the residual history
    1326:    and the number of residuals it contains.

    1328:    Not Collective

    1330:    Input Parameter:
    1331: .  ksp - iterative context obtained from KSPCreate()

    1333:    Output Parameters:
    1334: +  a   - pointer to array to hold history (or PETSC_NULL)
    1335: -  na  - number of used entries in a (or PETSC_NULL)

    1337:    Level: advanced

    1339:    Notes:
    1340:      Can only be called after a KSPSetResidualHistory() otherwise a and na are set to zero

    1342:      The Fortran version of this routine has a calling sequence
    1343: $   call KSPGetResidualHistory(KSP ksp, integer na, integer ierr)

    1345: .keywords: KSP, get, residual, history, norm

    1347: .seealso: KSPGetResidualHistory()

    1349: @*/
    1350: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetResidualHistory(KSP ksp,PetscReal *a[],PetscInt *na)
    1351: {
    1354:   if (a)  *a = ksp->res_hist;
    1355:   if (na) *na = ksp->res_hist_len;
    1356:   return(0);
    1357: }

    1361: /*@C
    1362:    KSPSetConvergenceTest - Sets the function to be used to determine
    1363:    convergence.

    1365:    Collective on KSP

    1367:    Input Parameters:
    1368: +  ksp - iterative context obtained from KSPCreate()
    1369: .  converge - pointer to int function
    1370: -  cctx    - context for private data for the convergence routine (may be null)

    1372:    Calling sequence of converge:
    1373: $     converge (KSP ksp, int it, PetscReal rnorm, KSPConvergedReason *reason,void *mctx)

    1375: +  ksp - iterative context obtained from KSPCreate()
    1376: .  it - iteration number
    1377: .  rnorm - (estimated) 2-norm of (preconditioned) residual
    1378: .  reason - the reason why it has converged or diverged
    1379: -  cctx  - optional convergence context, as set by KSPSetConvergenceTest()

    1382:    Notes:
    1383:    Must be called after the KSP type has been set so put this after
    1384:    a call to KSPSetType(), or KSPSetFromOptions().

    1386:    The default convergence test, KSPDefaultConverged(), aborts if the
    1387:    residual grows to more than 10000 times the initial residual.

    1389:    The default is a combination of relative and absolute tolerances.
    1390:    The residual value that is tested may be an approximation; routines
    1391:    that need exact values should compute them.

    1393:    In the default PETSc convergence test, the precise values of reason
    1394:    are macros such as KSP_CONVERGED_RTOL, which are defined in petscksp.h.

    1396:    Level: advanced

    1398: .keywords: KSP, set, convergence, test, context

    1400: .seealso: KSPDefaultConverged(), KSPGetConvergenceContext()
    1401: @*/
    1402: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetConvergenceTest(KSP ksp,PetscErrorCode (*converge)(KSP,PetscInt,PetscReal,KSPConvergedReason*,void*),void *cctx)
    1403: {
    1406:   ksp->converged = converge;
    1407:   ksp->cnvP      = (void*)cctx;
    1408:   return(0);
    1409: }

    1413: /*@C
    1414:    KSPGetConvergenceContext - Gets the convergence context set with
    1415:    KSPSetConvergenceTest().

    1417:    Not Collective

    1419:    Input Parameter:
    1420: .  ksp - iterative context obtained from KSPCreate()

    1422:    Output Parameter:
    1423: .  ctx - monitoring context

    1425:    Level: advanced

    1427: .keywords: KSP, get, convergence, test, context

    1429: .seealso: KSPDefaultConverged(), KSPSetConvergenceTest()
    1430: @*/
    1431: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetConvergenceContext(KSP ksp,void **ctx)
    1432: {
    1435:   *ctx = ksp->cnvP;
    1436:   return(0);
    1437: }

    1441: /*@C
    1442:    KSPBuildSolution - Builds the approximate solution in a vector provided.
    1443:    This routine is NOT commonly needed (see KSPSolve()).

    1445:    Collective on KSP

    1447:    Input Parameter:
    1448: .  ctx - iterative context obtained from KSPCreate()

    1450:    Output Parameter:
    1451:    Provide exactly one of
    1452: +  v - location to stash solution.
    1453: -  V - the solution is returned in this location. This vector is created
    1454:        internally. This vector should NOT be destroyed by the user with
    1455:        VecDestroy().

    1457:    Notes:
    1458:    This routine can be used in one of two ways
    1459: .vb
    1460:       KSPBuildSolution(ksp,PETSC_NULL,&V);
    1461:    or
    1462:       KSPBuildSolution(ksp,v,PETSC_NULL);
    1463: .ve
    1464:    In the first case an internal vector is allocated to store the solution
    1465:    (the user cannot destroy this vector). In the second case the solution
    1466:    is generated in the vector that the user provides. Note that for certain
    1467:    methods, such as KSPCG, the second case requires a copy of the solution,
    1468:    while in the first case the call is essentially free since it simply
    1469:    returns the vector where the solution already is stored.

    1471:    Level: advanced

    1473: .keywords: KSP, build, solution

    1475: .seealso: KSPGetSolution(), KSPBuildResidual()
    1476: @*/
    1477: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildSolution(KSP ksp,Vec v,Vec *V)
    1478: {

    1483:   if (!V && !v) SETERRQ(PETSC_ERR_ARG_WRONG,"Must provide either v or V");
    1484:   if (!V) V = &v;
    1485:   (*ksp->ops->buildsolution)(ksp,v,V);
    1486:   return(0);
    1487: }

    1491: /*@C
    1492:    KSPBuildResidual - Builds the residual in a vector provided.

    1494:    Collective on KSP

    1496:    Input Parameter:
    1497: .  ksp - iterative context obtained from KSPCreate()

    1499:    Output Parameters:
    1500: +  v - optional location to stash residual.  If v is not provided,
    1501:        then a location is generated.
    1502: .  t - work vector.  If not provided then one is generated.
    1503: -  V - the residual

    1505:    Notes:
    1506:    Regardless of whether or not v is provided, the residual is
    1507:    returned in V.

    1509:    Level: advanced

    1511: .keywords: KSP, build, residual

    1513: .seealso: KSPBuildSolution()
    1514: @*/
    1515: PetscErrorCode PETSCKSP_DLLEXPORT KSPBuildResidual(KSP ksp,Vec t,Vec v,Vec *V)
    1516: {
    1518:   PetscTruth     flag = PETSC_FALSE;
    1519:   Vec            w = v,tt = t;

    1523:   if (!w) {
    1524:     VecDuplicate(ksp->vec_rhs,&w);
    1525:     PetscLogObjectParent((PetscObject)ksp,w);
    1526:   }
    1527:   if (!tt) {
    1528:     VecDuplicate(ksp->vec_rhs,&tt); flag = PETSC_TRUE;
    1529:     PetscLogObjectParent((PetscObject)ksp,tt);
    1530:   }
    1531:   (*ksp->ops->buildresidual)(ksp,tt,w,V);
    1532:   if (flag) {VecDestroy(tt);}
    1533:   return(0);
    1534: }

    1538: /*@
    1539:    KSPSetDiagonalScale - Tells KSP to symmetrically diagonally scale the system
    1540:      before solving. This actually CHANGES the matrix (and right hand side).

    1542:    Collective on KSP

    1544:    Input Parameter:
    1545: +  ksp - the KSP context
    1546: -  scale - PETSC_TRUE or PETSC_FALSE

    1548:    Options Database Key:
    1549: +   -ksp_diagonal_scale -
    1550: -   -ksp_diagonal_scale_fix - scale the matrix back AFTER the solve

    1553:     BE CAREFUL with this routine: it actually scales the matrix and right
    1554:     hand side that define the system. After the system is solved the matrix
    1555:     and right hand side remain scaled.

    1557:     This routine is only used if the matrix and preconditioner matrix are
    1558:     the same thing.
    1559:
    1560:     If you use this with the PCType Eisenstat preconditioner than you can
    1561:     use the PCEisenstatNoDiagonalScaling() option, or -pc_eisenstat_no_diagonal_scaling
    1562:     to save some unneeded, redundant flops.

    1564:    Level: intermediate

    1566: .keywords: KSP, set, options, prefix, database

    1568: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScaleFix()
    1569: @*/
    1570: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScale(KSP ksp,PetscTruth scale)
    1571: {
    1574:   ksp->dscale = scale;
    1575:   return(0);
    1576: }

    1580: /*@C
    1581:    KSPGetDiagonalScale - Checks if KSP solver scales the matrix and
    1582:                           right hand side

    1584:    Not Collective

    1586:    Input Parameter:
    1587: .  ksp - the KSP context

    1589:    Output Parameter:
    1590: .  scale - PETSC_TRUE or PETSC_FALSE

    1592:    Notes:
    1593:     BE CAREFUL with this routine: it actually scales the matrix and right
    1594:     hand side that define the system. After the system is solved the matrix
    1595:     and right hand side remain scaled.

    1597:     This routine is only used if the matrix and preconditioner matrix are
    1598:     the same thing.

    1600:    Level: intermediate

    1602: .keywords: KSP, set, options, prefix, database

    1604: .seealso: KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
    1605: @*/
    1606: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScale(KSP ksp,PetscTruth *scale)
    1607: {
    1611:   *scale = ksp->dscale;
    1612:   return(0);
    1613: }

    1617: /*@
    1618:    KSPSetDiagonalScaleFix - Tells KSP to diagonally scale the system
    1619:      back after solving.

    1621:    Collective on KSP

    1623:    Input Parameter:
    1624: +  ksp - the KSP context
    1625: -  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
    1626:          rescale (default)

    1628:    Notes:
    1629:      Must be called after KSPSetDiagonalScale()

    1631:      Using this will slow things down, because it rescales the matrix before and
    1632:      after each linear solve. This is intended mainly for testing to allow one
    1633:      to easily get back the original system to make sure the solution computed is
    1634:      accurate enough.

    1636:     This routine is only used if the matrix and preconditioner matrix are
    1637:     the same thing.

    1639:    Level: intermediate

    1641: .keywords: KSP, set, options, prefix, database

    1643: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPGetDiagonalScaleFix()
    1644: @*/
    1645: PetscErrorCode PETSCKSP_DLLEXPORT KSPSetDiagonalScaleFix(KSP ksp,PetscTruth fix)
    1646: {
    1649:   ksp->dscalefix = fix;
    1650:   return(0);
    1651: }

    1655: /*@
    1656:    KSPGetDiagonalScaleFix - Determines if KSP diagonally scales the system
    1657:      back after solving.

    1659:    Collective on KSP

    1661:    Input Parameter:
    1662: .  ksp - the KSP context

    1664:    Output Parameter:
    1665: .  fix - PETSC_TRUE to scale back after the system solve, PETSC_FALSE to not
    1666:          rescale (default)

    1668:    Notes:
    1669:      Must be called after KSPSetDiagonalScale()

    1671:      If PETSC_TRUE will slow things down, because it rescales the matrix before and
    1672:      after each linear solve. This is intended mainly for testing to allow one
    1673:      to easily get back the original system to make sure the solution computed is
    1674:      accurate enough.

    1676:     This routine is only used if the matrix and preconditioner matrix are
    1677:     the same thing.

    1679:    Level: intermediate

    1681: .keywords: KSP, set, options, prefix, database

    1683: .seealso: KSPGetDiagonalScale(), KSPSetDiagonalScale(), KSPSetDiagonalScaleFix()
    1684: @*/
    1685: PetscErrorCode PETSCKSP_DLLEXPORT KSPGetDiagonalScaleFix(KSP ksp,PetscTruth *fix)
    1686: {
    1690:   *fix = ksp->dscalefix;
    1691:   return(0);
    1692: }