File: ksp.html

package info (click to toggle)
petsc 3.23.1%2Bdfsg1-1exp1
links: PTS, VCS
area: main
in suites: experimental
size: 515,576 kB
sloc: ansic: 751,607; cpp: 51,542; python: 38,598; f90: 17,352; javascript: 3,493; makefile: 3,157; sh: 1,502; xml: 619; objc: 445; java: 13; csh: 1
file content (3487 lines) | stat: -rw-r--r-- 340,010 bytes

<!DOCTYPE html>


<html lang="en" data-content_root="../" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>KSP: Linear System Solvers &#8212; PETSc 3.23.1 documentation</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
  </script>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="../_static/styles/theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />

  
  <link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
  <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=8f2a1f02" />
    <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
    <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=87e54e7c" />
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css" />
    <link rel="stylesheet" type="text/css" href="../_static/katex-math.css?v=91adb8b6" />
    <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=dbe1606d" />
  
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509" />
  <script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=bd9e20870c6007c4c509"></script>

    <script src="../_static/documentation_options.js?v=34da53a5"></script>
    <script src="../_static/doctools.js?v=9a2dae69"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/clipboard.min.js?v=a7894cd8"></script>
    <script src="../_static/copybutton.js?v=a56c686a"></script>
    <script src="../_static/design-tabs.js?v=f930bc37"></script>
    <script src="../_static/katex.min.js?v=be8ff15f"></script>
    <script src="../_static/auto-render.min.js?v=ad136472"></script>
    <script src="../_static/katex_autorenderer.js?v=bebc588a"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'manual/ksp';</script>
    <link rel="icon" href="../_static/petsc_favicon.png"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="SNES: Nonlinear Solvers" href="snes.html" />
    <link rel="prev" title="Matrices" href="mat.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
    <meta name="docbuild:last-update" content="2025-04-30T13:10:40-0500 (v3.23.1)"/>
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
  
  <div id="pst-scroll-pixel-helper"></div>

  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>
    Back to top
  </button>

  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__primary"
          id="__primary"/>
  <label class="overlay overlay-primary" for="__primary"></label>
  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__secondary"
          id="__secondary"/>
  <label class="overlay overlay-secondary" for="__secondary"></label>
  
  <div class="search-button__wrapper">
    <div class="search-button__overlay"></div>
    <div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
      action="../search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         id="search-input"
         placeholder="Search the docs ..."
         aria-label="Search the docs ..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
  </div>

  <header>
  
    <div class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
  <label class="sidebar-toggle primary-toggle" for="__primary">
    <span class="fa-solid fa-bars"></span>
  </label>
  
  
  <div class="col-lg-3 navbar-header-items__start">
    
      <div class="navbar-item">

  

<a class="navbar-brand logo" href="../index.html">
  
  
  
  
  
    
    
      
    
    
    <img src="../_static/PETSc-TAO_RGB.svg" class="logo__image only-light" alt="PETSc 3.23.1 documentation - Home"/>
    <script>document.write(`<img src="../_static/PETSc-TAO_RGB_white.svg" class="logo__image only-dark" alt="PETSc 3.23.1 documentation - Home"/>`);</script>
  
  
</a></div>
    
  </div>
  
  <div class="col-lg-9 navbar-header-items">
    
    <div class="me-auto navbar-header-items__center">
      
        <div class="navbar-item">
<nav class="navbar-nav">
  <ul class="bd-navbar-elements navbar-nav">
    
                    <li class="nav-item current active">
                      <a class="nav-link nav-internal" href="../overview/index.html">
                        Overview
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../install/index.html">
                        Install
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../tutorials/index.html">
                        Tutorials
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="index.html">
                        User-Guide
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manualpages/index.html">
                        C/Fortran API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../petsc4py/index.html">
                        petsc4py API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../faq/index.html">
                        FAQ
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../community/index.html">
                        Community
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../developers/index.html">
                        Developers
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../miscellaneous/index.html">
                        Misc.
                      </a>
                    </li>
                
  </ul>
</nav></div>
      
    </div>
    
    
    <div class="navbar-header-items__end">
      
        <div class="navbar-item navbar-persistent--container">
          

 <script>
 document.write(`
   <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass"></i>
    <span class="search-button__default-text">Search</span>
    <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
   </button>
 `);
 </script>
        </div>
      
      
        <div class="navbar-item">

<script>
document.write(`
  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
  </button>
`);
</script></div>
      
        <div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          
          
          
          
          
          
          <a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
            <span class="sr-only">GitLab</span></a>
        </li>
</ul></div>
      
    </div>
    
  </div>
  
  
    <div class="navbar-persistent--mobile">

 <script>
 document.write(`
   <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass"></i>
    <span class="search-button__default-text">Search</span>
    <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
   </button>
 `);
 </script>
    </div>
  

  
    <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
      <span class="fa-solid fa-outdent"></span>
    </label>
  
</div>

    </div>
  
  </header>

  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      
      
      <div class="bd-sidebar-primary bd-sidebar">
        

  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
      <div class="sidebar-header-items__center">
        
          <div class="navbar-item">
<nav class="navbar-nav">
  <ul class="bd-navbar-elements navbar-nav">
    
                    <li class="nav-item current active">
                      <a class="nav-link nav-internal" href="../overview/index.html">
                        Overview
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../install/index.html">
                        Install
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../tutorials/index.html">
                        Tutorials
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="index.html">
                        User-Guide
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../manualpages/index.html">
                        C/Fortran API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../petsc4py/index.html">
                        petsc4py API
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../faq/index.html">
                        FAQ
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../community/index.html">
                        Community
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../developers/index.html">
                        Developers
                      </a>
                    </li>
                

                    <li class="nav-item">
                      <a class="nav-link nav-internal" href="../miscellaneous/index.html">
                        Misc.
                      </a>
                    </li>
                
  </ul>
</nav></div>
        
      </div>
    
    
    
      <div class="sidebar-header-items__end">
        
          <div class="navbar-item">

<script>
document.write(`
  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
  </button>
`);
</script></div>
        
          <div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
    aria-label="Icon Links">
        <li class="nav-item">
          
          
          
          
          
          
          
          
          <a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
            <span class="sr-only">GitLab</span></a>
        </li>
</ul></div>
        
      </div>
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
     aria-label="Section Navigation">
  <p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
  <div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="../overview/nutshell.html">PETSc in a nutshell</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/features.html">Supported Systems</a></li>

<li class="toctree-l1"><a class="reference internal" href="../overview/gpu_roadmap.html">GPU Support Roadmap</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/vector_table.html">Summary of Vector Types Available In PETSc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/matrix_table.html">Summary of Matrix Types Available In PETSc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/linear_solve_table.html">Summary of Sparse Linear Solvers Available In PETSc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/nonlinear_solve_table.html">Summary of Nonlinear Solvers Available In PETSc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/integrator_table.html">Summary of Time Integrators Available In PETSc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/tao_solve_table.html">Summary of Tao Solvers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/discrete_table.html">Summary of Discretization Management Systems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/plex_transform_table.html">Summary of Unstructured Mesh Transformations</a></li>
<li class="toctree-l1 current active has-children"><a class="reference internal" href="index.html">User-Guide</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul class="current">
<li class="toctree-l2 has-children"><a class="reference internal" href="introduction.html">Introduction to PETSc</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="about_this_manual.html">About This Manual</a></li>
<li class="toctree-l3"><a class="reference internal" href="getting_started.html">Getting Started</a></li>






</ul>
</li>
<li class="toctree-l2 current active has-children"><a class="reference internal" href="programming.html">The Solvers in PETSc/TAO</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="vec.html">Vectors and Parallel Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="mat.html">Matrices</a></li>
<li class="toctree-l3 current active"><a class="current reference internal" href="#">KSP: Linear System Solvers</a></li>
<li class="toctree-l3"><a class="reference internal" href="snes.html">SNES: Nonlinear Solvers</a></li>
<li class="toctree-l3"><a class="reference internal" href="ts.html">TS: Scalable ODE and DAE Solvers</a></li>

<li class="toctree-l3"><a class="reference internal" href="tao.html">TAO: Optimization Solvers</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="dm.html">DM: Interfacing Between Solvers and Models/Discretizations</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="dmbase.html">DM Basics</a></li>
<li class="toctree-l3"><a class="reference internal" href="section.html">PetscSection: Connecting Grids to Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmplex.html">DMPlex: Unstructured Grids</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmstag.html">DMSTAG: Staggered, Structured Grid</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmnetwork.html">Networks</a></li>
<li class="toctree-l3"><a class="reference internal" href="dt.html">PetscDT: Discretization Technology in PETSc</a></li>
<li class="toctree-l3"><a class="reference internal" href="fe.html">PetscFE: Finite Element Infrastructure in PETSc</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="additional.html">Additional Information</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="fortran.html">PETSc for Fortran Users</a></li>
<li class="toctree-l3"><a class="reference internal" href="versionchecking.html">Checking the PETSc version</a></li>
<li class="toctree-l3"><a class="reference internal" href="matlab.html">Using MATLAB with PETSc</a></li>
<li class="toctree-l3"><a class="reference internal" href="profiling.html">Profiling</a></li>
<li class="toctree-l3"><a class="reference internal" href="performance.html">Hints for Performance Tuning</a></li>
<li class="toctree-l3"><a class="reference internal" href="streams.html">STREAMS: Example Study</a></li>
<li class="toctree-l3"><a class="reference internal" href="blas-lapack.html">The Use of BLAS and LAPACK in PETSc and external libraries</a></li>
<li class="toctree-l3"><a class="reference internal" href="other.html">Other PETSc Features</a></li>

<li class="toctree-l3"><a class="reference internal" href="advanced.html">Advanced Features of Matrices and Solvers</a></li>
<li class="toctree-l3"><a class="reference internal" href="tests.html">Running PETSc Tests</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../manualpages/index.html">C/Fortran API</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-6"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Vector.html">Vectors and Index Sets</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-7"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Vec/index.html">Vector Operations (Vec)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/IS/index.html">Index sets (IS)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Matrix.html">Matrices and Matrix Operations</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-8"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Mat/index.html">Matrix Operations (Mat)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/MatGraphOperations/index.html">Matrix colorings (MatColoring), orderings (MatOrdering), partitionings (MatPartitioning), and coarsening (MatCoarsen)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/MatFD/index.html">Finite difference computation of Jacobians (MatFD)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/DataLayout.html">Data Layout and Communication</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-9"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/PetscSF/index.html">Star Forest Communication (PetscSF)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/PetscSection/index.html">Section Data Layout (PetscSection)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/AO/index.html">Application Orderings (AO)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/DataManagement.html">Data Management between Vec and Mat, and Distributed Mesh Data Structures</a><input class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-10"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DM/index.html">Data Management (DM)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMDA/index.html">Structured Grids (DMDA)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMStag/index.html">Staggered, Structured Grids (DMSTAG)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMPlex/index.html">Unstructured Grids and Cell Complexes (DMPLEX)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMNetwork/index.html">Graphs and Networks (DMNETWORK)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMForest/index.html">A Forest of Trees and Structured Adaptive Refinement (DMFOREST)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMPatch/index.html">Sequences of parallel mesh patches (DMPATCH)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMSwarm/index.html">Particle Discretizations (DMSWARM)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMMOAB/index.html">MOAB Mesh Representation (DMMOAB)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMLabel/index.html">Selecting Parts of Meshes (DMLabel)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMPRODUCT/index.html">Tensor products of meshes (DMRODUCT)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DMComposite/index.html">DMComposite</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Discretization.html">Discretization and Function Spaces</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-11"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DT/index.html">Discretization Technology and Quadrature (DT)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/SPACE/index.html">Function Spaces (PetscSpace)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/DUALSPACE/index.html">Dual Spaces (PetscDualSpace)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/FE/index.html">Finite Elements (PetscFE)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/FV/index.html">Finite Volumes (PetscFV)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/PF/index.html">Defining your own mathematical functions (PF)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/LANDAU/index.html">Landau Collision Operator</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/LinearSolvers.html">Linear Solvers and Preconditioners</a><input class="toctree-checkbox" id="toctree-checkbox-12" name="toctree-checkbox-12" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-12"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/KSP/index.html">Linear Solvers and Krylov Methods (KSP)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/PC/index.html">Preconditioners (PC)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/NonlinearSolvers.html">Nonlinear Solvers</a><input class="toctree-checkbox" id="toctree-checkbox-13" name="toctree-checkbox-13" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-13"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/SNES/index.html">Nonlinear Solvers (SNES)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/SNESFAS/index.html">Full Approximation Scheme (FAS) nonlinear multigrid</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Timestepping.html">Forward and Adjoint Timestepping</a><input class="toctree-checkbox" id="toctree-checkbox-14" name="toctree-checkbox-14" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-14"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/TS/index.html">Time Stepping ODE and DAE Solvers (TS)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Sensitivity/index.html">Sensitivity Analysis for ODE and DAE</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Characteristic/index.html">Semi-Lagrangian Solves using the Method of Characteristics</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Optimization.html">Optimization</a><input class="toctree-checkbox" id="toctree-checkbox-15" name="toctree-checkbox-15" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-15"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Tao/index.html">Optimization Solvers (Tao)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/TaoLineSearch/index.html">Optimization Line Search (TaoLineSearch)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/Visualization.html">Graphics and Visualization</a><input class="toctree-checkbox" id="toctree-checkbox-16" name="toctree-checkbox-16" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-16"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Draw/index.html">Graphics (Draw)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Viewer/index.html">Viewing Objects (Viewer)</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="../manualpages/System.html">System Routines, Profiling, Data Structures</a><input class="toctree-checkbox" id="toctree-checkbox-17" name="toctree-checkbox-17" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-17"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Sys/index.html">PETSc Options, IO, and System Utilities</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/PetscH/index.html">Hash Tables</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Log/index.html">Profiling and Logging</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Device/index.html">Device</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Matlab/index.html">Matlab</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/Bag/index.html">Bag</a></li>
<li class="toctree-l3"><a class="reference internal" href="../manualpages/BM/index.html">Benchmarks (BM)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../changes/index.html">Changes for each release</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manualpages/singleindex.html">Single Index of all PETSc Manual Pages</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../changes/index.html">Changes for each release</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manualpages/singleindex.html">Single Index of all PETSc Manual Pages</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="../overview/previous_release_docs.html">Documentation for previous PETSc releases</a><input class="toctree-checkbox" id="toctree-checkbox-18" name="toctree-checkbox-18" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-18"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.22/docs"> 3.22</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.21/docs"> 3.21</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.20/docs"> 3.20</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.19/docs"> 3.19</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.18/docs"> 3.18</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.17/docs"> 3.17</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.16/docs"> 3.16</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.15/docs"> 3.15</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.14/docs"> 3.14</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.13/docs"> 3.13</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.12/docs"> 3.12</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.11/docs"> 3.11</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.10/docs"> 3.10</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.9/docs"> 3.9</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.8/docs"> 3.8</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.7/docs"> 3.7</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.6/docs"> 3.6</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.5/docs"> 3.5</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.4/docs"> 3.4</a></li>
<li class="toctree-l2"><a class="reference external" href="https://web.cels.anl.gov/projects/petsc/vault/petsc-3.3/docs"> 3.3</a></li>
</ul>
</li>
</ul>
</div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
  </div>
  
  <div id="rtd-footer-container"></div>


      </div>
      
      <main id="main-content" class="bd-main">
        
        
          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item">





<nav aria-label="Breadcrumb">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="../index.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    
    <li class="breadcrumb-item"><a href="../overview/index.html" class="nav-link">Overview</a></li>
    
    
    <li class="breadcrumb-item"><i class="fa-solid fa-ellipsis"></i></li>
    
    
    <li class="breadcrumb-item"><a href="programming.html" class="nav-link">The Solvers in PETSc/TAO</a></li>
    
    <li class="breadcrumb-item active" aria-current="page">KSP: Linear...</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="ksp-linear-system-solvers">
<span id="ch-ksp"></span><h1>KSP: Linear System Solvers<a class="headerlink" href="#ksp-linear-system-solvers" title="Link to this heading">#</a></h1>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> object is the heart of PETSc, because it provides uniform
and efficient access to all of the package’s linear system solvers,
including parallel and sequential, direct and iterative. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> is
intended for solving systems of the form</p>
<div class="math" id="equation-eq-axeqb">
<span class="eqno">(1)<a class="headerlink" href="#equation-eq-axeqb" title="Permalink to this equation">#</a></span>\[
A x = b,
\]</div>
<p>where <span class="math">\(A\)</span> denotes the matrix representation of a linear operator,
<span class="math">\(b\)</span> is the right-hand-side vector, and <span class="math">\(x\)</span> is the solution
vector. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> uses the same calling sequence for both direct and
iterative solution of a linear system. In addition, particular solution
techniques and their associated options can be selected at runtime.</p>
<p>The combination of a Krylov subspace method and a preconditioner is at
the center of most modern numerical codes for the iterative solution of
linear systems. Many textbooks (e.g. <span id="id1">[<a class="reference internal" href="#id1238" title="R. Freund, G. H. Golub, and N. Nachtigal. Iterative Solution of Linear Systems, pages 57–100. Acta Numerica. Cambridge University Press, 1992.">FGN92</a>]</span> <span id="id2">[<a class="reference internal" href="#id2252" title="H. van der Vorst. Iterative Krylov Methods for Large Linear Systems. Cambridge University Press, 2003. ISBN 9780521818285.">vdV03</a>]</span>, or <span id="id3">[<a class="reference internal" href="../manualpages/Mat/MatILUFactorSymbolic.html#id1341" title="Yousef Saad. Iterative Methods for Sparse Linear Systems. SIAM, 2nd edition, 2003. doi:10.1016/S1570-579X(01)80025-2.">Saa03</a>]</span>) provide an
overview of the theory of such methods.
The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> package, discussed in
<a class="reference internal" href="#sec-ksp"><span class="std std-ref">Krylov Methods</span></a>, provides many popular Krylov subspace
iterative methods; the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> module, described in
<a class="reference internal" href="#sec-pc"><span class="std std-ref">Preconditioners</span></a>, includes a variety of preconditioners.</p>
<section id="using-ksp">
<span id="sec-usingksp"></span><h2>Using KSP<a class="headerlink" href="#using-ksp" title="Link to this heading">#</a></h2>
<p>To solve a linear system with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>, one must first create a solver
context with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPCreate.html">KSPCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre">comm</span></code> is the MPI communicator and <code class="docutils notranslate"><span class="pre">ksp</span></code> is the newly formed
solver context. Before actually solving a linear system with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>,
the user must call the following routine to set the matrices associated
with the linear system:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Pmat</span><span class="p">);</span>
</pre></div>
</div>
<p>The argument <code class="docutils notranslate"><span class="pre">Amat</span></code>, representing the matrix that defines the linear
system, is a symbolic placeholder for any kind of matrix or operator. In
particular, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> <em>does</em> support matrix-free methods. The routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateShell.html">MatCreateShell</a>()</span></code> in <a class="reference internal" href="mat.html#sec-matrixfree"><span class="std std-ref">Application Specific Custom Matrices</span></a>
provides further information regarding matrix-free methods. Typically,
the matrix from which the preconditioner is to be constructed, <code class="docutils notranslate"><span class="pre">Pmat</span></code>,
is the same as the matrix that defines the linear system, <code class="docutils notranslate"><span class="pre">Amat</span></code>;
however, occasionally these matrices differ (for instance, when a
preconditioning matrix is obtained from a lower order method than that
employed to form the linear system matrix).</p>
<p>Much of the power of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> can be accessed through the single routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetFromOptions.html">KSPSetFromOptions</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine accepts the option <code class="docutils notranslate"><span class="pre">-help</span></code> as well as any of
the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> options discussed below. To solve a linear
system, one sets the right hand size and solution vectors using the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">b</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">b</span></code> and <code class="docutils notranslate"><span class="pre">x</span></code> respectively denote the right-hand side and
solution vectors. On return, the iteration number at which the iterative
process stopped can be obtained using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPGetIterationNumber.html">KSPGetIterationNumber</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">its</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that this does not state that the method converged at this
iteration: it can also have reached the maximum number of iterations, or
have diverged.</p>
<p><a class="reference internal" href="#sec-convergencetests"><span class="std std-ref">Convergence Tests</span></a> gives more details
regarding convergence testing. Note that multiple linear solves can be
performed by the same <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context. Once the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context is no
longer needed, it should be destroyed with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPDestroy.html">KSPDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>The above procedure is sufficient for general use of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>
package. One additional step is required for users who wish to customize
certain preconditioners (e.g., see <a class="reference internal" href="#sec-bjacobi"><span class="std std-ref">Block Jacobi and Overlapping Additive Schwarz Preconditioners</span></a>) or
to log certain performance data using the PETSc profiling facilities (as
discussed in <a class="reference internal" href="profiling.html#ch-profiling"><span class="std std-ref">Profiling</span></a>). In this case, the user can
optionally explicitly call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetUp.html">KSPSetUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>before calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> to perform any setup required for the
linear solvers. The explicit call of this routine enables the separate
profiling of any computations performed during the set up phase, such
as incomplete factorization for the ILU preconditioner.</p>
<p>The default solver within <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> is restarted GMRES, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code>, preconditioned for
the uniprocess case with ILU(0), and for the multiprocess case with the
block Jacobi method (with one block per process, each of which is solved
with ILU(0)). A variety of other solvers and options are also available.
To allow application programmers to set any of the preconditioner or
Krylov subspace options directly within the code, we provide routines
that extract the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> contexts,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="o">*</span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The application programmer can then directly call any of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> routines to modify the corresponding default options.</p>
<p>To solve a linear system with a direct solver (supported by
PETSc for sequential matrices, and by several external solvers through
PETSc interfaces, see <a class="reference internal" href="#sec-externalsol"><span class="std std-ref">Using External Linear Solvers</span></a>) one may use
the options <code class="docutils notranslate"><span class="pre">-ksp_type</span></code> <code class="docutils notranslate"><span class="pre">preonly</span></code> (or the equivalent <code class="docutils notranslate"><span class="pre">-ksp_type</span></code> <code class="docutils notranslate"><span class="pre">none</span></code>)
<code class="docutils notranslate"><span class="pre">-pc_type</span></code> <code class="docutils notranslate"><span class="pre">lu</span></code> or <code class="docutils notranslate"><span class="pre">-pc_type</span></code> <code class="docutils notranslate"><span class="pre">cholesky</span></code> (see below).</p>
<p>By default, if a direct solver is used, the factorization is <em>not</em> done
in-place. This approach prevents the user from the unexpected surprise
of having a corrupted matrix after a linear solve. The routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFactorSetUseInPlace.html">PCFactorSetUseInPlace</a>()</span></code>, discussed below, causes factorization to be
done in-place.</p>
</section>
<section id="solving-successive-linear-systems">
<h2>Solving Successive Linear Systems<a class="headerlink" href="#solving-successive-linear-systems" title="Link to this heading">#</a></h2>
<p>When solving multiple linear systems of the same size with the same
method, several options are available. To solve successive linear
systems having the <em>same</em> preconditioner matrix (i.e., the same data
structure with exactly the same matrix elements) but different
right-hand-side vectors, the user should simply call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>
multiple times. The preconditioner setup operations (e.g., factorization
for ILU) will be done during the first call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> only; such
operations will <em>not</em> be repeated for successive solves.</p>
<p>To solve successive linear systems that have <em>different</em> matrix values, because you
have changed the matrix values in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> objects you passed to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a>()</span></code>,
still simply call <code class="docutils notranslate"><span class="pre">KPSSolve()</span></code>. In this case the preconditioner will be recomputed
automatically. Use the option <code class="docutils notranslate"><span class="pre">-ksp_reuse_preconditioner</span> <span class="pre">true</span></code>, or call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetReusePreconditioner.html">KSPSetReusePreconditioner</a>()</span></code>, to reuse the previously computed preconditioner.
For many problems, if the matrix changes values only slightly, reusing the
old preconditioner can be more efficient.</p>
<p>If you wish to reuse the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> with a different sized matrix and vectors, you must
call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPReset.html">KSPReset</a>()</span></code> before calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a>()</span></code> with the new matrix.</p>
</section>
<section id="krylov-methods">
<span id="sec-ksp"></span><h2>Krylov Methods<a class="headerlink" href="#krylov-methods" title="Link to this heading">#</a></h2>
<p>The Krylov subspace methods accept a number of options, many of which
are discussed below. First, to set the Krylov subspace method that is to
be used, one calls the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span><span class="w"> </span><span class="n">method</span><span class="p">);</span>
</pre></div>
</div>
<p>The type can be one of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPRICHARDSON.html">KSPRICHARDSON</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCHEBYSHEV.html">KSPCHEBYSHEV</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTCQMR.html">KSPTCQMR</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBCGS.html">KSPBCGS</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCGS.html">KSPCGS</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTFQMR.html">KSPTFQMR</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCR.html">KSPCR</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPLSQR.html">KSPLSQR</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBICG.html">KSPBICG</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPREONLY.html">KSPPREONLY</a></span></code> (or the equivalent <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPNONE.html">KSPNONE</a></span></code>), or others; see
<a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a> or the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span></code> man page for more.
The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> method can also be set with the options database command
<code class="docutils notranslate"><span class="pre">-ksp_type</span></code>, followed by one of the options <code class="docutils notranslate"><span class="pre">richardson</span></code>,
<code class="docutils notranslate"><span class="pre">chebyshev</span></code>, <code class="docutils notranslate"><span class="pre">cg</span></code>, <code class="docutils notranslate"><span class="pre">gmres</span></code>, <code class="docutils notranslate"><span class="pre">tcqmr</span></code>, <code class="docutils notranslate"><span class="pre">bcgs</span></code>, <code class="docutils notranslate"><span class="pre">cgs</span></code>,
<code class="docutils notranslate"><span class="pre">tfqmr</span></code>, <code class="docutils notranslate"><span class="pre">cr</span></code>, <code class="docutils notranslate"><span class="pre">lsqr</span></code>, <code class="docutils notranslate"><span class="pre">bicg</span></code>, <code class="docutils notranslate"><span class="pre">preonly</span></code> (or the equivalent <code class="docutils notranslate"><span class="pre">none</span></code>), or others (see
<a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a> or the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span></code> man page). There are
method-specific options. For instance, for the Richardson, Chebyshev, and
GMRES methods:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPRichardsonSetScale.html">KSPRichardsonSetScale</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">scale</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPChebyshevSetEigenvalues.html">KSPChebyshevSetEigenvalues</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">emax</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">emin</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPGMRESSetRestart.html">KSPGMRESSetRestart</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">max_steps</span><span class="p">);</span>
</pre></div>
</div>
<p>The default parameter values are
<code class="docutils notranslate"><span class="pre">scale=1.0,</span> <span class="pre">emax=0.01,</span> <span class="pre">emin=100.0</span></code>, and <code class="docutils notranslate"><span class="pre">max_steps=30</span></code>. The
GMRES restart and Richardson damping factor can also be set with the
options <code class="docutils notranslate"><span class="pre">-ksp_gmres_restart</span> <span class="pre">&lt;n&gt;</span></code> and
<code class="docutils notranslate"><span class="pre">-ksp_richardson_scale</span> <span class="pre">&lt;factor&gt;</span></code>.</p>
<p>The default technique for orthogonalization of the Krylov vectors in
GMRES is the unmodified (classical) Gram-Schmidt method, which can be
set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPGMRESSetOrthogonalization.html">KSPGMRESSetOrthogonalization</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPGMRESClassicalGramSchmidtOrthogonalization.html">KSPGMRESClassicalGramSchmidtOrthogonalization</a></span><span class="p">);</span>
</pre></div>
</div>
<p>or the options database command <code class="docutils notranslate"><span class="pre">-ksp_gmres_classicalgramschmidt</span></code>. By
default this will <em>not</em> use iterative refinement to improve the
stability of the orthogonalization. This can be changed with the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPGMRESSetCGSRefinementType.html">KSPGMRESSetCGSRefinementType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPGMRESCGSRefinementType.html">KSPGMRESCGSRefinementType</a></span><span class="w"> </span><span class="n">type</span><span class="p">)</span>
</pre></div>
</div>
<p>or via the options database with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">ksp_gmres_cgs_refinement_type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">refine_never</span><span class="p">,</span><span class="n">refine_ifneeded</span><span class="p">,</span><span class="n">refine_always</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>The values for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRESCGSRefinementType.html">KSPGMRESCGSRefinementType</a>()</span></code> are
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP_GMRES_CGS_REFINE_NEVER.html">KSP_GMRES_CGS_REFINE_NEVER</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP_GMRES_CGS_REFINE_IFNEEDED.html">KSP_GMRES_CGS_REFINE_IFNEEDED</a></span></code>
and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP_GMRES_CGS_REFINE_ALWAYS.html">KSP_GMRES_CGS_REFINE_ALWAYS</a></span></code>.</p>
<p>One can also use modified Gram-Schmidt, by using the orthogonalization
routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRESModifiedGramSchmidtOrthogonalization.html">KSPGMRESModifiedGramSchmidtOrthogonalization</a>()</span></code> or by using
the command line option <code class="docutils notranslate"><span class="pre">-ksp_gmres_modifiedgramschmidt</span></code>.</p>
<p>For the conjugate gradient method with complex numbers, there are two
slightly different algorithms depending on whether the matrix is
Hermitian symmetric or truly symmetric (the default is to assume that it
is Hermitian symmetric). To indicate that it is symmetric, one uses the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPCGSetType.html">KSPCGSetType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPCGType.html">KSP_CG_SYMMETRIC</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Note that this option is not valid for all matrices.</p>
<p>Some <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> types do not support preconditioning. For instance,
the CGLS algorithm does not involve a preconditioner; any preconditioner
set to work with the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> object is ignored if <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCGLS.html">KSPCGLS</a></span></code> was
selected.</p>
<p>By default, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> assumes an initial guess of zero by zeroing the
initial value for the solution vector that is given; this zeroing is
done at the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>. To use a nonzero initial guess, the
user <em>must</em> call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetInitialGuessNonzero.html">KSPSetInitialGuessNonzero</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<section id="preconditioning-within-ksp">
<span id="sec-ksppc"></span><h3>Preconditioning within KSP<a class="headerlink" href="#preconditioning-within-ksp" title="Link to this heading">#</a></h3>
<p>Since the rate of convergence of Krylov projection methods for a
particular linear system is strongly dependent on its spectrum,
preconditioning is typically used to alter the spectrum and hence
accelerate the convergence rate of iterative techniques. Preconditioning
can be applied to the system <a class="reference internal" href="#equation-eq-axeqb">(1)</a> by</p>
<div class="math" id="equation-eq-prec">
<span class="eqno">(2)<a class="headerlink" href="#equation-eq-prec" title="Permalink to this equation">#</a></span>\[
(M_L^{-1} A M_R^{-1}) \, (M_R x) = M_L^{-1} b,
\]</div>
<p>where <span class="math">\(M_L\)</span> and <span class="math">\(M_R\)</span> indicate preconditioning matrices (or,
matrices from which the preconditioner is to be constructed). If
<span class="math">\(M_L = I\)</span> in <a class="reference internal" href="#equation-eq-prec">(2)</a>, right preconditioning
results, and the residual of <a class="reference internal" href="#equation-eq-axeqb">(1)</a>,</p>
<div class="math">
\[
r \equiv b - Ax = b - A M_R^{-1} \, M_R x,
\]</div>
<p>is preserved. In contrast, the residual is altered for left
(<span class="math">\(M_R = I\)</span>) and symmetric preconditioning, as given by</p>
<div class="math">
\[
r_L \equiv M_L^{-1} b - M_L^{-1} A x = M_L^{-1} r.
\]</div>
<p>By default, most KSP implementations use left preconditioning. Some more
naturally use other options, though. For instance, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPQCG.html">KSPQCG</a></span></code> defaults
to use symmetric preconditioning and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFGMRES.html">KSPFGMRES</a></span></code> uses right
preconditioning by default. Right preconditioning can be activated for
some methods by using the options database command
<code class="docutils notranslate"><span class="pre">-ksp_pc_side</span> <span class="pre">right</span></code> or calling the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetPCSide.html">KSPSetPCSide</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCSide.html">PC_RIGHT</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Attempting to use right preconditioning for a method that does not
currently support it results in an error message of the form</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>KSPSetUp_Richardson:No right preconditioning for <a href="../manualpages/KSP/KSPRICHARDSON.html">KSPRICHARDSON</a>
</pre></div>
</div>
<table class="table" id="tab-kspdefaults">
<caption><span class="caption-number">Table 6 </span><span class="caption-text">KSP Objects</span><a class="headerlink" href="#tab-kspdefaults" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Method</p></th>
<th class="head"><p>KSPType</p></th>
<th class="head"><p>Options Database</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Richardson</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPRICHARDSON.html">KSPRICHARDSON</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">richardson</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Chebyshev</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCHEBYSHEV.html">KSPCHEBYSHEV</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">chebyshev</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradient <span id="id1">[<a class="reference internal" href="../manualpages/KSP/KSPCR.html#id1272" title="Magnus R. Hestenes and Eduard Steifel. Methods of conjugate gradients for solving linear systems. J. Research of the National Bureau of Standards, 49:409-436, 1952.">HS52</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Conjugate Gradients <span id="id2">[<a class="reference internal" href="../manualpages/KSP/KSPPIPECR.html#id1800" title="P. Ghysels and W. Vanroose. Hiding global synchronization latency in the preconditioned conjugate gradient algorithm. Parallel Computing, 40(7):224–238, 2014. 7th Workshop on Parallel Matrix Algorithms and Applications. doi:10.1016/j.parco.2013.06.001.">GV14</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPECG.html">KSPPIPECG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipecg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined Conjugate Gradients (Gropp)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGROPPCG.html">KSPGROPPCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">groppcg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Conjugate Gradients with Residual Replacement</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPECGRR.html">KSPPIPECGRR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipecgrr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients for the Normal Equations</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCGNE.html">KSPCGNE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cgne</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Flexible Conjugate Gradients <span id="id3">[<a class="reference internal" href="../manualpages/KSP/KSPFCG.html#id1880" title="Yvan Notay. Flexible conjugate gradients. SIAM Journal on Scientific Computing, 22(4):1444–1460, 2000.">Not00</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFCG.html">KSPFCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p> Pipelined, Flexible Conjugate Gradients <span id="id4">[<a class="reference internal" href="../manualpages/KSP/KSPPIPEGCR.html#id990" title="P. Sanan, S. M. Schnepp, and D. A. May. Pipelined, flexible Krylov subspace methods. SIAM Journal on Scientific Computing, 38(5):C441-C470, 2016. doi:10.1137/15M1049130.">SSM16</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPEFCG.html">KSPPIPEFCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipefcg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients for Least Squares</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCGLS.html">KSPCGLS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cgls</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients with Constraint (1)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPNASH.html">KSPNASH</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">nash</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients with Constraint (2)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSTCG.html">KSPSTCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">stcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Gradients with Constraint (3)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGLTR.html">KSPGLTR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">gltr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradients with Constraint (4)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPQCG.html">KSPQCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">qcg</span></code></p></td>
</tr>
<tr class="row-even"><td><p>BiConjugate Gradient</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBICG.html">KSPBICG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bicg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>BiCGSTAB <span id="id5">[<a class="reference internal" href="#id1273" title="H. A. van der Vorst. BiCGSTAB: a fast and smoothly converging variant of BiCG for the solution of nonsymmetric linear systems. SIAM J. Sci. Stat. Comput., 13:631-644, 1992.">vandVorst92</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBCGS.html">KSPBCGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bcgs</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Improved BiCGSTAB</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPIBCGS.html">KSPIBCGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ibcgs</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>QMRCGSTAB <span id="id6">[<a class="reference internal" href="../manualpages/KSP/KSPQMRCGS.html#id3897" title="Tony F Chan, Efstratios Gallopoulos, Valeria Simoncini, Tedd Szeto, and Charles H Tong. A quasi-minimal residual variant of the Bi-CGSTAB algorithm for nonsymmetric systems. SIAM Journal on Scientific Computing, 15(2):338–347, 1994.">CGS+94</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPQMRCGS.html">KSPQMRCGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">qmrcgs</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Flexible BiCGSTAB</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFBCGS.html">KSPFBCGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fbcgs</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Flexible BiCGSTAB (variant)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFBCGSR.html">KSPFBCGSR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fbcgsr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Enhanced BiCGSTAB(L)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBCGSL.html">KSPBCGSL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bcgsl</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Minimal Residual Method <span id="id7">[<a class="reference internal" href="../manualpages/KSP/KSPSYMMLQ.html#id3448" title="C. C. Paige and M. A. Saunders. Solution of sparse indefinite systems of linear equations. SIAM Journal on Numerical Analysis, 12:617–629, 1975.">PS75</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMINRES.html">KSPMINRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">minres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Generalized Minimal Residual <span id="id8">[<a class="reference internal" href="../manualpages/KSP/KSPGMRES.html#id3638" title="Y. Saad and M. Schultz. GMRES: A generalized minimal residual algorithm for solving nonsymmetric linear systems. SIAM Journal on Scientific and Statistical Computing, 44:856–869, 1986.">SS86</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">gmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Flexible Generalized Minimal Residual <span id="id9">[<a class="reference internal" href="#id1669" title="Youcef Saad. A flexible inner-outer preconditioned GMRES algorithm. SIAM Journal on Scientific Computing, 14(2):461–469, 1993. doi:10.1137/0914028.">Saa93</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFGMRES.html">KSPFGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fgmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Deflated Generalized Minimal Residual</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPDGMRES.html">KSPDGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">dgmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined Generalized Minimal Residual <span id="id10">[<a class="reference internal" href="../manualpages/KSP/KSPPGMRES.html#id1799" title="P. Ghysels, T.J. Ashby, K. Meerbergen, and W. Vanroose. Hiding global communication latency in the GMRES algorithm on massively parallel machines. SIAM Journal on Scientific Computing, 35(1):C48–C71, 2013.">GAMV13</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPGMRES.html">KSPPGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pgmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined, Flexible Generalized Minimal Residual <span id="id11">[<a class="reference internal" href="../manualpages/KSP/KSPPIPEGCR.html#id990" title="P. Sanan, S. M. Schnepp, and D. A. May. Pipelined, flexible Krylov subspace methods. SIAM Journal on Scientific Computing, 38(5):C441-C470, 2016. doi:10.1137/15M1049130.">SSM16</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPEFGMRES.html">KSPPIPEFGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipefgmres</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Generalized Minimal Residual with Accelerated Restart</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPLGMRES.html">KSPLGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lgmres</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Conjugate Residual <span id="id12">[<a class="reference internal" href="../manualpages/KSP/KSPGCR.html#id1685" title="S.C. Eisenstat, H.C. Elman, and M.H. Schultz. Variational iterative methods for nonsymmetric systems of linear equations. SIAM Journal on Numerical Analysis, 20(2):345–357, 1983.">EES83</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCR.html">KSPCR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Generalized Conjugate Residual</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGCR.html">KSPGCR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">gcr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Pipelined Conjugate Residual</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPECR.html">KSPPIPECR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipecr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Pipelined, Flexible Conjugate Residual <span id="id13">[<a class="reference internal" href="../manualpages/KSP/KSPPIPEGCR.html#id990" title="P. Sanan, S. M. Schnepp, and D. A. May. Pipelined, flexible Krylov subspace methods. SIAM Journal on Scientific Computing, 38(5):C441-C470, 2016. doi:10.1137/15M1049130.">SSM16</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPIPEGCR.html">KSPPIPEGCR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pipegcr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>FETI-DP</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFETIDP.html">KSPFETIDP</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fetidp</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Conjugate Gradient Squared <span id="id14">[<a class="reference internal" href="../manualpages/KSP/KSPCGS.html#id1273" title="Peter Sonneveld. CGS, a fast Lanczos-type solver for nonsymmetric linear systems. SIAM J. Sci. Stat. Comput., 10:36-52, 1989.">Son89</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCGS.html">KSPCGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cgs</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Transpose-Free Quasi-Minimal Residual (1) <span id="id15">[<a class="reference internal" href="../manualpages/KSP/KSPTFQMR.html#id1275" title="Roland W. Freund. A transpose-free quasi-minimal residual algorithm for non-Hermitian linear systems. SIAM J. Sci. Stat. Comput., 14:470-482, 1993.">Fre93</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTFQMR.html">KSPTFQMR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">tfqmr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Transpose-Free Quasi-Minimal Residual (2)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTCQMR.html">KSPTCQMR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">tcqmr</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Least Squares Method</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPLSQR.html">KSPLSQR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lsqr</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Symmetric LQ Method <span id="id16">[<a class="reference internal" href="../manualpages/KSP/KSPSYMMLQ.html#id3448" title="C. C. Paige and M. A. Saunders. Solution of sparse indefinite systems of linear equations. SIAM Journal on Numerical Analysis, 12:617–629, 1975.">PS75</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSYMMLQ.html">KSPSYMMLQ</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">symmlq</span></code></p></td>
</tr>
<tr class="row-even"><td><p>TSIRM</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPTSIRM.html">KSPTSIRM</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">tsirm</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Python Shell</p></td>
<td><p><code class="docutils notranslate"><span class="pre">KSPPYTHON</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">python</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Shell for no <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> method</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPNONE.html">KSPNONE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">none</span></code></p></td>
</tr>
</tbody>
</table>
<p>Note: the bi-conjugate gradient method requires application of both the
matrix and its transpose plus the preconditioner and its transpose.
Currently not all matrices and preconditioners provide this support and
thus the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPBICG.html">KSPBICG</a></span></code> cannot always be used.</p>
<p>Note: PETSc implements the FETI-DP (Finite Element Tearing and
Interconnecting Dual-Primal) method as an implementation of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> since it recasts the
original problem into a constrained minimization one with Lagrange
multipliers. The only matrix type supported is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATIS.html">MATIS</a></span></code>. Support for
saddle point problems is provided. See the man page for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFETIDP.html">KSPFETIDP</a></span></code> for
further details.</p>
</section>
<section id="convergence-tests">
<span id="sec-convergencetests"></span><h3>Convergence Tests<a class="headerlink" href="#convergence-tests" title="Link to this heading">#</a></h3>
<p>The default convergence test, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPConvergedDefault.html">KSPConvergedDefault</a>()</span></code>, uses the $ l_2 $ norm of the preconditioned $ B(b - A x) $ or unconditioned residual $ b - Ax$, depending on the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span></code> and the value of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPNormType.html">KSPNormType</a></span></code> set with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetNormType.html">KSPSetNormType</a></span></code>. For <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code> the default is the norm of the preconditioned residual.
The preconditioned residual is used by default for
convergence testing of all left-preconditioned <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> methods. For the
conjugate gradient, Richardson, and Chebyshev methods the true residual
can be used by the options database command
<code class="docutils notranslate"><span class="pre">-ksp_norm_type</span> <span class="pre">unpreconditioned</span></code> or by calling the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetNormType.html">KSPSetNormType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/KSP/KSP_NORM_UNPRECONDITIONED.html">KSP_NORM_UNPRECONDITIONED</a></span><span class="p">);</span>
</pre></div>
</div>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code> also supports using the natural norm induced by the symmetric positive-definite
matrix that defines the linear system with the options database command <code class="docutils notranslate"><span class="pre">-ksp_norm_type</span> <span class="pre">natural</span></code> or by calling the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetNormType.html">KSPSetNormType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/KSP/KSP_NORM_NATURAL.html">KSP_NORM_NATURAL</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Convergence (or divergence) is decided
by three quantities: the decrease of the residual norm relative to the
norm of the right-hand side, <code class="docutils notranslate"><span class="pre">rtol</span></code>, the absolute size of the residual
norm, <code class="docutils notranslate"><span class="pre">atol</span></code>, and the relative increase in the residual, <code class="docutils notranslate"><span class="pre">dtol</span></code>.
Convergence is detected at iteration <span class="math">\(k\)</span> if</p>
<div class="math">
\[
\| r_k \|_2 < {\rm max} ( \text{rtol} * \| b \|_2, \text{atol}),
\]</div>
<p>where <span class="math">\(r_k = b - A x_k\)</span>. Divergence is detected if</p>
<div class="math">
\[
\| r_k \|_2 > \text{dtol} * \| b \|_2.
\]</div>
<p>These parameters, as well as the maximum number of allowable iterations,
can be set with the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetTolerances.html">KSPSetTolerances</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">rtol</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">atol</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">dtol</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">maxits</span><span class="p">);</span>
</pre></div>
</div>
<p>The user can retain the current value of any of these parameters by
specifying <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span></code> as the corresponding tolerance; the
defaults are <code class="docutils notranslate"><span class="pre">rtol=1e-5</span></code>, <code class="docutils notranslate"><span class="pre">atol=1e-50</span></code>, <code class="docutils notranslate"><span class="pre">dtol=1e5</span></code>, and
<code class="docutils notranslate"><span class="pre">maxits=1e4</span></code>. Using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_DETERMINE.html">PETSC_DETERMINE</a></span></code> will set the parameters back to their
initial values when the object’s type was set. These parameters can also be set from the options
database with the commands <code class="docutils notranslate"><span class="pre">-ksp_rtol</span></code> <code class="docutils notranslate"><span class="pre">&lt;rtol&gt;</span></code>, <code class="docutils notranslate"><span class="pre">-ksp_atol</span></code>
<code class="docutils notranslate"><span class="pre">&lt;atol&gt;</span></code>, <code class="docutils notranslate"><span class="pre">-ksp_divtol</span></code> <code class="docutils notranslate"><span class="pre">&lt;dtol&gt;</span></code>, and <code class="docutils notranslate"><span class="pre">-ksp_max_it</span></code> <code class="docutils notranslate"><span class="pre">&lt;its&gt;</span></code>.</p>
<p>In addition to providing an interface to a simple convergence test,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> allows the application programmer the flexibility to provide
customized convergence-testing routines. The user can specify a
customized routine with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetConvergenceTest.html">KSPSetConvergenceTest</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">test</span><span class="p">)(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">it</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">rnorm</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/KSP/KSPConvergedReason.html">KSPConvergedReason</a></span><span class="w"> </span><span class="o">*</span><span class="n">reason</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">destroy</span><span class="p">)(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">));</span>
</pre></div>
</div>
<p>The final routine argument, <code class="docutils notranslate"><span class="pre">ctx</span></code>, is an optional context for private
data for the user-defined convergence routine, <code class="docutils notranslate"><span class="pre">test</span></code>. Other <code class="docutils notranslate"><span class="pre">test</span></code>
routine arguments are the iteration number, <code class="docutils notranslate"><span class="pre">it</span></code>, and the residual’s
norm, <code class="docutils notranslate"><span class="pre">rnorm</span></code>. The routine for detecting convergence,
<code class="docutils notranslate"><span class="pre">test</span></code>, should set <code class="docutils notranslate"><span class="pre">reason</span></code> to positive for convergence, 0 for no
convergence, and negative for failure to converge. A full list of
possible values is given in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPConvergedReason.html">KSPConvergedReason</a></span></code> manual page.
You can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGetConvergedReason.html">KSPGetConvergedReason</a>()</span></code> after
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> to see why convergence/divergence was detected.</p>
</section>
<section id="convergence-monitoring">
<span id="sec-kspmonitor"></span><h3>Convergence Monitoring<a class="headerlink" href="#convergence-monitoring" title="Link to this heading">#</a></h3>
<p>By default, the Krylov solvers, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>, run silently without displaying
information about the iterations. The user can indicate that the norms
of the residuals should be displayed at each iteration by using <code class="docutils notranslate"><span class="pre">-ksp_monitor</span></code> with
the options database. To display the residual norms in a graphical
window (running under X Windows), one should use
<code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code>. Application programmers can also
provide their own routines to perform the monitoring by using the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPMonitorSet.html">KSPMonitorSet</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">mon</span><span class="p">)(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">it</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">rnorm</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">),</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscCtxDestroyFn.html">PetscCtxDestroyFn</a></span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">mondestroy</span><span class="p">);</span>
</pre></div>
</div>
<p>The final routine argument, <code class="docutils notranslate"><span class="pre">ctx</span></code>, is an optional context for private
data for the user-defined monitoring routine, <code class="docutils notranslate"><span class="pre">mon</span></code>. Other <code class="docutils notranslate"><span class="pre">mon</span></code>
routine arguments are the iteration number (<code class="docutils notranslate"><span class="pre">it</span></code>) and the residual’s
norm (<code class="docutils notranslate"><span class="pre">rnorm</span></code>), as discussed above in <a class="reference internal" href="#sec-convergencetests"><span class="std std-ref">Convergence Tests</span></a>.
A helpful routine within user-defined
monitors is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectGetComm.html">PetscObjectGetComm</a>((<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>)ksp,<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span> <span class="pre">*comm)</span></code>,
which returns in <code class="docutils notranslate"><span class="pre">comm</span></code> the MPI communicator for the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context.
See <a class="reference internal" href="getting_started.html#sec-writing"><span class="std std-ref">Writing PETSc Programs</span></a> for more discussion of the use of
MPI communicators within PETSc.</p>
<p>Many monitoring routines are supplied with PETSc, including</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPMonitorResidual.html">KSPMonitorResidual</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPMonitorSingularValue.html">KSPMonitorSingularValue</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPMonitorTrueResidual.html">KSPMonitorTrueResidual</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>The default monitor simply prints an estimate of a norm of
the residual at each iteration. The routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMonitorSingularValue.html">KSPMonitorSingularValue</a>()</span></code> is appropriate only for use with the
conjugate gradient method or GMRES, since it prints estimates of the
extreme singular values of the preconditioned operator at each
iteration computed via the Lanczos or Arnoldi algorithms.</p>
<p>Since <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMonitorTrueResidual.html">KSPMonitorTrueResidual</a>()</span></code> prints the true
residual at each iteration by actually computing the residual using the
formula <span class="math">\(r = b - Ax\)</span>, the routine is slow and should be used only
for testing or convergence studies, not for timing. These <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> monitors may
be accessed with the command line options <code class="docutils notranslate"><span class="pre">-ksp_monitor</span></code>,
<code class="docutils notranslate"><span class="pre">-ksp_monitor_singular_value</span></code>, and <code class="docutils notranslate"><span class="pre">-ksp_monitor_true_residual</span></code>.</p>
<p>To employ the default graphical monitor, one should use the command
<code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code>.</p>
<p>One can cancel hardwired monitoring routines for KSP at runtime with
<code class="docutils notranslate"><span class="pre">-ksp_monitor_cancel</span></code>.</p>
</section>
<section id="understanding-the-operators-spectrum">
<h3>Understanding the Operator’s Spectrum<a class="headerlink" href="#understanding-the-operators-spectrum" title="Link to this heading">#</a></h3>
<p>Since the convergence of Krylov subspace methods depends strongly on the
spectrum (eigenvalues) of the preconditioned operator, PETSc has
specific routines for eigenvalue approximation via the Arnoldi or
Lanczos iteration. First, before the linear solve one must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetComputeEigenvalues.html">KSPSetComputeEigenvalues</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Then after the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> solve one calls</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPComputeEigenvalues.html">KSPComputeEigenvalues</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">realpart</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">complexpart</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">neig</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils notranslate"><span class="pre">n</span></code> is the size of the two arrays and the eigenvalues are
inserted into those two arrays. <code class="docutils notranslate"><span class="pre">neig</span></code> is the number of eigenvalues
computed; this number depends on the size of the Krylov space generated
during the linear system solution, for GMRES it is never larger than the
<code class="docutils notranslate"><span class="pre">restart</span></code> parameter. There is an additional routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPComputeEigenvaluesExplicitly.html">KSPComputeEigenvaluesExplicitly</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">realpart</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">complexpart</span><span class="p">);</span>
</pre></div>
</div>
<p>that is useful only for very small problems. It explicitly computes the
full representation of the preconditioned operator and calls LAPACK to
compute its eigenvalues. It should be only used for matrices of size up
to a couple hundred. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawSP.html">PetscDrawSP</a>*()</span></code> routines are very useful for
drawing scatter plots of the eigenvalues.</p>
<p>The eigenvalues may also be computed and displayed graphically with the
options data base commands <code class="docutils notranslate"><span class="pre">-ksp_view_eigenvalues</span> <span class="pre">draw</span></code> and
<code class="docutils notranslate"><span class="pre">-ksp_view_eigenvalues_explicit</span> <span class="pre">draw</span></code>. Or they can be dumped to the
screen in ASCII text via <code class="docutils notranslate"><span class="pre">-ksp_view_eigenvalues</span></code> and
<code class="docutils notranslate"><span class="pre">-ksp_view_eigenvalues_explicit</span></code>.</p>
</section>
<section id="flexible-krylov-methods">
<span id="sec-flexibleksp"></span><h3>Flexible Krylov Methods<a class="headerlink" href="#flexible-krylov-methods" title="Link to this heading">#</a></h3>
<p>Standard Krylov methods require that the preconditioner be a linear operator, thus, for example, a standard <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> method
cannot use a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> in its preconditioner, as is common in the Block-Jacobi method <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBJACOBI.html">PCBJACOBI</a></span></code>, for example.
Flexible Krylov methods are a subset of methods that allow (with modest additional requirements
on memory) the preconditioner to be nonlinear. For example, they can be used with the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code> preconditioner.
The flexible <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> methods have the label “Flexible” in <a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a>.</p>
<p>One can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMonitorDynamicTolerance.html">KSPMonitorDynamicTolerance</a>()</span></code> to control the tolerances used by inner <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> solvers in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBJACOBI.html">PCBJACOBI</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCDEFLATION.html">PCDEFLATION</a></span></code>.</p>
<p>In addition to supporting <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code>, the flexible methods support <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a>*SetModifyPC()</span></code>, for example, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFGMRESSetModifyPC.html">KSPFGMRESSetModifyPC</a>()</span></code>, these functions
allow the user to provide a callback function that changes the preconditioner at each Krylov iteration. Its calling sequence is as follows.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">total_its</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">its_since_restart</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">res_norm</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="pipelined-krylov-methods">
<span id="sec-pipelineksp"></span><h3>Pipelined Krylov Methods<a class="headerlink" href="#pipelined-krylov-methods" title="Link to this heading">#</a></h3>
<p>Standard Krylov methods have one or more global reductions resulting from the computations of inner products or norms in each iteration.
These reductions need to block until all MPI processes have received the results. For a large number of MPI processes (this number is machine dependent
but can be above 10,000 processes) this synchronization is very time consuming and can significantly slow the computation. Pipelined Krylov
methods overlap the reduction operations with local computations (generally the application of the matrix-vector products and precondtiioners)
thus effectively “hiding” the time of the reductions. In addition, they may reduce the number of global synchronizations by rearranging the
computations in a way that some of them can be collapsed, e.g., two or more calls to <code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Allreduce.html#MPI_Allreduce">MPI_Allreduce</a>()</span></code> may be combined into one call.
The pipeline <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> methods have the label “Pipeline” in <a class="reference internal" href="#tab-kspdefaults"><span class="std std-ref">KSP Objects</span></a>.</p>
<p>Special configuration of MPI may be necessary for reductions to make asynchronous progress, which is important for
performance of pipelined methods. See <a class="reference internal" href="../faq/index.html#doc-faq-pipelined"><span class="std std-ref">What steps are necessary to make the pipelined solvers execute efficiently?</span></a> for details.</p>
</section>
<section id="other-ksp-options">
<h3>Other KSP Options<a class="headerlink" href="#other-ksp-options" title="Link to this heading">#</a></h3>
<p>To obtain the solution vector and right-hand side from a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>
context, one uses</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPGetSolution.html">KSPGetSolution</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">x</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPGetRhs.html">KSPGetRhs</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">rhs</span><span class="p">);</span>
</pre></div>
</div>
<p>During the iterative process the solution may not yet have been
calculated or it may be stored in a different location. To access the
approximate solution during the iterative process, one uses the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPBuildSolution.html">KSPBuildSolution</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>where the solution is returned in <code class="docutils notranslate"><span class="pre">v</span></code>. The user can optionally provide
a vector in <code class="docutils notranslate"><span class="pre">w</span></code> as the location to store the vector; however, if <code class="docutils notranslate"><span class="pre">w</span></code>
is <code class="docutils notranslate"><span class="pre">NULL</span></code>, space allocated by PETSc in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context is used.
One should not destroy this vector. For certain <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> methods (e.g.,
GMRES), the construction of the solution is expensive, while for many
others it doesn’t even require a vector copy.</p>
<p>Access to the residual is done in a similar way with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPBuildResidual.html">KSPBuildResidual</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">t</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>Again, for GMRES and certain other methods this is an expensive
operation.</p>
</section>
</section>
<section id="preconditioners">
<span id="sec-pc"></span><h2>Preconditioners<a class="headerlink" href="#preconditioners" title="Link to this heading">#</a></h2>
<p>As discussed in <a class="reference internal" href="#sec-ksppc"><span class="std std-ref">Preconditioning within KSP</span></a>, Krylov subspace methods
are typically used in conjunction with a preconditioner. To employ a
particular preconditioning method, the user can either select it from
the options database using input of the form <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">&lt;methodname&gt;</span></code>
or set the method with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCType.html">PCType</a></span><span class="w"> </span><span class="n">method</span><span class="p">);</span>
</pre></div>
</div>
<p>In <a class="reference internal" href="#tab-pcdefaults"><span class="std std-ref">PETSc Preconditioners (partial list)</span></a> we summarize the basic
preconditioning methods supported in PETSc. See the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCType.html">PCType</a></span></code> manual
page for a complete list.</p>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a></span></code> preconditioner allows users to provide their own
specific, application-provided custom preconditioner.</p>
<p>The direct
preconditioner, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLU.html">PCLU</a></span></code> , is, in fact, a direct solver for the linear
system that uses LU factorization. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLU.html">PCLU</a></span></code> is included as a
preconditioner so that PETSc has a consistent interface among direct and
iterative linear solvers.</p>
<p>PETSc provides several domain decomposition methods/preconditioners including
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCHPDDM.html">PCHPDDM</a></span></code>. In addition PETSc provides
multiple multigrid solvers/preconditioners including <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCHYPRE.html">PCHYPRE</a></span></code>,
and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCML.html">PCML</a></span></code>. See further discussion below.</p>
<table class="table" id="tab-pcdefaults">
<caption><span class="caption-number">Table 7 </span><span class="caption-text">PETSc Preconditioners (partial list)</span><a class="headerlink" href="#tab-pcdefaults" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Method</p></th>
<th class="head"><p>PCType</p></th>
<th class="head"><p>Options Database</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Jacobi</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCJACOBI.html">PCJACOBI</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">jacobi</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Block Jacobi</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBJACOBI.html">PCBJACOBI</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bjacobi</span></code></p></td>
</tr>
<tr class="row-even"><td><p>SOR (and SSOR)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSOR.html">PCSOR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">sor</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>SOR with Eisenstat trick</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCEISENSTAT.html">PCEISENSTAT</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">eisenstat</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Incomplete Cholesky</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCICC.html">PCICC</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">icc</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Incomplete LU</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCILU.html">PCILU</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ilu</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Additive Schwarz</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">asm</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Generalized Additive Schwarz</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">gasm</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Algebraic Multigrid</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">gamg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Balancing Domain Decomposition by Constraints</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bddc</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Linear solver</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ksp</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Combination of preconditioners</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCCOMPOSITE.html">PCCOMPOSITE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">composite</span></code></p></td>
</tr>
<tr class="row-even"><td><p>LU</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLU.html">PCLU</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Cholesky</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCCHOLESKY.html">PCCHOLESKY</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
</tr>
<tr class="row-even"><td><p>No preconditioning</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCNONE.html">PCNONE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">none</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Shell for user-defined <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">shell</span></code></p></td>
</tr>
</tbody>
</table>
<p>Each preconditioner may have associated with it a set of options, which
can be set with routines and options database commands provided for this
purpose. Such routine names and commands are all of the form
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a>&lt;TYPE&gt;&lt;Option&gt;</span></code> and <code class="docutils notranslate"><span class="pre">-pc_&lt;type&gt;_&lt;option&gt;</span> <span class="pre">[value]</span></code>. A complete
list can be found by consulting the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCType.html">PCType</a></span></code> manual page; we discuss
just a few in the sections below.</p>
<section id="ilu-and-icc-preconditioners">
<span id="sec-ilu-icc"></span><h3>ILU and ICC Preconditioners<a class="headerlink" href="#ilu-and-icc-preconditioners" title="Link to this heading">#</a></h3>
<p>Some of the options for ILU preconditioner are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCFactorSetLevels.html">PCFactorSetLevels</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">levels</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetReuseOrdering.html">PCFactorSetReuseOrdering</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flag</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetDropTolerance.html">PCFactorSetDropTolerance</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">dt</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">dtcol</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">dtcount</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetReuseFill.html">PCFactorSetReuseFill</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flag</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetUseInPlace.html">PCFactorSetUseInPlace</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetAllowDiagonalFill.html">PCFactorSetAllowDiagonalFill</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<p>When repeatedly solving linear systems with the same <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context,
one can reuse some information computed during the first linear solve.
In particular, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFactorSetReuseOrdering.html">PCFactorSetReuseOrdering</a>()</span></code> causes the ordering (for
example, set with <code class="docutils notranslate"><span class="pre">-pc_factor_mat_ordering_type</span></code> <code class="docutils notranslate"><span class="pre">order</span></code>) computed
in the first factorization to be reused for later factorizations.
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFactorSetUseInPlace.html">PCFactorSetUseInPlace</a>()</span></code> is often used with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBJACOBI.html">PCBJACOBI</a></span></code> when zero fill is used, since it reuses the matrix space
to store the incomplete factorization it saves memory and copying time.
Note that in-place factorization is not appropriate with any ordering
besides natural and cannot be used with the drop tolerance
factorization. These options may be set in the database with</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_levels</span> <span class="pre">&lt;levels&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_reuse_ordering</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_reuse_fill</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_in_place</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_nonzeros_along_diagonal</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_factor_diagonal_fill</span></code></p></li>
</ul>
<p>See <a class="reference internal" href="performance.html#sec-symbolfactor"><span class="std std-ref">Memory Allocation for Sparse Matrix Factorization</span></a> for information on
preallocation of memory for anticipated fill during factorization. By
alleviating the considerable overhead for dynamic memory allocation,
such tuning can significantly enhance performance.</p>
<p>PETSc supports incomplete factorization preconditioners
for several matrix types for sequential matrices (for example
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQAIJ.html">MATSEQAIJ</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQBAIJ.html">MATSEQBAIJ</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQSBAIJ.html">MATSEQSBAIJ</a></span></code>).</p>
</section>
<section id="sor-and-ssor-preconditioners">
<h3>SOR and SSOR Preconditioners<a class="headerlink" href="#sor-and-ssor-preconditioners" title="Link to this heading">#</a></h3>
<p>PETSc provides only a sequential SOR preconditioner; it can only be
used with sequential matrices or as the subblock preconditioner when
using block Jacobi or ASM preconditioning (see below).</p>
<p>The options for SOR preconditioning with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSOR.html">PCSOR</a></span></code> are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSORSetOmega.html">PCSORSetOmega</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">omega</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCSORSetIterations.html">PCSORSetIterations</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">its</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">lits</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCSORSetSymmetric.html">PCSORSetSymmetric</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatSORType.html">MatSORType</a></span><span class="w"> </span><span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>The first of these commands sets the relaxation factor for successive
over (under) relaxation. The second command sets the number of inner
iterations <code class="docutils notranslate"><span class="pre">its</span></code> and local iterations <code class="docutils notranslate"><span class="pre">lits</span></code> (the number of
smoothing sweeps on a process before doing a ghost point update from the
other processes) to use between steps of the Krylov space method. The
total number of SOR sweeps is given by <code class="docutils notranslate"><span class="pre">its*lits</span></code>. The third command
sets the kind of SOR sweep, where the argument <code class="docutils notranslate"><span class="pre">type</span></code> can be one of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_FORWARD_SWEEP</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_BACKWARD_SWEEP</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_SYMMETRIC_SWEEP</a></span></code>, the default being <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_FORWARD_SWEEP</a></span></code>.
Setting the type to be <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_SYMMETRIC_SWEEP</a></span></code> produces the SSOR method.
In addition, each process can locally and independently perform the
specified variant of SOR with the types <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_LOCAL_FORWARD_SWEEP</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_LOCAL_BACKWARD_SWEEP</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSORType.html">SOR_LOCAL_SYMMETRIC_SWEEP</a></span></code>. These
variants can also be set with the options <code class="docutils notranslate"><span class="pre">-pc_sor_omega</span> <span class="pre">&lt;omega&gt;</span></code>,
<code class="docutils notranslate"><span class="pre">-pc_sor_its</span> <span class="pre">&lt;its&gt;</span></code>, <code class="docutils notranslate"><span class="pre">-pc_sor_lits</span> <span class="pre">&lt;lits&gt;</span></code>, <code class="docutils notranslate"><span class="pre">-pc_sor_backward</span></code>,
<code class="docutils notranslate"><span class="pre">-pc_sor_symmetric</span></code>, <code class="docutils notranslate"><span class="pre">-pc_sor_local_forward</span></code>,
<code class="docutils notranslate"><span class="pre">-pc_sor_local_backward</span></code>, and <code class="docutils notranslate"><span class="pre">-pc_sor_local_symmetric</span></code>.</p>
<p>The Eisenstat trick <span id="id4">[<a class="reference internal" href="#id1243" title="S. Eisenstat. Efficient implementation of a class of CG methods. SIAM J. Sci. Stat. Comput., 2:1–4, 1981.">Eis81</a>]</span> for SSOR
preconditioning can be employed with the method <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCEISENSTAT.html">PCEISENSTAT</a></span></code>
(<code class="docutils notranslate"><span class="pre">-pc_type</span></code> <code class="docutils notranslate"><span class="pre">eisenstat</span></code>). By using both left and right
preconditioning of the linear system, this variant of SSOR requires
about half of the floating-point operations for conventional SSOR. The
option <code class="docutils notranslate"><span class="pre">-pc_eisenstat_no_diagonal_scaling</span></code> (or the routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCEisenstatSetNoDiagonalScaling.html">PCEisenstatSetNoDiagonalScaling</a>()</span></code>) turns off diagonal scaling in
conjunction with Eisenstat SSOR method, while the option
<code class="docutils notranslate"><span class="pre">-pc_eisenstat_omega</span> <span class="pre">&lt;omega&gt;</span></code> (or the routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCEisenstatSetOmega.html">PCEisenstatSetOmega</a>(<a href="../manualpages/PC/PC.html">PC</a></span> <span class="pre">pc,<a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span> <span class="pre">omega)</span></code>) sets the SSOR relaxation
coefficient, <code class="docutils notranslate"><span class="pre">omega</span></code>, as discussed above.</p>
</section>
<section id="lu-factorization">
<span id="sec-factorization"></span><h3>LU Factorization<a class="headerlink" href="#lu-factorization" title="Link to this heading">#</a></h3>
<p>The LU preconditioner provides several options. The first, given by the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCFactorSetUseInPlace.html">PCFactorSetUseInPlace</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">flg</span><span class="p">);</span>
</pre></div>
</div>
<p>causes the factorization to be performed in-place and hence destroys the
original matrix. The options database variant of this command is
<code class="docutils notranslate"><span class="pre">-pc_factor_in_place</span></code>. Another direct preconditioner option is
selecting the ordering of equations with the command
<code class="docutils notranslate"><span class="pre">-pc_factor_mat_ordering_type</span> <span class="pre">&lt;ordering&gt;</span></code>. The possible orderings are</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">MATORDERINGNATURAL</span></code> - Natural</p></li>
<li><p><code class="docutils notranslate"><span class="pre">MATORDERINGND</span></code> - Nested Dissection</p></li>
<li><p><code class="docutils notranslate"><span class="pre">MATORDERING1WD</span></code> - One-way Dissection</p></li>
<li><p><code class="docutils notranslate"><span class="pre">MATORDERINGRCM</span></code> - Reverse Cuthill-McKee</p></li>
<li><p><code class="docutils notranslate"><span class="pre">MATORDERINGQMD</span></code> - Quotient Minimum Degree</p></li>
</ul>
<p>These orderings can also be set through the options database by
specifying one of the following: <code class="docutils notranslate"><span class="pre">-pc_factor_mat_ordering_type</span></code>
<code class="docutils notranslate"><span class="pre">natural</span></code>, or <code class="docutils notranslate"><span class="pre">nd</span></code>, or <code class="docutils notranslate"><span class="pre">1wd</span></code>, or <code class="docutils notranslate"><span class="pre">rcm</span></code>, or <code class="docutils notranslate"><span class="pre">qmd</span></code>. In addition,
see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatGetOrdering.html">MatGetOrdering</a>()</span></code>, discussed in <a class="reference internal" href="advanced.html#sec-matfactor"><span class="std std-ref">Matrix Factorization</span></a>.</p>
<p>The sparse LU factorization provided in PETSc does not perform pivoting
for numerical stability (since they are designed to preserve nonzero
structure), and thus occasionally an LU factorization will fail with a
zero pivot when, in fact, the matrix is non-singular. The option
<code class="docutils notranslate"><span class="pre">-pc_factor_nonzeros_along_diagonal</span> <span class="pre">&lt;tol&gt;</span></code> will often help eliminate
the zero pivot, by preprocessing the column ordering to remove small
values from the diagonal. Here, <code class="docutils notranslate"><span class="pre">tol</span></code> is an optional tolerance to
decide if a value is nonzero; by default it is <code class="docutils notranslate"><span class="pre">1.e-10</span></code>.</p>
<p>In addition, <a class="reference internal" href="performance.html#sec-symbolfactor"><span class="std std-ref">Memory Allocation for Sparse Matrix Factorization</span></a> provides information
on preallocation of memory for anticipated fill during factorization.
Such tuning can significantly enhance performance, since it eliminates
the considerable overhead for dynamic memory allocation.</p>
</section>
<section id="block-jacobi-and-overlapping-additive-schwarz-preconditioners">
<span id="sec-bjacobi"></span><h3>Block Jacobi and Overlapping Additive Schwarz Preconditioners<a class="headerlink" href="#block-jacobi-and-overlapping-additive-schwarz-preconditioners" title="Link to this heading">#</a></h3>
<p>The block Jacobi and overlapping additive Schwarz (domain decomposition) methods in PETSc are
supported in parallel; however, only the uniprocess version of the block
Gauss-Seidel method is available. By default, the PETSc
implementations of these methods employ ILU(0) factorization on each
individual block (that is, the default solver on each subblock is
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCType.html">PCType</a>=<a href="../manualpages/PC/PCILU.html">PCILU</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a>=<a href="../manualpages/KSP/KSPPREONLY.html">KSPPREONLY</a></span></code> (or equivalently <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a>=<a href="../manualpages/KSP/KSPNONE.html">KSPNONE</a></span></code>); the user can set alternative
linear solvers via the options <code class="docutils notranslate"><span class="pre">-sub_ksp_type</span></code> and <code class="docutils notranslate"><span class="pre">-sub_pc_type</span></code>.
In fact, all of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> options can be applied to the
subproblems by inserting the prefix <code class="docutils notranslate"><span class="pre">-sub_</span></code> at the beginning of the
option name. These options database commands set the particular options
for <em>all</em> of the blocks within the global problem. In addition, the
routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCBJacobiGetSubKSP.html">PCBJacobiGetSubKSP</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">n_local</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">first_local</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">**</span><span class="n">subksp</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCASMGetSubKSP.html">PCASMGetSubKSP</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">n_local</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">first_local</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">**</span><span class="n">subksp</span><span class="p">);</span>
</pre></div>
</div>
<p>extract the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> context for each local block. The argument
<code class="docutils notranslate"><span class="pre">n_local</span></code> is the number of blocks on the calling process, and
<code class="docutils notranslate"><span class="pre">first_local</span></code> indicates the global number of the first block on the
process. The blocks are numbered successively by processes from zero
through <span class="math">\(b_g-1\)</span>, where <span class="math">\(b_g\)</span> is the number of global blocks.
The array of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> contexts for the local blocks is given by
<code class="docutils notranslate"><span class="pre">subksp</span></code>. This mechanism enables the user to set different solvers for
the various blocks. To set the appropriate data structures, the user
<em>must</em> explicitly call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetUp.html">KSPSetUp</a>()</span></code> before calling
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBJacobiGetSubKSP.html">PCBJacobiGetSubKSP</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMGetSubKSP.html">PCASMGetSubKSP</a>(</span></code>). For further details,
see
<a href="../src/ksp/ksp/tutorials/ex7.c.html">KSP Tutorial ex7</a>
or
<a href="../src/ksp/ksp/tutorials/ex8.c.html">KSP Tutorial ex8</a>.</p>
<p>The block Jacobi, block Gauss-Seidel, and additive Schwarz
preconditioners allow the user to set the number of blocks into which
the problem is divided. The options database commands to set this value
are <code class="docutils notranslate"><span class="pre">-pc_bjacobi_blocks</span></code> <code class="docutils notranslate"><span class="pre">n</span></code> and <code class="docutils notranslate"><span class="pre">-pc_bgs_blocks</span></code> <code class="docutils notranslate"><span class="pre">n</span></code>, and,
within a program, the corresponding routines are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCBJacobiSetTotalBlocks.html">PCBJacobiSetTotalBlocks</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">blocks</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">size</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCASMSetTotalSubdomains.html">PCASMSetTotalSubdomains</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">is</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">islocal</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCASMSetType.html">PCASMSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCASMType.html">PCASMType</a></span><span class="w"> </span><span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>The optional argument <code class="docutils notranslate"><span class="pre">size</span></code> is an array indicating the size of each
block. Currently, for certain parallel matrix formats, only a single
block per process is supported. However, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIAIJ.html">MATMPIAIJ</a></span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIBAIJ.html">MATMPIBAIJ</a></span></code> formats support the use of general blocks as long as no
blocks are shared among processes. The <code class="docutils notranslate"><span class="pre">is</span></code> argument contains the
index sets that define the subdomains.</p>
<p>The object <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PCASMType</a></span></code> is one of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_BASIC</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_INTERPOLATE</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_RESTRICT</a></span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_NONE</a></span></code> and may
also be set with the options database <code class="docutils notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils notranslate"><span class="pre">[basic</span></code>,
<code class="docutils notranslate"><span class="pre">interpolate</span></code>, <code class="docutils notranslate"><span class="pre">restrict</span></code>, <code class="docutils notranslate"><span class="pre">none]</span></code>. The type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_BASIC</a></span></code> (or
<code class="docutils notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils notranslate"><span class="pre">basic</span></code>) corresponds to the standard additive Schwarz
method that uses the full restriction and interpolation operators. The
type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_RESTRICT</a></span></code> (or <code class="docutils notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils notranslate"><span class="pre">restrict</span></code>) uses a full
restriction operator, but during the interpolation process ignores the
off-process values. Similarly, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_INTERPOLATE</a></span></code> (or
<code class="docutils notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils notranslate"><span class="pre">interpolate</span></code>) uses a limited restriction process in
conjunction with a full interpolation, while <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_NONE</a></span></code> (or
<code class="docutils notranslate"><span class="pre">-pc_asm_type</span></code> <code class="docutils notranslate"><span class="pre">none</span></code>) ignores off-process values for both
restriction and interpolation. The ASM types with limited restriction or
interpolation were suggested by Xiao-Chuan Cai and Marcus Sarkis
<span id="id5">[<a class="reference internal" href="../manualpages/PC/PCGASMType.html#id1185" title="X.-C. Cai and M. Sarkis. A restricted additive Schwarz preconditioner for general sparse linear systems. SIAM J. Scientific Computing, 21:792-797, 1999.">CS99</a>]</span>. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_RESTRICT</a></span></code> is the PETSc default, as
it saves substantial communication and for many problems has the added
benefit of requiring fewer iterations for convergence than the standard
additive Schwarz method.</p>
<p>The user can also set the number of blocks and sizes on a per-process
basis with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCBJacobiSetLocalBlocks.html">PCBJacobiSetLocalBlocks</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">blocks</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">size</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCASMSetLocalSubdomains.html">PCASMSetLocalSubdomains</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">is</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">islocal</span><span class="p">);</span>
</pre></div>
</div>
<p>For the ASM preconditioner one can use the following command to set the
overlap to compute in constructing the subdomains.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCASMSetOverlap.html">PCASMSetOverlap</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">overlap</span><span class="p">);</span>
</pre></div>
</div>
<p>The overlap defaults to 1, so if one desires that no additional overlap
be computed beyond what may have been set with a call to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetTotalSubdomains.html">PCASMSetTotalSubdomains</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetLocalSubdomains.html">PCASMSetLocalSubdomains</a>()</span></code>, then
<code class="docutils notranslate"><span class="pre">overlap</span></code> must be set to be 0. In particular, if one does <em>not</em>
explicitly set the subdomains in an application code, then all overlap
would be computed internally by PETSc, and using an overlap of 0 would
result in an ASM variant that is equivalent to the block Jacobi
preconditioner. Note that one can define initial index sets <code class="docutils notranslate"><span class="pre">is</span></code> with
<em>any</em> overlap via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetTotalSubdomains.html">PCASMSetTotalSubdomains</a>()</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetLocalSubdomains.html">PCASMSetLocalSubdomains</a>()</span></code>; the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetOverlap.html">PCASMSetOverlap</a>()</span></code> merely
allows PETSc to extend that overlap further if desired.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> is a generalization of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code> that allows
the user to specify subdomains that span multiple MPI processes. This can be
useful for problems where small subdomains result in poor convergence.
To be effective, the multi-processor subproblems must be solved using a
sufficiently strong subsolver, such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLU.html">PCLU</a></span></code>, for which <code class="docutils notranslate"><span class="pre">SuperLU_DIST</span></code> or a
similar parallel direct solver could be used; other choices may include
a multigrid solver on the subdomains.</p>
<p>The interface for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> is similar to that of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>. In
particular, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMType.html">PCGASMType</a></span></code> is one of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMType.html">PC_GASM_BASIC</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMType.html">PC_GASM_INTERPOLATE</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMType.html">PC_GASM_RESTRICT</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMType.html">PC_GASM_NONE</a></span></code>. These
options have the same meaning as with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code> and may also be set with
the options database <code class="docutils notranslate"><span class="pre">-pc_gasm_type</span></code> <code class="docutils notranslate"><span class="pre">[basic</span></code>, <code class="docutils notranslate"><span class="pre">interpolate</span></code>,
<code class="docutils notranslate"><span class="pre">restrict</span></code>, <code class="docutils notranslate"><span class="pre">none]</span></code>.</p>
<p>Unlike <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>, however, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> allows the user to define
subdomains that span multiple MPI processes. The simplest way to do this is
using a call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetTotalSubdomains.html">PCGASMSetTotalSubdomains</a>(<a href="../manualpages/PC/PC.html">PC</a></span> <span class="pre">pc,<a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">N)</span></code> with
the total number of subdomains <code class="docutils notranslate"><span class="pre">N</span></code> that is smaller than the MPI
communicator <code class="docutils notranslate"><span class="pre">size</span></code>. In this case <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> will coalesce <code class="docutils notranslate"><span class="pre">size/N</span></code>
consecutive single-rank subdomains into a single multi-rank subdomain.
The single-rank subdomains contain the degrees of freedom corresponding
to the locally-owned rows of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> preconditioning matrix –
these are the subdomains <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> use by default.</p>
<p>Each of the multirank subdomain subproblems is defined on the
subcommunicator that contains the coalesced <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> processes. In general
this might not result in a very good subproblem if the single-rank
problems corresponding to the coalesced processes are not very strongly
connected. In the future this will be addressed with a hierarchical
partitioner that generates well-connected coarse subdomains first before
subpartitioning them into the single-rank subdomains.</p>
<p>In the meantime the user can provide his or her own multi-rank
subdomains by calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetSubdomains.html">PCGASMSetSubdomains</a>(<a href="../manualpages/PC/PC.html">PC</a>,<a href="../manualpages/IS/IS.html">IS</a>[],<a href="../manualpages/IS/IS.html">IS</a>[])</span></code> where each
of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code> objects on the list defines the inner (without the
overlap) or the outer (including the overlap) subdomain on the
subcommunicator of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code> object. A helper subroutine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMCreateSubdomains2D.html">PCGASMCreateSubdomains2D</a>()</span></code> is similar to PCASM’s but is capable of
constructing multi-rank subdomains that can be then used with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetSubdomains.html">PCGASMSetSubdomains</a>()</span></code>. An alternative way of creating multi-rank
subdomains is by using the underlying <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object, if it is capable of
generating such decompositions via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateDomainDecomposition.html">DMCreateDomainDecomposition</a>()</span></code>.
Ordinarily the decomposition specified by the user via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetSubdomains.html">PCGASMSetSubdomains</a>()</span></code> takes precedence, unless
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetUseDMSubdomains.html">PCGASMSetUseDMSubdomains</a>()</span></code> instructs <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> to prefer
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>-created decompositions.</p>
<p>Currently there is no support for increasing the overlap of multi-rank
subdomains via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMSetOverlap.html">PCGASMSetOverlap</a>()</span></code> – this functionality works only
for subdomains that fit within a single MPI process, exactly as in
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>.</p>
<p>Examples of the described <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASM.html">PCGASM</a></span></code> usage can be found in
<a href="../src/ksp/ksp/tutorials/ex62.c.html">KSP Tutorial ex62</a>.
In particular, <code class="docutils notranslate"><span class="pre">runex62_superlu_dist</span></code> illustrates the use of
<code class="docutils notranslate"><span class="pre">SuperLU_DIST</span></code> as the subdomain solver on coalesced multi-rank
subdomains. The <code class="docutils notranslate"><span class="pre">runex62_2D_*</span></code> examples illustrate the use of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGASMCreateSubdomains2D.html">PCGASMCreateSubdomains2D</a>()</span></code>.</p>
</section>
<section id="algebraic-multigrid-amg-preconditioners">
<span id="sec-amg"></span><h3>Algebraic Multigrid (AMG) Preconditioners<a class="headerlink" href="#algebraic-multigrid-amg-preconditioners" title="Link to this heading">#</a></h3>
<p>PETSc has a native algebraic multigrid preconditioner <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> –
<em>gamg</em> – and interfaces to three external AMG packages: <em>hypre</em>, <em>ML</em>
and <em>AMGx</em> (CUDA platforms only) that can be downloaded in the
configuration phase (e.g., <code class="docutils notranslate"><span class="pre">--download-hypre</span></code> ) and used by
specifying that command line parameter (e.g., <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span></code>).
<em>Hypre</em> is relatively monolithic in that a PETSc matrix is converted into a hypre
matrix, and then <em>hypre</em> is called to solve the entire problem. <em>ML</em> is more
modular because PETSc only has <em>ML</em> generate the coarse grid spaces
(columns of the prolongation operator), which is the core of an AMG method,
and then constructs a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code> with Galerkin coarse grid operator
construction. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> is designed from the beginning to be modular, to
allow for new components to be added easily and also populates a
multigrid preconditioner <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code> so generic multigrid parameters are
used (see <a class="reference internal" href="#sec-mg"><span class="std std-ref">Multigrid Preconditioners</span></a>). PETSc provides a fully supported (smoothed) aggregation AMG, but supports the addition of new methods
(<code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">gamg</span> <span class="pre">-pc_gamg_type</span> <span class="pre">agg</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetType.html">PCSetType</a>(pc,<a href="../manualpages/PC/PCGAMG.html">PCGAMG</a>)</span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetType.html">PCGAMGSetType</a>(pc,</span> <span class="pre"><a href="../manualpages/PC/PCGAMGAGG.html">PCGAMGAGG</a>)</span></code>. Examples of extension are reference implementations of
a classical AMG method (<code class="docutils notranslate"><span class="pre">-pc_gamg_type</span> <span class="pre">classical</span></code>), a (2D) hybrid geometric
AMG method (<code class="docutils notranslate"><span class="pre">-pc_gamg_type</span> <span class="pre">geo</span></code>) that are not supported. A 2.5D AMG method DofColumns
<span id="id6">[<a class="reference internal" href="#id2029" title="Tobin Isaac, Georg Stadler, and Omar Ghattas. Solution of nonlinear Stokes equations discretized by high-order finite elements on nonconforming and anisotropic meshes, with application to ice sheet dynamics. SIAM Journal on Scientific Computing, 37(6):804–833, 2015. doi:10.1137/140974407.">ISG15</a>]</span> supports 2D coarsenings extruded in the third dimension. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> does require the use
of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> matrices. For instance, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> matrices are not supported. One
can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> instead of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> without changing any code other than the
constructor (or the <code class="docutils notranslate"><span class="pre">-mat_type</span></code> from the command line). For instance,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesBlocked.html">MatSetValuesBlocked</a></span></code> works with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATAIJ.html">MATAIJ</a></span></code> matrices.</p>
<p><strong>Important parameters for PCGAMGAGG</strong></p>
<ul>
<li><p>Control the generation of the coarse grid</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_aggressive_coarsening</span></code> &lt;n:int:1&gt; Use aggressive coarsening on the finest n levels to construct the coarser mesh.
See <code class="docutils notranslate"><span class="pre">PCGAMGAGGSetNSmooths()</span></code>. The larger value produces a faster preconditioner to create and solve, but the convergence may be slower.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_low_memory_threshold_filter</span></code> &lt;bool:false&gt; Filter small matrix entries before coarsening the mesh.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetLowMemoryFilter.html">PCGAMGSetLowMemoryFilter</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_threshold</span></code> &lt;tol:real:0.0&gt; The threshold of small values to drop when <code class="docutils notranslate"><span class="pre">-pc_gamg_low_memory_threshold_filter</span></code> is used. A
negative value means keeping even the locations with 0.0. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetThreshold.html">PCGAMGSetThreshold</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_threshold_scale</span></code> &lt;v&gt;:real:1.0&gt; Set a scale factor applied to each coarser level when <code class="docutils notranslate"><span class="pre">-pc_gamg_low_memory_threshold_filter</span></code> is used.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetThresholdScale.html">PCGAMGSetThresholdScale</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_mat_coarsen_type</span></code> &lt;mis|hem|misk:misk&gt; Algorithm used to coarsen the matrix graph. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatCoarsenSetType.html">MatCoarsenSetType</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_mat_coarsen_max_it</span></code> &lt;it:int:4&gt; Maximum HEM iterations to use. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatCoarsenSetMaximumIterations.html">MatCoarsenSetMaximumIterations</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_aggressive_mis_k</span></code> &lt;k:int:2&gt; k distance in MIS coarsening (&gt;2 is ‘aggressive’) to use in coarsening.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGMISkSetAggressive.html">PCGAMGMISkSetAggressive</a>()</span></code>. The larger value produces a preconditioner that is faster to create and solve with but the convergence may be slower.
This option and the previous option work to determine how aggressively the grids are coarsened.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_mis_k_minimum_degree_ordering</span></code> &lt;bool:true&gt; Use a minimum degree ordering in the greedy MIS algorithm used to coarsen.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGMISkSetMinDegreeOrdering.html">PCGAMGMISkSetMinDegreeOrdering</a>()</span></code></p></li>
</ul>
</div></blockquote>
</li>
<li><p>Control the generation of the prolongation for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGAGG.html">PCGAMGAGG</a></span></code></p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_agg_nsmooths</span></code> &lt;n:int:1&gt; Number of smoothing steps to be used in constructing the prolongation. For symmetric problems,
generally, one or more is best. For some strongly nonsymmetric problems, 0 may be best. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetNSmooths.html">PCGAMGSetNSmooths</a>()</span></code>.</p></li>
</ul>
</div></blockquote>
</li>
<li><p>Control the amount of parallelism on the levels</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_process_eq_limit</span></code> &lt;n:int:50&gt; Sets the minimum number of equations allowed per process when coarsening (otherwise, fewer MPI processes
are used for the coarser mesh). A larger value will cause the coarser problems to be run on fewer MPI processes, resulting
in less communication and possibly a faster time to solution. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetProcEqLim.html">PCGAMGSetProcEqLim</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_rank_reduction_factors</span></code> &lt;rn,rn-1,…,r1:int&gt; Set a schedule for MPI rank reduction on coarse grids. <code class="docutils notranslate"><span class="pre">See</span> <span class="pre"><a href="../manualpages/PC/PCGAMGSetRankReductionFactors.html">PCGAMGSetRankReductionFactors</a>()</span></code>
This overrides the lessening of processes that would arise from <code class="docutils notranslate"><span class="pre">-pc_gamg_process_eq_limit</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_repartition</span></code> &lt;bool:false&gt; Run a partitioner on each coarser mesh generated rather than using the default partition arising from the
finer mesh. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetRepartition.html">PCGAMGSetRepartition</a>()</span></code>. This increases the preconditioner setup time but will result in less time per
iteration of the solver.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_parallel_coarse_grid_solver</span></code> &lt;bool:false&gt; Allow the coarse grid solve to run in parallel, depending on the value of <code class="docutils notranslate"><span class="pre">-pc_gamg_coarse_eq_limit</span></code>.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetParallelCoarseGridSolve.html">PCGAMGSetParallelCoarseGridSolve</a>()</span></code>. If the coarse grid problem is large then this can
improve the time to solution.</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_coarse_eq_limit</span></code> &lt;n:int:50&gt; Sets the minimum number of equations allowed per process on the coarsest level when coarsening
(otherwise fewer MPI processes will be used). A larger value will cause the coarse problems to be run on fewer MPI processes.
This only applies if <code class="docutils notranslate"><span class="pre">-pc_gamg_parallel_coarse_grid_solver</span></code> is set to true. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetCoarseEqLim.html">PCGAMGSetCoarseEqLim</a>()</span></code>.</p></li>
</ul>
</li>
</ul>
</div></blockquote>
</li>
<li><p>Control the smoothers</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_mg_levels</span></code> &lt;n:int&gt; Set the maximum number of levels to use.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_ksp_type</span></code> &lt;KSPType:chebyshev&gt; If <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCHEBYSHEV.html">KSPCHEBYSHEV</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPRICHARDSON.html">KSPRICHARDSON</a></span></code> is not used, then the Krylov
method for the entire multigrid solve has to be a flexible method such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFGMRES.html">KSPFGMRES</a></span></code>. Generally, the
stronger the Krylov method the faster the convergence, but with more cost per iteration. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_ksp_max_it</span></code> &lt;its:int:2&gt; Sets the number of iterations to run the smoother on each level. Generally, the more iterations
, the faster the convergence, but with more cost per multigrid iteration. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGSetNumberSmooth.html">PCMGSetNumberSmooth</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_ksp_xxx</span></code> Sets options for the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> in the smoother on the levels.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_pc_type</span></code> &lt;PCType:jacobi&gt; Sets the smoother to use on each level. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetType.html">PCSetType</a>()</span></code>. Generally, the
stronger the preconditioner the faster the convergence, but with more cost per iteration.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_pc_xxx</span></code> Sets options for the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> in the smoother on the levels.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_coarse_ksp_type</span></code> &lt;KSPType:none&gt; Sets the solver <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span></code> to use on the coarsest level.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_coarse_pc_type</span></code> &lt;PCType:lu&gt; Sets the solver <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCType.html">PCType</a></span></code> to use on the coarsest level.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_gamg_asm_use_agg</span></code> &lt;bool:false&gt; Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code> as the smoother on each level with the aggregates defined by the coarsening process are
the subdomains. This option automatically switches the smoother on the levels to be <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASM.html">PCASM</a></span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mg_levels_pc_asm_overlap</span></code> &lt;n:int:0&gt; Use non-zero overlap with <code class="docutils notranslate"><span class="pre">-pc_gamg_asm_use_agg</span></code>. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMSetOverlap.html">PCASMSetOverlap</a>()</span></code>.</p></li>
</ul>
</div></blockquote>
</li>
<li><p>Control the multigrid algorithm</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_mg_type</span></code> &lt;additive|multiplicative|full|kaskade:multiplicative&gt; The type of multigrid to use. Usually, multiplicative is the fastest.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_mg_cycle_type</span></code> &lt;v|w:v&gt; Use V- or W-cycle with <code class="docutils notranslate"><span class="pre">-pc_mg_type</span></code> <code class="docutils notranslate"><span class="pre">multiplicative</span></code></p></li>
</ul>
</div></blockquote>
</li>
</ul>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> provides unsmoothed aggregation (<code class="docutils notranslate"><span class="pre">-pc_gamg_agg_nsmooths</span> <span class="pre">0</span></code>) and
smoothed aggregation (<code class="docutils notranslate"><span class="pre">-pc_gamg_agg_nsmooths</span> <span class="pre">1</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetNSmooths.html">PCGAMGSetNSmooths</a>(pc,1)</span></code>). Smoothed aggregation (SA), <span id="id7">[<a class="reference internal" href="../manualpages/PC/PCGAMGAGG.html#id1714" title="P. Vaněk, J. Mandel, and M. Brezina. Algebraic multigrid by smoothed aggregation for second and fourth order elliptic problems. Computing, 56(3):179–196, 1996.">VanvekMB96</a>]</span>, <span id="id8">[<a class="reference internal" href="../manualpages/PC/PCGAMGAGG.html#id1715" title="P. Vaněek, M. Brezina, and J. Mandel. Convergence of algebraic multigrid based on smoothed aggregation. Numerische Mathematik, 88(3):559–579, 2001.">VanveekBM01</a>]</span>, is recommended
for symmetric positive definite systems. Unsmoothed aggregation can be
useful for asymmetric problems and problems where the highest eigenestimates are problematic. If poor convergence rates are observed using
the smoothed version, one can test unsmoothed aggregation.</p>
<p><strong>Eigenvalue estimates:</strong> The parameters for the KSP eigen estimator,
used for SA, can be set with <code class="docutils notranslate"><span class="pre">-pc_gamg_esteig_ksp_max_it</span></code> and
<code class="docutils notranslate"><span class="pre">-pc_gamg_esteig_ksp_type</span></code>. For example, CG generally converges to the
highest eigenvalue faster than GMRES (the default for KSP) if your problem
is symmetric positive definite. One can specify CG with
<code class="docutils notranslate"><span class="pre">-pc_gamg_esteig_ksp_type</span> <span class="pre">cg</span></code>. The default for
<code class="docutils notranslate"><span class="pre">-pc_gamg_esteig_ksp_max_it</span></code> is 10, which we have found is pretty safe
with a (default) safety factor of 1.1. One can specify the range of real
eigenvalues in the same way as with Chebyshev KSP solvers
(smoothers), with <code class="docutils notranslate"><span class="pre">-pc_gamg_eigenvalues</span> <span class="pre">&lt;emin,emax&gt;</span></code>. GAMG sets the MG
smoother type to chebyshev by default. By default, GAMG uses its eigen
estimate, if it has one, for Chebyshev smoothers if the smoother uses
Jacobi preconditioning. This can be overridden with
<code class="docutils notranslate"><span class="pre">-pc_gamg_use_sa_esteig</span>&#160; <span class="pre">&lt;true,false&gt;</span></code>.</p>
<p>AMG methods require knowledge of the number of degrees of freedom per
vertex; the default is one (a scalar problem). Vector problems like
elasticity should set the block size of the matrix appropriately with
<code class="docutils notranslate"><span class="pre">-mat_block_size</span> <span class="pre">bs</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetBlockSize.html">MatSetBlockSize</a>(mat,bs)</span></code>. Equations must be
ordered in “vertex-major” ordering (e.g.,
<span class="math">\(x_1,y_1,z_1,x_2,y_2,...\)</span>).</p>
<p><strong>Near null space:</strong> Smoothed aggregation requires an explicit
representation of the (near) null space of the operator for optimal
performance. One can provide an orthonormal set of null space vectors
with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNearNullSpace.html">MatSetNearNullSpace</a>()</span></code>. The vector of all ones is the default
for each variable given by the block size (e.g., the translational rigid
body modes). For elasticity, where rotational rigid body modes are
required to complete the near null-space you can use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpaceCreateRigidBody.html">MatNullSpaceCreateRigidBody</a>()</span></code> to create the null space vectors and
then <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNearNullSpace.html">MatSetNearNullSpace</a>()</span></code>.</p>
<p><strong>Coarse grid data model:</strong> The GAMG framework provides for reducing the
number of active processes on coarse grids to reduce communication costs
when there is not enough parallelism to keep relative communication
costs down. Most AMG solvers reduce to just one active process on the
coarsest grid (the PETSc MG framework also supports redundantly solving
the coarse grid on all processes to reduce communication
costs potentially). However, this forcing to one process can be overridden if one
wishes to use a parallel coarse grid solver. GAMG generalizes this by
reducing the active number of processes on other coarse grids.
GAMG will select the number of active processors by fitting the desired
number of equations per process (set with
<code class="docutils notranslate"><span class="pre">-pc_gamg_process_eq_limit</span> <span class="pre">&lt;50&gt;,</span></code>) at each level given that size of
each level. If <span class="math">\(P_i &lt; P\)</span> processors are desired on a level
<span class="math">\(i\)</span>, then the first <span class="math">\(P_i\)</span> processes are populated with the grid
and the remaining are empty on that grid. One can, and probably should,
repartition the coarse grids with <code class="docutils notranslate"><span class="pre">-pc_gamg_repartition</span> <span class="pre">&lt;true&gt;</span></code>,
otherwise an integer process reduction factor (<span class="math">\(q\)</span>) is selected
and the equations on the first <span class="math">\(q\)</span> processes are moved to process
0, and so on. As mentioned, multigrid generally coarsens the problem
until it is small enough to be solved with an exact solver (e.g., LU or
SVD) in a relatively short time. GAMG will stop coarsening when the
number of the equation on a grid falls below the threshold given by
<code class="docutils notranslate"><span class="pre">-pc_gamg_coarse_eq_limit</span> <span class="pre">&lt;50&gt;,</span></code>.</p>
<p><strong>Coarse grid parameters:</strong> There are several options to provide
parameters to the coarsening algorithm and parallel data layout. Run a
code using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> with <code class="docutils notranslate"><span class="pre">-help</span></code> to get a full listing of GAMG
parameters with short descriptions. The rate of coarsening is
critical in AMG performance – too slow coarsening will result in an
overly expensive solver per iteration and too fast coarsening will
result in decrease in the convergence rate. <code class="docutils notranslate"><span class="pre">-pc_gamg_threshold</span> <span class="pre">&lt;-1&gt;</span></code>
and <code class="docutils notranslate"><span class="pre">-pc_gamg_aggressive_coarsening</span> <span class="pre">&lt;N&gt;</span></code> are the primary parameters that
control coarsening rates, which is very important for AMG performance. A
greedy maximal independent set (MIS) algorithm is used in coarsening.
Squaring the graph implements MIS-2; the root vertex in an
aggregate is more than two edges away from another root vertex instead
of more than one in MIS. The threshold parameter sets a normalized
threshold for which edges are removed from the MIS graph, thereby
coarsening slower. Zero will keep all non-zero edges, a negative number
will keep zero edges, and a positive number will drop small edges. Typical
finite threshold values are in the range of <span class="math">\(0.01 - 0.05\)</span>. There
are additional parameters for changing the weights on coarse grids.</p>
<p>The parallel MIS algorithms require symmetric weights/matrices. Thus <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code>
will automatically make the graph symmetric if it is not symmetric. Since this
has additional cost, users should indicate the symmetry of the matrices they
provide by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatSetOption.html">MatSetOption</a></span><span class="p">(</span><span class="n">mat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatOption.html">MAT_SYMMETRIC</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="w"> </span><span class="p">(</span><span class="n">or</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">))</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatSetOption.html">MatSetOption</a></span><span class="p">(</span><span class="n">mat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatOption.html">MAT_STRUCTURALLY_SYMMETRIC</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="w"> </span><span class="p">(</span><span class="n">or</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">)).</span>
</pre></div>
</div>
<p>If they know that the matrix will always have symmetry despite future changes
to the matrix (with, for example, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a>()</span></code>) then they should also call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatSetOption.html">MatSetOption</a></span><span class="p">(</span><span class="n">mat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatOption.html">MAT_SYMMETRY_ETERNAL</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="w"> </span><span class="p">(</span><span class="n">or</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">))</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatSetOption.html">MatSetOption</a></span><span class="p">(</span><span class="n">mat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatOption.html">MAT_STRUCTURAL_SYMMETRY_ETERNAL</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="w"> </span><span class="p">(</span><span class="n">or</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">)).</span>
</pre></div>
</div>
<p>Using this information allows the algorithm to skip unnecessary computations.</p>
<p><strong>Troubleshooting algebraic multigrid methods:</strong> If <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code>, <em>ML</em>, <em>AMGx</em> or
<em>hypre</em> does not perform well; the first thing to try is one of the other
methods. Often, the default parameters or just the strengths of different
algorithms can fix performance problems or provide useful information to
guide further debugging. There are several sources of poor performance
of AMG solvers and often special purpose methods must be developed to
achieve the full potential of multigrid. To name just a few sources of
performance degradation that may not be fixed with parameters in PETSc
currently: non-elliptic operators, curl/curl operators, highly stretched
grids or highly anisotropic problems, large jumps in material
coefficients with complex geometry (AMG is particularly well suited to
jumps in coefficients, but it is not a perfect solution), highly
incompressible elasticity, not to mention ill-posed problems and many
others. For Grad-Div and Curl-Curl operators, you may want to try the
Auxiliary-space Maxwell Solver (AMS,
<code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">ams</span></code>) or the Auxiliary-space Divergence
Solver (ADS, <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">hypre</span> <span class="pre">-pc_hypre_type</span> <span class="pre">ads</span></code>) solvers. These
solvers need some additional information on the underlying mesh;
specifically, AMS needs the discrete gradient operator, which can be
specified via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCHYPRESetDiscreteGradient.html">PCHYPRESetDiscreteGradient</a>()</span></code>. In addition to the
discrete gradient, ADS also needs the specification of the discrete curl
operator, which can be set using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCHYPRESetDiscreteCurl.html">PCHYPRESetDiscreteCurl</a>()</span></code>.</p>
<p><strong>I am converging slowly, what do I do?</strong> AMG methods are sensitive to
coarsening rates and methods; for GAMG use <code class="docutils notranslate"><span class="pre">-pc_gamg_threshold</span> <span class="pre">&lt;x&gt;</span></code>
or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetThreshold.html">PCGAMGSetThreshold</a>()</span></code> to regulate coarsening rates; higher values decrease
coarsening rate. Squaring the graph is the second mechanism for
increasing the coarsening rate. Use <code class="docutils notranslate"><span class="pre">-pc_gamg_aggressive_coarsening</span> <span class="pre">&lt;N&gt;</span></code>, or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMGSetAggressiveLevels.html">PCGAMGSetAggressiveLevels</a>(pc,N)</span></code>, to aggressive ly coarsen (MIS-2) the graph on the finest N
levels. A high threshold (e.g., <span class="math">\(x=0.08\)</span>) will result in an
expensive but potentially powerful preconditioner, and a low threshold
(e.g., <span class="math">\(x=0.0\)</span>) will result in faster coarsening, fewer levels,
cheaper solves, and generally worse convergence rates.</p>
<p>One can run with <code class="docutils notranslate"><span class="pre">-info</span> <span class="pre">:pc</span></code> and grep for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> to get statistics on
each level, which can be used to see if you are coarsening at an
appropriate rate. With smoothed aggregation, you generally want to coarse
at about a rate of 3:1 in each dimension. Coarsening too slowly will
result in large numbers of non-zeros per row on coarse grids (this is
reported). The number of non-zeros can go up very high, say about 300
(times the degrees of freedom per vertex) on a 3D hex mesh. One can also
look at the grid complexity, which is also reported (the ratio of the
total number of matrix entries for all levels to the number of matrix
entries on the fine level). Grid complexity should be well under 2.0 and
preferably around <span class="math">\(1.3\)</span> or lower. If convergence is poor and the
Galerkin coarse grid construction is much smaller than the time for each
solve, one can safely decrease the coarsening rate.
<code class="docutils notranslate"><span class="pre">-pc_gamg_threshold</span></code> <span class="math">\(-1.0\)</span> is the simplest and most robust
option and is recommended if poor convergence rates are observed, at
least until the source of the problem is discovered. In conclusion, decreasing the coarsening rate (increasing the
threshold) should be tried if convergence is slow.</p>
<p><strong>A note on Chebyshev smoothers.</strong> Chebyshev solvers are attractive as
multigrid smoothers because they can target a specific interval of the
spectrum, which is the purpose of a smoother. The spectral bounds for
Chebyshev solvers are simple to compute because they rely on the highest
eigenvalue of your (diagonally preconditioned) operator, which is
conceptually simple to compute. However, if this highest eigenvalue
estimate is not accurate (too low), the solvers can fail with an
indefinite preconditioner message. One can run with <code class="docutils notranslate"><span class="pre">-info</span></code> and grep
for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGAMG.html">PCGAMG</a></span></code> to get these estimates or use <code class="docutils notranslate"><span class="pre">-ksp_view</span></code>. These highest
eigenvalues are generally between 1.5-3.0. For symmetric positive
definite systems, CG is a better eigenvalue estimator
<code class="docutils notranslate"><span class="pre">-mg_levels_esteig_ksp_type</span> <span class="pre">cg</span></code>. Bad Eigen estimates often cause indefinite matrix messages. Explicitly damped Jacobi or Krylov
smoothers can provide an alternative to Chebyshev, and <em>hypre</em> has
alternative smoothers.</p>
<p><strong>Now, am I solving alright? Can I expect better?</strong> If you find that you
are getting nearly one digit in reduction of the residual per iteration
and are using a modest number of point smoothing steps (e.g., 1-4
iterations of SOR), then you may be fairly close to textbook multigrid
efficiency. However, you also need to check the setup costs. This can be
determined by running with <code class="docutils notranslate"><span class="pre">-log_view</span></code> and check that the time for the
Galerkin coarse grid construction (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatPtAP.html">MatPtAP</a>()</span></code>) is not (much) more than
the time spent in each solve (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>). If the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatPtAP.html">MatPtAP</a>()</span></code> time is
too large, then one can increase the coarsening rate by decreasing the
threshold and using aggressive coarsening
(<code class="docutils notranslate"><span class="pre">-pc_gamg_aggressive_coarsening</span> <span class="pre">&lt;N&gt;</span></code>, squares the graph on the finest N
levels). Likewise, if your <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatPtAP.html">MatPtAP</a>()</span></code> time is short and your convergence
If the rate is not ideal, you could decrease the coarsening rate.</p>
<p>PETSc’s AMG solver is a framework for developers to
easily add AMG capabilities, like new AMG methods or an AMG component
like a matrix triple product. Contact us directly if you are interested
in contributing.</p>
<p>Using algebraic multigrid as a “standalone” solver is possible but not recommended, as it does not accelerate it with a Krylov method.
Use a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPType.html">KSPType</a></span></code> of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPRICHARDSON.html">KSPRICHARDSON</a></span></code>
(or equivalently <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">richardson</span></code>) to achieve this. Using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPPREONLY.html">KSPPREONLY</a></span></code> will not work since it only applies a single multigrid cycle.</p>
<section id="adaptive-interpolation">
<h4>Adaptive Interpolation<a class="headerlink" href="#adaptive-interpolation" title="Link to this heading">#</a></h4>
<p><strong>Interpolation</strong> transfers a function from the coarse space to the fine space. We would like this process to be accurate for the functions resolved by the coarse grid, in particular the approximate solution computed there. By default, we create these matrices using local interpolation of the fine grid dual basis functions in the coarse basis. However, an adaptive procedure can optimize the coefficients of the interpolator to reproduce pairs of coarse/fine functions which should approximate the lowest modes of the generalized eigenproblem</p>
<div class="math">
\[
A x = \lambda M x
\]</div>
<p>where <span class="math">\(A\)</span> is the system matrix and <span class="math">\(M\)</span> is the smoother. Note that for defect-correction MG, the interpolated solution from the coarse space need not be as accurate as the fine solution, for the same reason that updates in iterative refinement can be less accurate. However, in FAS or in the final interpolation step for each level of Full Multigrid, we must have interpolation as accurate as the fine solution since we are moving the entire solution itself.</p>
<p><strong>Injection</strong> should accurately transfer the fine solution to the coarse grid. Accuracy here means that the action of a coarse dual function on either should produce approximately the same result. In the structured grid case, this means that we just use the same values on coarse points. This can result in aliasing.</p>
<p><strong>Restriction</strong> is intended to transfer the fine residual to the coarse space. Here we use averaging (often the transpose of the interpolation operation) to damp out the fine space contributions. Thus, it is less accurate than injection, but avoids aliasing of the high modes.</p>
<p>For a multigrid cycle, the interpolator <span class="math">\(P\)</span> is intended to accurately reproduce “smooth” functions from the coarse space in the fine space, keeping the energy of the interpolant about the same. For the Laplacian on a structured mesh, it is easy to determine what these low-frequency functions are. They are the Fourier modes. However an arbitrary operator <span class="math">\(A\)</span> will have different coarse modes that we want to resolve accurately on the fine grid, so that our coarse solve produces a good guess for the fine problem. How do we make sure that our interpolator <span class="math">\(P\)</span> can do this?</p>
<p>We first must decide what we mean by accurate interpolation of some functions. Suppose we know the continuum function <span class="math">\(f\)</span> that we care about, and we are only interested in a finite element description of discrete functions. Then the coarse function representing <span class="math">\(f\)</span> is given by</p>
<div class="math">
\[
f^C = \sum_i f^C_i \phi^C_i,
\]</div>
<p>and similarly the fine grid form is</p>
<div class="math">
\[
f^F = \sum_i f^F_i \phi^F_i.
\]</div>
<p>Now we would like the interpolant of the coarse representer to the fine grid to be as close as possible to the fine representer in a least squares sense, meaning we want to solve the minimization problem</p>
<div class="math">
\[
\min_{P} \| f^F - P f^C \|_2
\]</div>
<p>Now we can express <span class="math">\(P\)</span> as a matrix by looking at the matrix elements <span class="math">\(P_{ij} = \phi^F_i P \phi^C_j\)</span>. Then we have</p>
<div class="math">
\[
\begin{aligned}
  &\phi^F_i f^F - \phi^F_i P f^C \\
= &f^F_i - \sum_j P_{ij} f^C_j
\end{aligned}
\]</div>
<p>so that our discrete optimization problem is</p>
<div class="math">
\[
\min_{P_{ij}} \| f^F_i - \sum_j P_{ij} f^C_j \|_2
\]</div>
<p>and we will treat each row of the interpolator as a separate optimization problem. We could allow an arbitrary sparsity pattern, or try to determine adaptively, as is done in sparse approximate inverse preconditioning. However, we know the supports of the basis functions in finite elements, and thus the naive sparsity pattern from local interpolation can be used.</p>
<p>We note here that the BAMG framework of Brannick et al. <span id="id9">[<a class="reference internal" href="#id2244" title="Achi Brandt, James Brannick, Karsten Kahl, and Irene Livshits. Bootstrap AMG. SIAM Journal on Scientific Computing, 33(2):612–632, 2011.">BBKL11</a>]</span> does not use fine and coarse functions spaces, but rather a fine point/coarse point division which we will not employ here. Our general PETSc routine should work for both since the input would be the checking set (fine basis coefficients or fine space points) and the approximation set (coarse basis coefficients in the support or coarse points in the sparsity pattern).</p>
<p>We can easily solve the above problem using QR factorization. However, there are many smooth functions from the coarse space that we want interpolated accurately, and a single <span class="math">\(f\)</span> would not constrain the values <span class="math">\(P_{ij}`\)</span> well. Therefore, we will use several functions <span class="math">\(\{f_k\}\)</span> in our minimization,</p>
<div class="math">
\[
\begin{aligned}
  &\min_{P_{ij}} \sum_k w_k \| f^{F,k}_i - \sum_j P_{ij} f^{C,k}_j \|_2 \\
= &\min_{P_{ij}} \sum_k \| \sqrt{w_k} f^{F,k}_i - \sqrt{w_k} \sum_j P_{ij} f^{C,k}_j \|_2 \\
= &\min_{P_{ij}} \| W^{1/2} \mathbf{f}^{F}_i - W^{1/2} \mathbf{f}^{C} p_i \|_2
\end{aligned}
\]</div>
<p>where</p>
<div class="math">
\[
\begin{aligned}
W         &= \begin{pmatrix} w_0 & & \\ & \ddots & \\ & & w_K \end{pmatrix} \\
\mathbf{f}^{F}_i &= \begin{pmatrix} f^{F,0}_i \\ \vdots \\ f^{F,K}_i \end{pmatrix} \\
\mathbf{f}^{C}   &= \begin{pmatrix} f^{C,0}_0 & \cdots & f^{C,0}_n \\ \vdots & \ddots &  \vdots \\ f^{C,K}_0 & \cdots & f^{C,K}_n \end{pmatrix} \\
p_i       &= \begin{pmatrix} P_{i0} \\ \vdots \\ P_{in} \end{pmatrix}
\end{aligned}
\]</div>
<p>or alternatively</p>
<div class="math">
\[
\begin{aligned}
[W]_{kk}     &= w_k \\
[f^{F}_i]_k  &= f^{F,k}_i \\
[f^{C}]_{kj} &= f^{C,k}_j \\
[p_i]_j      &= P_{ij}
\end{aligned}
\]</div>
<p>We thus have a standard least-squares problem</p>
<div class="math">
\[
\min_{P_{ij}} \| b - A x \|_2
\]</div>
<p>where</p>
<div class="math">
\[
\begin{aligned}
A &= W^{1/2} f^{C} \\
b &= W^{1/2} f^{F}_i \\
x &= p_i
\end{aligned}
\]</div>
<p>which can be solved using LAPACK.</p>
<p>We will typically perform this optimization on a multigrid level <span class="math">\(l\)</span> when the change in eigenvalue from level <span class="math">\(l+1\)</span> is relatively large, meaning</p>
<div class="math">
\[
\frac{|\lambda_l - \lambda_{l+1}|}{|\lambda_l|}.
\]</div>
<p>This indicates that the generalized eigenvector associated with that eigenvalue was not adequately represented by <span class="math">\(P^l_{l+1}`\)</span>, and the interpolator should be recomputed.</p>
<hr></section>
</section>
<section id="balancing-domain-decomposition-by-constraints">
<h3>Balancing Domain Decomposition by Constraints<a class="headerlink" href="#balancing-domain-decomposition-by-constraints" title="Link to this heading">#</a></h3>
<p>PETSc provides the Balancing Domain Decomposition by Constraints (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>)
method for preconditioning parallel finite element problems stored in
unassembled format (see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATIS.html">MATIS</a></span></code>). <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> is a 2-level non-overlapping
domain decomposition method which can be easily adapted to different
problems and discretizations by means of few user customizations. The
application of the preconditioner to a vector consists in the static
condensation of the residual at the interior of the subdomains by means
of local Dirichlet solves, followed by an additive combination of Neumann
local corrections and the solution of a global coupled coarse problem.
Command line options for the underlying <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> objects are prefixed by
<code class="docutils notranslate"><span class="pre">-pc_bddc_dirichlet</span></code>, <code class="docutils notranslate"><span class="pre">-pc_bddc_neumann</span></code>, and <code class="docutils notranslate"><span class="pre">-pc_bddc_coarse</span></code>
respectively.</p>
<p>The implementation supports any kind of linear system, and
assumes a one-to-one mapping between subdomains and MPI processes.
Complex numbers are supported as well. For non-symmetric problems, use
the runtime option <code class="docutils notranslate"><span class="pre">-pc_bddc_symmetric</span> <span class="pre">0</span></code>.</p>
<p>Unlike conventional non-overlapping methods that iterates just on the
degrees of freedom at the interface between subdomain, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>
iterates on the whole set of degrees of freedom, allowing the use of
approximate subdomain solvers. When using approximate solvers, the
command line switches <code class="docutils notranslate"><span class="pre">-pc_bddc_dirichlet_approximate</span></code> and/or
<code class="docutils notranslate"><span class="pre">-pc_bddc_neumann_approximate</span></code> should be used to inform <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>. If
any of the local problems is singular, the nullspace of the local
operator should be attached to the local matrix via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNullSpace.html">MatSetNullSpace</a>()</span></code>.</p>
<p>At the basis of the method there’s the analysis of the connected
components of the interface for the detection of vertices, edges and
faces equivalence classes. Additional information on the degrees of
freedom can be supplied to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> by using the following functions:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetDofsSplitting.html">PCBDDCSetDofsSplitting</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetLocalAdjacencyGraph.html">PCBDDCSetLocalAdjacencyGraph</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetPrimalVerticesLocalIS.html">PCBDDCSetPrimalVerticesLocalIS</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetNeumannBoundaries.html">PCBDDCSetNeumannBoundaries</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetDirichletBoundaries.html">PCBDDCSetDirichletBoundaries</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetNeumannBoundariesLocal.html">PCBDDCSetNeumannBoundariesLocal</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetDirichletBoundariesLocal.html">PCBDDCSetDirichletBoundariesLocal</a>()</span></code></p></li>
</ul>
<p>Crucial for the convergence of the iterative process is the
specification of the primal constraints to be imposed at the interface
between subdomains. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> uses by default vertex continuities and
edge arithmetic averages, which are enough for the three-dimensional
Poisson problem with constant coefficients. The user can switch on and
off the usage of vertices, edges or face constraints by using the
command line switches <code class="docutils notranslate"><span class="pre">-pc_bddc_use_vertices</span></code>, <code class="docutils notranslate"><span class="pre">-pc_bddc_use_edges</span></code>,
<code class="docutils notranslate"><span class="pre">-pc_bddc_use_faces</span></code>. A customization of the constraints is available
by attaching a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span></code> object to the preconditioning matrix via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetNearNullSpace.html">MatSetNearNullSpace</a>()</span></code>. The vectors of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span></code> object
should represent the constraints in the form of quadrature rules;
quadrature rules for different classes of the interface can be listed in
the same vector. The number of vectors of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span></code> object
corresponds to the maximum number of constraints that can be imposed for
each class. Once all the quadrature rules for a given interface class
have been extracted, an SVD operation is performed to retain the
non-singular modes. As an example, the rigid body modes represent an
effective choice for elasticity, even in the almost incompressible case.
For particular problems, e.g. edge-based discretization with Nedelec
elements, a user defined change of basis of the degrees of freedom can
be beneficial for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>; use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetChangeOfBasisMat.html">PCBDDCSetChangeOfBasisMat</a>()</span></code> to
customize the change of basis.</p>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> method is usually robust with respect to jumps in the material
parameters aligned with the interface; for PDEs with more than one
material parameter you may also consider to use the so-called deluxe
scaling, available via the command line switch
<code class="docutils notranslate"><span class="pre">-pc_bddc_use_deluxe_scaling</span></code>. Other scalings are available, see
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCISSetSubdomainScalingFactor.html">PCISSetSubdomainScalingFactor</a>()</span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCISSetSubdomainDiagonalScaling.html">PCISSetSubdomainDiagonalScaling</a>()</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCISSetUseStiffnessScaling.html">PCISSetUseStiffnessScaling</a>()</span></code>. However, the convergence properties of
the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> method degrades in presence of large jumps in the material
coefficients not aligned with the interface; for such cases, PETSc has
the capability of adaptively computing the primal constraints. Adaptive
selection of constraints could be requested by specifying a threshold
value at command line by using <code class="docutils notranslate"><span class="pre">-pc_bddc_adaptive_threshold</span> <span class="pre">x</span></code>. Valid
values for the threshold <code class="docutils notranslate"><span class="pre">x</span></code> ranges from 1 to infinity, with smaller
values corresponding to more robust preconditioners. For SPD problems in
2D, or in 3D with only face degrees of freedom (like in the case of
Raviart-Thomas or Brezzi-Douglas-Marini elements), such a threshold is a
very accurate estimator of the condition number of the resulting
preconditioned operator. Since the adaptive selection of constraints for
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> methods is still an active topic of research, its implementation is
currently limited to SPD problems; moreover, because the technique
requires the explicit knowledge of the local Schur complements, it needs
the external package MUMPS.</p>
<p>When solving problems decomposed in thousands of subdomains or more, the
solution of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> coarse problem could become a bottleneck; in order
to overcome this issue, the user could either consider to solve the
parallel coarse problem on a subset of the communicator associated with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code> by using the command line switch
<code class="docutils notranslate"><span class="pre">-pc_bddc_coarse_redistribute</span></code>, or instead use a multilevel approach.
The latter can be requested by specifying the number of requested level
at command line (<code class="docutils notranslate"><span class="pre">-pc_bddc_levels</span></code>) or by using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetLevels.html">PCBDDCSetLevels</a>()</span></code>.
An additional parameter (see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDCSetCoarseningRatio.html">PCBDDCSetCoarseningRatio</a>()</span></code>) controls
the number of subdomains that will be generated at the next level; the
larger the coarsening ratio, the lower the number of coarser subdomains.</p>
<p>For further details, see the example
<a href="../src/ksp/ksp/tutorials/ex59.c">KSP Tutorial ex59</a>
and the online documentation for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCBDDC.html">PCBDDC</a></span></code>.</p>
</section>
<section id="shell-preconditioners">
<h3>Shell Preconditioners<a class="headerlink" href="#shell-preconditioners" title="Link to this heading">#</a></h3>
<p>The shell preconditioner simply uses an application-provided routine to
implement the preconditioner. That is, it allows users to write or wrap their
own custom preconditioners as a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> and use it with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>, etc.</p>
<p>To provide a custom preconditioner application, use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCShellSetApply.html">PCShellSetApply</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">apply</span><span class="p">)(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">));</span>
</pre></div>
</div>
<p>Often a preconditioner needs access to an application-provided data
structured. For this, one should use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCShellSetContext.html">PCShellSetContext</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>to set this data structure and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCShellGetContext.html">PCShellGetContext</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>to retrieve it in <code class="docutils notranslate"><span class="pre">apply</span></code>. The three routine arguments of <code class="docutils notranslate"><span class="pre">apply()</span></code>
are the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code>, the input vector, and the output vector, respectively.</p>
<p>For a preconditioner that requires some sort of “setup” before being
used, that requires a new setup every time the operator is changed, one
can provide a routine that is called every time the operator is changed
(usually via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a>()</span></code>).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCShellSetSetUp.html">PCShellSetSetUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">setup</span><span class="p">)(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="p">));</span>
</pre></div>
</div>
<p>The argument to the <code class="docutils notranslate"><span class="pre">setup</span></code> routine is the same <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> object which
can be used to obtain the operators with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCGetOperators.html">PCGetOperators</a>()</span></code> and the
application-provided data structure that was set with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCShellSetContext.html">PCShellSetContext</a>()</span></code>.</p>
</section>
<section id="combining-preconditioners">
<span id="sec-combining-pcs"></span><h3>Combining Preconditioners<a class="headerlink" href="#combining-preconditioners" title="Link to this heading">#</a></h3>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCCOMPOSITE.html">PCCOMPOSITE</a></span></code> allows one to form new preconditioners
by combining already-defined preconditioners and solvers. Combining
preconditioners usually requires some experimentation to find a
combination of preconditioners that works better than any single method.
It is a tricky business and is not recommended until your application
code is complete and running and you are trying to improve performance.
In many cases using a single preconditioner is better than a
combination; an exception is the multigrid/multilevel preconditioners
(solvers) that are always combinations of some sort, see <a class="reference internal" href="#sec-mg"><span class="std std-ref">Multigrid Preconditioners</span></a>.</p>
<p>Let <span class="math">\(B_1\)</span> and <span class="math">\(B_2\)</span> represent the application of two
preconditioners of type <code class="docutils notranslate"><span class="pre">type1</span></code> and <code class="docutils notranslate"><span class="pre">type2</span></code>. The preconditioner
<span class="math">\(B = B_1 + B_2\)</span> can be obtained with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCCOMPOSITE.html">PCCOMPOSITE</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCCompositeAddPCType.html">PCCompositeAddPCType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n">type1</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCCompositeAddPCType.html">PCCompositeAddPCType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n">type2</span><span class="p">);</span>
</pre></div>
</div>
<p>Any number of preconditioners may added in this way.</p>
<p>This way of combining preconditioners is called additive, since the
actions of the preconditioners are added together. This is the default
behavior. An alternative can be set with the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCCompositeSetType.html">PCCompositeSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCCompositeType.html">PC_COMPOSITE_MULTIPLICATIVE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>In this form the new residual is updated after the application of each
preconditioner and the next preconditioner applied to the next residual.
For example, with two composed preconditioners: <span class="math">\(B_1\)</span> and
<span class="math">\(B_2\)</span>; <span class="math">\(y = B x\)</span> is obtained from</p>
<div class="math">
\[
\begin{aligned}
y    = B_1 x \\
w_1  = x - A y \\
y    = y + B_2 w_1\end{aligned}
\]</div>
<p>Loosely, this corresponds to a Gauss-Seidel iteration, while additive
corresponds to a Jacobi iteration.</p>
<p>Under most circumstances, the multiplicative form requires one-half the
number of iterations as the additive form; however, the multiplicative
form does require the application of <span class="math">\(A\)</span> inside the
preconditioner.</p>
<p>In the multiplicative version, the calculation of the residual inside
the preconditioner can be done in two ways: using the original linear
system matrix or using the matrix used to build the preconditioners
<span class="math">\(B_1\)</span>, <span class="math">\(B_2\)</span>, etc. By default it uses the “preconditioner
matrix”, to use the <code class="docutils notranslate"><span class="pre">Amat</span></code> matrix use the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSetUseAmat.html">PCSetUseAmat</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The individual preconditioners can be accessed (in order to set options)
via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCCompositeGetPC.html">PCCompositeGetPC</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">count</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="o">*</span><span class="n">subpc</span><span class="p">);</span>
</pre></div>
</div>
<p>For example, to set the first sub preconditioners to use ILU(1)</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">subpc</span><span class="p">;</span>
<span class="n"><a href="../manualpages/PC/PCCompositeGetPC.html">PCCompositeGetPC</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="o">&amp;</span><span class="n">subpc</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetFill.html">PCFactorSetFill</a></span><span class="p">(</span><span class="n">subpc</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</div>
<p>One can also change the operator that is used to construct a particular
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> in the composite <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetOperators.html">PCSetOperators</a>()</span></code> on the obtained <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code>.
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFIELDSPLIT.html">PCFIELDSPLIT</a></span></code>, <a class="reference internal" href="#sec-block-matrices"><span class="std std-ref">Solving Block Matrices with PCFIELDSPLIT</span></a>, provides an alternative approach to defining composite preconditioners
with a variety of pre-defined compositions.</p>
<p>These various options can also be set via the options database. For
example, <code class="docutils notranslate"><span class="pre">-pc_type</span></code> <code class="docutils notranslate"><span class="pre">composite</span></code> <code class="docutils notranslate"><span class="pre">-pc_composite_pcs</span></code> <code class="docutils notranslate"><span class="pre">jacobi,ilu</span></code>
causes the composite preconditioner to be used with two preconditioners:
Jacobi and ILU. The option <code class="docutils notranslate"><span class="pre">-pc_composite_type</span></code> <code class="docutils notranslate"><span class="pre">multiplicative</span></code>
initiates the multiplicative version of the algorithm, while
<code class="docutils notranslate"><span class="pre">-pc_composite_type</span></code> <code class="docutils notranslate"><span class="pre">additive</span></code> the additive version. Using the
<code class="docutils notranslate"><span class="pre">Amat</span></code> matrix is obtained with the option <code class="docutils notranslate"><span class="pre">-pc_use_amat</span></code>. One sets
options for the sub-preconditioners with the extra prefix <code class="docutils notranslate"><span class="pre">-sub_N_</span></code>
where <code class="docutils notranslate"><span class="pre">N</span></code> is the number of the sub-preconditioner. For example,
<code class="docutils notranslate"><span class="pre">-sub_0_pc_ifactor_fill</span></code> <code class="docutils notranslate"><span class="pre">0</span></code>.</p>
<p>PETSc also allows a preconditioner to be a complete <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code> linear solver. This
is achieved with the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code> type.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCKSPGetKSP.html">PCKSPGetKSP</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">);</span>
<span class="w"> </span><span class="cm">/* set any <a href="../manualpages/KSP/KSP.html">KSP</a>/<a href="../manualpages/PC/PC.html">PC</a> options */</span>
</pre></div>
</div>
<p>From the command line one can use 5 iterations of biCG-stab with ILU(0)
preconditioning as the preconditioner with
<code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">ksp</span> <span class="pre">-ksp_pc_type</span> <span class="pre">ilu</span> <span class="pre">-ksp_ksp_max_it</span> <span class="pre">5</span> <span class="pre">-ksp_ksp_type</span> <span class="pre">bcgs</span></code>.</p>
<p>By default the inner <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> solver uses the outer preconditioner
matrix, <code class="docutils notranslate"><span class="pre">Pmat</span></code>, as the matrix to be solved in the linear system; to
use the matrix that defines the linear system, <code class="docutils notranslate"><span class="pre">Amat</span></code> use the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCSetUseAmat.html">PCSetUseAmat</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>or at the command line with <code class="docutils notranslate"><span class="pre">-pc_use_amat</span></code>.</p>
<p>Naturally, one can use a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCKSP.html">PCKSP</a></span></code> preconditioner inside a composite
preconditioner. For example,
<code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">composite</span> <span class="pre">-pc_composite_pcs</span> <span class="pre">ilu,ksp</span> <span class="pre">-sub_1_pc_type</span> <span class="pre">jacobi</span> <span class="pre">-sub_1_ksp_max_it</span> <span class="pre">10</span></code>
uses two preconditioners: ILU(0) and 10 iterations of GMRES with Jacobi
preconditioning. However, it is not clear whether one would ever wish to
do such a thing.</p>
</section>
<section id="multigrid-preconditioners">
<span id="sec-mg"></span><h3>Multigrid Preconditioners<a class="headerlink" href="#multigrid-preconditioners" title="Link to this heading">#</a></h3>
<p>A large suite of routines is available for using geometric multigrid as
a preconditioner <a class="footnote-reference brackets" href="#id16" id="id10" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. In the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> framework, the user is required to
provide the coarse grid solver, smoothers, restriction and interpolation
operators, and code to calculate residuals. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> package allows
these components to be encapsulated within a PETSc-compliant
preconditioner. We fully support both matrix-free and matrix-based
multigrid solvers.</p>
<p>A multigrid preconditioner is created with the four commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPCreate.html">KSPCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="o">*</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCMG.html">PCMG</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCMGSetLevels.html">PCMGSetLevels</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">levels</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="o">*</span><span class="n">comms</span><span class="p">);</span>
</pre></div>
</div>
<p>A large number of parameters affect the multigrid behavior. The command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetType.html">PCMGSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCMGType.html">PCMGType</a></span><span class="w"> </span><span class="n">mode</span><span class="p">);</span>
</pre></div>
</div>
<p>indicates which form of multigrid to apply <span id="id11">[<a class="reference internal" href="../manualpages/PC/PCGASM.html#id933" title="Barry F. Smith, Petter Bjørstad, and William D. Gropp. Domain Decomposition: Parallel Multilevel Methods for Elliptic Partial Differential Equations. Cambridge University Press, 1996. URL: http://www.mcs.anl.gov/~bsmith/ddbook.html.">SBjorstadG96</a>]</span>.</p>
<p>For standard V or W-cycle multigrids, one sets the <code class="docutils notranslate"><span class="pre">mode</span></code> to be
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGType.html">PC_MG_MULTIPLICATIVE</a></span></code>; for the additive form (which in certain cases
reduces to the BPX method, or additive multilevel Schwarz, or multilevel
diagonal scaling), one uses <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGType.html">PC_MG_ADDITIVE</a></span></code> as the <code class="docutils notranslate"><span class="pre">mode</span></code>. For a
variant of full multigrid, one can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGType.html">PC_MG_FULL</a></span></code>, and for the
Kaskade algorithm <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGType.html">PC_MG_KASKADE</a></span></code>. For the multiplicative and full
multigrid options, one can use a W-cycle by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetCycleType.html">PCMGSetCycleType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCMGCycleType.html">PCMGCycleType</a></span><span class="w"> </span><span class="n">ctype</span><span class="p">);</span>
</pre></div>
</div>
<p>with a value of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGCycleType.html">PC_MG_CYCLE_W</a></span></code> for <code class="docutils notranslate"><span class="pre">ctype</span></code>. The commands above can
also be set from the options database. The option names are
<code class="docutils notranslate"><span class="pre">-pc_mg_type</span> <span class="pre">[multiplicative,</span> <span class="pre">additive,</span> <span class="pre">full,</span> <span class="pre">kaskade]</span></code>, and
<code class="docutils notranslate"><span class="pre">-pc_mg_cycle_type</span></code> <code class="docutils notranslate"><span class="pre">&lt;ctype&gt;</span></code>.</p>
<p>The user can control the amount of smoothing by configuring the solvers
on the levels. By default, the up and down smoothers are identical. If
separate configuration of up and down smooths is required, it can be
requested with the option <code class="docutils notranslate"><span class="pre">-pc_mg_distinct_smoothup</span></code> or the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetDistinctSmoothUp.html">PCMGSetDistinctSmoothUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The multigrid routines, which determine the solvers and
interpolation/restriction operators that are used, are mandatory. To set
the coarse grid solver, one must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGGetCoarseSolve.html">PCMGGetCoarseSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>and set the appropriate options in <code class="docutils notranslate"><span class="pre">ksp</span></code>. Similarly, the smoothers are
controlled by first calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGGetSmoother.html">PCMGGetSmoother</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">ksp</span><span class="p">);</span>
</pre></div>
</div>
<p>and then setting the various options in the <code class="docutils notranslate"><span class="pre">ksp.</span></code> For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGGetSmoother.html">PCMGGetSmoother</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n">A1</span><span class="p">,</span><span class="n">A1</span><span class="p">);</span>
</pre></div>
</div>
<p>sets the matrix that defines the smoother on level 1 of the multigrid.
While</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGGetSmoother.html">PCMGGetSmoother</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">);</span>
<span class="n"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="o">&amp;</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCSOR.html">PCSOR</a></span><span class="p">);</span>
</pre></div>
</div>
<p>sets SOR as the smoother to use on level 1.</p>
<p>To use a different pre- or postsmoother, one should call the following
routines instead.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGGetSmootherUp.html">PCMGGetSmootherUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">upksp</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCMGGetSmootherDown.html">PCMGGetSmootherDown</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="o">*</span><span class="n">downksp</span><span class="p">);</span>
</pre></div>
</div>
<p>Use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetInterpolation.html">PCMGSetInterpolation</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">P</span><span class="p">);</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetRestriction.html">PCMGSetRestriction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">R</span><span class="p">);</span>
</pre></div>
</div>
<p>to define the intergrid transfer operations. If only one of these is
set, its transpose will be used for the other.</p>
<p>It is possible for these interpolation operations to be matrix-free (see
<a class="reference internal" href="mat.html#sec-matrixfree"><span class="std std-ref">Application Specific Custom Matrices</span></a>); One should then make
sure that these operations are defined for the (matrix-free) matrices
passed in. Note that this system is arranged so that if the
interpolation is the transpose of the restriction, you can pass the same
<code class="docutils notranslate"><span class="pre">mat</span></code> argument to both <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGSetRestriction.html">PCMGSetRestriction</a>()</span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMGSetInterpolation.html">PCMGSetInterpolation</a>()</span></code>.</p>
<p>On each level except the coarsest, one must also set the routine to
compute the residual. The following command suffices:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetResidual.html">PCMGSetResidual</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">residual</span><span class="p">)(</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">),</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">mat</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">residual()</span></code> function normally does not need to be set if one’s
operator is stored in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> format. In certain circumstances, where it
is much cheaper to calculate the residual directly, rather than through
the usual formula <span class="math">\(b - Ax\)</span>, the user may wish to provide an
alternative.</p>
<p>Finally, the user may provide three work vectors for each level (except
on the finest, where only the residual work vector is required). The
work vectors are set with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/PC/PCMGSetRhs.html">PCMGSetRhs</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">b</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCMGSetX.html">PCMGSetX</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCMGSetR.html">PCMGSetR</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">r</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> references these vectors, so you should call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a>()</span></code>
when you are finished with them. If any of these vectors are not
provided, the preconditioner will allocate them.</p>
<p>One can control the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> options used on the various
levels (as well as the coarse grid) using the prefix <code class="docutils notranslate"><span class="pre">mg_levels_</span></code>
(<code class="docutils notranslate"><span class="pre">mg_coarse_</span></code> for the coarse grid). For example,
<code class="docutils notranslate"><span class="pre">-mg_levels_ksp_type</span> <span class="pre">cg</span></code> will cause the CG method to be used as the
Krylov method for each level. Or
<code class="docutils notranslate"><span class="pre">-mg_levels_pc_type</span> <span class="pre">ilu</span> <span class="pre">-mg_levels_pc_factor_levels</span> <span class="pre">2</span></code> will cause the
ILU preconditioner to be used on each level with two levels of fill in
the incomplete factorization.</p>
</section>
</section>
<section id="solving-block-matrices-with-pcfieldsplit">
<span id="sec-block-matrices"></span><h2>Solving Block Matrices with PCFIELDSPLIT<a class="headerlink" href="#solving-block-matrices-with-pcfieldsplit" title="Link to this heading">#</a></h2>
<p>Block matrices represent an important class of problems in numerical
linear algebra and offer the possibility of far more efficient iterative
solvers than just treating the entire matrix as a black box. In this
section, we use the common linear algebra definition of block matrices, where matrices are divided into a small, problem-size independent (two,
three, or so) number of very large blocks. These blocks arise naturally
from the underlying physics or discretization of the problem, such as the velocity and pressure. Under a certain numbering of
unknowns, the matrix can be written as</p>
<div class="math">
\[
\left( \begin{array}{cccc}
A_{00}   & A_{01} & A_{02} & A_{03} \\
A_{10}   & A_{11} & A_{12} & A_{13} \\
A_{20}   & A_{21} & A_{22} & A_{23} \\
A_{30}   & A_{31} & A_{32} & A_{33} \\
\end{array} \right),
\]</div>
<p>where each <span class="math">\(A_{ij}\)</span> is an entire block. The matrices on a parallel computer are not explicitly stored this way. Instead, each process will
own some rows of <span class="math">\(A_{0*}\)</span>, <span class="math">\(A_{1*}\)</span> etc. On a
process, the blocks may be stored in one block followed by another</p>
<div class="math">
\[
\left( \begin{array}{ccccccc}
A_{{00}_{00}}   & A_{{00}_{01}} & A_{{00}_{02}} & ... & A_{{01}_{00}} & A_{{01}_{01}} & ...  \\
A_{{00}_{10}}   & A_{{00}_{11}} & A_{{00}_{12}} & ... & A_{{01}_{10}} & A_{{01}_{11}} & ... \\
A_{{00}_{20}}   & A_{{00}_{21}} & A_{{00}_{22}} & ... & A_{{01}_{20}} & A_{{01}_{21}}  & ...\\
... \\
A_{{10}_{00}}   & A_{{10}_{01}} & A_{{10}_{02}} & ... & A_{{11}_{00}} & A_{{11}_{01}}  & ... \\
A_{{10}_{10}}   & A_{{10}_{11}} & A_{{10}_{12}} & ... & A_{{11}_{10}} & A_{{11}_{11}}  & ... \\
... \\
\end{array} \right)
\]</div>
<p>or interlaced, for example, with four blocks</p>
<div class="math">
\[
\left( \begin{array}{ccccc}
A_{{00}_{00}}   & A_{{01}_{00}} &  A_{{00}_{01}} & A_{{01}_{01}} &  ... \\
A_{{10}_{00}}   & A_{{11}_{00}} &  A_{{10}_{01}} & A_{{11}_{01}} &  ... \\
A_{{00}_{10}}   & A_{{01}_{10}} & A_{{00}_{11}} & A_{{01}_{11}} & ...\\
A_{{10}_{10}}   & A_{{11}_{10}} & A_{{10}_{11}} & A_{{11}_{11}} & ...\\
...
\end{array} \right).
\]</div>
<p>Note that for interlaced storage, the number of rows/columns of each
block must be the same size. Matrices obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateMatrix.html">DMCreateMatrix</a>()</span></code>
where the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> is a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> are always stored interlaced. Block
matrices can also be stored using the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATNEST.html">MATNEST</a></span></code> format, which holds
separate assembled blocks. Each of these nested matrices is itself
distributed in parallel. It is more efficient to use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATNEST.html">MATNEST</a></span></code> with
the methods described in this section because there are fewer copies and
better formats (e.g., <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATBAIJ.html">MATBAIJ</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSBAIJ.html">MATSBAIJ</a></span></code>) can be used for the
components, but it is not possible to use many other methods with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATNEST.html">MATNEST</a></span></code>. See <a class="reference internal" href="mat.html#sec-matnest"><span class="std std-ref">Block Matrices</span></a> for more on assembling
block matrices without depending on a specific matrix format.</p>
<p>The PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFIELDSPLIT.html">PCFIELDSPLIT</a></span></code> preconditioner implements the
“block” solvers in PETSc, <span id="id12">[<a class="reference internal" href="../manualpages/PC/PCFIELDSPLIT.html#id1676" title="H.C. Elman, V.E. Howle, J. Shadid, R. Shuttleworth, and R. Tuminaro. A taxonomy and comparison of parallel block multi-level preconditioners for the incompressible Navier-Stokes equations. Journal of Computational Physics, 227(1):1790–1808, 2008. URL: https://www.osti.gov/biblio/920807/.">EHS+08</a>]</span>. There are three ways to provide the
information that defines the blocks. If the matrices are stored as
interlaced then <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetFields.html">PCFieldSplitSetFields</a>()</span></code> can be called repeatedly to
indicate which fields belong to each block. More generally
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetIS.html">PCFieldSplitSetIS</a>()</span></code> can be used to indicate exactly which
rows/columns of the matrix belong to a particular block (field). You can provide
names for each block with these routines; if you do not, they are numbered from 0. With these two approaches, the blocks may
overlap (though they generally will not overlap). If only one block is defined,
then the complement of the matrices is used to define the other block.
Finally, the option <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_detect_saddle_point</span></code> causes two
diagonal blocks to be found, one associated with all rows/columns that
have zeros on the diagonals and the rest.</p>
<p><strong>Important parameters for PCFIELDSPLIT</strong></p>
<ul>
<li><p>Control the fields used</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_detect_saddle_point</span></code> &lt;bool:false&gt; Generate two fields, the first consists of all rows with a nonzero on the diagonal, and the second will be all rows
with zero on the diagonal. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetDetectSaddlePoint.html">PCFieldSplitSetDetectSaddlePoint</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_dm_splits</span></code> &lt;bool:true&gt; Use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> attached to the preconditioner to determine the fields. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetDMSplits.html">PCFieldSplitSetDMSplits</a>()</span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateFieldDecomposition.html">DMCreateFieldDecomposition</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_%d_fields</span></code> &lt;f1,f2,…:int&gt; Use f1, f2, .. to define field <code class="docutils notranslate"><span class="pre">d</span></code>. The <code class="docutils notranslate"><span class="pre">fn</span></code> are in the range of 0, …, bs-1 where bs is the block size
of the matrix or set with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetBlockSize.html">PCFieldSplitSetBlockSize</a>()</span></code>. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetFields.html">PCFieldSplitSetFields</a>()</span></code>.</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_default</span></code> &lt;bool:true&gt; Automatically add any fields needed that have not been supplied explicitly by <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_%d_fields</span></code>.</p></li>
</ul>
</li>
<li><p><code class="docutils notranslate"><span class="pre">DMFieldsplitSetIS()</span></code> Provide the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code> that defines a particular field.</p></li>
</ul>
</li>
<li><p>Control the type of the block preconditioner</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type</span></code> &lt;additive|multiplicative|symmetric_multiplicative|schur|gkb:multiplicative&gt; The order in which the field solves are applied.
For symmetric problems where <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code> is used <code class="docutils notranslate"><span class="pre">symmetric_multiplicative</span></code> must be used instead of <code class="docutils notranslate"><span class="pre">multiplicative</span></code>. <code class="docutils notranslate"><span class="pre">additive</span></code> is the least expensive
to apply but provides the worst convergence. <code class="docutils notranslate"><span class="pre">schur</span></code> requires either a good preconditioner for the Schur complement or a naturally well-conditioned
Schur complement, but when it works well can be extremely effective. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetType.html">PCFieldSplitSetType</a>()</span></code>. <code class="docutils notranslate"><span class="pre">gkb</span></code> is for symmetric saddle-point problems (the lower-right
the block is zero).</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_diag_use_amat</span></code> &lt;bool:false&gt; Use the first matrix that is passed to <code class="docutils notranslate"><span class="pre">KSPSetJacobian()</span></code> to construct the block-diagonal sub-matrices used in the algorithms,
by default, the second matrix is used.</p></li>
<li><p>Options for Schur preconditioner: <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type</span></code>
<code class="docutils notranslate"><span class="pre">schur</span></code></p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_fact_type</span></code> &lt;diag|lower|upper|full:diag&gt; See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetSchurFactType.html">PCFieldSplitSetSchurFactType</a>()</span></code>. <code class="docutils notranslate"><span class="pre">full</span></code> reduces the iterations but each iteration requires additional
field solves.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span></code> &lt;self|selfp|user|a11|full:user&gt; How the Schur complement is preconditioned. See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetSchurPre.html">PCFieldSplitSetSchurPre</a>()</span></code>.</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-fieldsplit_1_mat_schur_complement_ainv_type</span></code> &lt;diag|lump:diag&gt; Use the lumped diagonal of <span class="math">\(A_{00}\)</span> when <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span></code>
<code class="docutils notranslate"><span class="pre">selfp</span></code> is used.</p></li>
</ul>
</li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_scale</span></code> &lt;scale:real:-1.0&gt; Controls the sign flip of S for <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_fact_type</span></code> <code class="docutils notranslate"><span class="pre">diag</span></code>.
See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetSchurScale.html">PCFieldSplitSetSchurScale</a>()</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">fieldsplit_1_xxx</span></code> controls the solver for the Schur complement system.
If a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> provided the fields, use the second field name set in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> instead of 1.</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-fieldsplit_1_pc_type</span></code> <code class="docutils notranslate"><span class="pre">lsc</span></code> <code class="docutils notranslate"><span class="pre">-fieldsplit_1_lsc_pc_xxx</span></code> use
the least squares commutators <span id="id13">[<a class="reference internal" href="../manualpages/PC/PCLSC.html#id1650" title="H.C. Elman, V.E. Howle, J. Shadid, R. Shuttleworth, and R. Tuminaro. Block preconditioners based on approximate commutators. SIAM J. Sci. Comput., 27(5):1651–1668, 2006.">EHS+06</a>]</span> <span id="id14">[<a class="reference internal" href="../manualpages/PC/PCLSC.html#id1678" title="D. Silvester, H. Elman, D. Kay, and A. Wathen. Efficient preconditioning of the linearized Navier-Stokes equations for incompressible flow. Journal of Computational and Applied Mathematics, 128(1-2):261–279, 2001.">SEKW01</a>]</span>
preconditioner for the Schur complement with any preconditioner for the least-squares matrix, see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLSC.html">PCLSC</a></span></code>.
If a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> provided the fields, use the second field name set in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> instead of 1.</p></li>
</ul>
</li>
<li><p><code class="docutils notranslate"><span class="pre">-fieldsplit_upper_xxx</span></code> Set options for the solver in the upper solver when <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_fact_type</span></code>
<code class="docutils notranslate"><span class="pre">upper</span></code> or <code class="docutils notranslate"><span class="pre">full</span></code> is used. Defaults to
using the solver as provided with <code class="docutils notranslate"><span class="pre">-fieldsplit_0_xxx</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-fieldsplit_1_inner_xxx</span></code> Set the options for the solver inside the application of the Schur complement;
defaults to using the solver as provided with <code class="docutils notranslate"><span class="pre">-fieldsplit_0_xxx</span></code>. If a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> provides the fields use the name of the second field name set in the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> instead of 1.</p></li>
</ul>
</li>
<li><p>Options for GKB preconditioner: <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type</span></code> gkb</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_gkb_tol</span></code> &lt;tol:real:1e-5&gt; See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetGKBTol.html">PCFieldSplitSetGKBTol</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_gkb_delay</span></code> &lt;delay:int:5&gt; See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetGKBDelay.html">PCFieldSplitSetGKBDelay</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_gkb_nu</span></code> &lt;nu:real:1.0&gt; See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetGKBNu.html">PCFieldSplitSetGKBNu</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_gkb_maxit</span></code> &lt;maxit:int:100&gt; See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetGKBMaxit.html">PCFieldSplitSetGKBMaxit</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-pc_fieldsplit_gkb_monitor</span></code> &lt;bool:false&gt; Monitor the convergence of the inner solver.</p></li>
</ul>
</li>
</ul>
</li>
<li><p>Options for additive and multiplication field solvers:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-fieldsplit_%d_xxx</span></code> Set options for the solver for field number <code class="docutils notranslate"><span class="pre">d</span></code>. For example, <code class="docutils notranslate"><span class="pre">-fieldsplit_0_pc_type</span></code>
<code class="docutils notranslate"><span class="pre">jacobi</span></code>. When the fields are obtained from a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> use the
field name instead of <code class="docutils notranslate"><span class="pre">d</span></code>.</p></li>
</ul>
</div></blockquote>
</li>
</ul>
<p>For simplicity, we restrict our matrices to two-by-two blocks in the rest of the section. So the matrix is</p>
<div class="math">
\[
\left( \begin{array}{cc}
A_{00}   & A_{01} \\
A_{10}   & A_{11} \\
\end{array} \right).
\]</div>
<p>On occasion, the user may provide another matrix that is used to
construct parts of the preconditioner</p>
<div class="math">
\[
\left( \begin{array}{cc}
Ap_{00}   & Ap_{01} \\
Ap_{10}   & Ap_{11} \\
\end{array} \right).
\]</div>
<p>For notational simplicity define <span class="math">\(\text{ksp}(A,Ap)\)</span> to mean
approximately solving a linear system using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> with the operator
<span class="math">\(A\)</span> and preconditioner built from matrix <span class="math">\(Ap\)</span>.</p>
<p>For matrices defined with any number of blocks, there are three “block”
algorithms available: block Jacobi,</p>
<div class="math">
\[
\left( \begin{array}{cc}
  \text{ksp}(A_{00},Ap_{00})   & 0 \\
  0   & \text{ksp}(A_{11},Ap_{11}) \\
\end{array} \right)
\]</div>
<p>block Gauss-Seidel,</p>
<div class="math">
\[
\left( \begin{array}{cc}
I   & 0 \\
0 & A^{-1}_{11} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A^{-1}_{00}   & 0 \\
0 & I \\
\end{array} \right)
\]</div>
<p>which is implemented <a class="footnote-reference brackets" href="#id17" id="id15" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a> as</p>
<div class="math">
\[
\left( \begin{array}{cc}
I   & 0 \\
  0 & \text{ksp}(A_{11},Ap_{11}) \\
\end{array} \right)
\]</div>
<div class="math">
\[
\left[
\left( \begin{array}{cc}
0   & 0 \\
0 & I \\
\end{array} \right) +
\left( \begin{array}{cc}
I   & 0 \\
-A_{10} & -A_{11} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
0 & 0 \\
\end{array} \right)
\right]
\]</div>
<div class="math">
\[
\left( \begin{array}{cc}
  \text{ksp}(A_{00},Ap_{00})   & 0 \\
0 & I \\
\end{array} \right)
\]</div>
<p>and symmetric block Gauss-Seidel</p>
<div class="math">
\[
\left( \begin{array}{cc}
A_{00}^{-1}   & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I   & -A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}   & 0 \\
0 & A_{11}^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1}   & 0 \\
0 & I \\
\end{array} \right).
\]</div>
<p>These can be accessed with
<code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type&lt;additive,multiplicative,``symmetric_multiplicative&gt;</span></code>
or the function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetType.html">PCFieldSplitSetType</a>()</span></code>. The option prefixes for the
internal KSPs are given by <code class="docutils notranslate"><span class="pre">-fieldsplit_name_</span></code>.</p>
<p>By default blocks <span class="math">\(A_{00}, A_{01}\)</span> and so on are extracted out of
<code class="docutils notranslate"><span class="pre">Pmat</span></code>, the matrix that the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> uses to build the preconditioner,
and not out of <code class="docutils notranslate"><span class="pre">Amat</span></code> (i.e., <span class="math">\(A\)</span> itself). As discussed above, in
<a class="reference internal" href="#sec-combining-pcs"><span class="std std-ref">Combining Preconditioners</span></a>, however, it is
possible to use <code class="docutils notranslate"><span class="pre">Amat</span></code> instead of <code class="docutils notranslate"><span class="pre">Pmat</span></code> by calling
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetUseAmat.html">PCSetUseAmat</a>(pc)</span></code> or using <code class="docutils notranslate"><span class="pre">-pc_use_amat</span></code> on the command line.
Alternatively, you can have <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFIELDSPLIT.html">PCFIELDSPLIT</a></span></code> extract the diagonal blocks
<span class="math">\(A_{00}, A_{11}\)</span> etc. out of <code class="docutils notranslate"><span class="pre">Amat</span></code> by calling
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetDiagUseAmat.html">PCFieldSplitSetDiagUseAmat</a>(pc,<a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a>)</span></code> or supplying command-line
argument <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_diag_use_amat</span></code>. Similarly,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetOffDiagUseAmat.html">PCFieldSplitSetOffDiagUseAmat</a>(pc,{<a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span></code>) or
<code class="docutils notranslate"><span class="pre">-pc_fieldsplit_off_diag_use_amat</span></code> will cause the off-diagonal blocks
<span class="math">\(A_{01},A_{10}\)</span> etc. to be extracted out of <code class="docutils notranslate"><span class="pre">Amat</span></code>.</p>
<p>For two-by-two blocks only, there is another family of solvers based on
Schur complements. The inverse of the Schur complement factorization is</p>
<div class="math">
\[
\left[
\left( \begin{array}{cc}
I   & 0 \\
A_{10}A_{00}^{-1} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}  & 0 \\
0 & S \\
\end{array} \right)
\left( \begin{array}{cc}
I   & A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)
\right]^{-1} =
\]</div>
<div class="math">
\[
\left( \begin{array}{cc}
I   & A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)^{-1}
\left( \begin{array}{cc}
A_{00}^{-1}  & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
A_{10}A_{00}^{-1} & I \\
\end{array} \right)^{-1} =
\]</div>
<div class="math">
\[
\left( \begin{array}{cc}
I   & -A_{00}^{-1} A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1}  & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
-A_{10}A_{00}^{-1} & I \\
\end{array} \right) =
\]</div>
<div class="math">
\[
\left( \begin{array}{cc}
A_{00}^{-1}   & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I   & -A_{01} \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1}  & 0 \\
0 & S^{-1} \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
-A_{10} & I \\
\end{array} \right)
\left( \begin{array}{cc}
A_{00}^{-1}   & 0 \\
0 & I \\
\end{array} \right).
\]</div>
<p>The preconditioner is accessed with <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type</span></code> <code class="docutils notranslate"><span class="pre">schur</span></code> and is
implemented as</p>
<div class="math">
\[
\left( \begin{array}{cc}
  \text{ksp}(A_{00},Ap_{00})   & 0 \\
0 & I \\
\end{array} \right)
\left( \begin{array}{cc}
I   & -A_{01} \\
0 & I \\
\end{array} \right)
\]</div>
<div class="math">
\[
\left( \begin{array}{cc}
I  & 0 \\
  0 & \text{ksp}(\hat{S},\hat{S}p) \\
\end{array} \right)
\left( \begin{array}{cc}
I   & 0 \\
  -A_{10} \text{ksp}(A_{00},Ap_{00}) & I \\
\end{array} \right).
\]</div>
<p>Where
<span class="math">\(\hat{S} = A_{11} - A_{10} \text{ksp}(A_{00},Ap_{00}) A_{01}\)</span> is
the approximate Schur complement.</p>
<p>There are several variants of the Schur complement preconditioner
obtained by dropping some of the terms; these can be obtained with
<code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_fact_type</span> <span class="pre">&lt;diag,lower,upper,full&gt;</span></code> or the
function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetSchurFactType.html">PCFieldSplitSetSchurFactType</a>()</span></code>. Note that the <code class="docutils notranslate"><span class="pre">diag</span></code> form
uses the preconditioner</p>
<div class="math">
\[
\left( \begin{array}{cc}
  \text{ksp}(A_{00},Ap_{00})   & 0 \\
  0 & -\text{ksp}(\hat{S},\hat{S}p) \\
\end{array} \right).
\]</div>
<p>This is done to ensure the preconditioner is positive definite for a
a common class of problems, saddle points with a positive definite
<span class="math">\(A_{00}\)</span>: for these, the Schur complement is negative definite.</p>
<p>The effectiveness of the Schur complement preconditioner depends on the
availability of a good preconditioner <span class="math">\(\hat Sp\)</span> for the Schur
complement matrix. In general, you are responsible for supplying
<span class="math">\(\hat Sp\)</span> via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCFieldSplitSetSchurPre.html">PCFieldSplitSetSchurPre</a>(pc,<a href="../manualpages/PC/PCFieldSplitSchurPreType.html">PC_FIELDSPLIT_SCHUR_PRE_USER</a>,Sp)</span></code>.
Without a good problem-specific <span class="math">\(\hat Sp\)</span>, you can use
some built-in options.</p>
<p>Using <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">user</span></code> on the command line
activates the matrix supplied programmatically, as explained above.</p>
<p>With <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">a11</span></code> (default)
<span class="math">\(\hat Sp = A_{11}\)</span> is used to build a preconditioner for
<span class="math">\(\hat S\)</span>.</p>
<p>Otherwise, <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">self</span></code> will set
<span class="math">\(\hat Sp = \hat S\)</span> and use the Schur complement matrix itself to
build the preconditioner.</p>
<p>The problem with the last approach is that <span class="math">\(\hat S\)</span> is used in
the unassembled, matrix-free form, and many preconditioners (e.g., ILU)
cannot be built out of such matrices. Instead, you can <em>assemble</em> an
approximation to <span class="math">\(\hat S\)</span> by inverting <span class="math">\(A_{00}\)</span>, but only
approximately, to ensure the sparsity of <span class="math">\(\hat Sp\)</span> as much
as possible. Specifically, using
<code class="docutils notranslate"><span class="pre">-pc_fieldsplit_schur_precondition</span> <span class="pre">selfp</span></code> will assemble
<span class="math">\(\hat Sp = A_{11} - A_{10} \text{inv}(A_{00}) A_{01}\)</span>.</p>
<p>By default <span class="math">\(\text{inv}(A_{00})\)</span> is the inverse of the diagonal of
<span class="math">\(A_{00}\)</span>, but using
<code class="docutils notranslate"><span class="pre">-fieldsplit_1_mat_schur_complement_ainv_type</span> <span class="pre">lump</span></code> will lump
<span class="math">\(A_{00}\)</span> first. Using
<code class="docutils notranslate"><span class="pre">-fieldsplit_1_mat_schur_complement_ainv_type</span> <span class="pre">blockdiag</span></code> will use the
inverse of the block diagonal of <span class="math">\(A_{00}\)</span>. Option
<code class="docutils notranslate"><span class="pre">-mat_schur_complement_ainv_type</span></code> applies to any matrix of
<code class="docutils notranslate"><span class="pre">MatSchurComplement</span></code> type and here it is used with the prefix
<code class="docutils notranslate"><span class="pre">-fieldsplit_1</span></code> of the linear system in the second split.</p>
<p>Finally, you can use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCLSC.html">PCLSC</a></span></code> preconditioner for the Schur
complement with <code class="docutils notranslate"><span class="pre">-pc_fieldsplit_type</span> <span class="pre">schur</span> <span class="pre">-fieldsplit_1_pc_type</span> <span class="pre">lsc</span></code>.
This uses for the preconditioner to <span class="math">\(\hat{S}\)</span> the operator</p>
<div class="math">
\[
\text{ksp}(A_{10} A_{01},A_{10} A_{01}) A_{10} A_{00} A_{01} \text{ksp}(A_{10} A_{01},A_{10} A_{01})
\]</div>
<p>Which, of course, introduces two additional inner solves for each
application of the Schur complement. The options prefix for this inner
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> is <code class="docutils notranslate"><span class="pre">-fieldsplit_1_lsc_</span></code>. Instead of constructing the matrix
<span class="math">\(A_{10} A_{01}\)</span>, users can provide their own matrix. This is
done by attaching the matrix/matrices to the <span class="math">\(Sp\)</span> matrix they
provide with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscObjectCompose.html">PetscObjectCompose</a></span><span class="p">((</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">)</span><span class="n">Sp</span><span class="p">,</span><span class="s">&quot;LSC_L&quot;</span><span class="p">,(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">)</span><span class="n">L</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscObjectCompose.html">PetscObjectCompose</a></span><span class="p">((</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">)</span><span class="n">Sp</span><span class="p">,</span><span class="s">&quot;LSC_Lp&quot;</span><span class="p">,(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">)</span><span class="n">Lp</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="solving-singular-systems">
<span id="sec-singular"></span><h2>Solving Singular Systems<a class="headerlink" href="#solving-singular-systems" title="Link to this heading">#</a></h2>
<p>Sometimes one is required to solver singular linear systems. In this
case, the system matrix has a nontrivial null space. For example, the
discretization of the Laplacian operator with Neumann boundary
conditions has a null space of the constant functions. PETSc has tools
to help solve these systems. This approach is only guaranteed to work for left preconditioning (see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetPCSide.html">KSPSetPCSide</a>()</span></code>); for example it
may not work in some situations with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPFGMRES.html">KSPFGMRES</a></span></code>.</p>
<p>First, one must know what the null space is and store it using an
orthonormal basis in an array of PETSc Vecs. The constant functions can
be handled separately, since they are such a common case. Create a
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span></code> object with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatNullSpaceCreate.html">MatNullSpaceCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">hasconstants</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">dim</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">basis</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span><span class="w"> </span><span class="o">*</span><span class="n">nsp</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils notranslate"><span class="pre">dim</span></code> is the number of vectors in <code class="docutils notranslate"><span class="pre">basis</span></code> and <code class="docutils notranslate"><span class="pre">hasconstants</span></code>
indicates if the null space contains the constant functions. If the null
space contains the constant functions you do not need to include it in
the <code class="docutils notranslate"><span class="pre">basis</span></code> vectors you provide, nor in the count <code class="docutils notranslate"><span class="pre">dim</span></code>.</p>
<p>One then tells the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> object you are using what the null space is
with the call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatSetNullSpace.html">MatSetNullSpace</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MatNullSpace.html">MatNullSpace</a></span><span class="w"> </span><span class="n">nsp</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">Amat</span></code> should be the <em>first</em> matrix argument used with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOperators.html">KSPSetOperators</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a>()</span></code>.
The PETSc solvers will now
handle the null space during the solution process.</p>
<p>If the right-hand side of linear system is not in the range of <code class="docutils notranslate"><span class="pre">Amat</span></code>, that is it is not
orthogonal to the null space of <code class="docutils notranslate"><span class="pre">Amat</span></code> transpose, then the residual
norm of the Krylov iteration will not converge to zero; it will converge to a non-zero value while the
solution is converging to the least squares solution of the linear system. One can, if one desires,
apply <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatNullSpaceRemove.html">MatNullSpaceRemove</a>()</span></code> with the null space of <code class="docutils notranslate"><span class="pre">Amat</span></code> transpose to the right-hand side before calling
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>. Then the residual norm will converge to zero.</p>
<p>If one chooses a direct solver (or an incomplete factorization) it may
still detect a zero pivot. You can run with the additional options or
<code class="docutils notranslate"><span class="pre">-pc_factor_shift_type</span> <span class="pre">NONZERO</span></code>
<code class="docutils notranslate"><span class="pre">-pc_factor_shift_amount</span>&#160; <span class="pre">&lt;dampingfactor&gt;</span></code> to prevent the zero pivot.
A good choice for the <code class="docutils notranslate"><span class="pre">dampingfactor</span></code> is 1.e-10.</p>
<p>If the matrix is non-symmetric and you wish to solve the transposed linear system
you must provide the null space of the transposed matrix with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetTransposeNullSpace.html">MatSetTransposeNullSpace</a>()</span></code>.</p>
</section>
<section id="using-external-linear-solvers">
<span id="sec-externalsol"></span><h2>Using External Linear Solvers<a class="headerlink" href="#using-external-linear-solvers" title="Link to this heading">#</a></h2>
<p>PETSc interfaces to several external linear solvers (also see <a class="reference internal" href="../miscellaneous/acknowledgements.html#acknowledgements"><span class="std std-ref">Acknowledgements</span></a>).
To use these solvers, one may:</p>
<ol class="arabic simple">
<li><p>Run <code class="docutils notranslate"><span class="pre">configure</span></code> with the additional options
<code class="docutils notranslate"><span class="pre">--download-packagename</span></code> e.g. <code class="docutils notranslate"><span class="pre">--download-superlu_dist</span></code>
<code class="docutils notranslate"><span class="pre">--download-parmetis</span></code> (SuperLU_DIST needs ParMetis) or
<code class="docutils notranslate"><span class="pre">--download-mumps</span></code> <code class="docutils notranslate"><span class="pre">--download-scalapack</span></code> (MUMPS requires
ScaLAPACK).</p></li>
<li><p>Build the PETSc libraries.</p></li>
<li><p>Use the runtime option: <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> (or equivalently <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">none</span></code>) <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">&lt;pctype&gt;</span></code>
<code class="docutils notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre">&lt;packagename&gt;</span></code>. For eg:
<code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">lu</span></code>
<code class="docutils notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre">superlu_dist</span></code>.</p></li>
</ol>
<table class="table" id="tab-externaloptions">
<caption><span class="caption-number">Table 8 </span><span class="caption-text">Options for External Solvers</span><a class="headerlink" href="#tab-externaloptions" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>MatType</p></th>
<th class="head"><p>PCType</p></th>
<th class="head"><p>MatSolverType</p></th>
<th class="head"><p>Package</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERESSL.html">MATSOLVERESSL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">essl</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERLUSOL.html">MATSOLVERLUSOL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lusol</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERMATLAB.html">MATSOLVERMATLAB</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">matlab</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERMUMPS.html">MATSOLVERMUMPS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">mumps</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">sbaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERSUPERLU.html">MATSOLVERSUPERLU</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">superlu</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERSUPERLU_DIST.html">MATSOLVERSUPERLU_DIST</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">superlu_dist</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERUMFPACK.html">MATSOLVERUMFPACK</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">umfpack</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERCHOLMOD.html">MATSOLVERCHOLMOD</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholmod</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERKLU.html">MATSOLVERKLU</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">klu</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">dense</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">MATSOLVERELEMENTAL</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">elemental</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">dense</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">seqaij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERMKL_PARDISO.html">MATSOLVERMKL_PARDISO</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">mkl_pardiso</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERMKL_CPARDISO.html">MATSOLVERMKL_CPARDISO</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">mkl_cpardiso</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERPASTIX.html">MATSOLVERPASTIX</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">pastix</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERBAS.html">MATSOLVERBAS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bas</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aijcusparse</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSOLVERCUSPARSE.html">MATSOLVERCUSPARSE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cusparse</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aijcusparse</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lu</span></code>, <code class="docutils notranslate"><span class="pre">cholesky</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">MATSOLVERPETSC</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">petsc</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">baij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aijcrl</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aijperm</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">seqdense</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">baij</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">aijcrl</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">aijperm</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">seqdense</span></code></p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>The default and available input options for each external software can
be found by specifying <code class="docutils notranslate"><span class="pre">-help</span></code> at runtime.</p>
<p>As an alternative to using runtime flags to employ these external
packages, procedural calls are provided for some packages. For example,
the following procedural calls are equivalent to runtime options
<code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">preonly</span></code> (or equivalently <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">none</span></code>) <code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">lu</span></code>
<code class="docutils notranslate"><span class="pre">-pc_factor_mat_solver_type</span> <span class="pre">mumps</span></code> <code class="docutils notranslate"><span class="pre">-mat_mumps_icntl_7</span> <span class="pre">3</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPPREONLY.html">KSPPREONLY</a></span><span class="p">);</span><span class="w"> </span><span class="p">(</span><span class="n">or</span><span class="w"> </span><span class="n">equivalently</span><span class="w"> </span><span class="n"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n"><a href="../manualpages/KSP/KSPNONE.html">KSPNONE</a></span><span class="p">))</span>
<span class="n"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="o">&amp;</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCSetType.html">PCSetType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PCLU.html">PCLU</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetMatSolverType.html">PCFactorSetMatSolverType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/MATSOLVERMUMPS.html">MATSOLVERMUMPS</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorSetUpMatSolverType.html">PCFactorSetUpMatSolverType</a></span><span class="p">(</span><span class="n">pc</span><span class="p">);</span>
<span class="n"><a href="../manualpages/PC/PCFactorGetMatrix.html">PCFactorGetMatrix</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="o">&amp;</span><span class="n">F</span><span class="p">);</span>
<span class="n">icntl</span><span class="o">=</span><span class="mi">7</span><span class="p">;</span><span class="w"> </span><span class="n">ival</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Mat/MatMumpsSetIcntl.html">MatMumpsSetIcntl</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="n">icntl</span><span class="p">,</span><span class="n">ival</span><span class="p">);</span>
</pre></div>
</div>
<p>One can also create matrices with the appropriate capabilities by
calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a>()</span></code> followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetType.html">MatSetType</a>()</span></code> specifying the
desired matrix type from <a class="reference internal" href="#tab-externaloptions"><span class="std std-ref">Options for External Solvers</span></a>. These
matrix types inherit capabilities from their PETSc matrix parents:
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQAIJ.html">MATSEQAIJ</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIAIJ.html">MATMPIAIJ</a></span></code>, etc. As a result, the preallocation routines
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSeqAIJSetPreallocation.html">MatSeqAIJSetPreallocation</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMPIAIJSetPreallocation.html">MatMPIAIJSetPreallocation</a>()</span></code>, etc.
and any other type specific routines of the base class are supported.
One can also call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatConvert.html">MatConvert</a>()</span></code> inplace to convert the matrix to and
from its base class without performing an expensive data copy.
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatConvert.html">MatConvert</a>()</span></code> cannot be called on matrices that have already been
factored.</p>
<p>In <a class="reference internal" href="#tab-externaloptions"><span class="std std-ref">Options for External Solvers</span></a>, the base class <code class="docutils notranslate"><span class="pre">aij</span></code> refers
to the fact that inheritance is based on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSEQAIJ.html">MATSEQAIJ</a></span></code> when constructed
with a single process communicator, and from <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIAIJ.html">MATMPIAIJ</a></span></code> otherwise.
The same holds for <code class="docutils notranslate"><span class="pre">baij</span></code> and <code class="docutils notranslate"><span class="pre">sbaij</span></code>. For codes that are intended
to be run as both a single process or with multiple processes, depending
on the <code class="docutils notranslate"><span class="pre">mpiexec</span></code> command, it is recommended that both sets of
preallocation routines are called for these communicator morphing types.
The call for the incorrect type will simply be ignored without any harm
or message.</p>
</section>
<section id="using-petsc-s-mpi-parallel-linear-solvers-from-a-non-mpi-program">
<span id="sec-pcmpi"></span><h2>Using PETSc’s MPI parallel linear solvers from a non-MPI program<a class="headerlink" href="#using-petsc-s-mpi-parallel-linear-solvers-from-a-non-mpi-program" title="Link to this heading">#</a></h2>
<p>Using PETSc’s MPI linear solver server it is possible to use multiple MPI processes to solve a
a linear system when the application code, including the matrix generation, is run on a single
MPI process (with or without OpenMP). The application code must be built with MPI and must call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code> at the very beginning of the program and end with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a>()</span></code>. The
application code may utilize OpenMP.
The code may create multiple matrices and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> objects and call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSolve.html">KSPSolve</a>()</span></code>, similarly the
code may utilize the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> nonlinear solvers, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> ODE integrators, and the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Tao/Tao.html">Tao</a></span></code> optimization algorithms
which use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>.</p>
<p>The program must then be launched using the standard approaches for launching MPI programs with the additional
PETSc option <code class="docutils notranslate"><span class="pre">-mpi_linear_solver_server</span></code>. The linear solves are controlled via the options database in the usual manner (using any options prefix
you may have provided via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOptionsPrefix.html">KSPSetOptionsPrefix</a>()</span></code>, for example <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">cg</span> <span class="pre">-ksp_monitor</span> <span class="pre">-pc_type</span> <span class="pre">bjacobi</span> <span class="pre">-ksp_view</span></code>. The solver options cannot be set via
the functional interface, for example <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a>()</span></code> etc.</p>
<p>The option <code class="docutils notranslate"><span class="pre">-mpi_linear_solver_server_view</span></code> will print
a summary of all the systems solved by the MPI linear solver server when the program completes. By default the linear solver server
will only parallelize the linear solve to the extent that it believes is appropriate to obtain speedup for the parallel solve, for example, if the
matrix has 1,000 rows and columns the solution will not be parallelized by default. One can use the option <code class="docutils notranslate"><span class="pre">-mpi_linear_solver_server_minimum_count_per_rank</span> <span class="pre">5000</span></code>
to cause the linear solver server to allow as few as 5,000 unknowns per MPI process in the parallel solve.</p>
<p>See <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPI.html">PCMPI</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPIServerBegin.html">PCMPIServerBegin</a>()</span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPIServerEnd.html">PCMPIServerEnd</a>()</span></code> for more details on the solvers.</p>
<p>For help when anything goes wrong with the MPI linear solver server see <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPIServerBegin.html">PCMPIServerBegin</a>()</span></code>.</p>
<p>Amdahl’s law makes clear that parallelizing only a portion of a numerical code can only provide a limited improvement
in the computation time; thus it is crucial to understand what phases of a computation must be parallelized (via MPI, OpenMP, or some other model)
to ensure a useful increase in performance. One of the crucial phases is likely the generation of the matrix entries; the
use of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetPreallocationCOO.html">MatSetPreallocationCOO</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesCOO.html">MatSetValuesCOO</a>()</span></code> in an OpenMP code allows parallelizing the generation of the matrix.</p>
<p>See <a class="reference internal" href="streams.html#sec-pcmpi-study"><span class="std std-ref">Application with the MPI linear solver server</span></a> for a study of the use of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMPI.html">PCMPI</a></span></code> on a specific PETSc application.</p>
<p class="rubric">Footnotes</p>
<p class="rubric">References</p>
<div class="docutils container" id="id1">
<div role="list" class="citation-list">
<div class="citation" id="id2244" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">BBKL11</a><span class="fn-bracket">]</span></span>
<p>Achi Brandt, James Brannick, Karsten Kahl, and Irene Livshits. Bootstrap AMG. <em>SIAM Journal on Scientific Computing</em>, 33(2):612–632, 2011.</p>
</div>
<div class="citation" id="id1183" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id5">CS99</a><span class="fn-bracket">]</span></span>
<p>X.-C. Cai and M. Sarkis. A restricted additive Schwarz preconditioner for general sparse linear systems. <em>SIAM J. Scientific Computing</em>, 21:792–797, 1999.</p>
</div>
<div class="citation" id="id3896" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">CGS+94</a><span class="fn-bracket">]</span></span>
<p>Tony F Chan, Efstratios Gallopoulos, Valeria Simoncini, Tedd Szeto, and Charles H Tong. A quasi-minimal residual variant of the Bi-CGSTAB algorithm for nonsymmetric systems. <em>SIAM Journal on Scientific Computing</em>, 15(2):338–347, 1994.</p>
</div>
<div class="citation" id="id1243" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">Eis81</a><span class="fn-bracket">]</span></span>
<p>S. Eisenstat. Efficient implementation of a class of CG methods. <em>SIAM J. Sci. Stat. Comput.</em>, 2:1–4, 1981.</p>
</div>
<div class="citation" id="id1684" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id12">EES83</a><span class="fn-bracket">]</span></span>
<p>S.C. Eisenstat, H.C. Elman, and M.H. Schultz. Variational iterative methods for nonsymmetric systems of linear equations. <em>SIAM Journal on Numerical Analysis</em>, 20(2):345–357, 1983.</p>
</div>
<div class="citation" id="id1648" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id13">EHS+06</a><span class="fn-bracket">]</span></span>
<p>H.C. Elman, V.E. Howle, J. Shadid, R. Shuttleworth, and R. Tuminaro. Block preconditioners based on approximate commutators. <em>SIAM J. Sci. Comput.</em>, 27(5):1651–1668, 2006.</p>
</div>
<div class="citation" id="id1673" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id12">EHS+08</a><span class="fn-bracket">]</span></span>
<p>H.C. Elman, V.E. Howle, J. Shadid, R. Shuttleworth, and R. Tuminaro. A taxonomy and comparison of parallel block multi-level preconditioners for the incompressible Navier-Stokes equations. <em>Journal of Computational Physics</em>, 227(1):1790–1808, 2008. URL: <a class="reference external" href="https://www.osti.gov/biblio/920807/">https://www.osti.gov/biblio/920807/</a>.</p>
</div>
<div class="citation" id="id1238" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">FGN92</a><span class="fn-bracket">]</span></span>
<p>R. Freund, G. H. Golub, and N. Nachtigal. <em>Iterative Solution of Linear Systems</em>, pages 57–100. Acta Numerica. Cambridge University Press, 1992.</p>
</div>
<div class="citation" id="id1274" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id15">Fre93</a><span class="fn-bracket">]</span></span>
<p>Roland W. Freund. A transpose-free quasi-minimal residual algorithm for non-Hermitian linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 14:470–482, 1993.</p>
</div>
<div class="citation" id="id1798" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">GAMV13</a><span class="fn-bracket">]</span></span>
<p>P. Ghysels, T.J. Ashby, K. Meerbergen, and W. Vanroose. Hiding global communication latency in the GMRES algorithm on massively parallel machines. <em>SIAM Journal on Scientific Computing</em>, 35(1):C48–C71, 2013.</p>
</div>
<div class="citation" id="id1799" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">GV14</a><span class="fn-bracket">]</span></span>
<p>P. Ghysels and W. Vanroose. Hiding global synchronization latency in the preconditioned conjugate gradient algorithm. <em>Parallel Computing</em>, 40(7):224–238, 2014. 7th Workshop on Parallel Matrix Algorithms and Applications. <a class="reference external" href="https://doi.org/10.1016/j.parco.2013.06.001">doi:10.1016/j.parco.2013.06.001</a>.</p>
</div>
<div class="citation" id="id1271" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">HS52</a><span class="fn-bracket">]</span></span>
<p>Magnus R. Hestenes and Eduard Steifel. Methods of conjugate gradients for solving linear systems. <em>J. Research of the National Bureau of Standards</em>, 49:409–436, 1952.</p>
</div>
<div class="citation" id="id2029" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">ISG15</a><span class="fn-bracket">]</span></span>
<p>Tobin Isaac, Georg Stadler, and Omar Ghattas. Solution of nonlinear Stokes equations discretized by high-order finite elements on nonconforming and anisotropic meshes, with application to ice sheet dynamics. <em>SIAM Journal on Scientific Computing</em>, 37(6):804–833, 2015. <a class="reference external" href="https://doi.org/10.1137/140974407">doi:10.1137/140974407</a>.</p>
</div>
<div class="citation" id="id1878" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">Not00</a><span class="fn-bracket">]</span></span>
<p>Yvan Notay. Flexible conjugate gradients. <em>SIAM Journal on Scientific Computing</em>, 22(4):1444–1460, 2000.</p>
</div>
<div class="citation" id="id3447" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>PS75<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id7">1</a>,<a role="doc-backlink" href="#id16">2</a>)</span>
<p>C. C. Paige and M. A. Saunders. Solution of sparse indefinite systems of linear equations. <em>SIAM Journal on Numerical Analysis</em>, 12:617–629, 1975.</p>
</div>
<div class="citation" id="id3637" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">SS86</a><span class="fn-bracket">]</span></span>
<p>Y. Saad and M. Schultz. GMRES: A generalized minimal residual algorithm for solving nonsymmetric linear systems. <em>SIAM Journal on Scientific and Statistical Computing</em>, 44:856–869, 1986.</p>
</div>
<div class="citation" id="id1669" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">Saa93</a><span class="fn-bracket">]</span></span>
<p>Youcef Saad. A flexible inner-outer preconditioned GMRES algorithm. <em>SIAM Journal on Scientific Computing</em>, 14(2):461–469, 1993. <a class="reference external" href="https://doi.org/10.1137/0914028">doi:10.1137/0914028</a>.</p>
</div>
<div class="citation" id="id1340" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">Saa03</a><span class="fn-bracket">]</span></span>
<p>Yousef Saad. <em>Iterative Methods for Sparse Linear Systems</em>. SIAM, 2nd edition, 2003. <a class="reference external" href="https://doi.org/10.1016/S1570-579X(01)80025-2">doi:10.1016/S1570-579X(01)80025-2</a>.</p>
</div>
<div class="citation" id="id989" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>SSM16<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id4">1</a>,<a role="doc-backlink" href="#id11">2</a>,<a role="doc-backlink" href="#id13">3</a>)</span>
<p>P. Sanan, S. M. Schnepp, and D. A. May. Pipelined, flexible Krylov subspace methods. <em>SIAM Journal on Scientific Computing</em>, 38(5):C441–C470, 2016. <a class="reference external" href="https://doi.org/10.1137/15M1049130">doi:10.1137/15M1049130</a>.</p>
</div>
<div class="citation" id="id1676" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id14">SEKW01</a><span class="fn-bracket">]</span></span>
<p>D. Silvester, H. Elman, D. Kay, and A. Wathen. Efficient preconditioning of the linearized Navier-Stokes equations for incompressible flow. <em>Journal of Computational and Applied Mathematics</em>, 128(1-2):261–279, 2001.</p>
</div>
<div class="citation" id="id931" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id11">SBjorstadG96</a><span class="fn-bracket">]</span></span>
<p>Barry F. Smith, Petter Bjørstad, and William D. Gropp. <em>Domain Decomposition: Parallel Multilevel Methods for Elliptic Partial Differential Equations</em>. Cambridge University Press, 1996. URL: <a class="reference external" href="http://www.mcs.anl.gov/~bsmith/ddbook.html">http://www.mcs.anl.gov/~bsmith/ddbook.html</a>.</p>
</div>
<div class="citation" id="id1272" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id14">Son89</a><span class="fn-bracket">]</span></span>
<p>Peter Sonneveld. CGS, a fast Lanczos-type solver for nonsymmetric linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 10:36–52, 1989.</p>
</div>
<div class="citation" id="id2252" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">vdV03</a><span class="fn-bracket">]</span></span>
<p>H. van der Vorst. <em>Iterative Krylov Methods for Large Linear Systems</em>. Cambridge University Press, 2003. ISBN 9780521818285.</p>
</div>
<div class="citation" id="id1713" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">VanveekBM01</a><span class="fn-bracket">]</span></span>
<p>P. Vaněek, M. Brezina, and J. Mandel. Convergence of algebraic multigrid based on smoothed aggregation. <em>Numerische Mathematik</em>, 88(3):559–579, 2001.</p>
</div>
<div class="citation" id="id1712" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">VanvekMB96</a><span class="fn-bracket">]</span></span>
<p>P. Vaněk, J. Mandel, and M. Brezina. Algebraic multigrid by smoothed aggregation for second and fourth order elliptic problems. <em>Computing</em>, 56(3):179–196, 1996.</p>
</div>
<div class="citation" id="id1273" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id5">vandVorst92</a><span class="fn-bracket">]</span></span>
<p>H. A. van der Vorst. BiCGSTAB: a fast and smoothly converging variant of BiCG for the solution of nonsymmetric linear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 13:631–644, 1992.</p>
</div>
</div>
</div>
</section>
</section>
<hr class="footnotes docutils" />
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id16" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id10">1</a><span class="fn-bracket">]</span></span>
<p>See <a class="reference internal" href="#sec-amg"><span class="std std-ref">Algebraic Multigrid (AMG) Preconditioners</span></a> for information on using algebraic multigrid.</p>
</aside>
<aside class="footnote brackets" id="id17" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id15">2</a><span class="fn-bracket">]</span></span>
<p>This may seem an odd way to implement since it involves the “extra”
multiply by <span class="math">\(-A_{11}\)</span>. The reason is this is implemented this
way is that this approach works for any number of blocks that may
overlap.</p>
</aside>
</aside>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="mat.html"
       title="previous page">
      <i class="fa-solid fa-angle-left"></i>
      <div class="prev-next-info">
        <p class="prev-next-subtitle">previous</p>
        <p class="prev-next-title">Matrices</p>
      </div>
    </a>
    <a class="right-next"
       href="snes.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">SNES: Nonlinear Solvers</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-ksp">Using KSP</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#solving-successive-linear-systems">Solving Successive Linear Systems</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#krylov-methods">Krylov Methods</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#preconditioning-within-ksp">Preconditioning within KSP</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#convergence-tests">Convergence Tests</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#convergence-monitoring">Convergence Monitoring</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#understanding-the-operators-spectrum">Understanding the Operator’s Spectrum</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#flexible-krylov-methods">Flexible Krylov Methods</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#pipelined-krylov-methods">Pipelined Krylov Methods</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#other-ksp-options">Other KSP Options</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#preconditioners">Preconditioners</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ilu-and-icc-preconditioners">ILU and ICC Preconditioners</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#sor-and-ssor-preconditioners">SOR and SSOR Preconditioners</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#lu-factorization">LU Factorization</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#block-jacobi-and-overlapping-additive-schwarz-preconditioners">Block Jacobi and Overlapping Additive Schwarz Preconditioners</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#algebraic-multigrid-amg-preconditioners">Algebraic Multigrid (AMG) Preconditioners</a><ul class="nav section-nav flex-column">
<li class="toc-h4 nav-item toc-entry"><a class="reference internal nav-link" href="#adaptive-interpolation">Adaptive Interpolation</a></li>
</ul>
</li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#balancing-domain-decomposition-by-constraints">Balancing Domain Decomposition by Constraints</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#shell-preconditioners">Shell Preconditioners</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#combining-preconditioners">Combining Preconditioners</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#multigrid-preconditioners">Multigrid Preconditioners</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#solving-block-matrices-with-pcfieldsplit">Solving Block Matrices with PCFIELDSPLIT</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#solving-singular-systems">Solving Singular Systems</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-external-linear-solvers">Using External Linear Solvers</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-petsc-s-mpi-parallel-linear-solvers-from-a-non-mpi-program">Using PETSc’s MPI parallel linear solvers from a non-MPI program</a></li>
</ul>
  </nav></div>

  <div class="sidebar-secondary-item">

  
  <div class="tocsection editthispage">
    <a href="https://gitlab.com/petsc/petsc/-/edit/release/doc/manual/ksp.md">
      <i class="fa-solid fa-pencil"></i>
      
      
        
          Edit on GitLab
        
      
    </a>
  </div>
</div>

  <div class="sidebar-secondary-item">

  <div class="tocsection sourcelink">
    <a href="../_sources/manual/ksp.md.txt">
      <i class="fa-solid fa-file-lines"></i> Show Source
    </a>
  </div>
</div>

</div></div>
              
            
          </div>
          <footer class="bd-footer-content">
            
          </footer>
        
      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script src="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509"></script>

  <footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
  
    <div class="footer-items__start">
      
        <div class="footer-item">

  <p class="copyright">
    
      © Copyright 1991-2025, UChicago Argonne, LLC and the PETSc Development Team.
      <br/>
    
  </p>
</div>
      
        <div class="footer-item">

  <p class="sphinx-version">
    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
    <br/>
  </p>
</div>
      
    </div>
  
  
  
    <div class="footer-items__end">
      
        <div class="footer-item">
<p class="theme-version">
  Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.1.
</p></div>
      
        <div class="footer-item"><p class="last-updated">
  Last updated on 2025-04-30T13:10:40-0500 (v3.23.1).
  <br/>
</p></div>
      
    </div>
  
</div>

  </footer>
  </body>
</html>